rune/scripts/check_construction_projection_parity.py

#!/usr/bin/env python3
"""check_construction_projection_parity.py — live parity for the
construction_projection dichotomy gap close (#2479): the Rust kernel
(.so via cproj_loader) vs the live Python oracle floor vs the frozen
truth — 100% on the full surface.

Structure (single oracle subprocess under the freeze rig, checker process
with the kernel live):
  * FROZEN rows (52) — 3-way: kernel | oracle floor | frozen expected;
  * FACADE fuzz rows (240 project + 40 minidoc) — the facade called in
    the checker process (kernel live) AND in the subprocess (floor) with
    the same fake-scaffold/fake-bridge inputs — must agree with each
    other and with the loader-direct kernel calls;
  * VALIDATE rows — the fuzz projections validated under both kernels;
  * CRASH rows — shapes where the oracle raises: the kernel errs, the
    facade falls back to the floor and reproduces the identical
    exception on BOTH sides.

Usage: python3 scripts/check_construction_projection_parity.py
Exit 0 iff every comparison matches.
"""
from __future__ import annotations

import json
import os
import random
import shutil
import subprocess
import sys
import tempfile
from pathlib import Path

ROOT = Path(__file__).resolve().parents[1]
sys.path.insert(0, str(ROOT / "src"))

TRUTH = ROOT / "src" / "rust" / "construction_projection" / "src" / "frozen_truth.json"

ORACLE_HELPER = r"""
import copy, json, os, sys, tempfile, shutil

for p in (%(scripts)r, %(src)r):
    if p not in sys.path:
        sys.path.insert(0, p)

import rune.construction_projection as cp  # floor pinned by the rig
from rune import event_wait as ew
from freeze_truth import _run_case

payload = json.load(sys.stdin)
REAL_WAIT = ew.operation_wait


class _FakeScaffold:
    def __init__(self, spec):
        self._doc = copy.deepcopy(spec.get("load") or {})
        if "project_id" in spec:
            self.project_id = spec["project_id"]

    def load(self):
        return copy.deepcopy(self._doc)


def _bridge(bridge):
    mode = (bridge or {}).get("__mode__", "none")

    def _wait(operation_id):
        if mode == "oserr":
            raise OSError(2, "bridge data root unreadable (parity-pinned)")
        if mode == "runtimeerr":
            raise RuntimeError("waitstore not resolvable (parity-pinned)")
        if mode == "found":
            return dict((bridge or {}).get("record") or {})
        return None

    return _wait


out = {
    "rows": [
        _run_case(cp, {"fn": r["fn"], "args": r["args"],
                       "kwargs": r.get("kwargs", {})})
        for r in payload["ROWS"]
    ],
    "facade_project": [],
    "facade_entity": [],
    "facade_validate": [],
    "facade_minidoc": [],
    "crash": {},
}

for spec, cid, bridge, kwargs in payload["FACADE_PROJECT"]:
    ew.operation_wait = _bridge(bridge)
    try:
        p = cp.project(_FakeScaffold(spec), cid, **kwargs)
        out["facade_project"].append(p)
    finally:
        ew.operation_wait = REAL_WAIT

for spec, cid, _bridge, _kwargs in payload["FACADE_PROJECT"]:
    out["facade_entity"].append(cp._contract_entity(copy.deepcopy(spec["load"] or {}), cid))

# validate rows: over the facade projections (real 24-field shapes)
out["facade_validate"] = [cp.validate(p) for p in out["facade_project"]]

for spec, cid in payload["FACADE_MINIDOC"]:
    scratch = tempfile.mkdtemp(prefix="cpjfloor-")
    try:
        path = cp.write_mini_doc(_FakeScaffold(spec), cid, out_dir=scratch)
        out["facade_minidoc"].append({
            "file": os.path.basename(str(path)),
            "content": open(path, encoding="utf-8").read(),
            "projection": cp.project(_FakeScaffold(spec), cid),
        })
    finally:
        shutil.rmtree(scratch, ignore_errors=True)

for kind, args in payload["CRASH"]:
    try:
        if kind in ("entity_nondict", "entity_null_entities"):
            result = cp._contract_entity(args[0], args[1])
        elif kind == "validate_nondict":
            result = cp.validate(args[0])
        elif kind in ("blocker_int", "checkpoint_int"):
            result = cp.project(_FakeScaffold({"load": args[0]}), args[1])
        elif kind in ("surface_int", "evidence_int"):
            result = cp.write_mini_doc(_FakeScaffold({"load": args[0]}), args[1])
        else:
            raise AssertionError(kind)
        out["crash"][kind] = "NO_CRASH:" + json.dumps(result, sort_keys=True)
    except Exception as e:  # noqa: BLE001 — the crash IS the check
        out["crash"][kind] = f"{type(e).__name__}: {e}"

print(json.dumps(out))
"""

