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

#!/usr/bin/env python3
"""Build a receipt-backed route map of easy cross-domain kernel wins.

The map ranks domains where local algebraic/logogram fixtures are likely to be
cheap to encode and easy to verify. It is a planning receipt, not a benchmark or
domain-proof result.
"""

from __future__ import annotations

import hashlib
import json
from datetime import datetime, timezone
from pathlib import Path
from typing import Any


REPO = Path(__file__).resolve().parents[2]
OUT_DIR = REPO / "shared-data" / "data" / "cross_domain_easy_wins"
ROUTE_MAP = OUT_DIR / "cross_domain_easy_wins_route_map.json"
RECEIPT = OUT_DIR / "cross_domain_easy_wins_route_map_receipt.json"
SUMMARY = OUT_DIR / "cross_domain_easy_wins_route_map.md"

SOURCE_REFS = [
    REPO / "shared-data/data/mass_number_transform_registry/mass_number_transform_registry_receipt.json",
    REPO / "shared-data/data/cross_domain_kernel_adapters/cross_domain_kernel_adapter_registry_receipt.json",
    REPO / "shared-data/data/magnetic_derivative_kernels/magnetic_derivative_kernel_receipt.json",
    REPO / "shared-data/data/solids_physics_kernels/solids_physics_kernel_receipt.json",
    REPO / "shared-data/data/mmff_rigid_body_geometry/mmff_rigid_body_geometry_receipt.json",
]


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


def sha256_bytes(data: bytes) -> str:
    return hashlib.sha256(data).hexdigest()


def hash_obj(obj: Any) -> str:
    return sha256_bytes(stable_json(obj).encode("utf-8"))


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


def file_hash(path: Path) -> str | None:
    return sha256_bytes(path.read_bytes()) if path.exists() else None


def source_ref(path: Path) -> dict[str, Any]:
    return {"path": rel(path), "exists": path.exists(), "sha256": file_hash(path)}


def route(
    *,
    rank: int,
    route_id: str,
    domain: str,
    easy_kernels: list[str],
    fixture_targets: list[str],
    hold_hazards: list[str],
    next_probe: str,
    estimated_candidate_yield: str,
    decision: str = "ROUTE_READY",
) -> dict[str, Any]:
    item = {
        "rank": rank,
        "route_id": route_id,
        "domain": domain,
        "easy_kernels": easy_kernels,
        "fixture_targets": fixture_targets,
        "hold_hazards": hold_hazards,
        "next_probe": next_probe,
        "estimated_candidate_yield": estimated_candidate_yield,
        "decision": decision,
    }
    item["route_hash"] = hash_obj({k: v for k, v in item.items() if k != "route_hash"})
    return item


