Research-Stack/4-Infrastructure/shim/illegal_state_unrepresentable_route_prior.py

#!/usr/bin/env python3
"""Distill "make illegal states unrepresentable" into DD route-state guards.

The source article's useful extraction is finite-state API discipline: expose
only legal transitions, and use type/state markers to prevent invalid builder
paths. For the bounded route compiler, invalid route combinations should be
unrepresentable when possible, and otherwise fail closed at the boundary.
"""

from __future__ import annotations

import hashlib
import json
from pathlib import Path
from typing import Any


REPO = Path(__file__).resolve().parents[2]
SHIM = REPO / "4-Infrastructure" / "shim"
OUT = SHIM / "illegal_state_unrepresentable_route_prior_receipt.json"
CURRICULUM_OUT = SHIM / "illegal_state_unrepresentable_route_prior_curriculum.jsonl"

GENERATED_AT = "2026-05-08T00:00:00+00:00"
SOURCE_URL = "https://blog.frankel.ch/illegal-state-unrepresentable/"


def stable_json(obj: Any) -> str:
    return json.dumps(obj, sort_keys=True, separators=(",", ":"), ensure_ascii=True)


def sha256_text(text: str) -> str:
    return hashlib.sha256(text.encode("utf-8")).hexdigest()


def rel(path: Path) -> str:
    return str(path.relative_to(REPO))


SOURCE_EVIDENCE = {
    "title": "Making illegal state unrepresentable",
    "author": "Nicolas Frankel",
    "published_date": "2026-04-19",
    "source_url": SOURCE_URL,
    "observed_core_claims": [
        "builder_pattern_can_be_read_as_finite_state_machine",
        "illegal_transitions_should_not_be_exposed_to_api_users",
        "static_typing_can_reject_nonexistent_transitions_at_compile_time",
        "dynamic_typing_requires_runtime_validation_or_external_type_checker",
        "naive_state_classes_can_create_combinatorial_growth",
        "phantom_or_generic_state_markers_reduce_growth_for_common_transitions",
        "opaque_constructors_help_hide_invalid_direct_construction",
    ],
}


STATE_DISCIPLINES = [
    {
        "id": "runtime_validation_only",
        "local_meaning": "route object can be built in invalid shape and rejected later",
        "use_when": "dynamic/plugin boundaries where static types are unavailable",
        "risk": "invalid states consume evaluator time and can leak into receipts",
        "verdict": "boundary_fallback_only",
    },
    {
        "id": "state_specific_builder",
        "local_meaning": "each route state exposes only legal next DD edges",
        "use_when": "small finite route machines with few compatibility dimensions",
        "risk": "class/edge explosion as route constraints multiply",
        "verdict": "good_for_small_closed_fsm",
    },
    {
        "id": "phantom_state_marker",
        "local_meaning": "carry compile-time or schema-time route state without serializing payload",
        "use_when": "shared transitions should preserve route family while specific edges are constrained",
        "risk": "marker must not become an uncounted witness channel",
        "verdict": "preferred_for_route_api_shape",
    },
    {
        "id": "opaque_route_constructor",
        "local_meaning": "force route construction through legal transition functions",
        "use_when": "receipts or config matrices should not be hand-assembled into invalid states",
        "risk": "bypass paths must be audited at JSON/plugin boundaries",
        "verdict": "preferred_for_receipt_objects",
    },
]


EQUATIONS = [
    {
        "id": "ISR0_route_fsm",
        "equation": "RouteFSM = (States, LegalEdges, start, terminals)",
        "meaning": "Transform tuning is an explicit finite-state route builder.",
    },
    {
        "id": "ISR1_transition_totality",
        "equation": "edge(s, a) is constructible iff a in LegalEdges(s)",
        "meaning": "An illegal DD edge should not be callable from the current route state.",
    },
    {
        "id": "ISR2_phantom_state",
        "equation": "RouteBuilder[S] carries S at type/schema time and erases S at payload time",
        "meaning": "State markers constrain transitions without becoming hidden compressed data.",
    },
    {
        "id": "ISR3_common_transition",
        "equation": "common_edge: RouteBuilder[S] -> RouteBuilder[S]",
        "meaning": "Shared legal edges preserve state and avoid duplicated boilerplate.",
    },
    {
        "id": "ISR4_specific_transition",
        "equation": "specific_edge: RouteBuilder[S_a] -> RouteBuilder[S_b]",
        "meaning": "Compatibility-changing route choices move to a new explicit state class.",
    },
    {
        "id": "ISR5_boundary_validation",
        "equation": "external_json_route valid iff reconstruct(RouteFSM, json).state != invalid",
        "meaning": "Typed interiors still need fail-closed validation at untyped plugin/file boundaries.",
    },
]