FAILS: list = [0]
CHECKS: list = [0]


def check(label, got, want) -> None:
    CHECKS[0] += 1
    gs = json.dumps(got, sort_keys=True, default=str)
    ws = json.dumps(want, sort_keys=True, default=str)
    if gs != ws:
        FAILS[0] += 1
        print(f"MISMATCH {label}\n  got:  {gs[:260]}\n  want: {ws[:260]}")


def fuzz_corpus(n: int, seed: int = 2026) -> list:
    """(spec, contract_id, bridge, kwargs) fuzz rows — adversarial shapes."""
    rng = random.Random(seed)
    ALPH = "abcxyzΛ中é."  # multibyte — the codepoint-truncation quirk
    rows = []

    def rnd_str(maxlen=40):
        return "".join(rng.choice(ALPH) for _ in range(rng.randint(0, maxlen)))

    for i in range(n):
        ents = []
        for k in range(rng.randint(0, 3)):
            e = {"id": f"contract:C-{i}-{k}"}
            if rng.random() < 0.8:
                e["phase"] = rng.choice(["draft", "approved", "verifying", "closed",
                                         "awaiting_approval"])
                ids: dict = {}
                if rng.random() < 0.7:
                    ids["construction_mode"] = rng.choice(["BUILD_NEW", "PATCH", ""])
                if rng.random() < 0.7:
                    ids["depth"] = rng.choice(["standard", "deep", 0])
                if rng.random() < 0.5:
                    ids["next_action"] = rng.choice([rnd_str(15), None])
                if rng.random() < 0.4:
                    ids["blocker"] = rng.choice([
                        {"class": rng.choice(["SCOPE", "BLOCKED"]),
                         "evidence": rnd_str(150)},
                        rnd_str(20),
                        "",
                    ])
                if rng.random() < 0.5:
                    ids["objective"] = rnd_str(50)
                if rng.random() < 0.3:
                    ids["affected_surface"] = "src/" + rnd_str(8) + ".py"
                if rng.random() < 0.4:
                    ids["task_ref"] = "T" + str(rng.randint(0, 200))
                e["identities"] = ids
                ext: dict = {}
                if rng.random() < 0.6:
                    ext["readiness_canary"] = rng.choice(["ready", None, ""])
                if rng.random() < 0.6:
                    ext["liveness_canary"] = "live"
                if rng.random() < 0.6:
                    ext["exit_canary"] = "exit"
                if rng.random() < 0.5:
                    ext["contract_quality"] = {
                        rng.choice(["correctly_predicted", "scope_check", "zz_last"]):
                            rng.choice([0, 3, True, "green"]),
                    }
                if rng.random() < 0.5:
                    ext["decision_trace"] = {"approval": rng.choice([
                        {"required": True},
                        {"required": False, "state": "REQUIRED"},
                        {"required": 0},
                        {},
                    ])}
                if rng.random() < 0.4:
                    ext["affected_paths"] = [
                        "src/" + rnd_str(6) + ".py"
                        for _ in range(rng.randint(0, 3))
                    ]
                if rng.random() < 0.3:
                    ext["need"] = {"objective": rnd_str(30)}
                e["ext"] = ext
                if rng.random() < 0.6:
                    e["checkpoints"] = [
                        {"evidence": rng.choice(["", rnd_str(140)])}
                        for _ in range(rng.randint(0, 3))
                    ]
            ents.append(e)
        spec = {"load": {"entities": ents}}
        if rng.random() < 0.8:
            spec["project_id"] = f"proj-{i}"
        cid = rng.choice([f"C-{i}-0", f"C-{i}-1", ""]) if ents else "C-404"
        bridge = rng.choice([
            None, {},
            {"__mode__": "found", "record": {"status": "W", "wait_id": "w7"}},
            {"__mode__": "oserr"},
            {"__mode__": "runtimeerr"},
        ])
        kwargs: dict = {}
        for k in ("originating_goal_id", "stage", "builder_state",
                  "verification_state", "checkpoint", "failure_class",
                  "completion_state"):
            if rng.random() < 0.6:
                kwargs[k] = rnd_str(10)
        if rng.random() < 0.7:
            kwargs["operation_id"] = rng.choice(["op-a", ""])
        if rng.random() < 0.5:
            kwargs["correlation_id"] = "corr"
        rows.append((spec, cid, bridge, kwargs))
    return rows