def build_route_map() -> dict[str, Any]:
    routes = [
        route(
            rank=1,
            route_id="circuits_impedance",
            domain="electrical circuits and transmission lines",
            easy_kernels=["MN_REFLECT", "MN_TRANSMIT_POWER", "MN_PAIR_PRODUCT", "MN_REDUCED"],
            fixture_targets=[
                "voltage divider",
                "Thevenin/Norton pair reduction",
                "series/parallel resistor identities",
                "transmission-line reflection coefficient",
            ],
            hold_hazards=["frequency-dependent parasitics", "nonlinear devices", "layout/skin-effect models"],
            next_probe="electrical_circuit_kernel_probe.py",
            estimated_candidate_yield="high",
        ),
        route(
            rank=2,
            route_id="thermal_diffusion",
            domain="thermal conduction and diffusion",
            easy_kernels=["MN_REFLECT", "MN_REDUCED", "MN_BLEND", "DERIV_LINEAR"],
            fixture_targets=[
                "thermal resistance series/parallel",
                "effusivity boundary contrast",
                "two-material steady flux",
                "lumped RC thermal time constant",
            ],
            hold_hazards=["transient PDE solves", "phase change", "temperature-dependent material laws"],
            next_probe="thermal_diffusion_kernel_probe.py",
            estimated_candidate_yield="high",
        ),
        route(
            rank=3,
            route_id="acoustics_waves",
            domain="acoustics and scalar waves",
            easy_kernels=["MN_REFLECT", "MN_TRANSMIT_POWER", "ANALYTIC_SQRT_RATIO"],
            fixture_targets=[
                "normal-incidence impedance reflection",
                "power transmission from reflection coefficient",
                "string/wave speed scalar route",
            ],
            hold_hazards=["oblique incidence", "loss/attenuation", "mode conversion", "boundary geometry"],
            next_probe="acoustic_wave_kernel_probe.py",
            estimated_candidate_yield="high",
        ),
        route(
            rank=4,
            route_id="probability_routing",
            domain="probability, routing, and expert selection",
            easy_kernels=["MN_BINARY_P", "MN_BLEND", "MN_BINARY_ENTROPY"],
            fixture_targets=[
                "two-route normalized probability",
                "confidence-weighted blend",
                "binary odds recovery",
                "entropy route with declared numeric policy",
            ],
            hold_hazards=["uncalibrated priors", "correlated experts", "floating-point entropy policy"],
            next_probe="probability_routing_kernel_probe.py",
            estimated_candidate_yield="very_high",
        ),
        route(
            rank=5,
            route_id="orbital_two_body",
            domain="two-body mechanics and orbital reductions",
            easy_kernels=["MN_SPLIT", "MN_REDUCED", "MN_ELASTIC_1D"],
            fixture_targets=[
                "mass split from total and MN",
                "reduced mass",
                "center-of-mass blend",
                "1D elastic collision",
            ],
            hold_hazards=["N-body dynamics", "relativistic corrections", "numerical integration"],
            next_probe="two_body_mechanics_kernel_probe.py",
            estimated_candidate_yield="high",
        ),
        route(
            rank=6,
            route_id="mmff_rigid_body_geometry",
            domain="MMFF-style molecular geometry as rigid/semi-rigid bodies",
            easy_kernels=["RIGID_BODY_POSE", "HINGED_RIGID_BODY", "MN_BOND_DEVIATION", "TORSION_OPCODE"],
            fixture_targets=[
                "linear triad coordinate replay",
                "bent triad coordinate replay",
                "aromatic ring template pose",
                "methyl rotor hinge state",
            ],
            hold_hazards=[
                "MMFF atom typing",
                "aromaticity perception",
                "parameter lookup tables",
                "partial charges and nonbonded cutoffs",
                "energy minimization and conformer ranking",
            ],
            next_probe="mmff_rigid_body_geometry_probe.py",
            estimated_candidate_yield="high",
        ),
        route(
            rank=7,
            route_id="chemistry_equilibrium",
            domain="chemistry equilibrium and reaction routing",
            easy_kernels=["MN_RATIO_INV", "MN_BINARY_P", "MN_BLEND"],
            fixture_targets=[
                "two-species normalized fraction",
                "odds/ratio recovery",
                "mixture weighted property",
                "two-lane equilibrium contrast fixture",
            ],
            hold_hazards=["activity coefficients", "temperature dependence", "kinetics and catalysis"],
            next_probe="chemistry_equilibrium_kernel_probe.py",
            estimated_candidate_yield="medium_high",
        ),
        route(
            rank=8,
            route_id="optics_fresnel",
            domain="optics at normal incidence",
            easy_kernels=["MN_REFLECT", "MN_TRANSMIT_POWER"],
            fixture_targets=[
                "normal-incidence amplitude reflection",
                "power transmission from contrast",
                "index/impedance contrast",
            ],
            hold_hazards=["polarization", "oblique incidence", "complex refractive index", "thin-film interference"],
            next_probe="optics_fresnel_kernel_probe.py",
            estimated_candidate_yield="medium_high",
        ),
        route(
            rank=9,
            route_id="statistics_effect_size",
            domain="statistics and signal scoring",
            easy_kernels=["MN", "MN_BLEND", "MN_BINARY_ENTROPY"],
            fixture_targets=[
                "two-bin contrast",
                "normalized difference score",
                "weighted mean update",
                "binary uncertainty score",
            ],
            hold_hazards=["sampling assumptions", "p-value misuse", "distributional claims"],
            next_probe="statistics_signal_kernel_probe.py",
            estimated_candidate_yield="medium",
        ),
        route(
            rank=10,
            route_id="bio_expression_contrast",
            domain="biology expression/accessibility contrast",
            easy_kernels=["MN", "MN_BINARY_P", "MN_BLEND"],
            fixture_targets=[
                "two-condition expression contrast",
                "accessibility contrast",
                "two-source regulatory blend",
            ],
            hold_hazards=["biological causality", "batch effects", "measurement normalization", "thermodynamic overclaim"],
            next_probe="bio_expression_contrast_kernel_probe.py",
            estimated_candidate_yield="medium",
        ),
        route(
            rank=11,
            route_id="geometry_contact",
            domain="contact geometry and motion planning",
            easy_kernels=["MN", "MN_BLEND"],
            fixture_targets=[
                "two-clearance contact contrast",
                "signed-distance transition fixture",
                "contact-regime switch scoring",
            ],
            hold_hazards=["continuous collision proof", "area optimality", "path completeness"],
            next_probe="contact_geometry_kernel_probe.py",
            estimated_candidate_yield="medium",
            decision="ROUTE_HOLD_FIRST",
        ),
    ]
    return {
        "schema": "cross_domain_easy_wins_route_map_v1",
        "claim_boundary": (
            "Planning receipt only. It ranks likely low-cost cross-domain kernel "
            "probes; it does not assert compression gain, domain truth, or benchmark "
            "performance. Each route still requires its own fixture receipt."
        ),
        "canonical_statement": (
            "Easy wins are domains where exact local algebra kernels can be checked "
            "before domain-specific PDEs, material laws, geometry, or measurement "
            "claims are touched."
        ),
        "selection_rule": "prefer exact local algebra first; HOLD nonlinear, field, geometry, and measurement claims",
        "routes": routes,
        "route_count": len(routes),
        "status_counts": {
            status: sum(1 for item in routes if item["decision"] == status)
            for status in sorted({item["decision"] for item in routes})
        },
    }