def build_receipt() -> dict[str, Any]:
    receipt: dict[str, Any] = {
        "schema": "illegal_state_unrepresentable_route_prior_v1",
        "generated_at": GENERATED_AT,
        "source_evidence": SOURCE_EVIDENCE,
        "primary_decision": {
            "name": "make_invalid_route_states_unrepresentable",
            "statement": (
                "Represent route construction as a finite-state builder where "
                "only legal DD edges are exposed from each state. Use phantom "
                "or schema-time state markers for common transitions, and keep "
                "runtime validation at external JSON/plugin boundaries."
            ),
        },
        "state_disciplines": STATE_DISCIPLINES,
        "equations": EQUATIONS,
        "candidate_dd_state_extension": [
            "route_state_type_id",
            "legal_edge_set_id",
            "phantom_marker_id",
            "opaque_constructor_status",
            "transition_witness_id",
            "compile_time_rejected_edge_count",
            "runtime_rejected_edge_count",
            "json_boundary_validation_status",
            "state_marker_payload_bytes",
            "invalid_state_nan0_flag",
            "byte_rehydration_hash",
        ],
        "candidate_dd_edges": [
            "open_typed_route_builder",
            "expose_only_legal_edges",
            "apply_common_transition_preserving_state",
            "apply_specific_transition_changing_state",
            "erase_phantom_marker_from_payload",
            "validate_external_route_json",
            "reject_unrepresentable_transition",
            "fail_closed_on_invalid_route_state",
        ],
        "lower_bound": [
            "state_marker_header_bytes",
            "transition_witness_floor",
            "json_boundary_validation_floor",
            "exact_residual_lane_floor",
        ],
        "promotion_rule": [
            "route_builder_exposes_only_legal_transitions",
            "phantom_or_schema_markers_are_not_payload_channels",
            "opaque_constructors_prevent_direct_invalid_receipts",
            "external_json_or_plugin_routes_validate_against_fsm",
            "invalid_states_fail_closed_before_evaluation",
            "decoded_hash_matches_source",
            "measured_total_bytes_beat_incumbent_under_ratio_schema",
        ],
        "failure_rule": [
            "illegal_transition_constructible -> invalid_api_surface",
            "phantom_marker_serialized_as_hidden_payload -> invalid_receipt",
            "state_class_growth_becomes_combinatorial -> refactor_to_marker_matrix",
            "external_route_json_bypasses_validation -> fail_closed",
            "runtime_rejection_after_expensive_eval -> prune_or_move_gate_earlier",
        ],
        "claim_boundary": (
            "This prior constrains route-state representation. It is not a "
            "compression result and does not replace exact decode/hash/byte-count "
            "promotion receipts."
        ),
    }
    preimage = {key: value for key, value in receipt.items() if key != "receipt_hash"}
    receipt["receipt_hash"] = sha256_text(stable_json(preimage))
    return receipt


def curriculum_lines(receipt: dict[str, Any]) -> list[dict[str, Any]]:
    lines: list[dict[str, Any]] = []
    for item in receipt["state_disciplines"]:
        lines.append({"type": "state_discipline", **item})
    for item in receipt["equations"]:
        lines.append({"type": "equation", **item})
    for rule in receipt["promotion_rule"]:
        lines.append({"type": "promotion_rule", "rule": rule})
    for rule in receipt["failure_rule"]:
        lines.append({"type": "failure_rule", "rule": rule})
    return lines


def main() -> None:
    receipt = build_receipt()
    OUT.write_text(json.dumps(receipt, indent=2, sort_keys=True) + "\n", encoding="utf-8")
    lines = curriculum_lines(receipt)
    CURRICULUM_OUT.write_text(
        "".join(json.dumps(line, sort_keys=True) + "\n" for line in lines),
        encoding="utf-8",
    )
    print(json.dumps({
        "receipt": rel(OUT),
        "curriculum": rel(CURRICULUM_OUT),
        "receipt_hash": receipt["receipt_hash"],
        "curriculum_records": len(lines),
        "decision": receipt["primary_decision"]["name"],
    }, indent=2, sort_keys=True))


if __name__ == "__main__":
    main()