def rust_entity(doc, cid):
    from rune import cproj_loader

    return cproj_loader.contract_entity(doc, cid)


def rust_validate(p):
    from rune import cproj_loader

    return cproj_loader.validate(p)


def rust_project(entity, cid, waiting_state, live_correlation, kwargs):
    from rune import cproj_loader

    return cproj_loader.project(
        entity if entity is not None else {},
        contract_id=cid,
        project_id=kwargs.get("project_id", ""),
        originating_goal_id=kwargs.get("originating_goal_id", ""),
        operation_id=kwargs.get("operation_id", ""),
        waiting_state=waiting_state,
        live_correlation=live_correlation,
        stage=kwargs.get("stage", ""),
        builder_state=kwargs.get("builder_state", ""),
        verification_state=kwargs.get("verification_state", ""),
        checkpoint=kwargs.get("checkpoint", ""),
        failure_class=kwargs.get("failure_class", ""),
        completion_state=kwargs.get("completion_state", ""),
    )


def rust_write_mini_doc(entity, cid, projection):
    from rune import cproj_loader

    return cproj_loader.write_mini_doc(
        entity if entity is not None else {}, cid, projection)


class _KernelScaffold:
    """Fake scaffold for the CHECK process (kernel live)."""

    def __init__(self, spec):
        import copy

        self._doc = copy.deepcopy(spec.get("load") or {})
        if "project_id" in spec:
            self.project_id = spec["project_id"]

    def load(self):
        import copy

        return copy.deepcopy(self._doc)


def _check_bridge(bridge):
    """Same fake-bridge rule as the rig (duplicated HERE — the parity
    contract pins both sides against the same fake, never the real store)."""
    mode = (bridge or {}).get("__mode__", "none")

    def _wait(operation_id):
        if mode == "oserr":
            raise OSError(2, "bridge data root unreadable (parity-pinned)")
        if mode == "runtimeerr":
            raise RuntimeError("waitstore not resolvable (parity-pinned)")
        if mode == "found":
            return dict((bridge or {}).get("record") or {})
        return None

    return _wait


def run_oracle(payload: dict) -> dict:
    """The floor side: one subprocess under the freeze rig (oracle = Python)."""
    code = ORACLE_HELPER % {"scripts": str(ROOT / "scripts"), "src": str(ROOT / "src")}
    env = {
        **os.environ,
        "PYTHONHASHSEED": "0",
        "PYTHONPATH": (
            f"{ROOT / 'scripts' / 'cproj_freeze_seams'}:{ROOT / 'scripts'}:{ROOT / 'src'}"
        ),
        "RUNE_CONSTRUCTION_PROJECTION_CORE": "python",
    }
    r = subprocess.run([sys.executable, "-c", code], input=json.dumps(payload),
                       capture_output=True, text=True, env=env, timeout=900)
    if r.returncode != 0:
        print("ORACLE SUBPROCESS FAILED:", r.stderr[-1500:])
        sys.exit(1)
    return json.loads(r.stdout)