def build_receipt(route_map: dict[str, Any]) -> dict[str, Any]:
    receipt = {
        "schema": "cross_domain_easy_wins_route_map_receipt_v1",
        "generated_at_utc": datetime.now(timezone.utc).isoformat(),
        "timestamp_role": "metadata_only",
        "generated_at_utc_included_in_receipt_hash": False,
        "route_map_path": rel(ROUTE_MAP),
        "route_map_hash": hash_obj(route_map),
        "source_refs": [source_ref(path) for path in SOURCE_REFS],
        "route_count": route_map["route_count"],
        "status_counts": route_map["status_counts"],
        "decision": "ADMIT_ROUTE_MAP_HOLD_FIRST",
        "claim_boundary": route_map["claim_boundary"],
    }
    receipt["receipt_hash"] = sha256_bytes(
        stable_json({k: v for k, v in receipt.items() if k not in {"receipt_hash", "generated_at_utc"}}).encode("utf-8")
    )
    return receipt


def write_summary(route_map: dict[str, Any], receipt: dict[str, Any]) -> None:
    lines = [
        "# Cross-Domain Easy Wins Route Map",
        "",
        f"Decision: `{receipt['decision']}`  ",
        f"Receipt hash: `{receipt['receipt_hash']}`",
        "",
        route_map["claim_boundary"],
        "",
        "## Canonical Statement",
        "",
        route_map["canonical_statement"],
        "",
        "## Ranked Routes",
        "",
        "| Rank | Route | Domain | Yield | Decision | Next probe |",
        "|---:|---|---|---|---|---|",
    ]
    for item in route_map["routes"]:
        lines.append(
            f"| {item['rank']} | `{item['route_id']}` | {item['domain']} | "
            f"{item['estimated_candidate_yield']} | `{item['decision']}` | `{item['next_probe']}` |"
        )
    lines.extend(
        [
            "",
            "## Rule",
            "",
            route_map["selection_rule"],
        ]
    )
    SUMMARY.write_text("\n".join(lines) + "\n", encoding="utf-8")


def main() -> int:
    OUT_DIR.mkdir(parents=True, exist_ok=True)
    route_map = build_route_map()
    receipt = build_receipt(route_map)
    ROUTE_MAP.write_text(json.dumps(route_map, indent=2, sort_keys=True) + "\n", encoding="utf-8")
    RECEIPT.write_text(json.dumps(receipt, indent=2, sort_keys=True) + "\n", encoding="utf-8")
    write_summary(route_map, receipt)
    print(
        json.dumps(
            {
                "route_map": rel(ROUTE_MAP),
                "receipt": rel(RECEIPT),
                "summary": rel(SUMMARY),
                "receipt_hash": receipt["receipt_hash"],
                "decision": receipt["decision"],
                "status_counts": route_map["status_counts"],
            },
            indent=2,
            sort_keys=True,
        )
    )
    return 0


if __name__ == "__main__":
    raise SystemExit(main())