def crash_shapes() -> list:
    """(kind, factory) — the factory builds the floor-call inputs."""
    LONG_INT = 5
    return [
        ("entity_nondict", lambda: (42, "X")),
        ("entity_null_entities", lambda: ({"entities": None}, "X")),
        ("validate_nondict", lambda: (42,)),
        ("blocker_int", lambda: (
            {"entities": [{"id": "contract:X",
                           "identities": {"blocker": {"evidence": LONG_INT}}}]}, "X")),
        ("checkpoint_int", lambda: (
            {"entities": [{"id": "contract:X",
                           "checkpoints": [{"evidence": LONG_INT}]}]}, "X")),
        ("surface_int", lambda: (
            {"entities": [{"id": "contract:X",
                           "ext": {"affected_paths": LONG_INT}}]}, "X")),
        ("evidence_int", lambda: (
            {"entities": [{"id": "contract:X", "identities": {},
                           "checkpoints": [{"evidence": "ev"}]}]}, "X")),
    ]


def main() -> int:
    from rune import cproj_loader

    if not cproj_loader.available():
        print("cproj_loader kernel not built — build "
              "src/rust/construction_projection first")
        return 1

    envelope = json.loads(TRUTH.read_text())
    truth_rows = envelope["cases"]

    fuzz = fuzz_corpus(240)
    facade_minidoc_rows = [(fz[0], fz[1]) for fz in fuzz[:40]]

    payload = {
        "ROWS": truth_rows,
        "FACADE_PROJECT": fuzz,
        "FACADE_MINIDOC": facade_minidoc_rows,
        "CRASH": [(kind, factory()) for kind, factory in crash_shapes()],
    }
    oracle = run_oracle(payload)

    total = len(truth_rows)

    print(f"== frozen rows ({total}) 3-way: kernel | oracle floor | frozen ==")
    for i, row in enumerate(truth_rows):
        fn, expected = row["fn"], row["expected"]
        check(f"frozen[{i}] frozen-vs-oracle {fn}", expected,
              oracle["rows"][i]["expected"])
        if fn == "cpj_freeze_contract_entity":
            doc, cid = row["args"][0], row["args"][1]
            check(f"frozen[{i}] contract_entity kernel-vs-frozen",
                  rust_entity(doc, cid), expected)
            check(f"frozen[{i}] contract_entity facade-kernel",
                  cp_contract_entity(doc, cid), expected)
        elif fn == "cpj_freeze_validate":
            p = row["args"][0]
            check(f"frozen[{i}] validate kernel-vs-frozen",
                  rust_validate(p), expected)
            check(f"frozen[{i}] validate facade-kernel", cp_validate(p), expected)
        elif fn == "cpj_freeze_project":
            spec, cid = row["args"][0], row["args"][1]
            bridge, kwargs = row["args"][2], row["kwargs"]
            wrapped = expected
            args_full = {**kwargs, "project_id": spec.get("project_id", "")}
            entity = rust_entity(spec["load"], cid)
            got_kernel = rust_project(entity, cid, wrapped["waiting_state"],
                                      wrapped["live_correlation"], args_full)
            check(f"frozen[{i}] project kernel-vs-frozen", got_kernel,
                  wrapped["projection"])
            got_facade = facade_project(spec, cid, bridge, kwargs)
            check(f"frozen[{i}] project facade-kernel-vs-frozen", got_facade,
                  wrapped["projection"])
        elif fn == "cpj_freeze_write_mini_doc":
            spec, cid = row["args"]
            entity = rust_entity(spec["load"], cid)
            check(f"frozen[{i}] mini-doc kernel-vs-frozen bytes",
                  rust_write_mini_doc(entity, cid, row["expected"]["projection"]),
                  row["expected"]["content"])
            check(f"frozen[{i}] mini-doc kernel-vs-frozen name",
                  f"{cid}.md", row["expected"]["file"])

    print(f"== facade both-pins fuzz ({len(fuzz)} project / "
          f"{len(facade_minidoc_rows)} mini-doc / {total} validate rows) ==")
    for i, (spec, cid, bridge, kwargs) in enumerate(fuzz):
        want = oracle["facade_project"][i]
        got_facade = facade_project(spec, cid, bridge, kwargs)
        check(f"facade fuzz[{i}]", got_facade, want)
        args_full = {**kwargs, "project_id": spec.get("project_id", "")}
        entity = rust_entity(spec["load"], cid)
        got_kernel = rust_project(entity, cid, want["waiting_state"],
                                  want["correlation_id"], args_full)
        check(f"kernel-direct fuzz[{i}]", got_kernel, want)
    for i, p in enumerate(oracle["facade_project"][:40]):
        check(f"validate fuzz[{i}]", cp_validate(p), oracle["facade_validate"][i])
        check(f"validate kernel-direct fuzz[{i}]", rust_validate(p),
              oracle["facade_validate"][i])
    for i, (spec, cid) in enumerate(facade_minidoc_rows):
        want = oracle["facade_minidoc"][i]
        scratch = tempfile.mkdtemp(prefix="cpjkern-")
        try:
            path = minidoc_kernel_facade(spec, cid, scratch)
            check(f"mini-doc facade-kernel[{i}] bytes", path.read_text(encoding="utf-8"),
                  want["content"])
            check(f"mini-doc facade-kernel[{i}] name", path.name, want["file"])
            entity = rust_entity(spec["load"], cid)
            check(f"mini-doc kernel-direct[{i}] bytes",
                  rust_write_mini_doc(entity, cid, want["projection"]),
                  want["content"])
        finally:
            shutil.rmtree(scratch, ignore_errors=True)

    print("== crash parity (kernel errs -> facade floor raises the oracle's exact exception) ==")
    for kind, factory in crash_shapes():
        args = factory()
        want = oracle["crash"][kind]
        try:
            got = facade_crash_call(kind, args)
            check(f"crash[{kind}]", f"NO_CRASH:{json.dumps(got, sort_keys=True)}", want)
        except Exception as e:  # noqa: BLE001 — the crash IS the check
            check(f"crash[{kind}]", f"{type(e).__name__}: {e}", want)

    if FAILS[0]:
        print(f"\nPARITY FAILED: {FAILS[0]} mismatches of {CHECKS[0]}")
        return 1
    print(f"\nPARITY OK: 100% — {CHECKS[0]} comparisons, rust == oracle == frozen "
          f"({total} frozen rows + {len(fuzz)} fuzz project + "
          f"{len(facade_minidoc_rows)} mini-doc + {len(crash_shapes())} crash)")
    return 0


# ── facade calls in the CHECK process (kernel live — no pin set) ────────────
def cp_contract_entity(doc, cid):
    from rune import construction_projection as cp

    return cp._contract_entity(doc, cid)


def cp_validate(p):
    from rune import construction_projection as cp

    out = cp.validate(p)
    return out


def _patch_bridge(bridge, fn, *args, **kwargs):
    from rune import event_wait as ew

    real = ew.operation_wait
    ew.operation_wait = _check_bridge(bridge)
    try:
        return fn(*args, **kwargs)
    finally:
        ew.operation_wait = real


def facade_project(spec, cid, bridge, kwargs):
    from rune import construction_projection as cp

    p = _patch_bridge(bridge, cp.project, _KernelScaffold(spec), cid,
                      **dict(kwargs))
    return p


def minidoc_kernel_facade(spec, cid, out_dir):
    from rune import construction_projection as cp

    return cp.write_mini_doc(_KernelScaffold(spec), cid, out_dir=out_dir)


def facade_crash_call(kind, args):
    """The facade path with the kernel live: kernel errs → floor raises."""
    from rune import construction_projection as cp

    if kind in ("entity_nondict", "entity_null_entities"):
        return cp._contract_entity(args[0], args[1])
    if kind == "validate_nondict":
        return cp.validate(args[0])
    if kind in ("blocker_int", "checkpoint_int"):
        return cp.project(_KernelScaffold({"load": args[0]}), args[1])
    if kind in ("surface_int", "evidence_int"):
        return cp.write_mini_doc(_KernelScaffold({"load": args[0]}), args[1])
    raise AssertionError(kind)


if __name__ == "__main__":
    sys.exit(main())