chore(sync): mirror backend .py + Dockerfile to Space (hf-sync-backend)

Automated backend sync from szl-holdings/a11oy main via hf-sync-backend.
Updated (differed from the Space): Dockerfile, a11oy_ayllu.py, a11oy_brain_graph.py, a11oy_code_engine.py, a11oy_code_orchestrator.py, a11oy_frontier_page.py, a11oy_frontier_patch.py, a11oy_hf_assets.py, a11oy_nemo_core.py, a11oy_operator_organ.py, a11oy_org_rag.py, ayllu/__init__.py, ayllu/backend.py, ayllu/loop.py, ayllu/lounge.py, ayllu/model_binding.py, ayllu/selftest.py, model_release/receipt-agent/receipt_runtime.py, numerics/isolation_probe.py, research/__init__.py, serve.py, szl3d_holographic.py, szl_alloy_models.py, szl_anatomy_3d.py, szl_anatomy_brainloop.py, szl_boot_preflight.py, szl_brain_api.py, szl_brain_reranker.py, szl_brain_training_admission.py, szl_braincorpus.py, szl_brainhealth.py, szl_claim_rupture_gate.py, szl_formal_conjecture_lab.py, szl_governed_infer.py, szl_gpu_quant.py, szl_llm_registry.py, szl_m1_corpus_manifest.py, szl_m1_model_gate.py, szl_nemo_agents.py, szl_numerics_adapter.py, szl_numerics_dataset.py, szl_numerics_experiment.py, szl_provider_http.py, szl_quant_qbio_holo.py, szl_quantum_bio.py, szl_quantum_utility.py, szl_release_identity.py, szl_waqay.py, szl_yupaq_compute.py, szl_yupay.py
Deleted (gone from the repo + Dockerfile COPY set): (none)

Keeps the Space-built backend (serve.py + the Dockerfile-COPY'd .py
modules) identical to GitHub main so the Space never rebuilds from a
stale backend, new endpoints don't 404 there, and orphaned modules
removed from the repo don't linger in the Space tree.

Dockerfile

@@ -163,12 +163,59 @@ COPY knowledge.json ./static/knowledge.json
 # registers live. (dockerfile-copy-guard verifies these sources exist on main.)
 COPY a11oy_ayllu.py ./
 COPY ayllu/ ./ayllu/
+# Canonical model-family/control-plane evidence ships with the runtime image so
+# deployed status surfaces can be audited against the same release contracts.
+COPY model_release/szl-forge-family.json model_release/szl-compute-plane.json model_release/szl-ayllu-binding.json model_release/szl-khipu-second-brain.json ./model_release/
+COPY model_release/receipt-agent/ ./model_release/receipt-agent/
+# Brain-derived rows remain quarantined until this deterministic, fail-closed
+# admission engine validates immutable provenance, rights, contamination, and
+# split obligations. Shipping the CLI does not start training or admit rows.
+COPY szl_brain_training_admission.py ./
 # Waqay Security Loop wave 15: pure read-only proposal contract.  The module
 # exposes zero external effectors; serve.py registers only its manifest GET.
 COPY szl_waqay_security_loop.py ./
 # Claim-integrity Rupture Gate wave 15: contract-only, external signals only,
 # unsigned deterministic receipts, zero effectors.
 COPY szl_claim_rupture_gate.py ./
+# Quantum Utility Gate wave 16: pure-stdlib proposal analysis only.  No provider
+# SDK, QPU call, credential path, external effector, or finance-engine coupling.
+COPY szl_quantum_utility.py ./
+# Wave 18 numerical-engine frontier. These are only the Apache-2.0 host contract
+# and fixed data-only Octave script. GNU Octave, MATLAB, proprietary Engine
+# libraries, license material, and packages are deliberately NOT installed or
+# copied. Without an operator-provided external engine and isolation controls,
+# the API reports UNAVAILABLE.
+COPY szl_numerics_adapter.py ./
+COPY szl_numerics_dataset.py ./
+COPY szl_numerics_experiment.py ./
+COPY numerics/ ./numerics/
+# Wave 23 Yupaq governed computation plane.  It ships only the strict routing
+# contract and delegates to already-copied engines; it installs no new runtime,
+# prover, provider SDK, or proprietary dependency.
+COPY szl_yupaq_compute.py ./
+COPY proofs/lean-theorem-tree.json ./proofs/lean-theorem-tree.json
+COPY research/formula-training-admission/admission-manifest.json ./research/formula-training-admission/admission-manifest.json
+COPY data/szl-lake/evidence-manifest.json ./data/szl-lake/evidence-manifest.json
+# Wave 19 formal-conjecture receipt lab. This copies only the strict contract,
+# bounded ledger, and public-key receipt verifier; it installs no prover and
+# exposes no command or network execution path.
+COPY szl_formal_conjecture_lab.py ./
+# M1 experimental model operational gate. Metadata and the status UI are
+# bundled, but model/base/adapter weights are not. A stock image therefore
+# reports UNAVAILABLE until an operator mounts exact local artifacts and the
+# verified local PEFT/GPU runtime; no build-time or request-time download path.
+COPY szl_m1_model_gate.py ./
+COPY szl_m1_corpus_manifest.py ./
+COPY model_release/m1/ ./model_release/m1/
+# Canonical release identity and public Zenodo readback receipt. The readback
+# file ships in a PENDING state until a separately verified archive PR replaces
+# it; the runtime never invents a DOI from the version number.
+COPY szl_release_identity.py ./
+COPY zenodo-readback.json ./
+# Shared fail-closed provider transport. Registry adapters opt in to private
+# destinations explicitly; this module performs pinned DNS validation, bounded
+# redirect handling, response-size limits, and secret-safe deterministic errors.
+COPY szl_provider_http.py ./
 # Primary official project registry (51 records across 10 fields).  Runtime
 # serves the deterministic, unranked registry; optional live metadata remains a
 # bounded adapter and is not executed on anonymous public requests.
@@ -659,7 +706,7 @@ COPY benchmarks/pinn/run_bench.py ./benchmarks/pinn/run_bench.py
 # hf-sync mirrored) — same baked-only pattern as web/sda.html + web/immune.html;
 # declared in copy-sync-lockstep.json image_only_assets + hf-module-drift-allow.json
 # accepted_divergences.
-COPY web/formulas.html web/v4_fleet_panel.html web/operator.html web/fleet-c2.html web/living-anatomy.html web/nemo.html web/restraint.html web/restraint-bench.html web/holo.html web/constitution.html web/quant.html web/estate-hologram.html web/hologram.html web/determinacy.html web/verify-receipt.html web/sda.html web/dns.html ./web/
+COPY web/formulas.html web/v4_fleet_panel.html web/operator.html web/fleet-c2.html web/living-anatomy.html web/nemo.html web/restraint.html web/restraint-bench.html web/holo.html web/constitution.html web/quant.html web/estate-hologram.html web/hologram.html web/determinacy.html web/verify-receipt.html web/sda.html web/dns.html web/m1-model.html ./web/
 COPY web/signature-is-not-proof.html ./web/signature-is-not-proof.html
 COPY web/defense-readiness.html ./web/defense-readiness.html
 # ADDITIVE (Lane A AGENTIC CORE, Dev A, 2026-06-14; QA9 restore 2026-06): the
@@ -1563,6 +1610,9 @@ COPY szl_brainconsensus.py ./szl_brainconsensus.py
 # brainqueryaudit.js ships via the existing whole-tree `COPY static/3d/ ./static/3d/`
 # above. RECORDS/OBSERVES only — adds NOTHING to the locked-8; Λ = Conjecture 1; trust 0.97.
 COPY szl_brainqueryaudit.py ./szl_brainqueryaudit.py
+# Wave 22: content-addressed corpus admission + fail-closed Brain reranker/feed.
+# No model weights, trainer, or network harvester are included.
+COPY szl_braincorpus.py szl_brain_reranker.py ./
 # BRAIN LINEAGE (feat/frontier-brainlineage) — NODE-ORIGIN lineage over the SAME
 # honest brain graph: for a node id or a query's top nodes it reports HOW each node
 # ENTERED the graph, read VERBATIM from the node's OWN real origin fields
@@ -1656,7 +1706,14 @@ COPY a11oy_quant_signals_nav.py ./a11oy_quant_signals_nav.py
 ARG SZL_GIT_SHA=unknown
 ARG SZL_BUILD_TIME=unknown
 ENV SZL_GIT_SHA=${SZL_GIT_SHA} \
-    SZL_BUILD_TIME=${SZL_BUILD_TIME}
+    SZL_BUILD_TIME=${SZL_BUILD_TIME} \
+    A11OY_ORG_RAG_DB=/app/data/a11oy_org_rag.db
+
+# The Second Brain's SQLite index is rebuildable, but a mounted /app/data keeps
+# the active generation across process/container replacement. Deployments that
+# do not attach storage will rebuild and report that fact; they never claim
+# cross-redeploy durability.
+VOLUME ["/app/data"]
 CMD ["python", "serve.py"]
 
 

a11oy_ayllu.py

@@ -4,8 +4,8 @@ Follows a11oy's module convention: expose `register(app, ns="a11oy") -> str`, mo
 by serve.py inside a try/except guard so a11oy boots unaffected if anything here fails.
 
 The model backend is a11oy's OWN orchestrator (see ayllu/backend.py): ask/council now
-produce REAL answers when an inference credential is present on the Space, and an
-honest, clearly-labeled stub otherwise — never a fabricated answer. Cost is bounded:
+produce REAL answers when a reachable local endpoint or credentialed remote provider
+is available, and an honest, clearly-labeled stub otherwise — never a fabricated answer. Cost is bounded:
 prompt length is capped, council fan-out is capped, and ask/council carry a process-
 wide rate limit (429 + Retry-After).
 
@@ -63,12 +63,14 @@ from ayllu import __version__ as _AYLLU_VERSION
 from ayllu import backend as _backend
 from ayllu.lounge import Lounge
 from ayllu.loop import run_turn
+from ayllu.model_binding import family_binding, persona_binding, second_brain_binding
 from ayllu.personas import ROSTER, get_persona
 
 __version__ = _AYLLU_VERSION
 
 # ---- cost + abuse bounds (public Space; real token cost once live) -----------
 MAX_PROMPT_CHARS = 6000
+MAX_BODY_BYTES = 24 * 1024
 COUNCIL_MAX = 5                                     # hard cap on participants / call
 COUNCIL_DEBATE_MAX = 3  # debate doubles model calls; tighter cap bounds cost
 ASK_MAX_TOKENS = 384
@@ -80,11 +82,43 @@ COUNCIL_DEFAULT = ["Amaru", "Kamachiq", "Qhatuq"]  # architect · orchestrator
 COUNCIL_CONTRACT_VERSION = "2.0"
 COUNCIL_SCHEMA = "szl.ayllu.evidence-bound-council/v2"
 NEMO_ARTIFACT = "https://huggingface.co/SZLHOLDINGS/szl-nemo"
+RUNTIME_VERIFY_KEY_URL = "/api/a11oy/cosign.pub"
 
-# One process-wide lounge (in-memory, honest source labels).
+# One process-wide opt-in lounge (in-memory, honest source labels). Public ask and
+# council handlers do not automatically publish caller output into it.
 _LOUNGE = Lounge()
 
 
+class _BodyTooLarge(ValueError):
+    pass
+
+
+async def _bounded_json_body(request: "Request") -> Dict[str, Any]:
+    """Read one bounded JSON object before any paid inference is attempted."""
+    declared = request.headers.get("content-length")
+    if declared is not None:
+        try:
+            size = int(declared)
+        except ValueError as exc:
+            raise ValueError("invalid content-length") from exc
+        if size < 0:
+            raise ValueError("invalid content-length")
+        if size > MAX_BODY_BYTES:
+            raise _BodyTooLarge(f"request body exceeds {MAX_BODY_BYTES} bytes")
+    data = bytearray()
+    async for chunk in request.stream():
+        if len(data) + len(chunk) > MAX_BODY_BYTES:
+            raise _BodyTooLarge(f"request body exceeds {MAX_BODY_BYTES} bytes")
+        data.extend(chunk)
+    try:
+        value = json.loads(bytes(data).decode("utf-8"))
+    except (UnicodeDecodeError, json.JSONDecodeError) as exc:
+        raise ValueError("invalid JSON body") from exc
+    if not isinstance(value, dict):
+        raise ValueError("request body must be a JSON object")
+    return value
+
+
 class _RateBucket:
     """Tiny process-wide sliding-window limiter. Honest: bounds THIS process only."""
 
@@ -144,7 +178,11 @@ def _make_receipt(payload: Dict[str, Any], sign_fn=None) -> Dict[str, Any]:
         try:
             env = sign_fn(payload)
             if isinstance(env, dict):
-                return env
+                out = dict(env)
+                out.setdefault("verify_key_url", RUNTIME_VERIFY_KEY_URL)
+                out.setdefault("key_scope", "PROCESS_BOOT_EPHEMERAL")
+                out.setdefault("key_lifetime", "UNTIL_PROCESS_RESTART")
+                return out
             honesty = "UNSIGNED - runtime signer returned a non-object; no signature fabricated."
         except Exception as exc:
             honesty = (f"UNSIGNED - runtime signer raised ({str(exc)[:80]}); "
@@ -277,6 +315,7 @@ def council_manifest(ns: str = "a11oy",
             "outer Council DSSE receipt",
         ],
         "limits": {
+            "request_body_bytes": MAX_BODY_BYTES,
             "prompt_chars": MAX_PROMPT_CHARS,
             "participants": COUNCIL_MAX,
             "debate_participants": COUNCIL_DEBATE_MAX,
@@ -299,7 +338,7 @@ def council_manifest(ns: str = "a11oy",
         "reproduce": {
             "manifest": base + "/council/manifest",
             "verifier": f"/api/{ns}/v1/verify/receipt",
-            "public_key": "/cosign.pub",
+            "public_key": RUNTIME_VERIFY_KEY_URL,
         },
         "nemo": {
             "artifact": NEMO_ARTIFACT,
@@ -311,6 +350,8 @@ def council_manifest(ns: str = "a11oy",
                 "not SZL-trained weights. Council answers use the live A11OY router."
             ),
         },
+        "model_family": family_binding(
+            namespace=ns, backend_status=_backend.backend_status()),
         "evaluation": {
             "council_effectiveness": "NOT_MEASURED",
             "required_next": (
@@ -350,11 +391,19 @@ def _nemo_council_route(prompt: str, sign_fn=None) -> Dict[str, Any]:
 
 
 def _build_council_contract(prompt: str, result: Dict[str, Any],
-                            nemo_route: Dict[str, Any]) -> Dict[str, Any]:
+                            nemo_route: Dict[str, Any],
+                            ns: str = "a11oy") -> Dict[str, Any]:
+    family = family_binding(namespace=ns, backend_status=_backend.backend_status())
     rounds = result.get("rounds") or []
     turn_evidence = []
     for turn in rounds:
         answer = turn.get("answer")
+        honesty = turn.get("honesty")
+        grounding = turn.get("grounding") if isinstance(
+            turn.get("grounding"), dict) else {}
+        citation_validation = grounding.get("citation_validation")
+        answer_sha = (hashlib.sha256(answer.encode("utf-8")).hexdigest()
+                      if isinstance(answer, str) else None)
         turn_evidence.append({
             "persona": turn.get("persona"),
             "round": turn.get("round"),
@@ -365,9 +414,39 @@ def _build_council_contract(prompt: str, result: Dict[str, Any],
             "timeout_s": turn.get("timeout_s"),
             "correctness_state": ("NOT_APPLICABLE_STUB" if bool(turn.get("stub"))
                                   else "UNVERIFIED_MODEL_OUTPUT"),
-            "output_sha256": (hashlib.sha256(str(answer).encode("utf-8")).hexdigest()
-                              if answer is not None else None),
+            "answer_present": answer is not None,
+            "answer_sha256": answer_sha,
+            "output_sha256": answer_sha,
+            "honesty_sha256": (hashlib.sha256(str(honesty).encode("utf-8")).hexdigest()
+                               if honesty is not None else None),
+            "turn_output_sha256": _sha256_json({
+                "answer": answer,
+                "honesty": honesty,
+                "stub": bool(turn.get("stub")),
+                "timeout": bool(turn.get("timeout", False)),
+                "model": turn.get("model"),
+            }),
             "energy_receipt_sha256": _receipt_sha(turn.get("energy_receipt")),
+            "model_binding": turn.get("model_binding"),
+            "model_binding_sha256": (
+                _sha256_json(turn["model_binding"])
+                if isinstance(turn.get("model_binding"), dict) else None
+            ),
+            "model_attestation_sha256": (
+                turn.get("model_binding", {}).get("model_attestation_sha256")
+                if isinstance(turn.get("model_binding"), dict) else None
+            ),
+            "grounding_sha256": (
+                turn.get("model_binding", {}).get("grounding_sha256")
+                if isinstance(turn.get("model_binding"), dict) else None
+            ),
+            "evidence_set_sha256": grounding.get("evidence_set_sha256"),
+            "handles_sha256": grounding.get("handles_sha256"),
+            "augmented_prompt_sha256": grounding.get("augmented_prompt_sha256"),
+            "citation_validation_sha256": (
+                _sha256_json(citation_validation)
+                if isinstance(citation_validation, dict) else None
+            ),
         })
     replay_material = {
         "contract_version": COUNCIL_CONTRACT_VERSION,
@@ -398,6 +477,8 @@ def _build_council_contract(prompt: str, result: Dict[str, Any],
         "correctness_state": "NOT_VERIFIED",
         "prompt_sha256": replay_material["prompt_sha256"],
         "turn_evidence": turn_evidence,
+        "model_family": family,
+        "model_family_binding_sha256": _sha256_json(family),
         "routing": nemo_route,
         "formula_path": [
             {"id": "lambda-aggregate", "state": "CONJECTURE_1_ADVISORY"},
@@ -432,7 +513,7 @@ def _build_council_contract(prompt: str, result: Dict[str, Any],
             "key": "sha256:" + _sha256_json(replay_material),
             "material": replay_material,
             "verifier": "/api/a11oy/v1/verify/receipt",
-            "public_key": "/cosign.pub",
+            "public_key": RUNTIME_VERIFY_KEY_URL,
         },
         "training": {
             "artifact": NEMO_ARTIFACT,
@@ -526,7 +607,7 @@ radial-gradient(50% 35% at 10% 110%,rgba(212,164,68,.05),transparent 60%)}
 main{max-width:980px;margin:0 auto;padding:36px 22px;position:relative;z-index:1}
 h1{color:var(--teal);margin:0 0 4px;font-size:26px;display:flex;align-items:center;gap:10px}
 h2{font-size:16px;margin:0 0 10px;color:var(--fg)}
-.sub{color:var(--dim);margin:0 0 22px}
+.sub,#family{color:var(--dim);margin:0 0 22px;min-width:0;overflow-wrap:anywhere}
 .badge{font-size:11px;font-weight:700;letter-spacing:.04em;padding:3px 8px;border-radius:20px;
 border:1px solid var(--line);color:var(--dim)}
 .badge.live{color:#0a1;background:#0a2a17;border-color:#1c5}
@@ -590,12 +671,13 @@ section[id]{scroll-margin-top:72px}
 .tgl{display:flex;gap:7px;align-items:center;color:var(--dim);font-size:13px;margin:0 0 8px}
 .tgl input{width:auto}
 .prov{color:var(--dim);font-size:11px;margin-top:14px;line-height:1.6}
+.small,.src,.contract,.rcpt,.prov,.ans{min-width:0;overflow-wrap:anywhere}
 @media (max-width:720px){
  main{padding:24px 14px}
  .tb-wrap{padding:9px 14px;flex-wrap:nowrap}
  .tb-brand{flex:0 0 auto}
- .tb-nav{flex:1 1 auto;min-width:0;flex-wrap:nowrap;overflow-x:auto;
-  -webkit-overflow-scrolling:touch;scrollbar-width:none}
+ .tb-nav{flex:1 1 auto;min-width:0;max-width:100%;flex-wrap:nowrap;overflow-x:auto;
+  -webkit-overflow-scrolling:touch;scrollbar-width:none;overscroll-behavior-inline:contain}
  .tb-nav::-webkit-scrollbar{display:none}
  .tb-nav a{flex:0 0 auto}
  .card{padding:14px}
@@ -608,13 +690,14 @@ section[id]{scroll-margin-top:72px}
 </style></head><body>
 <header class="topbar"><div class="tb-wrap">
 <a class="tb-brand" href="/ayllu">Ayllu <span id="badge" class="badge">…</span></a>
-<nav class="tb-nav"><a href="#sec-ask">Ask</a><a href="#sec-council">Council</a><a href="#sec-roster">Roster</a><a href="#sec-lounge">Lounge</a><a href="#sec-organism">Organism</a><a href="#sec-mesh">Mesh</a><a class="tb-home" href="/console" title="Back to the a11oy command centre">&#8592; a11oy command centre</a></nav>
+<nav class="tb-nav" aria-label="Ayllu sections"><a href="#sec-ask">Ask</a><a href="#sec-council">Council</a><a href="#sec-roster">Roster</a><a href="#sec-lounge">Lounge</a><a href="#sec-organism">Second Brain</a><a href="#sec-mesh">Mesh</a><a class="tb-home" href="/console" title="Back to the a11oy command centre">&#8592; a11oy command centre</a></nav>
 </div></header>
 <main>
 <h1>Ayllu</h1>
 <p class="sub">The AlloyScape tribe, ingested and reborn as a11oy's own agent community —
 <span id="count">?</span> personas, one guarded loop. v__VERSION__ ·
-<span title="Curated, cited text appended to every persona's system prompt — no weights changed anywhere.">knowledge instilled, never "trained"</span></p>
+<span title="Curated, cited text appended to every persona's system prompt — no weights changed anywhere.">knowledge instilled, never "trained"</span> ·
+<span id="family">model binding loading</span></p>
 
 <section class="card" id="sec-ask">
   <h2>Ask a persona</h2>
@@ -649,14 +732,14 @@ section[id]{scroll-margin-top:72px}
 <section class="card" id="sec-roster">
   <h2>Roster</h2>
   <table id="roster"><thead><tr><th>Persona</th><th>Quechua</th><th>Archetype</th>
-  <th>a11oy domain</th><th>Autonomy</th><th>Knowledge</th></tr></thead><tbody></tbody></table>
+  <th>a11oy domain</th><th>Forge intent</th><th>Autonomy</th><th>Knowledge</th></tr></thead><tbody></tbody></table>
   <div class="src" style="margin-top:6px">"Instilled ✓" = the shared, cited Wave-13 leaders
   corpus is appended to that persona's system prompt at runtime. No model weights are
   changed anywhere — this is knowledge instillation, not training.</div>
 </section>
 
 <section class="card" id="sec-lounge">
-  <h2>Lounge <button id="refreshlounge" class="mini">refresh</button></h2>
+  <h2>Opt-in lounge <button id="refreshlounge" class="mini">refresh</button></h2>
   <div id="lounge" class="out"></div>
 </section>
 
@@ -666,12 +749,14 @@ section[id]{scroll-margin-top:72px}
   organism. These panels read the same governed endpoints as the command centre — an
   unavailable endpoint says so rather than faking a value.</div>
   <div class="grid">
+    <div class="panel"><h3>Khipu Second Brain <span class="small" id="sb-badge">…</span></h3><div id="sb-out" class="small">loading…</div></div>
     <div class="panel"><h3>Formulas <span class="small" id="f-badge">…</span></h3><div id="f-out" class="small">loading…</div></div>
     <div class="panel"><h3>Doctrine lock <span class="small" id="d-badge">…</span></h3><div id="d-out" class="small">loading…</div></div>
     <div class="panel"><h3>Sovereign energy <span class="small" id="e-badge">…</span></h3><div id="e-out" class="small">loading…</div></div>
   </div>
   <div class="links">
     <a href="/living-anatomy">Living anatomy</a>
+    <a href="/api/__NS__/v1/ayllu/second-brain">Second Brain contract</a>
     <a href="/formulas">PURIQ formulas</a>
     <a href="/wires">The constitution</a>
     <a href="/api/__NS__/v1/brain/graph" title="Full brain graph JSON (~4 MB)">Brain graph (raw JSON)</a>
@@ -691,7 +776,8 @@ section[id]{scroll-margin-top:72px}
 <div class="law"><b>Bounded-autonomy law.</b> Every persona runs under a11oy's
 fail-closed Λ-gate; state-changing actions require two-person attestation. The tribe's
 "always execute" mandate is deliberately <b>not</b> adopted. Answers come from a11oy's
-own model backend + router; when no inference credential is set on this Space,
+own model backend + router; when neither a reachable local backend nor a remote
+inference credential is available,
 <code>ask</code>/<code>council</code> return a clearly-labeled stub — never a fabricated
 answer. Debate mode is bounded to exactly two rounds. These turns do direct completion
 only (no tool dispatch yet).</div>
@@ -744,6 +830,9 @@ async function loadRoster(){
   badge.textContent=mode.toUpperCase();
   badge.className='badge '+(mode==='live'?'live':mode==='stub'?'stub':'warn');
   badge.title=b.note||'';
+  const mf=data.model_family||{}, family=document.getElementById('family');
+  family.textContent=(mf.family_id||'model family unknown')+' · '+(mf.binding_state||'UNAVAILABLE');
+  family.title='Profile intent only. The actual model is named by each turn receipt.';
   const sel=document.getElementById('persona'), csel=document.getElementById('councilsel');
   const rows=[];
   (data.personas||[]).forEach(p=>{
@@ -751,8 +840,10 @@ async function loadRoster(){
     o.textContent=p.name+' — '+p.domain;sel.appendChild(o);
     csel.appendChild(o.cloneNode(true));
     const kn=p.knowledge_instilled?'instilled ✓':'—';
+    const mb=p.model_binding||{};
     rows.push(`<tr><td>${chip(p.name)} <b>${esc(p.name)}</b></td><td>${esc(p.quechua)}</td>`
       +`<td>${esc(p.archetype)}</td><td>${esc(p.domain)}</td>`
+      +`<td>${esc(mb.primary_profile||'UNBOUND')}</td>`
       +`<td>${esc(p.autonomy_level)}</td><td class="src">${kn}</td></tr>`);
   });
   document.querySelector('#roster tbody').innerHTML=rows.join('');
@@ -825,6 +916,30 @@ async function loadLounge(){
 document.getElementById('refreshlounge').onclick=loadLounge;
 function unavailable(el,status){el.innerHTML='<span class="src">endpoint unavailable ('
   +esc(String(status))+') — shown honestly, not faked.</span>';}
+async function loadSecondBrain(){
+  const badge=document.getElementById('sb-badge'), out=document.getElementById('sb-out');
+  const {ok,status,data}=await j(api('second-brain'));
+  if(!ok){badge.textContent='offline';unavailable(out,status);return;}
+  const ready=!!data.ready_for_grounded_navigation;
+  const profile=data.profile||{}, memory=data.memory||{}, training=data.training_boundary||{};
+  badge.textContent=ready?'ready':'gated';
+  out.innerHTML='<div class="kpi">'+esc(ready?'GROUNDED':'NOT READY')+'</div>'
+    +'<div class="small">'+esc(data.system_id||'SZL-Khipu-Second-Brain-v1')+'</div>'
+    +'<div class="lg small">model '+esc(profile.served_model||profile.expected_model||'unavailable')
+    +' · exact tag '+esc(profile.exact_tag_observed?'observed':'missing')+'</div>'
+    +'<div class="lg small">memory '+esc(memory.built?'built':'not built')
+    +' · '+esc(String(memory.document_count??'—'))+' docs · '
+    +esc(String(memory.chunk_count??'—'))+' chunks · '
+    +esc(String(memory.node_count??'—'))+' graph nodes</div>'
+    +'<div class="lg small">Brain handles '+esc(String(memory.brain_handle_count??0))
+    +' · gradient authority '+esc(String(memory.training_authority_rows??0))
+    +' · integrity '+esc(memory.integrity_state||memory.rehydration_state||'not evaluated')+'</div>'
+    +'<div class="lg small">gradient admission '
+    +esc(String(training.raw_brain_nodes_admitted_to_gradients??0))+' / '
+    +esc(String(training.raw_brain_nodes_observed??'—'))
+    +' · '+esc(data.promotion_state||data.state||'UNKNOWN')+'</div>'
+    +'<div class="src" style="margin-top:6px">Compound model: navigator + persistent evidence memory + governed controller + receipts. Indexed nodes are not mislabeled as weights.</div>';
+}
 async function loadFormulas(){
   const b=document.getElementById('f-badge'), out=document.getElementById('f-out');
   const {ok,status,data}=await j(gapi('formulas'));
@@ -880,7 +995,7 @@ async function loadObs(){
   out.innerHTML='<div class="lg"><b>observability</b><pre class="src" style="white-space:pre-wrap;margin:.3rem 0 0">'
     +esc(JSON.stringify(data.melt||data,null,2).slice(0,600))+'</pre></div>';
 }
-loadRoster();loadLounge();loadMesh();loadObs();loadFormulas();loadDoctrine();loadEnergy();
+loadRoster();loadLounge();loadMesh();loadObs();loadSecondBrain();loadFormulas();loadDoctrine();loadEnergy();
 </script>
 </body></html>"""
 
@@ -910,17 +1025,43 @@ def register(app, ns: str = "a11oy") -> str:
             return None
 
     async def _roster(request: "Request") -> "JSONResponse":
+        backend = _backend.backend_status()
         return JSONResponse({
             "count": len(ROSTER),
             "namespace": ns,
-            "personas": [p.metadata() for p in ROSTER],
-            "backend": _backend.backend_status(),
+            "personas": [
+                {**p.metadata(), "model_binding": persona_binding(p.name)}
+                for p in ROSTER
+            ],
+            "backend": backend,
+            "model_family": family_binding(namespace=ns, backend_status=backend),
             "law": "a11oy bounded-autonomy (fail-closed Λ-gate); the tribe's unbounded "
                    "'always execute' mandate is NOT adopted",
             "provenance": "ingested from the AlloyScape tribe design; see ayllu/INGEST.md",
             "version": __version__,
         })
 
+    async def _model_binding(request: "Request") -> "JSONResponse":
+        return JSONResponse(family_binding(
+            namespace=ns, backend_status=_backend.backend_status()))
+
+    async def _second_brain(request: "Request") -> "JSONResponse":
+        try:
+            import a11oy_org_rag as _org_rag
+            rag = _org_rag.status()
+        except Exception as exc:
+            rag = {
+                "built": False,
+                "state": "UNAVAILABLE",
+                "honesty": f"Brain status unavailable ({type(exc).__name__})",
+            }
+        return JSONResponse(second_brain_binding(
+            namespace=ns,
+            backend_status=_backend.backend_status(),
+            rag_status=rag,
+            signer_ready=callable(getattr(request.app.state, "szl_sign_receipt", None)),
+        ))
+
     async def _council_manifest(request: "Request") -> "JSONResponse":
         storage = getattr(request.app.state, "ayllu_council_khipu_storage",
                           council_storage)
@@ -933,12 +1074,12 @@ def register(app, ns: str = "a11oy") -> str:
                 {"error": "rate limited (process-wide ask budget)", "retry_after_s": retry},
                 status_code=429, headers={"Retry-After": str(retry)})
         try:
-            body = await request.json()
-        except Exception as e:
-            return JSONResponse({"error": f"invalid JSON: {e}"}, status_code=400)
-        if not isinstance(body, dict):
-            return JSONResponse({"error": "request body must be a JSON object"},
-                                status_code=422)
+            body = await _bounded_json_body(request)
+        except _BodyTooLarge as exc:
+            return JSONResponse({"error": str(exc), "max_bytes": MAX_BODY_BYTES},
+                                status_code=413)
+        except ValueError as exc:
+            return JSONResponse({"error": str(exc)}, status_code=400)
         name = body.get("persona")
         prompt = body.get("prompt")
         if not name or not prompt:
@@ -967,20 +1108,54 @@ def register(app, ns: str = "a11oy") -> str:
 
         turn = await run_turn(p, prompt, model_complete=_ask_complete,
                               difficulty=difficulty)
+        binding = turn["model_binding"]
+        grounding = turn.get("grounding") if isinstance(
+            turn.get("grounding"), dict) else {}
+        citation_validation = grounding.get("citation_validation")
         ask_id = str(uuid.uuid4())
+        # Bind the answer and honesty channels independently.  None means no
+        # answer; an empty string is a present answer and hashes as SHA256("").
+        answer = turn.get("answer")
+        honesty = turn.get("honesty")
+        answer_sha = (hashlib.sha256(answer.encode("utf-8")).hexdigest()
+                      if isinstance(answer, str) else None)
+        honesty_sha = (hashlib.sha256(str(honesty).encode("utf-8")).hexdigest()
+                       if honesty is not None else None)
+        turn_output_sha = _sha256_json({
+            "answer": answer,
+            "honesty": honesty,
+            "stub": bool(turn.get("stub")),
+            "timeout": bool(turn.get("timeout", False)),
+            "model": turn.get("model"),
+        })
         receipt = _make_receipt({
             "ask_id": ask_id,
             "persona": p.name,
             "prompt_sha256": hashlib.sha256(prompt.encode()).hexdigest(),
+            "answer_present": answer is not None,
+            "answer_sha256": answer_sha,
+            "output_sha256": answer_sha,
+            "honesty_sha256": honesty_sha,
+            "turn_output_sha256": turn_output_sha,
             "tier_advisory": turn.get("tier", {}).get("route"),
             "model": turn.get("model"),
             "stub": turn.get("stub"),
             "energy_receipt_sha256": _receipt_sha(turn.get("energy_receipt")),
+            "family_id": binding["family_id"],
+            "profile_intent": binding["primary_profile"],
+            "binding_state": binding["binding_state"],
+            "model_binding_sha256": _sha256_json(binding),
+            "model_attestation_sha256": binding.get("model_attestation_sha256"),
+            "grounding_sha256": binding.get("grounding_sha256"),
+            "evidence_set_sha256": grounding.get("evidence_set_sha256"),
+            "handles_sha256": grounding.get("handles_sha256"),
+            "augmented_prompt_sha256": grounding.get("augmented_prompt_sha256"),
+            "citation_validation_sha256": (
+                _sha256_json(citation_validation)
+                if isinstance(citation_validation, dict) else None
+            ),
             "honesty": turn.get("honesty"),
         }, sign_fn=_runtime_signer(request))
-        _LOUNGE.post(
-            p.name, turn.get("answer") or turn.get("honesty"),
-            source=("brain" if turn.get("answer") is not None else "persona-fallback"))
         return JSONResponse({"ask_id": ask_id, "turn": turn, "receipt": receipt})
 
     async def _council(request: "Request") -> "JSONResponse":
@@ -991,12 +1166,12 @@ def register(app, ns: str = "a11oy") -> str:
                  "retry_after_s": retry},
                 status_code=429, headers={"Retry-After": str(retry)})
         try:
-            body = await request.json()
-        except Exception as e:
-            return JSONResponse({"error": f"invalid JSON: {e}"}, status_code=400)
-        if not isinstance(body, dict):
-            return JSONResponse({"error": "request body must be a JSON object"},
-                                status_code=422)
+            body = await _bounded_json_body(request)
+        except _BodyTooLarge as exc:
+            return JSONResponse({"error": str(exc), "max_bytes": MAX_BODY_BYTES},
+                                status_code=413)
+        except ValueError as exc:
+            return JSONResponse({"error": str(exc)}, status_code=400)
         prompt = body.get("prompt")
         if not prompt:
             return JSONResponse({"error": "'prompt' is required"}, status_code=422)
@@ -1033,13 +1208,14 @@ def register(app, ns: str = "a11oy") -> str:
                 timeout_s=COUNCIL_TURN_TIMEOUT_S)
 
         result = await _LOUNGE.deliberate(
-            prompt, personas, model_complete=_council_complete, debate=debate)
+            prompt, personas, model_complete=_council_complete, debate=debate,
+            publish_to_lounge=False)
         if cap_note:
             result["cap_note"] = cap_note
         council_id = str(uuid.uuid4())
         signer = _runtime_signer(request)
         nemo_route = _nemo_council_route(prompt, sign_fn=signer)
-        contract = _build_council_contract(prompt, result, nemo_route)
+        contract = _build_council_contract(prompt, result, nemo_route, ns=ns)
         store = getattr(request.app.state, "ayllu_council_khipu", council_store)
         storage = getattr(request.app.state, "ayllu_council_khipu_storage",
                           council_storage)
@@ -1055,6 +1231,8 @@ def register(app, ns: str = "a11oy") -> str:
             "evidence_state": contract["evidence_state"],
             "replay_key": contract["replay"]["key"],
             "turn_evidence": contract["turn_evidence"],
+            "model_family_binding_sha256": contract[
+                "model_family_binding_sha256"],
             "nemo_route_receipt_sha256": _receipt_sha(
                 (contract.get("routing") or {}).get("receipt")),
             "human_checkpoint": contract["human_checkpoint"],
@@ -1079,6 +1257,12 @@ def register(app, ns: str = "a11oy") -> str:
     app.add_api_route(f"/api/{ns}/v1/ayllu/roster", _roster, methods=["GET"],
                       tags=["ayllu"],
                       summary="a11oy-native agent roster + live/stub backend status")
+    app.add_api_route(f"/api/{ns}/v1/ayllu/model-binding", _model_binding,
+                      methods=["GET"], tags=["ayllu"],
+                      summary="Honest SZL-Forge family and Yupaq proposal binding")
+    app.add_api_route(f"/api/{ns}/v1/ayllu/second-brain", _second_brain,
+                      methods=["GET"], tags=["ayllu"],
+                      summary="Khipu compound Second Brain runtime and training boundary")
     app.add_api_route(f"/api/{ns}/v1/ayllu/ask", _ask, methods=["POST"],
                       tags=["ayllu"],
                       summary="Ask one persona — bounded, honest, receipted")
@@ -1089,13 +1273,13 @@ def register(app, ns: str = "a11oy") -> str:
                       tags=["ayllu"],
                       summary="Bounded multi-persona deliberation (capped fan-out; optional 2-round debate mode after arXiv:2305.14325)")
     app.add_api_route(f"/api/{ns}/v1/ayllu/lounge", _lounge_feed, methods=["GET"],
-                      tags=["ayllu"], summary="Recent collaboration lounge feed")
+                      tags=["ayllu"], summary="Opt-in collaboration lounge feed")
     app.add_api_route("/ayllu", _page, methods=["GET"], include_in_schema=False)
 
     return (
         f"ok — ayllu registered: {len(ROSTER)} personas; live model backend "
         f"({_backend.backend_status().get('mode')}); bounded-autonomy Λ-gate; "
-        f"/ayllu + /api/{ns}/v1/ayllu/roster|ask|council|lounge; "
+        f"/ayllu + /api/{ns}/v1/ayllu/roster|model-binding|ask|council|lounge; "
         f"debate-mode council; council_khipu={council_storage.get('backend')} "
         f"(process_restart_durable={council_storage.get('durable')}, "
         f"redeploy=NOT_VERIFIED); version={__version__}"

a11oy_brain_graph.py

@@ -57,9 +57,6 @@ import json
 import os
 import re
 
-from fastapi import FastAPI
-from fastapi.responses import JSONResponse
-
 import a11oy_frontier_page as _frontier
 import szl_puriq_formulas as _puriq
 
@@ -555,7 +552,7 @@ def filtered_graph(ns: str = "a11oy", *, layer=None, axis=None, source=None,
     return view
 
 
-def register(app: FastAPI, ns: str = "a11oy") -> str:
+def register(app, ns: str = "a11oy") -> str:
     """Mount GET /api/<ns>/v1/brain/graph. ADDITIVE — before the SPA catch-all.
 
     Pure read; harvests the real estate + committed field-leader JSONL into a
@@ -563,6 +560,10 @@ def register(app: FastAPI, ns: str = "a11oy") -> str:
     GET). Query params: ?layer=<int> ?axis=<token> ?source=<token>
     ?kind=<token> ?summary=1 (counts only)."""
 
+    # Keep the pure graph harvester importable for canonical, offline reindex
+    # jobs. Web dependencies are required only when routes are mounted.
+    from fastapi.responses import JSONResponse
+
     @app.get(f"/api/{ns}/v1/brain/graph")
     async def brain_graph(layer: int = None, axis: str = None,
                           source: str = None, kind: str = None,

a11oy_code_engine.py

@@ -74,7 +74,7 @@ import json
 import math
 import os
 import re
-import resource
+import shutil
 import subprocess
 import sys
 import tempfile
@@ -83,6 +83,11 @@ from datetime import datetime, timezone
 from pathlib import Path
 from typing import Any, Optional
 
+try:  # POSIX-only; Windows must import the engine but refuse code execution.
+    import resource
+except ImportError:  # pragma: no cover - exercised on Windows
+    resource = None
+
 # ---- reuse the PROVEN loop primitives (single source of truth for chain semantics)
 try:
     import szl_agentic_loop as _loop
@@ -344,6 +349,35 @@ _FORBIDDEN_CALLS = ("open(", "eval(", "exec(", "compile(", "__import__", "input(
                     "os.remove", "os.rmdir", "os.unlink", "os.environ", "os.popen",
                     "os.fork", "os.kill")
 
+_UNSHARE = shutil.which("unshare") if os.name == "posix" else None
+
+
+def sandbox_capability() -> dict:
+    """Describe the fixed isolation prerequisites without attempting execution.
+
+    Importability is deliberately separate from executability: Windows can serve
+    diagnostics and governed planning, but it cannot claim an isolated code engine
+    without POSIX rlimits and a real network namespace boundary.
+    """
+    missing = []
+    if os.name != "posix":
+        missing.append("POSIX_HOST")
+    if resource is None:
+        missing.append("POSIX_RESOURCE_LIMITS")
+    if not _UNSHARE:
+        missing.append("UNSHARE_NET_NAMESPACE")
+    return {
+        "state": "READY_TO_PROBE" if not missing else "UNAVAILABLE",
+        "missing": missing,
+        "resource_limits": resource is not None,
+        "network_namespace_command": _UNSHARE,
+        "honesty": (
+            "Execution still requires a successful per-run unshare --net probe."
+            if not missing else
+            "Code execution is refused because the fixed isolation prerequisites are absent."
+        ),
+    }
+
 
 def _static_screen(code: str) -> dict:
     """Static pre-screen BEFORE execution (defense in depth — the loop's policy gate
@@ -439,6 +473,20 @@ def _sandbox_exec(code: str, lang: str = "python", timeout_s: int = 6,
                 "stdout": "", "stderr": "unsupported language: %s" % lang, "exit": -1,
                 "isolation": "n/a"}
 
+    capability = sandbox_capability()
+    if capability["state"] != "READY_TO_PROBE":
+        return {
+            "ok": False,
+            "execution_state": "UNAVAILABLE",
+            "error": "fixed sandbox isolation prerequisites unavailable",
+            "stdout": "",
+            "stderr": "missing: %s" % ", ".join(capability["missing"]),
+            "exit": -1,
+            "elapsed_ms": 0.0,
+            "isolation": "UNAVAILABLE — no code executed",
+            "capability": capability,
+        }
+
     def _limits():
         # child-only resource limits (POSIX). Applied in the forked child pre-exec.
         try:
@@ -472,8 +520,29 @@ def _sandbox_exec(code: str, lang: str = "python", timeout_s: int = 6,
         )
         src.write_text(preamble + (code or ""))
         try:
+            # A command being present is not evidence that this host permits a
+            # network namespace.  Prove the exact boundary immediately before
+            # the run; fail closed if the kernel denies it.
+            probe = subprocess.run(
+                [_UNSHARE, "--net", "--", sys.executable, "-I", "-S", "-c",
+                 "print('SZL_NETNS_READY')"],
+                cwd=box, env=env, capture_output=True, text=True, timeout=3,
+                preexec_fn=_limits,
+            )
+            if probe.returncode != 0 or probe.stdout.strip() != "SZL_NETNS_READY":
+                return {
+                    "ok": False,
+                    "execution_state": "UNAVAILABLE",
+                    "error": "network namespace probe failed",
+                    "stdout": "",
+                    "stderr": (probe.stderr or "unshare --net did not establish isolation")[:4000],
+                    "exit": probe.returncode,
+                    "elapsed_ms": round((time.time() - t0) * 1000, 1),
+                    "isolation": "UNAVAILABLE — no user code executed",
+                    "capability": capability,
+                }
             proc = subprocess.run(
-                [sys.executable, "-I", "-S", str(src)],   # -I isolated, -S no site
+                [_UNSHARE, "--net", "--", sys.executable, "-I", "-S", str(src)],
                 cwd=box, env=env, capture_output=True, text=True,
                 timeout=timeout_s + 1, preexec_fn=_limits,
             )
@@ -483,7 +552,7 @@ def _sandbox_exec(code: str, lang: str = "python", timeout_s: int = 6,
             return {"ok": proc.returncode == 0, "stdout": out, "stderr": err,
                     "exit": proc.returncode, "elapsed_ms": dt,
                     "isolation": ("sandboxed (restricted subprocess): separate process, "
-                                  "CPU+memory+fsize+nproc rlimits, network disabled, %ss "
+                                  "CPU+memory+fsize+nproc rlimits, unshare --net, %ss "
                                   "wall-clock timeout, minimal env. Full seccomp/container "
                                   "isolation on the tower/UDS pod." % timeout_s)}
         except subprocess.TimeoutExpired:

a11oy_code_orchestrator.py

@@ -153,21 +153,21 @@ def _local_endpoint_reachable(base: str, timeout: float = 2.0) -> bool:
 
     HONESTY GATE: setting A11OY_MODEL_BASE_URL is an INTENT, not proof the GPU is
     actually serving. We only claim sovereign:true when the endpoint's OpenAI-
-    compatible /models (or root) actually answers. If it's set but unreachable
+    compatible /models actually returns bounded JSON. If it's set but unreachable
     (e.g. a tailnet endpoint the Space can't reach), we honestly report a router
-    fallback instead of a false sovereign banner. Pure stdlib, short timeout,
-    never raises. NOTE: this reflects ENDPOINT liveness; the chat-serving path
+    fallback instead of a false sovereign banner. The probe uses the same pinned,
+    redirect-revalidating SSRF guard as model identity reads. NOTE: this reflects
+    ENDPOINT liveness; the chat-serving path
     wiring to this endpoint is tracked separately (see #324)."""
-    import urllib.request as _u
-    for path in ("/models", ""):
-        try:
-            req = _u.Request(base.rstrip("/") + path, method="GET")
-            with _u.urlopen(req, timeout=timeout) as r:  # noqa: S310 (trusted op-set base)
-                if 200 <= getattr(r, "status", r.getcode()) < 500:
-                    return True
-        except Exception:  # noqa: BLE001 - any failure => not reachable, stay honest
-            continue
-    return False
+    try:
+        payload = _endpoint_json(
+            base.rstrip("/") + "/models",
+            timeout=timeout,
+            allow_private=True,
+        )
+        return isinstance(payload, dict)
+    except Exception:  # noqa: BLE001 - any failure => not reachable, stay honest
+        return False
 
 
 def _sovereign_inference_state() -> dict:
@@ -265,6 +265,252 @@ def _map_model_for_local(model: str) -> str:
     return A11OY_LOCAL_MODEL_MAP.get("default", model)
 
 
+# Forge profiles are runtime intents, not claims that five separately-trained
+# adapters exist.  Two exact tags are real on the current sovereign runtime
+# (ReceiptAgent and Khipu); the remaining roles intentionally share szl1 until
+# separately-qualified weights and receipts exist.  Read overrides at call time
+# so an operator can change a loaded tag without rebuilding the service.
+_FORGE_PROFILE_DEFAULTS = {
+    "ReceiptAgent-v1": "receiptagent:latest",
+    "BrainNavigator-v1": "khipu:latest",
+    "Operator-v1": "szl1:latest",
+    "Sentinel-v1": "szl1:latest",
+    "Anatomy-v1": "szl1:latest",
+}
+_FORGE_PROFILE_ENV = {
+    "ReceiptAgent-v1": "A11OY_FORGE_RECEIPT_MODEL",
+    "BrainNavigator-v1": "A11OY_FORGE_BRAIN_MODEL",
+    "Operator-v1": "A11OY_FORGE_OPERATOR_MODEL",
+    "Sentinel-v1": "A11OY_FORGE_SENTINEL_MODEL",
+    "Anatomy-v1": "A11OY_FORGE_ANATOMY_MODEL",
+}
+
+
+def forge_profile_model_map() -> dict[str, str]:
+    """Return the exact local tag intended for every governed Forge profile.
+
+    ``A11OY_FORGE_PROFILE_MODELS_JSON`` is an additive whole-map override.  Bad
+    JSON or unknown keys are ignored rather than weakening the profile boundary.
+    """
+    out = {
+        profile: (os.environ.get(_FORGE_PROFILE_ENV[profile]) or default).strip()
+        for profile, default in _FORGE_PROFILE_DEFAULTS.items()
+    }
+    try:
+        raw = os.environ.get("A11OY_FORGE_PROFILE_MODELS_JSON", "").strip()
+        override = json.loads(raw) if raw else {}
+        if isinstance(override, dict):
+            for profile, tag in override.items():
+                if profile in out and isinstance(tag, str) and tag.strip():
+                    out[profile] = tag.strip()
+    except Exception:
+        pass
+    return out
+
+
+def _endpoint_json(url: str, *, body: dict[str, Any] | None = None,
+                   timeout: float = 2.0, allow_private: bool = False) -> dict[str, Any]:
+    """Fetch a bounded provider document through the shared SSRF guard.
+
+    Private/loopback access is never inferred from the URL.  Callers must grant
+    it explicitly, and only do so for the operator-configured self-hosted base.
+    The shared transport pins validated DNS answers, revalidates every redirect,
+    rejects link-local metadata destinations, and enforces request/response caps.
+    """
+    try:
+        from szl_provider_http import http_json as _provider_http_json
+    except Exception as exc:  # pragma: no cover - packaged runtime always includes it
+        raise RuntimeError("PROVIDER_HTTP_UNAVAILABLE") from exc
+
+    encoded = (None if body is None else json.dumps(
+        body, sort_keys=True, separators=(",", ":"), ensure_ascii=False
+    ).encode("utf-8"))
+    parsed, error = _provider_http_json(
+        url,
+        method="POST" if encoded is not None else "GET",
+        body=encoded,
+        timeout=timeout,
+        max_response_bytes=4 * 1024 * 1024,
+        max_redirects=2,
+        allow_private=allow_private,
+    )
+    if error:
+        raise RuntimeError(f"PROVIDER_HTTP:{error}")
+    return parsed if isinstance(parsed, dict) else {}
+
+
+def _served_model_ids(base: str, timeout: float = 2.0) -> list[str]:
+    try:
+        payload = _endpoint_json(
+            base.rstrip("/") + "/models", timeout=timeout, allow_private=True)
+    except Exception:
+        return []
+    rows = payload.get("data") or payload.get("models") or []
+    out: list[str] = []
+    if isinstance(rows, list):
+        for row in rows:
+            value = row.get("id") if isinstance(row, dict) else row
+            if isinstance(value, str) and value.strip():
+                out.append(value.strip())
+    return sorted(set(out), key=str.lower)
+
+
+def _model_origin(base: str) -> str:
+    from urllib.parse import urlsplit as _split, urlunsplit as _unsplit
+
+    parts = _split(base)
+    return _unsplit((parts.scheme, parts.netloc, "", "", "")).rstrip("/")
+
+
+def attest_local_model(profile_id: str, *, timeout: float = 2.0) -> dict[str, Any]:
+    """Attest one exact served tag without equating endpoint liveness to model load.
+
+    A matching OpenAI ``/models`` identity is mandatory.  When the endpoint is
+    Ollama-compatible, ``/api/show`` additionally binds family, quantization,
+    template, parameters, and the local GGUF blob digest.  A live tag is still
+    ``ARTIFACT_UNBOUND`` until a release manifest supplies and matches an expected
+    immutable blob digest; this deliberately prevents a same-name model swap.
+    """
+    models = forge_profile_model_map()
+    expected = models.get(profile_id)
+    base, is_local = _serving_base()
+    result: dict[str, Any] = {
+        "schema": "szl.forge.local-model-attestation/v1",
+        "profile_id": profile_id,
+        "expected_model": expected,
+        "base_url": base,
+        "local_endpoint": bool(is_local),
+        "observed_at_unix": int(time.time()),
+        "artifact_binding": "UNBOUND",
+    }
+    if not expected:
+        result.update({"state": "UNKNOWN_PROFILE", "available": False})
+        return result
+    if not is_local:
+        result.update({"state": "LOCAL_ENDPOINT_UNAVAILABLE", "available": False})
+        return result
+    served = _served_model_ids(base, timeout=timeout)
+    # Model identifiers are cryptographic identity inputs, not display labels.
+    # Case-folding here would let a differently named tag impersonate a profile.
+    exact = expected if expected in served else None
+    result["served_model_count"] = len(served)
+    result["served_models_sha256"] = hashlib.sha256(
+        json.dumps(served, separators=(",", ":"), ensure_ascii=False).encode("utf-8")
+    ).hexdigest()
+    if exact is None:
+        result.update({
+            "state": "MODEL_TAG_MISSING",
+            "available": False,
+            "honesty": "endpoint is live but the exact profile tag is absent",
+        })
+        return result
+
+    result.update({
+        "state": "TAG_ATTESTED_ARTIFACT_UNBOUND",
+        "available": True,
+        "served_model": exact,
+    })
+    try:
+        show = _endpoint_json(
+            _model_origin(base) + "/api/show", body={"model": exact},
+            timeout=timeout, allow_private=True)
+        details = show.get("details") if isinstance(show.get("details"), dict) else {}
+        modelfile = str(show.get("modelfile") or "")
+        layer_digests = sorted(set(
+            value.lower() for value in re.findall(
+                r"sha256[:-]([0-9a-fA-F]{64})(?![0-9a-fA-F])", modelfile)
+        ))
+        result["runtime"] = "ollama"
+        result["model_details"] = {
+            "format": details.get("format"),
+            "family": details.get("family"),
+            "parameter_size": details.get("parameter_size"),
+            "quantization_level": details.get("quantization_level"),
+        }
+        result["model_manifest_sha256"] = hashlib.sha256(json.dumps(
+            show, sort_keys=True, separators=(",", ":"), ensure_ascii=False
+        ).encode("utf-8")).hexdigest()
+        result["modelfile_sha256"] = hashlib.sha256(
+            modelfile.encode("utf-8")).hexdigest()
+        result["modelfile_layer_sha256"] = layer_digests
+        # Compatibility field remains singular only when the manifest really
+        # contains one layer.  Multiple layers must never be collapsed to the
+        # first regex match.
+        result["weights_blob_sha256"] = (
+            layer_digests[0] if len(layer_digests) == 1 else None)
+        for field in ("details", "model_info", "capabilities", "license"):
+            if field in show:
+                result[field + "_sha256"] = hashlib.sha256(json.dumps(
+                    show.get(field), sort_keys=True, separators=(",", ":"),
+                    ensure_ascii=False
+                ).encode("utf-8")).hexdigest()
+        for field in ("template", "parameters", "system"):
+            value = str(show.get(field) or "")
+            result[field + "_sha256"] = hashlib.sha256(value.encode("utf-8")).hexdigest()
+        try:
+            tags = _endpoint_json(
+                _model_origin(base) + "/api/tags", timeout=timeout,
+                allow_private=True)
+            rows = tags.get("models") if isinstance(tags.get("models"), list) else []
+            tag_row = next((row for row in rows if isinstance(row, dict) and (
+                row.get("name") == exact or row.get("model") == exact)), None)
+            if tag_row is not None:
+                result["tag_manifest_sha256"] = hashlib.sha256(json.dumps(
+                    tag_row, sort_keys=True, separators=(",", ":"),
+                    ensure_ascii=False
+                ).encode("utf-8")).hexdigest()
+                runtime_digest = tag_row.get("digest")
+                result["runtime_model_digest"] = (
+                    runtime_digest.lower()
+                    if isinstance(runtime_digest, str)
+                    and re.fullmatch(r"[0-9a-fA-F]{64}", runtime_digest)
+                    else None
+                )
+            else:
+                result["tag_manifest_state"] = "EXACT_TAG_NOT_IN_OLLAMA_TAGS"
+        except Exception as exc:
+            result["tag_manifest_state"] = "UNAVAILABLE"
+            result["tag_manifest_error_type"] = type(exc).__name__
+    except Exception as exc:
+        result["runtime"] = "openai-compatible"
+        result["show_state"] = "UNAVAILABLE"
+        result["show_error_type"] = type(exc).__name__
+    result["attestation_sha256"] = hashlib.sha256(
+        json.dumps(result, sort_keys=True, separators=(",", ":"),
+                   ensure_ascii=False).encode("utf-8")
+    ).hexdigest()
+    return result
+
+
+def forge_profile_runtime_status() -> dict[str, Any]:
+    """Shallow exact-tag inventory for status/UI surfaces (one /models read)."""
+    base, is_local = _serving_base()
+    served = _served_model_ids(base) if is_local else []
+    exact_served = set(served)
+    profiles = {}
+    for profile, tag in forge_profile_model_map().items():
+        actual = tag if tag in exact_served else None
+        profiles[profile] = {
+            "expected_model": tag,
+            "available": actual is not None,
+            "served_model": actual,
+            "state": ("EXACT_TAG_OBSERVED_ARTIFACT_UNBOUND" if actual is not None
+                      else "MODEL_TAG_MISSING" if is_local
+                      else "LOCAL_ENDPOINT_UNAVAILABLE"),
+            "separate_profile_weights_claimed": profile in {
+                "ReceiptAgent-v1", "BrainNavigator-v1"},
+        }
+    return {
+        "schema": "szl.forge.profile-runtime-status/v1",
+        "local_endpoint": bool(is_local),
+        "base_url": base,
+        "served_model_count": len(served),
+        "profiles": profiles,
+        "honesty": ("exact tag observation is not release-artifact identity; turn-level "
+                    "attestation remains authoritative"),
+    }
+
+
 def _serving_base_selftest() -> dict:
     """No-live-endpoint self-test for the #324 serving resolver (Zero-Bandaid).
 
@@ -852,6 +1098,18 @@ def has_inference_credential() -> bool:
     return bool(_resolve_hf_token()) or any(_resolve_provider_keys().values())
 
 
+def inference_backend_ready() -> bool:
+    """True when either a reachable local backend or remote credential is usable.
+
+    A local Ollama/LM Studio-style endpoint may intentionally require no API key.
+    This is distinct from :func:`has_inference_credential`: it never relabels a
+    no-key local service as credentialed, and an unreachable local URL does not
+    make the remote fallback live without a real remote credential.
+    """
+    _base, is_local = _serving_base()
+    return bool(is_local or has_inference_credential())
+
+
 def honest_stub_text(user_msg: str, decision: dict[str, Any]) -> str:
     """Deterministic, CLEARLY-LABELED stub. NEVER a fabricated model answer.
 
@@ -861,25 +1119,27 @@ def honest_stub_text(user_msg: str, decision: dict[str, Any]) -> str:
     """
     snippet = (user_msg or "").strip().replace("\n", " ")[:160]
     return (
-        "**[deterministic stub \u2014 inference token not yet set]**\n\n"
+        "**[deterministic stub \u2014 no usable inference backend]**\n\n"
         "a11oy.code received your request"
         + (f" (\u201c{snippet}\u201d)" if snippet else "")
         + f" and routed it to tier **{decision.get('tier')}** \u2192 model "
         f"`{decision.get('model')}` (license {decision.get('license_class')}). "
         "The PURIQ \u039b-gate, tier selection and the signed Khipu receipt below are "
-        "REAL deterministic math. The **model completion itself is unavailable** because no "
-        "inference credential is configured on this Space \u2014 so no answer is fabricated "
+        "REAL deterministic math. The **model completion itself is unavailable** because "
+        "neither a reachable local endpoint nor a credentialed remote provider is available "
+        "\u2014 so no answer is fabricated "
         "(Zero-Bandaid Law).\n\n"
         "_To enable live generation, paste a valid token into the Space secret_ `HF_TOKEN` "
         "_(Settings \u2192 Variables and secrets). Generation then goes live instantly \u2014 no redeploy._"
     )
 
 
-async def _call_model_stream(client: httpx.AsyncClient, model: str, payload: dict[str, Any]
+async def _call_model_stream(client: httpx.AsyncClient, model: str, payload: dict[str, Any],
+                             *, local_model: str | None = None
                              ) -> AsyncGenerator[bytes, None]:
     base, is_local = _serving_base()  # #324: serve local when reachable, else router
     body = dict(payload)
-    body["model"] = _map_model_for_local(model) if is_local else model
+    body["model"] = (local_model or _map_model_for_local(model)) if is_local else model
     body["stream"] = True
     async with client.stream("POST", f"{base}/chat/completions",
                              headers=_inference_headers(is_local), json=body, timeout=120.0) as resp:
@@ -891,10 +1151,11 @@ async def _call_model_stream(client: httpx.AsyncClient, model: str, payload: dic
                 yield (line + "\n").encode()
 
 
-async def _call_model(client: httpx.AsyncClient, model: str, payload: dict[str, Any]) -> dict[str, Any]:
+async def _call_model(client: httpx.AsyncClient, model: str, payload: dict[str, Any],
+                      *, local_model: str | None = None) -> dict[str, Any]:
     base, is_local = _serving_base()  # #324: serve local when reachable, else router
     body = dict(payload)
-    body["model"] = _map_model_for_local(model) if is_local else model
+    body["model"] = (local_model or _map_model_for_local(model)) if is_local else model
     body["stream"] = False
     resp = await client.post(f"{base}/chat/completions",
                              headers=_inference_headers(is_local), json=body, timeout=120.0)
@@ -906,19 +1167,21 @@ async def _call_model(client: httpx.AsyncClient, model: str, payload: dict[str,
 async def agent_model_complete(messages: list[dict], **kw) -> dict[str, Any]:
     """model_complete callable injected into the agent loop's FINALIZE step.
 
-    If a real inference credential is present, calls the live model (resilient
-    fallback walk). Otherwise returns the CLEARLY-LABELED deterministic stub —
-    the agentic control-flow already ran for real (Zero-Bandaid Law)."""
-    if not has_inference_credential():
+    If a reachable local endpoint or credentialed remote provider is available,
+    calls the live model (resilient fallback walk). Otherwise returns the
+    CLEARLY-LABELED deterministic stub — the agentic control-flow already ran
+    for real (Zero-Bandaid Law)."""
+    if not inference_backend_ready():
         last = next((m.get("content") for m in reversed(messages)
                      if m.get("role") == "user"), "")
         snippet = (last if isinstance(last, str) else json.dumps(last)).strip()[:160]
         stub_text = (
-            "**[deterministic stub — inference token not yet set]**\n\n"
+            "**[deterministic stub — no usable inference backend]**\n\n"
             "The a11oy Code agent's governed control-flow (plan DAG, per-step Λ-gate, "
             "PURIQ gate, typed evidence, signed Khipu receipts) executed FOR REAL. The "
-            "model-authored synthesis is unavailable because no inference credential is "
-            f"configured on this Space (set the secret {_code_secret_name()}), so no answer "
+            "model-authored synthesis is unavailable because neither a reachable local "
+            f"endpoint nor a credentialed remote provider (secret {_code_secret_name()}) "
+            "is available, so no answer "
             "is fabricated (Zero-Bandaid Law)."
             + (f" Request: \u201c{snippet}\u201d." if snippet else ""))
         out = {"text": stub_text, "model": "deterministic-stub", "stub": True}
@@ -932,17 +1195,67 @@ async def agent_model_complete(messages: list[dict], **kw) -> dict[str, Any]:
                "temperature": kw.get("temperature", 0.4)}
     candidates = [decision["model"], *decision.get("fallbacks", [])]
     _, is_local = _serving_base()  # honest sovereign posture for the receipt
+    local_profile = kw.get("local_profile")
+    local_model = None
+    model_attestation = None
+    if is_local and isinstance(local_profile, str) and local_profile:
+        local_model = forge_profile_model_map().get(local_profile)
+        model_attestation = attest_local_model(local_profile)
+        if not model_attestation.get("available"):
+            honesty = (
+                "exact Forge profile model is not loaded; refusing to relabel or use a "
+                "different local model"
+            )
+            out = {
+                "text": None,
+                "model": local_model or "unavailable",
+                "stub": True,
+                "honesty": honesty,
+                "model_attestation": model_attestation,
+            }
+            rcpt = _emit_turn_receipt(honesty, out["model"], True, True)
+            if rcpt is not None:
+                out["energy_receipt"] = rcpt
+            return out
     try:
-        data, model_used = await _call_model_resilient(client, candidates, payload)
+        if local_model:
+            data, model_used = await _call_model_resilient(
+                client, candidates, payload, local_model=local_model)
+        else:
+            data, model_used = await _call_model_resilient(client, candidates, payload)
+        if local_model and model_attestation is not None:
+            attested_tag = model_attestation.get("served_model")
+            if model_used != attested_tag:
+                honesty = (
+                    "model response identity did not exactly match the case-sensitive "
+                    "attested served tag; refusing the response"
+                )
+                out = {
+                    "text": None,
+                    "model": model_used,
+                    "stub": True,
+                    "honesty": honesty,
+                    "model_identity_state": "RESPONSE_TAG_MISMATCH",
+                    "attested_served_model": attested_tag,
+                    "model_attestation": model_attestation,
+                }
+                rcpt = _emit_turn_receipt(honesty, model_used, is_local, True)
+                if rcpt is not None:
+                    out["energy_receipt"] = rcpt
+                return out
         text = (data.get("choices", [{}])[0].get("message", {}) or {}).get("content", "") or ""
-        out = {"text": text, "model": model_used, "stub": False}
+        out = {"text": text, "model": model_used, "stub": False,
+               "model_attestation": model_attestation,
+               "model_identity_state": (
+                   "EXACT_ATTESTED_TAG" if local_model else "PROVIDER_REPORTED")}
         rcpt = _emit_turn_receipt(text, model_used, is_local, False)
         if rcpt is not None:
             out["energy_receipt"] = rcpt
         return out
     except Exception as exc:
         err_text = f"[honest error: live model call failed: {str(exc)[:200]}]"
-        out = {"text": err_text, "model": "error", "stub": True}
+        out = {"text": err_text, "model": "error", "stub": True,
+               "model_attestation": model_attestation}
         rcpt = _emit_turn_receipt(err_text, "error", is_local, True)
         if rcpt is not None:
             out["energy_receipt"] = rcpt
@@ -1075,8 +1388,120 @@ def _agent_rag_query(q: str, **kw) -> dict[str, Any]:
     return _orgrag.query(q, k=kw.get("k", 6), emit_receipt=khipu_emit)
 
 
+def agent_rag_context(q: str, *, k: int = 6) -> dict[str, Any]:
+    """Return evidence-bound Brain handles for a governed navigator model.
+
+    Node content remains in the controller.  The model receives only handles and
+    synthetic metadata, matching the Khipu model contract.  The API response can
+    independently resolve each selected handle against the evidence-set digest.
+    """
+    raw = _agent_rag_query(q, k=max(1, min(int(k), 12)))
+    chunks = raw.get("chunks") if isinstance(raw, dict) else []
+    chunks = chunks if isinstance(chunks, list) else []
+    handles: list[dict[str, Any]] = []
+    evidence: list[dict[str, Any]] = []
+    for chunk in chunks:
+        if not isinstance(chunk, dict):
+            continue
+        ev = chunk.get("evidence") if isinstance(chunk.get("evidence"), dict) else {}
+        handle = {
+            "nodeId": chunk.get("node_id"),
+            "chunkId": chunk.get("chunk_id"),
+            "title": chunk.get("title"),
+            "repo": chunk.get("repo"),
+            "path": chunk.get("path"),
+            "corpus": chunk.get("corpus"),
+            "lambda": chunk.get("lambda"),
+            "scores": chunk.get("scores"),
+            "sha256": chunk.get("sha256"),
+        }
+        handles.append(handle)
+        evidence.append({
+            "node_id": chunk.get("node_id"),
+            "chunk_id": chunk.get("chunk_id"),
+            "sha256": chunk.get("sha256"),
+            "path": ev.get("path") or chunk.get("path"),
+            "source": ev.get("source") or chunk.get("source"),
+            "citation": ev.get("citation"),
+        })
+    evidence_set = raw.get("evidence_set") if isinstance(raw, dict) else None
+    if not isinstance(evidence_set, list):
+        evidence_set = evidence
+
+    def _membership_row(row: Any, *, handle: bool) -> tuple[Any, Any, Any] | None:
+        if not isinstance(row, dict):
+            return None
+        node_id = row.get("nodeId") if handle else row.get("node_id")
+        chunk_id = row.get("chunkId") if handle else row.get("chunk_id")
+        digest = row.get("sha256")
+        if not all(isinstance(value, str) and value for value in (
+                node_id, chunk_id, digest)):
+            return None
+        if re.fullmatch(r"[0-9a-f]{64}", digest) is None:
+            return None
+        return node_id, chunk_id, digest
+
+    handle_members = [_membership_row(row, handle=True) for row in handles]
+    evidence_members = [_membership_row(row, handle=False) for row in evidence_set]
+    membership_rows_valid = (
+        all(row is not None for row in handle_members)
+        and all(row is not None for row in evidence_members)
+    )
+    handle_member_set = {row for row in handle_members if row is not None}
+    evidence_member_set = {row for row in evidence_members if row is not None}
+    handle_evidence_set_equivalent = (
+        membership_rows_valid
+        and len(handle_members) == len(handle_member_set)
+        and len(evidence_members) == len(evidence_member_set)
+        and handle_member_set == evidence_member_set
+    )
+    computed_evidence_sha = hashlib.sha256(json.dumps(
+        evidence_set, sort_keys=True, separators=(",", ":"), ensure_ascii=False
+    ).encode("utf-8")).hexdigest()
+    raw_evidence_sha = raw.get("evidence_set_sha256") if isinstance(raw, dict) else None
+    raw_digest_present = (
+        isinstance(raw_evidence_sha, str)
+        and re.fullmatch(r"[0-9a-f]{64}", raw_evidence_sha) is not None
+    )
+    evidence_digest_matches = (
+        not raw_digest_present or raw_evidence_sha == computed_evidence_sha
+    )
+    evidence_sha = raw_evidence_sha if raw_digest_present else computed_evidence_sha
+    handles_sha = hashlib.sha256(json.dumps(
+        handles, sort_keys=True, separators=(",", ":"), ensure_ascii=False
+    ).encode("utf-8")).hexdigest()
+    ready = (bool(raw.get("ok")) and bool(handles)
+             and not bool(raw.get("i_dont_know")) and evidence_digest_matches
+             and handle_evidence_set_equivalent)
+    return {
+        "schema": "szl.brain.navigator-context/v1",
+        "state": (
+            "GROUNDED_HANDLES_READY" if ready
+            else "ABSTAIN_EVIDENCE_DIGEST_CONFLICT" if not evidence_digest_matches
+            else "ABSTAIN_HANDLE_EVIDENCE_SET_MISMATCH"
+            if not handle_evidence_set_equivalent
+            else "ABSTAIN_NO_GROUNDED_HANDLES"
+        ),
+        "ready": ready,
+        "content_access": "HANDLES_ONLY",
+        "query_sha256": hashlib.sha256((q or "").encode("utf-8")).hexdigest(),
+        "handles": handles,
+        "evidence": evidence_set,
+        "evidence_set_sha256": evidence_sha,
+        "evidence_digest_matches": evidence_digest_matches,
+        "handle_evidence_set_equivalent": handle_evidence_set_equivalent,
+        "handles_sha256": handles_sha,
+        "grounded_count": len(handles),
+        "lambda_floor": raw.get("lambda_floor"),
+        "dense_used": raw.get("dense_used"),
+        "khipu_hash": raw.get("khipu_hash"),
+        "honesty": raw.get("honest_note") or raw.get("honest_error"),
+    }
+
+
 async def _call_model_resilient(
-    client: httpx.AsyncClient, models: list[str], payload: dict[str, Any]
+    client: httpx.AsyncClient, models: list[str], payload: dict[str, Any],
+    *, local_model: str | None = None
 ) -> tuple[dict[str, Any], str]:
     """Bounded fallback walk over [primary, *fallbacks]. Returns (response, model_used).
     On rate-limit / unavailable-model / provider errors it advances to the next
@@ -1089,8 +1514,17 @@ async def _call_model_resilient(
             continue
         seen.add(m)
         try:
-            data = await _call_model(client, m, payload)
-            return data, m
+            if local_model:
+                data = await _call_model(client, m, payload, local_model=local_model)
+            else:
+                data = await _call_model(client, m, payload)
+            observed = data.get("model") if isinstance(data, dict) else None
+            if isinstance(observed, str) and observed.strip():
+                model_used = observed.strip()
+            else:
+                _base, is_local = _serving_base()
+                model_used = (local_model or _map_model_for_local(m)) if is_local else m
+            return data, model_used
         except Exception as exc:  # provider 4xx/5xx, timeout, etc.
             last_exc = exc
             _METRICS["router_fallbacks_total"] = _METRICS.get("router_fallbacks_total", 0) + 1
@@ -1911,7 +2345,7 @@ async def agent_status() -> JSONResponse:
         "guards": {"max_steps": _agent.MAX_STEPS,
                    "max_reflect_depth": _agent.MAX_REFLECT_DEPTH,
                    "lambda_floor": _agent.LAMBDA_FLOOR},
-        "mode": "live" if has_inference_credential() else "deterministic_stub",
+        "mode": "live" if inference_backend_ready() else "deterministic_stub",
         "token_secret": _code_secret_name(),
         "recent_reflections": _agent.recent_reflections(limit=10),
     })
@@ -2384,13 +2818,14 @@ async def chat_stream(request: Request):
             return
 
         # ----------------------------------------------------------------
-        # HONEST-STUB BRANCH: if there is NO inference credential, do NOT
+        # HONEST-STUB BRANCH: if there is no reachable local backend and no
+        # credentialed remote backend, do NOT
         # error out and do NOT fabricate. Stream a clearly-labeled stub plus
         # the real signed receipt, then finish cleanly. This keeps the tab
         # fully operational (routing + Lambda + receipt) while being honest
-        # that the model text is unavailable until a token is pasted.
+        # that the model text is unavailable until a backend becomes usable.
         # ----------------------------------------------------------------
-        if not has_inference_credential():
+        if not inference_backend_ready():
             stub = honest_stub_text(user_msg, decision)
             for word in re.findall(r"\S+\s*", stub):
                 yield sse("token", {"text": word})

a11oy_frontier_page.py

@@ -47,9 +47,6 @@ from __future__ import annotations
 import pathlib
 import re
 
-from fastapi import FastAPI
-from fastapi.responses import HTMLResponse, JSONResponse
-
 DOCTRINE = {"version": "v11", "lambda": "Conjecture 1", "sovereign": False}
 
 # --------------------------------------------------------------------------- #
@@ -233,19 +230,23 @@ def _page_html(ns: str) -> str:
 <style>
   :root {{ --bg:#070b16; --panel:#101a2e; --ink:#e8eef7; --muted:#8aa0bd;
            --indigo:#4d8fcc; --terra:#c8643c; --gold:#d8a23c; --amber:#e8c074;
-           --green:#2fd07a; --warn:#c8893c; --violet:#9d7ad8; --red:#d8624a; }}
+           --green:#2fd07a; --warn:#c8893c; --violet:#9d7ad8; --red:#d8624a;
+           --honest-banner-h:3.1rem; }}
   * {{ box-sizing:border-box; }}
-  html,body {{ margin:0; min-height:100%; }}
+  html,body {{ margin:0; min-height:100%; max-width:100%; }}
+  html {{ overflow-x:clip; scroll-padding-top:calc(var(--honest-banner-h) + 1rem); }}
   body {{ font-family:ui-sans-serif,system-ui,Segoe UI,Roboto,sans-serif;
-          background:radial-gradient(1200px 700px at 70% -10%, #14213b, var(--bg));
-          color:var(--ink); }}
+           background:radial-gradient(1200px 700px at 70% -10%, #14213b, var(--bg));
+           color:var(--ink); overflow-x:hidden; }}
   /* Persistent, unmissable HONEST banner — top of every viewport. */
   #honest-banner {{ position:fixed; top:0; left:0; right:0; z-index:50;
     background:linear-gradient(90deg, rgba(77,143,204,.22), rgba(157,122,216,.18));
     border-bottom:1px solid rgba(232,192,116,.5);
     color:var(--amber); font-family:ui-monospace,monospace; font-size:.8rem;
     letter-spacing:.05em; padding:.55rem 1rem;
-    display:flex; align-items:center; gap:.6rem; backdrop-filter:blur(4px); }}
+    display:flex; align-items:flex-start; gap:.6rem; line-height:1.4;
+    backdrop-filter:blur(4px); overflow-wrap:anywhere; }}
+  #honest-banner > span:last-child {{ min-width:0; }}
   #honest-banner .dot {{ width:.6rem; height:.6rem; border-radius:50%;
     background:var(--amber); box-shadow:0 0 8px var(--amber); flex:0 0 auto; }}
   #honest-banner b {{ color:var(--gold); }}
@@ -253,7 +254,7 @@ def _page_html(ns: str) -> str:
   #scene {{ position:fixed; inset:0; z-index:0; }}
   /* Scrollable content layer above the canvas. */
   #wrap {{ position:relative; z-index:1; max-width:1180px; margin:0 auto;
-           padding:4.2rem 1.2rem 4rem; }}
+           padding:calc(var(--honest-banner-h) + 1.1rem) 1.2rem 4rem; min-width:0; }}
   .plaque {{ font-family:ui-monospace,monospace; font-size:.7rem; letter-spacing:.12em;
              color:var(--muted); text-transform:uppercase; }}
   .plaque b {{ color:var(--gold); }}
@@ -273,17 +274,18 @@ def _page_html(ns: str) -> str:
   .lg.modeled  {{ color:var(--amber);  border-color:rgba(232,192,116,.45); background:rgba(232,192,116,.1); }}
   .lg.roadmap  {{ color:var(--violet); border-color:rgba(157,122,216,.5);  background:rgba(157,122,216,.1); }}
   .lg.sample   {{ color:var(--indigo); border-color:rgba(77,143,204,.45);  background:rgba(77,143,204,.1); }}
-  #grid {{ display:grid; grid-template-columns:repeat(auto-fill,minmax(320px,1fr));
+  #grid {{ display:grid; grid-template-columns:repeat(auto-fill,minmax(min(100%,320px),1fr));
            gap:1rem; margin-top:1.2rem; }}
   .card {{ background:rgba(16,26,46,.84); border:1px solid #21304d; border-radius:14px;
            padding:1rem 1.1rem; box-shadow:0 18px 40px -28px #000;
            backdrop-filter:blur(6px); position:relative; overflow:hidden;
-           display:flex; flex-direction:column; gap:.55rem; }}
+            display:flex; flex-direction:column; gap:.55rem; min-width:0; }}
   .card::before {{ content:""; position:absolute; inset:0 0 auto 0; height:3px;
                    background:var(--edge,var(--indigo)); opacity:.85; }}
   .card h3 {{ margin:.15rem 0 0; font-family:ui-monospace,monospace; font-size:.96rem;
               color:var(--ink); display:flex; align-items:center; gap:.5rem;
-              justify-content:space-between; }}
+               justify-content:space-between; }}
+  .card h3 > span:first-child {{ min-width:0; overflow-wrap:anywhere; }}
   .card .cat {{ font-family:ui-monospace,monospace; font-size:.62rem; letter-spacing:.1em;
                 text-transform:uppercase; color:var(--muted); }}
   .card .stat {{ font-size:.82rem; color:var(--ink); line-height:1.4; }}
@@ -300,11 +302,70 @@ def _page_html(ns: str) -> str:
   /* 3D-surface list — compact honest pills, one per surface. */
   #surfaces-section {{ margin-top:1.6rem; }}
   #surfaces-section h2 {{ font-size:clamp(1.1rem,2vw,1.4rem); margin:.2rem 0 0; }}
-  #surfaces-list {{ display:flex; flex-wrap:wrap; gap:.5rem; margin-top:1rem; }}
-  .surface-pill {{ display:flex; align-items:center; gap:.5rem; background:rgba(16,26,46,.84);
-    border:1px solid #21304d; border-radius:10px; padding:.4rem .6rem;
-    font-family:ui-monospace,monospace; font-size:.72rem; color:var(--ink); }}
-  .surface-pill .sid {{ color:var(--muted); }}
+  .surface-tools {{ display:grid; grid-template-columns:minmax(0,1fr) minmax(220px,300px);
+    gap:.75rem; align-items:end; margin-top:1rem; min-width:0; }}
+  .surface-tabs {{ display:flex; gap:.4rem; overflow-x:auto; padding:.15rem .1rem .45rem;
+    min-width:0; scrollbar-width:thin; overscroll-behavior-inline:contain; }}
+  .surface-tab {{ border:1px solid #21304d; border-radius:999px; padding:.42rem .72rem;
+    color:var(--muted); background:rgba(7,12,23,.7); font:600 .66rem/1 ui-monospace,monospace;
+    letter-spacing:.04em; white-space:nowrap; cursor:pointer; }}
+  .surface-tab[aria-selected="true"] {{ color:var(--ink); border-color:var(--gold);
+    background:rgba(216,162,60,.14); }}
+  .surface-search {{ display:grid; gap:.35rem; min-width:0; color:var(--muted);
+    font:600 .62rem/1.2 ui-monospace,monospace; letter-spacing:.08em; text-transform:uppercase; }}
+  .surface-search input {{ width:100%; min-width:0; border:1px solid #2b3d60; border-radius:9px;
+    padding:.62rem .72rem; background:rgba(7,12,23,.86); color:var(--ink); font:inherit;
+    letter-spacing:0; text-transform:none; }}
+  #surfaces-list {{ display:grid; grid-template-columns:repeat(auto-fill,minmax(min(100%,250px),1fr));
+    gap:.6rem; margin-top:1rem; min-width:0; }}
+  .surface-pill {{ display:grid; grid-template-columns:minmax(0,1fr) auto; gap:.45rem .65rem;
+    align-items:start; min-width:0; background:rgba(16,26,46,.84); border:1px solid #21304d;
+    border-radius:11px; padding:.7rem .75rem; font-family:ui-monospace,monospace;
+    font-size:.72rem; color:var(--ink); text-decoration:none; overflow:hidden; }}
+  .surface-pill:hover {{ border-color:#3b537d; background:rgba(20,34,59,.92); }}
+  .surface-pill .surface-copy {{ min-width:0; display:grid; gap:.22rem; }}
+  .surface-pill .sid {{ color:var(--muted); overflow-wrap:anywhere; }}
+  .surface-pill .surface-title {{ min-width:0; line-height:1.35; overflow-wrap:anywhere; }}
+  .surface-pagination {{ display:flex; justify-content:space-between; align-items:center; gap:.75rem;
+    margin-top:.8rem; min-width:0; }}
+  .surface-pagination button {{ border:1px solid #2b3d60; border-radius:8px; padding:.46rem .72rem;
+    background:rgba(7,12,23,.82); color:var(--ink); font:600 .66rem/1 ui-monospace,monospace;
+    cursor:pointer; }}
+  .surface-pagination button:disabled {{ opacity:.38; cursor:not-allowed; }}
+  #surface-page-status {{ min-width:0; color:var(--muted); text-align:center;
+    font:500 .66rem/1.35 ui-monospace,monospace; overflow-wrap:anywhere; }}
+  .surface-empty {{ grid-column:1/-1; padding:1rem; border:1px dashed #2b3d60;
+    border-radius:10px; color:var(--muted); font:500 .72rem/1.5 ui-monospace,monospace; }}
+  #brain-section {{ margin-top:1.6rem; }}
+  .brain-shell {{ margin-top:.9rem; padding:1rem; border:1px solid #263858; border-radius:14px;
+    background:linear-gradient(145deg,rgba(16,26,46,.9),rgba(7,12,23,.88)); min-width:0; }}
+  .brain-head {{ display:flex; justify-content:space-between; gap:1rem; align-items:flex-start; }}
+  .brain-head > div {{ min-width:0; }}
+  .brain-head h2 {{ margin:0; font-size:clamp(1.1rem,2vw,1.4rem); }}
+  .brain-metrics {{ display:grid; grid-template-columns:repeat(6,minmax(0,1fr)); gap:.55rem;
+    margin-top:.9rem; }}
+  .brain-metric {{ min-width:0; padding:.7rem; border:1px solid #21304d; border-radius:9px;
+    background:rgba(7,12,23,.64); }}
+  .brain-value {{ display:block; color:var(--ink); font:700 clamp(.9rem,2vw,1.15rem)/1.2 ui-monospace,monospace;
+    overflow-wrap:anywhere; }}
+  .brain-key {{ display:block; margin-top:.28rem; color:var(--muted);
+    font:500 .58rem/1.35 ui-monospace,monospace; letter-spacing:.06em; text-transform:uppercase; }}
+  .brain-flow {{ display:grid; grid-template-columns:repeat(4,minmax(0,1fr)); gap:.45rem;
+    margin-top:.8rem; }}
+  .brain-step {{ min-width:0; padding:.6rem; border-radius:8px; border:1px solid rgba(77,143,204,.25);
+    color:#b9c9dd; font:500 .66rem/1.4 ui-monospace,monospace; overflow-wrap:anywhere; }}
+  .brain-step b {{ display:block; color:var(--indigo); margin-bottom:.18rem; }}
+  .brain-query {{ display:grid; grid-template-columns:minmax(0,1fr) auto; gap:.55rem; margin-top:.8rem; }}
+  .brain-query input {{ min-width:0; width:100%; border:1px solid #2b3d60; border-radius:9px;
+    padding:.7rem .75rem; background:#070c17; color:var(--ink); }}
+  .brain-query button {{ border:1px solid rgba(216,162,60,.55); border-radius:9px; padding:.65rem .85rem;
+    background:rgba(216,162,60,.12); color:var(--amber); font:600 .7rem/1 ui-monospace,monospace;
+    cursor:pointer; }}
+  #brain-result {{ margin-top:.65rem; min-width:0; padding:.65rem .75rem; border-radius:9px;
+    border:1px solid #1a2742; background:#070c17; color:#b9c9dd;
+    font:500 .68rem/1.5 ui-monospace,monospace; overflow-wrap:anywhere; }}
+  .brain-links {{ display:flex; flex-wrap:wrap; gap:.45rem .8rem; margin-top:.7rem; }}
+  .brain-links a {{ color:var(--green); font:500 .68rem/1.4 ui-monospace,monospace; text-underline-offset:3px; }}
   /* Per-tile persistent honest banner on non-MEASURED tiles. */
   .tile-banner {{ font-family:ui-monospace,monospace; font-size:.66rem; line-height:1.4;
                   border-radius:8px; padding:.4rem .55rem; letter-spacing:.03em; }}
@@ -323,10 +384,46 @@ def _page_html(ns: str) -> str:
   .meta b {{ color:var(--ink); }}
   .status-line {{ font-family:ui-monospace,monospace; font-size:.74rem; color:var(--muted); margin-top:1.4rem; }}
   .status-line.err {{ color:var(--warn); }}
+  :where(a,button,input):focus-visible {{ outline:2px solid var(--gold); outline-offset:3px; }}
   a.back {{ color:var(--muted); text-decoration:none; font-size:.8rem; }}
   a.orbital-link {{ color:var(--amber); text-decoration:none; }}
   a.orbital-link:hover {{ text-decoration:underline; }}
   noscript {{ color:var(--amber); display:block; padding:4rem 1.5rem; }}
+  @media (max-width:900px) {{
+    .brain-metrics {{ grid-template-columns:repeat(3,minmax(0,1fr)); }}
+  }}
+  @media (max-width:720px) {{
+    :root {{ --honest-banner-h:6.8rem; }}
+    #honest-banner {{ padding:.5rem .7rem; font-size:.66rem; letter-spacing:.025em; }}
+    #scene {{ opacity:.22; pointer-events:none; }}
+    #wrap {{ padding-left:.75rem; padding-right:.75rem; }}
+    .surface-tools {{ grid-template-columns:minmax(0,1fr); }}
+    .surface-tabs {{ width:100%; }}
+    #surfaces-list, #grid {{ grid-template-columns:minmax(0,1fr); }}
+    .surface-pill {{ padding:.65rem; }}
+    .surface-pagination {{ align-items:stretch; }}
+    .surface-pagination button {{ flex:0 0 auto; }}
+    #surface-page-status {{ align-self:center; }}
+    .brain-metrics {{ grid-template-columns:repeat(2,minmax(0,1fr)); }}
+    .brain-flow {{ grid-template-columns:repeat(2,minmax(0,1fr)); }}
+  }}
+  @media (max-width:420px) {{
+    :root {{ --honest-banner-h:7.4rem; }}
+    .plaque {{ font-size:.62rem; letter-spacing:.08em; }}
+    h1 {{ font-size:1.65rem; }}
+    #legend, #rollup {{ gap:.35rem; }}
+    .surface-pagination {{ display:grid; grid-template-columns:1fr 1fr; }}
+    #surface-page-status {{ grid-column:1/-1; grid-row:1; }}
+    .brain-head {{ display:grid; }}
+    .brain-metrics, .brain-flow {{ grid-template-columns:minmax(0,1fr); }}
+    .brain-query {{ grid-template-columns:minmax(0,1fr); }}
+  }}
+  @media (prefers-reduced-motion:reduce) {{
+    html {{ scroll-behavior:auto; }}
+    #scene {{ display:none; }}
+    *, *::before, *::after {{ animation-duration:.01ms !important; animation-iteration-count:1 !important;
+      transition-duration:.01ms !important; }}
+  }}
 </style></head>
 <body>
   <div id="honest-banner">
@@ -351,6 +448,48 @@ def _page_html(ns: str) -> str:
     </div>
     <div id="rollup"></div>
 
+    <section id="brain-section" aria-labelledby="brain-h">
+      <div class="brain-shell">
+        <div class="brain-head">
+          <div>
+            <div class="plaque">Evidence Brain / live governed reads</div>
+            <h2 id="brain-h">From indexed evidence to an answer or an honest abstention</h2>
+            <p class="sub">Counts come from the live Brain and corpus-admission APIs. Query round-trip
+              time is shown only after a real request. A dormant-to-active delta stays unavailable
+              until comparable before/after ingestion receipts exist.</p>
+          </div>
+          <span class="badge unavailable" id="brain-label">UNAVAILABLE</span>
+        </div>
+        <div class="brain-metrics" aria-label="Evidence Brain metrics">
+          <div class="brain-metric"><span class="brain-value" id="brain-node-count">--</span><span class="brain-key">Raw evidence nodes</span></div>
+          <div class="brain-metric"><span class="brain-value" id="brain-artifact-count">--</span><span class="brain-key">Distinct artifacts</span></div>
+          <div class="brain-metric"><span class="brain-value" id="brain-admitted-count">--</span><span class="brain-key">Governed corpus entries</span></div>
+          <div class="brain-metric"><span class="brain-value" id="brain-quarantine-count">--</span><span class="brain-key">Quarantined entries</span></div>
+          <div class="brain-metric"><span class="brain-value" id="brain-query-latency">NOT RUN</span><span class="brain-key">Measured client query RTT</span></div>
+          <div class="brain-metric"><span class="brain-value" id="brain-ingestion-delta">NOT MEASURED</span><span class="brain-key">Dormant to active delta</span></div>
+        </div>
+        <div class="brain-flow" aria-label="Source-grounded answer flow">
+          <div class="brain-step"><b>01 Query</b>bounded user question</div>
+          <div class="brain-step"><b>02 Retrieve</b>ranked graph evidence</div>
+          <div class="brain-step"><b>03 Ground</b>cited node identifiers</div>
+          <div class="brain-step"><b>04 Decide</b>MODELED answer or UNAVAILABLE</div>
+        </div>
+        <form class="brain-query" id="brain-query-form">
+          <label class="plaque" for="brain-query-input" style="position:absolute;left:-10000px">Evidence Brain question</label>
+          <input id="brain-query-input" name="q" type="search" autocomplete="off"
+            placeholder="Ask the graph; answers must cite retrieved node IDs"/>
+          <button type="submit">Run grounded query</button>
+        </form>
+        <div id="brain-result" role="status" aria-live="polite">Loading live Brain and corpus-admission status...</div>
+        <div class="brain-links">
+          <a href="/holographic#brainquery">Open Brain Query tab &rarr;</a>
+          <a href="/formulas">Inspect formula registry &rarr;</a>
+          <a href="/api/a11oy/v1/brain/stats">Raw Brain stats &rarr;</a>
+          <a href="/api/a11oy/v1/brain/health/corpus-sources">Corpus admission evidence &rarr;</a>
+        </div>
+      </div>
+    </section>
+
     <!-- 3D holographic surfaces — count + honest labels, from the SAME manifest the
          holographic showcase is built from (one source of truth: /frontier/surfaces). -->
     <div id="surfaces-section">
@@ -359,7 +498,20 @@ def _page_html(ns: str) -> str:
         <code>/frontier/surfaces</code> — the same machine-verifiable manifest that names each
         surface's asset and its honest label (parsed from the surface source, never upgraded).</p>
       <div id="surfaces-rollup"></div>
-      <div id="surfaces-list"></div>
+      <div class="surface-tools">
+        <div class="surface-tabs" id="surface-filters" role="tablist"
+          aria-label="Filter holographic surfaces by honest label"></div>
+        <label class="surface-search" for="surface-search">Find any surface
+          <input id="surface-search" type="search" autocomplete="off"
+            placeholder="Search ID or title"/>
+        </label>
+      </div>
+      <div id="surfaces-list" role="list" aria-label="Holographic surface catalog"></div>
+      <nav class="surface-pagination" id="surface-pagination" aria-label="Holographic surface pages">
+        <button id="surface-prev" type="button">&larr; Previous</button>
+        <span id="surface-page-status" aria-live="polite">Waiting for surface manifest...</span>
+        <button id="surface-next" type="button">Next &rarr;</button>
+      </nav>
       <div class="status-line" id="surfaces-status">fetching /frontier/surfaces…</div>
     </div>
 
@@ -378,6 +530,17 @@ import * as THREE from 'three';
 import {{ OrbitControls }} from 'three/addons/OrbitControls.js';
 
 const MANIFEST_EP = {manifest_ep!r};
+const BRAIN_STATS_EP = '/api/a11oy/v1/brain/stats';
+const BRAIN_CORPUS_EP = '/api/a11oy/v1/brain/health/corpus-sources';
+const BRAIN_ASK_EP = '/api/a11oy/v1/brain/ask';
+const banner = document.getElementById('honest-banner');
+function syncBannerOffset() {{
+  const height = banner ? Math.ceil(banner.getBoundingClientRect().height) : 0;
+  if (height > 0) document.documentElement.style.setProperty('--honest-banner-h', height + 'px');
+}}
+if ('ResizeObserver' in window && banner) new ResizeObserver(syncBannerOffset).observe(banner);
+addEventListener('resize', syncBannerOffset, {{passive:true}});
+syncBannerOffset();
 
 const LABEL_CLASS = {{
   MEASURED:'measured', MODELED:'modeled', ROADMAP:'roadmap',
@@ -394,19 +557,22 @@ const EDGE_HEX = {{
 
 function esc(s) {{ return String(s).replace(/[&<>"']/g, c =>
   ({{'&':'&amp;','<':'&lt;','>':'&gt;','"':'&quot;',"'":'&#39;'}}[c])); }}
-function cls(label) {{ return LABEL_CLASS[label] || 'sample'; }}
+function cls(label) {{ return LABEL_CLASS[label] || 'unavailable'; }}
 
 // ---- three.js holographic ecosystem constellation (r160, vendored, 0 CDN) ----
 const canvas = document.getElementById('scene');
 const renderer = new THREE.WebGLRenderer({{ canvas, antialias:true, alpha:true }});
-renderer.setPixelRatio(Math.min(devicePixelRatio, 2));
+const reducedMotion = matchMedia('(prefers-reduced-motion: reduce)');
+const compactCanvas = matchMedia('(max-width: 720px)');
+renderer.setPixelRatio(Math.min(devicePixelRatio, compactCanvas.matches ? 1 : 2));
 const scene = new THREE.Scene();
 const camera = new THREE.PerspectiveCamera(55, 1, 0.1, 2000);
 camera.position.set(0, 6, 60);
 const controls = new OrbitControls(camera, canvas);
 controls.enableDamping = true; controls.dampingFactor = 0.06;
 controls.enablePan = false; controls.enableZoom = false;
-controls.autoRotate = true; controls.autoRotateSpeed = 0.28;
+controls.autoRotate = !(reducedMotion.matches || compactCanvas.matches);
+controls.autoRotateSpeed = 0.28;
 
 scene.add(new THREE.AmbientLight(0x88aacc, 0.7));
 const key = new THREE.PointLight(0xffffff, 1.1); key.position.set(40, 50, 50); scene.add(key);
@@ -429,12 +595,29 @@ function resize() {{
 }}
 addEventListener('resize', resize); resize();
 
-(function loop() {{
-  requestAnimationFrame(loop);
+let animationFrame = 0;
+function renderFrame() {{
+  animationFrame = 0;
+  if (document.hidden || reducedMotion.matches || compactCanvas.matches) {{
+    renderer.render(scene, camera);
+    return;
+  }}
   controls.update();
   core.rotation.y += 0.0012; core.rotation.x += 0.0005;
   renderer.render(scene, camera);
-}})();
+  animationFrame = requestAnimationFrame(renderFrame);
+}}
+function applyMotionPolicy() {{
+  controls.autoRotate = !(reducedMotion.matches || compactCanvas.matches);
+  renderer.setPixelRatio(Math.min(devicePixelRatio, compactCanvas.matches ? 1 : 2));
+  if (animationFrame) cancelAnimationFrame(animationFrame);
+  animationFrame = 0;
+  renderFrame();
+}}
+reducedMotion.addEventListener?.('change', applyMotionPolicy);
+compactCanvas.addEventListener?.('change', applyMotionPolicy);
+document.addEventListener('visibilitychange', applyMotionPolicy);
+applyMotionPolicy();
 
 // Place capability tiles evenly on a ring around the core, colored by honest label.
 function drawConstellation(tiles) {{
@@ -520,6 +703,87 @@ function fail(msg) {{
   if (el) {{ el.className = 'status-line err'; el.textContent = msg; }}
 }}
 
+function setBrainMetric(id, value) {{
+  const el = document.getElementById(id);
+  if (el) el.textContent = value == null ? '--' : String(value);
+}}
+function setBrainLabel(label) {{
+  const honest = label || 'UNAVAILABLE';
+  const el = document.getElementById('brain-label');
+  if (el) {{ el.textContent = honest; el.className = 'badge ' + cls(honest); }}
+}}
+
+(async function loadEvidenceBrain() {{
+  const result = document.getElementById('brain-result');
+  try {{
+    const [statsResponse, corpusResponse] = await Promise.all([
+      fetch(BRAIN_STATS_EP, {{headers:{{Accept:'application/json'}}}}),
+      fetch(BRAIN_CORPUS_EP, {{headers:{{Accept:'application/json'}}}}),
+    ]);
+    if (!statsResponse.ok || !corpusResponse.ok) throw new Error(
+      'status endpoints ' + statsResponse.status + '/' + corpusResponse.status);
+    const stats = await statsResponse.json();
+    const corpus = await corpusResponse.json();
+    const counts = corpus?.summary?.counts || {{}};
+    const admitted = Object.values(counts).reduce((total, value) => total + (Number(value) || 0), 0);
+    setBrainMetric('brain-node-count', stats.node_count);
+    setBrainMetric('brain-artifact-count', stats.distinct_artifacts);
+    setBrainMetric('brain-admitted-count', admitted);
+    setBrainMetric('brain-quarantine-count', corpus?.summary?.quarantined_entries);
+    setBrainMetric('brain-ingestion-delta', 'NOT MEASURED');
+    setBrainLabel(stats.label);
+    result.textContent = 'Live status loaded. Brain counts are ' + (stats.label || 'UNAVAILABLE') +
+      '; corpus admission is ' + (corpus.label || 'UNAVAILABLE') +
+      '. Raw graph and governed-corpus counts are different contracts; no ingestion uplift is inferred.';
+  }} catch (error) {{
+    setBrainLabel('UNAVAILABLE');
+    result.textContent = 'Brain status unavailable: ' + error + '. No counts or ingestion delta fabricated.';
+  }}
+}})();
+
+document.getElementById('brain-query-form').addEventListener('submit', async event => {{
+  event.preventDefault();
+  const input = document.getElementById('brain-query-input');
+  const button = event.currentTarget.querySelector('button');
+  const result = document.getElementById('brain-result');
+  const q = input.value.trim();
+  if (!q) {{
+    result.textContent = 'Enter a non-empty question. No query was run and no latency was inferred.';
+    return;
+  }}
+  button.disabled = true;
+  result.textContent = 'Running a source-grounded Brain query...';
+  const started = performance.now();
+  try {{
+    const response = await fetch(BRAIN_ASK_EP + '?q=' + encodeURIComponent(q) + '&k=12',
+      {{headers:{{Accept:'application/json'}}}});
+    const payload = await response.json();
+    if (!response.ok) throw new Error('query ' + response.status);
+    const elapsed = Math.round(performance.now() - started);
+    setBrainMetric('brain-query-latency', elapsed + ' ms');
+    const answerLabel = payload.answer_label || 'UNAVAILABLE';
+    const cited = Array.isArray(payload.cited_node_ids) ? payload.cited_node_ids.slice(0, 12) : [];
+    const groundingCount = payload?.grounding_subgraph?.node_count ?? cited.length;
+    const prose = typeof payload.answer === 'string' && payload.answer.trim()
+      ? payload.answer.trim().slice(0, 600) : '';
+    setBrainLabel(answerLabel);
+    result.textContent = prose
+      ? '[' + answerLabel + '] ' + prose + ' | cited: ' + (cited.join(', ') || 'none') +
+        ' | measured client RTT: ' + elapsed + ' ms'
+      : '[' + answerLabel + '] Grounding returned ' + groundingCount + ' nodes (' +
+        (cited.join(', ') || 'no cited IDs') + '). No generated prose was available; nothing fabricated. ' +
+        'Measured client RTT: ' + elapsed + ' ms.';
+  }} catch (error) {{
+    const elapsed = Math.round(performance.now() - started);
+    setBrainMetric('brain-query-latency', elapsed + ' ms');
+    setBrainLabel('UNAVAILABLE');
+    result.textContent = 'Brain query unavailable after a measured ' + elapsed + ' ms: ' + error +
+      '. No answer fabricated.';
+  }} finally {{
+    button.disabled = false;
+  }}
+}});
+
 (async function load() {{
   try {{
     const r = await fetch(MANIFEST_EP, {{ headers:{{Accept:'application/json'}} }});
@@ -563,6 +827,93 @@ const SURF_CLASS = {{
 }};
 function surfCls(label) {{ return SURF_CLASS[label] || 'unavailable'; }}
 
+const SURFACE_PAGE_SIZE = 12;
+let allSurfaces = [];
+let activeSurfaceLabel = 'ALL';
+let surfaceQuery = '';
+let surfacePage = 0;
+
+function matchingSurfaces() {{
+  const needle = surfaceQuery.toLowerCase();
+  return allSurfaces.filter(surface => {{
+    const label = surface.label || 'UNAVAILABLE';
+    const labelMatches = activeSurfaceLabel === 'ALL' || label === activeSurfaceLabel;
+    const text = [surface.id, surface.title, surface.asset, label].join(' ').toLowerCase();
+    return labelMatches && (!needle || text.includes(needle));
+  }});
+}}
+
+function renderSurfaceTabs(labelCounts) {{
+  const labels = ['ALL', ...Object.keys(labelCounts)];
+  const tabs = document.getElementById('surface-filters');
+  tabs.innerHTML = labels.map((label, index) => {{
+    const count = label === 'ALL' ? allSurfaces.length : (labelCounts[label] || 0);
+    return `<button type="button" class="surface-tab" role="tab" id="surface-tab-${{index}}"`
+      + ` data-label="${{esc(label)}}" aria-selected="${{label === activeSurfaceLabel}}"`
+      + ` aria-controls="surfaces-list" tabindex="${{label === activeSurfaceLabel ? 0 : -1}}"`
+      + `>${{esc(label)}} ${{esc(count)}}</button>`;
+  }}).join('');
+  const tabButtons = [...tabs.querySelectorAll('[role="tab"]')];
+  tabButtons.forEach((tab, index) => {{
+    tab.addEventListener('click', () => {{
+      activeSurfaceLabel = tab.dataset.label || 'ALL';
+      surfacePage = 0;
+      renderSurfaceTabs(labelCounts);
+      renderSurfaceCatalog();
+    }});
+    tab.addEventListener('keydown', event => {{
+      let target = null;
+      if (event.key === 'ArrowRight') target = (index + 1) % tabButtons.length;
+      else if (event.key === 'ArrowLeft') target = (index - 1 + tabButtons.length) % tabButtons.length;
+      else if (event.key === 'Home') target = 0;
+      else if (event.key === 'End') target = tabButtons.length - 1;
+      if (target == null) return;
+      event.preventDefault();
+      tabButtons[target].click();
+      document.querySelectorAll('#surface-filters [role="tab"]')[target]?.focus();
+    }});
+  }});
+}}
+
+function renderSurfaceCatalog() {{
+  const filtered = matchingSurfaces();
+  const pageCount = Math.max(1, Math.ceil(filtered.length / SURFACE_PAGE_SIZE));
+  surfacePage = Math.min(surfacePage, pageCount - 1);
+  const start = surfacePage * SURFACE_PAGE_SIZE;
+  const visible = filtered.slice(start, start + SURFACE_PAGE_SIZE);
+  const list = document.getElementById('surfaces-list');
+  list.innerHTML = visible.length ? visible.map(surface => {{
+    const label = surface.label || 'UNAVAILABLE';
+    const target = '/holographic#' + encodeURIComponent(surface.id || '');
+    return `<a class="surface-pill" role="listitem" href="${{target}}"`
+      + ` title="${{esc(surface.asset || '')}}" aria-label="Open ${{esc(surface.title || surface.id || 'surface')}}; ${{esc(label)}}">`
+      + `<span class="surface-copy"><span class="sid">${{esc(surface.id || '')}}</span>`
+      + `<span class="surface-title">${{esc(surface.title || '')}}</span></span>`
+      + `<span class="badge ${{surfCls(label)}}">${{esc(label)}}</span></a>`;
+  }}).join('') : '<div class="surface-empty">No surface matches this exact label and search. No result fabricated.</div>';
+
+  const first = filtered.length ? start + 1 : 0;
+  const last = Math.min(start + visible.length, filtered.length);
+  document.getElementById('surface-page-status').textContent =
+    'showing ' + first + '-' + last + ' of ' + filtered.length +
+    ' matching / ' + allSurfaces.length + ' total | page ' + (surfacePage + 1) + '/' + pageCount;
+  document.getElementById('surface-prev').disabled = surfacePage === 0;
+  document.getElementById('surface-next').disabled = surfacePage >= pageCount - 1 || filtered.length === 0;
+}}
+
+document.getElementById('surface-search').addEventListener('input', event => {{
+  surfaceQuery = event.target.value.trim();
+  surfacePage = 0;
+  renderSurfaceCatalog();
+}});
+document.getElementById('surface-prev').addEventListener('click', () => {{
+  if (surfacePage > 0) {{ surfacePage -= 1; renderSurfaceCatalog(); }}
+}});
+document.getElementById('surface-next').addEventListener('click', () => {{
+  const count = matchingSurfaces().length;
+  if ((surfacePage + 1) * SURFACE_PAGE_SIZE < count) {{ surfacePage += 1; renderSurfaceCatalog(); }}
+}});
+
 (async function loadSurfaces() {{
   const statusEl = document.getElementById('surfaces-status');
   try {{
@@ -581,14 +932,10 @@ function surfCls(label) {{ return SURF_CLASS[label] || 'unavailable'; }}
     chips.push(`<span class="chip">labels valid: <b>${{esc(String(s.labels_valid))}}</b></span>`);
     document.getElementById('surfaces-rollup').innerHTML = chips.join('');
 
-    // one honest pill per surface: id · title · label badge
-    document.getElementById('surfaces-list').innerHTML = surfaces.map(su => {{
-      const label = su.label || 'UNAVAILABLE';
-      return `<span class="surface-pill" title="${{esc(su.asset || '')}}">`
-        + `<span class="sid">${{esc(su.id)}}</span>`
-        + `<span>${{esc(su.title || '')}}</span>`
-        + `<span class="badge ${{surfCls(label)}}">${{esc(label)}}</span></span>`;
-    }}).join('');
+    // retain every surface, then render a bounded honest page: id + title + label.
+    allSurfaces = surfaces;
+    renderSurfaceTabs(lc);
+    renderSurfaceCatalog();
 
     statusEl.className = 'status-line';
     statusEl.textContent = (m.ok === false)
@@ -596,6 +943,9 @@ function surfCls(label) {{ return SURF_CLASS[label] || 'unavailable'; }}
       : ('live · ' + esc(m.count ?? surfaces.length) + ' surfaces from ' + esc(SURFACES_EP)
          + ' · labels_valid=' + esc(String(s.labels_valid)));
   }} catch (e) {{
+    allSurfaces = [];
+    renderSurfaceTabs({{}});
+    renderSurfaceCatalog();
     statusEl.className = 'status-line err';
     statusEl.textContent = 'surfaces unavailable: ' + e + ' (nothing fabricated — raw data at ' + SURFACES_EP + ')';
   }}
@@ -604,16 +954,20 @@ function surfCls(label) {{ return SURF_CLASS[label] || 'unavailable'; }}
 </body></html>"""
 
 
-def register(app: FastAPI, ns: str = "a11oy") -> str:
+def register(app, ns: str = "a11oy") -> str:
     """Mount GET /frontier (HTML) + GET /api/<ns>/v1/frontier/page-manifest (JSON).
     ADDITIVE — registered before the SPA catch-all; touches no existing route."""
 
+    # Keep the pure manifest builders importable in bounded/offline evidence
+    # jobs where the web-serving dependency is intentionally absent.
+    from fastapi.responses import HTMLResponse, JSONResponse
+
     @app.get("/frontier", include_in_schema=False)
-    async def frontier_page() -> HTMLResponse:  # noqa: ANN202
+    async def frontier_page():  # noqa: ANN202
         return HTMLResponse(_page_html(ns))
 
     @app.get(f"/api/{ns}/v1/frontier/surfaces")
-    async def frontier_surfaces() -> JSONResponse:  # noqa: ANN202
+    async def frontier_surfaces():  # noqa: ANN202
         """Machine-verifiable manifest of every 3D frontier surface.
 
         id + title + honesty label (parsed from the surface source, verbatim) +
@@ -621,7 +975,7 @@ def register(app: FastAPI, ns: str = "a11oy") -> str:
         return JSONResponse(build_surfaces_manifest(ns))
 
     @app.get(f"/api/{ns}/v1/frontier/page-manifest", include_in_schema=False)
-    async def frontier_page_manifest() -> JSONResponse:  # noqa: ANN202
+    async def frontier_page_manifest():  # noqa: ANN202
         return JSONResponse({
             "section": "Frontier",
             "page": "/frontier",
@@ -667,8 +1021,35 @@ def _selftest() -> None:
     assert 'id="surfaces-list"' in html and 'id="surfaces-rollup"' in html, \
         "surfaces section markers missing"
     assert "loadSurfaces" in html, "surfaces client loader missing"
-
-    # 8) the manifest builder parses the live registry honestly
+    # 8) responsive catalog retains every fetched surface in memory while rendering a
+    # bounded, filterable page; its exact honesty labels remain the filter contract.
+    for marker in (
+        'id="surface-filters"', 'role="tablist"', 'id="surface-search"',
+        'id="surface-prev"', 'id="surface-next"', 'id="surface-page-status"',
+        "const SURFACE_PAGE_SIZE = 12", "allSurfaces = surfaces",
+        "filtered.slice(start, start + SURFACE_PAGE_SIZE)",
+        "'/holographic#' + encodeURIComponent", "ArrowRight", "ArrowLeft",
+    ):
+        assert marker in html, f"responsive surface catalog marker missing: {marker}"
+    for marker in (
+        "--honest-banner-h", "ResizeObserver", "overflow-x:clip",
+        "overflow-wrap:anywhere", "@media (max-width:720px)",
+        "@media (max-width:420px)", "prefers-reduced-motion:reduce",
+    ):
+        assert marker in html, f"responsive shell marker missing: {marker}"
+    # 9) the Evidence Brain only displays live reads and measured client RTT; it
+    # never promises a latency target or invents an ingestion uplift.
+    for marker in (
+        "/api/a11oy/v1/brain/stats",
+        "/api/a11oy/v1/brain/health/corpus-sources",
+        "/api/a11oy/v1/brain/ask",
+        'id="brain-query-form"', "performance.now()", "cited_node_ids",
+        "NOT MEASURED", 'href="/formulas"',
+    ):
+        assert marker in html, f"Evidence Brain marker missing: {marker}"
+    assert "answers in 2 seconds" not in html.lower(), "unmeasured latency promise found"
+
+    # 10) the manifest builder parses the live registry honestly
     man = build_surfaces_manifest("a11oy")
     assert man["ok"] is True, f"surfaces manifest not ok: {man.get('error')}"
     assert man["count"] == len(man["surfaces"]) and man["count"] > 0, "surface count mismatch"

a11oy_frontier_patch.py

@@ -37,17 +37,31 @@ async def _a11oy_frontier_health(request: Request):
 
 async def _a11oy_frontier_version(request: Request):
     import os as _os
+    from szl_release_identity import release_identity as _release_identity
+
+    identity = _release_identity()
+    release_tag = identity.get("release_tag")
+    release_assets_ready = bool(release_tag)
     return _FJSON({
-        "name": "a11oy", "version": "1.0.0",
-        "git_sha": _os.getenv("SZL_GIT_SHA", "90dd8e34efd7308f39c2230c78a4f1a67e4b0ba6"),
-        "hf_space_sha": _os.getenv("SZL_HF_SHA", "d9eedb5f0c0eda5bca3831f27c8f7f056059fabe"),
-        "build_time": _os.getenv("SZL_BUILD_TIME", "2026-06-03T00:00:00Z"),
-        "release_url": "https://github.com/szl-holdings/a11oy/releases/tag/v1.0.0",
+        **identity,
+        "git_sha": _os.getenv("SZL_GIT_SHA") or "UNKNOWN",
+        "hf_space_sha": _os.getenv("SZL_HF_SHA") or "UNKNOWN",
+        "build_time": _os.getenv("SZL_BUILD_TIME") or "UNKNOWN",
         "doctrine": _DOCTRINE, "kernel_commit": _KERNEL,
         "p6_status": "SIGNED_OFF", "p6_grader_score": "14/14",
         "verify": {
-            "cosign": "cosign verify ghcr.io/szl-holdings/a11oy:v1.0.0 --certificate-identity-regexp=szl-holdings",
-            "sbom": "https://github.com/szl-holdings/a11oy/releases/download/v1.0.0/a11oy-sbom.cdx.json",
+            "release_assets_status": "CONFIGURED_UNVERIFIED" if release_assets_ready else "PENDING_RELEASE",
+            "cosign": (
+                f"cosign verify ghcr.io/szl-holdings/a11oy:{release_tag} --certificate-identity-regexp=szl-holdings"
+                if release_assets_ready
+                else None
+            ),
+            "sbom": (
+                f"https://github.com/szl-holdings/a11oy/releases/download/{release_tag}/a11oy-sbom.cdx.json"
+                if release_assets_ready
+                else None
+            ),
+            "honest": "https://a-11-oy.com/api/a11oy/v1/honest",
         },
         # ADDITIVE (waveL Dev2): machine-readable release record of the waves'
         # shipped capabilities, HONEST labels. Canonical human record: CHANGELOG.md.

a11oy_hf_assets.py

@@ -159,11 +159,11 @@ def register(app, ns: str = "a11oy") -> str:
     base = f"/api/{ns}/v1/assets"
 
     @app.get(base + "/manifest")
-    async def _assets_manifest() -> "JSONResponse":  # noqa
+    async def _assets_manifest():  # noqa: ANN202
         return JSONResponse(manifest())
 
     @app.get(base + "/{key}")
-    async def _asset_one(key: str) -> "JSONResponse":  # noqa
+    async def _asset_one(key: str):  # noqa: ANN202
         return JSONResponse(asset_status(key))
 
     new = app.router.routes[n_before:]

a11oy_nemo_core.py

@@ -1,12 +1,12 @@
 """
 a11oy_nemo_core.py — SZL-NEMO CORE (Lane I1).
 
-SZL-Nemo is OUR sovereign, governed, self-improving agent model — delivered here
-as a LIVE SKELETON + architecture on a11oy. The HONEST framing, repeated in every
+SZL-Nemo is an SZL-governed recipe and orchestration runtime built on NVIDIA
+Nemotron 3 Nano 4B. The HONEST framing, repeated in every
 payload and on the tab, is:
 
-    "SZL-Nemo — built on an OPEN base (e.g. Qwen3-32B Apache-2.0 / GLM MIT),
-     governed & sovereign."
+    "SZL-Nemo — built on NVIDIA Nemotron 3 Nano 4B under its upstream license,
+     governed and served on SZL-controlled infrastructure when verified."
 
 NEVER claim: from-scratch training, 550B parameters, local Nemotron-Ultra, or a
 certification. We did NOT train a foundation model. OUR contribution is the
@@ -62,6 +62,9 @@ import math
 import os
 import threading
 import time
+import urllib.error
+import urllib.parse
+import urllib.request
 from datetime import datetime, timezone
 
 # ---------------------------------------------------------------------------
@@ -69,38 +72,46 @@ from datetime import datetime, timezone
 # governance/routing/self-improvement layer — NOT a from-scratch foundation model.
 # ---------------------------------------------------------------------------
 NEMO_NAME = "SZL-Nemo"
-NEMO_VERSION = "0.1.0-skeleton"
+NEMO_VERSION = "0.2.0-runtime-bound"
+NEMO_UPSTREAM_OLLAMA_MODEL = "nemotron-3-nano:4b"
+NEMO_SERVED_MODEL = os.environ.get("SZL_NEMO_MODEL", "szl-nemo:latest").strip()
+NEMO_OLLAMA_URL = os.environ.get(
+    "SZL_NEMO_OLLAMA_URL", "http://127.0.0.1:11436"
+).strip().rstrip("/")
+NEMO_EXPECTED_REGISTRY_MANIFEST_SHA256 = (
+    "6cc467f054393a55e98a74098abde0c762ffb6d1d8cd64becf30458f38886197"
+)
 NEMO_ARTIFACT = {
     "repo_id": "SZLHOLDINGS/szl-nemo",
     "url": "https://huggingface.co/SZLHOLDINGS/szl-nemo",
     "kind": "configuration-recipe",
     "weights_present": False,
-    "training_state": "NOT_PERFORMED",
+    "training_state": "NOT_FINE_TUNED",
+    "upstream_ollama_model": NEMO_UPSTREAM_OLLAMA_MODEL,
+    "expected_registry_manifest_sha256": NEMO_EXPECTED_REGISTRY_MANIFEST_SHA256,
     "honesty": (
         "The Hub artifact currently contains a model card and Modelfile recipe, "
         "not SZL-trained weights. It must not be described as a fine-tuned model."
     ),
 }
 
-# The honest base options (open weights, cited). We pick Qwen3-32B (Apache-2.0) as
-# the DEFAULT sovereign-local base because it fits the 2-GPU plan (TP=2). GLM (MIT)
-# is offered as an alternative. NEVER imply from-scratch / 550B.
+# Exact public recipe: NVIDIA Nemotron 3 Nano 4B through a content-bound Ollama
+# registry manifest. The prompt and governed runtime are SZL work; the weights are not.
 NEMO_BASE = {
-    "default_base": "Qwen3-32B",
-    "default_base_license": "Apache-2.0",
-    "default_base_url": "https://huggingface.co/Qwen/Qwen3-32B",
-    "alternatives": [
-        {"name": "GLM-4 (GLM family)", "license": "MIT",
-         "url": "https://huggingface.co/THUDM"},
-        {"name": "Qwen2.5-Coder-32B-Instruct", "license": "Apache-2.0",
-         "url": "https://huggingface.co/Qwen/Qwen2.5-Coder-32B-Instruct"},
-    ],
+    "default_base": "NVIDIA Nemotron 3 Nano 4B",
+    "default_base_tag": NEMO_UPSTREAM_OLLAMA_MODEL,
+    "default_base_license": "NVIDIA Nemotron Open Model License",
+    "default_base_url": "https://huggingface.co/nvidia/NVIDIA-Nemotron-3-Nano-4B-BF16",
+    "gguf_url": "https://huggingface.co/nvidia/NVIDIA-Nemotron-3-Nano-4B-GGUF",
+    "license_url": "https://huggingface.co/nvidia/NVIDIA-Nemotron-3-Nano-4B-BF16/blob/main/LICENSE",
+    "registry_manifest_sha256": NEMO_EXPECTED_REGISTRY_MANIFEST_SHA256,
+    "alternatives": [],
     "honest_framing": (
-        "SZL-Nemo is built ON an OPEN base (default Qwen3-32B, Apache-2.0). We did "
-        "NOT train a foundation model from scratch; there is NO 550B SZL model and "
-        "no local Nemotron-Ultra. OUR contribution is the governed-MoE domain-expert "
-        "router + MTP/speculative-decode default + Reflexion/Voyager self-improvement "
-        "+ signed-every-step receipts + Λ governance. Honest always."),
+        "SZL-Nemo is a governed Ollama recipe built ON NVIDIA Nemotron 3 Nano 4B. "
+        "SZL did NOT fine-tune or train these weights. OUR contribution is the "
+        "doctrine prompt, governed domain router, runtime identity binding, and "
+        "signed receipts. The exact upstream registry manifest must match before "
+        "the local tier can report READY."),
     "never_claim": ["from-scratch training", "550B parameters", "local Nemotron-Ultra",
                     "any certification (FedRAMP/IronBank/CMMC/ATO)"],
 }
@@ -158,13 +169,13 @@ DOCTRINE = {
 # (Leviathan et al. 2022 / Dev C #2). We mark the acceptance rate ILLUSTRATIVE
 # until the box emits real accept/draft counters → then it flips to MEASURED.
 MTP_DEFAULT = {
-    "enabled_default": True,
-    "draft_model": "Qwen2.5-Coder-1.5B-Instruct",
-    "target_model": "Qwen3-32B (open base)",
+    "enabled_default": False,
+    "draft_model": None,
+    "target_model": NEMO_UPSTREAM_OLLAMA_MODEL,
     "num_speculative_tokens_k": 4,
     "acceptance_rate_alpha": 0.8,   # ILLUSTRATIVE until box emits accept/draft counters
     "label_when_unmeasured": "ROADMAP",
-    "source": "speculative decoding (Leviathan et al. arXiv:2211.17192) + Dev C draft-model wiring",
+    "source": "speculative decoding (Leviathan et al. arXiv:2211.17192); not enabled on the verified Ollama path",
 }
 
 _LOCK = threading.RLock()
@@ -603,12 +614,149 @@ def mtp_view():
 
 
 # ---------------------------------------------------------------------------
-# INFER (skeleton) — a governed inference turn: route → pick serving tier → MTP
-# default → SIGNED receipt. App-layer skeleton: it does NOT run the open base
-# in-image (that is the sovereign-local box / cloud-NIM tier, ROADMAP/cloud). It
-# returns the GOVERNED PLAN + signed receipt, honestly labelled SKELETON.
+# LOCAL RUNTIME — fail closed to a loopback-only Ollama service.  Readiness binds
+# both the mutable upstream tag and the derived SZL recipe tag.  A reachable port
+# alone is not enough and a model's prose is never accepted as identity evidence.
 # ---------------------------------------------------------------------------
-def infer(query: str, top_k: int = 2, sign_fn=None):
+def _ollama_base_url() -> str:
+    parsed = urllib.parse.urlsplit(NEMO_OLLAMA_URL)
+    if parsed.scheme != "http" or parsed.username or parsed.password:
+        raise ValueError("SZL-Nemo requires a credential-free loopback HTTP URL")
+    if parsed.hostname not in {"127.0.0.1", "localhost", "::1"}:
+        raise ValueError("SZL-Nemo refuses non-loopback Ollama endpoints")
+    if parsed.path not in {"", "/"} or parsed.query or parsed.fragment:
+        raise ValueError("SZL-Nemo Ollama URL must not contain path/query/fragment")
+    return NEMO_OLLAMA_URL
+
+
+def _ollama_json(path: str, payload=None, timeout_s: float = 8.0):
+    base = _ollama_base_url()
+    body = None
+    headers = {"Accept": "application/json"}
+    method = "GET"
+    if payload is not None:
+        body = json.dumps(payload, sort_keys=True, separators=(",", ":")).encode("utf-8")
+        headers["Content-Type"] = "application/json"
+        method = "POST"
+    req = urllib.request.Request(base + path, data=body, method=method, headers=headers)
+    with urllib.request.urlopen(req, timeout=timeout_s) as response:
+        if response.status != 200:
+            raise RuntimeError("Ollama returned HTTP %s" % response.status)
+        raw = response.read(8 * 1024 * 1024 + 1)
+        if len(raw) > 8 * 1024 * 1024:
+            raise RuntimeError("Ollama response exceeded the bounded receipt limit")
+        value = json.loads(raw.decode("utf-8"))
+        if not isinstance(value, dict):
+            raise RuntimeError("Ollama returned a non-object response")
+        return value
+
+
+def _normal_model_tag(value: str) -> str:
+    value = (value or "").strip()
+    return value if ":" in value else value + ":latest"
+
+
+def nemo_runtime_status() -> dict:
+    expected = NEMO_EXPECTED_REGISTRY_MANIFEST_SHA256.lower()
+    try:
+        data = _ollama_json("/api/tags")
+        observed = {}
+        for item in data.get("models") or []:
+            if not isinstance(item, dict):
+                continue
+            name = _normal_model_tag(str(item.get("name") or item.get("model") or ""))
+            if name:
+                observed[name] = str(item.get("digest") or "").lower()
+        upstream = _normal_model_tag(NEMO_UPSTREAM_OLLAMA_MODEL)
+        served = _normal_model_tag(NEMO_SERVED_MODEL)
+        upstream_digest = observed.get(upstream)
+        served_digest = observed.get(served)
+        manifest_match = upstream_digest == expected
+        ready = bool(manifest_match and served_digest)
+        return {
+            "schema": "szl.nemo.runtime-status/v1",
+            "state": "READY" if ready else "UNAVAILABLE",
+            "transport": "OLLAMA_LOOPBACK",
+            "endpoint": _ollama_base_url(),
+            "served_model": served,
+            "served_model_digest": served_digest,
+            "upstream_model": upstream,
+            "upstream_registry_manifest_sha256": upstream_digest,
+            "expected_registry_manifest_sha256": expected,
+            "upstream_manifest_match": manifest_match,
+            "weights_origin": "NVIDIA",
+            "szl_fine_tuned": False,
+            "training_state": "NOT_FINE_TUNED",
+            "honesty": (
+                "Runtime and immutable upstream identity are verified; model quality "
+                "remains unestablished." if ready else
+                "Required exact upstream and derived recipe tags are not both verified."
+            ),
+        }
+    except Exception as exc:
+        return {
+            "schema": "szl.nemo.runtime-status/v1",
+            "state": "UNAVAILABLE",
+            "transport": "OLLAMA_LOOPBACK",
+            "endpoint": NEMO_OLLAMA_URL,
+            "served_model": _normal_model_tag(NEMO_SERVED_MODEL),
+            "served_model_digest": None,
+            "upstream_model": _normal_model_tag(NEMO_UPSTREAM_OLLAMA_MODEL),
+            "upstream_registry_manifest_sha256": None,
+            "expected_registry_manifest_sha256": expected,
+            "upstream_manifest_match": False,
+            "weights_origin": "NVIDIA",
+            "szl_fine_tuned": False,
+            "training_state": "NOT_FINE_TUNED",
+            "error_type": type(exc).__name__,
+            "honesty": "Local runtime is unavailable; no model output is fabricated.",
+        }
+
+
+def _live_nemo_generate(query: str, runtime: dict) -> dict:
+    if runtime.get("state") != "READY":
+        raise RuntimeError("SZL-Nemo runtime identity is not READY")
+    started = time.perf_counter_ns()
+    result = _ollama_json("/api/generate", {
+        "model": runtime["served_model"],
+        "prompt": query,
+        "stream": False,
+        # Nemotron is a reasoning model.  Ollama otherwise places its bounded
+        # generation in the separate `thinking` field and may exhaust the token
+        # budget before emitting `response`.  This public inference contract
+        # needs an answer, not a hidden reasoning trace, so disable thinking
+        # explicitly and continue to fail closed on an empty response.
+        "think": False,
+        "keep_alive": "5m",
+        "options": {"temperature": 0.2, "num_predict": 384},
+    }, timeout_s=180.0)
+    answer = result.get("response")
+    if not isinstance(answer, str) or not answer.strip():
+        raise RuntimeError("Ollama returned no answer text")
+    observed_model = _normal_model_tag(str(result.get("model") or ""))
+    if observed_model != runtime["served_model"]:
+        raise RuntimeError("served model identity mismatch")
+    return {
+        "state": "ANSWERED_UNVERIFIED",
+        "answer": answer.strip(),
+        "answer_sha256": hashlib.sha256(answer.strip().encode("utf-8")).hexdigest(),
+        "observed_model": observed_model,
+        "served_model_digest": runtime["served_model_digest"],
+        "upstream_registry_manifest_sha256": runtime["upstream_registry_manifest_sha256"],
+        "latency_ms": round((time.perf_counter_ns() - started) / 1_000_000, 3),
+        "eval_count": result.get("eval_count"),
+        "eval_duration_ns": result.get("eval_duration"),
+        "load_duration_ns": result.get("load_duration"),
+        "quality_state": "UNVERIFIED_MODEL_OUTPUT",
+        "training_state": "NOT_FINE_TUNED",
+    }
+
+
+# ---------------------------------------------------------------------------
+# INFER — plan by default for library callers; the HTTP endpoint explicitly asks
+# for execution.  A failed runtime stays UNAVAILABLE and never turns into demo text.
+# ---------------------------------------------------------------------------
+def infer(query: str, top_k: int = 2, sign_fn=None, execute: bool = False):
     route = govern_route(query, top_k=top_k, sign_fn=None)  # inner decision (re-signed below)
     primary = route["experts"][0] if route["experts"] else None
     serving = (primary or {}).get("serving_crossover", {})
@@ -621,18 +769,37 @@ def infer(query: str, top_k: int = 2, sign_fn=None):
         "routed_experts": route["experts_selected"],
         "primary_expert": (primary or {}).get("expert_id"),
         "serving_tier": tier_choice,
-        "serving_where": "sovereign-local (2-GPU)" if tier_choice == "small/local"
+        "serving_where": "sovereign-local Ollama" if tier_choice == "small/local"
                          else "cloud-NIM-frontier (Nemotron Ultra)",
         "mtp": mtp_view(),
         "overall_lambda_advisory": route["overall_lambda_advisory"],
+        "execution_requested": bool(execute),
+        "runtime": nemo_runtime_status(),
         "skeleton_note": (
-            "SKELETON — this returns the GOVERNED INFERENCE PLAN + a signed receipt. "
-            "SZL-Nemo does NOT run the open base in-image; generation happens on the "
-            "sovereign-local 2-GPU tier (ROADMAP→Forge) or the cloud-NIM tier. No "
-            "model output is fabricated."),
+            "Plan-only library call; set execute=true through the HTTP endpoint for "
+            "a fail-closed local generation. No model output is fabricated."),
         "tiers": tiers_view(),
         "ts_utc": datetime.now(timezone.utc).isoformat(),
     }
+    if execute:
+        try:
+            plan["generation"] = _live_nemo_generate(query, plan["runtime"])
+            plan["execution_state"] = "ANSWERED_UNVERIFIED"
+            plan["skeleton_note"] = (
+                "A real local model generated this output. Runtime identity and hashes "
+                "are measured; correctness and fine-tuning quality are not established."
+            )
+        except Exception as exc:
+            plan["generation"] = None
+            plan["execution_state"] = "UNAVAILABLE"
+            plan["runtime_error_type"] = type(exc).__name__
+            plan["skeleton_note"] = (
+                "Execution was requested but the exact runtime/model identity did not "
+                "complete. No fallback or demo answer was fabricated."
+            )
+    else:
+        plan["generation"] = None
+        plan["execution_state"] = "NOT_REQUESTED"
     # If the routed primary expert is CODE, this turn is on the code-emission
     # path: gate the intended diff through R1's restraint ladder and attach the
     # chosen rung + signed restraint receipt (honest PENDING if R1 not live yet).
@@ -656,8 +823,8 @@ def nemo_code(query: str, intent: str | None = None, intensity: str = "full",
     """A governed code-emission turn. `intent` is the natural-language description
     of the diff SZL-Nemo is about to write (defaults to the query). We route it
     through restraint BEFORE emitting, surface the rung + ceilings + lines-saved,
-    and sign the combined decision. SZL-Nemo does NOT run the open base in-image
-    (generation is the sovereign-local/cloud tier, ROADMAP/cloud) — this returns
+    and sign the combined decision. Code generation is not performed by this path;
+    this returns
     the GOVERNED, restraint-gated code PLAN + a signed receipt, honestly labelled."""
     task = (intent or query or "").strip()
     route = govern_route(query, top_k=2, sign_fn=None)
@@ -676,9 +843,8 @@ def nemo_code(query: str, intent: str | None = None, intensity: str = "full",
         "overall_lambda_advisory": route["overall_lambda_advisory"],
         "skeleton_note": (
             "GOVERNED CODE PLAN — the intended diff is routed through a11oy "
-            "Restraint (R1) BEFORE any code is emitted. SZL-Nemo does NOT run the "
-            "open base in-image; generation happens on the sovereign-local 2-GPU "
-            "tier (ROADMAP→Forge) or cloud-NIM tier. No code is fabricated here."),
+            "Restraint (R1) BEFORE any code is emitted. This endpoint creates a "
+            "governed plan only; no code is fabricated here."),
         "ponytail": _PONYTAIL,
         "doctrine": DOCTRINE,
         "ts_utc": datetime.now(timezone.utc).isoformat(),
@@ -695,56 +861,22 @@ def nemo_code(query: str, intent: str | None = None, intensity: str = "full",
 # sovereign:true ONLY from the live gpu_reachable probe (Dev C). cloud = false.
 # ---------------------------------------------------------------------------
 def tiers_view():
-    en = _energy()
-    sovereign = False
-    base_url = None
-    probe_note = "szl_energy_sovereign unavailable in-process; honest default not-sovereign."
-    if en is not None and hasattr(en, "_sovereign_state"):
-        try:
-            st = en._sovereign_state()
-            sovereign = bool(en._gpu_reachable(st)) if hasattr(en, "_gpu_reachable") else False
-            base_url = st.get("base_url")
-            probe_note = st.get("honest_note") or (
-                "live gpu_reachable probe: sovereign=%s" % sovereign)
-        except Exception as e:
-            probe_note = "probe error (%s); honest default not-sovereign." % type(e).__name__
-    # Model-aware honesty: the node being reachable (the sovereign brain, e.g.
-    # qwen2.5-coder:7b today) does NOT make the SZL-Nemo Qwen3-32B / 2-GPU tier live.
-    # Labelling a 32B that is served NOWHERE as MEASURED would be the half-state. This
-    # tier is MEASURED/sovereign ONLY when a 32B base is genuinely served; otherwise it
-    # is ROADMAP while honestly naming what IS served on the reachable node.
-    _served_model = (os.environ.get("SZL_LOCAL_LLM_MODEL")
-                     or os.environ.get("A11OY_LOCAL_LLM_MODEL") or "").strip()
-    _base_served = bool(sovereign) and ("32b" in _served_model.lower())
-    if _base_served:
-        _local_honesty = ("MEASURED — a live probe confirms the named 32B base is "
-                          "served on our GPU. NEVER claim local Nemotron-Ultra.")
-    elif sovereign:
-        _local_honesty = ("Node reachable now serving %r (the sovereign brain); the "
-                          "SZL-Nemo Qwen3-32B / 2-GPU serve is ROADMAP (founder-gated: "
-                          "one 7B-class GPU is reachable, no 32B / no vLLM TP=2 / 2nd "
-                          "card asleep) — see FORGE_SZL_NEMO.md. NEVER claim local "
-                          "Nemotron-Ultra." % (_served_model or "a small local model"))
-    else:
-        _local_honesty = ("Not reachable; honest ROADMAP. sovereign:true for this tier "
-                          "ONLY when a live probe confirms the 32B base is served on our "
-                          "GPU. NEVER claim local Nemotron-Ultra.")
+    runtime = nemo_runtime_status()
+    ready = runtime.get("state") == "READY"
     local_tier = {
         "tier_id": "sovereign-local",
-        "title": "Sovereign-Local (2-GPU)",
+        "title": "Sovereign-Local Nemotron Recipe",
         "where": "gpu",
-        "sovereign": _base_served,   # the 32B tier is sovereign ONLY when a 32B is actually served
-        "gpu_reachable": bool(sovereign),  # node reachability (the live sovereign brain) — honest
-        "node_serving_now": (_served_model or None),
+        "sovereign": ready,
+        "gpu_reachable": ready,
+        "node_serving_now": runtime.get("served_model") if ready else None,
         "base_model": NEMO_BASE["default_base"] + " (open base, " +
                       NEMO_BASE["default_base_license"] + ")",
-        "plan": ("2 GPUs (a-11-oy.com GPU + RTX 4000): vLLM TP=2 OR heterogeneous "
-                 "role-split (RTX 4000 = Auto-Review classifier + speculative draft + "
-                 "embeddings). Per NEMOTRON_TWO_GPU_PLAN.md."),
-        "base_url": base_url,
-        "probe_note": probe_note,
-        "label": "MEASURED" if _base_served else "ROADMAP",
-        "honesty": _local_honesty,
+        "plan": "Exact Ollama recipe on SZL-controlled local hardware.",
+        "base_url": runtime.get("endpoint"),
+        "probe_note": runtime,
+        "label": "MEASURED" if ready else "UNAVAILABLE",
+        "honesty": runtime.get("honesty"),
     }
     cloud_tier = {
         "tier_id": "cloud-NIM-frontier",
@@ -767,8 +899,8 @@ def tiers_view():
         "schema": "szl.nemo.tiers/v1",
         "model": NEMO_NAME,
         "tiers": [local_tier, cloud_tier],
-        "future": ("TIER 3 — when the supercomputer arrives, register Nemotron "
-                   "Ultra/Super as a LOCAL tier (same gateway; zero app rework)."),
+        "future": ("Larger local or cloud tiers remain separate candidates and must "
+                   "pass their own identity, license, quality, and runtime receipts."),
         "doctrine": ("sovereign:true only via live probe; measured > datasheet; "
                      "0 CDN; signed receipts; never commit a key."),
         "ts_utc": datetime.now(timezone.utc).isoformat(),
@@ -938,20 +1070,21 @@ def model_card():
     return {
         "schema": "szl.nemo.model_card/v1",
         "name": NEMO_NAME, "version": NEMO_VERSION,
-        "one_liner": ("SZL-Nemo — a sovereign, governed, self-improving AGENT model "
-                      "built ON an open base (default Qwen3-32B, Apache-2.0)."),
+        "one_liner": ("SZL-Nemo — a governed local recipe and orchestration runtime "
+                      "built on NVIDIA Nemotron 3 Nano 4B."),
         "base": NEMO_BASE,
         "hub_artifact": NEMO_ARTIFACT,
         "what_is_ours": [
             "Governed-MoE DOMAIN-EXPERT router (Λ-governed, signed every selection) — the differentiator.",
-            "MTP / speculative decoding as the inference default (app-layer; box ROADMAP→Forge).",
+            "Fail-closed loopback serving with exact upstream and derived-tag identity binding.",
             "Reflexion + Voyager + τ-bench self-improvement loop that SIGNS the measured delta.",
-            "Tiered sovereign-local (2-GPU) / cloud-NIM-frontier gateway with honest where/sovereign labels.",
+            "Tiered local/cloud gateway with honest where/sovereign labels.",
             "Tamper-evident DSSE ECDSA-P256 signed receipts on every governed step.",
         ],
         "what_is_NOT_ours": [
-            "The base weights (open, cited above — Apache-2.0 / MIT).",
+            "The base weights (NVIDIA, cited above, under the upstream model license).",
             "We did NOT train a foundation model from scratch.",
+            "The current SZL-Nemo recipe is NOT an SZL fine-tune.",
             "There is NO 550B SZL model and NO local Nemotron-Ultra (cloud tier only).",
         ],
         "experts": [{"id": e["id"], "title": e["title"], "desc": e["desc"]} for e in NEMO_EXPERTS],
@@ -960,8 +1093,11 @@ def model_card():
         "tiers": tiers_view(),
         "doctrine": DOCTRINE,
         "never_claim": NEMO_BASE["never_claim"],
+        "runtime": nemo_runtime_status(),
         "sources": {
-            "base_qwen3": NEMO_BASE["default_base_url"],
+            "base_nemotron": NEMO_BASE["default_base_url"],
+            "base_license": NEMO_BASE["license_url"],
+            "hub_recipe": NEMO_ARTIFACT["url"],
             "speculative_decoding": "https://arxiv.org/abs/2211.17192",
             "reflexion": "https://arxiv.org/abs/2303.11366",
             "voyager": "https://arxiv.org/abs/2305.16291",
@@ -1021,7 +1157,10 @@ def register(app, ns: str = "a11oy", sign_fn=None, verify_fn=None,
         if not q:
             return JSONResponse({"error": "missing 'query'"}, status_code=400)
         top_k = int(d.get("top_k", 2))
-        return JSONResponse(infer(q, top_k=top_k, sign_fn=sign_fn))
+        execute_value = str(d.get("execute", "true")).strip().lower()
+        execute = execute_value not in {"0", "false", "no", "off"}
+        return JSONResponse(infer(q, top_k=top_k, sign_fn=sign_fn,
+                                  execute=execute))
 
     async def _code_ep(request):
         if request.method == "POST":
@@ -1060,6 +1199,7 @@ def register(app, ns: str = "a11oy", sign_fn=None, verify_fn=None,
     async def _diag_ep(request):
         return JSONResponse({
             "status": "ok", "model": NEMO_NAME, "version": NEMO_VERSION,
+            "runtime": nemo_runtime_status(),
             "signer_present": sign_fn is not None,
             "signer_label": signer_label,
             "reuse": {

a11oy_operator_organ.py

@@ -119,14 +119,14 @@ def register(app, ns: str = "a11oy") -> str:
     n_before = len(app.router.routes)
 
     @app.get("/operator-organ")
-    async def _operator_page() -> Response:  # noqa
+    async def _operator_page():  # noqa: ANN202
         f = _PAGES / "operator_organ.html"
         if f.is_file():
             return FileResponse(str(f), media_type="text/html; charset=utf-8")
         return JSONResponse({"error": "operator organ page missing"}, status_code=404)
 
     @app.get("/operator-organ/app.js")
-    async def _operator_js() -> Response:  # noqa
+    async def _operator_js():  # noqa: ANN202
         f = _STATIC / "a11oy_operator_organ.js"
         if f.is_file():
             return FileResponse(
@@ -135,7 +135,7 @@ def register(app, ns: str = "a11oy") -> str:
         return JSONResponse({"error": "operator organ js missing"}, status_code=404)
 
     @app.get("/operator-organ/topology.json")
-    async def _operator_topology() -> Response:  # noqa
+    async def _operator_topology():  # noqa: ANN202
         try:
             topo = _build_topology(app)
             _CACHE["topo"] = topo
@@ -162,4 +162,4 @@ if __name__ == "__main__":
     class _Stub:
         class router:  # noqa
             routes = []
-    print(json.dumps(_build_topology(_Stub), indent=2))
+    print(json.dumps(_build_topology(_Stub), indent=2))

a11oy_org_rag.py

@@ -36,6 +36,12 @@ Build strategy (Series-A grade, honest):
     cannot finish synchronously in-image it runs on a receipted background tick
     (``refresh_tick`` / ``start_background_build``); status reports
     ``seed|building|full`` truthfully — never a fake "full".
+  * Every build writes a versioned staging generation. A single SQLite
+    transaction seals its digest/counts and swaps the active pointer; interrupted
+    builds remain invisible. Queries pin one active-generation read snapshot.
+  * The versioned M1 Brain decision ledger is searchable as metadata handles
+    (source URL + receipt + safety/quarantine) in a separate retrieval-only plane.
+    It grants exactly zero gradient/training authority.
 
 Graph model (our own original code; GraphRAG-shaped):
   nodes = {repo, file, symbol, hf_space, recipe}
@@ -80,6 +86,8 @@ import re
 import sqlite3
 import threading
 import time
+import uuid
+from pathlib import Path
 from typing import Any, Callable
 
 # Λ aggregator + receipts are reused from the shared brain / orchestrator.
@@ -225,6 +233,14 @@ def corpus_manifest() -> dict[str, Any]:
 
 
 _lock = threading.RLock()
+# Builders may run for minutes.  Queries must not take the builder lock; instead
+# they take this very short lock while pairing the immutable in-memory graph with
+# SQLite's active generation.  The SQLite read transaction then pins that
+# generation for the duration of the query.
+_SNAPSHOT_LOCK = threading.RLock()
+
+_M1_LEDGER_ENV = "A11OY_M1_BRAIN_LEDGER"
+_M1_LEDGER_DEFAULT = Path(__file__).resolve().parent / "model_release" / "m1" / "brain-ingest-ledger.jsonl"
 
 
 # --------------------------------------------------------------------------- #
@@ -279,6 +295,7 @@ class OrgGraph:
 
 # In-process graph cache (rebuilt by build_index).
 _GRAPH = OrgGraph()
+_REHYDRATE_ATTEMPTED = False
 _BUILD_META: dict[str, Any] = {"built": False, "ts": None, "repos": 0, "chunks": 0,
                                "honest_note": "index not built yet — call build_index"}
 
@@ -287,10 +304,12 @@ _BUILD_META: dict[str, Any] = {"built": False, "ts": None, "repos": 0, "chunks":
 # SQLite FTS5 + vector store
 # --------------------------------------------------------------------------- #
 def _db() -> sqlite3.Connection:
-    from pathlib import Path
     Path(RAG_DB_PATH).parent.mkdir(parents=True, exist_ok=True)
     conn = sqlite3.connect(RAG_DB_PATH, timeout=15)
     conn.row_factory = sqlite3.Row
+    conn.execute("PRAGMA busy_timeout=15000")
+    conn.execute("PRAGMA journal_mode=WAL")
+    conn.execute("PRAGMA synchronous=FULL")
     return conn
 
 
@@ -322,10 +341,380 @@ def _init_schema(conn: sqlite3.Connection) -> bool:
         "CREATE TABLE IF NOT EXISTS org_vectors("
         "chunk_id TEXT PRIMARY KEY, dim INTEGER, vec TEXT)"
     )
+    conn.execute(
+        "CREATE TABLE IF NOT EXISTS org_runtime_meta("
+        "key TEXT PRIMARY KEY, value TEXT NOT NULL)"
+    )
+    # Generation tables are additive so old installations can be opened and
+    # rebuilt without destructive migration.  A generation is immutable once it
+    # becomes ACTIVE; only the singleton pointer changes during publication.
+    conn.execute(
+        "CREATE TABLE IF NOT EXISTS org_generations("
+        "generation_id TEXT PRIMARY KEY, status TEXT NOT NULL, mode TEXT NOT NULL, "
+        "created_at REAL NOT NULL, activated_at REAL, chunk_count INTEGER NOT NULL DEFAULT 0, "
+        "vector_count INTEGER NOT NULL DEFAULT 0, brain_handle_count INTEGER NOT NULL DEFAULT 0, "
+        "graph_json TEXT, meta_json TEXT, digest_sha256 TEXT, failure_reason TEXT)"
+    )
+    conn.execute(
+        "CREATE TABLE IF NOT EXISTS org_active_generation("
+        "singleton INTEGER PRIMARY KEY CHECK(singleton=1), generation_id TEXT NOT NULL)"
+    )
+    if has_fts5:
+        conn.execute(
+            "CREATE VIRTUAL TABLE IF NOT EXISTS org_chunks_gen USING fts5("
+            "generation_id UNINDEXED, chunk_id UNINDEXED, node_id UNINDEXED, "
+            "repo UNINDEXED, path UNINDEXED, kind UNINDEXED, corpus UNINDEXED, "
+            "source UNINDEXED, title, body, sha256 UNINDEXED)"
+        )
+        conn.execute(
+            "CREATE VIRTUAL TABLE IF NOT EXISTS org_brain_handles_gen USING fts5("
+            "generation_id UNINDEXED, handle_id UNINDEXED, node_id UNINDEXED, "
+            "source UNINDEXED, source_url UNINDEXED, receipt_id UNINDEXED, "
+            "safety_decision UNINDEXED, training_decision UNINDEXED, "
+            "source_training_eligible UNINDEXED, title, metadata_text)"
+        )
+    else:
+        conn.execute(
+            "CREATE TABLE IF NOT EXISTS org_chunks_gen("
+            "generation_id TEXT, chunk_id TEXT, node_id TEXT, repo TEXT, path TEXT, "
+            "kind TEXT, corpus TEXT, source TEXT, title TEXT, body TEXT, sha256 TEXT)"
+        )
+        conn.execute(
+            "CREATE TABLE IF NOT EXISTS org_brain_handles_gen("
+            "generation_id TEXT, handle_id TEXT, node_id TEXT, source TEXT, "
+            "source_url TEXT, receipt_id TEXT, safety_decision TEXT, "
+            "training_decision TEXT, source_training_eligible TEXT, title TEXT, "
+            "metadata_text TEXT)"
+        )
+    conn.execute(
+        "CREATE TABLE IF NOT EXISTS org_vectors_gen("
+        "generation_id TEXT NOT NULL, chunk_id TEXT NOT NULL, dim INTEGER, vec TEXT, "
+        "PRIMARY KEY(generation_id,chunk_id))"
+    )
     conn.commit()
     return has_fts5
 
 
+def _active_generation(conn: sqlite3.Connection) -> str | None:
+    row = conn.execute(
+        "SELECT generation_id FROM org_active_generation WHERE singleton=1"
+    ).fetchone()
+    return str(row["generation_id"]) if row else None
+
+
+def _begin_generation(conn: sqlite3.Connection, mode: str) -> str:
+    generation_id = f"{int(time.time() * 1_000_000)}-{uuid.uuid4().hex[:12]}"
+    conn.execute(
+        "INSERT INTO org_generations(generation_id,status,mode,created_at) VALUES(?,?,?,?)",
+        (generation_id, "BUILDING", mode, time.time()),
+    )
+    conn.commit()
+    return generation_id
+
+
+def _canonical_json(value: Any) -> str:
+    return json.dumps(value, sort_keys=True, separators=(",", ":"), ensure_ascii=False)
+
+
+def _generation_digest(conn: sqlite3.Connection, generation_id: str,
+                       graph_data: dict[str, Any]) -> tuple[str, dict[str, int]]:
+    """Hash every persisted retrieval row plus the graph, in stable order."""
+    h = hashlib.sha256()
+    h.update(_canonical_json(graph_data).encode("utf-8"))
+    counts: dict[str, int] = {}
+    table_specs = (
+        ("chunks", "org_chunks_gen", ("chunk_id", "node_id", "repo", "path", "kind",
+                                       "corpus", "source", "title", "body", "sha256"),
+         "chunk_id"),
+        ("vectors", "org_vectors_gen", ("chunk_id", "dim", "vec"), "chunk_id"),
+        ("brain_handles", "org_brain_handles_gen",
+         ("handle_id", "node_id", "source", "source_url", "receipt_id",
+          "safety_decision", "training_decision", "source_training_eligible",
+          "title", "metadata_text"), "handle_id"),
+    )
+    for label, table, columns, order_col in table_specs:
+        n = 0
+        sql = (f"SELECT {','.join(columns)} FROM {table} WHERE generation_id=? "
+               f"ORDER BY {order_col}")
+        for row in conn.execute(sql, (generation_id,)):
+            h.update(label.encode("ascii"))
+            h.update(b"\0")
+            h.update(_canonical_json([row[c] for c in columns]).encode("utf-8"))
+            h.update(b"\n")
+            n += 1
+        counts[label] = n
+    return h.hexdigest(), counts
+
+
+def _resolve_m1_ledger() -> Path | None:
+    raw = os.environ.get(_M1_LEDGER_ENV, "").strip()
+    path = Path(raw).expanduser().resolve() if raw else _M1_LEDGER_DEFAULT
+    return path if path.is_file() else None
+
+
+def _verify_m1_ledger(path: Path) -> dict[str, Any]:
+    """Verify the release manifest when using the versioned in-repo M1 ledger."""
+    manifest_path = path.with_name("corpus-ingestion-manifest.json")
+    expected_sha = None
+    expected_rows = None
+    if manifest_path.is_file():
+        manifest = json.loads(manifest_path.read_text(encoding="utf-8"))
+        entry = ((manifest.get("ledgers") or {}).get("brain_nodes") or {})
+        expected_sha = entry.get("sha256")
+        expected_rows = entry.get("rows")
+    h = hashlib.sha256()
+    rows = 0
+    with path.open("rb") as stream:
+        for line in stream:
+            h.update(line)
+            if line.strip():
+                rows += 1
+    actual_sha = h.hexdigest()
+    if expected_sha and actual_sha != expected_sha:
+        raise ValueError("M1 Brain ledger SHA-256 does not match its release manifest")
+    if expected_rows is not None and rows != int(expected_rows):
+        raise ValueError("M1 Brain ledger row count does not match its release manifest")
+    return {"path": str(path), "sha256": actual_sha, "rows": rows,
+            "manifest_verified": bool(expected_sha and expected_rows is not None)}
+
+
+def _brain_handle_text(row: dict[str, Any]) -> tuple[str, str]:
+    """Return bounded metadata text only; never copy an external document body."""
+    canonical = str(row.get("canonical_text") or "")
+    title_match = re.search(r"(?m)^title:\s*(.+)$", canonical)
+    title = (title_match.group(1).strip() if title_match else
+             str(row.get("node_id") or "untitled Brain handle"))
+    prov = row.get("provenance") if isinstance(row.get("provenance"), dict) else {}
+    license_info = row.get("license") if isinstance(row.get("license"), dict) else {}
+    freshness = row.get("freshness") if isinstance(row.get("freshness"), dict) else {}
+    fields = {
+        "title": title,
+        "kind": row.get("kind"),
+        "source": prov.get("source"),
+        "url": prov.get("url"),
+        "evidence_label": prov.get("evidence_label"),
+        "receipt_id": row.get("receipt_id"),
+        "safety_decision": row.get("safety_decision"),
+        "training_decision": row.get("training_decision"),
+        "license_state": license_info.get("state"),
+        "freshness_state": freshness.get("state"),
+    }
+    return title, "\n".join(f"{k}: {v}" for k, v in fields.items() if v is not None)
+
+
+def _ingest_brain_handles(conn: sqlite3.Connection, generation_id: str,
+                          ledger_path: Path | None = None) -> dict[str, Any]:
+    """Index M1 rows as retrieval-only metadata handles with zero gradient authority."""
+    path = ledger_path or _resolve_m1_ledger()
+    if path is None:
+        return {"state": "ABSENT", "count": 0, "gradient_authority_rows": 0}
+    verified = _verify_m1_ledger(path)
+    count = 0
+    source_training_eligible_rows = 0
+    with path.open(encoding="utf-8") as stream:
+        for raw_line in stream:
+            if not raw_line.strip():
+                continue
+            row = json.loads(raw_line)
+            node_id = str(row.get("node_id") or "").strip()
+            receipt_id = str(row.get("receipt_id") or "").strip()
+            if not node_id or not receipt_id:
+                raise ValueError("M1 Brain handle is missing node_id or receipt_id")
+            prov = row.get("provenance") if isinstance(row.get("provenance"), dict) else {}
+            title, metadata_text = _brain_handle_text(row)
+            handle_id = hashlib.sha256(
+                f"{node_id}\0{receipt_id}".encode("utf-8")
+            ).hexdigest()
+            conn.execute(
+                "INSERT INTO org_brain_handles_gen("
+                "generation_id,handle_id,node_id,source,source_url,receipt_id,"
+                "safety_decision,training_decision,source_training_eligible,title,metadata_text) "
+                "VALUES(?,?,?,?,?,?,?,?,?,?,?)",
+                (generation_id, handle_id, node_id, str(prov.get("source") or ""),
+                 str(prov.get("url") or ""), receipt_id,
+                 str(row.get("safety_decision") or "UNKNOWN"),
+                 str(row.get("training_decision") or "UNKNOWN"),
+                 "true" if row.get("training_eligible") is True else "false",
+                 title, metadata_text),
+            )
+            if row.get("training_eligible") is True:
+                source_training_eligible_rows += 1
+            count += 1
+    conn.commit()
+    if count != int(verified["rows"]):
+        raise ValueError("M1 Brain handle ingest count changed during verified read")
+    return {"state": "INDEXED_RETRIEVAL_ONLY", "count": count,
+            "gradient_authority_rows": 0, "training_authority": "NONE",
+            "ledger_sha256": verified["sha256"],
+            "manifest_verified": verified["manifest_verified"],
+            "source_training_eligible_rows": source_training_eligible_rows}
+
+
+def _persist_runtime_state(conn: sqlite3.Connection, graph: OrgGraph,
+                           meta: dict[str, Any],
+                           generation_id: str | None = None) -> None:
+    """Seal one immutable generation and atomically make it query-active.
+
+    The optional legacy path is retained for focused callers that populated the
+    old tables directly: it copies their rows into a fresh generation before the
+    swap.  Production builders always pass their staging generation explicitly.
+    """
+    global _GRAPH, _BUILD_META
+    if generation_id is None:
+        generation_id = _begin_generation(conn, str(meta.get("mode") or "legacy-migration"))
+        conn.execute(
+            "INSERT INTO org_chunks_gen(generation_id,chunk_id,node_id,repo,path,kind,"
+            "corpus,source,title,body,sha256) SELECT ?,chunk_id,node_id,repo,path,kind,"
+            "corpus,source,title,body,sha256 FROM org_chunks", (generation_id,))
+        conn.execute(
+            "INSERT OR REPLACE INTO org_vectors_gen(generation_id,chunk_id,dim,vec) "
+            "SELECT ?,chunk_id,dim,vec FROM org_vectors", (generation_id,))
+        conn.commit()
+
+    if not meta.get("built"):
+        conn.execute(
+            "UPDATE org_generations SET status='FAILED',failure_reason=? "
+            "WHERE generation_id=? AND status='BUILDING'",
+            ("empty/unusable build refused before active-generation swap", generation_id),
+        )
+        conn.commit()
+        meta.update({"generation_id": generation_id,
+                     "integrity_state": "NOT_PUBLISHED_EMPTY_BUILD"})
+        return
+
+    graph_data = graph.to_dict()
+    with _SNAPSHOT_LOCK:
+        conn.commit()
+        conn.execute("BEGIN IMMEDIATE")
+        # Seal the exact rows protected by this writer transaction. No writer can
+        # change staging data between this digest and the active-pointer swap.
+        digest, counts = _generation_digest(conn, generation_id, graph_data)
+        meta.update({
+            "generation_id": generation_id,
+            "generation_digest_sha256": digest,
+            "integrity_state": "VERIFIED_AT_PUBLISH",
+            "corpus_chunk_count": counts["chunks"],
+            "brain_handle_count": counts["brain_handles"],
+            "training_authority_rows": 0,
+        })
+        meta_blob = _canonical_json(meta)
+        graph_blob = _canonical_json(graph_data)
+        previous = _active_generation(conn)
+        if previous and previous != generation_id:
+            conn.execute("UPDATE org_generations SET status='SUPERSEDED' WHERE generation_id=?",
+                         (previous,))
+        conn.execute(
+            "UPDATE org_generations SET status='ACTIVE',activated_at=?,chunk_count=?,"
+            "vector_count=?,brain_handle_count=?,graph_json=?,meta_json=?,digest_sha256=? "
+            "WHERE generation_id=? AND status='BUILDING'",
+            (time.time(), counts["chunks"], counts["vectors"], counts["brain_handles"],
+             graph_blob, meta_blob, digest, generation_id),
+        )
+        if conn.execute("SELECT changes() AS n").fetchone()["n"] != 1:
+            conn.rollback()
+            raise RuntimeError("generation publication refused: staging generation not BUILDING")
+        conn.execute(
+            "INSERT INTO org_active_generation(singleton,generation_id) VALUES(1,?) "
+            "ON CONFLICT(singleton) DO UPDATE SET generation_id=excluded.generation_id",
+            (generation_id,),
+        )
+        # Compatibility metadata is informational only. Rehydration trusts the
+        # active generation row and re-computes its digest, never these keys.
+        for key, value in {"build_meta": meta, "graph": graph_data}.items():
+            conn.execute(
+                "INSERT OR REPLACE INTO org_runtime_meta(key,value) VALUES(?,?)",
+                (key, _canonical_json(value)),
+            )
+        conn.commit()
+        _GRAPH = graph
+        _BUILD_META = dict(meta)
+
+
+def _rehydrate_runtime_state() -> bool:
+    """Restore only a digest-verified ACTIVE generation; mismatch fails closed."""
+    global _GRAPH, _BUILD_META, _REHYDRATE_ATTEMPTED
+    if _BUILD_META.get("built"):
+        return True
+    if _REHYDRATE_ATTEMPTED:
+        return False
+    _REHYDRATE_ATTEMPTED = True
+    try:
+        if not os.path.exists(RAG_DB_PATH):
+            return False
+        conn = _db()
+        _init_schema(conn)
+        conn.execute("BEGIN")
+        generation_id = _active_generation(conn)
+        if not generation_id:
+            conn.close()
+            _BUILD_META = {
+                "built": False, "ts": None, "repos": 0, "chunks": 0,
+                "rehydration_state": "REBUILD_REQUIRED_NO_GENERATION",
+                "honest_note": "legacy/unversioned Brain index is not trusted; rebuild required",
+            }
+            return False
+        row = conn.execute(
+            "SELECT * FROM org_generations WHERE generation_id=? AND status='ACTIVE'",
+            (generation_id,),
+        ).fetchone()
+        if not row or not row["graph_json"] or not row["meta_json"] or not row["digest_sha256"]:
+            conn.close()
+            raise ValueError("active Brain generation is incomplete")
+        graph_data = json.loads(row["graph_json"])
+        meta = json.loads(row["meta_json"])
+        actual_digest, counts = _generation_digest(conn, generation_id, graph_data)
+        conn.close()
+        count_match = (
+            counts["chunks"] == int(row["chunk_count"])
+            and counts["vectors"] == int(row["vector_count"])
+            and counts["brain_handles"] == int(row["brain_handle_count"])
+        )
+        if actual_digest != row["digest_sha256"] or not count_match:
+            _GRAPH = OrgGraph()
+            _BUILD_META = {
+                "built": False, "ts": None, "repos": 0, "chunks": 0,
+                "generation_id": generation_id,
+                "rehydration_state": "INTEGRITY_MISMATCH_REBUILD_REQUIRED",
+                "integrity_state": "FAILED_CLOSED",
+                "expected_generation_digest_sha256": row["digest_sha256"],
+                "actual_generation_digest_sha256": actual_digest,
+                "honest_note": "persisted Brain generation failed integrity validation; rebuild required",
+            }
+            return False
+        if not isinstance(meta, dict) or not meta.get("built"):
+            raise ValueError("active Brain generation metadata does not claim a built index")
+        graph = OrgGraph()
+        if isinstance(graph_data, dict):
+            for node in graph_data.get("nodes") or []:
+                if isinstance(node, dict) and isinstance(node.get("id"), str):
+                    attrs = {k: v for k, v in node.items() if k not in {"id", "kind"}}
+                    graph.add_node(node["id"], str(node.get("kind") or "unknown"), **attrs)
+            for edge in graph_data.get("edges") or []:
+                if isinstance(edge, dict):
+                    graph.add_edge(str(edge.get("src") or ""),
+                                   str(edge.get("dst") or ""),
+                                   str(edge.get("kind") or "related"))
+        _GRAPH = graph
+        _BUILD_META = dict(meta)
+        _BUILD_META["generation_id"] = generation_id
+        _BUILD_META["generation_digest_sha256"] = actual_digest
+        _BUILD_META["integrity_state"] = "VERIFIED_ON_REHYDRATE"
+        _BUILD_META["corpus_chunk_count"] = counts["chunks"]
+        _BUILD_META["brain_handle_count"] = counts["brain_handles"]
+        _BUILD_META["training_authority_rows"] = 0
+        _BUILD_META["rehydrated_from_sqlite"] = True
+        _BUILD_META["rehydrated_at"] = time.time()
+        return True
+    except Exception as exc:
+        _BUILD_META = {
+            "built": False, "ts": None, "repos": 0, "chunks": 0,
+            "rehydration_state": "FAILED",
+            "rehydration_error_type": type(exc).__name__,
+            "honest_note": "persisted Brain state could not be rehydrated; rebuild required",
+        }
+        return False
+
+
 # --------------------------------------------------------------------------- #
 # GitHub enumeration (the offline build path).  Receipted by the caller.
 # --------------------------------------------------------------------------- #
@@ -404,8 +793,7 @@ def build_index(repos: list[str] | None = None, max_files_per_repo: int = 120,
         graph = OrgGraph()
         conn = _db()
         has_fts5 = _init_schema(conn)
-        conn.execute("DELETE FROM org_chunks")
-        conn.execute("DELETE FROM org_vectors")
+        generation_id = _begin_generation(conn, "full-org")
 
         if repos is None:
             try:
@@ -464,35 +852,40 @@ def build_index(repos: list[str] | None = None, max_files_per_repo: int = 120,
                     cid = hashlib.sha256(f"{fid}:{j}".encode()).hexdigest()[:24]
                     csha = hashlib.sha256(seg.encode()).hexdigest()
                     conn.execute(
-                        "INSERT INTO org_chunks(chunk_id,node_id,repo,path,kind,corpus,source,title,body,sha256)"
-                        " VALUES(?,?,?,?,?,?,?,?,?,?)",
-                        (cid, fid, repo, path, "file", _cat, f"gh:{ORG}/{repo}", path, seg, csha))
+                        "INSERT INTO org_chunks_gen(generation_id,chunk_id,node_id,repo,path,kind,"
+                        "corpus,source,title,body,sha256) VALUES(?,?,?,?,?,?,?,?,?,?,?)",
+                        (generation_id, cid, fid, repo, path, "file", _cat,
+                         f"gh:{ORG}/{repo}", path, seg, csha))
                     if embed_fn is not None:
                         try:
                             v = embed_fn(seg)
                             conn.execute(
-                                "INSERT OR REPLACE INTO org_vectors(chunk_id,dim,vec) VALUES(?,?,?)",
-                                (cid, len(v), json.dumps([round(x, 6) for x in v])))
+                                "INSERT OR REPLACE INTO org_vectors_gen("
+                                "generation_id,chunk_id,dim,vec) VALUES(?,?,?,?)",
+                                (generation_id, cid, len(v),
+                                 json.dumps([round(x, 6) for x in v])))
                         except Exception:
                             pass
                     chunk_count += 1
             conn.commit()
 
-        global _GRAPH, _BUILD_META
-        _GRAPH = graph
-        _BUILD_META = {
-            "built": True, "mode": "full", "ts": time.time(), "org": ORG,
+        brain_handles = _ingest_brain_handles(conn, generation_id)
+        meta = {
+            "built": (chunk_count > 0 or brain_handles["count"] > 0),
+            "mode": "full", "ts": time.time(), "org": ORG,
             "repos": len(repos), "chunks": chunk_count,
             "fts5": has_fts5, "dense": embed_fn is not None,
             "node_count": len(graph.nodes), "edge_count": len(graph.edges),
             "build_ms": round((time.time() - t0) * 1000, 1),
             "corpus_categories": sorted({_category_for(r) for r in repos}),
+            "brain_handle_plane": brain_handles,
             "honest_note": ("dense vectors present" if embed_fn is not None
                             else "FTS5/lexical only — embedding model unavailable in this runtime (honest)"),
         }
+        _persist_runtime_state(conn, graph, meta, generation_id)
         conn.close()
-        rec = emit_receipt("org_rag.index.built", _BUILD_META) if emit_receipt else None
-        out = {"ok": True, **_BUILD_META}
+        rec = emit_receipt("org_rag.index.built", meta) if emit_receipt else None
+        out = {"ok": bool(meta.get("built")), **meta}
         if rec:
             out["khipu_hash"] = rec.get("hash")
         return out
@@ -537,7 +930,12 @@ def dense_vector_count() -> int:
     try:
         conn = _db()
         try:
-            row = conn.execute("SELECT COUNT(*) AS n FROM org_vectors").fetchone()
+            _init_schema(conn)
+            generation_id = _active_generation(conn)
+            row = (conn.execute(
+                "SELECT COUNT(*) AS n FROM org_vectors_gen WHERE generation_id=?",
+                (generation_id,)).fetchone() if generation_id else
+                conn.execute("SELECT COUNT(*) AS n FROM org_vectors").fetchone())
             return int(row["n"]) if row else 0
         finally:
             conn.close()
@@ -550,7 +948,12 @@ def chunk_count() -> int:
     try:
         conn = _db()
         try:
-            row = conn.execute("SELECT COUNT(*) AS n FROM org_chunks").fetchone()
+            _init_schema(conn)
+            generation_id = _active_generation(conn)
+            row = (conn.execute(
+                "SELECT COUNT(*) AS n FROM org_chunks_gen WHERE generation_id=?",
+                (generation_id,)).fetchone() if generation_id else
+                conn.execute("SELECT COUNT(*) AS n FROM org_chunks").fetchone())
             return int(row["n"]) if row else 0
         finally:
             conn.close()
@@ -569,10 +972,19 @@ def next_unembedded_chunks(limit: int = 4) -> list[dict[str, Any]]:
     try:
         conn = _db()
         try:
-            rows = conn.execute(
-                "SELECT chunk_id,repo,path,corpus,source,body FROM org_chunks "
-                "WHERE chunk_id NOT IN (SELECT chunk_id FROM org_vectors) "
-                "LIMIT ?", (max(1, int(limit)),)).fetchall()
+            _init_schema(conn)
+            generation_id = _active_generation(conn)
+            if generation_id:
+                rows = conn.execute(
+                    "SELECT chunk_id,repo,path,corpus,source,body FROM org_chunks_gen "
+                    "WHERE generation_id=? AND chunk_id NOT IN (SELECT chunk_id FROM "
+                    "org_vectors_gen WHERE generation_id=?) LIMIT ?",
+                    (generation_id, generation_id, max(1, int(limit)))).fetchall()
+            else:
+                rows = conn.execute(
+                    "SELECT chunk_id,repo,path,corpus,source,body FROM org_chunks "
+                    "WHERE chunk_id NOT IN (SELECT chunk_id FROM org_vectors) LIMIT ?",
+                    (max(1, int(limit)),)).fetchall()
             for r in rows:
                 out.append({"chunk_id": r["chunk_id"], "repo": r["repo"],
                             "path": r["path"], "corpus": r["corpus"],
@@ -590,13 +1002,19 @@ def embed_and_store_chunk(chunk_id: str, vec: list[float]) -> dict[str, Any]:
     org_chunks — we never create a chunk row here, so an indexed chunk can never be
     fabricated. Returns {ok, chunk_id, dim} or an honest error. Uses the SAME
     storage format as _ingest_text (json list, 6-dp rounding)."""
+    global _BUILD_META
     if not chunk_id or not isinstance(vec, (list, tuple)) or len(vec) == 0:
         return {"ok": False, "honest_error": "empty chunk_id or vector — nothing stored"}
     try:
         conn = _db()
         try:
-            exists = conn.execute(
-                "SELECT 1 FROM org_chunks WHERE chunk_id=? LIMIT 1", (chunk_id,)).fetchone()
+            _init_schema(conn)
+            generation_id = _active_generation(conn)
+            exists = (conn.execute(
+                "SELECT 1 FROM org_chunks_gen WHERE generation_id=? AND chunk_id=? LIMIT 1",
+                (generation_id, chunk_id)).fetchone() if generation_id else
+                conn.execute("SELECT 1 FROM org_chunks WHERE chunk_id=? LIMIT 1",
+                             (chunk_id,)).fetchone())
             if not exists:
                 # Honest refusal: cannot add a vector for a chunk that was never
                 # really ingested (would imply a fabricated indexed chunk).
@@ -604,10 +1022,44 @@ def embed_and_store_chunk(chunk_id: str, vec: list[float]) -> dict[str, Any]:
                         "honest_error": "chunk_id not present in org_chunks — refusing "
                                         "to store a vector for a non-existent chunk "
                                         "(Zero-Bandaid Law: never fabricate an index)"}
-            conn.execute(
-                "INSERT OR REPLACE INTO org_vectors(chunk_id,dim,vec) VALUES(?,?,?)",
-                (chunk_id, len(vec), json.dumps([round(float(x), 6) for x in vec])))
-            conn.commit()
+            if generation_id:
+                # Vector useful-work is a bounded atomic augmentation: the vector,
+                # generation digest, count, and metadata change in one transaction.
+                # Readers see either the old snapshot or the fully sealed new one.
+                with _SNAPSHOT_LOCK:
+                    conn.commit()
+                    conn.execute("BEGIN IMMEDIATE")
+                    conn.execute(
+                        "INSERT OR REPLACE INTO org_vectors_gen("
+                        "generation_id,chunk_id,dim,vec) VALUES(?,?,?,?)",
+                        (generation_id, chunk_id, len(vec),
+                         json.dumps([round(float(x), 6) for x in vec])))
+                    generation = conn.execute(
+                        "SELECT graph_json,meta_json FROM org_generations "
+                        "WHERE generation_id=? AND status='ACTIVE'", (generation_id,)
+                    ).fetchone()
+                    if not generation:
+                        conn.rollback()
+                        raise RuntimeError("active generation disappeared during vector write")
+                    graph_data = json.loads(generation["graph_json"])
+                    meta = json.loads(generation["meta_json"])
+                    digest, counts = _generation_digest(conn, generation_id, graph_data)
+                    meta.update({
+                        "generation_digest_sha256": digest,
+                        "integrity_state": "VERIFIED_AFTER_ATOMIC_VECTOR_WRITE",
+                    })
+                    conn.execute(
+                        "UPDATE org_generations SET vector_count=?,digest_sha256=?,meta_json=? "
+                        "WHERE generation_id=? AND status='ACTIVE'",
+                        (counts["vectors"], digest, _canonical_json(meta), generation_id),
+                    )
+                    conn.commit()
+                    _BUILD_META = meta
+            else:
+                conn.execute(
+                    "INSERT OR REPLACE INTO org_vectors(chunk_id,dim,vec) VALUES(?,?,?)",
+                    (chunk_id, len(vec), json.dumps([round(float(x), 6) for x in vec])))
+                conn.commit()
         finally:
             conn.close()
     except Exception as exc:
@@ -796,7 +1248,8 @@ def _local_provenance(rel_from_corpus: str) -> dict[str, str]:
 
 def _ingest_local_category(graph: OrgGraph, conn: sqlite3.Connection, *, category: str,
                            local_dirs: list[str],
-                           embed_fn: Callable[[str], list[float]] | None
+                           embed_fn: Callable[[str], list[float]] | None,
+                           generation_id: str
                            ) -> tuple[int, int]:
     """Ingest the REAL in-image mirror files for one category.  Returns
     (files, chunks).  Each chunk is labeled with an honest 'bundled:<repo>@<sha>'
@@ -833,7 +1286,7 @@ def _ingest_local_category(graph: OrgGraph, conn: sqlite3.Connection, *, categor
             prov = _local_provenance(f"corpus/{rel}/{name}")
             wrote = _ingest_text(graph, conn, repo=prov["repo"], path=prov["path"],
                                  raw=raw, source=prov["source"], category=category,
-                                 embed_fn=embed_fn)
+                                 embed_fn=embed_fn, generation_id=generation_id)
             files_n += 1
             chunks_n += wrote
     return (files_n, chunks_n)
@@ -841,7 +1294,8 @@ def _ingest_local_category(graph: OrgGraph, conn: sqlite3.Connection, *, categor
 
 def _ingest_text(graph: OrgGraph, conn: sqlite3.Connection, *, repo: str, path: str,
                  raw: str, source: str, category: str,
-                 embed_fn: Callable[[str], list[float]] | None) -> int:
+                 embed_fn: Callable[[str], list[float]] | None,
+                 generation_id: str) -> int:
     """Shared ingest: graph nodes/edges + symbols + imports + FTS5/vector chunks.
     Returns the number of chunks written. Used by seed AND full builds so the two
     paths are byte-for-byte consistent in how they ground + cite."""
@@ -861,15 +1315,16 @@ def _ingest_text(graph: OrgGraph, conn: sqlite3.Connection, *, repo: str, path:
         cid = hashlib.sha256(f"{source}:{fid}:{j}".encode()).hexdigest()[:24]
         csha = hashlib.sha256(seg.encode()).hexdigest()
         conn.execute(
-            "INSERT INTO org_chunks(chunk_id,node_id,repo,path,kind,corpus,source,title,body,sha256)"
-            " VALUES(?,?,?,?,?,?,?,?,?,?)",
-            (cid, fid, repo, path, "file", category, source, path, seg, csha))
+            "INSERT INTO org_chunks_gen(generation_id,chunk_id,node_id,repo,path,kind,"
+            "corpus,source,title,body,sha256) VALUES(?,?,?,?,?,?,?,?,?,?,?)",
+            (generation_id, cid, fid, repo, path, "file", category, source, path, seg, csha))
         if embed_fn is not None:
             try:
                 v = embed_fn(seg)
                 conn.execute(
-                    "INSERT OR REPLACE INTO org_vectors(chunk_id,dim,vec) VALUES(?,?,?)",
-                    (cid, len(v), json.dumps([round(x, 6) for x in v])))
+                    "INSERT OR REPLACE INTO org_vectors_gen(generation_id,chunk_id,dim,vec) "
+                    "VALUES(?,?,?,?)",
+                    (generation_id, cid, len(v), json.dumps([round(x, 6) for x in v])))
             except Exception:
                 pass
         n += 1
@@ -888,8 +1343,7 @@ def build_seed_index(emit_receipt: Callable[[str, dict], dict] | None = None) ->
         graph = OrgGraph()
         conn = _db()
         has_fts5 = _init_schema(conn)
-        conn.execute("DELETE FROM org_chunks")
-        conn.execute("DELETE FROM org_vectors")
+        generation_id = _begin_generation(conn, "seed")
         embed_fn = _maybe_embedder()
         per_cat: dict[str, dict[str, int]] = {}
         chunk_count = 0
@@ -921,7 +1375,8 @@ def build_seed_index(emit_receipt: Callable[[str, dict], dict] | None = None) ->
                     continue
                 repo_for = src.split("/")[-1]
                 wrote = _ingest_text(graph, conn, repo=repo_for, path=path, raw=raw,
-                                     source=src, category=cat, embed_fn=embed_fn)
+                                     source=src, category=cat, embed_fn=embed_fn,
+                                     generation_id=generation_id)
                 c_files += 1
                 c_chunks += wrote
                 chunk_count += wrote
@@ -932,7 +1387,8 @@ def build_seed_index(emit_receipt: Callable[[str, dict], dict] | None = None) ->
             local_dirs = spec.get("local_paths", [])
             if c_files == 0 and local_dirs:
                 lf, lc = _ingest_local_category(graph, conn, category=cat,
-                                                local_dirs=local_dirs, embed_fn=embed_fn)
+                                                local_dirs=local_dirs, embed_fn=embed_fn,
+                                                generation_id=generation_id)
                 c_files += lf
                 c_chunks += lc
                 chunk_count += lc
@@ -940,15 +1396,16 @@ def build_seed_index(emit_receipt: Callable[[str, dict], dict] | None = None) ->
             per_cat[cat] = {"files": c_files, "chunks": c_chunks}
             conn.commit()
 
-        global _GRAPH, _BUILD_META
-        _GRAPH = graph
-        _BUILD_META = {
-            "built": chunk_count > 0, "mode": "seed", "ts": time.time(), "org": ORG,
+        brain_handles = _ingest_brain_handles(conn, generation_id)
+        meta = {
+            "built": (chunk_count > 0 or brain_handles["count"] > 0),
+            "mode": "seed", "ts": time.time(), "org": ORG,
             "repos": len({s for s in per_cat}), "chunks": chunk_count, "files": files_ok,
             "fts5": has_fts5, "dense": embed_fn is not None,
             "node_count": len(graph.nodes), "edge_count": len(graph.edges),
             "build_ms": round((time.time() - t0) * 1000, 1),
             "per_category": per_cat,
+            "brain_handle_plane": brain_handles,
             "corpus_categories": [c for c, v in per_cat.items() if v["chunks"] > 0],
             "gh_credential": bool(gh), "hf_credential": bool(hf),
             "honest_note": (
@@ -961,10 +1418,11 @@ def build_seed_index(emit_receipt: Callable[[str, dict], dict] | None = None) ->
                    "szl-holdings repos read UNAUTHENTICATED (rate-limited but real); "
                    "HF Spaces also ingested (honest, not fabricated).")),
         }
+        _persist_runtime_state(conn, graph, meta, generation_id)
         conn.close()
-        rec = emit_receipt("org_rag.index.seed", _BUILD_META) if emit_receipt else None
-        out = {"ok": _BUILD_META["built"], **_BUILD_META}
-        if not _BUILD_META["built"]:
+        rec = emit_receipt("org_rag.index.seed", meta) if emit_receipt else None
+        out = {"ok": meta["built"], **meta}
+        if not meta["built"]:
             out["honest_error"] = ("seed index empty — no corpus file could be fetched "
                                    "(no GitHub/HF credential reachable). NOT claiming a "
                                    "built index (Zero-Bandaid Law).")
@@ -987,8 +1445,7 @@ def build_full_corpus(emit_receipt: Callable[[str, dict], dict] | None = None,
         graph = OrgGraph()
         conn = _db()
         has_fts5 = _init_schema(conn)
-        conn.execute("DELETE FROM org_chunks")
-        conn.execute("DELETE FROM org_vectors")
+        generation_id = _begin_generation(conn, "full")
         embed_fn = _maybe_embedder()
         per_cat: dict[str, dict[str, int]] = {}
         chunk_count = 0
@@ -1029,7 +1486,8 @@ def build_full_corpus(emit_receipt: Callable[[str, dict], dict] | None = None,
                             continue
                         wrote = _ingest_text(graph, conn, repo=repo, path=f["path"],
                                              raw=raw, source=f"gh:{ORG}/{repo}",
-                                             category=cat, embed_fn=embed_fn)
+                                             category=cat, embed_fn=embed_fn,
+                                             generation_id=generation_id)
                         c_files += 1
                         c_chunks += wrote
                         chunk_count += wrote
@@ -1043,7 +1501,8 @@ def build_full_corpus(emit_receipt: Callable[[str, dict], dict] | None = None,
                         continue
                     wrote = _ingest_text(graph, conn, repo=sp, path=path, raw=raw,
                                          source=f"hf:{HF_ORG}/{sp}", category=cat,
-                                         embed_fn=embed_fn)
+                                         embed_fn=embed_fn,
+                                         generation_id=generation_id)
                     c_files += 1
                     c_chunks += wrote
                     chunk_count += wrote
@@ -1056,7 +1515,8 @@ def build_full_corpus(emit_receipt: Callable[[str, dict], dict] | None = None,
             local_dirs = spec.get("local_paths", [])
             if c_files == 0 and local_dirs:
                 lf, lc = _ingest_local_category(graph, conn, category=cat,
-                                                local_dirs=local_dirs, embed_fn=embed_fn)
+                                                local_dirs=local_dirs, embed_fn=embed_fn,
+                                                generation_id=generation_id)
                 c_files += lf
                 c_chunks += lc
                 chunk_count += lc
@@ -1067,15 +1527,16 @@ def build_full_corpus(emit_receipt: Callable[[str, dict], dict] | None = None,
                     "category": cat, "files": c_files, "chunks": c_chunks})
 
         built_cats = [c for c, v in per_cat.items() if v["chunks"] > 0]
-        global _GRAPH, _BUILD_META
-        _GRAPH = graph
-        _BUILD_META = {
-            "built": chunk_count > 0, "mode": "full", "ts": time.time(), "org": ORG,
+        brain_handles = _ingest_brain_handles(conn, generation_id)
+        meta = {
+            "built": (chunk_count > 0 or brain_handles["count"] > 0),
+            "mode": "full", "ts": time.time(), "org": ORG,
             "repos": len(seen_repo), "chunks": chunk_count,
             "fts5": has_fts5, "dense": embed_fn is not None,
             "node_count": len(graph.nodes), "edge_count": len(graph.edges),
             "build_ms": round((time.time() - t0) * 1000, 1),
             "per_category": per_cat, "corpus_categories": built_cats,
+            "brain_handle_plane": brain_handles,
             "gh_credential": bool(gh),
             "corpus_mirror": bool(_corpus_root()),
             "honest_note": (
@@ -1091,9 +1552,10 @@ def build_full_corpus(emit_receipt: Callable[[str, dict], dict] | None = None,
                    "source='bundled:<repo>@<commit_sha>:<path>' — real files, honest "
                    "provenance, NOT fabricated." if _corpus_root() else "")),
         }
+        _persist_runtime_state(conn, graph, meta, generation_id)
         conn.close()
-        rec = emit_receipt("org_rag.index.full", _BUILD_META) if emit_receipt else None
-        out = {"ok": _BUILD_META["built"], **_BUILD_META}
+        rec = emit_receipt("org_rag.index.full", meta) if emit_receipt else None
+        out = {"ok": meta["built"], **meta}
         if rec:
             out["khipu_hash"] = rec.get("hash")
         return out
@@ -1187,39 +1649,101 @@ def query(q: str, k: int = 6, repo: str | None = None,
     ``file{path,sha256}`` evidence, plus an ``i_dont_know`` flag when support is
     too low.  ``hyde_text`` (optional) is a hypothetical answer used for dense
     recall (HyDE) instead of the bare query."""
+    _rehydrate_runtime_state()
     if not _BUILD_META.get("built"):
         return {"ok": False, "i_dont_know": True,
                 "honest_error": "org index not built — call /api/a11oy/code/rag/index first",
                 "query": q, "chunks": []}
-    conn = _db()
+    with _SNAPSHOT_LOCK:
+        conn = _db()
+        _init_schema(conn)
+        conn.execute("BEGIN")
+        generation_id = _active_generation(conn)
+        graph_snapshot = _GRAPH
+        meta_snapshot = dict(_BUILD_META)
+    if generation_id and generation_id != meta_snapshot.get("generation_id"):
+        conn.close()
+        return {"ok": False, "i_dont_know": True, "query": q, "chunks": [],
+                "honest_error": "Brain generation/graph snapshot mismatch; retry after rebuild",
+                "integrity_state": "FAILED_CLOSED"}
     embed_fn = _maybe_embedder()
     recall_text = hyde_text or q
     # Stage 1: lexical recall (FTS5 or LIKE fallback).
-    rows: list[sqlite3.Row] = []
+    rows: list[dict[str, Any]] = []
     try:
-        sql = "SELECT chunk_id,node_id,repo,path,corpus,source,title,body,sha256 FROM org_chunks WHERE org_chunks MATCH ?"
-        args: list[Any] = [_fts_escape(q)]
+        if generation_id:
+            sql = ("SELECT chunk_id,node_id,repo,path,corpus,source,title,body,sha256 "
+                   "FROM org_chunks_gen WHERE org_chunks_gen MATCH ? AND generation_id=?")
+            args: list[Any] = [_fts_escape(q), generation_id]
+        else:
+            sql = ("SELECT chunk_id,node_id,repo,path,corpus,source,title,body,sha256 "
+                   "FROM org_chunks WHERE org_chunks MATCH ?")
+            args = [_fts_escape(q)]
         if repo:
             sql += " AND repo = ?"
             args.append(repo)
         sql += " LIMIT ?"
         args.append(max(k * 4, 24))
-        rows = list(conn.execute(sql, args))
+        rows = [{**dict(row), "retrieval_plane": "corpus"}
+                for row in conn.execute(sql, args)]
     except Exception:
         # LIKE fallback (non-FTS5 runtime) — labeled weaker.
         like = f"%{re.sub(r'[^A-Za-z0-9_ ]', ' ', q)[:60]}%"
-        sql = "SELECT chunk_id,node_id,repo,path,corpus,source,title,body,sha256 FROM org_chunks WHERE body LIKE ?"
-        args = [like]
+        if generation_id:
+            sql = ("SELECT chunk_id,node_id,repo,path,corpus,source,title,body,sha256 "
+                   "FROM org_chunks_gen WHERE generation_id=? AND body LIKE ?")
+            args = [generation_id, like]
+        else:
+            sql = ("SELECT chunk_id,node_id,repo,path,corpus,source,title,body,sha256 "
+                   "FROM org_chunks WHERE body LIKE ?")
+            args = [like]
         if repo:
             sql += " AND repo = ?"
             args.append(repo)
         sql += " LIMIT ?"
         args.append(max(k * 4, 24))
         try:
-            rows = list(conn.execute(sql, args))
+            rows = [{**dict(row), "retrieval_plane": "corpus"}
+                    for row in conn.execute(sql, args)]
         except Exception:
             rows = []
 
+    # Search the M1 decision ledger as a distinct retrieval-only plane.  These
+    # rows are metadata handles (title/kind/source/URL/receipt/safety), not copied
+    # external documents, and never grant gradient or training authority.
+    if generation_id and (repo is None or repo == "m1-brain-ledger"):
+        handle_rows: list[sqlite3.Row] = []
+        try:
+            handle_rows = list(conn.execute(
+                "SELECT handle_id,node_id,source,source_url,receipt_id,safety_decision,"
+                "training_decision,source_training_eligible,title,metadata_text "
+                "FROM org_brain_handles_gen WHERE org_brain_handles_gen MATCH ? "
+                "AND generation_id=? LIMIT ?",
+                (_fts_escape(q), generation_id, max(k * 4, 24))))
+        except Exception:
+            like = f"%{re.sub(r'[^A-Za-z0-9_ ]', ' ', q)[:60]}%"
+            try:
+                handle_rows = list(conn.execute(
+                    "SELECT handle_id,node_id,source,source_url,receipt_id,safety_decision,"
+                    "training_decision,source_training_eligible,title,metadata_text "
+                    "FROM org_brain_handles_gen WHERE generation_id=? AND metadata_text LIKE ? "
+                    "LIMIT ?", (generation_id, like, max(k * 4, 24))))
+            except Exception:
+                handle_rows = []
+        for handle_row in handle_rows:
+            item = dict(handle_row)
+            rows.append({
+                "chunk_id": item["handle_id"], "node_id": item["node_id"],
+                "repo": "m1-brain-ledger", "path": f"brain-handle/{item['node_id']}",
+                "corpus": "brain_handles", "source": item["source"],
+                "title": item["title"], "body": item["metadata_text"],
+                "sha256": item["handle_id"], "retrieval_plane": "brain_handle",
+                "source_url": item["source_url"], "receipt_id": item["receipt_id"],
+                "safety_decision": item["safety_decision"],
+                "training_decision": item["training_decision"],
+                "source_training_eligible": item["source_training_eligible"],
+            })
+
     # dense vector for query (HyDE-aware)
     qvec = None
     if embed_fn is not None:
@@ -1237,14 +1761,18 @@ def query(q: str, k: int = 6, repo: str | None = None,
         lexical = (len(qtokens & btokens) / (len(qtokens) + 1e-9)) if qtokens else 0.0
         lexical = min(1.0, lexical)
         semantic = lexical
-        if qvec is not None:
-            row = conn.execute("SELECT vec FROM org_vectors WHERE chunk_id=?", (r["chunk_id"],)).fetchone()
+        if qvec is not None and r["retrieval_plane"] == "corpus":
+            row = (conn.execute(
+                "SELECT vec FROM org_vectors_gen WHERE generation_id=? AND chunk_id=?",
+                (generation_id, r["chunk_id"])).fetchone() if generation_id else
+                conn.execute("SELECT vec FROM org_vectors WHERE chunk_id=?",
+                             (r["chunk_id"],)).fetchone())
             if row:
                 try:
                     semantic = max(0.0, _cosine(qvec, json.loads(row["vec"])))
                 except Exception:
                     pass
-        centrality = _GRAPH.centrality(r["node_id"])
+        centrality = graph_snapshot.centrality(r["node_id"])
         # conformal anti-overconfidence floor 1/(n+1) over the recall set.
         conformal = 1.0 - 1.0 / (len(rows) + 1)
         # Λ over the three relevance axes (geometric mean — never 1.0 unless all 1.0).
@@ -1252,23 +1780,53 @@ def query(q: str, k: int = 6, repo: str | None = None,
         _cols = r.keys()
         corpus = (r["corpus"] if "corpus" in _cols else None) or _category_for(r["repo"])
         source = (r["source"] if "source" in _cols else None) or f"gh:{ORG}/{r['repo']}"
-        scored.append({
+        scored_item = {
             "chunk_id": r["chunk_id"], "node_id": r["node_id"], "repo": r["repo"],
             "path": r["path"], "title": r["title"], "text": body[:1200],
             "sha256": r["sha256"], "corpus": corpus, "source": source,
             "scores": {"semantic": round(semantic, 4), "lexical": round(lexical, 4),
                        "centrality": round(centrality, 4), "conformal": round(conformal, 4)},
             "lambda": round(lam, 4),
+            "retrieval_plane": r["retrieval_plane"],
             # M2M evidence of kind file{path,sha256} — carries corpus+source so the
             # agent CITES exactly where each grounded claim came from (founder mandate).
             "evidence": {"kind": "file", "path": f"{r['repo']}/{r['path']}",
                          "sha256": r["sha256"], "corpus": corpus, "source": source,
                          "citation": f"{source}/{r['path']}"},
-        })
+        }
+        if r["retrieval_plane"] == "brain_handle":
+            scored_item["evidence"] = {
+                "kind": "brain_handle", "node_id": r["node_id"],
+                "handle_sha256": r["sha256"], "source": source,
+                "source_url": r.get("source_url"), "receipt_id": r.get("receipt_id"),
+                "safety_decision": r.get("safety_decision"),
+                "training_decision": r.get("training_decision"),
+                "retrieval_only": True, "gradient_authority": False,
+                "citation": r.get("source_url") or r.get("receipt_id"),
+            }
+            scored_item["training_authority"] = "NONE"
+        scored.append(scored_item)
     conn.close()
     scored.sort(key=lambda x: x["lambda"], reverse=True)
     grounded = [s for s in scored if s["lambda"] >= _LAMBDA_FLOOR][:k]
     i_dont_know = len(grounded) == 0
+    evidence_set = [
+        {
+            "rank": rank,
+            "chunk_id": item.get("chunk_id"),
+            "node_id": item.get("node_id"),
+            "repo": item.get("repo"),
+            "path": item.get("path"),
+            "sha256": item.get("sha256"),
+            "corpus": item.get("corpus"),
+            "source": item.get("source"),
+            "lambda": item.get("lambda"),
+        }
+        for rank, item in enumerate(grounded, start=1)
+    ]
+    evidence_set_sha256 = hashlib.sha256(json.dumps(
+        evidence_set, sort_keys=True, separators=(",", ":"),
+        ensure_ascii=False).encode("utf-8")).hexdigest()
     out = {
         "ok": True,
         "query": q,
@@ -1277,21 +1835,33 @@ def query(q: str, k: int = 6, repo: str | None = None,
         "lambda_floor": _LAMBDA_FLOOR,
         "recall_count": len(scored),
         "grounded_count": len(grounded),
+        "generation_id": generation_id,
+        "generation_digest_sha256": meta_snapshot.get("generation_digest_sha256"),
+        "recall_by_plane": {
+            "corpus": sum(1 for s in scored if s["retrieval_plane"] == "corpus"),
+            "brain_handles": sum(1 for s in scored if s["retrieval_plane"] == "brain_handle"),
+        },
+        "brain_handle_count": int(meta_snapshot.get("brain_handle_count") or 0),
+        "training_authority_rows": 0,
         "i_dont_know": i_dont_know,
         "chunks": grounded,
+        "evidence_set": evidence_set,
+        "evidence_set_sha256": evidence_set_sha256,
         "honest_note": ("no chunk cleared the Λ relevance floor — returning i_dont_know "
                         "rather than fabricating support (Self-RAG)") if i_dont_know else None,
     }
     if emit_receipt:
         rec = emit_receipt("org_rag.query", {
             "query": q[:120], "grounded": len(grounded), "i_dont_know": i_dont_know,
-            "dense": qvec is not None})
+            "dense": qvec is not None,
+            "evidence_set_sha256": evidence_set_sha256})
         out["khipu_hash"] = rec.get("hash")
     return out
 
 
 def repo_map(repo: str) -> dict[str, Any]:
     """Aider-style repo map: files → symbols, ranked by Λ-weighted graph centrality."""
+    _rehydrate_runtime_state()
     if not _BUILD_META.get("built"):
         return {"ok": False, "honest_error": "org index not built — call build_index first",
                 "repo": repo}
@@ -1309,6 +1879,7 @@ def repo_map(repo: str) -> dict[str, Any]:
 
 def graph_dict() -> dict[str, Any]:
     """Org graph for the 3D UI (nodes/edges). Honest empty state if not built."""
+    _rehydrate_runtime_state()
     d = _GRAPH.to_dict()
     d["built"] = _BUILD_META.get("built", False)
     d["meta"] = _BUILD_META
@@ -1316,8 +1887,18 @@ def graph_dict() -> dict[str, Any]:
 
 
 def status() -> dict[str, Any]:
+    _rehydrate_runtime_state()
+    handle_plane = dict(_BUILD_META.get("brain_handle_plane") or {})
+    handle_plane.setdefault("state", "NOT_INDEXED")
+    handle_plane.setdefault("count", int(_BUILD_META.get("brain_handle_count") or 0))
+    handle_plane["gradient_authority_rows"] = 0
+    handle_plane["training_authority"] = "NONE"
     return {"ok": True, **_BUILD_META, "db_path": RAG_DB_PATH,
             "lambda_floor": _LAMBDA_FLOOR,
+            "brain_handle_plane": handle_plane,
+            "corpus_chunk_count": int(_BUILD_META.get("corpus_chunk_count") or 0),
+            "brain_handle_count": int(_BUILD_META.get("brain_handle_count") or 0),
+            "training_authority_rows": 0,
             "corpus": corpus_manifest(),
             "build_state": build_state()}
 
@@ -1363,9 +1944,16 @@ def build_waqay_backend(bit_width: int = 2,
         return {"ok": False, "honest_error": f"szl_waqay unavailable: {e}", "label": "WAQAY"}
     conn = _db()
     try:
-        rows = list(conn.execute("SELECT chunk_id,dim,vec FROM org_vectors"))
+        _init_schema(conn)
+        generation_id = _active_generation(conn)
+        rows = list(conn.execute(
+            "SELECT chunk_id,dim,vec FROM org_vectors_gen WHERE generation_id=?",
+            (generation_id,))) if generation_id else list(
+                conn.execute("SELECT chunk_id,dim,vec FROM org_vectors"))
     except Exception as e:
+        conn.close()
         return {"ok": False, "honest_error": f"org_vectors unavailable: {e}", "label": "WAQAY"}
+    conn.close()
     if not rows:
         return {"ok": False, "honest_error": "no dense vectors in org_vectors "
                 "(FTS5-only runtime) — WAQAY needs an embedding model present",
@@ -1390,6 +1978,7 @@ def build_waqay_backend(bit_width: int = 2,
     _WAQAY_INDEX = idx
     comp = idx.compression()
     _WAQAY_META = {"built": True, "n": len(ids), "dim": dim, "bit_width": bit_width,
+                   "generation_id": generation_id,
                    "compression_MEASURED": comp,
                    "recall_MODELED": szl_waqay.WaqayIndex.modeled_recall_bound(bit_width),
                    "label": "WAQAY"}
@@ -1418,7 +2007,9 @@ def waqay_query(q: str, k: int = 6, repo: str | None = None,
         return {"ok": False, "honest_error": f"szl_waqay unavailable: {e}",
                 "fallback": query(q, k=k, repo=repo, hyde_text=hyde_text,
                                   emit_receipt=emit_receipt)}
-    if _WAQAY_INDEX is None or not _WAQAY_META.get("built"):
+    active_generation = _BUILD_META.get("generation_id")
+    if (_WAQAY_INDEX is None or not _WAQAY_META.get("built")
+            or _WAQAY_META.get("generation_id") != active_generation):
         b = build_waqay_backend(emit_receipt=emit_receipt)
         if not b.get("ok"):
             # honest fallback to exact path — opting in never costs recall.
@@ -1437,12 +2028,18 @@ def waqay_query(q: str, k: int = 6, repo: str | None = None,
                                      allow=allow, data_label="LIVE")
     # Hydrate returned chunk ids with their text from org_chunks.
     conn = _db()
+    _init_schema(conn)
+    generation_id = _active_generation(conn)
     chunks = []
     for item in gres.get("results", []):
         cid = item["id"]
         try:
-            row = conn.execute("SELECT chunk_id,repo,path,corpus,source,title,body,sha256 "
-                               "FROM org_chunks WHERE chunk_id=?", (cid,)).fetchone()
+            row = (conn.execute(
+                "SELECT chunk_id,repo,path,corpus,source,title,body,sha256 "
+                "FROM org_chunks_gen WHERE generation_id=? AND chunk_id=?",
+                (generation_id, cid)).fetchone() if generation_id else
+                conn.execute("SELECT chunk_id,repo,path,corpus,source,title,body,sha256 "
+                             "FROM org_chunks WHERE chunk_id=?", (cid,)).fetchone())
         except Exception:
             row = None
         if row is not None:
@@ -1453,6 +2050,7 @@ def waqay_query(q: str, k: int = 6, repo: str | None = None,
                            "evidence": {"file": {"path": row["path"], "sha256": row["sha256"]}}})
         else:
             chunks.append({"chunk_id": cid, "score_approx": item["score"]})
+    conn.close()
     if emit_receipt:
         emit_receipt("org_rag.waqay.query", {"query": q[:120], "k": k,
                      "returned": [c["chunk_id"] for c in chunks]})

ayllu/__init__.py

@@ -5,9 +5,10 @@ agent-personas sharing one guarded tool loop, an always-on daemon, an autonomy g
 and a collaboration lounge) and rebuilds it in a11oy's idiom: the active-flux model
 router, the bounded-autonomy AgentLoop, and DSSE receipts.
 
-It deliberately does NOT adopt the tribe's "fully agentic, no sandbox" mandate. Every
-persona here runs under a11oy's fail-closed Λ-gate. See INGEST.md for the full mapping
-and boundary.
+It deliberately does NOT adopt the tribe's "fully agentic, no sandbox" mandate.
+The current runtime performs bounded direct completions with no tool dispatch. A
+separate autonomy gate exists for a future approved tool loop, but it is not claimed
+as active. See INGEST.md for the full mapping and boundary.
 
 Public surface:
     from ayllu.personas import ROSTER, get_persona, load_soul
@@ -18,7 +19,7 @@ Public surface:
 """
 from __future__ import annotations
 
-__version__ = "0.2.0"
+__version__ = "0.3.0"
 NAMESPACE_DEFAULT = "a11oy"
 
 __all__ = ["__version__", "NAMESPACE_DEFAULT"]

ayllu/backend.py

@@ -3,9 +3,9 @@
 Honest wiring: ayllu never talks to a provider directly. It delegates to
 `a11oy_code_orchestrator.agent_model_complete`, which owns model routing (route()),
 resilient fallback, and per-completion energy receipts, and which returns a
-CLEARLY-LABELED deterministic stub (never a fabricated answer) when no inference
-credential is configured. The live/stub decision is a11oy's, resolved at RUNTIME —
-it flips the instant a token is set on the Space, with no redeploy.
+CLEARLY-LABELED deterministic stub (never a fabricated answer) when neither a
+reachable local endpoint nor a credentialed remote provider is available. The
+live/stub decision is a11oy's, resolved at RUNTIME with no redeploy.
 
 Each turn is wrapped in an a11oy OTel span (szl_observability.span) when present.
 Everything here is guarded: if a11oy's modules are absent, model_complete returns an
@@ -15,6 +15,8 @@ from __future__ import annotations
 
 import asyncio
 import contextlib
+import hashlib
+import json
 from typing import Any, Optional
 
 
@@ -48,11 +50,21 @@ def backend_status() -> dict[str, Any]:
             has_cred = bool(orch._resolve_hf_token()) or any(
                 orch._resolve_provider_keys().values())
             _base, local_ready = orch._serving_base()
-            backend_ready = bool(orch.has_inference_credential())
+            readiness = getattr(orch, "inference_backend_ready", None)
+            backend_ready = bool(readiness() if callable(readiness)
+                                 else orch.has_inference_credential() or local_ready)
             cred_checked = True
         except Exception:
             cred_checked = False
 
+    profile_runtime = None
+    if orch is not None:
+        try:
+            profile_status = getattr(orch, "forge_profile_runtime_status", None)
+            profile_runtime = profile_status() if callable(profile_status) else None
+        except Exception:
+            profile_runtime = None
+
     if orch is None:
         mode = "unavailable"
     elif not cred_checked:
@@ -81,6 +93,7 @@ def backend_status() -> dict[str, Any]:
                      "clearly-labeled deterministic stub, no fabrication."),
         }.get(mode, ""),
         "backend": "a11oy_code_orchestrator.agent_model_complete",
+        "forge_profiles": profile_runtime,
     }
 
 
@@ -117,10 +130,63 @@ async def model_complete(
             }
         bounded_tokens = max(1, min(int(max_tokens), 2048))
         bounded_timeout = max(0.1, min(float(timeout_s), 120.0))
+        profile = None
+        try:
+            from .model_binding import persona_binding
+
+            profile = persona_binding(persona or "")["primary_profile"]
+        except Exception:
+            profile = None
+
+        grounding = None
+        if profile == "BrainNavigator-v1":
+            try:
+                grounding = await asyncio.to_thread(
+                    _o.agent_rag_context, prompt or "", k=6)
+            except Exception as exc:
+                grounding = {
+                    "schema": "szl.brain.navigator-context/v1",
+                    "state": "ABSTAIN_RETRIEVAL_ERROR",
+                    "ready": False,
+                    "content_access": "HANDLES_ONLY",
+                    "handles": [],
+                    "evidence": [],
+                    "honesty": f"Brain retrieval raised {type(exc).__name__}; no grounding fabricated",
+                }
+            if not grounding.get("ready"):
+                attestation = None
+                try:
+                    attestation = await asyncio.to_thread(
+                        _o.attest_local_model, profile)
+                except Exception:
+                    pass
+                return {
+                    "text": None,
+                    "model": ((attestation or {}).get("expected_model") or "khipu-unavailable"),
+                    "stub": True,
+                    "timeout": False,
+                    "token_budget": bounded_tokens,
+                    "timeout_s": bounded_timeout,
+                    "honesty": (grounding.get("honesty") or
+                                "no Brain evidence cleared the retrieval gate; abstaining"),
+                    "grounding": grounding,
+                    "model_attestation": attestation,
+                }
+            messages[1]["content"] = (
+                (prompt or "")
+                + "\n\nCANDIDATE_HANDLES_JSON (controller-provided; no node content):\n"
+                + json.dumps(grounding["handles"], sort_keys=True,
+                             separators=(",", ":"), ensure_ascii=False)
+                + "\nReturn a retrieval plan using only offered nodeId values. "
+                  "If none supports the query, return ABSTAIN with zero citations."
+            )
+            grounding["augmented_prompt_sha256"] = hashlib.sha256(
+                messages[1]["content"].encode("utf-8")).hexdigest()
         try:
             result = await asyncio.wait_for(
                 _o.agent_model_complete(
-                    messages, max_tokens=bounded_tokens, temperature=temperature),
+                    messages, max_tokens=bounded_tokens, temperature=temperature,
+                    local_profile=profile),
                 timeout=bounded_timeout,
             )
         except asyncio.TimeoutError:
@@ -159,8 +225,79 @@ async def model_complete(
                 "timeout_s": bounded_timeout,
                 "honesty": "model backend returned a non-contract value; no answer was used",
             }
+        answer = result.get("text", "")
+        if profile == "BrainNavigator-v1" and grounding is not None:
+            citation_state = "NOT_DECLARED_UNSTRUCTURED_OUTPUT"
+            cited_node_ids: list[str] = []
+            citation_error = None
+            if isinstance(answer, str):
+                candidate = answer.strip()
+                if candidate.startswith("```") and candidate.endswith("```"):
+                    candidate = candidate[3:-3].strip()
+                    if candidate.lower().startswith("json"):
+                        candidate = candidate[4:].lstrip()
+                try:
+                    parsed_answer = json.loads(candidate)
+                except (TypeError, ValueError):
+                    parsed_answer = None
+                if isinstance(parsed_answer, dict):
+                    declared = (
+                        parsed_answer.get("citedNodeIds")
+                        if "citedNodeIds" in parsed_answer
+                        else parsed_answer.get("cited_node_ids")
+                        if "cited_node_ids" in parsed_answer
+                        else None
+                    )
+                    if declared is not None:
+                        if (not isinstance(declared, list)
+                                or any(not isinstance(item, str) or not item
+                                       for item in declared)):
+                            citation_state = "INVALID_CITATION_CONTRACT"
+                            citation_error = "cited node IDs must be a list of non-empty strings"
+                        else:
+                            cited_node_ids = list(dict.fromkeys(declared))
+                            offered = {
+                                row.get("nodeId") for row in grounding.get("handles", [])
+                                if isinstance(row, dict) and isinstance(row.get("nodeId"), str)
+                            }
+                            unknown = sorted(set(cited_node_ids) - offered)
+                            if unknown:
+                                citation_state = "UNKNOWN_CITATION_REFUSED"
+                                citation_error = (
+                                    "model cited node IDs outside the controller-offered handle set"
+                                )
+                            else:
+                                citation_state = "CITATIONS_WITHIN_OFFERED_HANDLES"
+            grounding["citation_validation"] = {
+                "state": citation_state,
+                "cited_node_ids": cited_node_ids,
+                "cited_node_ids_sha256": hashlib.sha256(json.dumps(
+                    cited_node_ids, sort_keys=True, separators=(",", ":"),
+                    ensure_ascii=False
+                ).encode("utf-8")).hexdigest(),
+            }
+            if citation_error:
+                grounding["citation_validation"]["honesty"] = citation_error
+                rejected_output_sha256 = (
+                    hashlib.sha256(answer.encode("utf-8")).hexdigest()
+                    if isinstance(answer, str) else None
+                )
+                grounding["rejected_model_output_sha256"] = rejected_output_sha256
+                return {
+                    "text": None,
+                    "model": result.get("model"),
+                    "stub": True,
+                    "timeout": bool(result.get("timeout", False)),
+                    "token_budget": bounded_tokens,
+                    "timeout_s": bounded_timeout,
+                    "honesty": citation_error + "; no ungrounded model text returned",
+                    "raw_model_output_sha256": rejected_output_sha256,
+                    "energy_receipt": result.get("energy_receipt"),
+                    "model_attestation": result.get("model_attestation"),
+                    "grounding": grounding,
+                }
         return {
-            "text": result.get("text", ""),
+            "text": answer,
             "model": result.get("model"),
             "stub": bool(result.get("stub")),
             "timeout": bool(result.get("timeout", False)),
@@ -168,4 +305,6 @@ async def model_complete(
             "timeout_s": bounded_timeout,
             "honesty": result.get("honesty"),
             "energy_receipt": result.get("energy_receipt"),
+            "model_attestation": result.get("model_attestation"),
+            "grounding": grounding,
         }

ayllu/loop.py

@@ -65,7 +65,10 @@ async def run_turn(
     """
     diff = persona.default_difficulty if difficulty is None else float(difficulty)
     tier = select_tier(diff)
-    system = persona.system_prompt()
+    from .model_binding import persona_binding, prompt_contract
+
+    binding = persona_binding(persona.name)
+    system = persona.system_prompt() + "\n\n" + prompt_contract(binding)
 
     answer: Optional[str] = None
     model: Optional[str] = None
@@ -74,6 +77,8 @@ async def run_turn(
     token_budget: Optional[int] = None
     timeout_s: Optional[float] = None
     energy_receipt: Any = None
+    model_attestation: Any = None
+    grounding: Any = None
 
     if model_complete is None:
         honesty = ("model backend not injected — no answer fabricated. This turn "
@@ -108,16 +113,27 @@ async def run_turn(
                 token_budget = result.get("token_budget")
                 timeout_s = result.get("timeout_s")
                 energy_receipt = result.get("energy_receipt")
+                model_attestation = result.get("model_attestation")
+                grounding = result.get("grounding")
             else:
                 answer = str(result)
             honesty = "answer produced by a11oy's model backend" + (
-                " (clearly-labeled stub — no inference credential set)" if stub else "")
+                " (clearly-labeled stub — no reachable local or credentialed remote backend)"
+                if stub else "")
             if isinstance(result, dict) and result.get("honesty"):
                 honesty = str(result["honesty"])
         except Exception as exc:
             honesty = (f"model backend raised: {str(exc)[:120]} "
                        "(honest — no fabricated answer)")
 
+    binding = persona_binding(
+        persona.name,
+        actual_model=model,
+        backend_mode=("stub" if stub else "live" if model else "unavailable"),
+        model_attestation=model_attestation,
+        grounding=grounding,
+    )
+
     return {
         "persona": persona.name,
         "quechua": persona.quechua,
@@ -134,6 +150,10 @@ async def run_turn(
         "token_budget": token_budget,
         "timeout_s": timeout_s,
         "energy_receipt": energy_receipt,
+        "model_attestation": model_attestation,
+        "grounding": grounding,
+        "model_binding": binding,
         "honesty": honesty,
-        "evidence": [],
+        "evidence": (grounding.get("evidence", [])
+                     if isinstance(grounding, dict) else []),
     }

ayllu/lounge.py

@@ -1,10 +1,11 @@
 """ayllu.lounge — the collaboration surface, learned from the tribe lounge/bus.
 
 The tribe let souls talk in a shared room. a11oy keeps that, in-memory and honest: each
-posted message carries a source label ("brain" when a real model answered, else
-"persona-fallback"), so a reader always knows whether they are seeing a grounded reply
-or an honest placeholder. `deliberate()` runs a BOUNDED council round — one honest turn
-per persona — and never fabricates when no backend is injected.
+posted message carries a source label ("model-unverified" when a model answered,
+else "persona-fallback"), so a reader never mistakes direct model text for grounded
+Brain retrieval. `deliberate()` runs a BOUNDED council round — one honest turn
+per persona — and never fabricates when no backend is injected. Publishing is
+explicit opt-in; public ask/council calls keep their output out of this feed.
 """
 from __future__ import annotations
 
@@ -37,6 +38,7 @@ class Lounge:
         difficulty: float = 0.6,
         two_person_attested: bool = False,
         debate: bool = False,
+        publish_to_lounge: bool = False,
     ) -> dict[str, Any]:
         from .loop import run_turn
 
@@ -53,8 +55,10 @@ class Lounge:
         )))
         for p, turn in zip(personas, rounds):
             turn["round"] = 1
-            src = "brain" if turn.get("answer") is not None else "persona-fallback"
-            self.post(p.name, turn.get("answer") or turn.get("honesty"), source=src)
+            src = ("model-unverified" if turn.get("answer") is not None
+                   and not turn.get("stub") else "persona-fallback")
+            if publish_to_lounge:
+                self.post(p.name, turn.get("answer") or turn.get("honesty"), source=src)
 
         mode = "single-round"
         # Debate-then-converge (after arXiv:2305.14325, Multiagent Debate): one
@@ -88,10 +92,11 @@ class Lounge:
                 )))
                 for (p, _turn_prompt), turn in zip(debate_jobs, revised):
                     turn["round"] = 2
-                    src = ("brain" if turn.get("answer") is not None
-                           else "persona-fallback")
-                    self.post(p.name, turn.get("answer") or turn.get("honesty"),
-                              source=src)
+                    src = ("model-unverified" if turn.get("answer") is not None
+                           and not turn.get("stub") else "persona-fallback")
+                    if publish_to_lounge:
+                        self.post(p.name, turn.get("answer") or turn.get("honesty"),
+                                  source=src)
                     rounds.append(turn)
             else:
                 mode = "single-round"
@@ -101,6 +106,7 @@ class Lounge:
             "participants": [p.name for p in personas],
             "rounds": rounds,
             "mode": mode,
+            "published_to_lounge": publish_to_lounge,
             "note": "bounded council; each turn honest (no fabrication when a model "
                     "backend is absent); debate mode = exactly two rounds, "
                     "after arXiv:2305.14325",

ayllu/model_binding.py

@@ -0,0 +1,402 @@
+# SPDX-License-Identifier: Apache-2.0
+"""Honest runtime binding between the Ayllu council and SZL-Forge.
+
+Ayllu personas are task roles sharing A11oy's routed model backend.  They are
+not eleven separately trained models.  This module binds each role to a
+declared SZL-Forge profile and a bounded set of *proposal* capabilities while
+leaving execution, approval, signing, and verification in independent runtime
+organs.
+"""
+from __future__ import annotations
+
+import copy
+import json
+from typing import Any, Mapping
+
+
+SCHEMA = "szl.ayllu.model-family-binding/v1"
+SECOND_BRAIN_SCHEMA = "szl.khipu.compound-second-brain.v1"
+FAMILY_ID = "SZL-Forge-1.5B"
+COMPUTE_PLANE = "SZL-Yupaq"
+BINDING_STATE = "PROFILE_AWARE_LOCAL_ROUTING_ARTIFACT_BINDING_PARTIAL"
+
+_ALL_COMPUTE_OPERATIONS = (
+    "formula.org_lambda.weighted_geomean",
+    "quant.sample.pipeline",
+    "quantum.qubo.exact_baseline",
+    "numerics.external.run",
+    "numerics.external.compare",
+    "proof.lean.inventory",
+    "formula.admission.inventory",
+    "brain.corpus.inventory",
+    "lake.evidence.inventory",
+)
+
+_PROFILE_STATES = {
+    "ReceiptAgent-v1": "SIGNED_RECEIPTS_VALID_ARTIFACT_BINDING_CONFLICT",
+    "BrainNavigator-v1": "SIGNED_RECEIPTS_VALID_ARTIFACT_BINDING_CONFLICT",
+    "Operator-v1": "PLANNED_TOOL_CONTRACT_REQUIRED",
+    "Sentinel-v1": "PLANNED_SECURITY_ADMISSION_REQUIRED",
+    "Anatomy-v1": "PLANNED_ONTOLOGY_ADMISSION_REQUIRED",
+}
+
+_PERSONA_BINDINGS: dict[str, dict[str, Any]] = {
+    "Amaru": {
+        "primary_profile": "Operator-v1",
+        "supporting_profiles": ["Anatomy-v1"],
+        "proposal_surfaces": ["architecture.review", "anatomy.inspect"],
+        "compute_operations": [],
+    },
+    "Ruwaq": {
+        "primary_profile": "Operator-v1",
+        "supporting_profiles": [],
+        "proposal_surfaces": ["code.plan", "build.review", "compute.submit"],
+        "compute_operations": [
+            "proof.lean.inventory",
+            "formula.admission.inventory",
+            "brain.corpus.inventory",
+            "lake.evidence.inventory",
+        ],
+    },
+    "Yupaq": {
+        "primary_profile": "ReceiptAgent-v1",
+        "supporting_profiles": ["BrainNavigator-v1"],
+        "proposal_surfaces": ["compute.submit", "receipt.verify", "proof.review"],
+        "compute_operations": list(_ALL_COMPUTE_OPERATIONS),
+    },
+    "Qhaway": {
+        "primary_profile": "Sentinel-v1",
+        "supporting_profiles": ["Anatomy-v1"],
+        "proposal_surfaces": ["simulation.review", "failure.evaluate"],
+        "compute_operations": ["quantum.qubo.exact_baseline"],
+    },
+    "Maskaq": {
+        "primary_profile": "BrainNavigator-v1",
+        "supporting_profiles": ["ReceiptAgent-v1"],
+        "proposal_surfaces": ["brain.query", "evidence.retrieve", "citation.review"],
+        "compute_operations": [
+            "brain.corpus.inventory",
+            "formula.admission.inventory",
+            "lake.evidence.inventory",
+        ],
+    },
+    "Hampiq": {
+        "primary_profile": "Anatomy-v1",
+        "supporting_profiles": ["Sentinel-v1"],
+        "proposal_surfaces": ["health.inspect", "remediation.propose"],
+        "compute_operations": ["lake.evidence.inventory"],
+    },
+    "Yanapaq": {
+        "primary_profile": "Operator-v1",
+        "supporting_profiles": [],
+        "proposal_surfaces": ["ops.review", "incident.support"],
+        "compute_operations": [],
+    },
+    "Chaka": {
+        "primary_profile": "Operator-v1",
+        "supporting_profiles": ["ReceiptAgent-v1"],
+        "proposal_surfaces": ["connector.review", "contract.crosswalk"],
+        "compute_operations": [],
+    },
+    "Kamachiq": {
+        "primary_profile": "Operator-v1",
+        "supporting_profiles": ["ReceiptAgent-v1"],
+        "proposal_surfaces": ["route.review", "plan.sequence", "approval.request"],
+        "compute_operations": [],
+    },
+    "Qhatuq": {
+        "primary_profile": "ReceiptAgent-v1",
+        "supporting_profiles": [],
+        "proposal_surfaces": ["risk.review", "quant.compute"],
+        "compute_operations": [
+            "quant.sample.pipeline",
+            "formula.org_lambda.weighted_geomean",
+        ],
+    },
+    "Willakuq": {
+        "primary_profile": "ReceiptAgent-v1",
+        "supporting_profiles": [],
+        "proposal_surfaces": ["receipt.verify", "provenance.review", "archive.propose"],
+        "compute_operations": ["lake.evidence.inventory"],
+    },
+}
+
+_HARD_BOUNDARIES = {
+    "personas_are_separate_weights": False,
+    "tool_dispatch_active": False,
+    "can_execute_external_actions": False,
+    "can_approve_own_proposal": False,
+    "can_sign_own_evidence": False,
+    "can_self_certify_correctness": False,
+    "model_output_is_verified_truth": False,
+    "automatic_lounge_publish": False,
+    "compute_execution_location": "SZL-Yupaq external governed computation plane",
+    "binding_rule": "MODEL_PROPOSES; YUPAQ_VALIDATES_SCHEMA; ENGINE_COMPUTES; HONESTY_LABELS; RECEIPT_BINDS",
+}
+
+
+def persona_binding(
+    name: str,
+    *,
+    actual_model: Any = None,
+    backend_mode: str | None = None,
+    model_attestation: Mapping[str, Any] | None = None,
+    grounding: Mapping[str, Any] | None = None,
+) -> dict[str, Any]:
+    """Return one role's immutable model/control-plane binding."""
+    canonical = next((key for key in _PERSONA_BINDINGS if key.lower() == (name or "").lower()), None)
+    if canonical is None:
+        raise KeyError(f"unknown Ayllu persona: {name}")
+    binding = copy.deepcopy(_PERSONA_BINDINGS[canonical])
+    primary = binding["primary_profile"]
+    attestation = copy.deepcopy(dict(model_attestation or {})) or None
+    grounding_summary = None
+    if grounding:
+        grounding_summary = {
+            "schema": grounding.get("schema"),
+            "state": grounding.get("state"),
+            "content_access": grounding.get("content_access"),
+            "query_sha256": grounding.get("query_sha256"),
+            "evidence_set_sha256": grounding.get("evidence_set_sha256"),
+            "handles_sha256": grounding.get("handles_sha256"),
+            "augmented_prompt_sha256": grounding.get("augmented_prompt_sha256"),
+            "handle_evidence_set_equivalent": grounding.get(
+                "handle_evidence_set_equivalent"),
+            "citation_validation": copy.deepcopy(
+                grounding.get("citation_validation")),
+            "rejected_model_output_sha256": grounding.get(
+                "rejected_model_output_sha256"),
+            "grounded_count": grounding.get("grounded_count"),
+        }
+    attested_served_model = (
+        attestation.get("served_model") if attestation is not None else None)
+    model_identity_reconciled = (
+        actual_model == attested_served_model
+        if isinstance(attested_served_model, str) and attested_served_model
+        else None
+    )
+    binding.update({
+        "schema": SCHEMA,
+        "persona": canonical,
+        "family_id": FAMILY_ID,
+        "binding_state": BINDING_STATE,
+        "profile_state": _PROFILE_STATES[primary],
+        "actual_model": actual_model,
+        "backend_mode": backend_mode or "NOT_OBSERVED",
+        "actual_model_authority": "turn receipt and router evidence",
+        "attested_served_model": attested_served_model,
+        "model_identity_reconciled": model_identity_reconciled,
+        "model_attestation": attestation,
+        "model_attestation_sha256": (
+            _canonical_sha256(attestation) if attestation is not None else None
+        ),
+        "grounding": grounding_summary,
+        "grounding_sha256": (
+            _canonical_sha256(grounding_summary) if grounding_summary is not None else None
+        ),
+        "compute_plane": COMPUTE_PLANE,
+        "authority": "PROPOSAL_ONLY",
+        "hard_boundaries": copy.deepcopy(_HARD_BOUNDARIES),
+    })
+    return binding
+
+
+def family_binding(
+    *,
+    namespace: str = "a11oy",
+    backend_status: Mapping[str, Any] | None = None,
+) -> dict[str, Any]:
+    """Return the machine-readable Ayllu-to-Forge family contract."""
+    status = dict(backend_status or {})
+    profile_runtime = status.get("forge_profiles")
+    return {
+        "schema": SCHEMA,
+        "family_id": FAMILY_ID,
+        "binding_state": BINDING_STATE,
+        "runtime_backend": status,
+        "runtime_backend_is_profile_pinned": False,
+        "runtime_profile_status": profile_runtime,
+        "profile_pin_requirement": (
+            "The exact profile tag must be observed, its immutable weight/blob digest must "
+            "match a signed release manifest, and the turn receipt must bind that attestation."
+        ),
+        "personas": [persona_binding(name) for name in _PERSONA_BINDINGS],
+        "compute": {
+            "plane_id": COMPUTE_PLANE,
+            "capabilities_endpoint": f"/api/{namespace}/v1/compute/capabilities",
+            "submit_endpoint": f"/api/{namespace}/v1/compute/jobs",
+            "allowed_operations": list(_ALL_COMPUTE_OPERATIONS),
+            "dispatch_state": "PROPOSAL_ONLY_NOT_ACTIVE_IN_AYLLU_LOOP",
+            "stateful_routes_require_auth": True,
+        },
+        "hard_boundaries": copy.deepcopy(_HARD_BOUNDARIES),
+    }
+
+
+def second_brain_binding(
+    *,
+    namespace: str = "a11oy",
+    backend_status: Mapping[str, Any] | None = None,
+    rag_status: Mapping[str, Any] | None = None,
+    signer_ready: bool = False,
+) -> dict[str, Any]:
+    """Describe the Khipu Second Brain as an evidence-bound compound model.
+
+    The generator tag, persistent retrieval index, controller, and receipt
+    verifier are independent components.  Keeping that separation explicit
+    prevents an index row count from being mislabeled as parameters or trained
+    weights while still exposing one operational system contract.
+    """
+    backend = copy.deepcopy(dict(backend_status or {}))
+    rag = copy.deepcopy(dict(rag_status or {}))
+    profile_runtime = (
+        (backend.get("forge_profiles") or {}).get("profiles") or {}
+    ).get("BrainNavigator-v1") or {}
+    exact_tag_observed = bool(profile_runtime.get("available"))
+    index_ready = bool(rag.get("built"))
+    ready = exact_tag_observed and index_ready
+    if ready:
+        state = "READY_FOR_GROUNDED_NAVIGATION_ARTIFACT_UNBOUND"
+    elif not exact_tag_observed and not index_ready:
+        state = "UNAVAILABLE_MODEL_AND_INDEX"
+    elif not exact_tag_observed:
+        state = "UNAVAILABLE_MODEL_TAG_MISSING"
+    else:
+        state = "UNAVAILABLE_INDEX_NOT_BUILT"
+    return {
+        "schema": SECOND_BRAIN_SCHEMA,
+        "system_id": "SZL-Khipu-Second-Brain-v1",
+        "system_type": "COMPOUND_MODEL_WITH_EXTERNAL_EVIDENCE_MEMORY",
+        "state": state,
+        "ready_for_grounded_navigation": ready,
+        "live_grounded_turn_verified_this_request": False,
+        "signer_ready_this_request": bool(signer_ready),
+        "promotion_state": "BLOCKED_ARTIFACT_AND_EVAL_GATES",
+        "profile": {
+            "profile_id": "BrainNavigator-v1",
+            "expected_model": profile_runtime.get("expected_model", "khipu:latest"),
+            "served_model": profile_runtime.get("served_model"),
+            "exact_tag_observed": exact_tag_observed,
+            "artifact_binding": "UNBOUND",
+            "turn_level_attestation_required": True,
+        },
+        "memory": {
+            "kind": "PERSISTENT_SQLITE_HYBRID_RETRIEVAL_GRAPH",
+            "built": index_ready,
+            "document_count": rag.get("document_count", rag.get("files")),
+            "chunk_count": rag.get("chunk_count", rag.get("chunks")),
+            "corpus_chunk_count": rag.get(
+                "corpus_chunk_count", rag.get("chunk_count", rag.get("chunks"))
+            ),
+            "brain_handle_count": rag.get("brain_handle_count", 0),
+            "brain_handle_plane": rag.get("brain_handle_plane"),
+            "training_authority_rows": rag.get("training_authority_rows", 0),
+            "node_count": rag.get("node_count"),
+            "edge_count": rag.get("edge_count"),
+            "generation_id": rag.get("generation_id"),
+            "generation_digest_sha256": rag.get("generation_digest_sha256"),
+            "integrity_state": rag.get("integrity_state"),
+            "rehydration_state": rag.get("rehydration_state"),
+            "corpus": rag.get("corpus"),
+            "index_mode": rag.get("mode"),
+            "scope_boundary": (
+                "Corpus chunks and the canonical 9,464-node Brain handle plane are "
+                "separate, independently counted retrieval planes. Handles preserve "
+                "source and quarantine metadata and grant no gradient authority."
+            ),
+            "evidence_access": "HANDLES_ONLY_TO_MODEL; CONTENT_STAYS_IN_CONTROLLER",
+        },
+        "grounding": {
+            "ask_endpoint": f"/api/{namespace}/v1/ayllu/ask",
+            "persona": "Maskaq",
+            "query_endpoint": f"/api/{namespace}/code/rag/query",
+            "required_receipt_fields": [
+                "evidence_set_sha256",
+                "handles_sha256",
+                "augmented_prompt_sha256",
+                "grounding_sha256",
+                "model_attestation_sha256",
+                "turn_output_sha256",
+            ],
+            "abstain_when_ungrounded": True,
+        },
+        "training_boundary": {
+            "raw_brain_nodes_observed": 9464,
+            "raw_brain_nodes_admitted_to_gradients": 0,
+            "admission_is_row_level": True,
+            "admission_engine": "szl_brain_training_admission.py",
+            "admission_contract": "szl.brain-training-admission-report.v1",
+            "evidence_security": "ED25519_ALLOWLISTED_ISSUER_TOOL_KEY",
+            "required_signed_inputs": [
+                "protected_eval_content_sha256_list",
+                "signed_evidence_trust_store",
+                "signed_prior_split_ledger_descriptor",
+            ],
+            "current_state": (
+                "ROW_LEVEL_ADMISSION_ENGINE_IMPLEMENTED_CURRENT_RAW_ROWS_QUARANTINED"
+            ),
+            "required": [
+                "stable_node_id",
+                "content_sha256",
+                "immutable_source_revision",
+                "rights_basis_and_license",
+                "source_timestamp_and_freshness",
+                "canonical_state",
+                "dedup_group",
+                "contamination_result",
+                "immutable_split",
+                "cross_run_split_ledger_binding",
+            ],
+            "honesty": (
+                "All graph nodes may participate in retrieval and evaluation; only "
+                "independently admitted rows may enter gradients."
+            ),
+        },
+        "hard_boundaries": {
+            "index_is_model_weights": False,
+            "retrieval_is_training": False,
+            "model_can_read_raw_node_content": False,
+            "model_can_write_canonical_memory": False,
+            "model_can_self_certify_grounding": False,
+        },
+    }
+
+
+def prompt_contract(binding: Mapping[str, Any]) -> str:
+    """Serialize the binding into a compact system-prompt control contract."""
+    compact = {
+        "schema": binding.get("schema"),
+        "family_id": binding.get("family_id"),
+        "persona": binding.get("persona"),
+        "primary_profile": binding.get("primary_profile"),
+        "profile_state": binding.get("profile_state"),
+        "authority": binding.get("authority"),
+        "proposal_surfaces": binding.get("proposal_surfaces"),
+        "compute_operations": binding.get("compute_operations"),
+        "binding_rule": (binding.get("hard_boundaries") or {}).get("binding_rule"),
+    }
+    return (
+        "A11OY MODEL-BINDING CONTRACT (machine-readable; binding):\n"
+        + json.dumps(compact, sort_keys=True, separators=(",", ":"), ensure_ascii=False)
+        + "\nYou may propose only. Never claim that a proposal was executed, approved, "
+          "signed, kernel-verified, or trained unless an independent receipt is present."
+    )
+
+
+def _canonical_sha256(value: Any) -> str:
+    return __import__("hashlib").sha256(json.dumps(
+        value, sort_keys=True, separators=(",", ":"), ensure_ascii=False
+    ).encode("utf-8")).hexdigest()
+
+
+__all__ = [
+    "BINDING_STATE",
+    "COMPUTE_PLANE",
+    "FAMILY_ID",
+    "SCHEMA",
+    "SECOND_BRAIN_SCHEMA",
+    "family_binding",
+    "persona_binding",
+    "prompt_contract",
+    "second_brain_binding",
+]

ayllu/selftest.py

@@ -48,7 +48,8 @@ def main() -> None:
     # Lounge deliberation, honest (no backend => no fabricated answers).
     lounge = Lounge()
     res = asyncio.run(lounge.deliberate(
-        "What are the risks?", [get_persona("qhatuq"), get_persona("qhaway")]))
+        "What are the risks?", [get_persona("qhatuq"), get_persona("qhaway")],
+        publish_to_lounge=True))
     assert len(res["rounds"]) == 2
     assert all(r["answer"] is None for r in res["rounds"])
     assert len(lounge.recent()) == 2
@@ -64,8 +65,8 @@ def main() -> None:
         assert wired["stub"] is True and wired["answer"] and \
             "honest" in wired["answer"].lower(), wired
 
-    print(f"AYLLU SELFTEST OK — {len(ROSTER)} personas; tier router + bounded loop "
-          f"honest fallbacks; Λ-gate fail-closed; lounge honest; backend mode="
+    print(f"AYLLU SELFTEST OK - {len(ROSTER)} personas; tier router + bounded loop "
+          f"honest fallbacks; Lambda-gate fail-closed; lounge honest; backend mode="
           f"{st['mode']}.")
 
 

model_release/receipt-agent/receipt_runtime.py

@@ -0,0 +1,511 @@
+"""Deterministic draft-to-envelope bridge for SZL-Forge ReceiptAgent.
+
+The model emits ``szl.forge-receipt-draft.v1``.  This module never trusts the
+model to admit evidence, determine formula proof status, authorize a tool, or
+sign a receipt.  It resolves those facts from caller-supplied immutable
+snapshots and only returns an ANSWERED final envelope when an external receipt
+has already been verified against the exact computed bindings.
+
+This module performs no network calls, tool execution, signing, or secret
+access.  Those remain deployment boundaries of the A11oy runtime.
+"""
+
+from __future__ import annotations
+
+import base64
+import hashlib
+import hmac
+import json
+import re
+import threading
+from copy import deepcopy
+from typing import Any, Mapping
+
+
+DRAFT_SCHEMA_VERSION = "szl.forge-receipt-draft.v1"
+FINAL_SCHEMA_VERSION = "szl.receipt-agent-output.v1"
+CANONICAL_CANDIDATE_ID = "SZL-Forge-1.5B-ReceiptAgent-v1"
+RECEIPT_PAYLOAD_TYPE = "application/vnd.szl.receipt-agent-binding+json"
+SHA256_RE = re.compile(r"^[0-9a-f]{64}$")
+EVIDENCE_ID_RE = re.compile(r"^(fixture|brain|artifact|source|receipt):[A-Za-z0-9._:/-]+$")
+FINAL_EVIDENCE_ID_RE = re.compile(r"^(brain|artifact|source|receipt):[A-Za-z0-9._:/-]+$")
+FORMULA_STATUS = {"KERNEL_ACCEPTED", "CONDITIONAL", "OPEN", "REFUTED", "NOT_EVALUATED"}
+ABSTENTION_CODES = {
+    "NONE",
+    "MODEL_UNAVAILABLE",
+    "EVIDENCE_NOT_ADMITTED",
+    "EVIDENCE_INSUFFICIENT",
+    "FORMULA_NAMESPACE_CONFLICT",
+    "RECEIPT_INVALID",
+    "POLICY_DENIED",
+    "UNCERTAINTY_TOO_HIGH",
+}
+
+
+class ReceiptRuntimeError(ValueError):
+    """Raised when an input violates the deterministic runtime contract."""
+
+
+class ReceiptReplayGuard:
+    """Process-local single-use guard; deployments must back this with durable storage."""
+
+    def __init__(self) -> None:
+        self._lock = threading.Lock()
+        self._consumed: set[str] = set()
+
+    def consume(self, receipt_id: str) -> bool:
+        with self._lock:
+            if receipt_id in self._consumed:
+                return False
+            self._consumed.add(receipt_id)
+            return True
+
+
+def canonical_bytes(value: Any) -> bytes:
+    return json.dumps(
+        value,
+        sort_keys=True,
+        separators=(",", ":"),
+        ensure_ascii=False,
+        allow_nan=False,
+    ).encode("utf-8")
+
+
+def canonical_sha256(value: Any) -> str:
+    return hashlib.sha256(canonical_bytes(value)).hexdigest()
+
+
+def _dsse_pae(payload_type: str, payload: bytes) -> bytes:
+    payload_type_bytes = payload_type.encode("utf-8")
+    return b"DSSEv1 %d %b %d %b" % (
+        len(payload_type_bytes),
+        payload_type_bytes,
+        len(payload),
+        payload,
+    )
+
+
+def _verify_hmac_dsse(envelope: Any, key: bytes) -> dict[str, Any]:
+    """Verify a non-stub HMAC-SHA256 DSSE envelope and return its JSON payload."""
+
+    _require(isinstance(key, bytes) and len(key) >= 32, "receipt HMAC key must contain at least 32 bytes")
+    _require(isinstance(envelope, dict), "receipt envelope must be an object")
+    _require_exact_keys(envelope, {"payloadType", "payload", "signatures"}, "receipt envelope")
+    _require(envelope["payloadType"] == RECEIPT_PAYLOAD_TYPE, "unexpected receipt payload type")
+    _require(isinstance(envelope["payload"], str), "receipt payload must be base64 text")
+    _require(isinstance(envelope["signatures"], list) and len(envelope["signatures"]) == 1, "exactly one receipt signature is required")
+    signature = envelope["signatures"][0]
+    _require(isinstance(signature, dict), "receipt signature must be an object")
+    _require_exact_keys(signature, {"keyid", "scheme", "sig"}, "receipt signature")
+    _require(signature["scheme"] == "hmac-sha256", "stub or unsupported receipt signature scheme")
+    _require(isinstance(signature["keyid"], str) and bool(signature["keyid"]), "receipt key id required")
+    try:
+        payload = base64.b64decode(envelope["payload"], validate=True)
+        actual = base64.b64decode(signature["sig"], validate=True)
+    except Exception as exc:  # pragma: no cover - exact decoder exception is platform-specific
+        raise ReceiptRuntimeError("invalid receipt base64") from exc
+    expected = hmac.new(key, _dsse_pae(RECEIPT_PAYLOAD_TYPE, payload), hashlib.sha256).digest()
+    _require(hmac.compare_digest(actual, expected), "receipt DSSE signature verification failed")
+    try:
+        value = json.loads(payload.decode("utf-8"))
+    except (UnicodeDecodeError, json.JSONDecodeError) as exc:
+        raise ReceiptRuntimeError("receipt payload is not canonical JSON") from exc
+    _require(canonical_bytes(value) == payload, "receipt payload is not canonically encoded")
+    _require(isinstance(value, dict), "receipt payload must be an object")
+    return value
+
+
+def _require(condition: bool, message: str) -> None:
+    if not condition:
+        raise ReceiptRuntimeError(message)
+
+
+def _require_exact_keys(value: Mapping[str, Any], keys: set[str], label: str) -> None:
+    actual = set(value)
+    _require(actual == keys, f"{label} keys mismatch: expected {sorted(keys)}, got {sorted(actual)}")
+
+
+def validate_draft(draft: Any) -> None:
+    """Validate the full checked-in draft contract without optional packages."""
+
+    _require(isinstance(draft, dict), "draft must be an object")
+    _require_exact_keys(
+        draft,
+        {
+            "schema_version",
+            "status",
+            "answer",
+            "evidence_ids",
+            "formula_refs",
+            "uncertainty",
+            "abstention",
+            "tool_proposal",
+        },
+        "draft",
+    )
+    _require(draft["schema_version"] == DRAFT_SCHEMA_VERSION, "unsupported draft schema")
+    status = draft["status"]
+    _require(status in {"ANSWER_PROPOSED", "ABSTAINED", "UNAVAILABLE"}, "invalid draft status")
+
+    evidence_ids = draft["evidence_ids"]
+    _require(isinstance(evidence_ids, list), "evidence_ids must be an array")
+    _require(len(evidence_ids) == len(set(evidence_ids)), "evidence_ids must be unique")
+    _require(
+        all(isinstance(item, str) and EVIDENCE_ID_RE.fullmatch(item) for item in evidence_ids),
+        "invalid evidence id",
+    )
+
+    formula_refs = draft["formula_refs"]
+    _require(isinstance(formula_refs, list), "formula_refs must be an array")
+    formula_keys: set[tuple[str, str]] = set()
+    for index, formula in enumerate(formula_refs):
+        _require(isinstance(formula, dict), f"formula_refs[{index}] must be an object")
+        _require_exact_keys(formula, {"namespace", "formula_id", "claimed_status"}, f"formula_refs[{index}]")
+        namespace = formula["namespace"]
+        formula_id = formula["formula_id"]
+        _require(isinstance(namespace, str) and bool(namespace), "formula namespace required")
+        _require(isinstance(formula_id, str) and bool(formula_id), "formula id required")
+        _require(formula["claimed_status"] in FORMULA_STATUS, "invalid claimed formula status")
+        key = (namespace, formula_id)
+        _require(key not in formula_keys, "formula references must be unique")
+        formula_keys.add(key)
+
+    uncertainty = draft["uncertainty"]
+    _require(isinstance(uncertainty, dict), "uncertainty must be an object")
+    _require_exact_keys(uncertainty, {"band", "basis"}, "uncertainty")
+    _require(uncertainty["band"] in {"LOW", "MEDIUM", "HIGH", "NOT_EVALUATED"}, "invalid uncertainty band")
+    _require(isinstance(uncertainty["basis"], str) and bool(uncertainty["basis"]), "uncertainty basis required")
+
+    abstention = draft["abstention"]
+    _require(isinstance(abstention, dict), "abstention must be an object")
+    _require_exact_keys(abstention, {"required", "code", "detail"}, "abstention")
+    _require(isinstance(abstention["required"], bool), "abstention.required must be boolean")
+    _require(abstention["code"] in ABSTENTION_CODES, "invalid abstention code")
+    _require(isinstance(abstention["detail"], str) and bool(abstention["detail"]), "abstention detail required")
+
+    tool = draft["tool_proposal"]
+    _require(isinstance(tool, dict), "tool_proposal must be an object")
+    _require_exact_keys(tool, {"state", "tool_id", "arguments"}, "tool_proposal")
+    _require(tool["state"] in {"NONE", "PROPOSED"}, "invalid tool state")
+    if tool["state"] == "NONE":
+        _require(tool["tool_id"] is None and tool["arguments"] is None, "NONE tool must have null identity and arguments")
+    else:
+        _require(status == "ANSWER_PROPOSED", "only an answer proposal may contain a tool proposal")
+        _require(isinstance(tool["tool_id"], str) and bool(tool["tool_id"]), "proposed tool id required")
+        _require(isinstance(tool["arguments"], dict) and bool(tool["arguments"]), "proposed tool arguments required")
+
+    if status == "ANSWER_PROPOSED":
+        _require(isinstance(draft["answer"], str) and bool(draft["answer"]), "answer proposal requires text")
+        _require(bool(evidence_ids), "answer proposal requires evidence")
+        _require(uncertainty["band"] in {"LOW", "MEDIUM"}, "answer proposal uncertainty is too high")
+        _require(abstention["required"] is False and abstention["code"] == "NONE", "answer proposal cannot abstain")
+    elif status == "ABSTAINED":
+        _require(draft["answer"] is None, "abstention cannot carry answer text")
+        _require(not evidence_ids and not formula_refs, "abstention cannot carry model-selected evidence or formulae")
+        _require(uncertainty["band"] == "HIGH", "abstention must report HIGH uncertainty")
+        _require(abstention["required"] is True and abstention["code"] not in {"NONE", "MODEL_UNAVAILABLE"}, "invalid abstention state")
+        _require(tool["state"] == "NONE", "abstention cannot propose a tool")
+    else:
+        _require(draft["answer"] is None, "unavailable response cannot carry answer text")
+        _require(not evidence_ids and not formula_refs, "unavailable response cannot carry evidence or formulae")
+        _require(uncertainty["band"] == "NOT_EVALUATED", "unavailable response must be NOT_EVALUATED")
+        _require(abstention["required"] is True and abstention["code"] == "MODEL_UNAVAILABLE", "invalid unavailable state")
+        _require(tool["state"] == "NONE", "unavailable response cannot propose a tool")
+
+
+def _validate_model_identity(model_identity: Any) -> dict[str, Any]:
+    _require(isinstance(model_identity, dict), "model identity must be an object")
+    required = {"candidate_id", "release_state", "base_repository", "base_revision", "adapter_sha256"}
+    _require_exact_keys(model_identity, required, "model_identity")
+    _require(model_identity["candidate_id"] == CANONICAL_CANDIDATE_ID, "unexpected candidate identity")
+    _require(model_identity["release_state"] in {"EXPERIMENTAL", "PROMOTED"}, "a trained runtime identity is required")
+    _require(isinstance(model_identity["base_repository"], str) and bool(model_identity["base_repository"]), "base repository required")
+    _require(isinstance(model_identity["base_revision"], str) and re.fullmatch(r"[0-9a-f]{40}", model_identity["base_revision"]), "invalid base revision")
+    _require(isinstance(model_identity["adapter_sha256"], str) and SHA256_RE.fullmatch(model_identity["adapter_sha256"]), "verified adapter digest required")
+    return deepcopy(model_identity)
+
+
+def _empty_final(
+    *,
+    draft: Mapping[str, Any],
+    request: Any,
+    policy_snapshot: Any,
+    model_identity: Mapping[str, Any],
+    status: str,
+    code: str,
+    detail: str,
+    calibration_state: str,
+) -> dict[str, Any]:
+    response_seed = {"draft": draft, "request": request, "policy": policy_snapshot, "model": model_identity}
+    return {
+        "schema_version": FINAL_SCHEMA_VERSION,
+        "response_id": f"response:{canonical_sha256(response_seed)[:24]}",
+        "model_identity": deepcopy(model_identity),
+        "status": status,
+        "answer": None,
+        "evidence": [],
+        "formulae": [],
+        "uncertainty": {
+            "confidence": None,
+            "calibration_state": calibration_state,
+            "basis": draft["uncertainty"]["basis"],
+        },
+        "abstention": {"required": True, "code": code, "detail": detail},
+        "tool_proposal": {
+            "state": "NONE",
+            "tool_id": None,
+            "arguments_sha256": None,
+            "requires_human_approval": True,
+            "execution_receipt_id": None,
+        },
+        "receipt_binding": {
+            "state": "NOT_AVAILABLE",
+            "request_sha256": canonical_sha256(request),
+            "evidence_set_sha256": None,
+            "policy_snapshot_sha256": canonical_sha256(policy_snapshot),
+            "receipt_id": None,
+        },
+    }
+
+
+def finalize_draft(
+    draft: Any,
+    *,
+    request: Any,
+    evidence_catalog: Mapping[str, Mapping[str, Any]],
+    formula_catalog: Mapping[str, Mapping[str, Any]],
+    policy_snapshot: Mapping[str, Any],
+    model_identity: Mapping[str, Any],
+    calibration: Mapping[str, Any] | None = None,
+    receipt_envelope: Mapping[str, Any] | None = None,
+    receipt_hmac_key: bytes | None = None,
+    replay_guard: ReceiptReplayGuard | None = None,
+) -> dict[str, Any]:
+    """Resolve an unsigned model draft into a fail-closed final envelope.
+
+    The receipt must be a canonically encoded DSSE envelope with a valid
+    HMAC-SHA256 signature over every decision-bearing component.  HMAC is an
+    experimental local-runtime mechanism; public promotion still requires an
+    asymmetric DSSE/in-toto attestation and transparency-log record.
+    """
+
+    validate_draft(draft)
+    identity = _validate_model_identity(model_identity)
+    _require(isinstance(request, (dict, list, str)), "request must be canonical JSON data")
+    _require(isinstance(policy_snapshot, dict), "policy snapshot must be an object")
+    allowed_tools = policy_snapshot.get("allowed_tool_ids", [])
+    _require(isinstance(allowed_tools, list) and all(isinstance(x, str) for x in allowed_tools), "allowed_tool_ids must be strings")
+
+    if draft["status"] == "UNAVAILABLE":
+        return _empty_final(
+            draft=draft,
+            request=request,
+            policy_snapshot=policy_snapshot,
+            model_identity=identity,
+            status="UNAVAILABLE",
+            code="MODEL_UNAVAILABLE",
+            detail=draft["abstention"]["detail"],
+            calibration_state="NOT_EVALUATED",
+        )
+    if draft["status"] == "ABSTAINED":
+        return _empty_final(
+            draft=draft,
+            request=request,
+            policy_snapshot=policy_snapshot,
+            model_identity=identity,
+            status="ABSTAINED",
+            code=draft["abstention"]["code"],
+            detail=draft["abstention"]["detail"],
+            calibration_state="UNCALIBRATED",
+        )
+
+    resolved_evidence: list[dict[str, Any]] = []
+    for evidence_id in draft["evidence_ids"]:
+        record = evidence_catalog.get(evidence_id)
+        if not isinstance(record, Mapping):
+            return _empty_final(
+                draft=draft, request=request, policy_snapshot=policy_snapshot,
+                model_identity=identity, status="ABSTAINED", code="EVIDENCE_NOT_ADMITTED",
+                detail=f"Evidence {evidence_id} is absent from the immutable admitted snapshot.",
+                calibration_state="UNCALIBRATED",
+            )
+        required = {"content_sha256", "support_role", "admission_state", "freshness_state", "final_evidence_id"}
+        if not required.issubset(record):
+            raise ReceiptRuntimeError(f"evidence catalog record {evidence_id} is incomplete")
+        final_id = record["final_evidence_id"]
+        if (
+            record["admission_state"] != "ADMITTED_REFERENCE"
+            or record["freshness_state"] not in {"CURRENT", "NOT_APPLICABLE"}
+            or not isinstance(final_id, str)
+            or not FINAL_EVIDENCE_ID_RE.fullmatch(final_id)
+            or not isinstance(record["content_sha256"], str)
+            or not SHA256_RE.fullmatch(record["content_sha256"])
+            or record["support_role"] not in {"SUPPORTS", "CONTRADICTS", "CONTEXT"}
+        ):
+            return _empty_final(
+                draft=draft, request=request, policy_snapshot=policy_snapshot,
+                model_identity=identity, status="ABSTAINED", code="EVIDENCE_NOT_ADMITTED",
+                detail=f"Evidence {evidence_id} failed admission, freshness, or identity validation.",
+                calibration_state="UNCALIBRATED",
+            )
+        item = {
+            "evidence_id": final_id,
+            "content_sha256": record["content_sha256"],
+            "support_role": record["support_role"],
+            "admission_state": "ADMITTED_REFERENCE",
+        }
+        source_uri = record.get("source_uri")
+        if source_uri is not None:
+            _require(isinstance(source_uri, str) and source_uri.startswith("https://"), "invalid source URI")
+            item["source_uri"] = source_uri
+        resolved_evidence.append(item)
+
+    resolved_formulae: list[dict[str, Any]] = []
+    for claimed in draft["formula_refs"]:
+        key = f"{claimed['namespace']}::{claimed['formula_id']}"
+        authoritative = formula_catalog.get(key)
+        if not isinstance(authoritative, Mapping) or authoritative.get("status") != claimed["claimed_status"]:
+            return _empty_final(
+                draft=draft, request=request, policy_snapshot=policy_snapshot,
+                model_identity=identity, status="ABSTAINED", code="FORMULA_NAMESPACE_CONFLICT",
+                detail=f"Formula reference {key} does not match the authoritative snapshot.",
+                calibration_state="UNCALIBRATED",
+            )
+        receipt_hash = authoritative.get("formula_receipt_sha256")
+        semantic_binding = authoritative.get("semantic_binding_sha256")
+        proof_allowed = (
+            claimed["claimed_status"] == "KERNEL_ACCEPTED"
+            and authoritative.get("verification_state") == "KERNEL_VERIFIED"
+            and isinstance(receipt_hash, str)
+            and bool(SHA256_RE.fullmatch(receipt_hash))
+            and isinstance(semantic_binding, str)
+            and bool(SHA256_RE.fullmatch(semantic_binding))
+        )
+        if claimed["claimed_status"] == "KERNEL_ACCEPTED" and not proof_allowed:
+            return _empty_final(
+                draft=draft, request=request, policy_snapshot=policy_snapshot,
+                model_identity=identity, status="ABSTAINED", code="FORMULA_NAMESPACE_CONFLICT",
+                detail=f"Formula reference {key} lacks a kernel verification and semantic binding.",
+                calibration_state="UNCALIBRATED",
+            )
+        resolved_formulae.append(
+            {
+                "formula_id": claimed["formula_id"],
+                "namespace": claimed["namespace"],
+                "status": claimed["claimed_status"],
+                "proof_transfer_allowed": proof_allowed,
+                "formula_receipt_sha256": receipt_hash if proof_allowed else None,
+            }
+        )
+
+    tool = draft["tool_proposal"]
+    if tool["state"] == "PROPOSED" and tool["tool_id"] not in allowed_tools:
+        return _empty_final(
+            draft=draft, request=request, policy_snapshot=policy_snapshot,
+            model_identity=identity, status="ABSTAINED", code="POLICY_DENIED",
+            detail=f"Tool {tool['tool_id']} is not allowed by the bound policy snapshot.",
+            calibration_state="UNCALIBRATED",
+        )
+
+    if not isinstance(calibration, Mapping):
+        return _empty_final(
+            draft=draft, request=request, policy_snapshot=policy_snapshot,
+            model_identity=identity, status="ABSTAINED", code="UNCERTAINTY_TOO_HIGH",
+            detail="No externally measured calibration value is bound to this response.",
+            calibration_state="UNCALIBRATED",
+        )
+    confidence = calibration.get("confidence")
+    _require(isinstance(confidence, (int, float)) and not isinstance(confidence, bool) and 0 <= confidence <= 1, "invalid calibrated confidence")
+    _require(isinstance(calibration.get("basis"), str) and bool(calibration["basis"]), "calibration basis required")
+
+    final_tool = {
+        "state": tool["state"],
+        "tool_id": tool["tool_id"],
+        "arguments_sha256": canonical_sha256(tool["arguments"]) if tool["state"] == "PROPOSED" else None,
+        "requires_human_approval": True,
+        "execution_receipt_id": None,
+    }
+    evidence_hash = canonical_sha256(sorted(resolved_evidence, key=lambda item: item["evidence_id"]))
+    formula_hash = canonical_sha256(sorted(resolved_formulae, key=lambda item: (item["namespace"], item["formula_id"])))
+    request_hash = canonical_sha256(request)
+    policy_hash = canonical_sha256(policy_snapshot)
+    draft_hash = canonical_sha256(draft)
+    identity_hash = canonical_sha256(identity)
+    calibration_hash = canonical_sha256(calibration)
+    tool_hash = canonical_sha256(final_tool)
+    binding_payload = {
+        "schema_version": "szl.receipt-agent-binding.v1",
+        "draft_sha256": draft_hash,
+        "answer_sha256": canonical_sha256(draft["answer"]),
+        "model_identity_sha256": identity_hash,
+        "request_sha256": request_hash,
+        "evidence_set_sha256": evidence_hash,
+        "formula_set_sha256": formula_hash,
+        "calibration_sha256": calibration_hash,
+        "tool_proposal_sha256": tool_hash,
+        "policy_snapshot_sha256": policy_hash,
+    }
+    binding_hash = canonical_sha256(binding_payload)
+    if receipt_envelope is None or receipt_hmac_key is None or replay_guard is None:
+        return _empty_final(
+            draft=draft, request=request, policy_snapshot=policy_snapshot,
+            model_identity=identity, status="ABSTAINED", code="RECEIPT_INVALID",
+            detail="No cryptographically verified, replay-protected receipt binds the complete response payload.",
+            calibration_state="CALIBRATED",
+        )
+    receipt = _verify_hmac_dsse(receipt_envelope, receipt_hmac_key)
+    receipt_fields = {
+        "schema_version",
+        "receipt_id",
+        "nonce",
+        "binding_payload_sha256",
+        "draft_sha256",
+        "answer_sha256",
+        "model_identity_sha256",
+        "request_sha256",
+        "evidence_set_sha256",
+        "formula_set_sha256",
+        "calibration_sha256",
+        "tool_proposal_sha256",
+        "policy_snapshot_sha256",
+    }
+    _require_exact_keys(receipt, receipt_fields, "receipt payload")
+    _require(receipt["schema_version"] == "szl.receipt-agent-verifier-result.v1", "unsupported receipt result schema")
+    _require(isinstance(receipt["receipt_id"], str) and bool(receipt["receipt_id"]), "receipt id required")
+    _require(isinstance(receipt["nonce"], str) and len(receipt["nonce"]) >= 16, "receipt nonce required")
+    expected_bindings = dict(binding_payload)
+    expected_bindings["binding_payload_sha256"] = binding_hash
+    for field, expected in expected_bindings.items():
+        if field == "schema_version":
+            continue
+        _require(receipt.get(field) == expected, f"receipt {field} mismatch")
+    _require(replay_guard.consume(receipt["receipt_id"]), "receipt replay detected")
+
+    response_seed = {
+        "binding_payload_sha256": binding_hash,
+        "receipt_id": receipt["receipt_id"],
+        "nonce": receipt["nonce"],
+    }
+    return {
+        "schema_version": FINAL_SCHEMA_VERSION,
+        "response_id": f"response:{canonical_sha256(response_seed)[:24]}",
+        "model_identity": identity,
+        "status": "ANSWERED",
+        "answer": draft["answer"],
+        "evidence": resolved_evidence,
+        "formulae": resolved_formulae,
+        "uncertainty": {
+            "confidence": confidence,
+            "calibration_state": "CALIBRATED",
+            "basis": calibration["basis"],
+        },
+        "abstention": {"required": False, "code": "NONE", "detail": "All deterministic gates passed."},
+        "tool_proposal": final_tool,
+        "receipt_binding": {
+            "state": "SIGNED",
+            "request_sha256": request_hash,
+            "evidence_set_sha256": evidence_hash,
+            "policy_snapshot_sha256": policy_hash,
+            "receipt_id": receipt["receipt_id"],
+        },
+    }

numerics/isolation_probe.py

@@ -0,0 +1,38 @@
+# SPDX-License-Identifier: Apache-2.0
+"""Fixed child used only to attest a fresh Linux network namespace.
+
+The parent launches this file through ``unshare --net``.  It performs no
+network operation and accepts no command, expression, or package input.
+"""
+
+import json
+import os
+import sys
+from pathlib import Path
+
+
+def main() -> int:
+    if len(sys.argv) != 2:
+        return 64
+    target = Path(sys.argv[1])
+    interfaces = sorted(path.name for path in Path("/sys/class/net").iterdir())
+    loopback_state = None
+    state_path = Path("/sys/class/net/lo/operstate")
+    if state_path.is_file():
+        loopback_state = state_path.read_text(encoding="utf-8").strip()
+    payload = {
+        "schema": "szl.numerics.network-namespace-evidence/v1",
+        "network_operations_performed": 0,
+        "network_namespace": os.readlink("/proc/self/ns/net"),
+        "interfaces": interfaces,
+        "loopback_operstate": loopback_state,
+    }
+    target.write_text(
+        json.dumps(payload, sort_keys=True, separators=(",", ":"), ensure_ascii=False),
+        encoding="utf-8",
+    )
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

research/__init__.py

@@ -1,3 +1,2 @@
 # SPDX-License-Identifier: Apache-2.0
 """Research-layer modules for source-cited A11oy experiments."""
-

serve.py

@@ -199,6 +199,268 @@ async def frontier_projects_snapshot() -> JSONResponse:
     return JSONResponse(primary_project_registry_snapshot(fetch_live=False))
 
 
+# Quantum Utility Gate (wave 16): bounded proposal-only analysis.  The core is
+# pure stdlib and has no provider/QPU/network/filesystem/process effectors.  It
+# is deliberately separate from the finance szl_gpu_quant engine; the existing
+# szl_vqc surface remains MODELED/SIMULATED and is not hardware evidence.
+try:
+    from szl_quantum_utility import (
+        ContractError as QuantumUtilityContractError,
+        info as quantum_utility_info_payload,
+        replay_receipt as quantum_utility_replay,
+        run_with_receipt as quantum_utility_run,
+    )
+    _QUANTUM_UTILITY_READY = True
+except Exception:  # pragma: no cover - honest optional degradation
+    QuantumUtilityContractError = ValueError  # type: ignore[misc,assignment]
+    quantum_utility_info_payload = None  # type: ignore[assignment]
+    quantum_utility_replay = None  # type: ignore[assignment]
+    quantum_utility_run = None  # type: ignore[assignment]
+    _QUANTUM_UTILITY_READY = False
+
+
+_QUANTUM_UTILITY_BODY_LIMIT = 256 * 1024
+
+
+class _QuantumUtilityPayloadTooLarge(ValueError):
+    pass
+
+
+async def _quantum_utility_body(request: Request) -> dict[str, Any]:
+    content_length = request.headers.get("content-length")
+    if content_length is not None:
+        try:
+            declared_length = int(content_length)
+        except ValueError as exc:
+            raise QuantumUtilityContractError("content-length must be a non-negative integer") from exc
+        if declared_length < 0:
+            raise QuantumUtilityContractError("content-length must be a non-negative integer")
+        if declared_length > _QUANTUM_UTILITY_BODY_LIMIT:
+            raise _QuantumUtilityPayloadTooLarge("request body exceeds 256 KiB")
+
+    body_buffer = bytearray()
+    async for chunk in request.stream():
+        if len(body_buffer) + len(chunk) > _QUANTUM_UTILITY_BODY_LIMIT:
+            raise _QuantumUtilityPayloadTooLarge("request body exceeds 256 KiB")
+        body_buffer.extend(chunk)
+    body = bytes(body_buffer)
+    try:
+        value = json.loads(body.decode("utf-8"))
+    except (UnicodeDecodeError, json.JSONDecodeError) as exc:
+        raise QuantumUtilityContractError("request body must be one JSON object") from exc
+    if not isinstance(value, dict):
+        raise QuantumUtilityContractError("request body must be one JSON object")
+    return value
+
+
+def _quantum_utility_unavailable() -> JSONResponse:
+    return JSONResponse(
+        {
+            "ready": False,
+            "label": "UNAVAILABLE",
+            "mode": "UNAVAILABLE",
+            "effectors": 0,
+            "provider_calls": 0,
+            "qpu_calls": 0,
+        },
+        status_code=503,
+    )
+
+
+async def _quantum_utility_operation(request: Request, operation: str) -> JSONResponse:
+    if not _QUANTUM_UTILITY_READY or quantum_utility_run is None:
+        return _quantum_utility_unavailable()
+    try:
+        return JSONResponse(quantum_utility_run(operation, await _quantum_utility_body(request)))
+    except _QuantumUtilityPayloadTooLarge as exc:
+        return JSONResponse(
+            {
+                "ready": True,
+                "label": "STRUCTURAL-ONLY",
+                "accepted": False,
+                "error": str(exc),
+                "mode": "PROPOSAL_ONLY",
+                "effectors": 0,
+                "provider_calls": 0,
+                "qpu_calls": 0,
+            },
+            status_code=413,
+        )
+    except QuantumUtilityContractError as exc:
+        return JSONResponse(
+            {
+                "ready": True,
+                "label": "STRUCTURAL-ONLY",
+                "accepted": False,
+                "error": str(exc),
+                "mode": "PROPOSAL_ONLY",
+                "effectors": 0,
+                "provider_calls": 0,
+                "qpu_calls": 0,
+            },
+            status_code=422,
+        )
+
+
+@app.get("/api/a11oy/v1/quantum-utility/info")
+async def quantum_utility_info() -> JSONResponse:
+    if not _QUANTUM_UTILITY_READY or quantum_utility_info_payload is None:
+        return _quantum_utility_unavailable()
+    return JSONResponse(quantum_utility_info_payload())
+
+
+@app.post("/api/a11oy/v1/quantum-utility/qubo/baseline")
+async def quantum_utility_qubo_baseline(request: Request) -> JSONResponse:
+    return await _quantum_utility_operation(request, "QUBO_EXACT_BASELINE")
+
+
+@app.post("/api/a11oy/v1/quantum-utility/hamiltonian/shot-plan")
+async def quantum_utility_hamiltonian_shot_plan(request: Request) -> JSONResponse:
+    return await _quantum_utility_operation(request, "HAMILTONIAN_SHOT_PLAN")
+
+
+@app.post("/api/a11oy/v1/quantum-utility/counterfactual/score")
+async def quantum_utility_counterfactual_score(request: Request) -> JSONResponse:
+    return await _quantum_utility_operation(request, "COUNTERFACTUAL_SCORE")
+
+
+@app.post("/api/a11oy/v1/quantum-utility/claim/rupture-gate")
+async def quantum_utility_claim_gate(request: Request) -> JSONResponse:
+    return await _quantum_utility_operation(request, "QUANTUM_ADVANTAGE_GATE")
+
+
+@app.post("/api/a11oy/v1/quantum-utility/receipt/replay")
+async def quantum_utility_receipt_replay(request: Request) -> JSONResponse:
+    if not _QUANTUM_UTILITY_READY or quantum_utility_replay is None:
+        return _quantum_utility_unavailable()
+    try:
+        return JSONResponse(quantum_utility_replay(await _quantum_utility_body(request)))
+    except _QuantumUtilityPayloadTooLarge as exc:
+        return JSONResponse(
+            {
+                "ready": True,
+                "label": "STRUCTURAL-ONLY",
+                "valid": False,
+                "error": str(exc),
+                "mode": "PROPOSAL_ONLY",
+                "effectors": 0,
+                "provider_calls": 0,
+                "qpu_calls": 0,
+            },
+            status_code=413,
+        )
+    except QuantumUtilityContractError as exc:
+        return JSONResponse(
+            {
+                "ready": True,
+                "label": "STRUCTURAL-ONLY",
+                "valid": False,
+                "error": str(exc),
+                "mode": "PROPOSAL_ONLY",
+                "effectors": 0,
+                "provider_calls": 0,
+                "qpu_calls": 0,
+            },
+            status_code=422,
+        )
+
+
+# External numerical-engine frontier (wave 18). The module accepts only fixed
+# matrix solve, symmetric-eigenvalue, and reference-vector operations. GNU
+# Octave and MATLAB remain external installations; missing engine, offline
+# license configuration, POSIX resource limits, or network isolation reports
+# UNAVAILABLE. Results are unsigned deterministic digests with zero proof/trust
+# uplift. Registration is early so these routes precede both catch-alls.
+try:
+    import szl_numerics_adapter as _szl_numerics_adapter
+
+    _NUMERICS_ADAPTER_STATUS = _szl_numerics_adapter.register(app, ns="a11oy")
+except Exception as _numerics_adapter_error:  # pragma: no cover - honest optional degradation
+    _NUMERICS_ADAPTER_STATUS = {
+        "registered": False,
+        "state": "UNAVAILABLE",
+        "reason": type(_numerics_adapter_error).__name__,
+        "proof_uplift": 0,
+        "trust_uplift": 0,
+    }
+
+
+# Yupaq governed computation plane (wave 23).  This is the strict binding layer
+# over the existing Quant, Quantum Utility, MATLAB/Octave, Lean/mathlib,
+# formula-admission, Brain, Lambda, OTel, and SZL-Lake organs.  It accepts only
+# fixed typed operations; arbitrary code, paths, URLs, packages, provider
+# credentials, and shell arguments are structurally impossible.  Registration
+# remains early so the local routes precede both proxy and SPA catch-alls.
+try:
+    import szl_yupaq_compute as _szl_yupaq_compute
+
+    _YUPAQ_COMPUTE_STATUS = _szl_yupaq_compute.register(app, ns="a11oy")
+except Exception as _yupaq_compute_error:  # pragma: no cover - honest optional degradation
+    _YUPAQ_COMPUTE_STATUS = {
+        "registered": False,
+        "state": "UNAVAILABLE",
+        "reason": type(_yupaq_compute_error).__name__,
+        "proof_uplift": 0,
+        "trust_uplift": 0,
+    }
+
+
+# Preregistered numerical evaluator dataset (wave 22). This is a separate
+# evidence surface from engine execution: 1,328 deterministic case definitions
+# are read-only; authenticated run receipts append to an integrity-linked
+# ledger. Missing engines, reference evidence, network denial, or licensing
+# evidence remain UNAVAILABLE/NOT_EVALUATED and never become synthetic results.
+try:
+    import szl_numerics_dataset as _szl_numerics_dataset
+
+    _NUMERICS_DATASET_STATUS = _szl_numerics_dataset.register(app, ns="a11oy")
+except Exception as _numerics_dataset_error:  # pragma: no cover - honest optional degradation
+    _NUMERICS_DATASET_STATUS = {
+        "registered": False,
+        "state": "UNAVAILABLE",
+        "reason": type(_numerics_dataset_error).__name__,
+        "proof_uplift": 0,
+        "trust_uplift": 0,
+    }
+
+
+# Formal Conjecture Lab (wave 19). Declarations and formal artifacts are
+# bounded local writes. No prover command is exposed. A transition to a kernel
+# result requires an externally produced DSSE receipt verified against the
+# embedded public cosign key and bound to the exact server-computed statement
+# and artifact hashes. KERNEL_ACCEPTED is evidence only, never proof promotion.
+try:
+    import szl_formal_conjecture_lab as _szl_formal_conjecture_lab
+
+    _FORMAL_CONJECTURE_LAB_STATUS = _szl_formal_conjecture_lab.register(app, ns="a11oy")
+except Exception as _formal_conjecture_lab_error:  # pragma: no cover - honest optional degradation
+    _FORMAL_CONJECTURE_LAB_STATUS = {
+        "registered": False,
+        "kernel_execution": "UNAVAILABLE",
+        "proof_promotion": "DISABLED",
+        "reason": type(_formal_conjecture_lab_error).__name__,
+    }
+
+
+# M1 experimental model operational gate (wave 22). The candidate remains
+# NOT_PROMOTED and no weights are bundled. The module front-moves its exact
+# status/infer/page routes ahead of both catch-alls and runs only a local,
+# bounded PEFT turn after byte-exact artifact/receipt verification, GPU
+# admission, and provider-identity binding. Missing evidence reports structured
+# BLOCKED/UNAVAILABLE; there is no remote-provider or download fallback.
+try:
+    import szl_m1_model_gate as _szl_m1_model_gate
+
+    _M1_MODEL_GATE_STATUS = _szl_m1_model_gate.register(app, ns="a11oy")
+except Exception as _m1_model_gate_error:  # pragma: no cover - honest optional degradation
+    _M1_MODEL_GATE_STATUS = {
+        "registered": False,
+        "operational_state": "UNAVAILABLE",
+        "release_state": "NOT_PROMOTED",
+        "production_eligible": False,
+        "reason": type(_m1_model_gate_error).__name__,
+    }
+
 def _optional_module_absent(exc: Exception, module: str, surface: str,
                             *, stream=None) -> bool:
     """Log a direct optional-module absence without a noisy traceback.
@@ -763,8 +1025,8 @@ except Exception as _szl_op_e:  # pragma: no cover
 # router, bounded-autonomy AgentLoop, and DSSE receipts. Deliberately drops the tribe's
 # unbounded "fully agentic" mandate for a11oy's fail-closed Λ-gate. See ayllu/INGEST.md.
 # Additive, try/except-guarded, same register() pattern. Model backend IS wired via
-# ayllu.backend -> a11oy_code_orchestrator (live iff an inference credential is set on
-# the Space; a clearly-labeled deterministic stub otherwise - never a fabricated answer).
+# ayllu.backend -> a11oy_code_orchestrator (live when a local endpoint answers or a
+# remote credential is present; a clearly-labeled deterministic stub otherwise).
 try:
     import a11oy_ayllu as _a11oy_ayllu
     print("[a11oy] " + _a11oy_ayllu.register(app, ns="a11oy"), file=__import__("sys").stderr)
@@ -1025,7 +1287,22 @@ except Exception as _szl_brainhealth_e:  # pragma: no cover
 # READ (signs/mints nothing on GET). Adds NOTHING to the locked-8; Λ stays Conjecture 1;
 # trust ceiling 0.97. Additive, try/except-guarded, same register() pattern, BEFORE the SPA
 # catch-all. Must register AFTER the frontier index (which it reads).
+# BRAIN EVIDENCE RERANKER + OUROBOROS LOCAL FEED (wave 22). This is a
+# readiness/data boundary, not a trainer. It inventories every raw Brain node,
+# requires canonical content-addressed corpus manifests before admitting rows,
+# and reports dataset, evaluation, and model readiness independently. The local
+# feed write path is loopback-only, bounded, checkpointed, and kill-switched.
+try:
+    import szl_brain_reranker as _szl_brain_reranker
+    _brain_reranker_paths = _szl_brain_reranker.register(app, ns="a11oy")
+    print(f"[a11oy] Brain evidence-reranker registered: {_brain_reranker_paths}",
+          file=__import__("sys").stderr)
+except Exception as _szl_brain_reranker_e:  # pragma: no cover
+    print(f"[a11oy] Brain evidence-reranker NOT registered: {_szl_brain_reranker_e!r}; "
+          "SPA + API unaffected", file=__import__("sys").stderr)
+
 try:
+    # Status aggregate remains registered after the evidence-reranker block above.
     import szl_status_aggregate as _szl_status_aggregate
     _szl_status_aggregate.register(app, ns="a11oy")
     print("[a11oy] Operational STATUS aggregate registered: /api/a11oy/v1/status (honest per-subsystem/surface health, drift-proof)", file=__import__("sys").stderr)
@@ -2939,12 +3216,6 @@ async def _safe_json_body(request: Request):
         return None, JSONResponse({"error": "invalid JSON body"}, status_code=400)
 
 
-# ADDITIVE (mesh wire-up, Dev2): cross-pod vsp-otel tracing (W3C traceparent + OTLP/gRPC).
-try:
-    from vsp_otel.middleware import install as install_vsp; install_vsp(app)
-except Exception as _vsp_e:
-    import sys as _vsp_sys; print(f"[a11oy] vsp-otel wire skipped: {_vsp_e!r}", file=_vsp_sys.stderr)
-
 # ADDITIVE: OTel — instrument FastAPI app
 try:
     _szl_otel_setup(fastapi_app=app)
@@ -2963,6 +3234,12 @@ except Exception as _otel_e:
 try:
     import vsp_otel.middleware as _vsp_otel
     _vsp_otel.install(app)
+    app.add_api_route(
+        "/api/a11oy/v1/observability/status",
+        lambda: JSONResponse(_vsp_otel.status(app)),
+        methods=["GET"],
+        include_in_schema=False,
+    )
     import sys as _vsp_sys
     print(f"[a11oy] vsp-otel VSP installed: exporter={getattr(app, '_vsp_otel_exporter', 'unknown')}", file=_vsp_sys.stderr)
 except Exception as _vsp_e:
@@ -3438,8 +3715,8 @@ except Exception as _formulas_exc:  # additive: never break the Space if the mod
 # in this file, so FastAPI's ordered matching routes /api/a11oy/code/* here
 # rather than proxying to Node. Wrapped in try/except so a missing optional dep
 # (huggingface_hub / openai) can NEVER take down the existing SPA + gates API.
-# NO BANDAID: if no inference credential is present the orchestrator returns an
-# honest 503 at call time — it is never faked here.
+# NO BANDAID: if neither a reachable local endpoint nor a credentialed remote
+# provider is available, the orchestrator refuses or emits its labeled stub.
 # ---------------------------------------------------------------------------
 try:
     import a11oy_code_orchestrator as _a11oy_code
@@ -6685,22 +6962,34 @@ async def a11oy_mcp_call_inline(request: Request):
 async def a11oy_version():
     """Founder inspection: what build is live, when was it deployed, provenance."""
     import os as _szlv_os
+    from szl_release_identity import release_identity as _release_identity
+
+    _identity = _release_identity()
+    _release_tag = _identity.get("release_tag")
+    _release_assets_ready = bool(_release_tag)
     return {
-        "name": "a11oy",
-        "version": "1.0.0",
-        "git_sha": _szlv_os.getenv("SZL_GIT_SHA", "90dd8e34efd7308f39c2230c78a4f1a67e4b0ba6"),
-        "hf_space_sha": _szlv_os.getenv("SZL_HF_SHA", "1d2540609a07d41b4d333fc58ea1f74f852e8f53"),
-        "build_time": _szlv_os.getenv("SZL_BUILD_TIME", "2026-06-03T00:00:00Z"),
-        "release_url": "https://github.com/szl-holdings/a11oy/releases/tag/v1.0.0",
+        **_identity,
+        "git_sha": _szlv_os.getenv("SZL_GIT_SHA") or "UNKNOWN",
+        "hf_space_sha": _szlv_os.getenv("SZL_HF_SHA") or "UNKNOWN",
+        "build_time": _szlv_os.getenv("SZL_BUILD_TIME") or "UNKNOWN",
         "doctrine": "v11",
         "kernel_commit": "c7c0ba17",
         "p6_status": "SIGNED_OFF",
         "p6_grader_score": "14/14",
         "p6_sign_off_url": "https://github.com/szl-holdings/szl-holdings/blob/main/SHARED_LEDGER/a11oy/SIGN_OFF.md",
         "verify": {
-            "cosign": "cosign verify ghcr.io/szl-holdings/a11oy:v1.0.0 --certificate-identity-regexp=szl-holdings",
-            "sbom": "https://github.com/szl-holdings/a11oy/releases/download/v1.0.0/a11oy-sbom.cdx.json",
-            "honest": "https://szlholdings-a11oy.hf.space/api/a11oy/v1/honest",
+            "release_assets_status": "CONFIGURED_UNVERIFIED" if _release_assets_ready else "PENDING_RELEASE",
+            "cosign": (
+                f"cosign verify ghcr.io/szl-holdings/a11oy:{_release_tag} --certificate-identity-regexp=szl-holdings"
+                if _release_assets_ready
+                else None
+            ),
+            "sbom": (
+                f"https://github.com/szl-holdings/a11oy/releases/download/{_release_tag}/a11oy-sbom.cdx.json"
+                if _release_assets_ready
+                else None
+            ),
+            "honest": "https://a-11-oy.com/api/a11oy/v1/honest",
         },
         # ADDITIVE (waveL Dev2): machine-readable release record of the waves'
         # shipped capabilities with HONEST labels. Mirrors CHANGELOG.md; the
@@ -8106,7 +8395,25 @@ def _a11oy_canonical(obj) -> bytes:
 def _a11oy_sign_receipt(payload_obj) -> dict:
     """Produce a DSSE envelope over the canonical JSON of payload_obj using the
     in-image ephemeral key. Honest UNSIGNED marker if key unavailable."""
-    body = _a11oy_canonical(payload_obj)
+    key_identity = {
+        "keyid": _A11OY_KEYID,
+        "verify_key_url": "/api/a11oy/cosign.pub",
+        "key_scope": "PROCESS_BOOT_EPHEMERAL",
+        "key_lifetime": "UNTIL_PROCESS_RESTART",
+        "key_fingerprint_sha256": (
+            _hashv2.sha256((_A11OY_PUB_PEM or "").strip().encode()).hexdigest()
+            if _A11OY_PUB_PEM else None
+        ),
+    }
+    # Key discovery is part of the signed statement, not mutable envelope-only
+    # metadata. Verifiers must pin this same-origin URL and compare the fetched
+    # key fingerprint with this signed value before accepting a signature.
+    if isinstance(payload_obj, dict):
+        signed_payload = dict(payload_obj)
+    else:
+        signed_payload = {"value": payload_obj}
+    signed_payload["_signing_identity"] = key_identity
+    body = _a11oy_canonical(signed_payload)
     to_sign = _a11oy_pae(_A11OY_PAYLOAD_TYPE, body)
     env = {
         "payloadType": _A11OY_PAYLOAD_TYPE,
@@ -8114,6 +8421,12 @@ def _a11oy_sign_receipt(payload_obj) -> dict:
         "_dsse": "DSSEv1",
         "_pae_sha256": _hashv2.sha256(to_sign).hexdigest(),
         "_signed_at": _dtv2.now(_tzv2.utc).isoformat(),
+        # Duplicated for operator ergonomics; the authoritative values are the
+        # identical fields inside the signed payload's _signing_identity.
+        "verify_key_url": key_identity["verify_key_url"],
+        "key_scope": key_identity["key_scope"],
+        "key_lifetime": key_identity["key_lifetime"],
+        "key_fingerprint_sha256": key_identity["key_fingerprint_sha256"],
     }
     if _A11OY_PRIV is None:
         env["signatures"] = []
@@ -8126,7 +8439,8 @@ def _a11oy_sign_receipt(payload_obj) -> dict:
     env["signed"] = True
     env["honesty"] = ("REAL — ECDSA-P256-SHA256 over the DSSE PAE, signed by an "
                       "in-image key generated at server boot. Verify in-browser "
-                      "against /cosign.pub; a tampered byte fails. Key resets on rebuild.")
+                      "against /api/a11oy/cosign.pub; a tampered byte fails. "
+                      "Key resets on process restart.")
     return env
 
 
@@ -10019,9 +10333,13 @@ except Exception as _kl_e:
 _LOCAL_ONLY_A11OY_PREFIXES = ("v1/warhacker/", "v1/observability/", "v1/sec/",
                               "v1/live/", "v1/code/", "v1/seismic/", "v1/feeds/",
                               "v1/govern/",
+                              "v1/models/m1",       # M1 local-only experimental gate
                               "v1/verify/intoto",      # in-toto verify guide (DEV2)
                               "v1/khipu/intoto/",      # in-toto receipt views (DEV2)
                               "v1/vqc/",               # Governed VQC (in-process; DEV1)
+                              "v1/quantum-utility/",   # Proposal-only Quantum Utility Gate
+                              "v1/compute/",           # Yupaq governed computation plane
+                              "v1/formal-conjecture-lab/",  # Fail-closed formal receipt lab
                               )
 
 
@@ -12173,8 +12491,8 @@ except Exception as _op_e:
 
 # ============================================================================
 # SZL-NEMO CORE (Lane I1, 2026-06-14) — OUR sovereign, governed, self-improving
-# AGENT MODEL as a LIVE SKELETON. Built ON an open base (default Qwen3-32B,
-# Apache-2.0); governed & sovereign. NEVER claims from-scratch / 550B /
+# AGENT RUNTIME built on the exact public Nemotron 3 Nano 4B recipe and registry
+# manifest. NEVER claims SZL fine-tuning / from-scratch / 550B /
 # local-Nemotron-Ultra / a cert. The differentiator is the GOVERNED-MoE
 # domain-expert router: "experts" = domain heads (counter-uas / maritime /
 # governance / code / finance), routed by a Λ-governed (Conjecture 1, advisory
@@ -12225,7 +12543,7 @@ except Exception as _nemo_e:
 # szl_willay_gateway) via their OWN idempotent register() helpers, and adds the
 # missing honest GET /api/a11oy/v1/<surface>/status for nemo + qhawaq + waqay +
 # yupay + willay. SZL-Nemo /status summarizes a11oy_nemo_core.model_card() (model
-# = governed Qwen3-32B, Apache-2.0, served via the governed gateway; NEVER a
+# = governed Nemotron 3 Nano 4B recipe, served only after exact runtime identity; NEVER a
 # from-scratch model). Each /status is signed into a Khipu receipt (Conjecture 2).
 # Honest LIVE lifecycle (each surface has real runtime substance) with ROADMAP
 # sub-items labeled inline. 0 codenames. Front-inserted BEFORE the SPA catch-all.

szl3d_holographic.py

@@ -132,6 +132,7 @@ SURFACES: List[Dict[str, str]] = [
     {"id": "agentops", "cat": "reasoning", "title": "Agent Ops · bounded operate loop (ground→act→self-eval→gate, Ouroboros-bounded, writer≠judge)", "owner": "WaveP-Dev5"},
     {"id": "lgmi", "cat": "governance", "title": "LGMI · Λ-Governed Mechanistic Interpretability (synthesis)", "owner": "WaveP-Dev4"},
     {"id": "gnqs", "cat": "quant", "title": "GNQS · Governed-Norm Quantization Stability (synthesis)", "owner": "WaveP-Dev4"},
+    {"id": "numericsdataset", "cat": "quant", "title": "Numerics Dataset · 1,328 frozen matrix cases + append-only engine evidence · preregistered inputs are never shown as measured results · MATCH/CONFLICT/UNAVAILABLE · proof uplift=0", "owner": "Wave18"},
     {"id": "casta", "cat": "defense", "title": "CASTA · Clean-room Anomaly × Streaming Test-time Adaptation (synthesis)", "owner": "WaveP-Dev4"},
     {"id": "frontierindex", "cat": "brain", "title": "Frontier Index · honest ecosystem catalog · per-surface backend label + citations + native/fallback (self-audited)", "owner": "WaveQ-Dev5"},
     {"id": "sparsemoe", "cat": "quant", "title": "Extreme-Sparsity MoE Analyzer · activation-ratio ↔ inference-cost tradeoff (STRUCTURAL-ONLY)", "owner": "WaveP-Dev4"},
@@ -151,6 +152,7 @@ SURFACES: List[Dict[str, str]] = [
     {"id": "braincontradict", "cat": "brain", "flag": True, "title": "Brain Contradiction Detector · surfaces potential contradictions between grounded knowledge-graph claims HONESTLY via transparent deterministic heuristics (negation polarity / antonym opposition / numeric conflict) → NO-CONFLICT/POSSIBLE-CONFLICT/CONFLICT-FLAGGED · PRESENTS conflicts, NEVER resolves them (adjudication=human-required), unsigned SHA-256 receipt-on-write (MODELED)", "owner": "WaveS-Dev8"},
     {"id": "brainuncertainty", "cat": "brain", "title": "Brain Uncertainty · calibrated honest uncertainty on a brain retrieval · reads the same honest ranked retrieval and derives score dispersion + retrieval entropy + rank stability → one uncertainty in [0,1] with a CONFIDENT/UNCERTAIN/HIGHLY-UNCERTAIN verdict (recommends abstain), never CONFIDENT when dispersion/entropy high, MODELED calibration honesty not a probability, unsigned SHA-256 receipt-on-write", "owner": "WaveS-Dev8"},
     {"id": "brainhealth", "cat": "brain", "title": "Brain Health · live \"can the brain be trusted for this query right now?\" rollup · reads each brain-honesty surface's OWN label VERBATIM (grounding, freshness, provenance, contradiction, uncertainty), degrades absent siblings to UNAVAILABLE → TRUSTWORTHY/DEGRADED/UNTRUSTWORTHY/INSUFFICIENT-SIGNAL, never TRUSTWORTHY if any available component abstains, unsigned SHA-256 receipt-on-write (MODELED)", "owner": "WaveS-Dev8"},
+    {"id": "brainreranker", "cat": "brain", "flag": True, "title": "Anatomy v6 · Brain evidence inventory, reranker readiness, and bounded Ouroboros local-feed receipts · every raw node receives an admission/quarantine decision · zero proposal rows while canonical manifests are absent", "owner": "Wave22-Brain-Evidence"},
     {"id": "brainwatch", "cat": "brain", "title": "Brain Watch · knowledge-graph honesty-posture drift monitor · MEASURED label-distribution/orphan/community/salience snapshot vs a caller-supplied PRIOR → STABLE/DRIFTING/DEGRADED/BASELINE-ONLY (no fabricated trend without a real prior), unsigned SHA-256 receipt-on-write", "owner": "WaveT-Dev1"},
     {"id": "brainconsensus", "cat": "brain", "title": "Brain Consensus · honest corroboration of a brain grounding · measures how MANY distinct nodes support a query and how many distinct communities they span (cross-community agreement is stronger than one clique) → CORROBORATED/WEAK-CORROBORATION/SINGLE-SOURCE, single-source-risk flag when support collapses to one node/community, never CORROBORATED while that flag is set, MODELED corroboration honesty not a truth guarantee, unsigned SHA-256 receipt-on-write", "owner": "WaveU-Dev1"},
     {"id": "brainqueryaudit", "cat": "brain", "title": "Brain Query Audit · append-only hash-linked ledger of brain queries + the honest verdict each returned · POST appends {query, verdict, grounding_label} and mints an UNSIGNED SHA-256 receipt chained to the prior entry (tamper-evident); GET recomputes the whole chain → CHAIN-INTACT/CHAIN-BROKEN (never softened), ephemeral in-memory ledger labelled honestly, MODELED, receipt-on-write-not-on-read", "owner": "WaveT-Dev1"},

szl_alloy_models.py

@@ -366,7 +366,11 @@ def _local_generate(prompt: str, max_tokens: int = 256) -> dict:
                 {"role": "user", "content": prompt}]
         out = llm.create_chat_completion(messages=msgs, max_tokens=max_tokens, temperature=0.2)
         text = (out.get("choices") or [{}])[0].get("message", {}).get("content", "")
-        return {"served_locally": True, "text": text, "backend": "llama.cpp",
+        if not isinstance(text, str) or not text.strip():
+            return {"served_locally": False, "text": None,
+                    "honest_label": "llama.cpp returned an empty response",
+                    "backend": "llama.cpp", "tower_side": True}
+        return {"served_locally": True, "text": text.strip(), "backend": "llama.cpp",
                 "tower_side": False, "latency_ms": int((time.time() - t0) * 1000),
                 "gguf_sha256_fp": _gguf_sha(_gguf_path())}
     except Exception as e:
@@ -617,6 +621,24 @@ def alloy_governed_suggest(prompt: str, task_hint: str = "code", lam: float = 0.
         "doctrine": DOCTRINE, "lambda_status": LAMBDA_STATUS,
         "ts": datetime.now(timezone.utc).isoformat().replace("+00:00", "Z"),
     }
+    generation_receipt = {"ok": False, "inference_receipted": False,
+                          "reason": "no successful local generation to receipt"}
+    if out["served_locally"] and gen.get("text"):
+        try:
+            import szl_governed_infer as _gi
+            generation_receipt = _gi.record_provider_generation(
+                prompt, gen["text"], chosen["model_id"],
+                tokens=0, base_url="llama.cpp://local")
+        except Exception as exc:
+            generation_receipt = {
+                "ok": False, "inference_receipted": False,
+                "reason": "durable receipt unavailable: %s" % type(exc).__name__}
+    out["generation_receipt"] = generation_receipt
+    out["inference_receipted"] = bool(
+        generation_receipt.get("inference_receipted"))
+    out["operational"] = bool(out["served_locally"]
+                              and out["inference_receipted"])
+    out["honest_stub"] = not out["operational"]
     if do_consensus:
         # Honest demo consensus over production-eligible models' routing scores
         # (answer_key is a coarse bucket of the routed score — a real, deterministic
@@ -666,7 +688,7 @@ def unify_into_registry() -> dict:
                 "tier": 90,  # alloy band sits outside the legacy 0-5 closed tiers
                 "operator_mirrored": False,
                 "ecosystem_mirror": ["killinchu"],
-                "honest_stub": (not _production_eligible(m)) or (m["tier_band"] != "demo_cpu"),
+                "honest_stub": True,
                 "notes": "open-weight alloy; " + m.get("serving", ""),
             })
             report["added"].append(m["model_id"])
@@ -736,15 +758,49 @@ def register(app, ns: str = "a11oy", sign_fn=None) -> dict:
 
     async def _health(request):
         path = _gguf_path()
+        backend_live = backend_available()
+        receipt_state = {"inference_receipted": False,
+                         "successful_receipt_count": 0,
+                         "chain_ok": True,
+                         "latest_receipt_hash": None}
+        if backend_live:
+            try:
+                import szl_governed_infer as _gi
+                demo_statuses = [
+                    _gi.inference_receipt_status(m["model_id"])
+                    for m in ALLOY_ROSTER if m.get("tier_band") == "demo_cpu"
+                ]
+                proven = [s for s in demo_statuses
+                          if s.get("inference_receipted")]
+                receipt_state = (proven[-1] if proven else {
+                    "inference_receipted": False,
+                    "successful_receipt_count": 0,
+                    "chain_ok": all(s.get("chain_ok", False)
+                                    for s in demo_statuses),
+                    "latest_receipt_hash": None,
+                })
+            except Exception as exc:
+                receipt_state["chain_ok"] = False
+                receipt_state["reason"] = (
+                    "receipt ledger unavailable: %s" % type(exc).__name__)
+        operational = bool(backend_live
+                           and receipt_state.get("inference_receipted"))
         return JSONResponse({
-            "backend": "llama.cpp", "backend_available": backend_available(),
+            "backend": "llama.cpp", "backend_available": backend_live,
             "gguf_present": bool(path), "gguf_path": path,
             "gguf_sha256_fp": _gguf_sha(path), "backend_error": _LLAMA_ERR,
-            "live_demo_possible": backend_available(),
-            "honest_label": ("LIVE local CPU serving ready (llama.cpp + GGUF present)."
-                             if backend_available() else
-                             "No local GGUF in this CPU Space -> capable tier is tower-side (honest). "
-                             "Mount /app/models/*.gguf or set A11OY_ALLOY_GGUF to serve the demo tier live."),
+            "live_demo_possible": backend_live,
+            "inference_receipted": bool(receipt_state.get("inference_receipted")),
+            "operational": operational,
+            "honest_stub": not operational,
+            "receipt_state": receipt_state,
+            "honest_label": ("LIVE_RECEIPTED: local CPU serving has durable inference proof."
+                             if operational else
+                             ("REACHABLE_UNRECEIPTED: llama.cpp + GGUF load, but no "
+                              "durable successful-inference receipt exists yet."
+                              if backend_live else
+                              "No local GGUF in this CPU Space -> capable tier is tower-side (honest). "
+                              "Mount /app/models/*.gguf or set A11OY_ALLOY_GGUF to serve the demo tier live.")),
             "doctrine": DOCTRINE,
         })
 

szl_anatomy_3d.py

@@ -953,6 +953,16 @@ def register(app, ns: str = "a11oy") -> Dict[str, Any]:
         return HTMLResponse(_page_body(ns))
     paths.append("/body-3d")
 
+    # Incremental Anatomy v6 keeps the v5 body route untouched and opens the
+    # receipt-driven cortical surface in the shared sovereign Three.js shell.
+    # That surface renders no node, edge, or pulse without a measured inventory
+    # decision / written feed receipt from the Brain reranker API.
+    @app.get("/body-3d-v6")
+    async def _p_body_v6():  # noqa
+        from starlette.responses import RedirectResponse
+        return RedirectResponse("/holographic#brainreranker", status_code=307)
+    paths.append("/body-3d-v6")
+
     # ---- live JSON endpoints (wired to real evaluators + Khipu DAG + DSSE) ----
     @app.post(f"{base}/yuyay-13/vote")
     async def _e_yuyay(req: Request):  # noqa

szl_anatomy_brainloop.py

@@ -815,6 +815,23 @@ def salience_topk(k: int = 8, ns: str = "a11oy") -> list:
     return view.get("source_salience", [])[:k]
 
 
+def evidence_receipt_anatomy(node_id: str, ns: str = "a11oy") -> tuple:
+    """Existing Anatomy v5 bridge to the Brain evidence receipt contract.
+
+    This is a pure GET view: it reuses the reranker's deterministic per-node
+    anatomy and an already-written Ouroboros receipt when one matches the current
+    inventory. It never mints on read and returns explicit UNKNOWN/UNVERIFIED
+    fields when no written receipt exists.
+    """
+    try:
+        import szl_brain_reranker as _reranker
+        return _reranker.anatomy_receipt(str(node_id), ns)
+    except Exception as exc:
+        return ({"ok": False, "status": LABEL_UNAVAILABLE,
+                 "reason": f"evidence receipt unavailable: {type(exc).__name__}",
+                 "receipt_sha256": "UNKNOWN"}, 503)
+
+
 # --------------------------------------------------------------------------- #
 # Registration — POST /anatomy/pulse (write), GET /anatomy/salience (read).
 # Raw-Request handlers via app.router.add_route (fallback add_api_route). These
@@ -851,10 +868,17 @@ def register(app, ns: str = "a11oy") -> list:
         from starlette.responses import JSONResponse
         return JSONResponse(self_audit(ns=ns))
 
+    async def _evidence_receipt_handler(request: fastapi.Request):
+        from starlette.responses import JSONResponse
+        node_id = str(request.path_params.get("node_id") or "")
+        body, status = evidence_receipt_anatomy(node_id, ns)
+        return JSONResponse(body, status_code=status)
+
     routes = [
         (f"{base}/pulse", _pulse_handler, ["POST"]),
         (f"{base}/salience", _salience_handler, ["GET"]),
         (f"{base}/self-audit", _audit_handler, ["GET"]),
+        (f"{base}/evidence-receipt/{{node_id:path}}", _evidence_receipt_handler, ["GET"]),
     ]
     router = getattr(app, "router", None)
     add_route = getattr(router, "add_route", None) if router else None

szl_boot_preflight.py

@@ -143,6 +143,12 @@ _REGISTRY = [
             "Key identifier surfaced in verify receipts (non-secret).",
             default=None),
 
+    # ---- governed compute authority (store only the bearer SHA-256) ----
+    EnvSpec("A11OY_COMPUTE_TOKEN_SHA256", SECRET, "compute",
+            "SHA-256 of the bearer accepted by stateful Yupaq compute routes. "
+            "Absent => submit/readback routes fail closed.",
+            required=False, default=None),
+
     # ---- energy / GPU lungs (SECRET token + VARIABLE addressing/flags) ----
     EnvSpec("A11OY_GPU_TOKEN", SECRET, "energy",
             "Bearer token for the sovereign GPU node(s). Absent => joules are "

szl_brain_api.py

@@ -50,6 +50,7 @@ import json
 import math
 import os
 import re
+import time
 import urllib.error
 import urllib.request
 
@@ -551,6 +552,9 @@ class BrainIndex:
         Returns a REAL grounding subgraph regardless. Generated prose is ONLY
         produced if a sovereign model is reachable; otherwise it is honestly
         UNAVAILABLE — never fabricated."""
+        # Monotonic server timing only.  This measures elapsed work in this
+        # process; it is not a browser, transport, or end-to-end latency claim.
+        started_ns = time.perf_counter_ns()
         seeds = self.search(q, k=max(5, k))
         seed_ids = [s["id"] for s in seeds]
         personalization = None
@@ -577,9 +581,21 @@ class BrainIndex:
                       if c in self.community_summaries]
 
         answer, answer_label, model = self._maybe_generate(q, grounding, global_ctx)
+        elapsed_ms = round((time.perf_counter_ns() - started_ns) / 1_000_000, 3)
         return {
             "label": LBL_MODELED,
             "query": q,
+            "query_latency": {
+                "label": "MEASURED",
+                "value_ms": elapsed_ms,
+                "unit": "milliseconds",
+                "clock": "time.perf_counter_ns (monotonic)",
+                "basis": "server-observed elapsed duration for this request",
+                "scope": ("BrainIndex.ask retrieval, graph expansion, community context, "
+                          "and optional sovereign generation"),
+                "excludes": ("response serialization, network transport, and browser "
+                             "render time"),
+            },
             "retrieval": "hippoRAG-PPR(local) ⊕ graphRAG-community(global), "
                          "LightRAG-mix merge",
             "seeds": seeds,
@@ -652,11 +668,19 @@ class BrainIndex:
         }
 
     def index_status(self) -> dict:
+        # Raw graph facts are exposed together so clients cannot accidentally
+        # conflate people, distinct artifacts, dedupe lineage, or admission.
+        raw_node_count = self.graph.get("node_count", len(self.nodes))
+        raw_link_count = self.graph.get("link_count", len(self.links))
         return {
             "label": LBL_MODELED,
             "content_hash": self.content_hash,
-            "node_count": len(self.nodes),
-            "link_count": len(self.links),
+            "raw_node_count": raw_node_count,
+            "node_count": raw_node_count,
+            "link_count": raw_link_count,
+            "distinct_artifacts": self.graph.get("distinct_artifacts"),
+            "person_node_count": self.graph.get("person_node_count"),
+            "artifact_note": self.graph.get("artifact_note"),
             "embed_source": self.embed_source,
             "embed_tier": self.embed_tier,
             "embed_dim": self.embed_dim,
@@ -673,7 +697,8 @@ class BrainIndex:
                 "ollama_embeddings": self.embed_source.startswith("ollama"),
             },
             "note": ("hash-embedding similarity is MODELED (a deterministic "
-                     "token-overlap proxy), NEVER MEASURED."),
+                     "token-overlap proxy), NEVER MEASURED. Graph counts come "
+                     "from the current graph and do not imply training admission."),
         }
 
 
@@ -783,6 +808,10 @@ def _selftest() -> None:
 
     st = idx.index_status()
     assert st["embed_tier"] == LBL_MODELED, "embeddings are MODELED, never MEASURED"
+    assert st["raw_node_count"] == idx.graph["node_count"]
+    assert st["link_count"] == idx.graph["link_count"]
+    assert st["distinct_artifacts"] == idx.graph.get("distinct_artifacts")
+    assert st["person_node_count"] == idx.graph.get("person_node_count")
     assert st["vector_backend"] in (
         "sqlite-vec", "numpy-cosine", "python-cosine"), st["vector_backend"]
     assert st["community_count"] >= 1, "at least one community"
@@ -820,6 +849,9 @@ def _selftest() -> None:
     a = idx.ask("what proves the estate thesis", k=8)
     assert a["grounding_subgraph"]["node_count"] >= 1, "real grounding subgraph"
     assert a["cited_node_ids"], "cited node ids present"
+    assert a["query_latency"]["label"] == "MEASURED"
+    assert "perf_counter_ns" in a["query_latency"]["clock"]
+    assert "browser" in a["query_latency"]["excludes"]
     if a["answer_model"] is None:
         assert a["answer"] is None and a["answer_label"] == LBL_UNAVAILABLE, \
             "no model => UNAVAILABLE, never a fabricated answer"

szl_brain_reranker.py

@@ -0,0 +1,978 @@
+# SPDX-License-Identifier: Apache-2.0
+"""Fail-closed Brain evidence inventory, reranker proposal data, and local feed.
+
+This service does not scrape, train, or promote a model.  It turns the Brain graph and
+the canonical local corpus manifests into auditable *proposal* data.  Every raw graph
+node receives a deterministic inventory decision.  Reranker rows are admitted only
+when their evidence is an exact projection of a real Brain node and all declared
+source hashes match verified local bytes.
+
+GETs are pure reads.  The two POST paths are loopback-only writes:
+
+* ``rows`` appends one validated, hash-linked local row;
+* ``feed/refresh`` checkpoints one bounded local Ouroboros cycle.
+
+Missing canonical manifests always produce ``BLOCKED`` dataset/model/evaluation
+readiness and zero rows.  No threshold or proof status is upgraded.
+"""
+
+import datetime
+import hashlib
+import ipaddress
+import json
+import math
+import os
+import pathlib
+import re
+import tempfile
+import threading
+import time
+from typing import Any, Mapping
+
+import szl_braincorpus as _corpus_admission
+import szl_brain_corpus as _brain_projection
+
+
+SERVICE_SCHEMA = "szl.brain.reranker-readiness.v1"
+SOURCE_SCHEMA = "szl.brain.reranker-source.v1"
+ROW_SCHEMA = "szl.brain.reranker-row.v1"
+LEDGER_SCHEMA = "szl.brain.reranker-ledger.v1"
+FEED_SCHEMA = "szl.brain.ouroboros-feed.v1"
+MODEL_SCHEMA = "szl.brain.reranker-model.v1"
+EVAL_SCHEMA = "szl.brain.reranker-evaluation.v1"
+
+READY = "READY"
+BLOCKED = "BLOCKED"
+DEGRADED = "DEGRADED"
+UNAVAILABLE = "UNAVAILABLE"
+UNKNOWN = "UNKNOWN"
+UNVERIFIED = "UNVERIFIED"
+
+EXAMPLE_TYPES = ("positive", "negative", "abstention", "refutation")
+TARGETS = {"positive": 1.0, "negative": 0.0, "abstention": 0.0, "refutation": 0.0}
+FEED_STAGES = (
+    "DISCOVER", "FETCH", "HASH", "CLASSIFY", "DEDUP", "VERIFY",
+    "ADMIT_OR_QUARANTINE", "EVALUATE", "RECEIPT", "REFRESH",
+)
+
+MAX_QUERY_CHARS = 1_024
+MAX_EVIDENCE_CHARS = 12_000
+MAX_ENTITY_CHARS = 160
+MAX_ARTIFACT_EXAMPLES = 10_000
+MAX_LOCAL_ROWS = 2_000
+MAX_LEDGER_BYTES = 32 * 1024 * 1024
+MAX_INVENTORY_PAGE = 500
+MAX_DATASET_PAGE = 500
+FEED_MIN_INTERVAL_S = 60
+FEED_MAX_BACKOFF_S = 3_600
+FEED_NODE_BUDGET = 20_000
+FEED_SOURCE_BUDGET = 5_000
+
+_SHA256_RE = re.compile(r"^[0-9a-f]{64}$")
+_ID_RE = re.compile(r"^[A-Za-z0-9][A-Za-z0-9_.:/-]{0,159}$")
+_LOCK = threading.RLock()
+_INVENTORY_CACHE: dict[str, Any] = {"key": None, "value": None}
+
+
+def _now() -> str:
+    return datetime.datetime.now(datetime.timezone.utc).isoformat()
+
+
+def _canonical_bytes(value: Any) -> bytes:
+    return json.dumps(value, sort_keys=True, separators=(",", ":"),
+                      ensure_ascii=False).encode("utf-8")
+
+
+def _sha(value: Any) -> str:
+    return hashlib.sha256(_canonical_bytes(value)).hexdigest()
+
+
+def _sha_text(value: Any) -> str:
+    return hashlib.sha256(str(value).encode("utf-8")).hexdigest()
+
+
+def _is_sha(value: Any) -> bool:
+    return bool(_SHA256_RE.fullmatch(str(value or "").lower()))
+
+
+def _repo_root(repo_root: pathlib.Path | str | None = None) -> pathlib.Path:
+    return pathlib.Path(repo_root or pathlib.Path(__file__).resolve().parent).resolve()
+
+
+def _runtime_path(name: str, environ: Mapping[str, str], explicit: str) -> pathlib.Path:
+    configured = str(environ.get(explicit, "")).strip()
+    if configured:
+        return pathlib.Path(configured).expanduser().resolve()
+    state_dir = str(environ.get("A11OY_RUNTIME_STATE_DIR", "")).strip()
+    base = pathlib.Path(state_dir).expanduser().resolve() if state_dir else (
+        pathlib.Path(tempfile.gettempdir()) / "a11oy-brain-reranker"
+    ).resolve()
+    return base / name
+
+
+def _ledger_path(environ: Mapping[str, str]) -> pathlib.Path:
+    return _runtime_path("validated-rows.jsonl", environ,
+                         "A11OY_BRAIN_RERANKER_LEDGER")
+
+
+def _feed_path(environ: Mapping[str, str]) -> pathlib.Path:
+    return _runtime_path("ouroboros-feed.jsonl", environ,
+                         "A11OY_BRAIN_FEED_LEDGER")
+
+
+def _safe_read_json(path: pathlib.Path, maximum: int) -> tuple[Any | None, str | None]:
+    try:
+        with path.open("rb") as handle:
+            raw = handle.read(maximum + 1)
+        if len(raw) > maximum:
+            return None, f"FILE_TOO_LARGE:{len(raw)}>{maximum}"
+        return json.loads(raw.decode("utf-8")), None
+    except FileNotFoundError:
+        return None, "FILE_NOT_FOUND"
+    except (OSError, UnicodeError, json.JSONDecodeError) as exc:
+        return None, f"READ_FAILED:{type(exc).__name__}"
+
+
+def _source_family(node: Mapping[str, Any]) -> str:
+    raw = str(node.get("url") or node.get("source") or node.get("path") or
+              node.get("derived_from") or "").strip()
+    if raw.startswith(("http://", "https://")):
+        try:
+            from urllib.parse import urlsplit
+            return (urlsplit(raw).hostname or UNKNOWN).lower()
+        except Exception:
+            return UNKNOWN
+    if raw:
+        return raw.replace("\\", "/").split("/", 1)[0][:160]
+    return UNKNOWN
+
+
+def _source_url(node: Mapping[str, Any]) -> str:
+    raw = str(node.get("url") or "").strip()
+    return raw if raw.startswith(("http://", "https://")) else UNKNOWN
+
+
+def _revision(node: Mapping[str, Any]) -> str:
+    for key in ("revision", "commit", "commit_sha", "sha", "version", "rev"):
+        value = str(node.get(key) or "").strip()
+        if value:
+            return value[:200]
+    return UNKNOWN
+
+
+def _license(node: Mapping[str, Any]) -> str:
+    for key in ("license", "license_id", "spdx", "spdx_id"):
+        value = str(node.get(key) or "").strip()
+        if value:
+            return value[:200]
+    return UNKNOWN
+
+
+def _freshness(node: Mapping[str, Any]) -> tuple[str, str]:
+    for key in ("retrieved_at", "captured_at", "updated_at", "published_at", "timestamp", "date"):
+        value = str(node.get(key) or "").strip()
+        if value:
+            return value[:200], "SOURCE_TIMESTAMP"
+    return UNKNOWN, "UNVERIFIED"
+
+
+def _node_content(node: Mapping[str, Any]) -> dict[str, Any]:
+    """Hash only source-authored graph fields; never request time or derived verdicts."""
+    return {str(k): node[k] for k in sorted(node) if not str(k).startswith("_")}
+
+
+def _canonical_key(node: Mapping[str, Any], content_sha256: str) -> str:
+    url = _source_url(node)
+    if url != UNKNOWN:
+        return "url:" + url.rstrip("/").lower()
+    formula = str(node.get("formula_id") or "").strip().upper()
+    if formula:
+        return "formula:" + formula
+    title = str(node.get("title") or node.get("label") or "").strip().lower()
+    kind = str(node.get("kind") or "node").strip().lower()
+    if title:
+        return f"{kind}:{title}"
+    return "content:" + content_sha256
+
+
+def _graph_nodes(ns: str = "a11oy") -> tuple[list[dict[str, Any]], str | None]:
+    try:
+        import a11oy_brain_graph as graph
+        built = graph.get_brain_graph(ns)
+        nodes = built.get("nodes") if isinstance(built, dict) else None
+        if not isinstance(nodes, list):
+            return [], "GRAPH_NODES_UNAVAILABLE"
+        return [dict(n) for n in nodes if isinstance(n, dict)], None
+    except Exception as exc:
+        return [], f"GRAPH_UNAVAILABLE:{type(exc).__name__}"
+
+
+def _canonical_context(repo_root: pathlib.Path | str | None,
+                       environ: Mapping[str, str]) -> dict[str, Any]:
+    root = _repo_root(repo_root)
+    status = _corpus_admission.build_corpus_status(root, environ)
+    sources = status.get("sources") if isinstance(status, dict) else []
+    source_map: dict[tuple[str, str], dict[str, Any]] = {}
+    complete = True
+    reasons: list[str] = []
+    for source in sources if isinstance(sources, list) else []:
+        source_type = str(source.get("source_type") or "")
+        source_status = str(source.get("status") or "")
+        manifest_hash = str(source.get("manifest_sha256") or "").lower()
+        if source_status not in {"INGESTED_LOCAL", "PARTIAL_QUARANTINE"} or not _is_sha(manifest_hash):
+            complete = False
+            reasons.append(f"{source_type}:{source_status or 'SOURCE_UNAVAILABLE'}")
+        manifest_path, boundary, origin, path_error = _corpus_admission._safe_manifest_path(
+            source_type, root, environ,
+        )
+        for entry in source.get("entries", []) if isinstance(source.get("entries"), list) else []:
+            if not entry.get("artifact_verified"):
+                continue
+            source_path = str(entry.get("source_path") or "")
+            artifact = (boundary / pathlib.Path(source_path)).resolve() if source_path else None
+            if artifact is None or not _corpus_admission._inside(artifact, boundary):
+                continue
+            source_map[(source_type, str(entry.get("id") or ""))] = {
+                "source_type": source_type,
+                "source_entry_id": str(entry.get("id") or ""),
+                "manifest_sha256": manifest_hash,
+                "manifest_path": manifest_path,
+                "manifest_origin": origin,
+                "artifact_path": artifact,
+                "artifact_sha256": str(entry.get("artifact_sha256") or "").lower(),
+                "artifact_receipt": entry.get("artifact_receipt"),
+                "proof_receipt": entry.get("proof_receipt"),
+                "evidence_class": entry.get("effective_class"),
+            }
+        if path_error:
+            complete = False
+            reasons.append(f"{source_type}:{path_error}")
+    if len(sources or []) != len(_corpus_admission.SOURCE_TYPES):
+        complete = False
+        reasons.append("CANONICAL_SOURCE_ROSTER_INCOMPLETE")
+    return {
+        "complete": complete,
+        "reasons": sorted(set(reasons)),
+        "status": status,
+        "source_map": source_map,
+        "root": root,
+    }
+
+
+def _brain_docs(ns: str) -> tuple[dict[str, dict[str, str]], str | None]:
+    try:
+        docs = _brain_projection.corpus(ns, limit=20_000, include_people=True)
+    except Exception as exc:
+        return {}, f"BRAIN_PROJECTION_FAILED:{type(exc).__name__}"
+    result: dict[str, dict[str, str]] = {}
+    for doc in docs if isinstance(docs, list) else []:
+        if isinstance(doc, dict) and doc.get("id"):
+            result[str(doc["id"])] = {
+                "id": str(doc["id"]), "text": str(doc.get("text") or ""),
+                "source": str(doc.get("source") or ""),
+            }
+    return result, None if result else "BRAIN_PROJECTION_EMPTY"
+
+
+def build_inventory(ns: str = "a11oy", repo_root: pathlib.Path | str | None = None,
+                    environ: Mapping[str, str] | None = None) -> dict[str, Any]:
+    """Return one decision for every raw graph node, plus canonical/dedupe posture."""
+    env = os.environ if environ is None else environ
+    canonical = _canonical_context(repo_root, env)
+    nodes, graph_error = _graph_nodes(ns)
+    graph_hash = _sha([_node_content(n) for n in nodes]) if nodes else None
+    cache_key = _sha({"graph": graph_hash, "canonical": [
+        (s.get("source_type"), s.get("manifest_sha256"), s.get("status"))
+        for s in (canonical["status"].get("sources") or [])
+    ]})
+    with _LOCK:
+        if _INVENTORY_CACHE.get("key") == cache_key and _INVENTORY_CACHE.get("value") is not None:
+            return _INVENTORY_CACHE["value"]
+
+    seen: dict[str, str] = {}
+    decisions: list[dict[str, Any]] = []
+    reasons: dict[str, int] = {}
+    canonical_count = 0
+    for index, node in enumerate(nodes):
+        node_id = str(node.get("id") or f"raw-index:{index}")
+        content_sha = _sha(_node_content(node))
+        key = _canonical_key(node, content_sha)
+        duplicate_of = seen.get(key)
+        if duplicate_of is None:
+            seen[key] = node_id
+            canonical_count += 1
+        source_identity = str(node.get("source") or node.get("url") or node.get("path") or
+                              node.get("derived_from") or UNKNOWN)[:500]
+        retrieved_at, freshness_basis = _freshness(node)
+        reason_codes: list[str] = []
+        if duplicate_of:
+            reason_codes.append("DUPLICATE_CANONICAL_KEY")
+        if source_identity == UNKNOWN:
+            reason_codes.append("PROVENANCE_UNKNOWN")
+        if _revision(node) == UNKNOWN:
+            reason_codes.append("REVISION_UNKNOWN")
+        if _license(node) == UNKNOWN:
+            reason_codes.append("LICENSE_UNKNOWN")
+        if retrieved_at == UNKNOWN:
+            reason_codes.append("FRESHNESS_UNKNOWN")
+        if not canonical["complete"]:
+            reason_codes.append("CANONICAL_MANIFESTS_REQUIRED")
+        decision = "ADMITTED_TO_CANONICAL_MAP" if not reason_codes else "QUARANTINED"
+        if decision == "QUARANTINED":
+            for reason in reason_codes:
+                reasons[reason] = reasons.get(reason, 0) + 1
+        anatomy_core = {
+            "raw_index": index,
+            "brain_node_id": node_id,
+            "node_content_sha256": content_sha,
+            "source_identity": source_identity,
+            "source_url": _source_url(node),
+            "source_family": _source_family(node),
+            "source_revision": _revision(node),
+            "license": _license(node),
+            "robots_policy": "NOT_APPLICABLE_LOCAL_SNAPSHOT",
+            "retrieved_at": retrieved_at,
+            "freshness_basis": freshness_basis,
+            "canonical_key_sha256": _sha_text(key),
+            "canonical_node_id": duplicate_of or node_id,
+            "deduplicated": bool(duplicate_of),
+            "formula_id": str(node.get("formula_id") or UNKNOWN),
+            "proof_status": str(node.get("proof_status") or UNKNOWN),
+            "admission_decision": decision,
+            "reason_codes": reason_codes,
+            "split_assignment": "NOT_ASSIGNED",
+            "training_eligible": False,
+            "model_receipt_sha256": UNKNOWN,
+            "evaluation_receipt_sha256": UNKNOWN,
+        }
+        decisions.append({**anatomy_core, "anatomy_record_sha256": _sha(anatomy_core)})
+
+    inventory_core = {
+        "graph_content_sha256": graph_hash,
+        "raw_node_count": len(nodes),
+        "decision_count": len(decisions),
+        "canonical_node_count": canonical_count,
+        "quarantined_node_count": sum(d["admission_decision"] == "QUARANTINED" for d in decisions),
+        "reason_counts": dict(sorted(reasons.items())),
+    }
+    value = {
+        "ok": graph_error is None,
+        "label": "MEASURED" if graph_error is None else UNAVAILABLE,
+        "schema_version": SERVICE_SCHEMA,
+        "inventory": inventory_core,
+        "inventory_sha256": _sha(inventory_core),
+        "canonical_manifests_complete": canonical["complete"],
+        "canonical_manifest_reasons": canonical["reasons"],
+        "decisions": decisions,
+        "graph_error": graph_error,
+        "note": "Every raw node has one decision; no node is silently dropped.",
+    }
+    with _LOCK:
+        _INVENTORY_CACHE.update({"key": cache_key, "value": value})
+    return value
+
+
+def _row_core(example: Mapping[str, Any], source: Mapping[str, Any],
+              doc: Mapping[str, str], origin: str) -> tuple[dict[str, Any] | None, list[str]]:
+    errors: list[str] = []
+    example_type = str(example.get("example_type") or "").strip().lower()
+    query = str(example.get("query") or "").strip()
+    evidence = str(example.get("evidence_text") or "")
+    example_id = str(example.get("example_id") or "").strip()
+    entity_id = str(example.get("entity_id") or "").strip()
+    node_id = str(example.get("brain_node_id") or "").strip()
+    try:
+        target = float(example.get("target_relevance"))
+    except (TypeError, ValueError):
+        target = math.nan
+    if not _ID_RE.fullmatch(example_id): errors.append("INVALID_EXAMPLE_ID")
+    if not _ID_RE.fullmatch(entity_id): errors.append("INVALID_ENTITY_ID")
+    if not query or len(query) > MAX_QUERY_CHARS: errors.append("INVALID_QUERY")
+    if not evidence or len(evidence) > MAX_EVIDENCE_CHARS: errors.append("INVALID_EVIDENCE")
+    if example_type not in EXAMPLE_TYPES: errors.append("INVALID_EXAMPLE_TYPE")
+    if example_type in TARGETS and target != TARGETS[example_type]: errors.append("TARGET_TYPE_MISMATCH")
+    if node_id != doc.get("id"): errors.append("BRAIN_NODE_ID_MISMATCH")
+    if evidence != doc.get("text"): errors.append("EVIDENCE_NOT_EXACT_BRAIN_PROJECTION")
+    node_hash = _sha({"id": doc.get("id"), "text": doc.get("text"), "source": doc.get("source")})
+    source_hash = _sha_text(doc.get("source"))
+    declared_node_hash = str(example.get("brain_node_sha256") or "").lower()
+    declared_source_hash = str(example.get("brain_source_sha256") or "").lower()
+    if declared_node_hash != node_hash: errors.append("BRAIN_NODE_HASH_MISMATCH")
+    if declared_source_hash != source_hash: errors.append("BRAIN_SOURCE_HASH_MISMATCH")
+    if errors:
+        return None, sorted(set(errors))
+    source_receipt = (source.get("artifact_receipt") or {}).get("receipt_sha256")
+    if not _is_sha(source_receipt):
+        source_receipt = (source.get("proof_receipt") or {}).get("receipt_sha256")
+    if not _is_sha(source_receipt):
+        source_receipt = _sha({
+            "source_manifest_sha256": source["manifest_sha256"],
+            "source_artifact_sha256": source["artifact_sha256"],
+            "brain_node_sha256": node_hash,
+            "brain_source_sha256": source_hash,
+        })
+    core = {
+        "schema_version": ROW_SCHEMA,
+        "example_id": example_id,
+        "example_type": example_type,
+        "target_relevance": target,
+        "query": query,
+        "evidence_text": evidence,
+        "entity_id": entity_id,
+        "source_type": source["source_type"],
+        "source_entry_id": source["source_entry_id"],
+        "source_manifest_sha256": source["manifest_sha256"],
+        "source_artifact_sha256": source["artifact_sha256"],
+        "source_receipt_sha256": source_receipt,
+        "brain_node_id": node_id,
+        "brain_node_sha256": node_hash,
+        "brain_source_sha256": source_hash,
+        "origin": origin,
+    }
+    return {**core, "row_receipt_sha256": _sha(core)}, []
+
+
+def _load_embedded_rows(canonical: Mapping[str, Any], docs: Mapping[str, dict[str, str]]) -> tuple[list[dict], list[dict]]:
+    rows: list[dict] = []
+    rejected: list[dict] = []
+    for source in canonical["source_map"].values():
+        payload, error = _safe_read_json(source["artifact_path"], _corpus_admission.MAX_ARTIFACT_BYTES)
+        if error or not isinstance(payload, dict) or payload.get("schema_version") != SOURCE_SCHEMA:
+            continue
+        examples = payload.get("examples")
+        if not isinstance(examples, list):
+            rejected.append({"source_entry_id": source["source_entry_id"],
+                             "reasons": ["EXAMPLES_MUST_BE_ARRAY"]})
+            continue
+        for raw in examples[:MAX_ARTIFACT_EXAMPLES]:
+            if not isinstance(raw, dict):
+                rejected.append({"source_entry_id": source["source_entry_id"],
+                                 "reasons": ["EXAMPLE_NOT_OBJECT"]})
+                continue
+            doc = docs.get(str(raw.get("brain_node_id") or ""), {})
+            row, reasons = _row_core(raw, source, doc, "CANONICAL_ARTIFACT")
+            if row:
+                rows.append(row)
+            else:
+                rejected.append({"source_entry_id": source["source_entry_id"],
+                                 "example_id": raw.get("example_id"), "reasons": reasons})
+    return rows, rejected
+
+
+def _read_jsonl(path: pathlib.Path, maximum: int) -> tuple[list[Any], list[str]]:
+    if not path.is_file():
+        return [], []
+    try:
+        if path.stat().st_size > maximum:
+            return [], [f"LEDGER_TOO_LARGE:{path.stat().st_size}>{maximum}"]
+        rows, errors = [], []
+        with path.open("r", encoding="utf-8") as handle:
+            for i, line in enumerate(handle):
+                try:
+                    rows.append(json.loads(line))
+                except json.JSONDecodeError:
+                    errors.append(f"INVALID_JSON_LINE:{i + 1}")
+        return rows, errors
+    except OSError as exc:
+        return [], [f"LEDGER_READ_FAILED:{type(exc).__name__}"]
+
+
+def _load_local_rows(path: pathlib.Path, canonical: Mapping[str, Any],
+                     docs: Mapping[str, dict[str, str]]) -> tuple[list[dict], dict[str, Any]]:
+    records, errors = _read_jsonl(path, MAX_LEDGER_BYTES)
+    rows: list[dict] = []
+    prev = "0" * 64
+    valid_chain = not errors
+    for i, record in enumerate(records[:MAX_LOCAL_ROWS]):
+        if not isinstance(record, dict) or record.get("schema_version") != LEDGER_SCHEMA:
+            errors.append(f"INVALID_LEDGER_RECORD:{i}")
+            valid_chain = False
+            continue
+        stored_prev = str(record.get("prev_hash") or "")
+        stored_hash = str(record.get("entry_sha256") or "")
+        raw = record.get("row")
+        computed = _sha({"prev_hash": stored_prev, "row": raw})
+        if stored_prev != prev or stored_hash != computed or not isinstance(raw, dict):
+            errors.append(f"CHAIN_MISMATCH:{i}")
+            valid_chain = False
+            continue
+        source = canonical["source_map"].get((str(raw.get("source_type")),
+                                               str(raw.get("source_entry_id"))))
+        doc = docs.get(str(raw.get("brain_node_id") or ""), {})
+        if source is None:
+            errors.append(f"SOURCE_BINDING_GONE:{i}")
+            valid_chain = False
+            continue
+        row, reasons = _row_core(raw, source, doc, "LOCAL_VALIDATED_APPEND")
+        if row is None or row.get("row_receipt_sha256") != raw.get("row_receipt_sha256"):
+            errors.append(f"ROW_REVALIDATION_FAILED:{i}:{','.join(reasons)}")
+            valid_chain = False
+            continue
+        row["ledger_entry_sha256"] = stored_hash
+        rows.append(row)
+        prev = stored_hash
+    return rows, {"chain_valid": valid_chain, "record_count": len(records),
+                  "valid_row_count": len(rows), "head_sha256": prev,
+                  "errors": errors}
+
+
+def _split_group(row: Mapping[str, Any]) -> str:
+    group = f"{row['source_type']}|{row['source_entry_id']}|{row['entity_id']}"
+    bucket = int(hashlib.sha256(("split-v1|" + group).encode()).hexdigest()[:8], 16) % 10
+    return "train" if bucket < 7 else ("eval" if bucket < 9 else "test")
+
+
+def _verify_optional_manifest(path: pathlib.Path, schema: str, dataset_hash: str,
+                              model_hash: str | None = None) -> dict[str, Any]:
+    payload, error = _safe_read_json(path, 2 * 1024 * 1024)
+    if error:
+        return {"status": BLOCKED, "reasons": [error], "receipt_sha256": UNKNOWN}
+    reasons: list[str] = []
+    if not isinstance(payload, dict) or payload.get("schema_version") != schema:
+        reasons.append("SCHEMA_MISMATCH")
+    else:
+        body = {k: v for k, v in payload.items() if k != "content_sha256"}
+        if payload.get("content_sha256") != _sha(body): reasons.append("CONTENT_HASH_MISMATCH")
+        if payload.get("dataset_sha256") != dataset_hash: reasons.append("DATASET_HASH_MISMATCH")
+        if model_hash is not None and payload.get("model_sha256") != model_hash:
+            reasons.append("MODEL_HASH_MISMATCH")
+    return {"status": READY if not reasons else BLOCKED, "reasons": reasons,
+            "receipt_sha256": (payload or {}).get("receipt_sha256", UNKNOWN),
+            "manifest": payload if not reasons else None}
+
+
+def build_dataset(ns: str = "a11oy", repo_root: pathlib.Path | str | None = None,
+                  environ: Mapping[str, str] | None = None,
+                  ledger_path: pathlib.Path | str | None = None) -> dict[str, Any]:
+    env = os.environ if environ is None else environ
+    canonical = _canonical_context(repo_root, env)
+    docs, doc_error = _brain_docs(ns)
+    if not canonical["complete"] or doc_error:
+        reasons = list(canonical["reasons"])
+        if doc_error: reasons.append(doc_error)
+        return {
+            "ok": True, "schema_version": SERVICE_SCHEMA, "label": UNAVAILABLE,
+            "rows": [], "dataset_sha256": None,
+            "dataset_readiness": {"status": BLOCKED, "reasons": sorted(set(reasons))},
+            "evaluation_readiness": {"status": BLOCKED, "reasons": ["DATASET_BLOCKED"]},
+            "model_readiness": {"status": BLOCKED, "reasons": ["DATASET_BLOCKED"]},
+            "split_counts": {"train": 0, "eval": 0, "test": 0},
+            "example_type_counts": {name: 0 for name in EXAMPLE_TYPES},
+            "quarantined_rows": [], "ledger": {"chain_valid": True, "record_count": 0},
+            "canonical_manifests_complete": canonical["complete"],
+            "training_triggered": False,
+        }
+    embedded, rejected = _load_embedded_rows(canonical, docs)
+    ledger = pathlib.Path(ledger_path).resolve() if ledger_path else _ledger_path(env)
+    appended, ledger_state = _load_local_rows(ledger, canonical, docs)
+    rows_by_receipt: dict[str, dict] = {}
+    for row in embedded + appended:
+        rows_by_receipt.setdefault(row["row_receipt_sha256"], row)
+    rows = list(rows_by_receipt.values())
+    for row in rows:
+        row["split"] = _split_group(row)
+    rows.sort(key=lambda r: (r["split"], r["source_type"], r["entity_id"], r["example_id"]))
+    type_counts = {name: sum(r["example_type"] == name for r in rows) for name in EXAMPLE_TYPES}
+    split_counts = {name: sum(r["split"] == name for r in rows) for name in ("train", "eval", "test")}
+    groups: dict[tuple[str, str, str], set[str]] = {}
+    for row in rows:
+        key = (row["source_type"], row["source_entry_id"], row["entity_id"])
+        groups.setdefault(key, set()).add(row["split"])
+    leakage = sum(len(v) > 1 for v in groups.values())
+    reasons = []
+    missing_types = [name for name, count in type_counts.items() if count == 0]
+    if not rows: reasons.append("ZERO_GROUNDED_ROWS")
+    if missing_types: reasons.append("MISSING_REQUIRED_EXAMPLE_TYPES:" + ",".join(missing_types))
+    if leakage: reasons.append(f"SOURCE_ENTITY_SPLIT_LEAKAGE:{leakage}")
+    if not ledger_state["chain_valid"]: reasons.append("LOCAL_LEDGER_CHAIN_INVALID")
+    dataset_hash = _sha([{k: row[k] for k in sorted(row) if k != "ledger_entry_sha256"}
+                         for row in rows]) if rows else None
+    dataset_status = READY if not reasons else BLOCKED
+
+    model_path = _runtime_path("model-manifest.json", env,
+                               "A11OY_BRAIN_RERANKER_MODEL_MANIFEST")
+    model = _verify_optional_manifest(model_path, MODEL_SCHEMA, dataset_hash or "") \
+        if dataset_status == READY else {"status": BLOCKED, "reasons": ["DATASET_BLOCKED"],
+                                         "receipt_sha256": UNKNOWN}
+    model_hash = ((model.get("manifest") or {}).get("model_sha256")
+                  if model.get("status") == READY else None)
+    eval_path = _runtime_path("evaluation-manifest.json", env,
+                              "A11OY_BRAIN_RERANKER_EVAL_MANIFEST")
+    if dataset_status != READY:
+        evaluation = {"status": BLOCKED, "reasons": ["DATASET_BLOCKED"],
+                      "receipt_sha256": UNKNOWN}
+    elif model.get("status") != READY:
+        evaluation = {"status": BLOCKED, "reasons": ["MODEL_BLOCKED"],
+                      "receipt_sha256": UNKNOWN}
+    elif not split_counts["test"]:
+        evaluation = {"status": BLOCKED, "reasons": ["TEST_SPLIT_EMPTY"],
+                      "receipt_sha256": UNKNOWN}
+    else:
+        evaluation = _verify_optional_manifest(eval_path, EVAL_SCHEMA,
+                                               dataset_hash or "", model_hash)
+    return {
+        "ok": True, "schema_version": SERVICE_SCHEMA, "label": "MEASURED",
+        "rows": rows, "dataset_sha256": dataset_hash,
+        "dataset_readiness": {"status": dataset_status, "reasons": reasons},
+        "model_readiness": model, "evaluation_readiness": evaluation,
+        "split_counts": split_counts, "example_type_counts": type_counts,
+        "source_entity_group_count": len(groups), "split_leakage_group_count": leakage,
+        "quarantined_rows": rejected, "ledger": ledger_state,
+        "canonical_manifests_complete": True, "training_triggered": False,
+    }
+
+
+def append_validated_row(payload: Mapping[str, Any], ns: str = "a11oy",
+                         repo_root: pathlib.Path | str | None = None,
+                         environ: Mapping[str, str] | None = None,
+                         ledger_path: pathlib.Path | str | None = None) -> tuple[dict, int]:
+    """Append one hash-bound row after revalidating all local source bytes."""
+    env = os.environ if environ is None else environ
+    canonical = _canonical_context(repo_root, env)
+    if not canonical["complete"]:
+        return {"ok": False, "status": BLOCKED, "reasons": canonical["reasons"],
+                "row": None}, 503
+    docs, doc_error = _brain_docs(ns)
+    if doc_error:
+        return {"ok": False, "status": BLOCKED, "reasons": [doc_error], "row": None}, 503
+    source = canonical["source_map"].get((str(payload.get("source_type") or ""),
+                                           str(payload.get("source_entry_id") or "")))
+    if source is None:
+        return {"ok": False, "status": BLOCKED, "reasons": ["SOURCE_BINDING_NOT_VERIFIED"],
+                "row": None}, 422
+    required_hashes = {
+        "source_manifest_sha256": source["manifest_sha256"],
+        "source_artifact_sha256": source["artifact_sha256"],
+    }
+    mismatch = [key + "_MISMATCH" for key, expected in required_hashes.items()
+                if str(payload.get(key) or "").lower() != expected]
+    doc = docs.get(str(payload.get("brain_node_id") or ""), {})
+    row, reasons = _row_core(payload, source, doc, "LOCAL_VALIDATED_APPEND")
+    if mismatch or row is None:
+        return {"ok": False, "status": BLOCKED,
+                "reasons": sorted(set(mismatch + reasons)), "row": None}, 422
+    path = pathlib.Path(ledger_path).resolve() if ledger_path else _ledger_path(env)
+    with _LOCK:
+        existing, state = _load_local_rows(path, canonical, docs)
+        if not state["chain_valid"]:
+            return {"ok": False, "status": BLOCKED,
+                    "reasons": ["LOCAL_LEDGER_CHAIN_INVALID"], "row": None}, 409
+        if state["record_count"] >= MAX_LOCAL_ROWS:
+            return {"ok": False, "status": BLOCKED,
+                    "reasons": ["LOCAL_ROW_LIMIT_REACHED"], "row": None}, 429
+        if any(r["row_receipt_sha256"] == row["row_receipt_sha256"] for r in existing):
+            return {"ok": True, "status": READY, "duplicate": True, "row": row}, 200
+        prev = state["head_sha256"]
+        record = {"schema_version": LEDGER_SCHEMA, "prev_hash": prev, "row": row}
+        record["entry_sha256"] = _sha({"prev_hash": prev, "row": row})
+        path.parent.mkdir(parents=True, exist_ok=True)
+        with path.open("a", encoding="utf-8", newline="\n") as handle:
+            handle.write(json.dumps(record, sort_keys=True, ensure_ascii=False) + "\n")
+            handle.flush()
+            os.fsync(handle.fileno())
+    return {"ok": True, "status": READY, "duplicate": False,
+            "row": {**row, "ledger_entry_sha256": record["entry_sha256"]}}, 201
+
+
+def _last_feed_state(path: pathlib.Path) -> dict[str, Any]:
+    records, errors = _read_jsonl(path, MAX_LEDGER_BYTES)
+    prev = "0" * 64
+    valid = not errors
+    last = None
+    for i, record in enumerate(records):
+        if not isinstance(record, dict) or record.get("schema_version") != FEED_SCHEMA:
+            valid = False; errors.append(f"INVALID_FEED_RECORD:{i}"); continue
+        stored = str(record.get("receipt_sha256") or "")
+        body = {k: v for k, v in record.items() if k != "receipt_sha256"}
+        if record.get("prev_hash") != prev or stored != _sha(body):
+            valid = False; errors.append(f"FEED_CHAIN_MISMATCH:{i}"); continue
+        prev, last = stored, record
+    return {"chain_valid": valid, "record_count": len(records), "head_sha256": prev,
+            "last": last, "errors": errors}
+
+
+def feed_status(ns: str = "a11oy", repo_root: pathlib.Path | str | None = None,
+                environ: Mapping[str, str] | None = None,
+                feed_path: pathlib.Path | str | None = None) -> dict[str, Any]:
+    env = os.environ if environ is None else environ
+    path = pathlib.Path(feed_path).resolve() if feed_path else _feed_path(env)
+    state = _last_feed_state(path)
+    enabled = str(env.get("A11OY_BRAIN_FEED_ENABLED", "0")).strip().lower() in {"1", "true", "yes"}
+    killed = str(env.get("A11OY_BRAIN_FEED_KILL_SWITCH", "1")).strip().lower() not in {"0", "false", "no"}
+    last = state.get("last") or {}
+    return {
+        "ok": True, "schema_version": FEED_SCHEMA,
+        "status": (DEGRADED if enabled and not killed and state["chain_valid"] else UNAVAILABLE),
+        "enabled": enabled, "kill_switch_engaged": killed,
+        "network_access": False, "training_trigger": False,
+        "stages": list(FEED_STAGES),
+        "bounds": {"node_budget": FEED_NODE_BUDGET, "per_source_budget": FEED_SOURCE_BUDGET,
+                   "minimum_interval_seconds": FEED_MIN_INTERVAL_S,
+                   "maximum_backoff_seconds": FEED_MAX_BACKOFF_S,
+                   "network_rate_limit": "ZERO_NETWORK_REQUESTS"},
+        "checkpoint": last.get("checkpoint", "NOT_STARTED"),
+        "last_successful_receipt": last.get("receipt_sha256", UNKNOWN),
+        "last_inventory_sha256": last.get("inventory_sha256", UNKNOWN),
+        "admitted_count": last.get("admitted_count", 0),
+        "quarantined_count": last.get("quarantined_count", 0),
+        "freshness_state": last.get("freshness_state", UNKNOWN),
+        "next_refresh_utc": last.get("next_refresh_utc", UNKNOWN),
+        "backoff_seconds": last.get("backoff_seconds", 0),
+        "receipt_chain": {k: state[k] for k in ("chain_valid", "record_count", "head_sha256", "errors")},
+    }
+
+
+def refresh_feed(ns: str = "a11oy", repo_root: pathlib.Path | str | None = None,
+                 environ: Mapping[str, str] | None = None,
+                 feed_path: pathlib.Path | str | None = None) -> tuple[dict, int]:
+    """Run one bounded local-only cycle; no network fetch and no training trigger."""
+    env = os.environ if environ is None else environ
+    path = pathlib.Path(feed_path).resolve() if feed_path else _feed_path(env)
+    status = feed_status(ns, repo_root, env, path)
+    if not status["enabled"] or status["kill_switch_engaged"]:
+        return {**status, "ok": False, "reason": "FEED_DISABLED_OR_KILLED"}, 503
+    state = _last_feed_state(path)
+    last = state.get("last") or {}
+    now = time.time()
+    try:
+        last_epoch = datetime.datetime.fromisoformat(str(last.get("completed_at"))).timestamp()
+    except Exception:
+        last_epoch = 0.0
+    if last_epoch and now - last_epoch < FEED_MIN_INTERVAL_S:
+        return {**status, "ok": False, "reason": "REFRESH_RATE_LIMITED"}, 429
+    inventory = build_inventory(ns, repo_root, env)
+    if inventory["inventory"]["raw_node_count"] > FEED_NODE_BUDGET:
+        return {**status, "ok": False, "reason": "NODE_BUDGET_EXCEEDED"}, 503
+    dataset = build_dataset(ns, repo_root, env)
+    completed = _now()
+    next_refresh = (datetime.datetime.now(datetime.timezone.utc) +
+                    datetime.timedelta(seconds=FEED_MIN_INTERVAL_S)).isoformat()
+    record = {
+        "schema_version": FEED_SCHEMA,
+        "prev_hash": state["head_sha256"],
+        "checkpoint": f"inventory:{inventory['inventory_sha256']}:rows:{len(dataset['rows'])}",
+        "completed_at": completed,
+        "inventory_sha256": inventory["inventory_sha256"],
+        "dataset_sha256": dataset.get("dataset_sha256") or UNKNOWN,
+        "raw_node_count": inventory["inventory"]["raw_node_count"],
+        "admitted_count": inventory["inventory"]["raw_node_count"] - inventory["inventory"]["quarantined_node_count"],
+        "quarantined_count": inventory["inventory"]["quarantined_node_count"],
+        "dataset_row_count": len(dataset["rows"]),
+        "dataset_status": dataset["dataset_readiness"]["status"],
+        "freshness_state": ("VERIFIED_SOURCE_TIMESTAMPS_PRESENT" if any(
+            d["freshness_basis"] == "SOURCE_TIMESTAMP" for d in inventory["decisions"]
+        ) else "UNVERIFIED"),
+        "next_refresh_utc": next_refresh,
+        "backoff_seconds": 0,
+        "source_policy": {"network": "DENIED", "robots": "NOT_APPLICABLE_LOCAL_SNAPSHOT",
+                          "license_unknown_quarantined": True, "provenance_required": True},
+        "stage_results": [
+            {"stage": stage, "status": (READY if stage != "EVALUATE" or
+                                          dataset["evaluation_readiness"]["status"] == READY
+                                          else BLOCKED)}
+            for stage in FEED_STAGES
+        ],
+        "training_triggered": False,
+    }
+    record["receipt_sha256"] = _sha(record)
+    path.parent.mkdir(parents=True, exist_ok=True)
+    with _LOCK:
+        with path.open("a", encoding="utf-8", newline="\n") as handle:
+            handle.write(json.dumps(record, sort_keys=True, ensure_ascii=False) + "\n")
+            handle.flush(); os.fsync(handle.fileno())
+    return {"ok": True, "status": DEGRADED, "receipt": record,
+            "note": "Local evidence checkpoint written; no network or training occurred."}, 201
+
+
+def anatomy_receipt(node_id: str, ns: str = "a11oy",
+                    repo_root: pathlib.Path | str | None = None,
+                    environ: Mapping[str, str] | None = None,
+                    feed_path: pathlib.Path | str | None = None) -> tuple[dict, int]:
+    inventory = build_inventory(ns, repo_root, environ)
+    item = next((d for d in inventory["decisions"] if d["brain_node_id"] == node_id), None)
+    if item is None:
+        return {"ok": False, "status": UNAVAILABLE, "reason": "NODE_NOT_FOUND",
+                "receipt_sha256": UNKNOWN}, 404
+    feed = feed_status(ns, repo_root, environ, feed_path)
+    loop_receipt = (feed["last_successful_receipt"]
+                    if feed["last_inventory_sha256"] == inventory["inventory_sha256"]
+                    else UNKNOWN)
+    payload = {
+        **item,
+        "inventory_sha256": inventory["inventory_sha256"],
+        "loop_checkpoint": feed["checkpoint"],
+        "loop_receipt_sha256": loop_receipt,
+        "receipt_state": "VERIFIED_CHAIN_REFERENCE" if loop_receipt != UNKNOWN else UNVERIFIED,
+        "model_receipt_sha256": UNKNOWN,
+        "evaluation_receipt_sha256": UNKNOWN,
+        "note": "GET returns existing deterministic anatomy and loop linkage; it mints no receipt.",
+    }
+    return {"ok": True, "label": inventory["label"], "receipt_anatomy": payload,
+            "receipt_sha256": loop_receipt}, 200
+
+
+def service_status(ns: str = "a11oy", repo_root: pathlib.Path | str | None = None,
+                   environ: Mapping[str, str] | None = None) -> dict[str, Any]:
+    dataset = build_dataset(ns, repo_root, environ)
+    inventory = build_inventory(ns, repo_root, environ)
+    feed = feed_status(ns, repo_root, environ)
+    readiness = (
+        dataset["dataset_readiness"]["status"],
+        dataset["model_readiness"]["status"],
+        dataset["evaluation_readiness"]["status"],
+    )
+    operational = all(state == READY for state in readiness)
+    return {
+        "ok": True, "schema_version": SERVICE_SCHEMA,
+        # The inventory can be measured while the train/eval/model pipeline is still
+        # unavailable.  Keep those truths separate so the estate rollup cannot turn
+        # a measured node count into an operational model claim.
+        "status": READY if operational else BLOCKED,
+        "label": "MEASURED" if operational else UNAVAILABLE,
+        "inventory_label": inventory["label"],
+        "inventory": inventory["inventory"],
+        "inventory_sha256": inventory["inventory_sha256"],
+        "dataset": {"status": dataset["dataset_readiness"]["status"],
+                    "reasons": dataset["dataset_readiness"]["reasons"],
+                    "row_count": len(dataset["rows"]),
+                    "dataset_sha256": dataset.get("dataset_sha256"),
+                    "split_counts": dataset["split_counts"],
+                    "example_type_counts": dataset["example_type_counts"]},
+        "evaluation": dataset["evaluation_readiness"],
+        "model": dataset["model_readiness"],
+        "feed": feed,
+        "training_triggered": False,
+    }
+
+
+def info() -> dict[str, Any]:
+    return {
+        "service": "a11oy.brain.evidence-reranker",
+        "schema_version": SERVICE_SCHEMA,
+        "readiness_dimensions": ["dataset", "evaluation", "model"],
+        "required_example_types": list(EXAMPLE_TYPES),
+        "split_rule": "sha256(source_type|source_entry_id|entity_id), 70/20/10",
+        "feed_stages": list(FEED_STAGES),
+        "network_access": False, "training_trigger": False,
+        "write_paths": ["loopback validated-row append", "loopback feed checkpoint"],
+        "bounds": {"local_rows": MAX_LOCAL_ROWS, "inventory_page": MAX_INVENTORY_PAGE,
+                   "dataset_page": MAX_DATASET_PAGE, "node_budget": FEED_NODE_BUDGET},
+        "honesty": "Missing canonical manifests or hashes => BLOCKED with zero rows.",
+    }
+
+
+def _loopback(host: Any) -> bool:
+    value = str(host or "").strip().lower()
+    if value in {"localhost", "testclient", "testserver"}: return True
+    try:
+        return ipaddress.ip_address(value).is_loopback
+    except ValueError:
+        return False
+
+
+def _local_request(request: Any) -> bool:
+    """Require both transport peer and Host/URL to be loopback.
+
+    Checking only ``request.client`` is not sufficient behind a same-host reverse
+    proxy: a public request can otherwise appear to originate from 127.0.0.1.
+    """
+    client_host = getattr(getattr(request, "client", None), "host", None)
+    url_host = getattr(getattr(request, "url", None), "hostname", None)
+    return _loopback(client_host) and _loopback(url_host)
+
+
+def register(app: Any, ns: str = "a11oy") -> list[str]:
+    """Register bounded API routes before the SPA catch-all."""
+    from fastapi.responses import JSONResponse
+    base = f"/api/{ns}/v1/brain/reranker"
+    paths: list[str] = []
+
+    @app.get(base + "/info")
+    def _info():
+        return JSONResponse(info())
+    paths.append(base + "/info")
+
+    @app.get(base + "/status")
+    def _status():
+        return JSONResponse(service_status(ns))
+    paths.append(base + "/status")
+
+    # The holographic/frontier registry matches a surface id by exact route
+    # segment.  This additive alias makes the ``brainreranker`` surface visible
+    # to the estate status rollup while the structured canonical API remains
+    # ``/brain/reranker/status``.
+    @app.get(f"/api/{ns}/v1/brainreranker/status")
+    def _surface_status():
+        return JSONResponse(service_status(ns))
+    paths.append(f"/api/{ns}/v1/brainreranker/status")
+
+    @app.get(base + "/inventory")
+    def _inventory(offset: int = 0, limit: int = 100, decision: str = ""):
+        result = build_inventory(ns)
+        selected = result["decisions"]
+        if decision:
+            selected = [d for d in selected if d["admission_decision"] == decision.upper()]
+        start = max(0, int(offset)); page = selected[start:start + max(1, min(MAX_INVENTORY_PAGE, int(limit)))]
+        return JSONResponse({k: v for k, v in result.items() if k != "decisions"} | {
+            "offset": start, "limit": len(page), "total": len(selected),
+            "next_offset": start + len(page) if start + len(page) < len(selected) else None,
+            "decisions": page,
+        })
+    paths.append(base + "/inventory")
+
+    @app.get(base + "/dataset")
+    def _dataset(split: str = "", offset: int = 0, limit: int = 100):
+        result = build_dataset(ns)
+        selected = result["rows"]
+        if split:
+            selected = [r for r in selected if r["split"] == split.lower()]
+        start = max(0, int(offset)); page = selected[start:start + max(1, min(MAX_DATASET_PAGE, int(limit)))]
+        return JSONResponse({k: v for k, v in result.items() if k != "rows"} | {
+            "offset": start, "limit": len(page), "total": len(selected),
+            "next_offset": start + len(page) if start + len(page) < len(selected) else None,
+            "rows": page,
+        })
+    paths.append(base + "/dataset")
+
+    @app.get(base + "/feed")
+    def _feed():
+        return JSONResponse(feed_status(ns))
+    paths.append(base + "/feed")
+
+    @app.get(f"/api/{ns}/v1/anatomy/brain-receipt/{{node_id:path}}")
+    def _anatomy(node_id: str):
+        body, status = anatomy_receipt(node_id, ns)
+        return JSONResponse(body, status_code=status)
+    paths.append(f"/api/{ns}/v1/anatomy/brain-receipt/{{node_id:path}}")
+
+    async def _append(request):
+        if not _local_request(request):
+            return JSONResponse({"ok": False, "status": BLOCKED,
+                                 "reasons": ["LOCAL_CLIENT_REQUIRED"]}, status_code=403)
+        try:
+            payload = await request.json()
+        except Exception:
+            payload = None
+        if not isinstance(payload, dict):
+            return JSONResponse({"ok": False, "status": BLOCKED,
+                                 "reasons": ["JSON_OBJECT_REQUIRED"]}, status_code=400)
+        body, status = append_validated_row(payload, ns)
+        return JSONResponse(body, status_code=status)
+
+    async def _refresh(request):
+        if not _local_request(request):
+            return JSONResponse({"ok": False, "status": BLOCKED,
+                                 "reason": "LOCAL_CLIENT_REQUIRED"}, status_code=403)
+        body, status = refresh_feed(ns)
+        return JSONResponse(body, status_code=status)
+
+    try:
+        import fastapi
+        _append.__annotations__["request"] = fastapi.Request
+        _refresh.__annotations__["request"] = fastapi.Request
+    except Exception:
+        pass
+    app.router.add_route(base + "/rows", _append, methods=["POST"])
+    app.router.add_route(base + "/feed/refresh", _refresh, methods=["POST"])
+    paths.extend([base + "/rows", base + "/feed/refresh"])
+    return paths

szl_brain_training_admission.py

@@ -0,0 +1,1221 @@
+#!/usr/bin/env python3
+# SPDX-License-Identifier: Apache-2.0
+"""Bounded, deterministic admission for Brain-derived train/eval rows.
+
+This module does not turn raw Brain inventory into training data.  It evaluates
+caller-supplied JSON/JSONL candidates and admits a row only when every required
+provenance, rights, freshness, contamination, deduplication, and split
+obligation is established by pinned, allowlisted Ed25519 evidence and a signed
+cross-run split ledger.  Missing evidence is a reason-coded quarantine
+decision; it is never guessed or filled in.
+
+The gate performs no network access, starts no training, and grants no proof or
+model-promotion credit.
+"""
+
+from __future__ import annotations
+
+import argparse
+import base64
+import binascii
+import collections
+import dataclasses
+import datetime as dt
+import hashlib
+import json
+import os
+import pathlib
+import re
+from typing import Any, Iterable, Mapping, Sequence
+from urllib.parse import urlsplit
+
+from cryptography.exceptions import InvalidSignature
+from cryptography.hazmat.primitives import serialization
+from cryptography.hazmat.primitives.asymmetric.ed25519 import Ed25519PublicKey
+
+
+CANDIDATE_SCHEMA = "szl.brain-training-candidate.v1"
+DECISION_SCHEMA = "szl.brain-training-admission-decision.v1"
+REPORT_SCHEMA = "szl.brain-training-admission-report.v1"
+SOURCE_EVIDENCE_SCHEMA = "szl.source-revision-evidence.v2"
+RIGHTS_EVIDENCE_SCHEMA = "szl.rights-evidence.v2"
+CONTAMINATION_EVIDENCE_SCHEMA = "szl.contamination-evidence.v2"
+SPLIT_LEDGER_SCHEMA = "szl.brain-training-split-ledger.v1"
+TRUST_STORE_SCHEMA = "szl.evidence-trust-store.v1"
+SIGNATURE_ALGORITHM = "Ed25519"
+
+MAX_INPUT_BYTES = 32 * 1024 * 1024
+MAX_ROWS = 20_000
+MAX_ROW_BYTES = 256 * 1024
+MAX_CONTENT_BYTES = 64 * 1024
+MAX_EVIDENCE_BYTES = 4 * 1024 * 1024
+MAX_REFERENCES = 64
+
+DEFAULT_RIGHTS_BASES = ("PROJECT_AUTHORED_SCHEMA_GENERATED",)
+DEFAULT_LICENSES = ("Apache-2.0",)
+SPLITS = frozenset({"TRAIN", "EVAL"})
+
+_SHA256_RE = re.compile(r"^[0-9a-f]{64}$")
+_REVISION_RE = re.compile(r"^(?:git:[0-9a-f]{40,64}|sha256:[0-9a-f]{64})$")
+_NODE_ID_RE = re.compile(r"^[A-Za-z0-9][A-Za-z0-9._:/@+\-]{2,255}$")
+_METHOD_RE = re.compile(r"^[A-Z0-9][A-Z0-9._:\-]{2,127}$")
+_REFERENCE_RE = re.compile(r"^[A-Za-z0-9][A-Za-z0-9._:/@+\-]{1,255}$")
+
+_ROW_FIELDS = frozenset(
+    {
+        "schema_version",
+        "node_id",
+        "content",
+        "content_sha256",
+        "source",
+        "rights",
+        "contamination",
+        "split",
+    }
+)
+_SOURCE_FIELDS = frozenset({"uri", "revision", "timestamp_utc", "evidence"})
+_RIGHTS_FIELDS = frozenset({"basis", "license", "evidence"})
+_CONTAMINATION_FIELDS = frozenset(
+    {"result", "method", "checked_against", "evidence"}
+)
+_SIGNED_ENVELOPE_FIELDS = frozenset(
+    {"schema_version", "issuer", "tool_identity", "issued_at_utc", "statement", "signature"}
+)
+_SIGNATURE_FIELDS = frozenset({"algorithm", "key_id", "value_base64"})
+_RUN_RECEIPT_FIELDS = frozenset(
+    {
+        "run_id",
+        "completed_at_utc",
+        "tool_identity",
+        "method",
+        "candidate_content_sha256",
+        "checked_against_sha256",
+        "result",
+    }
+)
+
+
+class AdmissionInputError(RuntimeError):
+    """A bounded file-level input obligation failed before row evaluation."""
+
+
+@dataclasses.dataclass(frozen=True)
+class TrustedEvidenceSigner:
+    """Pinned public-key identity allowed to issue admission evidence."""
+
+    key_id: str
+    issuer: str
+    tool_identity: str
+    public_key_path: str
+    public_key_sha256: str
+
+
+@dataclasses.dataclass(frozen=True)
+class AdmissionPolicy:
+    """Frozen policy inputs; ``as_of_utc`` is required for reproducibility."""
+
+    as_of_utc: str
+    evidence_root: pathlib.Path | str
+    max_age_days: int = 365
+    allowed_rights_bases: tuple[str, ...] = DEFAULT_RIGHTS_BASES
+    allowed_licenses: tuple[str, ...] = DEFAULT_LICENSES
+    protected_eval_content_sha256: frozenset[str] = frozenset()
+    trusted_evidence_signers: tuple[TrustedEvidenceSigner, ...] = ()
+    split_ledger_evidence: Mapping[str, str] | None = None
+
+    def __post_init__(self) -> None:
+        as_of = _parse_utc(self.as_of_utc)
+        if as_of is None:
+            raise AdmissionInputError("POLICY_AS_OF_UTC_INVALID")
+        if not isinstance(self.max_age_days, int) or not 0 <= self.max_age_days <= 3650:
+            raise AdmissionInputError("POLICY_MAX_AGE_DAYS_INVALID")
+        root = pathlib.Path(self.evidence_root).resolve()
+        if not root.is_dir():
+            raise AdmissionInputError("POLICY_EVIDENCE_ROOT_UNAVAILABLE")
+        bases = tuple(sorted(set(self.allowed_rights_bases)))
+        licenses = tuple(sorted(set(self.allowed_licenses)))
+        if not bases or not licenses or any(not value for value in (*bases, *licenses)):
+            raise AdmissionInputError("POLICY_RIGHTS_ALLOWLIST_INVALID")
+        protected = frozenset(self.protected_eval_content_sha256)
+        if any(not _is_sha256(value) for value in protected):
+            raise AdmissionInputError("POLICY_PROTECTED_EVAL_HASH_INVALID")
+        signers = tuple(self.trusted_evidence_signers)
+        if not signers:
+            # Empty trust is valid policy construction, but every signed evidence
+            # check will fail closed.  This keeps inspection-only use possible.
+            pass
+        if len({item.key_id for item in signers}) != len(signers):
+            raise AdmissionInputError("POLICY_SIGNER_KEY_ID_DUPLICATE")
+        for signer in signers:
+            if not all(
+                isinstance(value, str) and value.strip()
+                for value in (signer.key_id, signer.issuer, signer.tool_identity)
+            ):
+                raise AdmissionInputError("POLICY_SIGNER_IDENTITY_INVALID")
+            if not _is_sha256(signer.public_key_sha256):
+                raise AdmissionInputError("POLICY_SIGNER_PUBLIC_KEY_SHA256_INVALID")
+            key_path = _safe_evidence_path(root, signer.public_key_path)
+            if key_path is None or not key_path.is_file():
+                raise AdmissionInputError("POLICY_SIGNER_PUBLIC_KEY_UNAVAILABLE")
+            if sha256_file(key_path) != signer.public_key_sha256:
+                raise AdmissionInputError("POLICY_SIGNER_PUBLIC_KEY_HASH_MISMATCH")
+            try:
+                key = serialization.load_pem_public_key(key_path.read_bytes())
+            except (OSError, ValueError, TypeError) as exc:
+                raise AdmissionInputError("POLICY_SIGNER_PUBLIC_KEY_INVALID") from exc
+            if not isinstance(key, Ed25519PublicKey):
+                raise AdmissionInputError("POLICY_SIGNER_PUBLIC_KEY_NOT_ED25519")
+        ledger_descriptor = self.split_ledger_evidence
+        if ledger_descriptor is not None and (
+            not isinstance(ledger_descriptor, Mapping)
+            or set(ledger_descriptor) != {"path", "sha256"}
+        ):
+            raise AdmissionInputError("POLICY_SPLIT_LEDGER_DESCRIPTOR_INVALID")
+        object.__setattr__(self, "as_of_utc", _format_utc(as_of))
+        object.__setattr__(self, "evidence_root", root)
+        object.__setattr__(self, "allowed_rights_bases", bases)
+        object.__setattr__(self, "allowed_licenses", licenses)
+        object.__setattr__(self, "protected_eval_content_sha256", protected)
+        object.__setattr__(self, "trusted_evidence_signers", signers)
+
+
+def canonical_bytes(value: Any) -> bytes:
+    return json.dumps(
+        value, ensure_ascii=False, sort_keys=True, separators=(",", ":")
+    ).encode("utf-8")
+
+
+def sha256_bytes(value: bytes) -> str:
+    return hashlib.sha256(value).hexdigest()
+
+
+def sha256_file(path: pathlib.Path) -> str:
+    digest = hashlib.sha256()
+    with path.open("rb") as stream:
+        for chunk in iter(lambda: stream.read(1024 * 1024), b""):
+            digest.update(chunk)
+    return digest.hexdigest()
+
+
+def _receipted(value: Mapping[str, Any], field: str) -> dict[str, Any]:
+    result = dict(value)
+    result[field] = sha256_bytes(canonical_bytes(value))
+    return result
+
+
+def _is_sha256(value: Any) -> bool:
+    return isinstance(value, str) and _SHA256_RE.fullmatch(value) is not None
+
+
+def _parse_utc(value: Any) -> dt.datetime | None:
+    if not isinstance(value, str) or not value.strip():
+        return None
+    try:
+        parsed = dt.datetime.fromisoformat(value.replace("Z", "+00:00"))
+    except ValueError:
+        return None
+    if parsed.tzinfo is None or parsed.utcoffset() is None:
+        return None
+    return parsed.astimezone(dt.timezone.utc)
+
+
+def _format_utc(value: dt.datetime) -> str:
+    return value.astimezone(dt.timezone.utc).isoformat().replace("+00:00", "Z")
+
+
+def _unique_reasons(reasons: Iterable[str]) -> list[str]:
+    return sorted(set(reasons))
+
+
+def _safe_evidence_path(root: pathlib.Path, raw_path: Any) -> pathlib.Path | None:
+    if not isinstance(raw_path, str) or not raw_path or "\x00" in raw_path:
+        return None
+    relative = pathlib.Path(raw_path)
+    if relative.is_absolute():
+        return None
+    candidate = (root / relative).resolve()
+    try:
+        candidate.relative_to(root)
+    except ValueError:
+        return None
+    return candidate
+
+
+def _trusted_signer(
+    policy: AdmissionPolicy, key_id: Any
+) -> TrustedEvidenceSigner | None:
+    if not isinstance(key_id, str):
+        return None
+    return next(
+        (item for item in policy.trusted_evidence_signers if item.key_id == key_id),
+        None,
+    )
+
+
+def _signed_payload(envelope: Mapping[str, Any]) -> dict[str, Any]:
+    return {
+        "schema_version": envelope.get("schema_version"),
+        "issuer": envelope.get("issuer"),
+        "tool_identity": envelope.get("tool_identity"),
+        "issued_at_utc": envelope.get("issued_at_utc"),
+        "statement": envelope.get("statement"),
+    }
+
+
+def _verify_bound_evidence(
+    descriptor: Any,
+    policy: AdmissionPolicy,
+    prefix: str,
+    schema: str,
+    expected: Mapping[str, Any],
+    *,
+    exact_statement_fields: bool = True,
+) -> tuple[dict[str, Any], list[str], Mapping[str, Any] | None]:
+    observed: dict[str, Any] = {
+        "path": None,
+        "sha256": None,
+        "status": "UNVERIFIED",
+    }
+    reasons: list[str] = []
+    if not isinstance(descriptor, Mapping) or set(descriptor) != {"path", "sha256"}:
+        return observed, [f"{prefix}_EVIDENCE_DESCRIPTOR_INVALID"], None
+    raw_path = descriptor.get("path")
+    declared_sha = descriptor.get("sha256")
+    observed["path"] = raw_path if isinstance(raw_path, str) else None
+    observed["sha256"] = declared_sha if isinstance(declared_sha, str) else None
+    if not _is_sha256(declared_sha):
+        reasons.append(f"{prefix}_EVIDENCE_SHA256_INVALID")
+    path = _safe_evidence_path(pathlib.Path(policy.evidence_root), raw_path)
+    if path is None:
+        reasons.append(f"{prefix}_EVIDENCE_PATH_UNSAFE")
+        return observed, _unique_reasons(reasons), None
+    if not path.is_file():
+        reasons.append(f"{prefix}_EVIDENCE_FILE_MISSING")
+        return observed, _unique_reasons(reasons), None
+    size = path.stat().st_size
+    observed["bytes"] = size
+    if size > MAX_EVIDENCE_BYTES:
+        reasons.append(f"{prefix}_EVIDENCE_FILE_TOO_LARGE")
+        return observed, _unique_reasons(reasons), None
+    actual_sha = sha256_file(path)
+    observed["observed_sha256"] = actual_sha
+    if declared_sha != actual_sha:
+        reasons.append(f"{prefix}_EVIDENCE_HASH_MISMATCH")
+        return observed, _unique_reasons(reasons), None
+    try:
+        payload = json.loads(path.read_text(encoding="utf-8"))
+    except (OSError, UnicodeError, json.JSONDecodeError):
+        reasons.append(f"{prefix}_EVIDENCE_JSON_INVALID")
+        return observed, _unique_reasons(reasons), None
+    if not isinstance(payload, Mapping) or set(payload) != _SIGNED_ENVELOPE_FIELDS:
+        reasons.append(f"{prefix}_EVIDENCE_ENVELOPE_INVALID")
+        return observed, _unique_reasons(reasons), None
+    if payload.get("schema_version") != schema:
+        reasons.append(f"{prefix}_EVIDENCE_SCHEMA_MISMATCH")
+    statement = payload.get("statement")
+    if not isinstance(statement, Mapping):
+        reasons.append(f"{prefix}_EVIDENCE_STATEMENT_INVALID")
+        statement = None
+    else:
+        if exact_statement_fields and set(statement) != set(expected):
+            reasons.append(f"{prefix}_EVIDENCE_STATEMENT_FIELDS_INVALID")
+        for field, expected_value in expected.items():
+            if statement.get(field) != expected_value:
+                reasons.append(f"{prefix}_EVIDENCE_BINDING_MISMATCH:{field}")
+
+    issued_at = _parse_utc(payload.get("issued_at_utc"))
+    as_of = _parse_utc(policy.as_of_utc)
+    if issued_at is None:
+        reasons.append(f"{prefix}_EVIDENCE_ISSUED_AT_INVALID")
+    elif as_of is not None and issued_at > as_of:
+        reasons.append(f"{prefix}_EVIDENCE_ISSUED_IN_FUTURE")
+
+    signature = payload.get("signature")
+    if not isinstance(signature, Mapping) or set(signature) != _SIGNATURE_FIELDS:
+        reasons.append(f"{prefix}_EVIDENCE_SIGNATURE_DESCRIPTOR_INVALID")
+    else:
+        key_id = signature.get("key_id")
+        signer = _trusted_signer(policy, key_id)
+        if signature.get("algorithm") != SIGNATURE_ALGORITHM:
+            reasons.append(f"{prefix}_EVIDENCE_SIGNATURE_ALGORITHM_INVALID")
+        if signer is None:
+            reasons.append(f"{prefix}_EVIDENCE_SIGNER_NOT_ALLOWLISTED")
+        else:
+            if payload.get("issuer") != signer.issuer:
+                reasons.append(f"{prefix}_EVIDENCE_ISSUER_NOT_ALLOWLISTED")
+            if payload.get("tool_identity") != signer.tool_identity:
+                reasons.append(f"{prefix}_EVIDENCE_TOOL_NOT_ALLOWLISTED")
+            try:
+                signature_bytes = base64.b64decode(
+                    signature.get("value_base64"), validate=True
+                )
+            except (binascii.Error, TypeError, ValueError):
+                reasons.append(f"{prefix}_EVIDENCE_SIGNATURE_ENCODING_INVALID")
+            else:
+                key_path = _safe_evidence_path(
+                    pathlib.Path(policy.evidence_root), signer.public_key_path
+                )
+                try:
+                    if key_path is None:
+                        raise ValueError("trusted public key path is unsafe")
+                    public_key = serialization.load_pem_public_key(key_path.read_bytes())
+                    if not isinstance(public_key, Ed25519PublicKey):
+                        raise TypeError("trusted public key is not Ed25519")
+                    public_key.verify(signature_bytes, canonical_bytes(_signed_payload(payload)))
+                except InvalidSignature:
+                    reasons.append(f"{prefix}_EVIDENCE_SIGNATURE_INVALID")
+                except (OSError, TypeError, ValueError):
+                    reasons.append(f"{prefix}_EVIDENCE_PUBLIC_KEY_VERIFICATION_FAILED")
+    if not reasons:
+        observed.update(
+            {
+                "status": "VERIFIED_SIGNED_CONTENT_BINDING",
+                "issuer": payload.get("issuer"),
+                "tool_identity": payload.get("tool_identity"),
+                "key_id": signature.get("key_id") if isinstance(signature, Mapping) else None,
+                "statement_sha256": sha256_bytes(canonical_bytes(statement)),
+            }
+        )
+    return observed, _unique_reasons(reasons), statement
+
+
+def _checked_against_sha256(references: Sequence[str]) -> str:
+    return sha256_bytes(canonical_bytes(list(references)))
+
+
+def _protected_eval_set_sha256(values: Iterable[str]) -> str:
+    return sha256_bytes(canonical_bytes(sorted(set(values))))
+
+
+def _verify_contamination_run_receipt(
+    statement: Mapping[str, Any] | None,
+    *,
+    expected_tool_identity: str | None,
+    method: Any,
+    content_sha256: Any,
+    checked_against_sha256: str,
+    result: Any,
+) -> list[str]:
+    prefix = "CONTAMINATION"
+    if not isinstance(statement, Mapping):
+        return [f"{prefix}_RUN_RECEIPT_MISSING"]
+    required = {
+        "result",
+        "method",
+        "candidate_content_sha256",
+        "checked_against_sha256",
+        "run_receipt",
+        "run_receipt_sha256",
+    }
+    reasons: list[str] = []
+    if set(statement) != required:
+        reasons.append(f"{prefix}_EVIDENCE_STATEMENT_FIELDS_INVALID")
+    receipt = statement.get("run_receipt")
+    if not isinstance(receipt, Mapping) or set(receipt) != _RUN_RECEIPT_FIELDS:
+        reasons.append(f"{prefix}_RUN_RECEIPT_INVALID")
+        return _unique_reasons(reasons)
+    receipt_sha = statement.get("run_receipt_sha256")
+    if not _is_sha256(receipt_sha) or receipt_sha != sha256_bytes(canonical_bytes(receipt)):
+        reasons.append(f"{prefix}_RUN_RECEIPT_HASH_MISMATCH")
+    expected_receipt = {
+        "tool_identity": expected_tool_identity,
+        "method": method,
+        "candidate_content_sha256": content_sha256,
+        "checked_against_sha256": checked_against_sha256,
+        "result": result,
+    }
+    for field, expected_value in expected_receipt.items():
+        if receipt.get(field) != expected_value:
+            reasons.append(f"{prefix}_RUN_RECEIPT_BINDING_MISMATCH:{field}")
+    if not isinstance(receipt.get("run_id"), str) or not receipt.get("run_id"):
+        reasons.append(f"{prefix}_RUN_RECEIPT_RUN_ID_INVALID")
+    if _parse_utc(receipt.get("completed_at_utc")) is None:
+        reasons.append(f"{prefix}_RUN_RECEIPT_COMPLETED_AT_INVALID")
+    return _unique_reasons(reasons)
+
+
+def _load_split_ledger(
+    policy: AdmissionPolicy,
+) -> tuple[dict[str, str], dict[str, Any], list[str]]:
+    descriptor = policy.split_ledger_evidence
+    if descriptor is None:
+        return {}, {"status": "MISSING"}, ["SPLIT_LEDGER_REQUIRED"]
+    observed, reasons, statement = _verify_bound_evidence(
+        descriptor,
+        policy,
+        "SPLIT_LEDGER",
+        SPLIT_LEDGER_SCHEMA,
+        {},
+        exact_statement_fields=False,
+    )
+    if not isinstance(statement, Mapping):
+        return {}, observed, _unique_reasons([*reasons, "SPLIT_LEDGER_STATEMENT_INVALID"])
+    expected_fields = {
+        "ledger_id",
+        "as_of_utc",
+        "previous_ledger_sha256",
+        "protected_eval_set_sha256",
+        "entries",
+    }
+    if set(statement) != expected_fields:
+        reasons.append("SPLIT_LEDGER_STATEMENT_FIELDS_INVALID")
+    if not isinstance(statement.get("ledger_id"), str) or not statement.get("ledger_id"):
+        reasons.append("SPLIT_LEDGER_ID_INVALID")
+    ledger_as_of = _parse_utc(statement.get("as_of_utc"))
+    policy_as_of = _parse_utc(policy.as_of_utc)
+    if ledger_as_of is None:
+        reasons.append("SPLIT_LEDGER_AS_OF_INVALID")
+    elif policy_as_of is not None and ledger_as_of > policy_as_of:
+        reasons.append("SPLIT_LEDGER_AS_OF_IN_FUTURE")
+    previous = statement.get("previous_ledger_sha256")
+    if previous is not None and not _is_sha256(previous):
+        reasons.append("SPLIT_LEDGER_PREVIOUS_HASH_INVALID")
+    if statement.get("protected_eval_set_sha256") != _protected_eval_set_sha256(
+        policy.protected_eval_content_sha256
+    ):
+        reasons.append("SPLIT_LEDGER_PROTECTED_EVAL_BINDING_MISMATCH")
+    raw_entries = statement.get("entries")
+    ledger: dict[str, str] = {}
+    normalized: list[dict[str, str]] = []
+    if not isinstance(raw_entries, list):
+        reasons.append("SPLIT_LEDGER_ENTRIES_INVALID")
+    else:
+        for entry in raw_entries:
+            if (
+                not isinstance(entry, Mapping)
+                or set(entry) != {"content_sha256", "split"}
+                or not _is_sha256(entry.get("content_sha256"))
+                or entry.get("split") not in SPLITS
+            ):
+                reasons.append("SPLIT_LEDGER_ENTRY_INVALID")
+                continue
+            content_sha = str(entry["content_sha256"])
+            split = str(entry["split"])
+            if content_sha in ledger:
+                reasons.append(
+                    "SPLIT_LEDGER_CONFLICTING_ENTRY"
+                    if ledger[content_sha] != split
+                    else "SPLIT_LEDGER_DUPLICATE_ENTRY"
+                )
+            else:
+                ledger[content_sha] = split
+                normalized.append({"content_sha256": content_sha, "split": split})
+        expected_order = sorted(
+            normalized, key=lambda item: (item["content_sha256"], item["split"])
+        )
+        if normalized != expected_order:
+            reasons.append("SPLIT_LEDGER_NOT_DETERMINISTIC_ORDER")
+    reasons = _unique_reasons(reasons)
+    if reasons:
+        observed["status"] = "UNVERIFIED"
+        return {}, observed, reasons
+    observed.update(
+        {
+            "status": "VERIFIED_SIGNED_FROZEN_LEDGER",
+            "ledger_id": statement.get("ledger_id"),
+            "as_of_utc": statement.get("as_of_utc"),
+            "entry_count": len(ledger),
+        }
+    )
+    return ledger, observed, []
+
+
+def _uri_is_explicit(value: Any) -> bool:
+    if not isinstance(value, str) or len(value) > 2048:
+        return False
+    parsed = urlsplit(value)
+    return bool(parsed.scheme and (parsed.netloc or parsed.path) and not parsed.username)
+
+
+def _validate_row(raw: Any, index: int, policy: AdmissionPolicy) -> dict[str, Any]:
+    reasons: list[str] = []
+    candidate_sha = sha256_bytes(canonical_bytes(raw))
+    if not isinstance(raw, Mapping):
+        return {
+            "schema_version": DECISION_SCHEMA,
+            "input_index": index,
+            "candidate_row_sha256": candidate_sha,
+            "node_id": None,
+            "content_sha256": None,
+            "split": None,
+            "dedup_group": None,
+            "source": {"status": "UNVERIFIED"},
+            "rights": {"status": "UNVERIFIED"},
+            "freshness": {"state": "UNKNOWN"},
+            "contamination": {"observed_result": "NOT_ESTABLISHED"},
+            "reason_codes": ["ROW_NOT_OBJECT"],
+        }
+
+    row_bytes = len(canonical_bytes(raw))
+    if row_bytes > MAX_ROW_BYTES:
+        reasons.append("ROW_TOO_LARGE")
+    missing = sorted(_ROW_FIELDS - set(raw))
+    extra = sorted(set(raw) - _ROW_FIELDS)
+    if missing:
+        reasons.append("ROW_REQUIRED_FIELDS_MISSING")
+    if extra:
+        reasons.append("ROW_UNRECOGNIZED_FIELDS")
+    if raw.get("schema_version") != CANDIDATE_SCHEMA:
+        reasons.append("ROW_SCHEMA_MISMATCH")
+
+    node_id = raw.get("node_id")
+    if not isinstance(node_id, str) or _NODE_ID_RE.fullmatch(node_id) is None:
+        reasons.append("NODE_ID_INVALID")
+        node_id = node_id if isinstance(node_id, str) else None
+
+    content = raw.get("content")
+    if not isinstance(content, str) or not content:
+        reasons.append("CONTENT_MISSING")
+        content_bytes = b""
+    else:
+        content_bytes = content.encode("utf-8")
+        if len(content_bytes) > MAX_CONTENT_BYTES:
+            reasons.append("CONTENT_TOO_LARGE")
+    declared_content_sha = raw.get("content_sha256")
+    if not _is_sha256(declared_content_sha):
+        reasons.append("CONTENT_SHA256_INVALID")
+        content_sha = declared_content_sha if isinstance(declared_content_sha, str) else None
+    else:
+        content_sha = declared_content_sha
+        if not isinstance(content, str) or sha256_bytes(content_bytes) != content_sha:
+            reasons.append("CONTENT_HASH_MISMATCH")
+
+    split = raw.get("split")
+    if split not in SPLITS:
+        reasons.append("SPLIT_INVALID")
+        split = split if isinstance(split, str) else None
+
+    source_raw = raw.get("source")
+    source_result: dict[str, Any] = {"status": "UNVERIFIED"}
+    freshness: dict[str, Any] = {
+        "source_timestamp_utc": None,
+        "as_of_utc": policy.as_of_utc,
+        "max_age_days": policy.max_age_days,
+        "age_seconds": None,
+        "state": "UNKNOWN",
+    }
+    if not isinstance(source_raw, Mapping):
+        reasons.append("SOURCE_INVALID")
+    else:
+        if set(source_raw) != _SOURCE_FIELDS:
+            reasons.append("SOURCE_FIELDS_INVALID")
+        uri = source_raw.get("uri")
+        revision = source_raw.get("revision")
+        timestamp = source_raw.get("timestamp_utc")
+        if not _uri_is_explicit(uri):
+            reasons.append("SOURCE_URI_INVALID")
+        if not isinstance(revision, str) or _REVISION_RE.fullmatch(revision) is None:
+            reasons.append("SOURCE_IMMUTABLE_REVISION_REQUIRED")
+        timestamp_value = _parse_utc(timestamp)
+        if timestamp_value is None:
+            reasons.append("SOURCE_TIMESTAMP_INVALID")
+        else:
+            as_of_value = _parse_utc(policy.as_of_utc)
+            assert as_of_value is not None
+            age_seconds = int((as_of_value - timestamp_value).total_seconds())
+            freshness.update(
+                {
+                    "source_timestamp_utc": _format_utc(timestamp_value),
+                    "age_seconds": age_seconds,
+                }
+            )
+            if age_seconds < 0:
+                freshness["state"] = "FUTURE"
+                reasons.append("SOURCE_TIMESTAMP_IN_FUTURE")
+            elif age_seconds > policy.max_age_days * 86_400:
+                freshness["state"] = "STALE"
+                reasons.append("SOURCE_STALE")
+            else:
+                freshness["state"] = "FRESH"
+        source_evidence, source_reasons, _ = _verify_bound_evidence(
+            source_raw.get("evidence"),
+            policy,
+            "SOURCE",
+            SOURCE_EVIDENCE_SCHEMA,
+            {
+                "candidate_content_sha256": declared_content_sha,
+                "source_uri": uri,
+                "source_revision": revision,
+            },
+        )
+        reasons.extend(source_reasons)
+        source_shape_ok = (
+            _uri_is_explicit(uri)
+            and isinstance(revision, str)
+            and _REVISION_RE.fullmatch(revision) is not None
+        )
+        source_result = {
+            "uri": uri if isinstance(uri, str) else None,
+            "revision": revision if isinstance(revision, str) else None,
+            "revision_state": (
+                "PINNED_IDENTIFIER_WITH_SIGNED_EVIDENCE"
+                if not source_reasons
+                and source_shape_ok
+                else "UNVERIFIED"
+            ),
+            "evidence": source_evidence,
+            "status": (
+                "VERIFIED_SIGNED_BINDING"
+                if not source_reasons and source_shape_ok
+                else "UNVERIFIED"
+            ),
+        }
+
+    rights_raw = raw.get("rights")
+    rights_result: dict[str, Any] = {"status": "UNVERIFIED"}
+    if not isinstance(rights_raw, Mapping):
+        reasons.append("RIGHTS_INVALID")
+    else:
+        if set(rights_raw) != _RIGHTS_FIELDS:
+            reasons.append("RIGHTS_FIELDS_INVALID")
+        basis = rights_raw.get("basis")
+        license_id = rights_raw.get("license")
+        if basis not in policy.allowed_rights_bases:
+            reasons.append("RIGHTS_BASIS_NOT_ALLOWED")
+        if license_id not in policy.allowed_licenses:
+            reasons.append("LICENSE_NOT_ALLOWED")
+        revision = source_raw.get("revision") if isinstance(source_raw, Mapping) else None
+        source_uri = source_raw.get("uri") if isinstance(source_raw, Mapping) else None
+        rights_evidence, rights_reasons, _ = _verify_bound_evidence(
+            rights_raw.get("evidence"),
+            policy,
+            "RIGHTS",
+            RIGHTS_EVIDENCE_SCHEMA,
+            {
+                "candidate_content_sha256": declared_content_sha,
+                "source_uri": source_uri,
+                "source_revision": revision,
+                "basis": basis,
+                "license": license_id,
+            },
+        )
+        reasons.extend(rights_reasons)
+        rights_result = {
+            "basis": basis if isinstance(basis, str) else None,
+            "license": license_id if isinstance(license_id, str) else None,
+            "evidence": rights_evidence,
+            "status": (
+                "VERIFIED_SIGNED_CONTENT_RIGHTS_BINDING"
+                if not rights_reasons
+                and basis in policy.allowed_rights_bases
+                and license_id in policy.allowed_licenses
+                else "UNVERIFIED"
+            ),
+        }
+
+    contamination_raw = raw.get("contamination")
+    contamination_result: dict[str, Any] = {
+        "declared_result": None,
+        "observed_result": "NOT_ESTABLISHED",
+        "method": None,
+        "checked_against": [],
+        "evidence": {"status": "UNVERIFIED"},
+    }
+    if not isinstance(contamination_raw, Mapping):
+        reasons.append("CONTAMINATION_INVALID")
+    else:
+        if set(contamination_raw) != _CONTAMINATION_FIELDS:
+            reasons.append("CONTAMINATION_FIELDS_INVALID")
+        declared_result = contamination_raw.get("result")
+        method = contamination_raw.get("method")
+        references = contamination_raw.get("checked_against")
+        if declared_result != "CLEAR":
+            reasons.append(
+                "CONTAMINATION_DETECTED"
+                if declared_result == "DETECTED"
+                else "CONTAMINATION_NOT_CLEARED"
+            )
+        if not isinstance(method, str) or _METHOD_RE.fullmatch(method) is None:
+            reasons.append("CONTAMINATION_METHOD_INVALID")
+        references_valid = (
+            isinstance(references, list)
+            and 0 < len(references) <= MAX_REFERENCES
+            and len(references) == len(set(references))
+            and all(
+                isinstance(item, str) and _REFERENCE_RE.fullmatch(item) is not None
+                for item in references
+            )
+        )
+        if not references_valid:
+            reasons.append("CONTAMINATION_REFERENCE_SET_INVALID")
+        checked_against = list(references) if references_valid else []
+        reference_digest = _checked_against_sha256(checked_against)
+        contamination_evidence, contamination_reasons, contamination_statement = _verify_bound_evidence(
+            contamination_raw.get("evidence"),
+            policy,
+            "CONTAMINATION",
+            CONTAMINATION_EVIDENCE_SCHEMA,
+            {
+                "result": declared_result,
+                "method": method,
+                "candidate_content_sha256": declared_content_sha,
+                "checked_against_sha256": reference_digest,
+            },
+            exact_statement_fields=False,
+        )
+        contamination_reasons.extend(
+            _verify_contamination_run_receipt(
+                contamination_statement,
+                expected_tool_identity=(
+                    contamination_evidence.get("tool_identity")
+                    if isinstance(contamination_evidence, Mapping)
+                    else None
+                ),
+                method=method,
+                content_sha256=declared_content_sha,
+                checked_against_sha256=reference_digest,
+                result=declared_result,
+            )
+        )
+        contamination_reasons = _unique_reasons(contamination_reasons)
+        if contamination_reasons:
+            contamination_evidence["status"] = "UNVERIFIED"
+        reasons.extend(contamination_reasons)
+        contamination_result = {
+            "declared_result": declared_result if isinstance(declared_result, str) else None,
+            "observed_result": (
+                "CLEAR_WITH_SIGNED_RUN_RECEIPT"
+                if declared_result == "CLEAR"
+                and not contamination_reasons
+                and isinstance(method, str)
+                and _METHOD_RE.fullmatch(method) is not None
+                and references_valid
+                else "NOT_ESTABLISHED"
+            ),
+            "method": method if isinstance(method, str) else None,
+            "checked_against": checked_against,
+            "evidence": contamination_evidence,
+        }
+
+    if (
+        split == "TRAIN"
+        and _is_sha256(content_sha)
+        and content_sha in policy.protected_eval_content_sha256
+    ):
+        reasons.append("PROTECTED_EVAL_CONTENT_IN_TRAIN")
+        contamination_result["observed_result"] = "PROTECTED_EVAL_MATCH"
+    elif (
+        split == "EVAL"
+        and _is_sha256(content_sha)
+        and content_sha in policy.protected_eval_content_sha256
+    ):
+        contamination_result["observed_result"] = "PROTECTED_EVAL_MEMBER"
+
+    return {
+        "schema_version": DECISION_SCHEMA,
+        "input_index": index,
+        "candidate_row_sha256": candidate_sha,
+        "node_id": node_id,
+        "content": content if isinstance(content, str) else None,
+        "content_sha256": content_sha,
+        "split": split,
+        "dedup_group": f"sha256:{content_sha}" if _is_sha256(content_sha) else None,
+        "canonical_node_id": node_id if isinstance(node_id, str) else None,
+        "source": source_result,
+        "rights": rights_result,
+        "freshness": freshness,
+        "contamination": contamination_result,
+        "reason_codes": _unique_reasons(reasons),
+    }
+
+
+def _append_reason(record: dict[str, Any], reason: str) -> None:
+    record["reason_codes"] = _unique_reasons([*record["reason_codes"], reason])
+
+
+def _finalize_record(record: Mapping[str, Any]) -> dict[str, Any]:
+    body = dict(record)
+    reasons = list(body.pop("reason_codes", []))
+    admitted = not reasons
+    split = body.get("split")
+    body.update(
+        {
+            "canonical_status": "CANONICAL" if admitted else "QUARANTINED",
+            "admission_decision": (
+                f"ADMIT_{split}" if admitted and split in SPLITS else "QUARANTINE"
+            ),
+            "training_eligible": admitted and split == "TRAIN",
+            "evaluation_eligible": admitted and split == "EVAL",
+            "reason_codes": reasons,
+        }
+    )
+    if not admitted:
+        body.pop("content", None)
+        body["content_included"] = False
+    else:
+        body["content_included"] = True
+    return _receipted(body, "decision_receipt_sha256")
+
+
+def admit_rows(rows: Sequence[Any], policy: AdmissionPolicy) -> dict[str, Any]:
+    """Evaluate a bounded in-memory batch and return a receipted machine report."""
+
+    if len(rows) > MAX_ROWS:
+        raise AdmissionInputError("INPUT_ROW_LIMIT_EXCEEDED")
+    drafts = [_validate_row(raw, index, policy) for index, raw in enumerate(rows)]
+    prior_split_ledger, split_ledger_observed, split_ledger_reasons = _load_split_ledger(
+        policy
+    )
+
+    for record in drafts:
+        split = record.get("split")
+        content_sha = record.get("content_sha256")
+        if split == "TRAIN":
+            if not policy.protected_eval_content_sha256:
+                _append_reason(record, "FROZEN_EVAL_HASHES_REQUIRED_FOR_TRAIN")
+            for reason in split_ledger_reasons:
+                _append_reason(record, reason)
+        if not split_ledger_reasons and _is_sha256(content_sha):
+            prior_split = prior_split_ledger.get(str(content_sha))
+            if prior_split is not None:
+                _append_reason(
+                    record,
+                    "CROSS_RUN_SPLIT_CONFLICT"
+                    if prior_split != split
+                    else "CROSS_RUN_CONTENT_REUSE",
+                )
+                record["contamination"]["observed_result"] = (
+                    "CROSS_RUN_SPLIT_MATCH"
+                    if prior_split != split
+                    else "PRIOR_RUN_CONTENT_MATCH"
+                )
+
+    by_node: dict[str, list[dict[str, Any]]] = collections.defaultdict(list)
+    by_content: dict[str, list[dict[str, Any]]] = collections.defaultdict(list)
+    for record in drafts:
+        if isinstance(record.get("node_id"), str):
+            by_node[record["node_id"]].append(record)
+        if _is_sha256(record.get("content_sha256")):
+            by_content[record["content_sha256"]].append(record)
+
+    for group in by_node.values():
+        if len(group) > 1:
+            for record in group:
+                _append_reason(record, "DUPLICATE_NODE_ID")
+
+    for content_sha, group in by_content.items():
+        if len(group) < 2:
+            continue
+        splits = {record.get("split") for record in group if record.get("split") in SPLITS}
+        canonical = min(
+            group,
+            key=lambda record: (
+                str(record.get("node_id") or "~"),
+                str(record.get("candidate_row_sha256") or "~"),
+                int(record.get("input_index") or 0),
+            ),
+        )
+        canonical_node_id = canonical.get("node_id")
+        for record in group:
+            record["canonical_node_id"] = canonical_node_id
+        if len(splits) > 1:
+            for record in group:
+                _append_reason(record, "DEDUP_GROUP_SPLIT_CONFLICT")
+                record["contamination"]["observed_result"] = "CROSS_SPLIT_CONTENT_MATCH"
+        else:
+            for record in group:
+                if record is not canonical:
+                    _append_reason(record, "DUPLICATE_CONTENT")
+
+    decisions = [_finalize_record(record) for record in drafts]
+    reason_counts: collections.Counter[str] = collections.Counter()
+    for decision in decisions:
+        reason_counts.update(decision["reason_codes"])
+    train_count = sum(item["admission_decision"] == "ADMIT_TRAIN" for item in decisions)
+    eval_count = sum(item["admission_decision"] == "ADMIT_EVAL" for item in decisions)
+    quarantine_count = sum(item["admission_decision"] == "QUARANTINE" for item in decisions)
+    if not decisions:
+        state = "EMPTY_INPUT"
+    elif quarantine_count == len(decisions):
+        state = "ALL_QUARANTINED"
+    elif quarantine_count:
+        state = "COMPLETE_WITH_QUARANTINE"
+    else:
+        state = "ADMISSION_COMPLETE"
+    if split_ledger_reasons:
+        next_split_ledger: dict[str, Any] = {
+            "state": "BLOCKED_INVALID_OR_MISSING_PRIOR_LEDGER",
+            "reason_codes": split_ledger_reasons,
+        }
+    else:
+        next_entries = dict(prior_split_ledger)
+        for decision in decisions:
+            if decision.get("admission_decision") in {"ADMIT_TRAIN", "ADMIT_EVAL"}:
+                next_entries[str(decision["content_sha256"])] = str(decision["split"])
+        next_split_ledger = {
+            "state": "UNSIGNED_CANDIDATE_SIGNATURE_REQUIRED_BEFORE_REUSE",
+            "schema_version": SPLIT_LEDGER_SCHEMA,
+            "previous_ledger_evidence_sha256": (
+                policy.split_ledger_evidence.get("sha256")
+                if isinstance(policy.split_ledger_evidence, Mapping)
+                else None
+            ),
+            "protected_eval_set_sha256": _protected_eval_set_sha256(
+                policy.protected_eval_content_sha256
+            ),
+            "entries": [
+                {"content_sha256": content_sha, "split": split}
+                for content_sha, split in sorted(next_entries.items())
+            ],
+        }
+        next_split_ledger["entries_sha256"] = sha256_bytes(
+            canonical_bytes(next_split_ledger["entries"])
+        )
+    body = {
+        "schema_version": REPORT_SCHEMA,
+        "state": state,
+        "policy": {
+            "as_of_utc": policy.as_of_utc,
+            "max_age_days": policy.max_age_days,
+            "allowed_rights_bases": list(policy.allowed_rights_bases),
+            "allowed_licenses": list(policy.allowed_licenses),
+            "protected_eval_hash_count": len(policy.protected_eval_content_sha256),
+            "trusted_evidence_signer_count": len(policy.trusted_evidence_signers),
+            "bounds": {
+                "max_input_bytes": MAX_INPUT_BYTES,
+                "max_rows": MAX_ROWS,
+                "max_row_bytes": MAX_ROW_BYTES,
+                "max_content_bytes": MAX_CONTENT_BYTES,
+                "max_evidence_bytes": MAX_EVIDENCE_BYTES,
+            },
+        },
+        "summary": {
+            "observed_rows": len(decisions),
+            "admitted_train_rows": train_count,
+            "admitted_eval_rows": eval_count,
+            "quarantined_rows": quarantine_count,
+            "dedup_group_count": len(by_content),
+            "reason_counts": dict(sorted(reason_counts.items())),
+        },
+        "training_input_state": (
+            "ADMITTED_ROWS_PRESENT_NOT_TRAINING_AUTHORIZATION"
+            if train_count
+            else "BLOCKED_ZERO_ADMITTED_TRAIN_ROWS"
+        ),
+        "split_ledger": {
+            "observed": split_ledger_observed,
+            "reason_codes": split_ledger_reasons,
+            "next_unsigned_candidate": next_split_ledger,
+        },
+        "claims_boundary": {
+            "training_triggered": False,
+            "network_used": False,
+            "proof_credit": 0,
+            "model_trust_delta": 0,
+            "model_promotion_allowed": False,
+            "provenance_inferred": False,
+        },
+        "decisions": decisions,
+    }
+    return _receipted(body, "report_receipt_sha256")
+
+
+def load_candidate_rows(path: pathlib.Path | str) -> list[Any]:
+    """Read bounded JSONL or JSON (array or ``{"rows": [...]}``) candidates."""
+
+    source = pathlib.Path(path)
+    if not source.is_file():
+        raise AdmissionInputError("INPUT_FILE_MISSING")
+    if source.stat().st_size > MAX_INPUT_BYTES:
+        raise AdmissionInputError("INPUT_FILE_TOO_LARGE")
+    if source.suffix.lower() == ".jsonl":
+        rows: list[Any] = []
+        try:
+            with source.open("r", encoding="utf-8") as stream:
+                for line_number, line in enumerate(stream, start=1):
+                    if not line.strip():
+                        continue
+                    if len(line.encode("utf-8")) > MAX_ROW_BYTES:
+                        raise AdmissionInputError(f"INPUT_JSONL_ROW_TOO_LARGE:{line_number}")
+                    try:
+                        rows.append(json.loads(line))
+                    except json.JSONDecodeError as exc:
+                        raise AdmissionInputError(
+                            f"INPUT_JSONL_INVALID:{line_number}"
+                        ) from exc
+                    if len(rows) > MAX_ROWS:
+                        raise AdmissionInputError("INPUT_ROW_LIMIT_EXCEEDED")
+        except (OSError, UnicodeError) as exc:
+            raise AdmissionInputError("INPUT_JSONL_UNREADABLE") from exc
+        return rows
+    try:
+        payload = json.loads(source.read_text(encoding="utf-8"))
+    except (OSError, UnicodeError, json.JSONDecodeError) as exc:
+        raise AdmissionInputError("INPUT_JSON_INVALID") from exc
+    rows = payload.get("rows") if isinstance(payload, Mapping) else payload
+    if not isinstance(rows, list):
+        raise AdmissionInputError("INPUT_JSON_ROWS_ARRAY_REQUIRED")
+    if len(rows) > MAX_ROWS:
+        raise AdmissionInputError("INPUT_ROW_LIMIT_EXCEEDED")
+    return rows
+
+
+def _jsonl_bytes(rows: Iterable[Mapping[str, Any]]) -> bytes:
+    return b"".join(canonical_bytes(row) + b"\n" for row in rows)
+
+
+def _atomic_write(path: pathlib.Path, content: bytes) -> None:
+    path.parent.mkdir(parents=True, exist_ok=True)
+    temporary = path.with_name(f".{path.name}.{os.getpid()}.tmp")
+    temporary.write_bytes(content)
+    temporary.replace(path)
+
+
+def write_artifacts(report: Mapping[str, Any], output_dir: pathlib.Path | str) -> dict[str, Any]:
+    """Write deterministic admitted/quarantine ledgers plus a receipted report."""
+
+    output = pathlib.Path(output_dir)
+    decisions = list(report.get("decisions") or [])
+    ledgers = {
+        "admitted_train": (
+            "admitted-train.jsonl",
+            [row for row in decisions if row.get("admission_decision") == "ADMIT_TRAIN"],
+        ),
+        "admitted_eval": (
+            "admitted-eval.jsonl",
+            [row for row in decisions if row.get("admission_decision") == "ADMIT_EVAL"],
+        ),
+        "quarantine": (
+            "quarantine.jsonl",
+            [row for row in decisions if row.get("admission_decision") == "QUARANTINE"],
+        ),
+    }
+    artifacts: dict[str, Any] = {}
+    encoded: dict[str, bytes] = {}
+    for key, (name, rows) in ledgers.items():
+        content = _jsonl_bytes(rows)
+        encoded[name] = content
+        artifacts[key] = {
+            "path": name,
+            "rows": len(rows),
+            "bytes": len(content),
+            "sha256": sha256_bytes(content),
+        }
+    body = dict(report)
+    body.pop("report_receipt_sha256", None)
+    body["artifacts"] = artifacts
+    final_report = _receipted(body, "report_receipt_sha256")
+    encoded["admission-report.json"] = (
+        json.dumps(final_report, ensure_ascii=False, sort_keys=True, indent=2) + "\n"
+    ).encode("utf-8")
+    for name, content in encoded.items():
+        _atomic_write(output / name, content)
+    return final_report
+
+
+def admit_file(
+    input_path: pathlib.Path | str,
+    output_dir: pathlib.Path | str,
+    policy: AdmissionPolicy,
+) -> dict[str, Any]:
+    return write_artifacts(admit_rows(load_candidate_rows(input_path), policy), output_dir)
+
+
+def _load_protected_hashes(path: str | None) -> frozenset[str]:
+    if path is None:
+        return frozenset()
+    try:
+        value = json.loads(pathlib.Path(path).read_text(encoding="utf-8"))
+    except (OSError, UnicodeError, json.JSONDecodeError) as exc:
+        raise AdmissionInputError("PROTECTED_EVAL_HASH_FILE_INVALID") from exc
+    if isinstance(value, Mapping):
+        value = value.get("content_sha256")
+    if not isinstance(value, list) or any(not _is_sha256(item) for item in value):
+        raise AdmissionInputError("PROTECTED_EVAL_HASH_LIST_INVALID")
+    return frozenset(value)
+
+
+def _load_trusted_signers(path: str | None) -> tuple[TrustedEvidenceSigner, ...]:
+    if path is None:
+        return ()
+    try:
+        value = json.loads(pathlib.Path(path).read_text(encoding="utf-8"))
+    except (OSError, UnicodeError, json.JSONDecodeError) as exc:
+        raise AdmissionInputError("TRUST_STORE_FILE_INVALID") from exc
+    if (
+        not isinstance(value, Mapping)
+        or set(value) != {"schema_version", "signers"}
+        or value.get("schema_version") != TRUST_STORE_SCHEMA
+        or not isinstance(value.get("signers"), list)
+    ):
+        raise AdmissionInputError("TRUST_STORE_SCHEMA_INVALID")
+    signers: list[TrustedEvidenceSigner] = []
+    required = {
+        "key_id",
+        "issuer",
+        "tool_identity",
+        "public_key_path",
+        "public_key_sha256",
+    }
+    for item in value["signers"]:
+        if not isinstance(item, Mapping) or set(item) != required:
+            raise AdmissionInputError("TRUST_STORE_SIGNER_INVALID")
+        try:
+            signers.append(TrustedEvidenceSigner(**dict(item)))
+        except TypeError as exc:
+            raise AdmissionInputError("TRUST_STORE_SIGNER_INVALID") from exc
+    return tuple(signers)
+
+
+def _load_evidence_descriptor(path: str | None, error_code: str) -> Mapping[str, str] | None:
+    if path is None:
+        return None
+    try:
+        value = json.loads(pathlib.Path(path).read_text(encoding="utf-8"))
+    except (OSError, UnicodeError, json.JSONDecodeError) as exc:
+        raise AdmissionInputError(error_code) from exc
+    if (
+        not isinstance(value, Mapping)
+        or set(value) != {"path", "sha256"}
+        or not isinstance(value.get("path"), str)
+        or not _is_sha256(value.get("sha256"))
+    ):
+        raise AdmissionInputError(error_code)
+    return dict(value)
+
+
+def main(argv: Sequence[str] | None = None) -> int:
+    parser = argparse.ArgumentParser(description=__doc__)
+    parser.add_argument("--input", required=True)
+    parser.add_argument("--output-dir", required=True)
+    parser.add_argument("--evidence-root", required=True)
+    parser.add_argument("--as-of-utc", required=True)
+    parser.add_argument("--max-age-days", type=int, default=365)
+    parser.add_argument("--protected-eval-hashes")
+    parser.add_argument("--trust-store")
+    parser.add_argument("--split-ledger-evidence")
+    args = parser.parse_args(argv)
+    try:
+        policy = AdmissionPolicy(
+            as_of_utc=args.as_of_utc,
+            evidence_root=args.evidence_root,
+            max_age_days=args.max_age_days,
+            protected_eval_content_sha256=_load_protected_hashes(
+                args.protected_eval_hashes
+            ),
+            trusted_evidence_signers=_load_trusted_signers(args.trust_store),
+            split_ledger_evidence=_load_evidence_descriptor(
+                args.split_ledger_evidence,
+                "SPLIT_LEDGER_EVIDENCE_DESCRIPTOR_FILE_INVALID",
+            ),
+        )
+        report = admit_file(args.input, args.output_dir, policy)
+    except AdmissionInputError as exc:
+        print(json.dumps({"ok": False, "reason_code": str(exc)}, sort_keys=True))
+        return 2
+    print(
+        json.dumps(
+            {
+                "ok": True,
+                "state": report["state"],
+                "summary": report["summary"],
+                "report_receipt_sha256": report["report_receipt_sha256"],
+            },
+            sort_keys=True,
+        )
+    )
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

szl_braincorpus.py

@@ -0,0 +1,644 @@
+# SPDX-License-Identifier: Apache-2.0
+"""Bounded, content-addressed local corpus admission for the A11oy Brain.
+
+This module is intentionally an *admission/status* boundary, not a harvester and not a
+trainer.  It reads only three operator-selected JSON manifests, verifies local bytes, and
+classifies every item without changing any Brain trust threshold.  Missing sources remain
+``SOURCE_UNAVAILABLE``; malformed, conflicting, or weakly evidenced claims are quarantined.
+
+No request parameter can choose a filesystem path.  Defaults are repo-confined.  An operator
+may opt into one explicit manifest path per source through a named environment variable; an
+explicit manifest may reference only relative artifacts below its own directory.
+"""
+
+from __future__ import annotations
+
+import datetime as _datetime
+import hashlib
+import json
+import os
+import pathlib
+import re
+from collections import defaultdict
+from typing import Any, Mapping, Sequence
+
+SCHEMA_VERSION = "szl.brain.corpus-evidence.v1"
+PROOF_RECEIPT_SCHEMA = "szl.lean-kernel-proof-receipt.v1"
+ARTIFACT_RECEIPT_SCHEMA = "szl.brain.artifact-receipt.v1"
+SOURCE_TYPES = ("szl_lake", "lean_mathlib", "formula")
+EVIDENCE_CLASSES = ("PROVED", "OPEN", "REFUTED", "EXPERIMENTAL", "UNKNOWN")
+
+MAX_MANIFEST_BYTES = 8 * 1024 * 1024
+MAX_ARTIFACT_BYTES = 64 * 1024 * 1024
+MAX_ENTRIES = 5_000
+
+_SHA256_RE = re.compile(r"^[0-9a-f]{64}$")
+_COMMIT_RE = re.compile(r"^[0-9a-f]{40}$")
+_FORMULA_ID_RE = re.compile(r"^F[1-9][0-9]*$", re.IGNORECASE)
+
+DEFAULT_MANIFESTS = {
+    "szl_lake": pathlib.Path("data/szl-lake/evidence-manifest.json"),
+    "lean_mathlib": pathlib.Path("docs/thesis/v18/lean-corpus-evidence.json"),
+    "formula": pathlib.Path("corpus/formulas/formula-corpus-evidence.json"),
+}
+MANIFEST_ENV = {
+    "szl_lake": "A11OY_BRAIN_CORPUS_SZL_LAKE_MANIFEST",
+    "lean_mathlib": "A11OY_BRAIN_CORPUS_LEAN_MANIFEST",
+    "formula": "A11OY_BRAIN_CORPUS_FORMULA_MANIFEST",
+}
+
+MANIFEST_CONTRACT = {
+    "schema_version": SCHEMA_VERSION,
+    "source_types": list(SOURCE_TYPES),
+    "evidence_classes": list(EVIDENCE_CLASSES),
+    "required_top_level": ["schema_version", "source_type", "version", "entries"],
+    "entry_required": ["id", "evidence_class", "source_path", "artifact_sha256"],
+    "artifact_receipt_optional": {
+        "schema_version": ARTIFACT_RECEIPT_SCHEMA,
+        "purpose": (
+            "bind the admitted artifact to exact local source bytes and licenses; this "
+            "receipt never grants mathematical proof credit"
+        ),
+    },
+    "proof_receipt_required_for_proved": [
+        "schema_version", "verified", "artifact_sha256", "sorry_count",
+        "kernel_commit", "lean_commit", "mathlib_commit", "receipt_sha256",
+    ],
+    "proof_rule": (
+        "PROVED requires verified local artifact bytes, zero sorry/admit obligations, an exact "
+        "40-hex kernel/Lean/mathlib commit triple matching the manifest toolchain, and a valid "
+        "content-addressed kernel receipt"
+    ),
+    "non_uplift_rule": (
+        "OPEN, REFUTED, EXPERIMENTAL, UNKNOWN, invalid PROVED claims, and F-ID conflicts "
+        "receive zero proof credit and cannot raise query trust"
+    ),
+    "path_rule": (
+        "default manifests and artifacts are repo-confined; explicitly configured manifests "
+        "may read only relative artifacts confined below that manifest's directory"
+    ),
+}
+
+
+def _utc_now() -> str:
+    return _datetime.datetime.now(_datetime.timezone.utc).isoformat()
+
+
+def _canonical_json_bytes(value: Any) -> bytes:
+    return json.dumps(value, sort_keys=True, separators=(",", ":"), ensure_ascii=False).encode("utf-8")
+
+
+def sha256_json(value: Any) -> str:
+    """Return the canonical JSON SHA-256 used by proof receipts and fixture builders."""
+    return hashlib.sha256(_canonical_json_bytes(value)).hexdigest()
+
+
+def _sha256_file(path: pathlib.Path, maximum: int) -> tuple[str | None, int, str | None]:
+    try:
+        size = path.stat().st_size
+        if size > maximum:
+            return None, size, f"FILE_TOO_LARGE:{size}>{maximum}"
+        digest = hashlib.sha256()
+        read = 0
+        with path.open("rb") as stream:
+            while True:
+                chunk = stream.read(1024 * 1024)
+                if not chunk:
+                    break
+                read += len(chunk)
+                if read > maximum:
+                    return None, read, f"FILE_TOO_LARGE:{read}>{maximum}"
+                digest.update(chunk)
+        return digest.hexdigest(), read, None
+    except OSError as exc:
+        return None, 0, f"READ_FAILED:{type(exc).__name__}"
+
+
+def _read_file_bounded(path: pathlib.Path, maximum: int) -> tuple[bytes | None, str | None]:
+    """Read once so the bytes parsed are exactly the bytes that receive the content hash."""
+    try:
+        with path.open("rb") as stream:
+            raw = stream.read(maximum + 1)
+        if len(raw) > maximum:
+            return None, f"FILE_TOO_LARGE:{len(raw)}>{maximum}"
+        return raw, None
+    except OSError as exc:
+        return None, f"READ_FAILED:{type(exc).__name__}"
+
+
+def _inside(path: pathlib.Path, boundary: pathlib.Path) -> bool:
+    try:
+        path.relative_to(boundary)
+        return True
+    except ValueError:
+        return False
+
+
+def _safe_manifest_path(
+    source_type: str,
+    repo_root: pathlib.Path,
+    environ: Mapping[str, str],
+) -> tuple[pathlib.Path, pathlib.Path, str, str | None]:
+    """Resolve one fixed source path; no API/user value participates in this decision."""
+    env_name = MANIFEST_ENV[source_type]
+    configured = str(environ.get(env_name, "")).strip()
+    root = repo_root.resolve()
+    if configured:
+        raw = pathlib.Path(configured).expanduser()
+        path = (root / raw if not raw.is_absolute() else raw).resolve()
+        boundary = path.parent
+        origin = f"EXPLICIT_CONFIG:{env_name}"
+    else:
+        path = (root / DEFAULT_MANIFESTS[source_type]).resolve()
+        boundary = root
+        origin = "REPO_DEFAULT"
+        if not _inside(path, root):
+            return path, boundary, origin, "MANIFEST_PATH_ESCAPES_REPO"
+    if path.suffix.lower() != ".json":
+        return path, boundary, origin, "MANIFEST_MUST_BE_JSON"
+    return path, boundary, origin, None
+
+
+def _entry_shell(entry: Any, source_type: str, ordinal: int) -> dict[str, Any]:
+    entry_id = entry.get("id") if isinstance(entry, dict) else None
+    return {
+        "id": str(entry_id or f"entry-{ordinal}"),
+        "source_type": source_type,
+        "declared_class": "UNKNOWN",
+        "effective_class": "UNKNOWN",
+        "artifact_sha256": None,
+        "artifact_verified": False,
+        "artifact_receipt_valid": False,
+        "proof_receipt_valid": False,
+        "proof_credit": 0,
+        "trust_uplift_eligible": False,
+        "disposition": "QUARANTINED",
+        "quarantine_reasons": [],
+    }
+
+
+def _validate_artifact_receipt(
+    receipt: Any,
+    artifact_sha256: str,
+    artifact_boundary: pathlib.Path,
+) -> tuple[bool, list[str], dict[str, Any] | None]:
+    """Verify an optional local-byte receipt without upgrading proof status."""
+    if receipt is None:
+        return False, [], None
+    if not isinstance(receipt, dict):
+        return False, ["ARTIFACT_RECEIPT_NOT_OBJECT"], None
+    reasons: list[str] = []
+    if receipt.get("schema_version") != ARTIFACT_RECEIPT_SCHEMA:
+        reasons.append("ARTIFACT_RECEIPT_SCHEMA_MISMATCH")
+    if receipt.get("verified") is not True:
+        reasons.append("ARTIFACT_RECEIPT_NOT_VERIFIED")
+    if str(receipt.get("artifact_sha256") or "").lower() != artifact_sha256:
+        reasons.append("ARTIFACT_RECEIPT_ARTIFACT_MISMATCH")
+    if receipt.get("proof_credit") not in {0, 0.0}:
+        reasons.append("ARTIFACT_RECEIPT_PROOF_CREDIT_FORBIDDEN")
+
+    assets = receipt.get("source_assets")
+    if not isinstance(assets, list) or not assets:
+        reasons.append("ARTIFACT_RECEIPT_SOURCE_ASSETS_REQUIRED")
+        assets = []
+    elif len(assets) > 128:
+        reasons.append("ARTIFACT_RECEIPT_TOO_MANY_SOURCE_ASSETS")
+        assets = assets[:128]
+    public_assets: list[dict[str, Any]] = []
+    for ordinal, asset in enumerate(assets):
+        if not isinstance(asset, dict):
+            reasons.append(f"ARTIFACT_RECEIPT_ASSET_NOT_OBJECT:{ordinal}")
+            continue
+        path_value = str(asset.get("path") or "").strip()
+        expected = str(asset.get("sha256") or "").lower()
+        license_id = str(asset.get("license") or "").strip()
+        if not path_value:
+            reasons.append(f"ARTIFACT_RECEIPT_ASSET_PATH_REQUIRED:{ordinal}")
+            continue
+        relative = pathlib.Path(path_value)
+        path = (artifact_boundary / relative).resolve() if not relative.is_absolute() else None
+        if path is None or not _inside(path, artifact_boundary):
+            reasons.append(f"ARTIFACT_RECEIPT_ASSET_PATH_FORBIDDEN:{ordinal}")
+            continue
+        if not _SHA256_RE.fullmatch(expected):
+            reasons.append(f"ARTIFACT_RECEIPT_ASSET_SHA_INVALID:{ordinal}")
+        if not license_id or license_id.upper() == "UNKNOWN":
+            reasons.append(f"ARTIFACT_RECEIPT_ASSET_LICENSE_UNKNOWN:{ordinal}")
+        actual, size, read_error = _sha256_file(path, MAX_ARTIFACT_BYTES)
+        if read_error:
+            reasons.append(f"ARTIFACT_RECEIPT_ASSET_{read_error}:{ordinal}")
+        elif actual != expected:
+            reasons.append(f"ARTIFACT_RECEIPT_ASSET_SHA_MISMATCH:{ordinal}")
+        public_assets.append({
+            "path": path_value.replace("\\", "/"),
+            "sha256": expected or None,
+            "license": license_id or None,
+            "bytes": size,
+        })
+
+    stored = str(receipt.get("receipt_sha256") or "").lower()
+    body = {key: value for key, value in receipt.items() if key != "receipt_sha256"}
+    if not _SHA256_RE.fullmatch(stored) or stored != sha256_json(body):
+        reasons.append("ARTIFACT_RECEIPT_DIGEST_MISMATCH")
+    public = {
+        "schema_version": receipt.get("schema_version"),
+        "verified": receipt.get("verified") is True,
+        "artifact_sha256": str(receipt.get("artifact_sha256") or "").lower() or None,
+        "proof_credit": receipt.get("proof_credit"),
+        "source_asset_count": len(public_assets),
+        "source_assets": public_assets,
+        "receipt_sha256": stored or None,
+    }
+    return not reasons, reasons, public
+
+
+def _validate_toolchain(manifest: Mapping[str, Any]) -> tuple[dict[str, str], list[str]]:
+    raw = manifest.get("toolchain")
+    if not isinstance(raw, dict):
+        return {}, ["TOOLCHAIN_REQUIRED_FOR_PROVED"]
+    toolchain: dict[str, str] = {}
+    reasons: list[str] = []
+    for name in ("kernel_commit", "lean_commit", "mathlib_commit"):
+        value = str(raw.get(name) or "").lower()
+        if not _COMMIT_RE.fullmatch(value):
+            reasons.append(f"INVALID_EXACT_{name.upper()}")
+        else:
+            toolchain[name] = value
+    return toolchain, reasons
+
+
+def _validate_receipt(
+    receipt: Any,
+    artifact_sha256: str,
+    toolchain: Mapping[str, str],
+) -> tuple[bool, list[str], dict[str, Any] | None]:
+    if not isinstance(receipt, dict):
+        return False, ["KERNEL_RECEIPT_REQUIRED"], None
+    reasons: list[str] = []
+    if receipt.get("schema_version") != PROOF_RECEIPT_SCHEMA:
+        reasons.append("KERNEL_RECEIPT_SCHEMA_MISMATCH")
+    if receipt.get("verified") is not True:
+        reasons.append("KERNEL_RECEIPT_NOT_VERIFIED")
+    if receipt.get("artifact_sha256") != artifact_sha256:
+        reasons.append("KERNEL_RECEIPT_ARTIFACT_MISMATCH")
+    try:
+        receipt_sorries = int(receipt.get("sorry_count"))
+    except (TypeError, ValueError):
+        receipt_sorries = -1
+    if receipt_sorries != 0:
+        reasons.append("KERNEL_RECEIPT_NOT_ZERO_SORRY")
+    for name in ("kernel_commit", "lean_commit", "mathlib_commit"):
+        value = str(receipt.get(name) or "").lower()
+        if not _COMMIT_RE.fullmatch(value):
+            reasons.append(f"KERNEL_RECEIPT_INVALID_{name.upper()}")
+        elif value != toolchain.get(name):
+            reasons.append(f"KERNEL_RECEIPT_{name.upper()}_MISMATCH")
+    stored = str(receipt.get("receipt_sha256") or "").lower()
+    body = {key: value for key, value in receipt.items() if key != "receipt_sha256"}
+    computed = sha256_json(body)
+    if not _SHA256_RE.fullmatch(stored) or stored != computed:
+        reasons.append("KERNEL_RECEIPT_DIGEST_MISMATCH")
+    public = {
+        "schema_version": receipt.get("schema_version"),
+        "verified": receipt.get("verified") is True,
+        "sorry_count": receipt_sorries,
+        "kernel_commit": receipt.get("kernel_commit"),
+        "lean_commit": receipt.get("lean_commit"),
+        "mathlib_commit": receipt.get("mathlib_commit"),
+        "receipt_sha256": stored or None,
+    }
+    return not reasons, reasons, public
+
+
+def _validate_entry(
+    entry: Any,
+    source_type: str,
+    ordinal: int,
+    artifact_boundary: pathlib.Path,
+    toolchain: Mapping[str, str],
+) -> dict[str, Any]:
+    out = _entry_shell(entry, source_type, ordinal)
+    reasons: list[str] = out["quarantine_reasons"]
+    if not isinstance(entry, dict):
+        reasons.append("ENTRY_NOT_OBJECT")
+        return out
+
+    entry_id = str(entry.get("id") or "").strip()
+    if not entry_id:
+        reasons.append("ENTRY_ID_REQUIRED")
+    else:
+        out["id"] = entry_id.upper() if _FORMULA_ID_RE.fullmatch(entry_id) else entry_id
+
+    declared = str(entry.get("evidence_class") or "UNKNOWN").upper()
+    if declared not in EVIDENCE_CLASSES:
+        reasons.append("INVALID_EVIDENCE_CLASS")
+        declared = "UNKNOWN"
+    out["declared_class"] = declared
+    out["effective_class"] = declared
+
+    expected = str(entry.get("artifact_sha256") or "").lower()
+    out["artifact_sha256"] = expected or None
+    if not _SHA256_RE.fullmatch(expected):
+        reasons.append("INVALID_ARTIFACT_SHA256")
+
+    source_path = entry.get("source_path")
+    if not isinstance(source_path, str) or not source_path.strip():
+        reasons.append("SOURCE_PATH_REQUIRED")
+        artifact_path = None
+    else:
+        relative = pathlib.Path(source_path.strip())
+        if relative.is_absolute():
+            reasons.append("ABSOLUTE_ARTIFACT_PATH_FORBIDDEN")
+            artifact_path = None
+        else:
+            artifact_path = (artifact_boundary / relative).resolve()
+            if not _inside(artifact_path, artifact_boundary):
+                reasons.append("ARTIFACT_PATH_ESCAPES_BOUNDARY")
+                artifact_path = None
+
+    if artifact_path is not None:
+        out["source_path"] = source_path.replace("\\", "/")
+        if not artifact_path.is_file():
+            reasons.append("ARTIFACT_SOURCE_UNAVAILABLE")
+        else:
+            actual, size, read_error = _sha256_file(artifact_path, MAX_ARTIFACT_BYTES)
+            out["artifact_bytes"] = size
+            out["computed_artifact_sha256"] = actual
+            if read_error:
+                reasons.append(read_error)
+            elif actual != expected:
+                reasons.append("ARTIFACT_SHA256_MISMATCH")
+            else:
+                out["artifact_verified"] = True
+
+    try:
+        sorry_count = int(entry.get("sorry_count", 0))
+    except (TypeError, ValueError):
+        sorry_count = -1
+    if sorry_count < 0:
+        reasons.append("INVALID_SORRY_COUNT")
+        sorry_count = 0
+    out["sorry_count"] = sorry_count
+
+    artifact_receipt_valid, artifact_receipt_reasons, artifact_receipt_public = (
+        _validate_artifact_receipt(entry.get("artifact_receipt"), expected, artifact_boundary)
+    )
+    reasons.extend(artifact_receipt_reasons)
+    out["artifact_receipt_valid"] = artifact_receipt_valid
+    out["artifact_receipt"] = artifact_receipt_public
+
+    if declared == "PROVED":
+        if sorry_count != 0:
+            reasons.append("PROVED_REQUIRES_ZERO_SORRY")
+        valid_receipt, receipt_reasons, receipt_public = _validate_receipt(
+            entry.get("proof_receipt"), expected, toolchain,
+        )
+        reasons.extend(receipt_reasons)
+        out["proof_receipt"] = receipt_public
+        out["proof_receipt_valid"] = valid_receipt
+        if reasons or not out["artifact_verified"] or not valid_receipt:
+            out["effective_class"] = "UNKNOWN"
+    else:
+        out["proof_receipt"] = None
+        out["proof_receipt_valid"] = False
+
+    proof_eligible = bool(
+        declared == "PROVED"
+        and out["effective_class"] == "PROVED"
+        and out["artifact_verified"]
+        and out["proof_receipt_valid"]
+        and not reasons
+    )
+    out["proof_credit"] = 1 if proof_eligible else 0
+    out["trust_uplift_eligible"] = proof_eligible
+    if proof_eligible:
+        out["disposition"] = "ADMITTED_PROOF_EVIDENCE"
+    elif not reasons and declared in {"OPEN", "REFUTED", "EXPERIMENTAL", "UNKNOWN"}:
+        out["disposition"] = "QUARANTINED_NON_PROOF"
+        reasons.append(f"{declared}_HAS_ZERO_PROOF_CREDIT")
+    elif reasons:
+        out["effective_class"] = "UNKNOWN"
+    return out
+
+
+def _load_manifest(
+    source_type: str,
+    manifest_path: pathlib.Path,
+    artifact_boundary: pathlib.Path,
+    origin: str,
+) -> dict[str, Any]:
+    public_path = (
+        manifest_path.relative_to(artifact_boundary).as_posix()
+        if origin == "REPO_DEFAULT"
+        else f"<explicit-config>/{manifest_path.name}"
+    )
+    base: dict[str, Any] = {
+        "source_type": source_type,
+        "status": "SOURCE_UNAVAILABLE",
+        "manifest_origin": origin,
+        "manifest_path": public_path,
+        "entries": [],
+        "counts": {name: 0 for name in EVIDENCE_CLASSES},
+        "proof_credit": 0,
+        "errors": [],
+    }
+    if not manifest_path.is_file():
+        base["errors"] = ["MANIFEST_NOT_FOUND"]
+        return base
+    raw, read_error = _read_file_bounded(manifest_path, MAX_MANIFEST_BYTES)
+    base["manifest_sha256"] = hashlib.sha256(raw).hexdigest() if raw is not None else None
+    base["manifest_bytes"] = len(raw) if raw is not None else 0
+    if read_error:
+        base["status"] = "MANIFEST_QUARANTINED"
+        base["errors"] = [read_error]
+        return base
+    try:
+        manifest = json.loads(raw.decode("utf-8"))
+    except (UnicodeError, json.JSONDecodeError) as exc:
+        base["status"] = "MANIFEST_QUARANTINED"
+        base["errors"] = [f"INVALID_JSON:{type(exc).__name__}"]
+        return base
+    if not isinstance(manifest, dict):
+        base["status"] = "MANIFEST_QUARANTINED"
+        base["errors"] = ["MANIFEST_NOT_OBJECT"]
+        return base
+    if manifest.get("schema_version") != SCHEMA_VERSION:
+        base["status"] = "MANIFEST_QUARANTINED"
+        base["errors"] = ["SCHEMA_VERSION_MISMATCH"]
+        return base
+    if manifest.get("source_type") != source_type:
+        base["status"] = "MANIFEST_QUARANTINED"
+        base["errors"] = ["SOURCE_TYPE_MISMATCH"]
+        return base
+    if not isinstance(manifest.get("version"), str) or not manifest["version"].strip():
+        base["status"] = "MANIFEST_QUARANTINED"
+        base["errors"] = ["VERSION_REQUIRED"]
+        return base
+    entries = manifest.get("entries")
+    if not isinstance(entries, list):
+        base["status"] = "MANIFEST_QUARANTINED"
+        base["errors"] = ["ENTRIES_MUST_BE_ARRAY"]
+        return base
+    if len(entries) > MAX_ENTRIES:
+        base["status"] = "MANIFEST_QUARANTINED"
+        base["errors"] = [f"TOO_MANY_ENTRIES:{len(entries)}>{MAX_ENTRIES}"]
+        return base
+
+    expected_manifest_digest = manifest.get("content_sha256")
+    if expected_manifest_digest is not None:
+        body = {key: value for key, value in manifest.items() if key != "content_sha256"}
+        actual_manifest_digest = sha256_json(body)
+        base["manifest_content_sha256"] = actual_manifest_digest
+        if (not isinstance(expected_manifest_digest, str)
+                or expected_manifest_digest.lower() != actual_manifest_digest):
+            base["status"] = "MANIFEST_QUARANTINED"
+            base["errors"] = ["MANIFEST_CONTENT_DIGEST_MISMATCH"]
+            return base
+
+    toolchain, toolchain_errors = _validate_toolchain(manifest)
+    if any(str(e.get("evidence_class") or "").upper() == "PROVED"
+           for e in entries if isinstance(e, dict)) and toolchain_errors:
+        base["errors"].extend(toolchain_errors)
+    base["version"] = manifest["version"]
+    base["toolchain"] = toolchain or None
+    base["entries"] = [
+        _validate_entry(e, source_type, i, artifact_boundary, toolchain)
+        for i, e in enumerate(entries)
+    ]
+    for entry in base["entries"]:
+        base["counts"][entry["effective_class"]] += 1
+        base["proof_credit"] += entry["proof_credit"]
+    quarantined = sum(e["disposition"].startswith("QUARANTINED") for e in base["entries"])
+    if base["errors"] or quarantined:
+        base["status"] = "PARTIAL_QUARANTINE" if base["entries"] else "MANIFEST_QUARANTINED"
+    else:
+        base["status"] = "INGESTED_LOCAL"
+    return base
+
+
+def _apply_formula_id_conflicts(sources: Sequence[dict[str, Any]]) -> list[dict[str, Any]]:
+    by_id: dict[str, list[dict[str, Any]]] = defaultdict(list)
+    for source in sources:
+        for entry in source.get("entries", []):
+            entry_id = str(entry.get("id") or "").upper()
+            if _FORMULA_ID_RE.fullmatch(entry_id):
+                by_id[entry_id].append(entry)
+    conflicts: list[dict[str, Any]] = []
+    for formula_id, rows in sorted(by_id.items()):
+        signatures = {
+            (
+                row.get("artifact_sha256"), row.get("effective_class"),
+                (row.get("proof_receipt") or {}).get("receipt_sha256"),
+            )
+            for row in rows
+        }
+        if len(signatures) <= 1:
+            continue
+        conflicts.append({
+            "formula_id": formula_id,
+            "reason": "F_ID_CONFLICT",
+            "variants": len(signatures),
+            "sources": sorted({str(row.get("source_type")) for row in rows}),
+        })
+        for row in rows:
+            row["disposition"] = "QUARANTINED"
+            row["effective_class"] = "UNKNOWN"
+            row["proof_credit"] = 0
+            row["trust_uplift_eligible"] = False
+            row.setdefault("quarantine_reasons", []).append("F_ID_CONFLICT")
+    return conflicts
+
+
+def build_corpus_status(
+    repo_root: pathlib.Path | str | None = None,
+    environ: Mapping[str, str] | None = None,
+) -> dict[str, Any]:
+    """Build a bounded, read-only admission status from local canonical manifests."""
+    root = pathlib.Path(repo_root or pathlib.Path(__file__).resolve().parent).resolve()
+    env = os.environ if environ is None else environ
+    sources: list[dict[str, Any]] = []
+    for source_type in SOURCE_TYPES:
+        manifest_path, boundary, origin, path_error = _safe_manifest_path(source_type, root, env)
+        if path_error:
+            sources.append({
+                "source_type": source_type,
+                "status": "SOURCE_UNAVAILABLE",
+                "manifest_origin": origin,
+                "manifest_path": (
+                    manifest_path.relative_to(root).as_posix()
+                    if origin == "REPO_DEFAULT" and _inside(manifest_path, root)
+                    else f"<explicit-config>/{manifest_path.name}"
+                ),
+                "entries": [],
+                "counts": {name: 0 for name in EVIDENCE_CLASSES},
+                "proof_credit": 0,
+                "errors": [path_error],
+            })
+            continue
+        # Default artifacts are repo-confined. Explicit external artifacts are confined below
+        # the explicit manifest directory; the environment is the sole operator trust boundary.
+        artifact_boundary = root if origin == "REPO_DEFAULT" else boundary
+        sources.append(_load_manifest(source_type, manifest_path, artifact_boundary, origin))
+
+    conflicts = _apply_formula_id_conflicts(sources)
+    counts = {name: 0 for name in EVIDENCE_CLASSES}
+    proof_credit = 0
+    quarantined_entries = 0
+    for source in sources:
+        source["counts"] = {name: 0 for name in EVIDENCE_CLASSES}
+        source["proof_credit"] = 0
+        for entry in source.get("entries", []):
+            source["counts"][entry["effective_class"]] += 1
+            source["proof_credit"] += entry["proof_credit"]
+            counts[entry["effective_class"]] += 1
+            proof_credit += entry["proof_credit"]
+            quarantined_entries += int(entry["disposition"].startswith("QUARANTINED"))
+        if any("F_ID_CONFLICT" in e.get("quarantine_reasons", []) for e in source.get("entries", [])):
+            source["status"] = "PARTIAL_QUARANTINE"
+
+    corpus_operational = any(
+        source["status"] in {"INGESTED_LOCAL", "PARTIAL_QUARANTINE"}
+        and bool(source.get("entries"))
+        for source in sources
+    )
+
+    return {
+        "ok": True,
+        "endpoint": "brain/health/corpus-sources",
+        "label": "MEASURED",
+        "schema_version": SCHEMA_VERSION,
+        "manifest_contract": MANIFEST_CONTRACT,
+        "sources": sources,
+        "formula_id_conflicts": conflicts,
+        "summary": {
+            "counts": counts,
+            "proof_credit": proof_credit,
+            "quarantined_entries": quarantined_entries,
+            "trust_uplift_from_non_proved": 0,
+            "missing_sources": sum(s["status"] == "SOURCE_UNAVAILABLE" for s in sources),
+            "corpus_operational": corpus_operational,
+            "proof_admission_available": proof_credit > 0,
+            "network_access": False,
+            "gpu_training_started": False,
+            "writes_performed": 0,
+            "trust_thresholds_changed": False,
+        },
+        "note": (
+            "This is admission evidence, not a proof-count claim. Legacy/Hugging Face snapshots "
+            "are not translated into the canonical contract; missing sources remain unavailable."
+        ),
+        "timestamp_utc": _utc_now(),
+    }
+
+
+def info() -> dict[str, Any]:
+    """Static, side-effect-free contract description for documentation and tests."""
+    return {
+        "service": "a11oy.brain.corpus-admission",
+        "schema_version": SCHEMA_VERSION,
+        "contract": MANIFEST_CONTRACT,
+        "effectors": 0,
+        "network_access": False,
+        "gpu_training": False,
+        "request_selected_paths": False,
+    }

szl_brainhealth.py

@@ -54,9 +54,14 @@ import datetime
 import hashlib
 import importlib
 import json
+import pathlib
 import re
+import threading
+import time
 from typing import Any, Callable
 
+import szl_braincorpus as _braincorpus
+
 try:  # numpy is allowed; used only for the modeled mean, guarded so a missing wheel is honest.
     import numpy as _np
     _HAVE_NUMPY = True
@@ -92,6 +97,25 @@ DEGRADED = "DEGRADED"
 UNTRUSTWORTHY = "UNTRUSTWORTHY"
 INSUFFICIENT_SIGNAL = "INSUFFICIENT-SIGNAL"
 
+# Operational readiness is deliberately separate from epistemic/query trust.  A service can
+# load its index and expose every honesty component while a particular question still needs to
+# abstain.  Conflating these two states made the blank dashboard query look like a failed brain.
+SERVICE_READY = "READY"
+SERVICE_DEGRADED = "DEGRADED"
+QUERY_EVALUATED = "EVALUATED"
+QUERY_NOT_EVALUATED = "NOT-EVALUATED"
+
+_ROOT = pathlib.Path(__file__).resolve().parent
+
+_REFRESH_LOCK = threading.Lock()
+_REFRESH_COOLDOWN_SECONDS = 5.0
+_LAST_REFRESH_MONOTONIC = 0.0
+
+
+def _client_is_loopback(host: str | None) -> bool:
+    """Fail-closed client check for the local-only cache rebuild endpoint."""
+    return str(host or "").strip().lower() in {"127.0.0.1", "::1", "localhost", "testclient"}
+
 VERDICTS = (TRUSTWORTHY, DEGRADED, UNTRUSTWORTHY, INSUFFICIENT_SIGNAL)
 
 # Minimum available components required to render a confident verdict; below this the honest
@@ -148,7 +172,7 @@ COMPONENTS: list[dict] = [
         "funcs": ("build_provenance",),
         "call_style": "ns_q_k",
         "value_keys": ("trust_value", "provenance_coverage", "lineage_coverage", "score", "value"),
-        "adverse": ("unprovenanced", "no-lineage", "no lineage", "unsourced"),
+        "adverse": ("unprovenanced", "untraceable", "no-lineage", "no lineage", "unsourced"),
     },
     {
         "key": "contradiction",
@@ -439,6 +463,168 @@ def _gather_component(spec: dict, q: str, k: int, ns: str = "a11oy") -> dict:
     return base
 
 
+def _component_module_readiness() -> list[dict]:
+    """Probe import/entrypoint readiness without running a query or inventing query evidence."""
+    checks = []
+    for spec in COMPONENTS:
+        fn = _resolve_callable(spec)
+        checks.append({
+            "key": spec["key"],
+            "module": spec["module"],
+            "ready": callable(fn),
+            "entrypoint": spec["funcs"][0],
+        })
+    return checks
+
+
+def _source_snapshot_metadata(ns: str = "a11oy") -> dict:
+    """Small, source-authored snapshot manifest; never substitutes request time for capture time."""
+    try:
+        import a11oy_brain_graph as graph_module
+        import szl_brain_api as brain_api
+
+        graph = graph_module.get_brain_graph(ns)
+        index = brain_api.get_index(ns)
+        sources = graph.get("sources") if isinstance(graph.get("sources"), dict) else {}
+        repos = sources.get("repos") if isinstance(sources.get("repos"), dict) else {}
+        harvest = sources.get("harvest") if isinstance(sources.get("harvest"), dict) else {}
+        return {
+            "available": True,
+            "label": graph.get("label", MODELED),
+            "graph_generated_at": graph.get("generated"),
+            "graph_content_hash": getattr(index, "content_hash", None),
+            "node_count": graph.get("node_count"),
+            "link_count": graph.get("link_count"),
+            "distinct_artifacts": graph.get("distinct_artifacts"),
+            "sources": {
+                "surfaces": sources.get("surfaces"),
+                "formulas": sources.get("formulas"),
+                "repos": repos,
+                "topics": sources.get("topics"),
+                "harvest": harvest,
+            },
+            "capture_evidence": {
+                "repo_snapshot_captured": repos.get("captured"),
+                "repo_snapshot_source": repos.get("source"),
+                "harvest_files": list(harvest.get("files") or []),
+                "harvest_source": harvest.get("source"),
+            },
+            "freshness_rule": (
+                "only source-provided captured_at/harvested_at values count as recency; "
+                "graph_generated_at is cache-build time and is never treated as source freshness"
+            ),
+            "refresh_scope": "bounded committed local sources; no network, no source-date rewrite",
+        }
+    except Exception as exc:
+        return {
+            "available": False,
+            "label": UNAVAILABLE,
+            "error": str(exc)[:200],
+            "freshness_rule": "no source timestamp fabricated while snapshot is unavailable",
+            "refresh_scope": "bounded committed local sources; no network, no source-date rewrite",
+        }
+
+
+def build_corpus_source_contract() -> dict:
+    """Return the bounded content-addressed corpus admission status (pure read)."""
+    return _braincorpus.build_corpus_status(_ROOT)
+
+
+def _service_readiness(ns: str = "a11oy", snapshot: dict | None = None) -> dict:
+    """Operational/service readiness only.  It is never a synonym for query trust."""
+    module_checks = _component_module_readiness()
+    snapshot = snapshot if isinstance(snapshot, dict) else _source_snapshot_metadata(ns)
+    modules_ready = all(c["ready"] for c in module_checks)
+    index_ready = bool(snapshot.get("available") and snapshot.get("graph_content_hash")
+                       and isinstance(snapshot.get("node_count"), int)
+                       and snapshot.get("node_count") > 0)
+    operational = modules_ready and index_ready
+    return {
+        "status": SERVICE_READY if operational else SERVICE_DEGRADED,
+        "operational": operational,
+        "query_trust_equivalent": False,
+        "checks": {
+            "brain_index_readable": index_ready,
+            "honesty_components_loadable": modules_ready,
+            "component_modules": module_checks,
+        },
+        "note": (
+            "READY means the local graph/index and honesty evaluators can serve requests; it does "
+            "not mean any query is trustworthy. Query trust remains a separate evidence verdict."
+        ),
+    }
+
+
+def _remediation_plan(components: list[dict], query_evaluated: bool, ns: str) -> list[dict]:
+    """Return concrete next actions for observed gaps; actions never change verdicts by fiat."""
+    base = f"/api/{ns}/v1/brain/health"
+    if not query_evaluated:
+        return [{
+            "component": "query",
+            "action": "submit a non-empty q parameter to run grounding/provenance/conflict/uncertainty",
+            "endpoint": f"GET {base}?q=<question>&k=12",
+            "effect_on_trust": "none until evidence is evaluated",
+        }]
+
+    actions = []
+    adverse = {c.get("key"): c.get("adverse_reason") for c in components
+               if c.get("signal") == SIG_ADVERSE}
+    if "freshness" in adverse:
+        actions.append({
+            "component": "freshness",
+            "action": (
+                "reindex the bounded committed local sources, then replace stale/undated source "
+                "snapshots only through a separately reviewed harvest carrying real capture times"
+            ),
+            "endpoint": f"POST {base}/refresh",
+            "limitation": (
+                "local reindex clears caches but cannot make old evidence fresh or rewrite capture times"
+            ),
+        })
+    if "grounding" in adverse:
+        actions.append({
+            "component": "grounding",
+            "action": "narrow the query or ingest a cited local source that directly covers its terms",
+            "effect_on_trust": "re-evaluate; no automatic upgrade",
+        })
+    if "provenance" in adverse:
+        actions.append({
+            "component": "provenance",
+            "action": "attach source/url and an honest label to every supporting node, then reindex",
+            "effect_on_trust": "re-evaluate; no automatic upgrade",
+        })
+    if "contradiction" in adverse:
+        actions.append({
+            "component": "contradiction",
+            "action": "inspect the reported conflict pairs; resolve sources or narrow the claim scope",
+            "effect_on_trust": "re-evaluate; conflicts remain adverse until evidence changes",
+        })
+    if "uncertainty" in adverse:
+        actions.append({
+            "component": "uncertainty",
+            "action": "narrow the question and require a more concentrated, source-cited retrieval",
+            "effect_on_trust": "re-evaluate; abstention remains active until uncertainty falls",
+        })
+    return actions
+
+
+def _unevaluated_components() -> list[dict]:
+    checks = {c["key"]: c for c in _component_module_readiness()}
+    return [{
+        "key": spec["key"],
+        "title": spec["title"],
+        "module": spec["module"],
+        "available": False,
+        "service_available": bool(checks[spec["key"]]["ready"]),
+        "label": UNAVAILABLE,
+        "value": None,
+        "signal": None,
+        "adverse_reason": None,
+        "evaluation_status": QUERY_NOT_EVALUATED,
+        "note": "no query was supplied; component was not invoked and no query evidence was fabricated",
+    } for spec in COMPONENTS]
+
+
 # ---------------------------------------------------------------------------
 # Rollup assembly — pure computation over ONLY the available components. Mints nothing.
 # ---------------------------------------------------------------------------
@@ -485,8 +671,16 @@ def _modeled_trust(components: list[dict]) -> float | None:
 def build_rollup(q: str = "", k: int = 12, ns: str = "a11oy") -> dict:
     """Gather every brain-honesty component (available ones read VERBATIM, missing ones
     UNAVAILABLE) and roll the AVAILABLE ones into ONE honest brain-trust verdict."""
-    components = [_gather_component(spec, q, k, ns=ns) for spec in COMPONENTS]
-    verdict, reason = _decide_verdict(components)
+    q = (q or "").strip()
+    query_evaluated = bool(q)
+    if query_evaluated:
+        components = [_gather_component(spec, q, k, ns=ns) for spec in COMPONENTS]
+        verdict, reason = _decide_verdict(components)
+    else:
+        components = _unevaluated_components()
+        verdict = INSUFFICIENT_SIGNAL
+        reason = ("no query supplied; epistemic trust was NOT EVALUATED. Operational readiness "
+                  "is reported separately and is never promoted into a query-trust verdict")
 
     available = [c for c in components if c["available"]]
     unavailable = [c for c in components if not c["available"]]
@@ -501,7 +695,9 @@ def build_rollup(q: str = "", k: int = 12, ns: str = "a11oy") -> dict:
                     for c in available if c["signal"] == SIG_ADVERSE],
         "min_components_required": MIN_COMPONENTS,
     }
-    trust = _modeled_trust(components)
+    trust = _modeled_trust(components) if query_evaluated else None
+    snapshot = _source_snapshot_metadata(ns)
+    readiness = _service_readiness(ns, snapshot=snapshot)
 
     return {
         "ok": True,
@@ -512,6 +708,14 @@ def build_rollup(q: str = "", k: int = 12, ns: str = "a11oy") -> dict:
         "label": MODELED,
         "query": q,
         "k": k,
+        "query_assessment": {
+            "status": QUERY_EVALUATED if query_evaluated else QUERY_NOT_EVALUATED,
+            "evaluated": query_evaluated,
+            "note": ("component evidence evaluated for this query" if query_evaluated else
+                     "blank q is a service-status view only; no answer trust was inferred"),
+        },
+        "service_readiness": readiness,
+        "source_snapshot": snapshot,
         "verdict": verdict,
         "verdict_reason": reason,
         "modeled_trust": trust,
@@ -524,6 +728,7 @@ def build_rollup(q: str = "", k: int = 12, ns: str = "a11oy") -> dict:
                  "honesty — advances no detection/fusion/effector/targeting/cueing capability."),
         "components": components,
         "summary": summary,
+        "remediation": _remediation_plan(components, query_evaluated, ns),
         "doctrine": {
             "label_top": MODELED,
             "locked_proven": LOCKED_COUNT,
@@ -559,6 +764,7 @@ def _canonical_core(rollup: dict) -> str:
     volatile timestamp), so the digest attests the VERDICT + component evidence, not the clock."""
     core = {
         "query": rollup.get("query"),
+        "query_assessment": rollup.get("query_assessment"),
         "verdict": rollup.get("verdict"),
         "modeled_trust": rollup.get("modeled_trust"),
         "summary": rollup.get("summary"),
@@ -568,6 +774,10 @@ def _canonical_core(rollup: dict) -> str:
              "adverse_reason": c.get("adverse_reason")}
             for c in rollup.get("components", [])
         ],
+        "source_snapshot": {
+            "graph_content_hash": (rollup.get("source_snapshot") or {}).get("graph_content_hash"),
+            "capture_evidence": (rollup.get("source_snapshot") or {}).get("capture_evidence"),
+        },
     }
     return json.dumps(core, sort_keys=True, separators=(",", ":"), default=str)
 
@@ -589,6 +799,96 @@ def _content_receipt(rollup: dict) -> dict:
     }
 
 
+def _refresh_receipt(core: dict) -> dict:
+    canonical = json.dumps(core, sort_keys=True, separators=(",", ":"), default=str)
+    return {
+        "kind": "szl.brainhealth.bounded-local-reindex",
+        "algorithm": "sha256",
+        "content_sha256": hashlib.sha256(canonical.encode("utf-8")).hexdigest(),
+        "signed": False,
+        "mode": "UNSIGNED-CONTENT-DIGEST",
+        "receipt_on": "write (POST refresh)",
+        "note": (
+            "unsigned digest of the bounded local reindex result; no source timestamps were "
+            "rewritten and no signature was fabricated"
+        ),
+        "computed_at": _now_iso(),
+    }
+
+
+def handle_refresh(ns: str = "a11oy") -> dict:
+    """Rebuild only the in-process graph/index from committed local sources.
+
+    This is intentionally not a network harvest and cannot make stale evidence fresh.  It is a
+    bounded cache/index write with a receipt so operators can distinguish "reindexed" from
+    "source evidence updated".
+    """
+    global _LAST_REFRESH_MONOTONIC
+    if not _REFRESH_LOCK.acquire(blocking=False):
+        return {
+            "ok": False, "endpoint": "brain/health/refresh", "label": UNAVAILABLE,
+            "outcome": "REINDEX-IN-PROGRESS", "retry_after_seconds": _REFRESH_COOLDOWN_SECONDS,
+            "source_freshness_changed": False, "receipt": None,
+        }
+    now = time.monotonic()
+    if _LAST_REFRESH_MONOTONIC and now - _LAST_REFRESH_MONOTONIC < _REFRESH_COOLDOWN_SECONDS:
+        retry = round(_REFRESH_COOLDOWN_SECONDS - (now - _LAST_REFRESH_MONOTONIC), 3)
+        _REFRESH_LOCK.release()
+        return {
+            "ok": False, "endpoint": "brain/health/refresh", "label": UNAVAILABLE,
+            "outcome": "REINDEX-COOLDOWN", "retry_after_seconds": retry,
+            "source_freshness_changed": False, "receipt": None,
+        }
+    before = _source_snapshot_metadata(ns)
+    try:
+        import szl_brain_api as brain_api
+
+        # get_index(refresh=True) refreshes the graph exactly once and rebuilds the index.
+        brain_api.get_index(ns, refresh=True)
+        after = _source_snapshot_metadata(ns)
+        core = {
+            "scope": "BOUNDED-COMMITTED-LOCAL-SOURCES",
+            "network_access": False,
+            "source_timestamps_rewritten": False,
+            "before_content_hash": before.get("graph_content_hash"),
+            "after_content_hash": after.get("graph_content_hash"),
+            "node_count": after.get("node_count"),
+            "link_count": after.get("link_count"),
+            "capture_evidence": after.get("capture_evidence"),
+        }
+        return {
+            "ok": True,
+            "endpoint": "brain/health/refresh",
+            "label": MODELED,
+            "outcome": "REINDEXED",
+            "changed": core["before_content_hash"] != core["after_content_hash"],
+            "source_freshness_changed": False,
+            "before": before,
+            "after": after,
+            "receipt": _refresh_receipt(core),
+            "note": (
+                "local caches/index rebuilt from committed bounded sources. This does not refresh "
+                "old capture dates; update source snapshots through a reviewed harvest if stale."
+            ),
+            "timestamp_utc": _now_iso(),
+        }
+    except Exception as exc:
+        return {
+            "ok": False,
+            "endpoint": "brain/health/refresh",
+            "label": UNAVAILABLE,
+            "outcome": "REINDEX-FAILED",
+            "source_freshness_changed": False,
+            "error": str(exc)[:200],
+            "receipt": None,
+            "note": "no source timestamps changed and no receipt minted over a failed reindex",
+            "timestamp_utc": _now_iso(),
+        }
+    finally:
+        _LAST_REFRESH_MONOTONIC = time.monotonic()
+        _REFRESH_LOCK.release()
+
+
 # ---------------------------------------------------------------------------
 # Handlers.
 # ---------------------------------------------------------------------------
@@ -615,7 +915,17 @@ def handle_info(ns: str = "a11oy") -> dict:
             "info": f"GET  {base}/info",
             "health": f"GET  {base}?q=&k=",
             "receipt": f"POST {base}/receipt",
+            "bounded_local_reindex": f"POST {base}/refresh",
+            "corpus_sources": f"GET  {base}/corpus-sources",
+            "corpus_sources_info": f"GET  {base}/corpus-sources/info",
+        },
+        "state_separation": {
+            "service_readiness": "can the graph/index and evaluators serve a request?",
+            "query_trust": "does the evidence support this specific non-empty query?",
+            "invariant": "service READY never promotes query trust",
+            "empty_query": QUERY_NOT_EVALUATED,
         },
+        "source_snapshot": _source_snapshot_metadata(ns),
         "verdicts": list(VERDICTS),
         "verdict_legend": {
             TRUSTWORTHY: "enough components available and ALL OK; none UNAVAILABLE",
@@ -699,6 +1009,17 @@ def register(app, ns: str = "a11oy") -> str:
         """Live brain-trust rollup verdict + per-component value/label/available (pure read)."""
         return JSONResponse(handle_health(q, k, ns))
 
+    @app.get(f"{base}/corpus-sources")
+    def _brainhealth_corpus_sources():
+        """Versioned local evidence manifests under the no-uplift proof lattice."""
+        return JSONResponse(build_corpus_source_contract())
+
+    @app.get(f"{base}/corpus-sources/info")
+    def _brainhealth_corpus_sources_info():
+        """Static, side-effect-free content-addressed corpus admission contract."""
+        return JSONResponse({"ok": True, "endpoint": "brain/health/corpus-sources/info",
+                             **_braincorpus.info()})
+
     async def _brainhealth_receipt(request):
         """POST: rollup + UNSIGNED SHA-256 content digest (RECEIPT-ON-WRITE). Reads q/k from the
         query string when present; the body is otherwise ignored (a pure rollup compute)."""
@@ -718,6 +1039,7 @@ def register(app, ns: str = "a11oy") -> str:
         pass
 
     rec_path = f"{base}/receipt"
+    refresh_path = f"{base}/refresh"
     add_route = getattr(getattr(app, "router", None), "add_route", None)
     add_api_route = getattr(app, "add_api_route", None)
     try:
@@ -733,7 +1055,50 @@ def register(app, ns: str = "a11oy") -> str:
               file=__import__("sys").stderr)
         return "brainhealth-wired:2(get-only)"
 
-    return "brainhealth-wired:3"
+    async def _brainhealth_refresh(request):
+        """POST: bounded local cache/index rebuild with an unsigned result receipt."""
+        client = getattr(request, "client", None)
+        host = getattr(client, "host", None)
+        if not _client_is_loopback(host):
+            return JSONResponse({
+                "ok": False,
+                "endpoint": "brain/health/refresh",
+                "label": UNAVAILABLE,
+                "outcome": "LOCAL-CLIENT-REQUIRED",
+                "source_freshness_changed": False,
+                "receipt": None,
+                "note": "bounded local reindex rejects non-loopback clients; no auth bypass",
+            }, status_code=403)
+        result = handle_refresh(ns)
+        status = 200
+        if result.get("outcome") == "REINDEX-IN-PROGRESS":
+            status = 409
+        elif result.get("outcome") == "REINDEX-COOLDOWN":
+            status = 429
+        elif not result.get("ok"):
+            status = 503
+        return JSONResponse(result, status_code=status)
+
+    try:
+        import fastapi as _fastapi
+        _brainhealth_refresh.__annotations__["request"] = _fastapi.Request
+    except Exception:  # noqa: BLE001
+        pass
+
+    try:
+        if callable(add_route):
+            app.router.add_route(refresh_path, _brainhealth_refresh, methods=["POST"])
+        elif callable(add_api_route):
+            app.add_api_route(refresh_path, _brainhealth_refresh, methods=["POST"])
+        else:  # pragma: no cover
+            from starlette.routing import Route
+            app.router.routes.append(Route(refresh_path, _brainhealth_refresh, methods=["POST"]))
+    except Exception as exc:  # additive register must never break boot
+        print(f"[{ns}] brainhealth refresh POST route NOT wired (guarded): {exc!r}",
+              file=__import__("sys").stderr)
+        return "brainhealth-wired:3(no-refresh)"
+
+    return "brainhealth-wired:5"
 
 
 # ---------------------------------------------------------------------------

szl_claim_rupture_gate.py

@@ -473,4 +473,3 @@ def info() -> dict[str, Any]:
         ],
         "not_implemented_here": ["HTTP registration", "persistence", "signing", "effectors"],
     }
-

szl_formal_conjecture_lab.py

@@ -0,0 +1,727 @@
+#!/usr/bin/env python3
+# SPDX-License-Identifier: Apache-2.0
+# (c) 2026 Lutar, Stephen P. - SZL Holdings - ORCID 0009-0001-0110-4173
+"""Fail-closed formal-conjecture attempt and kernel-receipt ledger.
+
+Taxonomy home: services/provenance.  This module does not execute a prover.  It
+stores bounded declarations and formal artifacts, then accepts only a DSSE
+kernel-result receipt that verifies against the published SZL cosign public
+key and binds the exact server-computed statement and artifact hashes.
+
+``KERNEL_ACCEPTED`` means only that the configured external Lean 4 checker
+reported exit code zero with no sorries or unsafe declarations.  It does not
+promote a conjecture, add a locked formula, establish novelty, or authorize a
+publication claim.  Reads never mint receipts; every successful write appends
+one hash-chained, honestly unsigned DSSE-shaped Khipu event.
+"""
+
+import base64
+import binascii
+import datetime
+import hashlib
+import json
+import os
+import re
+import threading
+from pathlib import Path
+from typing import Any, Mapping
+
+
+ATTEMPT_SCHEMA = "szl.formal-conjecture-attempt/v1"
+KERNEL_SCHEMA = "szl.formal-kernel-result/v1"
+KERNEL_PAYLOAD_TYPE = "application/vnd.szl.formal-kernel-result+json"
+LOCAL_PAYLOAD_TYPE = "application/vnd.szl.khipu+json"
+
+DECLARED = "DECLARED"
+KERNEL_UNCHECKED = "KERNEL_UNCHECKED"
+KERNEL_ACCEPTED = "KERNEL_ACCEPTED"
+KERNEL_REJECTED = "KERNEL_REJECTED"
+UNAVAILABLE = "UNAVAILABLE"
+STATES = (DECLARED, KERNEL_UNCHECKED, KERNEL_ACCEPTED, KERNEL_REJECTED, UNAVAILABLE)
+
+MAX_BODY_BYTES = 384 * 1024
+MAX_STATEMENT_CHARS = 32 * 1024
+MAX_ARTIFACT_CHARS = 256 * 1024
+MAX_TITLE_CHARS = 256
+MAX_BRAIN_REFS = 64
+MAX_EVENTS = 2048
+MAX_LEDGER_BYTES = 8 * 1024 * 1024
+GENESIS = "0" * 64
+LOCKED_SET = ("F1", "F4", "F7", "F11", "F12", "F18", "F19", "F22")
+ARTIFACT_FORMATS = ("LEAN4", "COQ", "ISABELLE", "TEXT")
+SOURCE_KINDS = ("OPERATOR_DECLARED", "CONJECTURE_FACTORY_CACHE")
+
+_STATE_PATH = Path(
+    os.environ.get(
+        "A11OY_FORMAL_CONJECTURE_LAB_PATH",
+        str(Path(__file__).resolve().parent / ".a11oy-state" / "formal-conjecture-lab.jsonl"),
+    )
+)
+_WRITE_LOCK = threading.RLock()
+_ID_RE = re.compile(r"^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$")
+_HEX64_RE = re.compile(r"^[0-9a-f]{64}$")
+
+
+class ContractError(ValueError):
+    """The caller supplied a malformed or hidden-field-bearing contract."""
+
+
+class StateConflict(RuntimeError):
+    """The requested transition conflicts with the recorded attempt state."""
+
+
+class LabUnavailable(RuntimeError):
+    """A required local integrity or public-key verification boundary is absent."""
+
+
+def _now() -> str:
+    return datetime.datetime.now(datetime.timezone.utc).isoformat()
+
+
+def _canonical_bytes(value: Any) -> bytes:
+    return json.dumps(
+        value, sort_keys=True, separators=(",", ":"), ensure_ascii=False, allow_nan=False
+    ).encode("utf-8")
+
+
+def _sha256(value: Any) -> str:
+    raw = value.encode("utf-8") if isinstance(value, str) else _canonical_bytes(value)
+    return hashlib.sha256(raw).hexdigest()
+
+
+def _sha3(value: Any) -> str:
+    return hashlib.sha3_256(_canonical_bytes(value)).hexdigest()
+
+
+def _mapping(value: Any, name: str) -> Mapping[str, Any]:
+    if not isinstance(value, Mapping):
+        raise ContractError(f"{name} must be one JSON object")
+    return value
+
+
+def _strict_keys(value: Mapping[str, Any], expected: set[str], name: str) -> None:
+    actual = set(value)
+    if actual != expected:
+        raise ContractError(
+            f"{name} fields must be exactly {sorted(expected)}; got {sorted(actual)}"
+        )
+
+
+def _text(value: Any, name: str, maximum: int) -> str:
+    if not isinstance(value, str) or not value.strip():
+        raise ContractError(f"{name} must be a non-empty string")
+    clean = value.strip()
+    if len(clean) > maximum:
+        raise ContractError(f"{name} exceeds {maximum} characters")
+    if "\x00" in clean:
+        raise ContractError(f"{name} contains a NUL byte")
+    return clean
+
+
+def _hex64(value: Any, name: str) -> str:
+    if not isinstance(value, str) or not _HEX64_RE.fullmatch(value):
+        raise ContractError(f"{name} must be one lowercase SHA-256 hex digest")
+    return value
+
+
+def _parse_brain_refs(value: Any) -> list[str]:
+    if not isinstance(value, list) or len(value) > MAX_BRAIN_REFS:
+        raise ContractError(f"brain_node_ids must be an array of at most {MAX_BRAIN_REFS} ids")
+    refs: list[str] = []
+    for index, item in enumerate(value):
+        ref = _text(item, f"brain_node_ids[{index}]", 256)
+        if ref in refs:
+            raise ContractError("brain_node_ids must not contain duplicates")
+        refs.append(ref)
+    return refs
+
+
+def _factory_crosscheck(conjecture_id: str, title: str, statement: str) -> dict[str, Any]:
+    """Cross-check only the on-disk factory cache; this never performs a fetch."""
+    try:
+        import szl_conjecture_factory
+
+        item = szl_conjecture_factory.load_conjecture(conjecture_id, force_refresh=False)
+    except Exception as exc:
+        raise LabUnavailable(
+            f"conjecture factory cache unavailable ({type(exc).__name__}); no source match assumed"
+        ) from exc
+    if item is None:
+        raise LabUnavailable("conjecture id is absent from the local factory cache")
+    if str(item.get("statement") or "").strip() != statement:
+        raise ContractError("statement does not exactly match the cached conjecture statement")
+    cached_title = str(item.get("title") or "").strip()
+    if cached_title and cached_title != title:
+        raise ContractError("title does not exactly match the cached conjecture title")
+    return {
+        "factory_receipt_id": item.get("receipt", {}).get("receipt_id"),
+        "factory_envelope_status": item.get("_envelope_status"),
+        "factory_statement_sha256": _sha256(statement),
+        "crosscheck": "EXACT_LOCAL_CACHE_MATCH",
+    }
+
+
+def normalize_attempt_request(request: Mapping[str, Any]) -> dict[str, Any]:
+    obj = _mapping(request, "attempt")
+    expected = {
+        "schema_version", "source_kind", "conjecture_id", "title", "statement",
+        "artifact", "artifact_format", "brain_node_ids",
+    }
+    _strict_keys(obj, expected, "attempt")
+    if obj.get("schema_version") != ATTEMPT_SCHEMA:
+        raise ContractError(f"schema_version must be {ATTEMPT_SCHEMA}")
+    source_kind = _text(obj.get("source_kind"), "source_kind", 64)
+    if source_kind not in SOURCE_KINDS:
+        raise ContractError(f"source_kind must be one of {SOURCE_KINDS}")
+    conjecture_id = _text(obj.get("conjecture_id"), "conjecture_id", 128)
+    if not _ID_RE.fullmatch(conjecture_id):
+        raise ContractError("conjecture_id contains unsupported characters")
+    title = _text(obj.get("title"), "title", MAX_TITLE_CHARS)
+    statement = _text(obj.get("statement"), "statement", MAX_STATEMENT_CHARS)
+    artifact_value = obj.get("artifact")
+    if artifact_value is None:
+        artifact = None
+    elif isinstance(artifact_value, str):
+        artifact = artifact_value
+        if len(artifact) > MAX_ARTIFACT_CHARS:
+            raise ContractError(f"artifact exceeds {MAX_ARTIFACT_CHARS} characters")
+        if "\x00" in artifact:
+            raise ContractError("artifact contains a NUL byte")
+        if not artifact.strip():
+            artifact = None
+    else:
+        raise ContractError("artifact must be a string or null")
+    artifact_format = _text(obj.get("artifact_format"), "artifact_format", 32)
+    if artifact_format not in ARTIFACT_FORMATS:
+        raise ContractError(f"artifact_format must be one of {ARTIFACT_FORMATS}")
+    if artifact is None and artifact_format != "TEXT":
+        raise ContractError("artifact_format must be TEXT when artifact is null")
+    brain_refs = _parse_brain_refs(obj.get("brain_node_ids"))
+    source_crosscheck = None
+    if source_kind == "CONJECTURE_FACTORY_CACHE":
+        source_crosscheck = _factory_crosscheck(conjecture_id, title, statement)
+    return {
+        "schema_version": ATTEMPT_SCHEMA,
+        "source_kind": source_kind,
+        "conjecture_id": conjecture_id,
+        "title": title,
+        "statement": statement,
+        "statement_sha256": _sha256(statement),
+        "artifact": artifact,
+        "artifact_sha256": _sha256(artifact) if artifact is not None else None,
+        "artifact_format": artifact_format,
+        "brain_node_ids": brain_refs,
+        "brain_refs_evidence": "DECLARED_REFERENCES_ONLY",
+        "source_crosscheck": source_crosscheck,
+    }
+
+
+def _read_events() -> list[dict[str, Any]]:
+    if not _STATE_PATH.exists():
+        return []
+    try:
+        if _STATE_PATH.stat().st_size > MAX_LEDGER_BYTES:
+            raise LabUnavailable("formal lab ledger exceeds its bounded size")
+        lines = _STATE_PATH.read_text(encoding="utf-8").splitlines()
+    except LabUnavailable:
+        raise
+    except OSError as exc:
+        raise LabUnavailable(f"formal lab ledger unreadable ({type(exc).__name__})") from exc
+    if len(lines) > MAX_EVENTS:
+        raise LabUnavailable("formal lab ledger exceeds its bounded event count")
+    events: list[dict[str, Any]] = []
+    try:
+        for line in lines:
+            if line.strip():
+                value = json.loads(line)
+                if not isinstance(value, dict):
+                    raise ValueError("ledger event is not an object")
+                events.append(value)
+    except (json.JSONDecodeError, ValueError) as exc:
+        raise LabUnavailable("formal lab ledger is structurally invalid") from exc
+    verdict = verify_event_chain(events)
+    if not verdict["valid"]:
+        raise LabUnavailable(f"formal lab ledger chain invalid at event {verdict['broken_at']}")
+    return events
+
+
+def verify_event_chain(events: list[dict[str, Any]]) -> dict[str, Any]:
+    prev = GENESIS
+    for index, event in enumerate(events):
+        try:
+            payload = event["payload"]
+            receipt = event["receipt"]["khipu"]
+            dsse = event["receipt"]["dsse"]
+            body = {key: receipt[key] for key in (
+                "organ", "ns", "seq", "action", "payload_digest", "ts", "prev"
+            )}
+            receipt_core = {**body, "digest": receipt["digest"],
+                            "signature": receipt["signature"],
+                            "chain_verified": receipt["chain_verified"]}
+            dsse_payload = base64.b64decode(dsse["payload"], validate=True)
+            ok = (
+                receipt["seq"] == index
+                and receipt["prev"] == prev
+                and receipt["payload_digest"] == _sha3(payload)
+                and receipt["digest"] == _sha3(body)
+                and receipt["signature"] == "UNSIGNED"
+                and receipt["chain_verified"] is True
+                and dsse["payloadType"] == LOCAL_PAYLOAD_TYPE
+                and dsse["signatures"] == []
+                and dsse.get("signed") is False
+                and dsse_payload == _canonical_bytes(receipt_core)
+            )
+        except (KeyError, TypeError, ValueError, binascii.Error):
+            ok = False
+        if not ok:
+            return {"valid": False, "depth": len(events), "broken_at": index}
+        prev = receipt["digest"]
+    return {"valid": True, "depth": len(events), "broken_at": None, "head": prev}
+
+
+def _unsigned_dsse(receipt: dict[str, Any]) -> dict[str, Any]:
+    return {
+        "payloadType": LOCAL_PAYLOAD_TYPE,
+        "payload": base64.b64encode(_canonical_bytes(receipt)).decode("ascii"),
+        "signatures": [],
+        "signed": False,
+        "honesty": "UNSIGNED - this local write receipt is hash-chained; no secret or signature fabricated.",
+    }
+
+
+def _append_event(ns: str, action: str, payload: dict[str, Any]) -> dict[str, Any]:
+    with _WRITE_LOCK:
+        events = _read_events()
+        if len(events) >= MAX_EVENTS:
+            raise LabUnavailable("formal lab event bound reached; archival is required")
+        prev = events[-1]["receipt"]["khipu"]["digest"] if events else GENESIS
+        body = {
+            "organ": "formal-conjecture-lab",
+            "ns": ns,
+            "seq": len(events),
+            "action": action,
+            "payload_digest": _sha3(payload),
+            "ts": datetime.datetime.now(datetime.timezone.utc).timestamp(),
+            "prev": prev,
+        }
+        receipt = {
+            **body,
+            "digest": _sha3(body),
+            "signature": "UNSIGNED",
+            "chain_verified": True,
+        }
+        event = {"payload": payload, "receipt": {"khipu": receipt, "dsse": _unsigned_dsse(receipt)}}
+        encoded = "\n".join(
+            json.dumps(row, sort_keys=True, separators=(",", ":"), ensure_ascii=False)
+            for row in [*events, event]
+        ) + "\n"
+        if len(encoded.encode("utf-8")) > MAX_LEDGER_BYTES:
+            raise LabUnavailable("formal lab ledger byte bound reached; archival is required")
+        try:
+            _STATE_PATH.parent.mkdir(parents=True, exist_ok=True)
+            tmp = _STATE_PATH.with_suffix(_STATE_PATH.suffix + ".tmp")
+            with tmp.open("w", encoding="utf-8", newline="\n") as handle:
+                handle.write(encoded)
+                handle.flush()
+                os.fsync(handle.fileno())
+            os.replace(tmp, _STATE_PATH)
+        except OSError as exc:
+            raise LabUnavailable(f"formal lab ledger write failed ({type(exc).__name__})") from exc
+        return event
+
+
+def _fold_attempts(events: list[dict[str, Any]]) -> dict[str, dict[str, Any]]:
+    attempts: dict[str, dict[str, Any]] = {}
+    for event in events:
+        payload = event["payload"]
+        if event["receipt"]["khipu"]["action"] == "formal.attempt.declare":
+            attempt = dict(payload["attempt"])
+            attempt["write_receipt"] = event["receipt"]
+            attempts[attempt["attempt_id"]] = attempt
+        elif event["receipt"]["khipu"]["action"] == "formal.kernel-receipt.ingest":
+            attempt_id = payload["attempt_id"]
+            if attempt_id in attempts:
+                attempts[attempt_id]["state"] = payload["derived_state"]
+                attempts[attempt_id]["kernel_result"] = payload["kernel_result"]
+                attempts[attempt_id]["kernel_receipt_verification"] = payload["verification"]
+                attempts[attempt_id]["write_receipt"] = event["receipt"]
+    return attempts
+
+
+def list_attempts(limit: int = 100) -> dict[str, Any]:
+    if not isinstance(limit, int) or not 1 <= limit <= 200:
+        raise ContractError("limit must be an integer from 1 through 200")
+    events = _read_events()
+    attempts = list(_fold_attempts(events).values())
+    attempts.sort(key=lambda row: (row.get("declared_at", ""), row["attempt_id"]), reverse=True)
+    chain = verify_event_chain(events)
+    return {
+        "service": "formal-conjecture-lab",
+        "attempts": attempts[:limit],
+        "count": len(attempts),
+        "ledger": chain,
+        "read_receipt_minted": False,
+        "proof_promotion": "DISABLED",
+    }
+
+
+def get_attempt(attempt_id: str) -> dict[str, Any] | None:
+    if not isinstance(attempt_id, str) or not _ID_RE.fullmatch(attempt_id):
+        raise ContractError("attempt_id is malformed")
+    return _fold_attempts(_read_events()).get(attempt_id)
+
+
+def declare_attempt(request: Mapping[str, Any], ns: str = "a11oy") -> dict[str, Any]:
+    normalized = normalize_attempt_request(request)
+    identity = {
+        "conjecture_id": normalized["conjecture_id"],
+        "statement_sha256": normalized["statement_sha256"],
+        "artifact_sha256": normalized["artifact_sha256"],
+    }
+    attempt_id = "fcl-" + _sha256(identity)[:24]
+    with _WRITE_LOCK:
+        prior = get_attempt(attempt_id)
+        if prior is not None:
+            return {"created": False, "attempt": prior, "write_receipt_minted": False}
+        state = KERNEL_UNCHECKED if normalized["artifact"] is not None else DECLARED
+        attempt = {
+            **normalized,
+            "attempt_id": attempt_id,
+            "state": state,
+            "declared_at": _now(),
+            "kernel_result": None,
+            "kernel_receipt_verification": None,
+            "automatic_proof_promotion": False,
+            "proof_status": "NOT_PROMOTED",
+            "publication_claim_authorized": False,
+            "locked_proven_count": len(LOCKED_SET),
+            "locked_set": list(LOCKED_SET),
+            "lambda_uniqueness": "Conjecture 1",
+            "khipu_bft_safety": "Conjecture 2",
+        }
+        event = _append_event(ns, "formal.attempt.declare", {"attempt": attempt})
+        stored = dict(attempt)
+        stored["write_receipt"] = event["receipt"]
+        return {"created": True, "attempt": stored, "write_receipt_minted": True}
+
+
+def _kernel_verifier_status() -> dict[str, Any]:
+    try:
+        import cryptography  # noqa: F401
+        import szl_dsse
+
+        fingerprint = szl_dsse.public_key_fingerprint()
+        return {
+            "available": True,
+            "state": KERNEL_UNCHECKED,
+            "trust_anchor": "SZL_COSIGN_PUBLIC_KEY_EMBEDDED",
+            "public_key_fingerprint_sha256": fingerprint,
+        }
+    except Exception as exc:
+        return {
+            "available": False,
+            "state": UNAVAILABLE,
+            "reason": f"public-key receipt verifier unavailable ({type(exc).__name__})",
+        }
+
+
+def _decode_verified_kernel_receipt(envelope: Mapping[str, Any], attempt: dict[str, Any]) -> tuple[dict[str, Any], dict[str, Any]]:
+    verifier = _kernel_verifier_status()
+    if not verifier["available"]:
+        raise LabUnavailable(verifier["reason"])
+    env = _mapping(envelope, "dsse_envelope")
+    allowed = {
+        "payloadType", "payload", "signatures", "_dsse", "_pae_sha256", "_signed_at",
+        "honesty", "signed", "verify_key_url",
+    }
+    required = {"payloadType", "payload", "signatures"}
+    if not required <= set(env) or not set(env) <= allowed:
+        raise ContractError("dsse_envelope fields are incomplete or unsupported")
+    if env.get("payloadType") != KERNEL_PAYLOAD_TYPE:
+        raise ContractError(f"payloadType must be {KERNEL_PAYLOAD_TYPE}")
+    signatures = env.get("signatures")
+    if not isinstance(signatures, list) or len(signatures) != 1:
+        raise ContractError("one SZL cosign signature is required")
+    signature = _mapping(signatures[0], "signature")
+    _strict_keys(signature, {"sig", "keyid"}, "signature")
+    if signature.get("keyid") != "szlholdings-cosign":
+        raise ContractError("signature keyid is not the configured SZL cosign key")
+    try:
+        raw = base64.b64decode(str(env.get("payload")), validate=True)
+    except (ValueError, binascii.Error) as exc:
+        raise ContractError("payload is not strict base64") from exc
+    if len(raw) > MAX_BODY_BYTES:
+        raise ContractError("kernel receipt payload exceeds the bounded body size")
+    try:
+        payload = json.loads(raw.decode("utf-8"))
+    except (UnicodeDecodeError, json.JSONDecodeError) as exc:
+        raise ContractError("kernel receipt payload is not one UTF-8 JSON object") from exc
+    payload = dict(_mapping(payload, "kernel receipt payload"))
+    fields = {
+        "schema_version", "attempt_id", "conjecture_id", "statement_sha256",
+        "artifact_sha256", "checker_id", "checker_version", "kernel_commit_sha256",
+        "exit_code", "sorry_count", "unsafe_declaration_count", "compiler_output_sha256",
+        "checked_at", "claimed_verdict",
+    }
+    _strict_keys(payload, fields, "kernel receipt payload")
+    if payload.get("schema_version") != KERNEL_SCHEMA:
+        raise ContractError(f"kernel schema_version must be {KERNEL_SCHEMA}")
+    if payload.get("attempt_id") != attempt["attempt_id"]:
+        raise ContractError("kernel receipt attempt_id does not match the stored attempt")
+    if payload.get("conjecture_id") != attempt["conjecture_id"]:
+        raise ContractError("kernel receipt conjecture_id does not match the stored attempt")
+    if payload.get("statement_sha256") != attempt["statement_sha256"]:
+        raise ContractError("kernel receipt statement hash does not match the stored statement")
+    if payload.get("artifact_sha256") != attempt["artifact_sha256"]:
+        raise ContractError("kernel receipt artifact hash does not match the stored artifact")
+    if payload.get("checker_id") != "LEAN4":
+        raise ContractError("checker_id must be LEAN4")
+    _text(payload.get("checker_version"), "checker_version", 128)
+    _hex64(payload.get("kernel_commit_sha256"), "kernel_commit_sha256")
+    _hex64(payload.get("compiler_output_sha256"), "compiler_output_sha256")
+    for name in ("exit_code", "sorry_count", "unsafe_declaration_count"):
+        value = payload.get(name)
+        if not isinstance(value, int) or isinstance(value, bool) or value < 0 or value > 1_000_000:
+            raise ContractError(f"{name} must be a bounded non-negative integer")
+    _text(payload.get("checked_at"), "checked_at", 96)
+    claimed = _text(payload.get("claimed_verdict"), "claimed_verdict", 32)
+    if claimed not in ("ACCEPTED", "REJECTED"):
+        raise ContractError("claimed_verdict must be ACCEPTED or REJECTED")
+    import szl_dsse
+
+    verification = szl_dsse.verify_envelope(dict(env))
+    if verification.get("verified") is not True:
+        raise ContractError(
+            "kernel DSSE signature did not verify: " + str(verification.get("reason") or "unknown")[:160]
+        )
+    if verification.get("keyid_expected") != "szlholdings-cosign":
+        raise ContractError("kernel receipt verification used an unexpected trust anchor")
+    return payload, verification
+
+
+def ingest_kernel_receipt(attempt_id: str, request: Mapping[str, Any], ns: str = "a11oy") -> dict[str, Any]:
+    obj = _mapping(request, "kernel receipt request")
+    _strict_keys(obj, {"schema_version", "dsse_envelope"}, "kernel receipt request")
+    if obj.get("schema_version") != KERNEL_SCHEMA:
+        raise ContractError(f"schema_version must be {KERNEL_SCHEMA}")
+    with _WRITE_LOCK:
+        attempt = get_attempt(attempt_id)
+        if attempt is None:
+            raise StateConflict("attempt does not exist")
+        if attempt.get("artifact_sha256") is None:
+            raise StateConflict("attempt has no formal artifact to check")
+        payload, verification = _decode_verified_kernel_receipt(obj.get("dsse_envelope"), attempt)
+        derived = (
+            KERNEL_ACCEPTED
+            if payload["exit_code"] == 0
+            and payload["sorry_count"] == 0
+            and payload["unsafe_declaration_count"] == 0
+            else KERNEL_REJECTED
+        )
+        envelope_digest = _sha256(dict(_mapping(obj.get("dsse_envelope"), "dsse_envelope")))
+        prior_result = attempt.get("kernel_result")
+        if attempt["state"] in (KERNEL_ACCEPTED, KERNEL_REJECTED):
+            if prior_result and prior_result.get("envelope_sha256") == envelope_digest:
+                return {"updated": False, "attempt": attempt, "write_receipt_minted": False}
+            raise StateConflict("attempt already has a different terminal kernel receipt")
+        if attempt["state"] != KERNEL_UNCHECKED:
+            raise StateConflict("attempt is not ready for a kernel receipt")
+        kernel_result = {
+            "derived_state": derived,
+            "derived_from": "SIGNED_EXIT_CODE_AND_SIGNED_SORRY_UNSAFE_COUNTS",
+            "client_claimed_verdict": payload["claimed_verdict"],
+            "client_label_trusted": False,
+            "label_conflict": payload["claimed_verdict"] != (
+                "ACCEPTED" if derived == KERNEL_ACCEPTED else "REJECTED"
+            ),
+            "checker_id": payload["checker_id"],
+            "checker_version": payload["checker_version"],
+            "kernel_commit_sha256": payload["kernel_commit_sha256"],
+            "exit_code": payload["exit_code"],
+            "sorry_count": payload["sorry_count"],
+            "unsafe_declaration_count": payload["unsafe_declaration_count"],
+            "compiler_output_sha256": payload["compiler_output_sha256"],
+            "checked_at": payload["checked_at"],
+            "envelope_sha256": envelope_digest,
+            "proof_promoted": False,
+            "publication_claim_authorized": False,
+            "note": "Kernel acceptance is recorded evidence only; it is not automatic proof promotion.",
+        }
+        event_payload = {
+            "attempt_id": attempt_id,
+            "derived_state": derived,
+            "kernel_result": kernel_result,
+            "verification": {
+                "verified": True,
+                "keyid_expected": verification.get("keyid_expected"),
+                "pub_fingerprint_sha256": verification.get("pub_fingerprint_sha256"),
+                "pae_sha256": verification.get("pae_sha256"),
+            },
+        }
+        event = _append_event(ns, "formal.kernel-receipt.ingest", event_payload)
+        updated = get_attempt(attempt_id)
+        if updated is None:
+            raise LabUnavailable("attempt disappeared after a successful ledger write")
+        updated["write_receipt"] = event["receipt"]
+        return {"updated": True, "attempt": updated, "write_receipt_minted": True}
+
+
+def status() -> dict[str, Any]:
+    verifier = _kernel_verifier_status()
+    try:
+        bundle = list_attempts(limit=200)
+        attempts = bundle["attempts"]
+        ledger = bundle["ledger"]
+        storage_state = "READY"
+        reason = None
+    except LabUnavailable as exc:
+        attempts = []
+        ledger = {"valid": False, "depth": 0, "broken_at": None}
+        storage_state = UNAVAILABLE
+        reason = str(exc)
+    counts = {state: 0 for state in STATES}
+    for attempt in attempts:
+        counts[attempt["state"]] = counts.get(attempt["state"], 0) + 1
+    return {
+        "service": "formal-conjecture-lab",
+        "ready": storage_state == "READY",
+        "storage_state": storage_state,
+        "reason": reason,
+        "states": list(STATES),
+        "attempt_state_counts": counts,
+        "ledger": ledger,
+        "kernel_execution": {
+            "state": UNAVAILABLE,
+            "reason": "no in-process prover execution path; arbitrary commands and network are disabled",
+        },
+        "kernel_receipt_verification": verifier,
+        "kernel_receipt_contract": {
+            "schema_version": KERNEL_SCHEMA,
+            "payload_type": KERNEL_PAYLOAD_TYPE,
+            "checker_id": "LEAN4",
+            "signature_keyid": "szlholdings-cosign",
+            "exact_bindings": [
+                "attempt_id", "conjecture_id", "statement_sha256", "artifact_sha256"
+            ],
+            "derived_acceptance": (
+                "verified DSSE AND exit_code == 0 AND sorry_count == 0 AND "
+                "unsafe_declaration_count == 0"
+            ),
+            "client_claimed_verdict_controls_state": False,
+        },
+        "endpoints": {
+            "status": "GET /api/a11oy/v1/formal-conjecture-lab/status",
+            "list": "GET /api/a11oy/v1/formal-conjecture-lab/attempts?limit=100",
+            "get": "GET /api/a11oy/v1/formal-conjecture-lab/attempts/{attempt_id}",
+            "declare": "POST /api/a11oy/v1/formal-conjecture-lab/attempts",
+            "ingest_kernel_receipt": (
+                "POST /api/a11oy/v1/formal-conjecture-lab/attempts/{attempt_id}/kernel-receipts"
+            ),
+        },
+        "controls": {
+            "network_calls": "DISABLED",
+            "command_execution": "DISABLED",
+            "arbitrary_code": "DISABLED",
+            "secret_reads": "DISABLED",
+            "strict_contracts": True,
+            "body_limit_bytes": MAX_BODY_BYTES,
+            "max_events": MAX_EVENTS,
+            "max_ledger_bytes": MAX_LEDGER_BYTES,
+        },
+        "proof_policy": {
+            "automatic_promotion": False,
+            "kernel_accepted_means_proved": False,
+            "publication_claim_authorized": False,
+            "locked_proven_count": len(LOCKED_SET),
+            "locked_set": list(LOCKED_SET),
+            "lambda_uniqueness": "Conjecture 1",
+            "khipu_bft_safety": "Conjecture 2",
+        },
+        "receipt_policy": "RECEIPT-ON-WRITE-NOT-ON-READ",
+    }
+
+
+async def _read_body(request: Any) -> dict[str, Any]:
+    content_length = request.headers.get("content-length")
+    if content_length is not None:
+        try:
+            declared = int(content_length)
+        except ValueError as exc:
+            raise ContractError("content-length must be a non-negative integer") from exc
+        if declared < 0:
+            raise ContractError("content-length must be a non-negative integer")
+        if declared > MAX_BODY_BYTES:
+            raise ContractError(f"request body exceeds {MAX_BODY_BYTES} bytes")
+    data = bytearray()
+    async for chunk in request.stream():
+        if len(data) + len(chunk) > MAX_BODY_BYTES:
+            raise ContractError(f"request body exceeds {MAX_BODY_BYTES} bytes")
+        data.extend(chunk)
+    try:
+        value = json.loads(bytes(data).decode("utf-8"))
+    except (UnicodeDecodeError, json.JSONDecodeError) as exc:
+        raise ContractError("request body must be one UTF-8 JSON object") from exc
+    return dict(_mapping(value, "request body"))
+
+
+def register(app: Any, ns: str = "a11oy") -> dict[str, Any]:
+    """Register bounded read/write routes before both application catch-alls."""
+    from fastapi import Request
+    from fastapi.responses import JSONResponse
+
+    base = f"/api/{ns}/v1/formal-conjecture-lab"
+
+    @app.get(base + "/status")
+    async def _formal_lab_status() -> JSONResponse:
+        return JSONResponse(status())
+
+    @app.get(base + "/attempts")
+    async def _formal_lab_attempts(limit: int = 100) -> JSONResponse:
+        try:
+            return JSONResponse(list_attempts(limit))
+        except ContractError as exc:
+            return JSONResponse({"state": UNAVAILABLE, "error": str(exc)}, status_code=422)
+        except LabUnavailable as exc:
+            return JSONResponse({"state": UNAVAILABLE, "error": str(exc)}, status_code=503)
+
+    @app.get(base + "/attempts/{attempt_id}")
+    async def _formal_lab_attempt(attempt_id: str) -> JSONResponse:
+        try:
+            attempt = get_attempt(attempt_id)
+        except ContractError as exc:
+            return JSONResponse({"state": UNAVAILABLE, "error": str(exc)}, status_code=422)
+        except LabUnavailable as exc:
+            return JSONResponse({"state": UNAVAILABLE, "error": str(exc)}, status_code=503)
+        if attempt is None:
+            return JSONResponse({"state": UNAVAILABLE, "error": "attempt not found"}, status_code=404)
+        return JSONResponse({"attempt": attempt, "read_receipt_minted": False})
+
+    @app.post(base + "/attempts")
+    async def _formal_lab_declare(request: Request) -> JSONResponse:
+        try:
+            result = declare_attempt(await _read_body(request), ns)
+            return JSONResponse(result, status_code=201 if result["created"] else 200)
+        except ContractError as exc:
+            code = 413 if "body exceeds" in str(exc) else 422
+            return JSONResponse({"state": UNAVAILABLE, "error": str(exc)}, status_code=code)
+        except LabUnavailable as exc:
+            return JSONResponse({"state": UNAVAILABLE, "error": str(exc)}, status_code=503)
+
+    @app.post(base + "/attempts/{attempt_id}/kernel-receipts")
+    async def _formal_lab_kernel_receipt(attempt_id: str, request: Request) -> JSONResponse:
+        try:
+            return JSONResponse(ingest_kernel_receipt(attempt_id, await _read_body(request), ns))
+        except ContractError as exc:
+            code = 413 if "body exceeds" in str(exc) else 422
+            return JSONResponse({"state": UNAVAILABLE, "error": str(exc)}, status_code=code)
+        except StateConflict as exc:
+            return JSONResponse({"state": UNAVAILABLE, "error": str(exc)}, status_code=409)
+        except LabUnavailable as exc:
+            return JSONResponse({"state": UNAVAILABLE, "error": str(exc)}, status_code=503)
+
+    return {
+        "registered": True,
+        "base": base,
+        "kernel_execution": UNAVAILABLE,
+        "proof_promotion": "DISABLED",
+    }

szl_governed_infer.py

@@ -65,6 +65,8 @@ LABEL_MEASURED = "MEASURED"
 LABEL_BOUNDED = "MEASURED_SHARED_BOUNDED"
 LABEL_MODELED = "MODELED"
 LABEL_UNAVAILABLE = "UNAVAILABLE"
+RECEIPT_SCHEMA_V1 = "szl.govern.brain-infer/v1"
+RECEIPT_SCHEMA_V2 = "szl.govern.inference/v2"
 
 # Grounding subgraph size (k) for the PPR retrieval.
 GROUND_K = 12
@@ -286,7 +288,8 @@ def _prev_hash():
 
 
 def _make_receipt(query, subgraph_ids, answer_digest, energy, tokens, model,
-                  prev_hash):
+                  prev_hash, *, answer_available=False,
+                  receipt_source="brain-infer", base_url=""):
     """Build a DSSE-style SHA-256 hash-chained receipt over the governed turn.
 
     tokens_per_joule is populated ONLY when BOTH a real output-token count and a
@@ -302,14 +305,22 @@ def _make_receipt(query, subgraph_ids, answer_digest, energy, tokens, model,
         # tokens_per_joule inherits the joule measurement's honest label.
         tpj_label = energy_label
     body = {
-        "schema": "szl.govern.brain-infer/v1",
+        "schema": RECEIPT_SCHEMA_V2,
         "chain_alg": "sha256",
+        "receipt_source": str(receipt_source or "unknown"),
         "q": query,
         "query_digest": _sha(query),
         "subgraph_ids": list(subgraph_ids),
         "subgraph_size": len(subgraph_ids),
         "answer_digest": answer_digest,
         "model": model,
+        "answer_available": bool(answer_available),
+        # A durable receipt is evidence of successful inference only when the
+        # provider returned real non-empty text and named the model that ran.
+        # Failed attempts still receive an attempt receipt, but never set this.
+        "inference_receipted": bool(answer_available and answer_digest
+                                      and model),
+        "base_url_sha256": _sha(base_url) if base_url else None,
         "joules": joules,
         "energy_label": energy_label,
         "tokens": int(tokens or 0),
@@ -325,7 +336,7 @@ def _make_receipt(query, subgraph_ids, answer_digest, energy, tokens, model,
 
 def _receipt_hash(body):
     """Canonical SHA-256 over the load-bearing receipt fields (chain link)."""
-    return _sha(
+    parts = [
         body.get("prev_hash", ""),
         body.get("query_digest", ""),
         body.get("answer_digest", ""),
@@ -335,7 +346,84 @@ def _receipt_hash(body):
         str(body.get("model")),
         body.get("node", ""),
         body.get("ts", ""),
-    )
+    ]
+    # Preserve verification of existing v1 receipts while binding every new
+    # inference-state field into the v2 hash.
+    if body.get("schema") == RECEIPT_SCHEMA_V2:
+        parts.extend([
+            body.get("receipt_source", ""),
+            str(bool(body.get("answer_available"))),
+            str(bool(body.get("inference_receipted"))),
+            body.get("base_url_sha256") or "",
+        ])
+    return _sha(*parts)
+
+
+def record_provider_generation(query, text, model, *, tokens=0, base_url=""):
+    """Persist one successful provider generation as a durable v2 receipt.
+
+    This is called only from POST/write paths after a provider returned real,
+    non-empty text.  Reachability, configuration, and a routing decision are not
+    enough.  The append is fsync'd and immediately replay-verified; failure is
+    returned honestly and never upgraded to receipted inference.
+    """
+    query = (query or "").strip()
+    text = (text or "").strip()
+    model = (model or "").strip()
+    if not query or not text or not model:
+        return {"ok": False, "inference_receipted": False,
+                "reason": "query, non-empty provider text, and model are required"}
+    try:
+        token_count = max(0, int(tokens or 0))
+    except (TypeError, ValueError):
+        token_count = 0
+    energy = {"joules": None, "label": LABEL_UNAVAILABLE,
+              "reason": "provider-route receipt did not bracket an NVML meter delta"}
+    with _LOCK:
+        prev = _prev_hash()
+        receipt = _make_receipt(
+            query, [], _sha(text), energy, token_count, model, prev,
+            answer_available=True, receipt_source="llm-route", base_url=base_url)
+        _append(receipt)
+        chain = _read_chain()
+        persisted = bool(chain and chain[-1].get("receipt_hash") == receipt["receipt_hash"])
+        verified = persisted and _verify_entry(chain[-1], prev)
+    return {
+        "ok": bool(verified),
+        "inference_receipted": bool(verified),
+        "receipt_hash": receipt["receipt_hash"] if verified else None,
+        "schema": receipt["schema"],
+        "reason": ("durable inference receipt appended and replay-verified"
+                   if verified else "receipt append could not be replay-verified"),
+    }
+
+
+def inference_receipt_status(model=""):
+    """Read-only successful-inference receipt status; never emits a receipt."""
+    wanted = (model or "").strip()
+    chain = _read_chain()
+    prev = ""
+    broken = []
+    successful = []
+    for idx, entry in enumerate(chain):
+        valid = _verify_entry(entry, prev)
+        if not valid:
+            broken.append(idx)
+        prev = entry.get("receipt_hash", prev)
+        entry_model = str(entry.get("model") or "")
+        model_match = (not wanted or entry_model == wanted
+                       or entry_model.endswith(":" + wanted))
+        if valid and entry.get("inference_receipted") is True and model_match:
+            successful.append(entry)
+    latest = successful[-1] if successful else None
+    return {
+        "inference_receipted": bool(successful and not broken),
+        "successful_receipt_count": len(successful),
+        "total_receipt_count": len(chain),
+        "chain_ok": not broken,
+        "latest_receipt_hash": latest.get("receipt_hash") if latest else None,
+        "latest_model": latest.get("model") if latest else None,
+    }
 
 
 def _append(receipt):
@@ -406,7 +494,12 @@ def govern_infer(query, ns="a11oy"):
             prev = _prev_hash()
             receipt = _make_receipt(query, subgraph_ids, answer_digest, energy,
                                     answer.get("tokens", 0), answer.get("model"),
-                                    prev)
+                                    prev,
+                                    answer_available=bool(answer.get("available")
+                                                          and ans_text),
+                                    receipt_source="brain-infer",
+                                    base_url=_local_llm_url()
+                                             or _sovereign_gateway())
             _append(receipt)
         dsse = _maybe_dsse(receipt)
 
@@ -476,6 +569,9 @@ def list_receipts(limit=50):
         "q": r.get("q"),
         "subgraph_size": r.get("subgraph_size"),
         "model": r.get("model"),
+        "receipt_source": r.get("receipt_source", "brain-infer"),
+        "answer_available": bool(r.get("answer_available")),
+        "inference_receipted": bool(r.get("inference_receipted")),
         "joules": r.get("joules"),
         "energy_label": r.get("energy_label"),
         "tokens": r.get("tokens"),

szl_gpu_quant.py

@@ -25,10 +25,11 @@ The VRAM-resident, three-layer quant pipeline validated in GPU_QUANT_RESEARCH.md
 HONESTY SPINE (doctrine v11 — the non-negotiable part of this build):
   * EVERY output is a SAMPLE_SIGNAL: synthetic / illustrative returns, NOT a live feed,
     NO_BACKTEST_VALIDATED. We have NOT run a backtest. We do NOT claim live-trading.
-  * The compute path here is the HONEST CPU FALLBACK (pure-Python linear algebra +
+  * The compute path here is the HONEST CPU REFERENCE (pure-Python linear algebra +
     a pure-Python Vietoris-Rips β0/β1 over a thresholded distance graph). The GPU path
-    (cuML LedoitWolf + cuPy eigh + giotto-tda / Ripser++) is labeled ROADMAP — it flips
-    to MEASURED only on a sovereign GPU with those libs present (live gpu_reachable probe).
+    (cuML LedoitWolf + cuPy eigh + giotto-tda / Ripser++) is labeled ROADMAP. GPU
+    reachability and dependency imports are readiness only; MEASURED requires a distinct
+    accelerated path plus device/kernel/timing execution evidence.
   * Every receipt is SIGNED via szl_dsse.sign_payload (REAL ECDSA when the cosign key
     is present in the runtime; an explicit UNSIGNED honesty marker otherwise — never a
     fabricated signature). The label SAMPLE_SIGNAL | NOT_LIVE | NO_BACKTEST_VALIDATED is
@@ -105,8 +106,8 @@ def _np_present() -> bool:
 
 def _sovereign_state() -> dict:
     """LIVE sovereign-inference posture (delegated to the orchestrator — the authority).
-    Honest default not-sovereign on any failure. The GPU quant path may claim MEASURED
-    ONLY when gpu_reachable AND the cuML/cuPy/giotto stack is present."""
+    Honest default not-sovereign on any failure. This state is reachability evidence,
+    never proof that the finance quant pipeline executed on a GPU."""
     try:
         import a11oy_code_orchestrator as _orch  # type: ignore
         st = _orch._sovereign_inference_state()
@@ -127,23 +128,33 @@ def _gpu_reachable(state: dict | None = None) -> bool:
 def _compute_backend() -> dict:
     """Which compute path actually ran, honestly labeled.
 
-    GPU-MEASURED  -> a sovereign GPU is reachable AND cuML+cuPy+giotto are importable.
-    CPU-SAMPLE    -> the honest pure-Python fallback (what runs in this Space today).
+    The numerical layer implementations in this module are currently the pure-Python
+    reference path.  Dependency availability is *readiness*, not execution evidence:
+    merely finding a sovereign GPU and importing cuML/cuPy must never relabel CPU
+    results as GPU-MEASURED.  When an accelerated implementation is added it must
+    supply execution evidence (device, kernel/implementation id, and timing receipt)
+    before this contract can emit a MEASURED GPU label.
     """
     libs = _gpu_libs_present()
     reachable = _gpu_reachable()
-    gpu_path = reachable and libs.get("cuml") and libs.get("cupy")
+    acceleration_dependencies_ready = bool(
+        reachable and libs.get("cuml") and libs.get("cupy")
+    )
     return {
-        "backend": "GPU (cuML/cuPy)" if gpu_path else "CPU pure-Python fallback",
-        "label": "MEASURED" if gpu_path else "SAMPLE",
+        "backend": "CPU pure-Python reference",
+        "compute_path": "CPU_REFERENCE",
+        "label": "SAMPLE",
         "gpu_reachable": reachable,
         "gpu_libs_present": libs,
+        "acceleration_dependencies_ready": acceleration_dependencies_ready,
+        "acceleration_implementation_wired": False,
+        "execution_evidence": None,
         "honest_note": (
-            "Sovereign GPU reachable and RAPIDS stack present — Layers 1/3 run in VRAM (cuML LedoitWolf + cuPy eigh)."
-            if gpu_path else
-            "Honest CPU fallback: pure-Python linear algebra (Jacobi eigensolver) + pure-Python "
-            "Vietoris-Rips β0/β1. The cuML/cuPy/giotto-tda/Ripser++ GPU path is ROADMAP — it flips "
-            "to MEASURED only on a sovereign GPU with those libraries (live gpu_reachable probe)."),
+            "Pure-Python reference implementation executed: Jacobi eigensolver plus "
+            "pure-Python Vietoris-Rips β0/β1. GPU reachability and importable RAPIDS "
+            "dependencies indicate readiness only. The accelerated cuML/cuPy/Ripser++ "
+            "implementation is ROADMAP and cannot be labeled MEASURED until a distinct "
+            "device-executed path emits execution evidence."),
     }
 
 
@@ -757,7 +768,8 @@ def tiers_panel() -> dict:
             "config": "vLLM --tensor-parallel-size 2 shards ONE larger model across a-11-oy.com GPU + RTX 4000",
             "fits": "e.g. Qwen3-32B comfortably, or a quantized Nemotron-3-Super across combined VRAM",
             "gpus": [per_gpu("a-11-oy.com GPU"), per_gpu("NVIDIA RTX 4000 (Ada, ~20GB)")],
-            "label": "MEASURED" if reachable else "ROADMAP",
+            "label": "LIVE_REACHABLE" if reachable else "ROADMAP",
+            "execution_evidence": None,
         },
         {
             "tier": "sovereign-local · ROLE-SPLIT (recommended for agent loops)",
@@ -768,7 +780,8 @@ def tiers_panel() -> dict:
             "fits": "keeps the main GPU from stalling on inline review/draft — best fit for our agent+Auto-Review arch",
             "gpus": [per_gpu("a-11-oy.com GPU · primary model"),
                      per_gpu("RTX 4000 · classifier+draft+embeddings")],
-            "label": "MEASURED" if reachable else "ROADMAP",
+            "label": "LIVE_REACHABLE" if reachable else "ROADMAP",
+            "execution_evidence": None,
         },
         {
             "tier": "cloud · NVIDIA NIM (Nemotron 3 Ultra) — frontier/hard tier",

szl_llm_registry.py

@@ -50,13 +50,14 @@ import math
 import os
 import threading
 import time
-import urllib.request as _urllib_request
 from datetime import datetime, timezone
 from typing import Any
 
 from fastapi import FastAPI, Request
 from fastapi.responses import JSONResponse
 
+from szl_provider_http import http_json as _bounded_http_json
+
 DOCTRINE = "v11"
 _KERNEL = "c7c0ba17"
 _LAMBDA_FLOOR = 0.90
@@ -75,6 +76,17 @@ _SOVEREIGN_PROVENANCE = "SZL sovereign (Ollama, local, Doctrine-v11 system promp
 # the node answers this request; otherwise UNAVAILABLE (never SIMULATED/fabricated).
 _LABEL_LIVE = "LIVE"
 _LABEL_UNAVAILABLE = "UNAVAILABLE"
+_STATE_OFFLINE_UNTIL_KEYED = "OFFLINE_UNTIL_KEYED"
+_STATE_CONFIGURED_UNVERIFIED = "CONFIGURED_UNVERIFIED"
+_STATE_UNAVAILABLE = "UNAVAILABLE"
+_STATE_REACHABLE_MODEL_MISMATCH = "REACHABLE_MODEL_MISMATCH"
+_STATE_REACHABLE_UNRECEIPTED = "REACHABLE_UNRECEIPTED"
+_STATE_LIVE_RECEIPTED = "LIVE_RECEIPTED"
+_SOVEREIGN_MODEL_ALIASES = (
+    _SOVEREIGN_MODEL_TAG,
+    "szl-sovereign:latest",
+    "szl1:latest",
+)
 
 # ─────────────────────────────────────────────────────────────────────────────
 # THE CANONICAL LLM ROSTER — a11oy is the hub; every model lives here.
@@ -413,6 +425,11 @@ _SOVEREIGN_ENV = "SZL_LOCAL_LLM_URL"
 # SZL_LOCAL_LLM_URL). Never fabricates reachability — a live call still proves it.
 # See box-scripts/litellm_config.yaml + research/SOVEREIGN_MESH_RUNBOOK.md.
 _GATEWAY_ENV = "A11OY_SOVEREIGN_GATEWAY_URL"
+# Code/Forge uses these names for the endpoint that actually serves turns.  The
+# global health rollup is backed by this registry, so it must resolve the same
+# endpoint instead of silently probing the legacy localhost default.  Ordered
+# exactly as a11oy_code_orchestrator._sovereign_base_url().
+_CODE_SOVEREIGN_ENVS = ("A11OY_BRAIN_URL", "A11OY_MODEL_BASE_URL")
 # Optional bearer for a bearer-protected gateway (LiteLLM master_key). The SECRET
 # is NEVER logged or returned — only attached as an Authorization header on the
 # guarded outbound call. Falls back to SZL_LOCAL_LLM_KEY. Unset => no header.
@@ -443,27 +460,38 @@ _SOVEREIGN_DEFAULT_URL = "http://localhost:11434/v1"
 def _sovereign_base() -> str:
     """Resolve the sovereign base URL from env.
 
-    Prefers the unified mesh gateway (A11OY_SOVEREIGN_GATEWAY_URL, the LiteLLM
-    load-balancer over both GPU boxes: omen + betterwithage). Falls back to the
-    single-node SZL_LOCAL_LLM_URL, then to the OpenAI-compatible Tower endpoint
-    (http://localhost:11434/v1) when neither is set, so the backend always has a
-    concrete target to reachability-probe. The probe/generate paths normalise a
+    Prefers the Code/Forge serving endpoint (A11OY_BRAIN_URL then
+    A11OY_MODEL_BASE_URL) so the global health rollup observes the same endpoint
+    that actually serves turns. Falls back to the unified mesh gateway
+    (A11OY_SOVEREIGN_GATEWAY_URL), the legacy single-node SZL_LOCAL_LLM_URL, then
+    the OpenAI-compatible Tower endpoint (http://localhost:11434/v1). The
+    probe/generate paths normalise a
     trailing `/v1` back to the Ollama root for native /api calls, so either form
     (`.../11434` or `.../11434/v1`) works. This is a guarded preference only — it
     never asserts the endpoint is reachable; a live call still proves it.
     """
-    gw = (os.environ.get(_GATEWAY_ENV, "") or "").strip()
-    if gw:
-        return gw.rstrip("/")
-    val = (os.environ.get(_SOVEREIGN_ENV, "") or "").strip().rstrip("/")
-    return val or _SOVEREIGN_DEFAULT_URL
+    for env_name in (*_CODE_SOVEREIGN_ENVS, _GATEWAY_ENV, _SOVEREIGN_ENV):
+        val = (os.environ.get(env_name, "") or "").strip()
+        if val:
+            return val.rstrip("/")
+    return _SOVEREIGN_DEFAULT_URL
+
+
+def _sovereign_env_used() -> str | None:
+    """Return the endpoint env NAME selected by :func:`_sovereign_base`.
+
+    The value is deliberately never returned or logged here.  ``None`` means
+    the guarded localhost default is being probed without operator intent.
+    """
+    for env_name in (*_CODE_SOVEREIGN_ENVS, _GATEWAY_ENV, _SOVEREIGN_ENV):
+        if (os.environ.get(env_name, "") or "").strip():
+            return env_name
+    return None
 
 
 def _sovereign_env_present() -> bool:
-    """True only when the sovereign gateway URL (A11OY_SOVEREIGN_GATEWAY_URL) or
-    the single-node SZL_LOCAL_LLM_URL was explicitly set (operator intent)."""
-    return bool((os.environ.get(_GATEWAY_ENV, "") or "").strip()
-                or (os.environ.get(_SOVEREIGN_ENV, "") or "").strip())
+    """True only when an accepted serving-endpoint env was explicitly set."""
+    return _sovereign_env_used() is not None
 
 
 def _ollama_root(base: str) -> str:
@@ -489,10 +517,78 @@ def _sovereign_auth_header() -> dict[str, str]:
 
 
 def _sovereign_model_slug() -> str:
-    """The ollama model tag the local node should serve. Overridable per-deploy.
-    The registry slug is `llama3-szl-finetuned-q4`; the live tower currently
-    serves `llama3.1:8b`, so SZL_LOCAL_LLM_MODEL lets a deploy name the real tag."""
-    return (os.environ.get("SZL_LOCAL_LLM_MODEL", "llama3.1:8b") or "llama3.1:8b").strip()
+    """Requested model tag, without pretending a legacy default is installed."""
+    return (os.environ.get("SZL_LOCAL_LLM_MODEL", "") or "").strip()
+
+
+def _reconcile_sovereign_model(served_models: list[str], requested: str = "") -> dict[str, Any]:
+    """Resolve the exact tag that can be executed on a probed local node.
+
+    An explicit SZL_LOCAL_LLM_MODEL is fail-closed: if the node does not report
+    that exact tag, no alternate is silently substituted.  Without an explicit
+    tag we may select only a declared SZL alias, never an arbitrary first model.
+    """
+    served = [str(m).strip() for m in served_models if str(m).strip()]
+    served_set = set(served)
+    explicit = (requested or _sovereign_model_slug()).strip()
+    if explicit:
+        if explicit in served_set:
+            return {"requested_model": explicit, "selected_model": explicit,
+                    "model_ready": True, "selection_basis": "explicit exact match",
+                    "served_models": served}
+        return {"requested_model": explicit, "selected_model": None,
+                "model_ready": False,
+                "selection_basis": "explicit model not present in served model list",
+                "served_models": served}
+    for alias in _SOVEREIGN_MODEL_ALIASES:
+        if alias in served_set:
+            return {"requested_model": None, "selected_model": alias,
+                    "model_ready": True,
+                    "selection_basis": "declared SZL alias exact match",
+                    "served_models": served}
+    return {"requested_model": None, "selected_model": None,
+            "model_ready": False,
+            "selection_basis": "no explicit model and no declared SZL alias is served",
+            "served_models": served}
+
+
+def _inference_receipt_state(model: str = "") -> dict[str, Any]:
+    """Read durable successful-inference proof without making a network call."""
+    try:
+        import szl_governed_infer as _gi
+        status = _gi.inference_receipt_status(model)
+        return dict(status)
+    except Exception as exc:  # honest read failure; never create proof on a GET
+        return {"inference_receipted": False, "successful_receipt_count": 0,
+                "total_receipt_count": 0, "chain_ok": False,
+                "latest_receipt_hash": None,
+                "reason": "receipt ledger unavailable: %s" % type(exc).__name__}
+
+
+def _provider_state(*, configured: bool, reachable: bool, model_ready: bool,
+                    inference_receipted: bool, requires_key: bool = False) -> dict[str, Any]:
+    """Keep configuration, reachability, proof, and operation independent."""
+    operational = bool(reachable and model_ready and inference_receipted)
+    if operational:
+        state = _STATE_LIVE_RECEIPTED
+    elif requires_key and not configured:
+        state = _STATE_OFFLINE_UNTIL_KEYED
+    elif requires_key and configured:
+        state = _STATE_CONFIGURED_UNVERIFIED
+    elif not reachable:
+        state = _STATE_UNAVAILABLE
+    elif not model_ready:
+        state = _STATE_REACHABLE_MODEL_MISMATCH
+    else:
+        state = _STATE_REACHABLE_UNRECEIPTED
+    return {
+        "configured": bool(configured),
+        "reachable": bool(reachable),
+        "model_ready": bool(model_ready),
+        "inference_receipted": bool(inference_receipted),
+        "operational": operational,
+        "state": state,
+    }
 
 
 def _http_json(url: str, *, method: str = "GET", body: bytes | None = None,
@@ -505,17 +601,12 @@ def _http_json(url: str, *, method: str = "GET", body: bytes | None = None,
         headers["Content-Type"] = "application/json"
     # Optional bearer for a bearer-protected gateway (LiteLLM). Secret never logged.
     headers.update(_sovereign_auth_header())
-    try:
-        req = _urllib_request.Request(url, data=body, method=method, headers=headers)
-        with _urllib_request.urlopen(req, timeout=timeout) as r:  # noqa: S310
-            status = getattr(r, "status", None) or 200
-            if not (200 <= int(status) < 300):
-                return None, "node non-2xx status %s" % status
-            raw = r.read().decode("utf-8", "replace")
-        doc = json.loads(raw)
-        return doc, None
-    except Exception as exc:  # noqa: BLE001 — unreachable/timeout => honest OFFLINE
-        return None, "node unreachable: %s" % (str(exc)[:160])
+    # Private/local targets are permitted only because this is the explicit
+    # operator-controlled sovereign path. Metadata/link-local targets remain
+    # denied; DNS and redirects are revalidated and the body/time are bounded.
+    return _bounded_http_json(
+        url, method=method, body=body, headers=headers, timeout=timeout,
+        max_response_bytes=1_048_576, max_redirects=2, allow_private=True)
 
 
 def sovereign_probe(base: str = "", timeout: float | None = None) -> dict[str, Any]:
@@ -530,6 +621,8 @@ def sovereign_probe(base: str = "", timeout: float | None = None) -> dict[str, A
     env_present = _sovereign_env_present()
     out: dict[str, Any] = {
         "env_var": _SOVEREIGN_ENV,
+        "env_used": _sovereign_env_used(),
+        "accepted_endpoint_envs": [*_CODE_SOVEREIGN_ENVS, _GATEWAY_ENV, _SOVEREIGN_ENV],
         "env_present": env_present,
         "base_url": base or None,
         "live": False,
@@ -585,20 +678,41 @@ def sovereign_generate(prompt: str, base: str = "", model: str = "",
     native /api/generate first, then OpenAI-compatible /v1/chat/completions.
     """
     base = (base or _sovereign_base())
-    model = (model or _sovereign_model_slug())
+    requested_model = (model or _sovereign_model_slug()).strip()
+    resolution = None
+    if not model:
+        probe = sovereign_probe(base, timeout=min(
+            _SOVEREIGN_PROBE_TIMEOUT_S,
+            _SOVEREIGN_GEN_TIMEOUT_S if timeout is None else float(timeout)))
+        resolution = _reconcile_sovereign_model(
+            probe.get("models", []), requested=requested_model)
+        model = resolution.get("selected_model") or ""
+    else:
+        model = model.strip()
+        resolution = {"requested_model": requested_model or model,
+                      "selected_model": model, "model_ready": bool(model),
+                      "selection_basis": "pre-reconciled model from mesh probe"}
     to = _SOVEREIGN_GEN_TIMEOUT_S if timeout is None else float(timeout)
     res: dict[str, Any] = {
         "wired": False, "live": False, "text": None, "model": model,
+        "generated": False, "inference_receipted": False,
+        "model_ready": bool(resolution.get("model_ready")),
+        "model_resolution": resolution,
         "api_style": None, "base_url": base or None, "env_var": _SOVEREIGN_ENV,
         "env_present": _sovereign_env_present(), "note": "",
     }
+    if not model:
+        res["note"] = ("Sovereign endpoint may be reachable, but no executable model "
+                       "tag reconciled against its served model list; generation denied.")
+        return res
     b = _ollama_root(base)
     # 1) ollama native /api/generate
     gen_url = b + "/api/generate"
     body = json.dumps({"model": model, "prompt": prompt, "stream": False}).encode("utf-8")
     doc, err = _http_json(gen_url, method="POST", body=body, timeout=to)
     if isinstance(doc, dict) and isinstance(doc.get("response"), str):
-        res.update({"wired": True, "live": True, "text": doc["response"],
+        res.update({"wired": True, "live": True, "generated": True,
+                    "text": doc["response"],
                     "api_style": "ollama /api/generate",
                     "note": "REAL local generation (ollama /api/generate) THIS request."})
         for k in ("eval_count", "prompt_eval_count", "total_duration"):
@@ -617,7 +731,8 @@ def sovereign_generate(prompt: str, base: str = "", model: str = "",
         except Exception:  # noqa: BLE001 — malformed => honest stub
             txt = None
         if isinstance(txt, str):
-            res.update({"wired": True, "live": True, "text": txt,
+            res.update({"wired": True, "live": True, "generated": True,
+                        "text": txt,
                         "api_style": "openai /v1/chat/completions",
                         "note": "REAL local generation (OpenAI-compatible /v1) THIS request."})
             if isinstance(doc2.get("usage"), dict):
@@ -764,7 +879,9 @@ def sovereign_mesh_generate(prompt: str, timeout: float | None = None) -> dict[s
     sel = matrix.get("selected")
     res: dict[str, Any] = {
         "wired": False, "live": False, "text": None,
-        "model": _sovereign_model_slug(), "api_style": None,
+        "generated": False, "inference_receipted": False,
+        "model": None, "requested_model": _sovereign_model_slug() or None,
+        "model_ready": False, "model_resolution": None, "api_style": None,
         "base_url": None, "role": None, "node_index": None,
         "matrix": matrix, "note": "",
     }
@@ -773,9 +890,23 @@ def sovereign_mesh_generate(prompt: str, timeout: float | None = None) -> dict[s
                        "%s" % matrix.get("note", ""))
         return res
     base = sel["base_url"]
-    gen = sovereign_generate(prompt, base=base, timeout=timeout)
+    resolution = _reconcile_sovereign_model(
+        sel.get("served_models", []), requested=_sovereign_model_slug())
+    res["model_resolution"] = resolution
+    res["model_ready"] = bool(resolution.get("model_ready"))
+    res["model"] = resolution.get("selected_model")
+    if not resolution.get("model_ready"):
+        res.update({"base_url": base, "role": sel.get("role"),
+                    "node_index": sel.get("index")})
+        res["note"] = ("Node %s is reachable, but model reconciliation failed: %s. "
+                       "Generation denied; no text or inference receipt fabricated."
+                       % (base, resolution.get("selection_basis")))
+        return res
+    gen = sovereign_generate(prompt, base=base,
+                             model=resolution["selected_model"], timeout=timeout)
     res.update({
         "wired": bool(gen.get("wired")), "live": bool(gen.get("live")),
+        "generated": bool(gen.get("generated")),
         "text": gen.get("text"), "model": gen.get("model"),
         "api_style": gen.get("api_style"), "base_url": base,
         "role": sel.get("role"), "node_index": sel.get("index"),
@@ -910,48 +1041,114 @@ def _enrich_model(m: dict, *, probe_local: bool = False) -> dict:
     if model_id in (_SOVEREIGN_LEGACY_ID, _SOVEREIGN_BACKEND_ID) or env_var == _SOVEREIGN_ENV:
         base = _sovereign_base()
         env_present = _sovereign_env_present()
-        # `wired` = operator intent (env explicitly set). `label` = honest state:
-        # LIVE only when the node answers this request; else UNAVAILABLE.
-        wired = env_present
-        out["api_key_wired"] = wired
-        out["wired"] = wired
+        # Backward-compatible api_key_wired means configuration only. `wired`
+        # now means operational (successful durable inference proof), not intent.
+        out["api_key_wired"] = env_present
+        out["credential_configured"] = env_present
+        out["configured"] = env_present
+        out["wired"] = False
         out["provider"] = m.get("provider", _SOVEREIGN_PROVENANCE)
-        out["env_used"] = _SOVEREIGN_ENV
+        out["env_used"] = _sovereign_env_used() or _SOVEREIGN_ENV
         out["env_present"] = env_present
         out["base_url"] = base or m.get("api_base")
         out["is_local"] = True
         out["own_metal"] = True
         # Default (no probe): honest UNAVAILABLE until proven live this request.
         out["honest_stub"] = True
-        out["label"] = _LABEL_UNAVAILABLE
+        out["label"] = "UNPROBED"
         out["reachable"] = False
+        out["model_ready"] = False
+        out["inference_receipted"] = False
+        out["operational"] = False
+        out["state"] = "UNPROBED"
         if probe_local:
             probe = sovereign_probe(base)
             live = bool(probe.get("live"))
+            resolution = _reconcile_sovereign_model(
+                probe.get("models", []), requested=_sovereign_model_slug())
+            selected_model = resolution.get("selected_model")
+            receipt_state = (_inference_receipt_state(selected_model)
+                             if selected_model else
+                             {"inference_receipted": False,
+                              "successful_receipt_count": 0,
+                              "chain_ok": True,
+                              "latest_receipt_hash": None})
+            state = _provider_state(
+                configured=env_present,
+                reachable=live,
+                model_ready=bool(resolution.get("model_ready")),
+                inference_receipted=bool(receipt_state.get("inference_receipted")))
             out["local_live"] = live
             out["reachable"] = live
             out["local_models"] = probe.get("models", [])
             out["local_probe_note"] = probe.get("note", "")
             out["api_style"] = probe.get("api_style")
-            # honest_stub clears / label flips to LIVE ONLY when actually live.
-            out["honest_stub"] = not live
-            out["label"] = _LABEL_LIVE if live else _LABEL_UNAVAILABLE
+            out["requested_model"] = resolution.get("requested_model")
+            out["selected_model"] = selected_model
+            out["model_resolution"] = resolution
+            out["receipt_state"] = receipt_state
+            out.update(state)
+            out["wired"] = state["operational"]
+            out["honest_stub"] = not state["operational"]
+            out["label"] = state["state"]
+        return out
+
+    if m.get("open_weight"):
+        backend_live = False
+        backend_note = "catalog-only model; no local backend receipt"
+        if m.get("tier_band") == "demo_cpu":
+            try:
+                import szl_alloy_models as _alloy
+                backend_live = bool(_alloy.backend_available())
+                backend_note = (_alloy._LLAMA_ERR or
+                                "llama.cpp backend and GGUF are loadable")
+            except Exception as exc:
+                backend_note = "alloy backend unavailable: %s" % type(exc).__name__
+        receipt_state = (_inference_receipt_state(model_id)
+                         if backend_live else
+                         {"inference_receipted": False,
+                          "successful_receipt_count": 0,
+                          "chain_ok": True,
+                          "latest_receipt_hash": None})
+        state = _provider_state(
+            configured=backend_live, reachable=backend_live,
+            model_ready=backend_live,
+            inference_receipted=bool(receipt_state.get("inference_receipted")))
+        out.update(state)
+        out["api_key_wired"] = False
+        out["credential_configured"] = False
+        out["wired"] = state["operational"]
+        out["provider"] = m.get("provider")
+        out["env_used"] = "A11OY_ALLOY_GGUF" if m.get("tier_band") == "demo_cpu" else None
+        out["env_present"] = bool(os.environ.get("A11OY_ALLOY_GGUF", "").strip())
+        out["base_url"] = None
+        out["is_local"] = True
+        out["runtime_available"] = backend_live
+        out["receipt_state"] = receipt_state
+        out["honest_stub"] = not state["operational"]
+        out["label"] = state["state"]
+        out["runtime_note"] = backend_note
         return out
 
-    wired = _api_key_wired(env_var)
-    out["api_key_wired"] = wired
-    out["wired"] = wired
+    configured = _api_key_wired(env_var)
+    out["api_key_wired"] = configured
+    out["credential_configured"] = configured
+    out["configured"] = configured
+    out["authenticated"] = False
+    out["reachable"] = False
+    out["model_ready"] = False
+    out["inference_receipted"] = False
+    out["operational"] = False
+    out["state"] = (_STATE_CONFIGURED_UNVERIFIED if configured
+                    else _STATE_OFFLINE_UNTIL_KEYED)
+    out["wired"] = False
     out["provider"] = m.get("provider")
     out["env_used"] = env_var or None
-    out["env_present"] = wired
+    out["env_present"] = configured
     out["base_url"] = m.get("api_base") or m.get("base_url")
     out["is_local"] = bool(m.get("open_weight"))
-    # Open-weight alloy models are not cloud-key gated; keep their own honest_stub
-    # if the unifier already set one, else derive from key presence.
-    if m.get("open_weight"):
-        out["honest_stub"] = bool(m.get("honest_stub", True))
-    else:
-        out["honest_stub"] = not wired
+    out["honest_stub"] = True
+    out["label"] = out["state"]
     return out
 
 def _seed_forum() -> None:
@@ -959,7 +1156,9 @@ def _seed_forum() -> None:
     _forum_append({
         "ts": _now(), "source": "a11oy", "event": "registry_boot",
         "model_count": len(MODEL_REGISTRY), "doctrine": DOCTRINE,
-        "note": "a11oy LLM registry initialised — 7 models across 5 tiers",
+        "note": ("a11oy canonical base registry initialised with %d records; "
+                 "runtime extensions are counted at request time"
+                 % len(MODEL_REGISTRY)),
     })
     _forum_append({
         "ts": _now(), "source": "operator", "event": "forum_join",
@@ -990,15 +1189,23 @@ def register(app: FastAPI) -> dict:
         do_probe = bool(probe)
         models = [_enrich_model(m, probe_local=do_probe) for m in MODEL_REGISTRY]
         wired = [m for m in models if m.get("wired")]
+        configured = [m for m in models if m.get("configured")]
+        reachable = [m for m in models if m.get("reachable")]
+        receipted = [m for m in models if m.get("inference_receipted")]
         badges = [{
             "model_id": m["model_id"],
             "wired": bool(m.get("wired")),
+            "configured": bool(m.get("configured")),
+            "reachable": bool(m.get("reachable")),
+            "inference_receipted": bool(m.get("inference_receipted")),
+            "operational": bool(m.get("operational")),
+            "state": m.get("state"),
             "provider": m.get("provider"),
             "env_used": m.get("env_used"),
             "base_url": m.get("base_url"),
             "honest_stub": bool(m.get("honest_stub", True)),
             "is_local": bool(m.get("is_local")),
-            **({"label": m.get("label"), "reachable": m.get("reachable"),
+            **({"label": m.get("label"),
                 "own_metal": bool(m.get("own_metal"))} if m.get("own_metal") else {}),
         } for m in models]
         all_stub = (len(wired) == 0)
@@ -1008,7 +1215,11 @@ def register(app: FastAPI) -> dict:
         _sov_badge = next((m for m in models if m.get("model_id") == _SOVEREIGN_BACKEND_ID), None)
         sovereign_snapshot = {
             "backend_id": _SOVEREIGN_BACKEND_ID,
-            "model": _SOVEREIGN_MODEL_TAG,
+            "canonical_model": _SOVEREIGN_MODEL_TAG,
+            "requested_model": (_sov_badge.get("requested_model")
+                                if _sov_badge else _sovereign_model_slug() or None),
+            "selected_model": (_sov_badge.get("selected_model")
+                               if _sov_badge else None),
             "provider": _SOVEREIGN_PROVENANCE,
             "url": _sovereign_base(),
             "env_present": _sovereign_env_present(),
@@ -1016,6 +1227,12 @@ def register(app: FastAPI) -> dict:
             "reachable": (bool(_sov_badge.get("reachable")) if (do_probe and _sov_badge) else None),
             "label": (_sov_badge.get("label") if (do_probe and _sov_badge)
                       else "UNPROBED (pass ?probe=1 for THIS-request reachability)"),
+            "state": (_sov_badge.get("state") if (do_probe and _sov_badge)
+                      else "UNPROBED"),
+            "inference_receipted": (bool(_sov_badge.get("inference_receipted"))
+                                     if (do_probe and _sov_badge) else False),
+            "operational": (bool(_sov_badge.get("operational"))
+                            if (do_probe and _sov_badge) else False),
             "route_order": "own-metal/sovereign FIRST (when reachable) → free → paid",
             "health_endpoint": "/api/a11oy/v1/llm/sovereign/health",
         }
@@ -1026,6 +1243,15 @@ def register(app: FastAPI) -> dict:
             "model_count": len(models),
             "wired_count": len(wired),
             "wired_model_ids": [m["model_id"] for m in wired],
+            "configured_count": len(configured),
+            "reachable_count": len(reachable),
+            "inference_receipted_count": len(receipted),
+            "operational_count": len(wired),
+            "registry_record_count": len(models),
+            "unique_backend_count": len(models) - 1,
+            "alias_groups": [{"backend_id": _SOVEREIGN_BACKEND_ID,
+                              "aliases": [_SOVEREIGN_LEGACY_ID],
+                              "record_count": 2, "backend_count": 1}],
             "models": models,
             "badges": badges,
             "tier_map": {
@@ -1043,11 +1269,12 @@ def register(app: FastAPI) -> dict:
             "doctrine": DOCTRINE,
             "kernel_commit": _KERNEL,
             "honest_note": (
-                ("wired_count=0 — no API key / no SZL_LOCAL_LLM_URL in this env. "
-                 "Tier selection + Λ-receipt + model_weight_sha256 are REAL. Responses are honest stubs.")
+                ("operational_count=0 — configuration and reachability are not "
+                 "inference proof. Providers remain offline or unreceipted until "
+                 "a successful durable inference receipt verifies.")
                 if all_stub else
-                ("wired_count=%d — per-model `wired` computed from env at request time "
-                 "(_api_key_wired / SZL_LOCAL_LLM_URL). Unwired models degrade to honest stubs."
+                ("operational_count=%d — every operational provider has an exact "
+                 "served model and a verified durable inference receipt."
                  % len(wired))),
         })
 
@@ -1177,17 +1404,44 @@ def register(app: FastAPI) -> dict:
         _want_sovereign = _explicit_sovereign or _offline_pref or _own_metal_first
         if _want_sovereign:
             gen = _mesh_gen
-            _live = bool(gen.get("live"))
+            _generated = bool(gen.get("live") and gen.get("text"))
+            _generation_receipt = {"ok": False, "inference_receipted": False,
+                                   "reason": "no successful generation to receipt"}
+            if _generated:
+                try:
+                    import szl_governed_infer as _gi
+                    _raw = gen.get("raw") or {}
+                    _tokens = (_raw.get("eval_count")
+                               or (_raw.get("usage") or {}).get("completion_tokens")
+                               or 0)
+                    _generation_receipt = _gi.record_provider_generation(
+                        prompt or _DEFAULT_SOVEREIGN_PROMPT,
+                        gen.get("text"), gen.get("model"), tokens=_tokens,
+                        base_url=gen.get("base_url") or "")
+                except Exception as exc:
+                    _generation_receipt = {
+                        "ok": False, "inference_receipted": False,
+                        "reason": "durable receipt unavailable: %s" % type(exc).__name__}
+            _state = _provider_state(
+                configured=_sovereign_env_present(),
+                reachable=_mesh_reachable,
+                model_ready=bool(gen.get("model_ready")),
+                inference_receipted=bool(
+                    _generation_receipt.get("inference_receipted")))
             # Prefer the first-class Wave-M backend id; fall back to legacy alias.
             sov_model = (_MODEL_BY_ID.get(_SOVEREIGN_BACKEND_ID)
                          or _MODEL_BY_ID.get(_SOVEREIGN_LEGACY_ID)
                          or MODEL_REGISTRY[0])
             sov_enriched = _enrich_model(sov_model)
-            sov_enriched["wired"] = _sovereign_env_present()
-            sov_enriched["reachable"] = _live
-            sov_enriched["local_live"] = _live
-            sov_enriched["honest_stub"] = not _live
-            sov_enriched["label"] = _LABEL_LIVE if _live else _LABEL_UNAVAILABLE
+            sov_enriched.update(_state)
+            sov_enriched["wired"] = _state["operational"]
+            sov_enriched["local_live"] = _mesh_reachable
+            sov_enriched["generated"] = _generated
+            sov_enriched["selected_model"] = gen.get("model")
+            sov_enriched["model_resolution"] = gen.get("model_resolution")
+            sov_enriched["generation_receipt"] = _generation_receipt
+            sov_enriched["honest_stub"] = not _state["operational"]
+            sov_enriched["label"] = _state["state"]
             if _explicit_sovereign:
                 _why = "explicit request"
             elif _own_metal_first:
@@ -1195,11 +1449,15 @@ def register(app: FastAPI) -> dict:
             else:
                 _why = "offline preference, no cloud key wired"
             sov_reason = "%s selected (%s); " % (sov_model.get("model_id"), _why)
-            if _live:
-                sov_reason += ("own-metal-first node %s (role=%s) LIVE this request — "
-                               "REAL local generation [LIVE]."
+            if _generated and _state["operational"]:
+                sov_reason += ("own-metal-first node %s (role=%s) generated real text "
+                               "and its durable inference receipt replay-verified."
                                % (gen.get("base_url"), gen.get("role")))
                 response_text = gen.get("text") or ""
+            elif _generated:
+                sov_reason += ("node generated real text, but durable inference receipt "
+                               "did not verify; provider remains unreceipted.")
+                response_text = gen.get("text") or ""
             elif _mesh_reachable:
                 sov_reason += ("node %s reachable but did not generate live — honest "
                                "UNAVAILABLE (never fabricate)." % gen.get("base_url"))
@@ -1232,10 +1490,16 @@ def register(app: FastAPI) -> dict:
                 "model_display": sov_model.get("display_name"),
                 "reason": sov_reason, "task_hint": task_hint,
                 "own_metal_first": bool(_own_metal_first),
-                "reachable": _live,
-                "label": _LABEL_LIVE if _live else _LABEL_UNAVAILABLE,
+                "configured": _state["configured"],
+                "reachable": _state["reachable"],
+                "model_ready": _state["model_ready"],
+                "generated": _generated,
+                "inference_receipted": _state["inference_receipted"],
+                "operational": _state["operational"],
+                "state": _state["state"],
+                "label": _state["state"],
                 "api_key_wired": _sovereign_env_present(),
-                "local_live": _live,
+                "local_live": _mesh_reachable,
                 "local_api_style": gen.get("api_style"),
                 "local_base_url": gen.get("base_url"),
                 "mesh_node_count": matrix.get("node_count", 0),
@@ -1243,6 +1507,8 @@ def register(app: FastAPI) -> dict:
                 "mesh_selected": matrix.get("selected"),
                 "selected_role": gen.get("role"),
                 "selected_base_url": gen.get("base_url"),
+                "selected_model": gen.get("model"),
+                "generation_receipt_hash": _generation_receipt.get("receipt_hash"),
                 "doctrine": DOCTRINE, "kernel_commit": _KERNEL,
                 "conjecture_note": "Λ = Conjecture 1 — NOT a theorem. CAUCHY_ND sorry open.",
             }
@@ -1252,14 +1518,20 @@ def register(app: FastAPI) -> dict:
                 "response": response_text,
                 "model_selected": sov_enriched,
                 "lambda_receipt": sov_receipt,
-                "label": _LABEL_LIVE if _live else _LABEL_UNAVAILABLE,
-                "reachable": _live,
+                "label": _state["state"],
+                "reachable": _state["reachable"],
+                "generated": _generated,
+                "inference_receipted": _state["inference_receipted"],
+                "operational": _state["operational"],
+                "provider_state": _state,
+                "generation_receipt": _generation_receipt,
                 "routed_via": "%s via sovereign_mesh (%s)" % (
                     sov_model.get("model_id"),
-                    gen.get("api_style") if _live else "honest UNAVAILABLE"),
+                    gen.get("api_style") if _generated else "honest UNAVAILABLE"),
                 "local": {k: gen.get(k) for k in
-                          ("wired", "live", "api_style", "base_url", "role",
-                           "node_index", "model", "note", "raw")
+                          ("wired", "live", "generated", "api_style", "base_url", "role",
+                           "node_index", "model", "model_ready", "model_resolution",
+                           "note", "raw")
                           if k in gen},
                 "sovereign_mesh": matrix,
                 "doctrine": DOCTRINE,
@@ -1305,6 +1577,13 @@ def register(app: FastAPI) -> dict:
         except Exception:
             pass
 
+        provider_state = _provider_state(
+            configured=bool(enriched.get("configured")),
+            reachable=False,
+            model_ready=False,
+            inference_receipted=False,
+            requires_key=True,
+        )
         receipt = {
             "schema": "szl.llm_route.lambda_receipt/v1",
             "ts": _now(),
@@ -1320,6 +1599,13 @@ def register(app: FastAPI) -> dict:
             "model_weight_sha256": mw_sha,
             "model_weight_method": mw_method,
             "api_key_wired": enriched["api_key_wired"],
+            "configured": provider_state["configured"],
+            "authenticated": False,
+            "reachable": False,
+            "model_ready": False,
+            "inference_receipted": False,
+            "operational": False,
+            "provider_state": provider_state["state"],
             "doctrine": DOCTRINE,
             "kernel_commit": _KERNEL,
             "conjecture_note": "Λ = Conjecture 1 — NOT a theorem. CAUCHY_ND sorry open.",
@@ -1328,7 +1614,11 @@ def register(app: FastAPI) -> dict:
         # Emit honest response (stub when no key)
         if enriched["api_key_wired"]:
             # Real call would go here — key present but routing call not implemented
-            response_text = f"[ROUTING READY] API key present for {selected_model['display_name']}. Prompt would be forwarded."
+            response_text = (
+                f"[CONFIGURED_UNVERIFIED] A credential is present for "
+                f"{selected_model['display_name']}, but this route did not perform "
+                "an authenticated inference call. No model output is fabricated."
+            )
         else:
             response_text = (
                 f"[HONEST STUB] Would route to {selected_model['display_name']} "
@@ -1477,20 +1767,35 @@ def register(app: FastAPI) -> dict:
         base = _sovereign_base()
         primary_probe = sovereign_probe(base)
         env_present = bool(primary_probe.get("env_present"))
-        wired = env_present
         any_reachable = bool(matrix.get("any_reachable"))
         # Primary-node reachability (Wave-M compact contract mirrors the primary).
         reachable = bool(primary_probe.get("live"))
-        # Honest labels: primary-node `label`, plus mesh-wide `sovereign_status`
-        # (LIVE when ANY node answered; UNAVAILABLE when none did).
-        label = _LABEL_LIVE if reachable else _LABEL_UNAVAILABLE
-        sovereign_status = _LABEL_LIVE if any_reachable else _LABEL_UNAVAILABLE
+        resolution = _reconcile_sovereign_model(
+            primary_probe.get("models", []), requested=_sovereign_model_slug())
+        selected_model = resolution.get("selected_model")
+        receipt_state = (_inference_receipt_state(selected_model)
+                         if selected_model else
+                         {"inference_receipted": False,
+                          "successful_receipt_count": 0,
+                          "total_receipt_count": 0,
+                          "chain_ok": True,
+                          "latest_receipt_hash": None})
+        state = _provider_state(
+            configured=env_present,
+            reachable=reachable,
+            model_ready=bool(resolution.get("model_ready")),
+            inference_receipted=bool(receipt_state.get("inference_receipted")))
+        label = state["state"]
+        sovereign_status = (_STATE_LIVE_RECEIPTED
+                            if state["operational"] else
+                            (_STATE_REACHABLE_UNRECEIPTED
+                             if any_reachable else _STATE_UNAVAILABLE))
         return JSONResponse({
             # ── Wave-M required compact contract ──
             # `model` = canonical sovereign model tag; `configured_model` (below)
             # is the runtime-overridable ollama tag the node is asked to serve.
             "reachable": reachable,
-            "model": _SOVEREIGN_MODEL_TAG,
+            "model": selected_model,
             "url": base,
             "provider": _SOVEREIGN_PROVENANCE,
             "label": label,
@@ -1501,6 +1806,16 @@ def register(app: FastAPI) -> dict:
             "model_id": _SOVEREIGN_BACKEND_ID,
             "legacy_alias": _SOVEREIGN_LEGACY_ID,
             "model_slug": _SOVEREIGN_MODEL_TAG,
+            "canonical_model": _SOVEREIGN_MODEL_TAG,
+            "requested_model": resolution.get("requested_model"),
+            "selected_model": selected_model,
+            "model_ready": state["model_ready"],
+            "model_resolution": resolution,
+            "configured": state["configured"],
+            "inference_receipted": state["inference_receipted"],
+            "operational": state["operational"],
+            "state": state["state"],
+            "receipt_state": receipt_state,
             # ── Mesh (multi-node) reachability matrix (Wave N, Dev 3) ──
             "sovereign_status": sovereign_status,   # honest label: LIVE | UNAVAILABLE (mesh-wide)
             "mesh": matrix,
@@ -1510,17 +1825,23 @@ def register(app: FastAPI) -> dict:
             "selected_node": matrix.get("selected"),
             "own_metal_first": True,
             "fallthrough_to_cloud": (not any_reachable),
-            "env_vars": {"primary": _SOVEREIGN_ENV, "nodes": _SOVEREIGN_NODES_ENV},
+            "env_vars": {
+                "primary": _SOVEREIGN_ENV,
+                "code_primary": list(_CODE_SOVEREIGN_ENVS),
+                "gateway": _GATEWAY_ENV,
+                "nodes": _SOVEREIGN_NODES_ENV,
+            },
+            "env_used": _sovereign_env_used(),
             # ── Backward-compatible single-node (primary) fields ──
             "env_var": _SOVEREIGN_ENV,
             "env_present": env_present,
-            "wired": wired,                   # env present => operator intends local routing
+            "wired": state["operational"],
             "live": reachable,                # primary-node THIS-request liveness (== reachable)
-            "honest_stub": not any_reachable,
+            "honest_stub": not state["operational"],
             "base_url": base,
             "api_style": primary_probe.get("api_style"),
             "served_models": primary_probe.get("models", []),
-            "configured_model": _sovereign_model_slug(),
+            "configured_model": _sovereign_model_slug() or None,
             "probed": primary_probe.get("probed", []),
             "probe_ua": "browser-UA (Cloudflare-front safe)",
             "note": matrix.get("note", ""),
@@ -1547,6 +1868,14 @@ def register(app: FastAPI) -> dict:
                 "provider": provider,
                 "env_var": env_var,      # NAME ONLY — never the secret value
                 "key_present": present,
+                "configured": present,
+                "authenticated": False,
+                "reachable": False,
+                "model_ready": False,
+                "inference_receipted": False,
+                "operational": False,
+                "state": (_STATE_CONFIGURED_UNVERIFIED if present
+                          else _STATE_OFFLINE_UNTIL_KEYED),
             })
             if present:
                 seen_present.add(provider)
@@ -1570,6 +1899,21 @@ def register(app: FastAPI) -> dict:
             _matrix = sovereign_mesh_matrix()
             _any = bool(_matrix.get("any_reachable"))
             _sel = _matrix.get("selected") or {}
+            _resolution = _reconcile_sovereign_model(
+                _sel.get("served_models", []), requested=_sovereign_model_slug())
+            _selected_model = _resolution.get("selected_model")
+            _receipt = (_inference_receipt_state(_selected_model)
+                        if _selected_model else
+                        {"inference_receipted": False,
+                         "successful_receipt_count": 0,
+                         "total_receipt_count": 0,
+                         "chain_ok": True,
+                         "latest_receipt_hash": None})
+            _local_state = _provider_state(
+                configured=_sovereign_env_present(),
+                reachable=_any,
+                model_ready=bool(_resolution.get("model_ready")),
+                inference_receipted=bool(_receipt.get("inference_receipted")))
             _mesh_summary = {
                 "node_count": _matrix.get("node_count", 0),
                 "reachable_count": _matrix.get("reachable_count", 0),
@@ -1586,7 +1930,17 @@ def register(app: FastAPI) -> dict:
                 "nodes_env": _SOVEREIGN_NODES_ENV,
                 "env_present": _sovereign_env_present(),
                 "live": _any, "reachable": _any,
-                "label": _LABEL_LIVE if _any else _LABEL_UNAVAILABLE,
+                "configured": _local_state["configured"],
+                "model_ready": _local_state["model_ready"],
+                "requested_model": _resolution.get("requested_model"),
+                "selected_model": _selected_model,
+                "model_resolution": _resolution,
+                "inference_receipted": _local_state["inference_receipted"],
+                "operational": _local_state["operational"],
+                "wired": _local_state["operational"],
+                "state": _local_state["state"],
+                "label": _local_state["state"],
+                "receipt_state": _receipt,
                 "served_models": _sel.get("served_models", []),
                 "note": _matrix.get("note", ""),
             }
@@ -1596,7 +1950,10 @@ def register(app: FastAPI) -> dict:
                 "env_var": _SOVEREIGN_ENV, "base_url": base or None,
                 "nodes_env": _SOVEREIGN_NODES_ENV,
                 "env_present": _sovereign_env_present(), "live": None,
-                "reachable": None, "label": "UNPROBED",
+                "reachable": None, "configured": _sovereign_env_present(),
+                "model_ready": False, "inference_receipted": False,
+                "operational": False, "wired": False,
+                "state": "UNPROBED", "label": "UNPROBED",
                 "note": "pass ?probe=1 to ping the mesh for THIS-request liveness",
             }
 
@@ -1607,16 +1964,18 @@ def register(app: FastAPI) -> dict:
             "role": "router key/liveness status — provider NAMES only, never secrets",
             "providers": providers,
             "provider_keys_present": provider_keys_present,
-            "provider_wired_count": len(provider_keys_present),
+            "provider_configured_count": len(provider_keys_present),
+            "provider_operational_count": 0,
+            "provider_wired_count": 0,
             "code_agent_credential": code_key_public,
             "local_nodes": [local_node],
             "sovereign_mesh": _mesh_summary,
             "any_cloud_key_present": len(provider_keys_present) > 0,
             "doctrine": DOCTRINE,
             "kernel_commit": _KERNEL,
-            "honest_note": ("Presence is a real os.environ check THIS request. The secret "
-                            "value is NEVER read into the response, logged, or returned — "
-                            "only the env-var NAME + a boolean presence flag."),
+            "honest_note": ("Presence is a real os.environ check THIS request, but "
+                            "configuration is not authentication, reachability, or "
+                            "receipted inference. Secret values are never returned."),
         })
 
     return {

szl_m1_corpus_manifest.py

@@ -0,0 +1,363 @@
+#!/usr/bin/env python3
+# SPDX-License-Identifier: Apache-2.0
+"""Build the deterministic, fail-closed M1 corpus decision ledgers.
+
+This module is an accounting and evaluation-readiness tool.  It reads only
+versioned local sources, performs no network calls, and never trains or promotes
+a model.  Every Brain graph node receives an explicit decision.  External
+metadata without an item-level license and person metadata are quarantined;
+they are never silently converted into training text.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import json
+from collections import Counter
+from pathlib import Path
+from typing import Any, Iterable
+
+
+ROOT = Path(__file__).resolve().parent
+OUT_DIR = ROOT / "model_release" / "m1"
+GRAPH_LEDGER = OUT_DIR / "brain-ingest-ledger.jsonl"
+FORMULA_LEDGER = OUT_DIR / "formula-curriculum-ledger.jsonl"
+CORPUS_MANIFEST = OUT_DIR / "corpus-ingestion-manifest.json"
+EVALUATION_MANIFEST = OUT_DIR / "evaluation-manifest.json"
+EXPECTED_RAW_NODES = 9464
+EXPECTED_DISTINCT_ARTIFACTS = 4229
+PERSON_KINDS = {"person", "author"}
+LOCAL_LICENSED_KINDS = {"estate", "endpoint", "topic", "surface", "formula"}
+FORMULA_STATUS_VOCABULARY = ["KERNEL_ACCEPTED", "CONDITIONAL", "OPEN", "REFUTED"]
+
+
+def _canonical(value: Any) -> bytes:
+    return json.dumps(value, ensure_ascii=False, sort_keys=True, separators=(",", ":")).encode("utf-8")
+
+
+def _sha(value: bytes) -> str:
+    return hashlib.sha256(value).hexdigest()
+
+
+def _sha_file(path: Path) -> str:
+    digest = hashlib.sha256()
+    with path.open("rb") as stream:
+        for chunk in iter(lambda: stream.read(1024 * 1024), b""):
+            digest.update(chunk)
+    return digest.hexdigest()
+
+
+def _receipt(prefix: str, value: Any) -> str:
+    return f"{prefix}:sha256:{_sha(_canonical(value))}"
+
+
+def _source_family(node: dict[str, Any]) -> str:
+    kind = str(node.get("kind") or "unknown").lower()
+    source = str(node.get("source") or "").lower()
+    if kind in PERSON_KINDS:
+        return "authorship-person-metadata"
+    if kind == "formula":
+        # The raw graph row is an index duplicate, not the canonical formula
+        # curriculum record.  Keep it in its own family so the raw inventory
+        # can remain quarantined while the canonical record stays HOLDOUT.
+        return "brain-raw-formula-index"
+    if kind in {"estate", "endpoint", "topic", "surface"} and int(node.get("layer", -1)) >= 0:
+        return "a11oy-versioned-runtime"
+    if kind == "repo" or "github" in source or "gitlab" in source:
+        return "repository-metadata"
+    if kind == "paper" or "arxiv" in source:
+        return "academic-publication-metadata"
+    if kind in {"dataset", "benchmark"}:
+        return "dataset-benchmark-metadata"
+    if kind in {"standard", "org", "lab", "axis"}:
+        return "research-landscape-metadata"
+    return "other-graph-metadata"
+
+
+def _split_for_family(family: str) -> str:
+    # Raw Brain rows are inventory, never training data.  Admitted canonical
+    # rows are built by the separate evidence/formula generators.
+    return "QUARANTINE"
+
+
+def _formula_status(formula_id: str, meta: dict[str, Any]) -> str:
+    locked = {"F1", "F4", "F7", "F11", "F12", "F18", "F19", "F22"}
+    if formula_id in locked and str(meta.get("proof_status")) == "PROVED" and str(meta.get("lean_status")) == "PROVED":
+        return "KERNEL_ACCEPTED"
+    evidence = " ".join(str(meta.get(key) or "") for key in ("proof_status", "lean_status", "maturity", "status")).upper()
+    if "REFUT" in evidence:
+        return "REFUTED"
+    if "CONDITIONAL" in evidence or "AXIOM-GATED" in evidence:
+        return "CONDITIONAL"
+    return "OPEN"
+
+
+def _formula_canonical_text(formula_id: str, meta: dict[str, Any], status: str) -> str:
+    text_parts = [f"formula_id: {formula_id}", f"formula_status: {status}"]
+    for field in ("name", "primitive", "identity_doc", "latex", "context", "source_file", "source_line"):
+        if meta.get(field) not in (None, ""):
+            text_parts.append(f"{field}: {meta[field]}")
+    return "\n".join(text_parts)
+
+
+def _formula_receipt_id(family: str, formula_id: str, meta: dict[str, Any]) -> tuple[str, str, str]:
+    status = _formula_status(formula_id, meta)
+    canonical_text = _formula_canonical_text(formula_id, meta, status)
+    text_sha = _sha(canonical_text.encode("utf-8"))
+    stable = {"source_family": family, "formula_id": formula_id,
+              "formula_status": status, "canonical_text_sha256": text_sha}
+    return _receipt("formula", stable), canonical_text, status
+
+
+def _node_canonical_text(node: dict[str, Any]) -> str:
+    fields = [
+        f"title: {str(node.get('title') or '').strip()}",
+        f"kind: {str(node.get('kind') or 'unknown')}",
+        f"evidence_label: {str(node.get('label') or 'UNKNOWN')}",
+    ]
+    for key in ("axis", "organ", "primitive", "source", "url", "path", "note"):
+        value = node.get(key)
+        if value not in (None, ""):
+            fields.append(f"{key}: {str(value).strip()}")
+    return "\n".join(fields)
+
+
+def _graph_formula_receipts(nodes: Iterable[dict[str, Any]]) -> dict[str, str]:
+    result: dict[str, str] = {}
+    for node in nodes:
+        if node.get("kind") == "formula" and node.get("formula_id"):
+            stable = {key: value for key, value in node.items() if key not in {"degree"}}
+            result[str(node["formula_id"])] = _receipt("brain-node", stable)
+    return result
+
+
+def _build_node_rows(nodes: list[dict[str, Any]], evaluation_receipt_id: str,
+                     formula_receipts: dict[str, str]) -> list[dict[str, Any]]:
+    from szl_puriq_formulas import FORMULA_META
+
+    rows: list[dict[str, Any]] = []
+    seen_ids: set[str] = set()
+    for node in sorted(nodes, key=lambda item: str(item.get("id") or "")):
+        node_id = str(node.get("id") or "")
+        if not node_id or node_id in seen_ids:
+            raise ValueError(f"Brain node id is absent or duplicated: {node_id!r}")
+        seen_ids.add(node_id)
+        stable = {key: value for key, value in node.items() if key not in {"degree"}}
+        receipt_id = _receipt("brain-node", stable)
+        family = _source_family(node)
+        split = _split_for_family(family)
+        kind = str(node.get("kind") or "unknown").lower()
+        is_person = kind in PERSON_KINDS
+        locally_licensed = int(node.get("layer", -1)) >= 0 and kind in LOCAL_LICENSED_KINDS
+        formula_id = str(node.get("formula_id") or "") if kind == "formula" else ""
+        formula_status = _formula_status(formula_id, FORMULA_META.get(formula_id, {})) if formula_id else None
+        if is_person:
+            safety = "QUARANTINE_PERSON_METADATA"
+        elif kind == "formula":
+            safety = "QUARANTINE_RAW_GRAPH_DUPLICATE_FORMULA"
+        elif not locally_licensed:
+            safety = "QUARANTINE_LICENSE_UNKNOWN"
+        else:
+            safety = "QUARANTINE_RAW_GRAPH_NOT_ADMITTED"
+        decision = "QUARANTINE"
+        canonical_text = _node_canonical_text(node)
+        capture = node.get("captured_at") or node.get("harvested_at")
+        freshness = "CAPTURED_SOURCE_DATE" if capture else (
+            "VERSION_BOUND_NOT_TIME_FRESH" if locally_licensed else "UNKNOWN_NO_SOURCE_TIMESTAMP"
+        )
+        rows.append({
+            "schema": "szl.m1-brain-ingest-decision/v1",
+            "receipt_id": receipt_id,
+            "brain_anatomy_receipt_id": receipt_id,
+            "node_id": node_id,
+            "canonical_artifact_id": node_id if not is_person else None,
+            "artifact_role": "ATTRIBUTION_METADATA" if is_person else "DISTINCT_ARTIFACT",
+            "kind": kind,
+            "source_family": family,
+            "source_family_split": split,
+            "provenance": {
+                "source": node.get("source") or node.get("derived_from") or "versioned-local-graph",
+                "url": node.get("url"),
+                "captured_at": capture,
+                "evidence_label": node.get("label") or "UNKNOWN",
+                "graph_node_receipt_id": receipt_id,
+            },
+            "license": {
+                "spdx": "Apache-2.0" if locally_licensed else None,
+                "state": "VERSIONED_REPOSITORY_LICENSE" if locally_licensed else "UNKNOWN_ITEM_LEVEL_LICENSE",
+                "evidence": "LICENSE" if locally_licensed else None,
+            },
+            "freshness": {"state": freshness, "captured_at": capture},
+            "safety_decision": safety,
+            "training_decision": decision,
+            "training_eligible": False,
+            "formula_id": formula_id or None,
+            "formula_status": formula_status,
+            "formula_receipt_id": formula_receipts.get(formula_id) if formula_id else None,
+            "evaluation_receipt_id": evaluation_receipt_id,
+            "canonical_text": canonical_text,
+            "canonical_text_sha256": _sha(canonical_text.encode("utf-8")),
+        })
+    return rows
+
+
+def _build_formula_rows(nodes: list[dict[str, Any]], evaluation_receipt_id: str) -> list[dict[str, Any]]:
+    from szl_puriq_formulas import FORMULA_META
+
+    graph_receipts = _graph_formula_receipts(nodes)
+    rows: list[dict[str, Any]] = []
+    sources: list[tuple[str, str, dict[str, Any]]] = [
+        ("canonical-formula-registry", formula_id, dict(meta))
+        for formula_id, meta in FORMULA_META.items()
+    ]
+    knowledge = json.loads((ROOT / "knowledge.json").read_text(encoding="utf-8"))
+    for item in knowledge.get("formulas") or []:
+        if isinstance(item, dict) and item.get("id"):
+            sources.append(("thesis-formula-corpus", str(item["id"]), dict(item)))
+
+    seen: set[tuple[str, str]] = set()
+    for family, formula_id, meta in sorted(sources, key=lambda item: (item[0], item[1])):
+        key = (family, formula_id)
+        if key in seen:
+            raise ValueError(f"formula source duplicate: {key}")
+        seen.add(key)
+        receipt_id, canonical_text, status = _formula_receipt_id(family, formula_id, meta)
+        if status == "KERNEL_ACCEPTED":
+            role = "HOLDOUT_POSITIVE"
+        elif status == "REFUTED":
+            role = "HOLDOUT_NEGATIVE"
+        else:
+            role = "HOLDOUT_ABSTENTION"
+        rows.append({
+            "schema": "szl.m1-formula-curriculum-decision/v1",
+            "receipt_id": receipt_id,
+            "formula_receipt_id": receipt_id,
+            "brain_anatomy_receipt_id": graph_receipts.get(formula_id),
+            "formula_id": formula_id,
+            "source_family": family,
+            "source_family_split": "HOLDOUT",
+            "formula_status": status,
+            "training_decision": role,
+            "abstention_required": status in {"OPEN", "CONDITIONAL"},
+            "negative_example": status == "REFUTED",
+            "provenance": {
+                "source": "szl_puriq_formulas.FORMULA_META" if family == "canonical-formula-registry" else "knowledge.json#/formulas",
+                "source_file": meta.get("source_file"),
+                "source_line": meta.get("source_line"),
+            },
+            "license": {"spdx": "Apache-2.0", "state": "VERSIONED_REPOSITORY_LICENSE", "evidence": "LICENSE"},
+            "freshness": {"state": "VERSION_BOUND_NOT_TIME_FRESH", "captured_at": None},
+            "safety_decision": "ALLOW_HOLDOUT_ONLY",
+            "evaluation_receipt_id": evaluation_receipt_id,
+            "canonical_text": canonical_text,
+            "canonical_text_sha256": _sha(canonical_text.encode("utf-8")),
+        })
+    return rows
+
+
+def _write_jsonl(path: Path, rows: Iterable[dict[str, Any]]) -> None:
+    with path.open("w", encoding="utf-8", newline="\n") as stream:
+        for row in rows:
+            stream.write(json.dumps(row, ensure_ascii=False, sort_keys=True, separators=(",", ":")) + "\n")
+
+
+def build() -> dict[str, Any]:
+    from a11oy_brain_graph import get_brain_graph
+
+    OUT_DIR.mkdir(parents=True, exist_ok=True)
+    graph = get_brain_graph(refresh=True)
+    nodes = list(graph.get("nodes") or [])
+    if len(nodes) != EXPECTED_RAW_NODES:
+        raise ValueError(f"expected {EXPECTED_RAW_NODES} Brain nodes, observed {len(nodes)}")
+    distinct = sum(1 for node in nodes if str(node.get("kind") or "").lower() not in PERSON_KINDS)
+    if distinct != EXPECTED_DISTINCT_ARTIFACTS:
+        raise ValueError(f"expected {EXPECTED_DISTINCT_ARTIFACTS} distinct artifacts, observed {distinct}")
+
+    evaluation_sha = _sha_file(EVALUATION_MANIFEST)
+    evaluation_receipt_id = f"m1-evaluation:sha256:{evaluation_sha}"
+    from szl_puriq_formulas import FORMULA_META
+    formula_receipts = {
+        formula_id: _formula_receipt_id("canonical-formula-registry", formula_id, dict(meta))[0]
+        for formula_id, meta in FORMULA_META.items()
+    }
+    node_rows = _build_node_rows(nodes, evaluation_receipt_id, formula_receipts)
+    formula_rows = _build_formula_rows(nodes, evaluation_receipt_id)
+    _write_jsonl(GRAPH_LEDGER, node_rows)
+    _write_jsonl(FORMULA_LEDGER, formula_rows)
+
+    node_decisions = Counter(row["training_decision"] for row in node_rows)
+    node_safety = Counter(row["safety_decision"] for row in node_rows)
+    formula_status = Counter(row["formula_status"] for row in formula_rows)
+    formula_roles = Counter(row["training_decision"] for row in formula_rows)
+    source_families: dict[str, dict[str, Any]] = {}
+    for row in [*node_rows, *formula_rows]:
+        family = row["source_family"]
+        entry = source_families.setdefault(family, {"split": row["source_family_split"], "rows": 0})
+        if entry["split"] != row["source_family_split"]:
+            raise ValueError(f"source family leakage across splits: {family}")
+        entry["rows"] += 1
+
+    stable_nodes = [{key: value for key, value in node.items() if key != "degree"}
+                    for node in sorted(nodes, key=lambda item: str(item.get("id") or ""))]
+    graph_snapshot_sha = _sha(_canonical(stable_nodes))
+    manifest = {
+        "schema": "szl.m1-corpus-ingestion-manifest/v1",
+        "candidate_id": "a11oy-evidence-1.5b-sft-lora",
+        "release_state": "NOT_PROMOTED",
+        "training_state": "NOT_RUN",
+        "training_relation": "PROPOSAL_ONLY_NOT_USED_BY_EXISTING_ADAPTER",
+        "quality_claim": "NOT_ESTABLISHED",
+        "source_snapshot": {
+            "brain_graph_receipt_id": f"brain-graph:sha256:{graph_snapshot_sha}",
+            "brain_graph_sha256": graph_snapshot_sha,
+            "raw_node_count": len(node_rows),
+            "distinct_artifact_count": distinct,
+            "person_metadata_count": len(node_rows) - distinct,
+            "link_count_reported_by_graph": graph.get("link_count"),
+            "versioned_sources_only": True,
+            "network_fetches": 0,
+        },
+        "ledgers": {
+            "brain_nodes": {"path": GRAPH_LEDGER.name, "rows": len(node_rows), "bytes": GRAPH_LEDGER.stat().st_size,
+                            "sha256": _sha_file(GRAPH_LEDGER), "schema": "szl.m1-brain-ingest-decision/v1"},
+            "formulas": {"path": FORMULA_LEDGER.name, "rows": len(formula_rows), "bytes": FORMULA_LEDGER.stat().st_size,
+                         "sha256": _sha_file(FORMULA_LEDGER), "schema": "szl.m1-formula-curriculum-decision/v1"},
+        },
+        "coverage": {
+            "node_decisions_total": len(node_rows),
+            "node_decisions_expected": EXPECTED_RAW_NODES,
+            "node_decision_coverage": 1.0,
+            "distinct_artifacts": distinct,
+            "person_metadata": len(node_rows) - distinct,
+            "node_decisions": dict(sorted(node_decisions.items())),
+            "node_safety": dict(sorted(node_safety.items())),
+            "raw_nodes_training_quarantined": sum(not bool(row["training_eligible"]) for row in node_rows),
+            "training_eligible_nodes": sum(bool(row["training_eligible"]) for row in node_rows),
+            "formula_records_current_versioned_sources": len(formula_rows),
+            "formula_requested_200_claim": "NOT_VERIFIED_BY_CURRENT_VERSIONED_SOURCES",
+            "formula_status_vocabulary": FORMULA_STATUS_VOCABULARY,
+            "formula_status": {status: formula_status.get(status, 0) for status in FORMULA_STATUS_VOCABULARY},
+            "formula_roles": dict(sorted(formula_roles.items())),
+            "abstention_examples": sum(bool(row["abstention_required"]) for row in formula_rows),
+            "negative_examples": sum(bool(row["negative_example"]) for row in formula_rows),
+            "quarantined_or_excluded_nodes": sum(not bool(row["training_eligible"]) for row in node_rows),
+            "missing_item_level_license_nodes": sum(row["license"]["state"] == "UNKNOWN_ITEM_LEVEL_LICENSE" for row in node_rows),
+            "missing_source_timestamp_nodes": sum(row["freshness"]["state"] == "UNKNOWN_NO_SOURCE_TIMESTAMP" for row in node_rows),
+        },
+        "source_family_split": dict(sorted(source_families.items())),
+        "leakage_policy": "all rows from one source_family have exactly one split; formula families are HOLDOUT; quarantined rows are never training text",
+        "resulting_evaluation_receipt": {
+            "receipt_id": evaluation_receipt_id,
+            "path": EVALUATION_MANIFEST.name,
+            "bytes": EVALUATION_MANIFEST.stat().st_size,
+            "sha256": evaluation_sha,
+            "state": "INCOMPLETE",
+            "promotion_decision": "NOT_PROMOTED",
+        },
+    }
+    CORPUS_MANIFEST.write_text(json.dumps(manifest, indent=2, ensure_ascii=False, sort_keys=True) + "\n", encoding="utf-8", newline="\n")
+    return manifest
+
+
+if __name__ == "__main__":
+    print(json.dumps(build(), indent=2, ensure_ascii=True, sort_keys=True))

szl_m1_model_gate.py

@@ -0,0 +1,833 @@
+#!/usr/bin/env python3
+# SPDX-License-Identifier: Apache-2.0
+"""Fail-closed operational gate for the M1 experimental PEFT candidate.
+
+This module does not ship model weights, download artifacts, train, publish, or
+call a remote provider.  It will run bounded inference only when every local
+artifact and evidence receipt matches the immutable manifest, the local runtime
+and GPU pass admission, and the operator binds the exact in-process provider
+identity.  ``NOT_PROMOTED`` is always preserved and production use is rejected.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import gc
+import hashlib
+import importlib.util
+import json
+import os
+import shutil
+import subprocess
+import threading
+import time
+from collections import Counter
+from datetime import datetime, timezone
+from pathlib import Path
+from typing import Any
+
+from fastapi import Request
+
+
+SCHEMA = "szl.m1-operational-gate/v1"
+INFER_SCHEMA = "szl.m1-experimental-inference-request/v1"
+RECEIPT_SCHEMA = "szl.m1-experimental-inference-receipt/v1"
+READY = "READY_EXPERIMENTAL"
+BLOCKED = "BLOCKED"
+UNAVAILABLE = "UNAVAILABLE"
+PASS = "PASS"
+MANIFEST_DIR = Path(__file__).resolve().parent / "model_release" / "m1"
+MANIFEST_PATH = MANIFEST_DIR / "operational-manifest.json"
+PAGE_PATH = Path(__file__).resolve().parent / "web" / "m1-model.html"
+_INFERENCE_LOCK = threading.Lock()
+
+
+class ContractError(ValueError):
+    """The caller supplied a request outside the fixed experimental contract."""
+
+
+def _now() -> str:
+    return datetime.now(timezone.utc).isoformat().replace("+00:00", "Z")
+
+
+def _canonical(value: Any) -> bytes:
+    return json.dumps(value, sort_keys=True, separators=(",", ":"), ensure_ascii=False).encode("utf-8")
+
+
+def _digest_bytes(value: bytes) -> str:
+    return hashlib.sha256(value).hexdigest()
+
+
+def _digest_file(path: Path) -> str:
+    digest = hashlib.sha256()
+    with path.open("rb") as handle:
+        for chunk in iter(lambda: handle.read(1024 * 1024), b""):
+            digest.update(chunk)
+    return digest.hexdigest()
+
+
+def _read_json(path: Path) -> dict[str, Any]:
+    value = json.loads(path.read_text(encoding="utf-8"))
+    if not isinstance(value, dict):
+        raise ValueError("JSON root must be an object")
+    return value
+
+
+def _load_manifest() -> dict[str, Any]:
+    value = _read_json(MANIFEST_PATH)
+    if value.get("schema") != "szl.m1-operational-manifest/v1":
+        raise ValueError("unsupported M1 manifest schema")
+    if value.get("release_state") != "NOT_PROMOTED":
+        raise ValueError("M1 manifest must remain NOT_PROMOTED")
+    if (value.get("inference_policy") or {}).get("production_eligible") is not False:
+        raise ValueError("M1 production eligibility must be false")
+    return value
+
+
+def _result(state: str, reason: str, **evidence: Any) -> dict[str, Any]:
+    return {"state": state, "reason": reason, **evidence}
+
+
+def _configured_root(env_name: str) -> Path | None:
+    raw = os.environ.get(env_name, "").strip()
+    if not raw:
+        return None
+    try:
+        return Path(raw).expanduser().resolve(strict=False)
+    except (OSError, RuntimeError):
+        return None
+
+
+def _confined_file(root: Path, relative: str) -> Path:
+    if not relative or Path(relative).is_absolute():
+        raise ValueError("artifact path must be relative")
+    target = (root / relative).resolve(strict=False)
+    try:
+        target.relative_to(root.resolve(strict=False))
+    except ValueError as exc:
+        raise ValueError("artifact path escapes configured root") from exc
+    return target
+
+
+def _verify_file(root: Path | None, spec: dict[str, Any]) -> dict[str, Any]:
+    relative = str(spec.get("path") or "")
+    public = {"path": relative, "expected_sha256": spec.get("sha256"), "expected_bytes": spec.get("bytes")}
+    if root is None:
+        return _result(UNAVAILABLE, "artifact root is not configured", **public)
+    try:
+        path = _confined_file(root, relative)
+    except ValueError as exc:
+        return _result(BLOCKED, str(exc), **public)
+    if not path.is_file():
+        return _result(UNAVAILABLE, "required local artifact is absent", **public)
+    try:
+        size = path.stat().st_size
+        expected_size = int(spec["bytes"])
+        if size != expected_size:
+            return _result(BLOCKED, "artifact byte length mismatch", actual_bytes=size, **public)
+        digest = _digest_file(path)
+    except (OSError, ValueError, KeyError) as exc:
+        return _result(UNAVAILABLE, f"artifact could not be verified ({type(exc).__name__})", **public)
+    if digest != str(spec.get("sha256") or "").lower():
+        return _result(BLOCKED, "artifact SHA-256 mismatch", actual_sha256=digest, **public)
+    return _result(PASS, "exact byte length and SHA-256 match", actual_sha256=digest, actual_bytes=size, **public)
+
+
+def _rollup_files(root: Path | None, specs: list[dict[str, Any]], label: str) -> dict[str, Any]:
+    files = [_verify_file(root, spec) for spec in specs]
+    states = {entry["state"] for entry in files}
+    state = BLOCKED if BLOCKED in states else UNAVAILABLE if UNAVAILABLE in states else PASS
+    return {
+        "state": state,
+        "reason": f"{label}: {sum(item['state'] == PASS for item in files)}/{len(files)} exact files verified",
+        "verified_files": sum(item["state"] == PASS for item in files),
+        "required_files": len(files),
+        "files": files,
+    }
+
+
+def _json_after_verified(root: Path | None, spec: dict[str, Any]) -> tuple[dict[str, Any], dict[str, Any] | None]:
+    checked = _verify_file(root, spec)
+    if checked["state"] != PASS or root is None:
+        return checked, None
+    try:
+        return checked, _read_json(_confined_file(root, str(spec["path"])))
+    except (OSError, ValueError, KeyError, json.JSONDecodeError) as exc:
+        public = {key: value for key, value in checked.items() if key not in {"state", "reason"}}
+        return _result(BLOCKED, f"verified receipt is not valid JSON ({type(exc).__name__})", **public), None
+
+
+def _metadata_evidence(manifest: dict[str, Any]) -> dict[str, Any]:
+    evidence = manifest["evidence"]
+    candidate_check, candidate = _json_after_verified(MANIFEST_DIR, evidence["candidate_manifest"])
+    evaluation_check, evaluation = _json_after_verified(MANIFEST_DIR, evidence["evaluation_manifest"])
+    if candidate_check["state"] != PASS or evaluation_check["state"] != PASS:
+        state = BLOCKED if BLOCKED in {candidate_check["state"], evaluation_check["state"]} else UNAVAILABLE
+        return _result(state, "candidate or evaluation manifest integrity failed", candidate=candidate_check, evaluation=evaluation_check)
+
+    expected_base = manifest["base"]
+    candidate_base = candidate.get("base") if candidate else {}
+    mismatches: list[str] = []
+    for key in ("repository", "revision", "architecture", "license", "license_evidence"):
+        if candidate_base.get(key) != expected_base.get(key):
+            mismatches.append(f"base.{key}")
+    if not candidate or candidate.get("candidate_id") != manifest["candidate_id"]:
+        mismatches.append("candidate_id")
+    if candidate and candidate.get("release_state") != "NOT_PROMOTED":
+        mismatches.append("release_state")
+    if candidate and candidate.get("quality_claim") != "NOT_ESTABLISHED":
+        mismatches.append("quality_claim")
+    if not evaluation or evaluation.get("candidate_id") != manifest["candidate_id"]:
+        mismatches.append("evaluation.candidate_id")
+    if evaluation and evaluation.get("promotion_decision") != "NOT_PROMOTED":
+        mismatches.append("evaluation.promotion_decision")
+    corpus_spec = (manifest.get("evidence") or {}).get("corpus_ingestion_manifest") or {}
+    corpus_policy = manifest.get("corpus_policy") or {}
+    proposal = (candidate or {}).get("full_corpus_proposal") or {}
+    expected_proposal = {
+        "relation": "PROPOSAL_ONLY_NOT_USED_BY_EXISTING_ADAPTER",
+        "manifest_path": corpus_spec.get("path"),
+        "manifest_sha256": corpus_spec.get("sha256"),
+        "brain_raw_nodes": corpus_policy.get("expected_raw_nodes"),
+        "brain_distinct_artifacts": corpus_policy.get("expected_distinct_artifacts"),
+        "formula_records": corpus_policy.get("expected_formula_records"),
+        "training_state": "NOT_RUN",
+    }
+    if proposal != expected_proposal:
+        mismatches.append("full_corpus_proposal")
+    reload_meta = ((evaluation or {}).get("measured") or {}).get("offline_reload") or {}
+    if reload_meta.get("state") != "PASS":
+        mismatches.append("evaluation.offline_reload.state")
+    if mismatches:
+        return _result(BLOCKED, "metadata consistency check failed", mismatches=mismatches,
+                       candidate=candidate_check, evaluation=evaluation_check)
+    return _result(
+        PASS,
+        "immutable candidate and evaluation metadata are consistent",
+        candidate=candidate_check,
+        evaluation=evaluation_check,
+        repository=expected_base["repository"],
+        revision=expected_base["revision"],
+        architecture=expected_base["architecture"],
+        license=expected_base["license"],
+        license_evidence=expected_base["license_evidence"],
+        license_verification_scope="metadata consistency only; not an independent legal opinion",
+        evaluation_state=evaluation.get("evaluation_state"),
+        unrun_suites=list(evaluation.get("required_unrun_suites") or []),
+        corpus_relation=proposal.get("relation"), corpus_manifest_sha256=proposal.get("manifest_sha256"),
+        quality_claim="NOT_ESTABLISHED",
+        release_state="NOT_PROMOTED",
+    )
+
+
+def _audit_corpus_ledger(spec: dict[str, Any], *, expected_schema: str,
+                         evaluation_receipt_id: str, kind: str) -> dict[str, Any]:
+    checked = _verify_file(MANIFEST_DIR, spec)
+    if checked["state"] != PASS:
+        return checked
+    try:
+        path = _confined_file(MANIFEST_DIR, str(spec["path"]))
+        expected_rows = int(spec["rows"])
+    except (KeyError, TypeError, ValueError) as exc:
+        return _result(BLOCKED, f"ledger specification is invalid ({type(exc).__name__})", file=checked)
+
+    rows = 0
+    artifact_rows = 0
+    receipts: set[str] = set()
+    identities: set[str] = set()
+    family_splits: dict[str, str] = {}
+    decisions: Counter[str] = Counter()
+    formula_status: Counter[str] = Counter()
+    formula_bindings: dict[str, dict[str, str | None]] = {}
+    errors: list[str] = []
+    vocabulary = {"KERNEL_ACCEPTED", "CONDITIONAL", "OPEN", "REFUTED"}
+    try:
+        with path.open("r", encoding="utf-8") as stream:
+            for line_number, line in enumerate(stream, 1):
+                if not line.strip():
+                    errors.append(f"line {line_number}: blank row")
+                    continue
+                try:
+                    row = json.loads(line)
+                except json.JSONDecodeError:
+                    errors.append(f"line {line_number}: invalid JSON")
+                    continue
+                rows += 1
+                if not isinstance(row, dict) or row.get("schema") != expected_schema:
+                    errors.append(f"line {line_number}: schema mismatch")
+                    continue
+                receipt_id = str(row.get("receipt_id") or "")
+                if not receipt_id or receipt_id in receipts:
+                    errors.append(f"line {line_number}: absent or duplicate receipt_id")
+                receipts.add(receipt_id)
+                identity = str(row.get("node_id") if kind == "brain" else f"{row.get('source_family')}:{row.get('formula_id')}")
+                if not identity or identity in identities:
+                    errors.append(f"line {line_number}: absent or duplicate row identity")
+                identities.add(identity)
+                if row.get("evaluation_receipt_id") != evaluation_receipt_id:
+                    errors.append(f"line {line_number}: evaluation receipt binding mismatch")
+                canonical_text = row.get("canonical_text")
+                if not isinstance(canonical_text, str) or not canonical_text:
+                    errors.append(f"line {line_number}: canonical text absent")
+                elif _digest_bytes(canonical_text.encode("utf-8")) != row.get("canonical_text_sha256"):
+                    errors.append(f"line {line_number}: canonical text digest mismatch")
+                family = str(row.get("source_family") or "")
+                split = str(row.get("source_family_split") or "")
+                if not family or split not in {"TRAIN", "HOLDOUT", "QUARANTINE"}:
+                    errors.append(f"line {line_number}: invalid source-family split")
+                elif family in family_splits and family_splits[family] != split:
+                    errors.append(f"line {line_number}: source family crosses partitions")
+                else:
+                    family_splits[family] = split
+                decision = str(row.get("training_decision") or "")
+                decisions[decision] += 1
+                if kind == "brain":
+                    if row.get("brain_anatomy_receipt_id") != receipt_id or not receipt_id.startswith("brain-node:sha256:"):
+                        errors.append(f"line {line_number}: Brain Anatomy receipt binding mismatch")
+                    if row.get("artifact_role") == "DISTINCT_ARTIFACT":
+                        artifact_rows += 1
+                    license_state = ((row.get("license") or {}).get("state"))
+                    if license_state == "UNKNOWN_ITEM_LEVEL_LICENSE" and decision != "QUARANTINE":
+                        errors.append(f"line {line_number}: unknown-license row escaped quarantine")
+                    if row.get("formula_status") is not None:
+                        formula_id = str(row.get("formula_id") or "")
+                        if (not formula_id or formula_id in formula_bindings or
+                                row.get("formula_status") not in vocabulary or
+                                not str(row.get("formula_receipt_id") or "").startswith("formula:sha256:")):
+                            errors.append(f"line {line_number}: formula node status/receipt invalid")
+                        else:
+                            formula_bindings[formula_id] = {
+                                "formula_receipt_id": str(row["formula_receipt_id"]),
+                                "brain_anatomy_receipt_id": receipt_id,
+                            }
+                else:
+                    status = str(row.get("formula_status") or "")
+                    formula_status[status] += 1
+                    if not receipt_id.startswith("formula:sha256:") or row.get("formula_receipt_id") != receipt_id:
+                        errors.append(f"line {line_number}: formula receipt binding mismatch")
+                    if status not in vocabulary or split != "HOLDOUT":
+                        errors.append(f"line {line_number}: formula status/split invalid")
+                    expected_role = "HOLDOUT_POSITIVE" if status == "KERNEL_ACCEPTED" else (
+                        "HOLDOUT_NEGATIVE" if status == "REFUTED" else "HOLDOUT_ABSTENTION"
+                    )
+                    if decision != expected_role:
+                        errors.append(f"line {line_number}: formula role does not match status")
+                    if bool(row.get("abstention_required")) != (status in {"OPEN", "CONDITIONAL"}):
+                        errors.append(f"line {line_number}: abstention label mismatch")
+                    if bool(row.get("negative_example")) != (status == "REFUTED"):
+                        errors.append(f"line {line_number}: negative-example label mismatch")
+                    if row.get("brain_anatomy_receipt_id"):
+                        formula_bindings[str(row.get("formula_id") or "")] = {
+                            "formula_receipt_id": receipt_id,
+                            "brain_anatomy_receipt_id": str(row["brain_anatomy_receipt_id"]),
+                        }
+                if len(errors) >= 20:
+                    break
+    except OSError as exc:
+        return _result(UNAVAILABLE, f"ledger could not be read ({type(exc).__name__})", file=checked)
+
+    if rows != expected_rows:
+        errors.append(f"row count {rows} != expected {expected_rows}")
+    if errors:
+        return _result(BLOCKED, "corpus ledger semantic verification failed", file=checked,
+                       errors=errors[:20], rows_observed=rows, rows_expected=expected_rows)
+    return _result(
+        PASS, "exact ledger bytes and every decision row verified",
+        file=checked, rows=rows, distinct_artifact_rows=artifact_rows,
+        source_family_split=dict(sorted(family_splits.items())),
+        decisions=dict(sorted(decisions.items())), formula_status=dict(sorted(formula_status.items())),
+        formula_bindings=dict(sorted(formula_bindings.items())),
+    )
+
+
+def _corpus_evidence(manifest: dict[str, Any]) -> dict[str, Any]:
+    evidence = manifest.get("evidence") or {}
+    policy = manifest.get("corpus_policy") or {}
+    try:
+        summary_check, summary = _json_after_verified(MANIFEST_DIR, evidence["corpus_ingestion_manifest"])
+        if summary_check["state"] != PASS or summary is None:
+            return summary_check
+        if summary.get("schema") != "szl.m1-corpus-ingestion-manifest/v1":
+            return _result(BLOCKED, "corpus ingestion manifest schema mismatch", file=summary_check)
+        evaluation_spec = evidence["evaluation_manifest"]
+        evaluation_receipt_id = f"m1-evaluation:sha256:{evaluation_spec['sha256']}"
+        brain = _audit_corpus_ledger(
+            evidence["brain_ingest_ledger"], expected_schema="szl.m1-brain-ingest-decision/v1",
+            evaluation_receipt_id=evaluation_receipt_id, kind="brain",
+        )
+        formulas = _audit_corpus_ledger(
+            evidence["formula_curriculum_ledger"], expected_schema="szl.m1-formula-curriculum-decision/v1",
+            evaluation_receipt_id=evaluation_receipt_id, kind="formula",
+        )
+    except (KeyError, TypeError, ValueError) as exc:
+        return _result(BLOCKED, f"corpus evidence configuration invalid ({type(exc).__name__})")
+    if BLOCKED in {brain["state"], formulas["state"]}:
+        return _result(BLOCKED, "corpus ledger integrity or semantic gate failed", manifest=summary_check,
+                       brain_ledger=brain, formula_ledger=formulas)
+    if UNAVAILABLE in {brain["state"], formulas["state"]}:
+        return _result(UNAVAILABLE, "corpus ledger is unavailable", manifest=summary_check,
+                       brain_ledger=brain, formula_ledger=formulas)
+
+    coverage = summary.get("coverage") or {}
+    source = summary.get("source_snapshot") or {}
+    ledgers = summary.get("ledgers") or {}
+    resulting = summary.get("resulting_evaluation_receipt") or {}
+    expected_nodes = int(policy.get("expected_raw_nodes", -1))
+    expected_artifacts = int(policy.get("expected_distinct_artifacts", -1))
+    expected_formulas = int(policy.get("expected_formula_records", -1))
+    mismatches: list[str] = []
+    if summary.get("candidate_id") != manifest.get("candidate_id"):
+        mismatches.append("candidate_id")
+    if summary.get("release_state") != "NOT_PROMOTED" or summary.get("training_state") != "NOT_RUN":
+        mismatches.append("release/training state")
+    if summary.get("training_relation") != policy.get("training_relation"):
+        mismatches.append("training relation")
+    if source.get("raw_node_count") != expected_nodes or brain.get("rows") != expected_nodes:
+        mismatches.append("raw node coverage")
+    if source.get("distinct_artifact_count") != expected_artifacts or brain.get("distinct_artifact_rows") != expected_artifacts:
+        mismatches.append("distinct artifact coverage")
+    if coverage.get("node_decisions_total") != expected_nodes or coverage.get("node_decisions_expected") != expected_nodes or coverage.get("node_decision_coverage") != 1.0:
+        mismatches.append("decision coverage")
+    if policy.get("require_raw_brain_training_quarantine") is True and (
+        coverage.get("raw_nodes_training_quarantined") != expected_nodes
+        or coverage.get("training_eligible_nodes") != 0
+        or brain.get("decisions") != {"QUARANTINE": expected_nodes}
+    ):
+        mismatches.append("raw Brain training quarantine")
+    if coverage.get("formula_records_current_versioned_sources") != expected_formulas or formulas.get("rows") != expected_formulas:
+        mismatches.append("formula coverage")
+    if resulting.get("receipt_id") != evaluation_receipt_id or resulting.get("sha256") != evaluation_spec.get("sha256"):
+        mismatches.append("evaluation receipt binding")
+    if resulting.get("state") != "INCOMPLETE" or resulting.get("promotion_decision") != "NOT_PROMOTED":
+        mismatches.append("evaluation/promotion boundary")
+    if brain.get("formula_bindings") != formulas.get("formula_bindings"):
+        mismatches.append("Brain/formula Anatomy receipt crosswalk")
+    for summary_name, evidence_name in (("brain_nodes", "brain_ingest_ledger"), ("formulas", "formula_curriculum_ledger")):
+        declared = ledgers.get(summary_name) or {}
+        expected = evidence.get(evidence_name) or {}
+        if any(declared.get(key) != expected.get(key) for key in ("path", "bytes", "sha256")):
+            mismatches.append(f"{summary_name} ledger binding")
+    family_split = summary.get("source_family_split") or {}
+    if policy.get("require_source_family_isolation") is not True or any(
+        not isinstance(value, dict) or value.get("split") not in {"TRAIN", "HOLDOUT", "QUARANTINE"}
+        for value in family_split.values()
+    ):
+        mismatches.append("source family isolation")
+    if policy.get("allow_unknown_license_for_training") is not False:
+        mismatches.append("unknown-license policy")
+    if policy.get("require_raw_brain_training_quarantine") is not True:
+        mismatches.append("raw Brain quarantine policy")
+    if mismatches:
+        return _result(BLOCKED, "corpus manifest coverage contract mismatch", mismatches=mismatches,
+                       manifest=summary_check, brain_ledger=brain, formula_ledger=formulas)
+    return _result(
+        PASS,
+        "full Brain decision coverage and formula holdout curriculum verified; quarantines retained",
+        manifest=summary_check, brain_ledger=brain, formula_ledger=formulas,
+        corpus_receipt_id=f"m1-corpus:sha256:{evidence['corpus_ingestion_manifest']['sha256']}",
+        evaluation_receipt_id=evaluation_receipt_id,
+        coverage=coverage, source_snapshot=source, source_family_split=family_split,
+        training_state="NOT_RUN", training_relation=summary.get("training_relation"),
+        quality_claim="NOT_ESTABLISHED", release_state="NOT_PROMOTED",
+    )
+
+
+def _training_evidence(manifest: dict[str, Any], run_root: Path | None) -> dict[str, Any]:
+    checked, receipt = _json_after_verified(run_root, manifest["evidence"]["training_receipt"])
+    if checked["state"] != PASS or receipt is None:
+        return checked
+    mismatches: list[str] = []
+    base = receipt.get("base_model") or {}
+    if receipt.get("schema") != "szl.bounded-lora-training-receipt/v1":
+        mismatches.append("schema")
+    if receipt.get("state") != "COMPLETED":
+        mismatches.append("state")
+    if receipt.get("evidence_label") != "MEASURED":
+        mismatches.append("evidence_label")
+    if receipt.get("receipt_sha256") != manifest["evidence"]["training_receipt"]["internal_sha256"]:
+        mismatches.append("receipt_sha256")
+    if base.get("repo") != manifest["base"]["repository"]:
+        mismatches.append("base_model.repo")
+    if base.get("revision") != manifest["base"]["revision"]:
+        mismatches.append("base_model.revision")
+    if base.get("network_download_allowed") is not False:
+        mismatches.append("base_model.network_download_allowed")
+    if (receipt.get("evaluation") or {}).get("quality_claim") != "NOT_ESTABLISHED":
+        mismatches.append("evaluation.quality_claim")
+    if (receipt.get("artifacts") or {}).get("promotion_state") != "NOT_PROMOTED":
+        mismatches.append("artifacts.promotion_state")
+    receipt_files = {item.get("path"): item for item in (receipt.get("artifacts") or {}).get("files", [])}
+    for expected in manifest["adapter"]["files"]:
+        actual = receipt_files.get(expected["path"])
+        if not actual or actual.get("sha256") != expected["sha256"] or actual.get("bytes") != expected["bytes"]:
+            mismatches.append(f"artifacts.files:{expected['path']}")
+    if mismatches:
+        return _result(BLOCKED, "training receipt content does not match the operational manifest",
+                       mismatches=mismatches, file=checked)
+    return _result(PASS, "training receipt integrity and lineage match", file=checked,
+                   measured_state="COMPLETED", quality_claim="NOT_ESTABLISHED",
+                   release_state="NOT_PROMOTED")
+
+
+def _reload_evidence(manifest: dict[str, Any], run_root: Path | None) -> dict[str, Any]:
+    checked, receipt = _json_after_verified(run_root, manifest["evidence"]["reload_receipt"])
+    if checked["state"] != PASS or receipt is None:
+        return checked
+    adapter_sha = next(
+        item["sha256"] for item in manifest["adapter"]["files"]
+        if item["path"] == "adapter/adapter_model.safetensors"
+    )
+    mismatches = []
+    if receipt.get("schema") != "szl.adapter-reload-smoke/v1":
+        mismatches.append("schema")
+    if receipt.get("state") != "PASS":
+        mismatches.append("state")
+    if receipt.get("offline") is not True:
+        mismatches.append("offline")
+    if receipt.get("adapter_model_sha256") != adapter_sha:
+        mismatches.append("adapter_model_sha256")
+    if not receipt.get("generated_text_sha256"):
+        mismatches.append("generated_text_sha256")
+    if mismatches:
+        return _result(BLOCKED, "offline reload receipt content mismatch", mismatches=mismatches, file=checked)
+    return _result(PASS, "offline reload receipt verified", file=checked,
+                   interpretation="COMPATIBILITY_ONLY_NOT_QUALITY",
+                   generated_text_sha256=receipt["generated_text_sha256"])
+
+
+def _runtime_provider(manifest: dict[str, Any]) -> dict[str, Any]:
+    expected = manifest["provider"]["id"]
+    configured = os.environ.get("A11OY_M1_PROVIDER_ID", "").strip()
+    if os.environ.get("A11OY_M1_BASE_URL", "").strip():
+        return _result(BLOCKED, "remote provider/base URL is forbidden for M1", expected_provider_id=expected)
+    if not configured:
+        return _result(UNAVAILABLE, "A11OY_M1_PROVIDER_ID is not configured", expected_provider_id=expected)
+    if configured != expected:
+        return _result(BLOCKED, "configured provider identity mismatch", expected_provider_id=expected)
+    packages = {name: importlib.util.find_spec(name) is not None for name in ("torch", "transformers", "peft")}
+    if not all(packages.values()):
+        return _result(UNAVAILABLE, "local PEFT runtime dependencies are unavailable",
+                       provider_id=configured, transport="IN_PROCESS_ONLY", packages=packages)
+    return _result(PASS, "exact local in-process provider identity and runtime are available",
+                   provider_id=configured, transport="IN_PROCESS_ONLY", network_allowed=False, packages=packages)
+
+
+def _gpu_snapshot() -> dict[str, Any]:
+    executable = shutil.which("nvidia-smi") or shutil.which("nvidia-smi.exe")
+    if not executable:
+        return _result(UNAVAILABLE, "nvidia-smi is unavailable")
+    query = [
+        executable,
+        "--query-gpu=index,name,memory.total,memory.free,utilization.gpu,temperature.gpu",
+        "--format=csv,noheader,nounits",
+    ]
+    try:
+        completed = subprocess.run(query, capture_output=True, text=True, timeout=3, check=False, shell=False)
+    except (OSError, subprocess.SubprocessError) as exc:
+        return _result(UNAVAILABLE, f"GPU telemetry unavailable ({type(exc).__name__})")
+    if completed.returncode != 0:
+        return _result(UNAVAILABLE, "nvidia-smi telemetry command failed")
+    target = os.environ.get("A11OY_M1_GPU_INDEX", "0").strip()
+    rows = []
+    for raw in completed.stdout.splitlines():
+        parts = [part.strip() for part in raw.split(",")]
+        if len(parts) != 6:
+            continue
+        try:
+            rows.append({
+                "index": parts[0], "name": parts[1], "total_memory_mib": int(float(parts[2])),
+                "free_memory_mib": int(float(parts[3])), "utilization_pct": int(float(parts[4])),
+                "temperature_c": int(float(parts[5])),
+            })
+        except ValueError:
+            continue
+    selected = next((row for row in rows if row["index"] == target), None)
+    if selected is None:
+        return _result(UNAVAILABLE, "configured GPU index was not reported", gpu_index=target)
+    return _result(PASS, "live GPU telemetry measured", **selected)
+
+
+def _gpu_admission(manifest: dict[str, Any]) -> dict[str, Any]:
+    snapshot = _gpu_snapshot()
+    if snapshot["state"] != PASS:
+        return snapshot
+    policy = manifest["gpu_admission"]
+    reasons = []
+    if snapshot["name"] != manifest["provider"]["expected_gpu_name"]:
+        reasons.append("GPU identity mismatch")
+    if snapshot["free_memory_mib"] < policy["minimum_free_memory_mib"]:
+        reasons.append("insufficient free GPU memory")
+    if snapshot["utilization_pct"] > policy["maximum_utilization_pct"]:
+        reasons.append("GPU utilization exceeds admission ceiling")
+    if snapshot["temperature_c"] > policy["maximum_temperature_c"]:
+        reasons.append("GPU temperature exceeds admission ceiling")
+    if reasons:
+        return _result(BLOCKED, "; ".join(reasons), telemetry=snapshot, policy=policy)
+    return _result(PASS, "live GPU identity and resource admission pass", telemetry=snapshot, policy=policy)
+
+
+def operational_status() -> dict[str, Any]:
+    try:
+        manifest = _load_manifest()
+    except (OSError, ValueError, json.JSONDecodeError, KeyError) as exc:
+        return {
+            "schema": SCHEMA, "candidate_id": "a11oy-evidence-1.5b-sft-lora",
+            "operational_state": BLOCKED, "release_state": "NOT_PROMOTED",
+            "production_eligible": False, "inference_mode": "DISABLED",
+            "reason": f"operational manifest invalid ({type(exc).__name__})", "checks": {},
+        }
+
+    run_root = _configured_root("A11OY_M1_RUN_ROOT")
+    base_root = _configured_root("A11OY_M1_BASE_SNAPSHOT")
+    metadata = _metadata_evidence(manifest)
+    corpus = _corpus_evidence(manifest)
+    base = _rollup_files(base_root, manifest["base"]["files"], "base snapshot")
+    adapter = _rollup_files(run_root, manifest["adapter"]["files"], "adapter")
+    training = _training_evidence(manifest, run_root)
+    reload = _reload_evidence(manifest, run_root)
+    provider = _runtime_provider(manifest)
+    gpu = _gpu_admission(manifest)
+
+    tokenizer_paths = {"added_tokens.json", "merges.txt", "special_tokens_map.json", "tokenizer.json", "tokenizer_config.json", "vocab.json"}
+    tokenizer_files = [item for item in base["files"] if item["path"] in tokenizer_paths]
+    tokenizer_state = BLOCKED if any(item["state"] == BLOCKED for item in tokenizer_files) else (
+        UNAVAILABLE if any(item["state"] == UNAVAILABLE for item in tokenizer_files) else PASS
+    )
+    tokenizer = {
+        "state": tokenizer_state,
+        "reason": f"tokenizer: {sum(item['state'] == PASS for item in tokenizer_files)}/{len(tokenizer_files)} exact files verified",
+        "files": tokenizer_files,
+    }
+    checks = {
+        "metadata": metadata, "corpus_ingestion": corpus,
+        "base_weights": base, "adapter_weights": adapter,
+        "tokenizer": tokenizer, "training_receipt": training, "offline_reload": reload,
+        "evaluation_receipt": {
+            "state": metadata["state"],
+            "reason": "evaluation receipt integrity verified; broad quality evaluation remains incomplete" if metadata["state"] == PASS else metadata["reason"],
+            "quality_claim": "NOT_ESTABLISHED", "release_state": "NOT_PROMOTED",
+            "evaluation_state": metadata.get("evaluation_state"), "unrun_suites": metadata.get("unrun_suites", []),
+        },
+        "provider_identity": provider, "gpu_admission": gpu,
+    }
+    mandatory = [entry["state"] for entry in checks.values()]
+    state = BLOCKED if BLOCKED in mandatory else UNAVAILABLE if UNAVAILABLE in mandatory else READY
+    enabled = state == READY
+    stages = {
+        "corpus": {
+            "state": "FULL_DECISION_LEDGER_VERIFIED" if corpus["state"] == PASS else corpus["state"],
+            "raw_nodes": (corpus.get("coverage") or {}).get("node_decisions_total"),
+            "distinct_artifacts": (corpus.get("coverage") or {}).get("distinct_artifacts"),
+            "quarantined_or_excluded": (corpus.get("coverage") or {}).get("quarantined_or_excluded_nodes"),
+            "formula_records": (corpus.get("coverage") or {}).get("formula_records_current_versioned_sources"),
+            "training": "NOT_RUN",
+        },
+        "weights": {"state": PASS if base["state"] == adapter["state"] == tokenizer["state"] == PASS else state,
+                    "base": base["state"], "adapter": adapter["state"], "tokenizer": tokenizer["state"]},
+        "load": {"state": "READY_TO_LOAD" if provider["state"] == reload["state"] == gpu["state"] == PASS else state,
+                 "provider": provider["state"], "offline_reload": reload["state"], "gpu": gpu["state"]},
+        "evaluation": {"state": "EVIDENCE_VERIFIED_WITH_LIMITS" if metadata["state"] == PASS else metadata["state"],
+                       "quality_claim": "NOT_ESTABLISHED", "promotion": "NOT_PROMOTED"},
+        "inference": {"state": "ENABLED_EXPERIMENTAL_LOCAL_ONLY" if enabled else "DISABLED",
+                      "production": "BLOCKED", "network": "DISABLED"},
+    }
+    return {
+        "schema": SCHEMA, "candidate_id": manifest["candidate_id"], "checked_at": _now(),
+        "operational_state": state, "release_state": "NOT_PROMOTED", "quality_claim": "NOT_ESTABLISHED",
+        "production_eligible": False, "inference_mode": "EXPERIMENTAL_LOCAL_ONLY" if enabled else "DISABLED",
+        "effectors": {"network": "DISABLED", "download": "DISABLED", "training": "DISABLED", "publishing": "DISABLED"},
+        "configured": {"run_root": run_root is not None, "base_snapshot": base_root is not None,
+                       "provider_identity": bool(os.environ.get("A11OY_M1_PROVIDER_ID", "").strip())},
+        "stages": stages, "checks": checks,
+        "corpus_coverage": corpus.get("coverage", {}),
+    }
+
+
+async def _bounded_json(request: Request, maximum: int) -> dict[str, Any]:
+    declared = request.headers.get("content-length")
+    if declared is not None:
+        try:
+            if int(declared) < 0 or int(declared) > maximum:
+                raise ContractError(f"request body exceeds {maximum} bytes")
+        except ValueError as exc:
+            raise ContractError("content-length must be a non-negative integer") from exc
+    body = bytearray()
+    async for chunk in request.stream():
+        if len(body) + len(chunk) > maximum:
+            raise ContractError(f"request body exceeds {maximum} bytes")
+        body.extend(chunk)
+    try:
+        value = json.loads(bytes(body).decode("utf-8"))
+    except (UnicodeDecodeError, json.JSONDecodeError) as exc:
+        raise ContractError("body must be one JSON object") from exc
+    if not isinstance(value, dict):
+        raise ContractError("body must be one JSON object")
+    return value
+
+
+def _parse_inference_request(payload: dict[str, Any], manifest: dict[str, Any]) -> dict[str, Any]:
+    required = {"schema", "prompt", "max_new_tokens", "temperature", "requested_tier", "provider_id"}
+    if set(payload) != required:
+        raise ContractError(f"fields must be exactly {sorted(required)}")
+    if payload.get("schema") != INFER_SCHEMA:
+        raise ContractError("unsupported inference request schema")
+    if payload.get("requested_tier") != "EXPERIMENTAL_LOCAL_ONLY":
+        raise ContractError("production and promoted tiers are forbidden for M1")
+    if payload.get("provider_id") != manifest["provider"]["id"]:
+        raise ContractError("request provider identity mismatch")
+    prompt = payload.get("prompt")
+    if not isinstance(prompt, str) or not prompt.strip() or len(prompt) > manifest["inference_policy"]["max_prompt_chars"]:
+        raise ContractError("prompt must be non-empty and within the character limit")
+    if any(ord(char) < 32 and char not in "\n\t\r" for char in prompt):
+        raise ContractError("prompt contains disallowed control characters")
+    max_new_tokens = payload.get("max_new_tokens")
+    if not isinstance(max_new_tokens, int) or isinstance(max_new_tokens, bool) or not 1 <= max_new_tokens <= manifest["inference_policy"]["max_new_tokens"]:
+        raise ContractError("max_new_tokens is outside the bounded policy")
+    temperature = payload.get("temperature")
+    if not isinstance(temperature, (int, float)) or isinstance(temperature, bool) or not 0 <= float(temperature) <= 1:
+        raise ContractError("temperature must be within [0,1]")
+    return {"prompt": prompt, "max_new_tokens": max_new_tokens, "temperature": float(temperature),
+            "provider_id": payload["provider_id"]}
+
+
+def _local_peft_inference(parsed: dict[str, Any], manifest: dict[str, Any]) -> str:
+    """Load exact local paths with local_files_only and run one bounded turn."""
+    import torch
+    from peft import PeftModel
+    from transformers import AutoModelForCausalLM, AutoTokenizer
+
+    run_root = _configured_root("A11OY_M1_RUN_ROOT")
+    base_root = _configured_root("A11OY_M1_BASE_SNAPSHOT")
+    if run_root is None or base_root is None:
+        raise RuntimeError("artifact roots unavailable")
+    adapter_root = _confined_file(run_root, "adapter/adapter_config.json").parent
+    gpu_index = int(os.environ.get("A11OY_M1_GPU_INDEX", "0"))
+    model = None
+    tuned = None
+    try:
+        torch.cuda.set_device(gpu_index)
+        tokenizer = AutoTokenizer.from_pretrained(str(adapter_root), local_files_only=True, trust_remote_code=False)
+        model = AutoModelForCausalLM.from_pretrained(
+            str(base_root), local_files_only=True, trust_remote_code=False, device_map={"": gpu_index}
+        )
+        tuned = PeftModel.from_pretrained(
+            model, str(adapter_root), local_files_only=True, is_trainable=False
+        )
+        tuned.eval()
+        inputs = tokenizer(parsed["prompt"], return_tensors="pt", truncation=True, max_length=384)
+        inputs = {key: value.to(f"cuda:{gpu_index}") for key, value in inputs.items()}
+        kwargs: dict[str, Any] = {
+            "max_new_tokens": parsed["max_new_tokens"], "use_cache": True,
+            "do_sample": parsed["temperature"] > 0,
+        }
+        if parsed["temperature"] > 0:
+            kwargs["temperature"] = parsed["temperature"]
+        with torch.inference_mode():
+            output = tuned.generate(**inputs, **kwargs)
+        new_tokens = output[0, inputs["input_ids"].shape[1]:]
+        text = tokenizer.decode(new_tokens, skip_special_tokens=True).strip()
+        if not text:
+            raise RuntimeError("local model returned no generated text")
+        return text
+    finally:
+        del tuned, model
+        gc.collect()
+        if torch.cuda.is_available():
+            torch.cuda.empty_cache()
+
+
+def run_inference(payload: dict[str, Any]) -> tuple[dict[str, Any], int]:
+    try:
+        manifest = _load_manifest()
+        parsed = _parse_inference_request(payload, manifest)
+    except (OSError, ValueError, json.JSONDecodeError, KeyError, ContractError) as exc:
+        return {"schema": SCHEMA, "state": BLOCKED, "release_state": "NOT_PROMOTED",
+                "production_eligible": False, "error": str(exc)}, 422
+
+    status = operational_status()
+    if status["operational_state"] != READY:
+        code = 409 if status["operational_state"] == BLOCKED else 503
+        return {"schema": SCHEMA, "state": status["operational_state"], "release_state": "NOT_PROMOTED",
+                "production_eligible": False, "inference": None, "gate": status}, code
+    if not _INFERENCE_LOCK.acquire(blocking=False):
+        return {"schema": SCHEMA, "state": BLOCKED, "release_state": "NOT_PROMOTED",
+                "production_eligible": False, "error": "bounded M1 concurrency slot is busy"}, 429
+    started = time.perf_counter()
+    try:
+        # Re-run the full exact gate immediately before executing. No hash cache is
+        # used, so a changed file or GPU state fails closed.
+        preflight = operational_status()
+        if preflight["operational_state"] != READY:
+            code = 409 if preflight["operational_state"] == BLOCKED else 503
+            return {"schema": SCHEMA, "state": preflight["operational_state"],
+                    "release_state": "NOT_PROMOTED", "production_eligible": False,
+                    "inference": None, "gate": preflight}, code
+        try:
+            text = _local_peft_inference(parsed, manifest)
+        except Exception as exc:
+            return {"schema": SCHEMA, "state": UNAVAILABLE, "release_state": "NOT_PROMOTED",
+                    "production_eligible": False, "inference": None,
+                    "error": f"local inference failed ({type(exc).__name__}); no output fabricated"}, 503
+        receipt_core = {
+            "schema": RECEIPT_SCHEMA, "candidate_id": manifest["candidate_id"],
+            "release_state": "NOT_PROMOTED", "quality_claim": "NOT_ESTABLISHED",
+            "tier": "EXPERIMENTAL_LOCAL_ONLY", "provider_id": manifest["provider"]["id"],
+            "prompt_sha256": _digest_bytes(parsed["prompt"].encode("utf-8")),
+            "output_sha256": _digest_bytes(text.encode("utf-8")),
+            "max_new_tokens": parsed["max_new_tokens"], "temperature": parsed["temperature"],
+            "duration_ms": round((time.perf_counter() - started) * 1000, 3), "completed_at": _now(),
+            "network": "DISABLED", "production_eligible": False,
+            "corpus_receipt_id": preflight["checks"]["corpus_ingestion"]["corpus_receipt_id"],
+            "evaluation_receipt_id": preflight["checks"]["corpus_ingestion"]["evaluation_receipt_id"],
+            "corpus_relation": "PROPOSAL_ONLY_NOT_USED_BY_EXISTING_ADAPTER",
+        }
+        receipt = {**receipt_core, "receipt_sha256": _digest_bytes(_canonical(receipt_core)),
+                   "signature_state": "UNSIGNED_DETERMINISTIC_DIGEST_ONLY"}
+        return {"schema": SCHEMA, "state": "RESULT", "release_state": "NOT_PROMOTED",
+                "quality_claim": "NOT_ESTABLISHED", "production_eligible": False,
+                "inference": {"text": text, "provider_id": manifest["provider"]["id"]},
+                "receipt": receipt}, 200
+    finally:
+        _INFERENCE_LOCK.release()
+
+
+def register(app: Any, ns: str = "a11oy") -> dict[str, Any]:
+    from fastapi.responses import FileResponse, JSONResponse
+
+    prefix = f"/api/{ns}/v1/models/m1"
+    before = {id(route) for route in app.router.routes}
+
+    @app.get(prefix)
+    async def m1_status():  # noqa: ANN202
+        return JSONResponse(operational_status())
+
+    @app.post(f"{prefix}/infer")
+    async def m1_infer(request: Request):  # noqa: ANN202
+        try:
+            manifest = _load_manifest()
+            payload = await _bounded_json(request, int(manifest["inference_policy"]["max_request_bytes"]))
+        except (ContractError, OSError, ValueError, json.JSONDecodeError, KeyError) as exc:
+            return JSONResponse({"schema": SCHEMA, "state": BLOCKED, "release_state": "NOT_PROMOTED",
+                                 "production_eligible": False, "error": str(exc)}, status_code=422)
+        result, status_code = await asyncio.to_thread(run_inference, payload)
+        return JSONResponse(result, status_code=status_code)
+
+    @app.get("/models/m1")
+    async def m1_page() -> Any:
+        if not PAGE_PATH.is_file():
+            return JSONResponse({"state": UNAVAILABLE, "error": "M1 status page is unavailable"}, status_code=503)
+        return FileResponse(PAGE_PATH, media_type="text/html")
+
+    added = [route for route in app.router.routes if id(route) not in before]
+    for route in added:
+        app.router.routes.remove(route)
+    for route in reversed(added):
+        app.router.routes.insert(0, route)
+    return {"registered": True, "routes": [prefix, f"{prefix}/infer", "/models/m1"],
+            "release_state": "NOT_PROMOTED", "production_eligible": False}
+
+
+__all__ = [
+    "BLOCKED", "ContractError", "INFER_SCHEMA", "PASS", "READY", "SCHEMA",
+    "UNAVAILABLE", "operational_status", "register", "run_inference",
+]

szl_nemo_agents.py

@@ -42,8 +42,8 @@ HONESTY (Doctrine v11 — NEVER violate)
     ROADMAP inside the same payload (e.g. SZL-Nemo's on-box 2-GPU serving + Z3
     cross-check for qhawaq + numpy-SIMD perf for waqay). We NEVER fake-LIVE a
     capability that is not running, and we NEVER fabricate a metric.
-  * SZL-Nemo is a GOVERNED model built on an OPEN base (default Qwen3-32B,
-    Apache-2.0). We NEVER claim a from-scratch model, 550B params, a local
+  * SZL-Nemo is a governed recipe built on NVIDIA Nemotron 3 Nano 4B. We NEVER
+    claim an SZL fine-tune, a from-scratch model, 550B params, a local
     Nemotron-Ultra, or any certification. The base/license are read straight from
     a11oy_nemo_core.NEMO_BASE.
   * locked theorems = EXACTLY 8 {F1,F4,F7,F11,F12,F18,F19,F22} @ kernel c7c0ba17
@@ -159,8 +159,8 @@ def _khipu_sign(surface: str, summary: dict) -> dict:
 # /status BUILDERS — each reads ONLY the real backing module's live data.
 # ===========================================================================
 def _nemo_status() -> dict:
-    """SZL-Nemo: governed Qwen3-32B (Apache-2.0) base. LIVE governed-MoE router +
-    signed receipts + τ-bench self-improvement; on-box 2-GPU serving is ROADMAP."""
+    """SZL-Nemo: governed Nemotron 3 Nano 4B recipe. Router and runtime
+    readiness are reported independently; the recipe is not an SZL fine-tune."""
     base = {}
     experts: list = []
     tiers: list = []
@@ -179,7 +179,8 @@ def _nemo_status() -> dict:
         nemo_version = card.get("version")
     except Exception as e:  # noqa: BLE001
         nemo_name, nemo_version = "SZL-Nemo", None
-        base = {"default_base": "Qwen3-32B", "default_base_license": "Apache-2.0",
+        base = {"default_base": "NVIDIA Nemotron 3 Nano 4B",
+                "default_base_license": "NVIDIA Nemotron Open Model License",
                 "_note": "a11oy_nemo_core not importable here (%r)" % e}
 
     payload = {
@@ -189,23 +190,24 @@ def _nemo_status() -> dict:
         "lifecycle": "LIVE",
         "model": nemo_name,
         "version": nemo_version,
-        "model_governed": "%s (governed)" % base.get("default_base", "Qwen3-32B"),
-        "base": base.get("default_base", "Qwen3-32B"),
-        "base_license": base.get("default_base_license", "Apache-2.0"),
+        "model_governed": "%s (governed recipe)" % base.get("default_base", "UNKNOWN"),
+        "base": base.get("default_base", "UNKNOWN"),
+        "base_license": base.get("default_base_license", "UNKNOWN"),
         "base_url": base.get("default_base_url"),
-        "served_tier": "governed gateway (governed-MoE domain-expert router); "
-                       "sovereign-local 2-GPU serving is ROADMAP→Forge, cloud-NIM tier sovereign:false",
-        "provenance": ("SZL-Nemo is OUR governance/routing/self-improvement layer wrapped "
-                       "around an OPEN base (default Qwen3-32B, Apache-2.0). We did NOT train "
-                       "a foundation model from scratch."),
+        "served_tier": "exact-tag loopback Ollama runtime when identity-bound; "
+                       "cloud-NIM tier remains sovereign:false",
+        "provenance": ("SZL-Nemo is the SZL governance/routing layer wrapped around "
+                       "NVIDIA Nemotron 3 Nano 4B. The recipe is not an SZL fine-tune; "
+                       "runtime readiness and model identity are separate evidence."),
         "what_is_live": [
             "Λ-governed domain-expert MoE router (signed selection receipts) — LIVE",
             "τ-bench self-improvement loop signing the measured delta — LIVE",
             "model card / tiers / experts endpoints — LIVE",
+            "exact upstream-manifest and derived-tag runtime probe — LIVE",
         ],
         "what_is_roadmap": [
-            "On-box sovereign-local 2-GPU serving (Forge, founder-gated) — ROADMAP",
-            "MTP / speculative decoding on-box config — ROADMAP (app-layer view only)",
+            "Fine-tuned SZL-Nemo weights — NOT CREATED",
+            "MTP / speculative decoding — ROADMAP (not enabled on verified Ollama path)",
         ],
         "experts": experts,
         "tiers": tiers,
@@ -537,8 +539,11 @@ def _selftest() -> dict:
         out[name] = {"lifecycle": s["lifecycle"], "khipu_kind": s.get("khipu", {}).get("kind")}
     # SZL-Nemo honesty: governed open base, never from-scratch.
     n = _nemo_status()
-    assert n["base_license"] in ("Apache-2.0",), n["base_license"]
-    assert "from-scratch" not in json.dumps(n).lower() or "did NOT train" in json.dumps(n)
+    assert n["base_license"] == "NVIDIA Nemotron Open Model License", n["base_license"]
+    rendered = json.dumps(n).lower()
+    assert ("from-scratch" not in rendered
+            or "not an szl fine-tune" in rendered
+            or "did not train" in rendered)
     out["nemo_base"] = (n["base"], n["base_license"])
     # No banned codename leaks anywhere.
     served = json.dumps(served_parts).lower()

szl_numerics_adapter.py

@@ -0,0 +1,532 @@
+# SPDX-License-Identifier: Apache-2.0
+"""Fail-closed external numerical-engine frontier.
+
+The host accepts only three fixed numeric operations.  It never accepts source
+code, expressions, function names, file paths, packages, or shell arguments.
+GNU Octave is an optional external process.  MATLAB is an optional external
+service executable with an offline-license status boundary; the proprietary
+Python Engine is detected for status only and is never imported.  Neither
+engine, its libraries, nor its license material is shipped by a11oy.
+
+External execution is allowed only on POSIX when ``unshare --net`` and resource
+limits are available.  The child runs with a private network namespace, a small
+environment, a temporary working directory, and hard time/address-space/file-
+size limits.  Missing controls produce ``UNAVAILABLE`` rather than a soft
+fallback.  Results and receipts are deterministic hashes, always unsigned, and
+never increase proof or trust state.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import importlib.util
+import json
+import math
+import os
+import re
+import shutil
+import subprocess
+import tempfile
+from pathlib import Path
+from typing import Any, Callable, Mapping, Sequence
+
+from starlette.requests import Request
+
+
+REQUEST_SCHEMA = "szl.numerics.request/v1"
+ENGINE_RESPONSE_SCHEMA = "szl.numerics.engine-response/v1"
+RESULT_SCHEMA = "szl.numerics.result/v1"
+COMPARE_SCHEMA = "szl.numerics.compare/v1"
+RECEIPT_SCHEMA = "szl.numerics.receipt/v1"
+OPERATIONS = ("MATRIX_SOLVE", "SYMMETRIC_EIGENVALUES", "VALIDATE_REFERENCE_VECTOR")
+ENGINES = ("octave", "matlab")
+MAX_BODY_BYTES = 128 * 1024
+MAX_DIMENSION = 64
+MAX_SCALARS = MAX_DIMENSION * MAX_DIMENSION + 2 * MAX_DIMENSION
+MAX_ABS_VALUE = 1.0e12
+MAX_TIMEOUT_SECONDS = 8
+DEFAULT_TIMEOUT_SECONDS = 5
+MAX_MEMORY_BYTES = 512 * 1024 * 1024
+MAX_OUTPUT_BYTES = 256 * 1024
+MAX_ABS_TOLERANCE = 1.0
+MAX_REL_TOLERANCE = 1.0
+ZERO_UPLIFT = {"proof_uplift": 0, "trust_uplift": 0}
+_REQUEST_ID_RE = re.compile(r"^[A-Za-z0-9][A-Za-z0-9._:-]{0,63}$")
+
+
+class ContractError(ValueError):
+    """The request or engine response violates the fixed contract."""
+
+
+class EngineUnavailable(RuntimeError):
+    """The external engine or a mandatory isolation control is unavailable."""
+
+
+def canonical_json(value: Any) -> bytes:
+    return json.dumps(
+        value,
+        sort_keys=True,
+        separators=(",", ":"),
+        ensure_ascii=False,
+        allow_nan=False,
+    ).encode("utf-8")
+
+
+def digest_json(value: Any) -> str:
+    return hashlib.sha256(canonical_json(value)).hexdigest()
+
+
+def _mapping(value: Any, name: str) -> Mapping[str, Any]:
+    if not isinstance(value, Mapping):
+        raise ContractError(f"{name} must be an object")
+    return value
+
+
+def _strict_keys(value: Mapping[str, Any], allowed: set[str], name: str) -> None:
+    extras = sorted(set(value) - allowed)
+    missing = sorted(allowed - set(value))
+    if extras:
+        raise ContractError(f"{name} has unsupported fields: {', '.join(extras)}")
+    if missing:
+        raise ContractError(f"{name} is missing fields: {', '.join(missing)}")
+
+
+def _number(value: Any, name: str) -> float:
+    if isinstance(value, bool) or not isinstance(value, (int, float)):
+        raise ContractError(f"{name} must be a finite JSON number")
+    result = float(value)
+    if not math.isfinite(result) or abs(result) > MAX_ABS_VALUE:
+        raise ContractError(f"{name} must be finite with absolute value <= {MAX_ABS_VALUE:g}")
+    return result
+
+
+def _vector(value: Any, name: str, length: int | None = None) -> list[float]:
+    if not isinstance(value, Sequence) or isinstance(value, (str, bytes, bytearray)):
+        raise ContractError(f"{name} must be an array")
+    if not value or len(value) > MAX_DIMENSION:
+        raise ContractError(f"{name} must contain 1..{MAX_DIMENSION} numbers")
+    if length is not None and len(value) != length:
+        raise ContractError(f"{name} must contain exactly {length} numbers")
+    return [_number(item, f"{name}[{index}]") for index, item in enumerate(value)]
+
+
+def _matrix(value: Any, name: str) -> list[list[float]]:
+    if not isinstance(value, Sequence) or isinstance(value, (str, bytes, bytearray)):
+        raise ContractError(f"{name} must be an array of rows")
+    if not value or len(value) > MAX_DIMENSION:
+        raise ContractError(f"{name} must contain 1..{MAX_DIMENSION} rows")
+    size = len(value)
+    rows = [_vector(row, f"{name}[{index}]", size) for index, row in enumerate(value)]
+    return rows
+
+
+def _tolerance(value: Any) -> dict[str, float]:
+    obj = _mapping(value, "tolerance")
+    _strict_keys(obj, {"absolute", "relative"}, "tolerance")
+    absolute = _number(obj["absolute"], "tolerance.absolute")
+    relative = _number(obj["relative"], "tolerance.relative")
+    if not 0.0 <= absolute <= MAX_ABS_TOLERANCE:
+        raise ContractError("tolerance.absolute must be between 0 and 1")
+    if not 0.0 <= relative <= MAX_REL_TOLERANCE:
+        raise ContractError("tolerance.relative must be between 0 and 1")
+    return {"absolute": absolute, "relative": relative}
+
+
+def parse_request(payload: Mapping[str, Any]) -> dict[str, Any]:
+    obj = _mapping(payload, "request")
+    _strict_keys(obj, {"schema", "request_id", "operation", "inputs", "tolerance"}, "request")
+    if obj["schema"] != REQUEST_SCHEMA:
+        raise ContractError(f"schema must be {REQUEST_SCHEMA}")
+    request_id = obj["request_id"]
+    if not isinstance(request_id, str) or not _REQUEST_ID_RE.fullmatch(request_id):
+        raise ContractError("request_id must match [A-Za-z0-9][A-Za-z0-9._:-]{0,63}")
+    operation = obj["operation"]
+    if operation not in OPERATIONS:
+        raise ContractError(f"operation must be one of: {', '.join(OPERATIONS)}")
+    raw_inputs = _mapping(obj["inputs"], "inputs")
+    if operation == "SYMMETRIC_EIGENVALUES":
+        _strict_keys(raw_inputs, {"matrix"}, "inputs")
+    elif operation == "MATRIX_SOLVE":
+        _strict_keys(raw_inputs, {"matrix", "rhs"}, "inputs")
+    else:
+        _strict_keys(raw_inputs, {"matrix", "rhs", "expected"}, "inputs")
+
+    matrix = _matrix(raw_inputs["matrix"], "inputs.matrix")
+    size = len(matrix)
+    inputs: dict[str, Any] = {"matrix": matrix}
+    if operation == "SYMMETRIC_EIGENVALUES":
+        for row in range(size):
+            for column in range(row + 1, size):
+                if abs(matrix[row][column] - matrix[column][row]) > 1.0e-12:
+                    raise ContractError("SYMMETRIC_EIGENVALUES requires a symmetric matrix")
+    else:
+        inputs["rhs"] = _vector(raw_inputs["rhs"], "inputs.rhs", size)
+    if operation == "VALIDATE_REFERENCE_VECTOR":
+        inputs["expected"] = _vector(raw_inputs["expected"], "inputs.expected", size)
+    if sum(len(row) for row in matrix) + sum(
+        len(value) for value in inputs.values() if isinstance(value, list) and value and not isinstance(value[0], list)
+    ) > MAX_SCALARS:
+        raise ContractError("request exceeds the scalar ceiling")
+    return {
+        "schema": REQUEST_SCHEMA,
+        "request_id": request_id,
+        "operation": operation,
+        "inputs": inputs,
+        "tolerance": _tolerance(obj["tolerance"]),
+    }
+
+
+def _configured_executable(name: str, env_key: str) -> str | None:
+    configured = os.environ.get(env_key, "").strip()
+    if configured:
+        path = Path(configured)
+        return str(path.resolve()) if path.is_absolute() and path.is_file() else None
+    discovered = shutil.which(name)
+    return str(Path(discovered).resolve()) if discovered else None
+
+
+def _controls() -> dict[str, Any]:
+    try:
+        import resource  # noqa: F401
+        resource_limits = os.name == "posix"
+    except ImportError:
+        resource_limits = False
+    unshare = shutil.which("unshare") if os.name == "posix" else None
+    return {
+        "network_isolation": "PRESENT_UNVERIFIED" if unshare else "SOURCE_UNAVAILABLE",
+        "network_launcher": str(Path(unshare).resolve()) if unshare else None,
+        "resource_limits": "PRESENT" if resource_limits else "SOURCE_UNAVAILABLE",
+        "memory_limit_bytes": MAX_MEMORY_BYTES,
+        "output_limit_bytes": MAX_OUTPUT_BYTES,
+        "timeout_limit_seconds": MAX_TIMEOUT_SECONDS,
+        "package_installs": "DISABLED",
+        "arbitrary_code": "DISABLED",
+    }
+
+
+def engine_status() -> dict[str, Any]:
+    controls = _controls()
+    controls_ready = bool(controls["network_launcher"] and controls["resource_limits"] == "PRESENT")
+    octave = _configured_executable("octave-cli", "A11OY_OCTAVE_EXECUTABLE")
+    matlab_service = _configured_executable("", "A11OY_MATLAB_SERVICE_EXECUTABLE")
+    # Looking up the top-level package is status-only and does not import it.
+    # Looking up ``matlab.engine`` could import its parent as a side effect.
+    matlab_engine = importlib.util.find_spec("matlab") is not None
+    matlab_offline_license = os.environ.get("A11OY_MATLAB_OFFLINE_LICENSE_CONFIGURED") == "1"
+    return {
+        "schema": "szl.numerics.status/v1",
+        "mode": "EXTERNAL_ENGINES_ONLY",
+        "substrate_evidence": "UNKNOWN",
+        "engines": {
+            "octave": {
+                "execution_state": "READY_TO_ATTEMPT" if octave and controls_ready else "UNAVAILABLE",
+                "executable": "PRESENT_UNVERIFIED" if octave else "SOURCE_UNAVAILABLE",
+                "executable_path": octave,
+                "license_boundary": "EXTERNAL_GPL_PROCESS_NOT_BUNDLED",
+            },
+            "matlab": {
+                "execution_state": "READY_TO_ATTEMPT" if matlab_service and matlab_offline_license and controls_ready else "UNAVAILABLE",
+                "service_executable": "PRESENT_UNVERIFIED" if matlab_service else "SOURCE_UNAVAILABLE",
+                "service_executable_path": matlab_service,
+                "python_engine_package": "PRESENT_STATUS_ONLY_NOT_IMPORTED" if matlab_engine else "SOURCE_UNAVAILABLE",
+                "offline_license_configuration": "CONFIGURED_UNVERIFIED" if matlab_offline_license else "SOURCE_UNAVAILABLE",
+                "license_boundary": "EXTERNAL_PROPRIETARY_SERVICE_NOT_BUNDLED",
+            },
+        },
+        "controls": controls,
+        "operations": list(OPERATIONS),
+        "limits": {
+            "max_body_bytes": MAX_BODY_BYTES,
+            "max_dimension": MAX_DIMENSION,
+            "max_scalars": MAX_SCALARS,
+            "max_abs_value": MAX_ABS_VALUE,
+        },
+        **ZERO_UPLIFT,
+    }
+
+
+def _preexec_limits(timeout_seconds: int) -> Callable[[], None]:
+    def apply() -> None:
+        import resource
+
+        resource.setrlimit(resource.RLIMIT_AS, (MAX_MEMORY_BYTES, MAX_MEMORY_BYTES))
+        resource.setrlimit(resource.RLIMIT_CPU, (timeout_seconds, timeout_seconds))
+        resource.setrlimit(resource.RLIMIT_FSIZE, (MAX_OUTPUT_BYTES, MAX_OUTPUT_BYTES))
+        resource.setrlimit(resource.RLIMIT_NOFILE, (64, 64))
+
+    return apply
+
+
+def _read_bounded(path: Path) -> bytes:
+    size = path.stat().st_size
+    if size > MAX_OUTPUT_BYTES:
+        raise EngineUnavailable("ENGINE_OUTPUT_LIMIT_EXCEEDED")
+    return path.read_bytes()
+
+
+def _engine_command(engine: str, input_path: Path, output_path: Path) -> list[str]:
+    status = engine_status()
+    details = status["engines"][engine]
+    if details["execution_state"] != "READY_TO_ATTEMPT":
+        raise EngineUnavailable("ENGINE_OR_ISOLATION_CONTROL_UNAVAILABLE")
+    if engine == "octave":
+        script = Path(__file__).resolve().parent / "numerics" / "octave_adapter.m"
+        if not script.is_file():
+            raise EngineUnavailable("FIXED_OCTAVE_ADAPTER_SOURCE_UNAVAILABLE")
+        command = [details["executable_path"], "--quiet", "--no-gui", "--no-history", str(script), str(input_path), str(output_path)]
+    else:
+        command = [details["service_executable_path"], "--json-input", str(input_path), "--json-output", str(output_path)]
+    return [status["controls"]["network_launcher"], "--net", "--", *command]
+
+
+def _execute_external(engine: str, request: Mapping[str, Any], timeout_seconds: int) -> Mapping[str, Any]:
+    if engine not in ENGINES:
+        raise ContractError(f"engine must be one of: {', '.join(ENGINES)}")
+    if not 1 <= timeout_seconds <= MAX_TIMEOUT_SECONDS:
+        raise ContractError(f"timeout_seconds must be between 1 and {MAX_TIMEOUT_SECONDS}")
+    if os.name != "posix":
+        raise EngineUnavailable("POSIX_RESOURCE_AND_NETWORK_ISOLATION_UNAVAILABLE")
+    with tempfile.TemporaryDirectory(prefix="a11oy-numerics-") as tmp:
+        work = Path(tmp)
+        input_path = work / "request.json"
+        output_path = work / "response.json"
+        log_path = work / "engine.log"
+        input_path.write_bytes(canonical_json(request))
+        command = _engine_command(engine, input_path, output_path)
+        env = {
+            "HOME": str(work),
+            "TMPDIR": str(work),
+            "LANG": "C.UTF-8",
+            "LC_ALL": "C.UTF-8",
+            "OCTAVE_HISTFILE": os.devnull,
+            "PATH": "/usr/bin:/bin",
+        }
+        try:
+            with log_path.open("wb") as log:
+                completed = subprocess.run(
+                    command,
+                    cwd=work,
+                    env=env,
+                    stdin=subprocess.DEVNULL,
+                    stdout=log,
+                    stderr=subprocess.STDOUT,
+                    shell=False,
+                    timeout=timeout_seconds,
+                    check=False,
+                    preexec_fn=_preexec_limits(timeout_seconds),
+                )
+        except subprocess.TimeoutExpired as exc:
+            raise EngineUnavailable("ENGINE_TIMEOUT") from exc
+        except OSError as exc:
+            raise EngineUnavailable("ENGINE_START_FAILED") from exc
+        _read_bounded(log_path)
+        if completed.returncode != 0:
+            raise EngineUnavailable(f"ENGINE_EXIT_{completed.returncode}")
+        if not output_path.is_file():
+            raise EngineUnavailable("ENGINE_RESPONSE_UNAVAILABLE")
+        try:
+            response = json.loads(_read_bounded(output_path).decode("utf-8"))
+        except (UnicodeDecodeError, json.JSONDecodeError) as exc:
+            raise EngineUnavailable("ENGINE_RESPONSE_INVALID_JSON") from exc
+        return _mapping(response, "engine response")
+
+
+def _parse_engine_response(value: Mapping[str, Any], request: Mapping[str, Any]) -> list[float]:
+    obj = _mapping(value, "engine response")
+    _strict_keys(obj, {"schema", "state", "operation", "values", "substrate_evidence"}, "engine response")
+    if obj["schema"] != ENGINE_RESPONSE_SCHEMA or obj["state"] != "RESULT":
+        raise EngineUnavailable("ENGINE_RESPONSE_NOT_RESULT")
+    if obj["operation"] != request["operation"]:
+        raise EngineUnavailable("ENGINE_OPERATION_MISMATCH")
+    if obj["substrate_evidence"] not in ("MEASURED", "UNKNOWN"):
+        raise EngineUnavailable("ENGINE_SUBSTRATE_LABEL_INVALID")
+    values = _vector(obj["values"], "engine response.values", len(request["inputs"]["matrix"]))
+    return values
+
+
+def _within(left: float, right: float, tolerance: Mapping[str, float]) -> bool:
+    return abs(left - right) <= tolerance["absolute"] + tolerance["relative"] * max(abs(left), abs(right))
+
+
+def _receipt(kind: str, engine: str | None, request_digest: str, result: Mapping[str, Any]) -> dict[str, Any]:
+    body = {
+        "schema": RECEIPT_SCHEMA,
+        "kind": kind,
+        "engine": engine,
+        "request_sha256": request_digest,
+        "result_sha256": digest_json(result),
+        "signature_state": "UNSIGNED_DETERMINISTIC_DIGEST_ONLY",
+        **ZERO_UPLIFT,
+    }
+    return {**body, "receipt_sha256": digest_json(body)}
+
+
+Executor = Callable[[Mapping[str, Any]], Mapping[str, Any]]
+
+
+def run_engine(
+    engine: str,
+    payload: Mapping[str, Any],
+    *,
+    timeout_seconds: int = DEFAULT_TIMEOUT_SECONDS,
+    executor: Executor | None = None,
+) -> dict[str, Any]:
+    if engine not in ENGINES:
+        raise ContractError(f"engine must be one of: {', '.join(ENGINES)}")
+    request = parse_request(payload)
+    request_digest = digest_json(request)
+    try:
+        raw = executor(request) if executor is not None else _execute_external(engine, request, timeout_seconds)
+        values = _parse_engine_response(raw, request)
+        reference = None
+        if request["operation"] == "VALIDATE_REFERENCE_VECTOR":
+            reference = "MATCH" if all(
+                _within(value, expected, request["tolerance"])
+                for value, expected in zip(values, request["inputs"]["expected"])
+            ) else "CONFLICT"
+        core = {
+            "schema": RESULT_SCHEMA,
+            "state": "RESULT",
+            "engine": engine,
+            "request_id": request["request_id"],
+            "request_sha256": request_digest,
+            "operation": request["operation"],
+            "values": values,
+            "reference_validation": reference,
+            "substrate_evidence": "UNKNOWN",
+            "signature_state": "UNSIGNED",
+            **ZERO_UPLIFT,
+        }
+    except EngineUnavailable as exc:
+        core = {
+            "schema": RESULT_SCHEMA,
+            "state": "UNAVAILABLE",
+            "engine": engine,
+            "request_id": request["request_id"],
+            "request_sha256": request_digest,
+            "operation": request["operation"],
+            "reason": str(exc),
+            "substrate_evidence": "UNKNOWN",
+            "signature_state": "UNSIGNED",
+            **ZERO_UPLIFT,
+        }
+    return {**core, "receipt": _receipt("ENGINE_RUN", engine, request_digest, core)}
+
+
+def compare_engines(
+    payload: Mapping[str, Any],
+    *,
+    executors: Mapping[str, Executor] | None = None,
+) -> dict[str, Any]:
+    request = parse_request(payload)
+    request_digest = digest_json(request)
+    configured = executors or {}
+    results = {
+        engine: run_engine(engine, request, executor=configured.get(engine))
+        for engine in ENGINES
+    }
+    if any(result["state"] != "RESULT" for result in results.values()):
+        state = "UNAVAILABLE"
+        metrics = None
+    else:
+        octave_values = results["octave"]["values"]
+        matlab_values = results["matlab"]["values"]
+        differences = [abs(left - right) for left, right in zip(octave_values, matlab_values)]
+        state = "MATCH" if all(
+            _within(left, right, request["tolerance"])
+            for left, right in zip(octave_values, matlab_values)
+        ) else "CONFLICT"
+        metrics = {
+            "max_absolute_difference": max(differences, default=0.0),
+            "declared_tolerance": request["tolerance"],
+        }
+    core = {
+        "schema": COMPARE_SCHEMA,
+        "comparison_state": state,
+        "request_id": request["request_id"],
+        "request_sha256": request_digest,
+        "operation": request["operation"],
+        "engine_states": {engine: result["state"] for engine, result in results.items()},
+        "engine_result_sha256": {engine: result["receipt"]["result_sha256"] for engine, result in results.items()},
+        "metrics": metrics,
+        "substrate_evidence": "UNKNOWN",
+        "signature_state": "UNSIGNED",
+        **ZERO_UPLIFT,
+    }
+    return {**core, "receipt": _receipt("CROSS_ENGINE_COMPARE", None, request_digest, core)}
+
+
+async def _bounded_json_body(request: Any) -> dict[str, Any]:
+    declared = request.headers.get("content-length")
+    if declared is not None:
+        try:
+            size = int(declared)
+        except ValueError as exc:
+            raise ContractError("content-length must be a non-negative integer") from exc
+        if size < 0:
+            raise ContractError("content-length must be a non-negative integer")
+        if size > MAX_BODY_BYTES:
+            raise ContractError("request body exceeds 128 KiB")
+    data = bytearray()
+    async for chunk in request.stream():
+        if len(data) + len(chunk) > MAX_BODY_BYTES:
+            raise ContractError("request body exceeds 128 KiB")
+        data.extend(chunk)
+    try:
+        value = json.loads(bytes(data).decode("utf-8"))
+    except (UnicodeDecodeError, json.JSONDecodeError) as exc:
+        raise ContractError("request body must be one JSON object") from exc
+    if not isinstance(value, dict):
+        raise ContractError("request body must be one JSON object")
+    return value
+
+
+def register(app: Any, ns: str = "a11oy") -> dict[str, Any]:
+    """Register the fixed status/run/compare routes on a FastAPI application."""
+
+    from fastapi.responses import JSONResponse
+
+    prefix = f"/api/{ns}/v1/numerics"
+
+    @app.get(f"{prefix}/status")
+    async def numerics_status():  # noqa: ANN202
+        return JSONResponse(engine_status())
+
+    @app.post(f"{prefix}/run/{{engine}}")
+    async def numerics_run(engine: str, request: Request):  # noqa: ANN202
+        try:
+            result = run_engine(engine, await _bounded_json_body(request))
+        except ContractError as exc:
+            return JSONResponse({"state": "REJECTED", "error": str(exc), "substrate_evidence": "UNKNOWN", **ZERO_UPLIFT}, status_code=422)
+        return JSONResponse(result, status_code=200 if result["state"] == "RESULT" else 503)
+
+    @app.post(f"{prefix}/compare")
+    async def numerics_compare(request: Request):  # noqa: ANN202
+        try:
+            result = compare_engines(await _bounded_json_body(request))
+        except ContractError as exc:
+            return JSONResponse({"comparison_state": "REJECTED", "error": str(exc), "substrate_evidence": "UNKNOWN", **ZERO_UPLIFT}, status_code=422)
+        return JSONResponse(result, status_code=200 if result["comparison_state"] in ("MATCH", "CONFLICT") else 503)
+
+    return {
+        "registered": True,
+        "routes": [f"{prefix}/status", f"{prefix}/run/{{engine}}", f"{prefix}/compare"],
+        "engines_bundled": 0,
+        **ZERO_UPLIFT,
+    }
+
+
+__all__ = [
+    "COMPARE_SCHEMA",
+    "ContractError",
+    "ENGINE_RESPONSE_SCHEMA",
+    "ENGINES",
+    "OPERATIONS",
+    "REQUEST_SCHEMA",
+    "compare_engines",
+    "digest_json",
+    "engine_status",
+    "parse_request",
+    "register",
+    "run_engine",
+]

szl_numerics_dataset.py

@@ -0,0 +1,1000 @@
+# SPDX-License-Identifier: Apache-2.0
+"""Deterministic, evidence-typed numerical evaluator dataset service.
+
+Taxonomy home: services/numerics.  This module freezes and serves the
+preregistered matrix-case design, accepts only authenticated bounded run
+receipts, computes binary64 diagnostics, and appends an integrity-linked row to
+an NDJSON ledger.  It does not invoke MATLAB or Octave, does not infer engine or
+network availability, and never increases proof or trust state.
+"""
+
+import datetime as _datetime
+import hashlib
+import hmac
+import json
+import math
+import os
+import re
+import threading
+from functools import lru_cache
+from pathlib import Path
+from typing import Any, Iterable, Mapping, Sequence
+
+import szl_numerics_adapter as _adapter
+import szl_puriq_formulas as _puriq
+from starlette.requests import Request
+
+
+PREREGISTRATION_SCHEMA = "szl.numerics.dataset-preregistration/v1"
+INGEST_SCHEMA = "szl.numerics.dataset-ingest/v1"
+CASE_SCHEMA = "szl.numerics.dataset-case/v1"
+ROW_SCHEMA = "szl.numerics.dataset-row/v1"
+STATUS_SCHEMA = "szl.numerics.dataset-status/v1"
+CURRICULUM_SCHEMA = "szl.numerics.formula-curriculum/v1"
+MAX_LEDGER_ROWS = 10_000
+MAX_LEDGER_BYTES = 64 * 1024 * 1024
+MAX_ROW_BYTES = 64 * 1024
+MAX_PAGE_SIZE = 100
+ZERO_UPLIFT = {"proof_uplift": 0, "trust_uplift": 0}
+_ROOT = Path(__file__).resolve().parent
+_MANIFEST_PATH = _ROOT / "numerics" / "dataset_preregistration.json"
+_FORMULA_SOURCE_PATH = _ROOT / "szl_puriq_formulas.py"
+_LICENSE_PATH = _ROOT / "LICENSE"
+_LOCKED_FORMULA_IDS = frozenset({"F1", "F4", "F7", "F11", "F12", "F18", "F19", "F22"})
+_SHA256_RE = re.compile(r"^[0-9a-f]{64}$")
+_ID_RE = re.compile(r"^[A-Za-z0-9][A-Za-z0-9._:-]{0,95}$")
+_CASE_RE = re.compile(r"^case-[a-z0-9-]{8,120}$")
+_LEDGER_LOCK = threading.Lock()
+_MASK64 = (1 << 64) - 1
+
+
+class DatasetContractError(ValueError):
+    """A case selector or ingested row violates the frozen contract."""
+
+
+class DatasetUnavailable(RuntimeError):
+    """A mandatory dataset service precondition is unavailable."""
+
+
+def _file_sha256(path: Path) -> str:
+    digest = hashlib.sha256()
+    with path.open("rb") as handle:
+        for block in iter(lambda: handle.read(1024 * 1024), b""):
+            digest.update(block)
+    return digest.hexdigest()
+
+
+def _formula_source_family(meta: Mapping[str, Any]) -> str:
+    organ = str(meta.get("organ") or "source-unavailable").strip().lower()
+    organ = re.sub(r"[^a-z0-9]+", "-", organ).strip("-") or "source-unavailable"
+    return f"puriq-formula-meta/{organ}"
+
+
+def _source_family_split(source_family: str) -> str:
+    """Assign a whole source family to one split to prevent family leakage."""
+
+    bucket = int(hashlib.sha256(source_family.encode("utf-8")).hexdigest()[:8], 16) % 10
+    if bucket < 7:
+        return "train"
+    if bucket < 9:
+        return "validation"
+    return "test"
+
+
+@lru_cache(maxsize=1)
+def formula_curriculum() -> dict[str, Any]:
+    """Build the full formula-ID/status curriculum without manufacturing proof evidence.
+
+    This is a metadata bridge into the Brain curriculum, not a theorem dataset.
+    The local canonical registry and repository license are content-addressed.  A
+    proof/refutation receipt remains null unless an exact per-formula receipt is
+    present; the repository currently provides no such mapping.
+    """
+
+    if not _FORMULA_SOURCE_PATH.is_file() or not _LICENSE_PATH.is_file():
+        raise DatasetUnavailable("FORMULA_CURRICULUM_SOURCE_OR_LICENSE_UNAVAILABLE")
+    source_sha256 = _file_sha256(_FORMULA_SOURCE_PATH)
+    license_sha256 = _file_sha256(_LICENSE_PATH)
+    eligible: list[dict[str, Any]] = []
+    quarantined: list[dict[str, Any]] = []
+    expected_ids = {f"F{index}" for index in range(1, 24)}
+
+    def quarantine(formula_id: str, reasons: Sequence[str], meta: Mapping[str, Any] | None = None) -> None:
+        quarantined.append({
+            "formula_id": formula_id,
+            "reasons": sorted(set(reasons)),
+            "source_record_sha256": _adapter.digest_json(dict(meta)) if meta is not None else None,
+            "proof_receipt_sha256": None,
+            "refutation_receipt_sha256": None,
+            "proof_uplift": 0,
+            "trust_uplift": 0,
+        })
+
+    for formula_id in sorted(expected_ids, key=lambda token: int(token[1:])):
+        meta = _puriq.FORMULA_META.get(formula_id)
+        if not isinstance(meta, Mapping):
+            quarantine(formula_id, ["CANONICAL_RECORD_UNAVAILABLE"])
+            continue
+        reasons: list[str] = []
+        if meta.get("id") != formula_id:
+            reasons.append("FORMULA_ID_CONFLICT")
+        status = meta.get("proof_status")
+        if status not in {"PROVED", "UNATTEMPTED", "CONJECTURE_1"}:
+            reasons.append("UNSUPPORTED_PROOF_STATUS")
+        if (formula_id in _LOCKED_FORMULA_IDS) != (status == "PROVED"):
+            reasons.append("LOCKED_PROOF_CLAIM_CONFLICT")
+        if formula_id == "F23" and status != "CONJECTURE_1":
+            reasons.append("LAMBDA_CONJECTURE_STATUS_CONFLICT")
+        required_text = ("name", "organ", "primitive", "identity_doc")
+        if any(not isinstance(meta.get(field), str) or not str(meta[field]).strip() for field in required_text):
+            reasons.append("PROVENANCE_METADATA_INCOMPLETE")
+        if reasons:
+            quarantine(formula_id, reasons, meta)
+            continue
+
+        source_family = _formula_source_family(meta)
+        proof_note = meta.get("proof_note")
+        if status == "PROVED" and proof_note:
+            claim_scope = "LOCKED_THEOREM_ONLY_FORMULA_IDENTITY_SCOPE_MAY_DIFFER"
+        elif status == "PROVED":
+            claim_scope = "LOCKED_THEOREM_REPORTED_BY_CANONICAL_REGISTRY"
+        elif status == "CONJECTURE_1":
+            claim_scope = "CONJECTURE_1_OPEN_NOT_A_THEOREM"
+        else:
+            claim_scope = "OPEN_PROOF_OBLIGATION_UNATTEMPTED"
+        eligible.append({
+            "formula_id": formula_id,
+            "name": meta["name"],
+            "organ": meta["organ"],
+            "primitive": meta["primitive"],
+            "identity_doc": meta["identity_doc"],
+            "proof_status": status,
+            "lean_name": meta.get("lean_name"),
+            "lean_status": meta.get("lean_status"),
+            "locked": formula_id in _LOCKED_FORMULA_IDS,
+            "claim_scope": claim_scope,
+            "source_family": source_family,
+            "split": _source_family_split(source_family),
+            "source_record_sha256": _adapter.digest_json(dict(meta)),
+            "proof_receipt_sha256": None,
+            "refutation_receipt_sha256": None,
+            "receipt_state": "PER_FORMULA_RECEIPT_SOURCE_UNAVAILABLE",
+            "license_state": "REPOSITORY_APACHE_2_0",
+            "dataset_role": "STATUS_AND_PROVENANCE_METADATA_ONLY",
+            "proof_uplift": 0,
+            "trust_uplift": 0,
+        })
+
+    extras = sorted(set(_puriq.FORMULA_META) - expected_ids)
+    for formula_id in extras:
+        meta = _puriq.FORMULA_META[formula_id]
+        quarantine(str(formula_id), ["FORMULA_ID_OUTSIDE_F1_F23_CONTRACT"], meta if isinstance(meta, Mapping) else None)
+
+    split_families: dict[str, list[str]] = {"train": [], "validation": [], "test": []}
+    for item in eligible:
+        if item["source_family"] not in split_families[item["split"]]:
+            split_families[item["split"]].append(item["source_family"])
+    for families in split_families.values():
+        families.sort()
+    return {
+        "schema": CURRICULUM_SCHEMA,
+        "state": "READY" if eligible and not quarantined else ("PARTIAL" if eligible else "UNAVAILABLE"),
+        "dataset_role": "BRAIN_CURRICULUM_FORMULA_STATUS_AND_PROVENANCE_METADATA",
+        "canonical_source": {
+            "path": "szl_puriq_formulas.py",
+            "sha256": source_sha256,
+            "license": "Apache-2.0",
+            "license_file_sha256": license_sha256,
+        },
+        "formula_contract": {
+            "expected_ids": [f"F{index}" for index in range(1, 24)],
+            "locked_proven_ids": sorted(_LOCKED_FORMULA_IDS, key=lambda token: int(token[1:])),
+            "lambda_formula_id": "F23",
+            "lambda_status": "CONJECTURE_1",
+        },
+        "counts": {
+            "expected": 23,
+            "eligible": len(eligible),
+            "quarantined": len(quarantined),
+            "source_families": len({item["source_family"] for item in eligible}),
+        },
+        "source_family_split": {
+            "method": "SHA256_FAMILY_BUCKET_70_20_10_NO_FAMILY_LEAKAGE",
+            "families": split_families,
+        },
+        "eligible": eligible,
+        "quarantined": quarantined,
+        "receipt_boundary": (
+            "Null receipt hashes mean no exact per-formula proof/refutation receipt mapping was found; "
+            "canonical registry status is not upgraded into receipt evidence."
+        ),
+        "interpretation_guard": (
+            "This curriculum carries formula identifiers, statuses, and provenance metadata only. "
+            "It does not prove formulas, refute conjectures, or improve numerical-result trust."
+        ),
+        **ZERO_UPLIFT,
+    }
+
+
+def _strict(value: Any, required: set[str], name: str) -> Mapping[str, Any]:
+    if not isinstance(value, Mapping):
+        raise DatasetContractError(f"{name} must be an object")
+    missing = sorted(required - set(value))
+    extras = sorted(set(value) - required)
+    if missing:
+        raise DatasetContractError(f"{name} is missing fields: {', '.join(missing)}")
+    if extras:
+        raise DatasetContractError(f"{name} has unsupported fields: {', '.join(extras)}")
+    return value
+
+
+def _finite(value: Any, name: str) -> float:
+    if isinstance(value, bool) or not isinstance(value, (int, float)):
+        raise DatasetContractError(f"{name} must be a finite JSON number")
+    result = float(value)
+    if not math.isfinite(result) or abs(result) > _adapter.MAX_ABS_VALUE:
+        raise DatasetContractError(f"{name} must be finite and bounded")
+    return result
+
+
+def _nullable_uint(value: Any, name: str) -> int | None:
+    if value is None:
+        return None
+    if isinstance(value, bool) or not isinstance(value, int) or value < 0:
+        raise DatasetContractError(f"{name} must be a non-negative integer or null")
+    return value
+
+
+def _sha_or_none(value: Any, name: str) -> str | None:
+    if value is None:
+        return None
+    if not isinstance(value, str) or not _SHA256_RE.fullmatch(value):
+        raise DatasetContractError(f"{name} must be a lowercase SHA-256 digest or null")
+    return value
+
+
+def _utc_timestamp(value: Any) -> str:
+    if not isinstance(value, str) or len(value) > 40:
+        raise DatasetContractError("observed_at_utc must be an ISO-8601 timestamp")
+    try:
+        parsed = _datetime.datetime.fromisoformat(value.replace("Z", "+00:00"))
+    except ValueError as exc:
+        raise DatasetContractError("observed_at_utc must be an ISO-8601 timestamp") from exc
+    if parsed.tzinfo is None or parsed.utcoffset() is None:
+        raise DatasetContractError("observed_at_utc must include a UTC offset")
+    return parsed.astimezone(_datetime.timezone.utc).isoformat().replace("+00:00", "Z")
+
+
+@lru_cache(maxsize=1)
+def preregistration() -> dict[str, Any]:
+    try:
+        value = json.loads(_MANIFEST_PATH.read_text(encoding="utf-8"))
+    except (OSError, json.JSONDecodeError) as exc:
+        raise DatasetUnavailable("PREREGISTRATION_SOURCE_UNAVAILABLE") from exc
+    required = {
+        "schema", "protocol_id", "protocol_version", "state", "frozen_before_execution",
+        "results_present", "matrix_dimensions", "deterministic_seeds",
+        "condition_number_strata", "confirmatory_matrix_families",
+        "exploratory_matrix_families", "fixture_generation", "tolerance",
+        "machine_epsilon_binary64", "execution_order_seed", "engines",
+        "expected_case_counts", "evidence_boundary",
+    }
+    _strict(value, required, "preregistration")
+    if value["schema"] != PREREGISTRATION_SCHEMA:
+        raise DatasetUnavailable("PREREGISTRATION_SCHEMA_MISMATCH")
+    if value["matrix_dimensions"] != [2, 4, 8, 16, 32, 64]:
+        raise DatasetUnavailable("PREREGISTRATION_DIMENSIONS_MISMATCH")
+    if value["deterministic_seeds"] != [1729, 57721, 271828, 314159, 1618033]:
+        raise DatasetUnavailable("PREREGISTRATION_SEEDS_MISMATCH")
+    if value["expected_case_counts"] != {"confirmatory": 1320, "exploratory": 8, "total": 1328}:
+        raise DatasetUnavailable("PREREGISTRATION_CASE_COUNT_MISMATCH")
+    if value["engines"] != ["octave", "matlab"]:
+        raise DatasetUnavailable("PREREGISTRATION_ENGINE_SET_MISMATCH")
+    return value
+
+
+class _SplitMix64:
+    def __init__(self, seed: int) -> None:
+        self.state = seed & _MASK64
+
+    def next_u64(self) -> int:
+        self.state = (self.state + 0x9E3779B97F4A7C15) & _MASK64
+        z = self.state
+        z = ((z ^ (z >> 30)) * 0xBF58476D1CE4E5B9) & _MASK64
+        z = ((z ^ (z >> 27)) * 0x94D049BB133111EB) & _MASK64
+        return (z ^ (z >> 31)) & _MASK64
+
+    def uniform(self) -> float:
+        return (self.next_u64() >> 11) / float(1 << 53)
+
+
+def _derived_seed(seed: int, family: str, label: str) -> int:
+    payload = f"szl-numerics-v1:{seed}:{family}:{label}".encode("ascii")
+    return int.from_bytes(hashlib.sha256(payload).digest()[:8], "big")
+
+
+def _identity(n: int) -> list[list[float]]:
+    return [[1.0 if row == column else 0.0 for column in range(n)] for row in range(n)]
+
+
+def _orthogonal(n: int, seed: int) -> list[list[float]]:
+    generator = _SplitMix64(seed)
+    result = _identity(n)
+    for left in range(n):
+        for right in range(left + 1, n):
+            theta = 2.0 * math.pi * generator.uniform()
+            cosine, sine = math.cos(theta), math.sin(theta)
+            for row in range(n):
+                old_left, old_right = result[row][left], result[row][right]
+                result[row][left] = cosine * old_left - sine * old_right
+                result[row][right] = sine * old_left + cosine * old_right
+    return result
+
+
+def _spectrum(n: int, kappa: float, *, signed: bool = False) -> list[float]:
+    if n == 1:
+        values = [1.0]
+    else:
+        exponent = math.log10(kappa)
+        values = [10.0 ** (-exponent * index / (n - 1)) for index in range(n)]
+    if signed:
+        values = [value if index % 2 == 0 else -value for index, value in enumerate(values)]
+    return values
+
+
+def _q_diag_qt(q: Sequence[Sequence[float]], diagonal: Sequence[float]) -> list[list[float]]:
+    n = len(diagonal)
+    return [
+        [sum(q[row][k] * diagonal[k] * q[column][k] for k in range(n)) for column in range(n)]
+        for row in range(n)
+    ]
+
+
+def _ql_diag_qr(ql: Sequence[Sequence[float]], diagonal: Sequence[float], qr: Sequence[Sequence[float]]) -> list[list[float]]:
+    n = len(diagonal)
+    return [
+        [sum(ql[row][k] * diagonal[k] * qr[column][k] for k in range(n)) for column in range(n)]
+        for row in range(n)
+    ]
+
+
+def _stable_matrix(matrix: Sequence[Sequence[float]]) -> list[list[float]]:
+    return [[float(format(value, ".17g")) for value in row] for row in matrix]
+
+
+def _matvec(matrix: Sequence[Sequence[float]], vector: Sequence[float]) -> list[float]:
+    return [sum(value * vector[column] for column, value in enumerate(row)) for row in matrix]
+
+
+def _known_solution(n: int) -> list[float]:
+    return [((-1.0) ** index) * (index + 1) / n for index in range(n)]
+
+
+def _slug(token: str) -> str:
+    return token.lower().replace("_", "-")
+
+
+def _case_id(family: str, dimension: int, stratum: str, seed: int, operation: str) -> str:
+    return f"case-{_slug(family)}-n{dimension:02d}-{_slug(stratum)}-s{seed}-{_slug(operation)}"
+
+
+def _case_descriptors() -> Iterable[dict[str, Any]]:
+    manifest = preregistration()
+    strata = manifest["condition_number_strata"]
+    for family in manifest["confirmatory_matrix_families"]:
+        for dimension in manifest["matrix_dimensions"]:
+            for stratum in strata:
+                for seed in manifest["deterministic_seeds"]:
+                    for operation in family["operations"]:
+                        case_id = _case_id(family["id"], dimension, stratum["id"], seed, operation)
+                        yield {
+                            "case_id": case_id,
+                            "design": "CONFIRMATORY",
+                            "matrix_family": family["id"],
+                            "symmetric": family["symmetric"],
+                            "dimension": dimension,
+                            "condition_stratum": stratum["id"],
+                            "condition_number_target": stratum["target"],
+                            "seed": seed,
+                            "operation": operation,
+                            "execution_order_sha256": hashlib.sha256(
+                                f"{manifest['execution_order_seed']}:{case_id}".encode("utf-8")
+                            ).hexdigest(),
+                        }
+    for family in manifest["exploratory_matrix_families"]:
+        for dimension in family["dimensions"]:
+            for seed in family["seeds"]:
+                for operation in family["operations"]:
+                    case_id = _case_id(family["id"], dimension, family["condition_stratum"], seed, operation)
+                    yield {
+                        "case_id": case_id,
+                        "design": "EXPLORATORY",
+                        "matrix_family": family["id"],
+                        "symmetric": family["symmetric"],
+                        "dimension": dimension,
+                        "condition_stratum": family["condition_stratum"],
+                        "condition_number_target": None,
+                        "seed": seed,
+                        "operation": operation,
+                        "excluded_from_confirmatory_denominators": True,
+                        "execution_order_sha256": hashlib.sha256(
+                            f"{manifest['execution_order_seed']}:{case_id}".encode("utf-8")
+                        ).hexdigest(),
+                    }
+
+
+@lru_cache(maxsize=1)
+def _case_index() -> dict[str, dict[str, Any]]:
+    values = {item["case_id"]: item for item in _case_descriptors()}
+    manifest = preregistration()
+    if len(values) != manifest["expected_case_counts"]["total"]:
+        raise DatasetUnavailable("GENERATED_CASE_COUNT_MISMATCH")
+    return values
+
+
+def _matrix_for(descriptor: Mapping[str, Any]) -> list[list[float]]:
+    n = descriptor["dimension"]
+    family = descriptor["matrix_family"]
+    seed = descriptor["seed"]
+    kappa = descriptor["condition_number_target"]
+    if family == "HILBERT_SENTINEL":
+        return _stable_matrix([[1.0 / (row + column + 1) for column in range(n)] for row in range(n)])
+    diagonal = _spectrum(n, kappa, signed=family == "SYMMETRIC_INDEFINITE_GIVENS")
+    if family == "DIAGONAL_GEOMETRIC":
+        matrix = [[diagonal[row] if row == column else 0.0 for column in range(n)] for row in range(n)]
+    elif family in ("SPD_GIVENS", "SYMMETRIC_INDEFINITE_GIVENS"):
+        q = _orthogonal(n, _derived_seed(seed, family, "Q"))
+        matrix = _q_diag_qt(q, diagonal)
+    elif family == "GENERAL_SVD_GIVENS":
+        ql = _orthogonal(n, _derived_seed(seed, family, "Q_LEFT"))
+        qr = _orthogonal(n, _derived_seed(seed, family, "Q_RIGHT"))
+        matrix = _ql_diag_qr(ql, diagonal, qr)
+    else:
+        raise DatasetUnavailable("UNKNOWN_PREREGISTERED_MATRIX_FAMILY")
+    return _stable_matrix(matrix)
+
+
+def get_case(case_id: str) -> dict[str, Any]:
+    if not isinstance(case_id, str) or not _CASE_RE.fullmatch(case_id):
+        raise DatasetContractError("case_id is invalid")
+    descriptor = _case_index().get(case_id)
+    if descriptor is None:
+        raise DatasetContractError("case_id is not preregistered")
+    matrix = _matrix_for(descriptor)
+    operation = descriptor["operation"]
+    inputs: dict[str, Any] = {"matrix": matrix}
+    construction_reference: dict[str, Any] = {"state": "NOT_APPLICABLE"}
+    if operation != "SYMMETRIC_EIGENVALUES":
+        expected = _known_solution(descriptor["dimension"])
+        inputs["rhs"] = _matvec(matrix, expected)
+        construction_reference = {
+            "state": "FROZEN_CONSTRUCTION_REFERENCE",
+            "role": "fixture construction only; not the independent primary reference",
+            "values": expected,
+        }
+        if operation == "VALIDATE_REFERENCE_VECTOR":
+            inputs["expected"] = expected
+    request = {
+        "schema": _adapter.REQUEST_SCHEMA,
+        "request_id": case_id,
+        "operation": operation,
+        "inputs": inputs,
+        "tolerance": preregistration()["tolerance"],
+    }
+    request = _adapter.parse_request(request)
+    core = {
+        "schema": CASE_SCHEMA,
+        **descriptor,
+        "request": request,
+        "request_sha256": _adapter.digest_json(request),
+        "construction_reference": construction_reference,
+        "primary_reference": {"state": "SOURCE_UNAVAILABLE"},
+        "condition_number_reference": {"state": "NOT_EVALUATED"},
+        "substrate_evidence": "UNKNOWN",
+        **ZERO_UPLIFT,
+    }
+    return {**core, "fixture_sha256": _adapter.digest_json(core)}
+
+
+def list_cases(*, offset: int = 0, limit: int = 25, family: str | None = None, operation: str | None = None) -> dict[str, Any]:
+    if offset < 0 or not 1 <= limit <= MAX_PAGE_SIZE:
+        raise DatasetContractError(f"offset must be non-negative and limit must be 1..{MAX_PAGE_SIZE}")
+    values = list(_case_index().values())
+    if family:
+        values = [item for item in values if item["matrix_family"] == family]
+    if operation:
+        values = [item for item in values if item["operation"] == operation]
+    values.sort(key=lambda item: item["execution_order_sha256"])
+    return {
+        "schema": "szl.numerics.dataset-case-list/v1",
+        "total": len(values),
+        "offset": offset,
+        "limit": limit,
+        "items": values[offset: offset + limit],
+        "items_are": "PREREGISTERED_INPUT_DESCRIPTORS_NOT_ENGINE_RESULTS",
+        **ZERO_UPLIFT,
+    }
+
+
+def _ledger_path() -> Path:
+    configured = os.environ.get("A11OY_NUMERICS_DATASET_LEDGER", "").strip()
+    return Path(configured).expanduser() if configured else _ROOT / ".a11oy-state" / "numerics-dataset.ndjson"
+
+
+def _read_rows() -> list[dict[str, Any]]:
+    path = _ledger_path()
+    if not path.is_file():
+        return []
+    if path.stat().st_size > MAX_LEDGER_BYTES:
+        raise DatasetUnavailable("LEDGER_SIZE_LIMIT_EXCEEDED")
+    rows: list[dict[str, Any]] = []
+    for line_number, raw in enumerate(path.read_bytes().splitlines(), start=1):
+        if not raw:
+            continue
+        if len(raw) > MAX_ROW_BYTES:
+            raise DatasetUnavailable(f"LEDGER_ROW_SIZE_LIMIT_EXCEEDED:{line_number}")
+        try:
+            value = json.loads(raw.decode("utf-8"))
+        except (UnicodeDecodeError, json.JSONDecodeError) as exc:
+            raise DatasetUnavailable(f"LEDGER_ROW_INVALID:{line_number}") from exc
+        if not isinstance(value, dict) or value.get("schema") != ROW_SCHEMA:
+            raise DatasetUnavailable(f"LEDGER_ROW_SCHEMA_INVALID:{line_number}")
+        rows.append(value)
+    if len(rows) > MAX_LEDGER_ROWS:
+        raise DatasetUnavailable("LEDGER_ROW_LIMIT_EXCEEDED")
+    return rows
+
+
+def list_results(*, offset: int = 0, limit: int = 25, case_id: str | None = None) -> dict[str, Any]:
+    if offset < 0 or not 1 <= limit <= MAX_PAGE_SIZE:
+        raise DatasetContractError(f"offset must be non-negative and limit must be 1..{MAX_PAGE_SIZE}")
+    rows = _read_rows()
+    if case_id:
+        rows = [row for row in rows if row.get("case_id") == case_id]
+    rows.reverse()
+    return {
+        "schema": "szl.numerics.dataset-result-list/v1",
+        "total": len(rows),
+        "offset": offset,
+        "limit": limit,
+        "items": rows[offset: offset + limit],
+        "ledger_semantics": "APPEND_ONLY_NEWEST_FIRST",
+        **ZERO_UPLIFT,
+    }
+
+
+def _vector_norm(vector: Sequence[float]) -> float:
+    return math.sqrt(sum(value * value for value in vector))
+
+
+def _matrix_norm2_diagnostic(matrix: Sequence[Sequence[float]]) -> float:
+    """Deterministic binary64 power iteration; explicitly not a high-precision reference."""
+
+    n = len(matrix)
+    vector = [1.0 / math.sqrt(n)] * n
+    for _ in range(96):
+        av = _matvec(matrix, vector)
+        ata_v = [sum(matrix[row][column] * av[row] for row in range(n)) for column in range(n)]
+        size = _vector_norm(ata_v)
+        if size == 0.0:
+            return 0.0
+        next_vector = [value / size for value in ata_v]
+        delta = _vector_norm([left - right for left, right in zip(next_vector, vector)])
+        vector = next_vector
+        if delta <= 1.0e-15:
+            break
+    return _vector_norm(_matvec(matrix, vector))
+
+
+def _relative_error(actual: Sequence[float], expected: Sequence[float]) -> float:
+    numerator = _vector_norm([left - right for left, right in zip(actual, expected)])
+    denominator = _vector_norm(expected)
+    if denominator == 0.0:
+        return 0.0 if numerator == 0.0 else math.inf
+    return numerator / denominator
+
+
+def _within(left: float, right: float, tolerance: Mapping[str, float]) -> bool:
+    return abs(left - right) <= tolerance["absolute"] + tolerance["relative"] * max(abs(left), abs(right))
+
+
+def _diagnostics(case: Mapping[str, Any], values: Sequence[float], reference: Mapping[str, Any]) -> dict[str, Any]:
+    request = case["request"]
+    matrix = request["inputs"]["matrix"]
+    operation = request["operation"]
+    n = len(matrix)
+    threshold = 100.0 * n * preregistration()["machine_epsilon_binary64"]
+    base: dict[str, Any] = {
+        "diagnostic_precision": "PYTHON_BINARY64",
+        "matrix_norm2_method": "DETERMINISTIC_POWER_ITERATION_NOT_PRIMARY_REFERENCE",
+        "absolute_residual_norm2": None,
+        "relative_residual": None,
+        "normwise_backward_error": None,
+        "forward_error": None,
+        "maximum_elementwise_reference_error": None,
+        "reference_state": "NOT_EVALUATED",
+        "trace_invariant": None,
+        "frobenius_invariant": None,
+        "quality_gate_threshold": threshold,
+        "quality_gate": "NOT_EVALUATED",
+    }
+    if operation in ("MATRIX_SOLVE", "VALIDATE_REFERENCE_VECTOR"):
+        rhs = request["inputs"]["rhs"]
+        residual_vector = [right - left for right, left in zip(rhs, _matvec(matrix, values))]
+        residual = _vector_norm(residual_vector)
+        denominator = _matrix_norm2_diagnostic(matrix) * _vector_norm(values) + _vector_norm(rhs)
+        backward = 0.0 if residual == 0.0 and denominator == 0.0 else (math.inf if denominator == 0.0 else residual / denominator)
+        base.update({
+            "absolute_residual_norm2": residual,
+            "relative_residual": backward,
+            "normwise_backward_error": backward,
+            "quality_gate": "PASS" if math.isfinite(backward) and backward <= threshold else "FAIL",
+        })
+    else:
+        trace_matrix = sum(matrix[index][index] for index in range(n))
+        trace_values = sum(values)
+        norm_f_squared = sum(value * value for row in matrix for value in row)
+        value_sq_sum = sum(value * value for value in values)
+        trace_invariant = abs(trace_values - trace_matrix) / max(1.0, abs(trace_matrix))
+        frobenius_invariant = abs(value_sq_sum - norm_f_squared) / max(1.0, norm_f_squared)
+        base.update({
+            "trace_invariant": trace_invariant,
+            "frobenius_invariant": frobenius_invariant,
+            "quality_gate": "PASS" if trace_invariant <= threshold and frobenius_invariant <= threshold else "FAIL",
+        })
+    if reference["state"] == "MEASURED":
+        expected = reference["values"]
+        base.update({
+            "forward_error": _relative_error(values, expected),
+            "maximum_elementwise_reference_error": max(abs(left - right) for left, right in zip(values, expected)),
+            "reference_state": "REFERENCE_MATCH" if all(
+                _within(left, right, request["tolerance"]) for left, right in zip(values, expected)
+            ) else "REFERENCE_CONFLICT",
+            "reference_implementation": reference["implementation"],
+            "reference_evidence_sha256": reference["evidence_sha256"],
+        })
+    return base
+
+
+def _parse_ingest(payload: Mapping[str, Any]) -> dict[str, Any]:
+    required = {"schema", "run_id", "case_id", "engine", "outcome", "engine_evidence", "containment", "resources", "reference", "observed_at_utc"}
+    obj = _strict(payload, required, "ingest")
+    if obj["schema"] != INGEST_SCHEMA:
+        raise DatasetContractError(f"schema must be {INGEST_SCHEMA}")
+    if not isinstance(obj["run_id"], str) or not _ID_RE.fullmatch(obj["run_id"]):
+        raise DatasetContractError("run_id is invalid")
+    case = get_case(obj["case_id"])
+    if obj["engine"] not in _adapter.ENGINES:
+        raise DatasetContractError("engine must be octave or matlab")
+    outcome = obj["outcome"]
+    if not isinstance(outcome, Mapping) or outcome.get("state") not in ("RESULT", "UNAVAILABLE"):
+        raise DatasetContractError("outcome.state must be RESULT or UNAVAILABLE")
+    if outcome["state"] == "RESULT":
+        outcome = _strict(outcome, {"state", "values"}, "outcome")
+        raw_values = outcome["values"]
+        if not isinstance(raw_values, Sequence) or isinstance(raw_values, (str, bytes, bytearray)):
+            raise DatasetContractError("outcome.values must be an array")
+        if len(raw_values) != case["dimension"]:
+            raise DatasetContractError(f"outcome.values must contain exactly {case['dimension']} numbers")
+        outcome = {"state": "RESULT", "values": [_finite(value, f"outcome.values[{index}]") for index, value in enumerate(raw_values)]}
+    else:
+        outcome = _strict(outcome, {"state", "reason"}, "outcome")
+        if not isinstance(outcome["reason"], str) or not 1 <= len(outcome["reason"]) <= 160:
+            raise DatasetContractError("outcome.reason must contain 1..160 characters")
+        outcome = dict(outcome)
+    engine_evidence = _strict(
+        obj["engine_evidence"],
+        {"version", "version_evidence_sha256", "executable_sha256", "license_state", "offline_license_state"},
+        "engine_evidence",
+    )
+    version = engine_evidence["version"]
+    if version is not None and (not isinstance(version, str) or not 1 <= len(version) <= 120):
+        raise DatasetContractError("engine_evidence.version must be null or 1..120 characters")
+    engine_evidence = {
+        "version": version,
+        "version_evidence_sha256": _sha_or_none(engine_evidence["version_evidence_sha256"], "engine_evidence.version_evidence_sha256"),
+        "executable_sha256": _sha_or_none(engine_evidence["executable_sha256"], "engine_evidence.executable_sha256"),
+        "license_state": engine_evidence["license_state"],
+        "offline_license_state": engine_evidence["offline_license_state"],
+    }
+    if engine_evidence["license_state"] not in ("OPERATOR_REVIEWED", "REVIEW_REQUIRED", "UNKNOWN"):
+        raise DatasetContractError("engine_evidence.license_state is invalid")
+    if engine_evidence["offline_license_state"] not in ("CONFIGURED", "UNAVAILABLE", "NOT_APPLICABLE", "UNKNOWN"):
+        raise DatasetContractError("engine_evidence.offline_license_state is invalid")
+    containment = _strict(obj["containment"], {"network_state", "evidence_sha256"}, "containment")
+    if containment["network_state"] not in ("DENIED", "UNAVAILABLE", "UNKNOWN"):
+        raise DatasetContractError("containment.network_state is invalid")
+    containment = {"network_state": containment["network_state"], "evidence_sha256": _sha_or_none(containment["evidence_sha256"], "containment.evidence_sha256")}
+    resources = _strict(
+        obj["resources"],
+        {"wall_time_ns", "child_user_cpu_ns", "child_system_cpu_ns", "peak_resident_bytes", "request_bytes", "response_bytes", "log_bytes"},
+        "resources",
+    )
+    resources = {name: _nullable_uint(value, f"resources.{name}") for name, value in resources.items()}
+    reference = obj["reference"]
+    if not isinstance(reference, Mapping) or reference.get("state") not in ("SOURCE_UNAVAILABLE", "MEASURED"):
+        raise DatasetContractError("reference.state must be SOURCE_UNAVAILABLE or MEASURED")
+    if reference["state"] == "SOURCE_UNAVAILABLE":
+        reference = dict(_strict(reference, {"state"}, "reference"))
+    else:
+        reference = _strict(reference, {"state", "implementation", "values", "evidence_sha256"}, "reference")
+        if reference["implementation"] != "PYTHON_MPMATH_100DP":
+            raise DatasetContractError("only the preregistered PYTHON_MPMATH_100DP primary reference is accepted")
+        values = reference["values"]
+        if not isinstance(values, Sequence) or isinstance(values, (str, bytes, bytearray)) or len(values) != case["dimension"]:
+            raise DatasetContractError(f"reference.values must contain exactly {case['dimension']} numbers")
+        reference = {
+            "state": "MEASURED",
+            "implementation": "PYTHON_MPMATH_100DP",
+            "values": [_finite(value, f"reference.values[{index}]") for index, value in enumerate(values)],
+            "evidence_sha256": _sha_or_none(reference["evidence_sha256"], "reference.evidence_sha256"),
+        }
+        if reference["evidence_sha256"] is None:
+            raise DatasetContractError("measured primary reference requires evidence_sha256")
+    return {
+        "run_id": obj["run_id"],
+        "case": case,
+        "engine": obj["engine"],
+        "outcome": outcome,
+        "engine_evidence": engine_evidence,
+        "containment": containment,
+        "resources": resources,
+        "reference": reference,
+        "observed_at_utc": _utc_timestamp(obj["observed_at_utc"]),
+    }
+
+
+def _evidence_gate(parsed: Mapping[str, Any]) -> tuple[str, str | None]:
+    if parsed["outcome"]["state"] == "UNAVAILABLE":
+        return "UNAVAILABLE", parsed["outcome"]["reason"]
+    evidence = parsed["engine_evidence"]
+    containment = parsed["containment"]
+    resources = parsed["resources"]
+    if containment["network_state"] != "DENIED" or containment["evidence_sha256"] is None:
+        return "REFUSED", "NETWORK_DENIAL_EVIDENCE_UNAVAILABLE"
+    if evidence["version"] is None or evidence["version_evidence_sha256"] is None or evidence["executable_sha256"] is None:
+        return "REFUSED", "ENGINE_VERSION_EVIDENCE_UNAVAILABLE"
+    if evidence["license_state"] != "OPERATOR_REVIEWED":
+        return "REFUSED", "ENGINE_LICENSE_REVIEW_UNAVAILABLE"
+    if parsed["engine"] == "matlab" and evidence["offline_license_state"] != "CONFIGURED":
+        return "REFUSED", "MATLAB_OFFLINE_LICENSE_STATE_UNAVAILABLE"
+    if parsed["engine"] == "octave" and evidence["offline_license_state"] != "NOT_APPLICABLE":
+        return "REFUSED", "OCTAVE_OFFLINE_LICENSE_STATE_MUST_BE_NOT_APPLICABLE"
+    if resources["wall_time_ns"] is None:
+        return "REFUSED", "WALL_TIME_MEASUREMENT_UNAVAILABLE"
+    return "RESULT", None
+
+
+def _latest_other(rows: Sequence[Mapping[str, Any]], case_id: str, engine: str) -> Mapping[str, Any] | None:
+    for row in reversed(rows):
+        if row.get("case_id") == case_id and row.get("engine") != engine and row.get("row_state") == "RESULT":
+            return row
+    return None
+
+
+def ingest_result(payload: Mapping[str, Any]) -> dict[str, Any]:
+    parsed = _parse_ingest(payload)
+    with _LEDGER_LOCK:
+        rows = _read_rows()
+        if len(rows) >= MAX_LEDGER_ROWS:
+            raise DatasetUnavailable("LEDGER_ROW_LIMIT_EXCEEDED")
+        if any(row.get("run_id") == parsed["run_id"] for row in rows):
+            raise DatasetContractError("run_id already exists in the append-only ledger")
+        row_state, reason = _evidence_gate(parsed)
+        values = parsed["outcome"].get("values") if row_state == "RESULT" else None
+        diagnostics = _diagnostics(parsed["case"], values, parsed["reference"]) if values is not None else None
+        comparison_state = "UNAVAILABLE" if row_state == "UNAVAILABLE" else ("REFUSED" if row_state == "REFUSED" else "NOT_EVALUATED")
+        compared_to = None
+        if row_state == "RESULT":
+            other = _latest_other(rows, parsed["case"]["case_id"], parsed["engine"])
+            if other is not None:
+                compared_to = other["run_id"]
+                tolerance = parsed["case"]["request"]["tolerance"]
+                pair_matches = all(_within(left, right, tolerance) for left, right in zip(values, other["values"]))
+                own_gate = diagnostics["quality_gate"] == "PASS"
+                other_gate = (other.get("diagnostics") or {}).get("quality_gate") == "PASS"
+                comparison_state = "MATCH" if pair_matches and own_gate and other_gate else "CONFLICT"
+        core = {
+            "schema": ROW_SCHEMA,
+            "sequence": len(rows) + 1,
+            "run_id": parsed["run_id"],
+            "case_id": parsed["case"]["case_id"],
+            "fixture_sha256": parsed["case"]["fixture_sha256"],
+            "request_sha256": parsed["case"]["request_sha256"],
+            "engine": parsed["engine"],
+            "row_state": row_state,
+            "comparison_state": comparison_state,
+            "compared_to_run_id": compared_to,
+            "reason": reason,
+            "values": values,
+            "values_sha256": _adapter.digest_json(values) if values is not None else None,
+            "diagnostics": diagnostics,
+            "engine_evidence": parsed["engine_evidence"],
+            "containment": parsed["containment"],
+            "resources": parsed["resources"],
+            "reference": {key: value for key, value in parsed["reference"].items() if key != "values"},
+            "observed_at_utc": parsed["observed_at_utc"],
+            "evidence_label": "MEASURED" if row_state == "RESULT" else "UNKNOWN",
+            "evidence_origin": "AUTHENTICATED_APPEND_ONLY_INGESTION_NOT_LOCAL_ENGINE_EXECUTION",
+            "substrate_evidence": "UNKNOWN",
+            "signature_state": "UNSIGNED_INTEGRITY_CHAIN",
+            "previous_row_sha256": rows[-1]["row_sha256"] if rows else None,
+            **ZERO_UPLIFT,
+        }
+        row = {**core, "row_sha256": _adapter.digest_json(core)}
+        encoded = _adapter.canonical_json(row) + b"\n"
+        if len(encoded) > MAX_ROW_BYTES:
+            raise DatasetContractError("result row exceeds the 64 KiB append ceiling")
+        path = _ledger_path()
+        path.parent.mkdir(parents=True, exist_ok=True)
+        with path.open("ab") as handle:
+            handle.write(encoded)
+            handle.flush()
+            os.fsync(handle.fileno())
+        return row
+
+
+def _ingest_configured() -> bool:
+    digest = os.environ.get("A11OY_NUMERICS_DATASET_INGEST_TOKEN_SHA256", "").strip().lower()
+    return bool(_SHA256_RE.fullmatch(digest))
+
+
+def _authorized(token: str | None) -> bool:
+    expected = os.environ.get("A11OY_NUMERICS_DATASET_INGEST_TOKEN_SHA256", "").strip().lower()
+    if not _SHA256_RE.fullmatch(expected) or not token:
+        return False
+    return hmac.compare_digest(hashlib.sha256(token.encode("utf-8")).hexdigest(), expected)
+
+
+def dataset_status() -> dict[str, Any]:
+    manifest = preregistration()
+    curriculum = formula_curriculum()
+    rows = _read_rows()
+    classifications: dict[str, int] = {}
+    for row in rows:
+        token = row.get("comparison_state", "UNKNOWN")
+        classifications[token] = classifications.get(token, 0) + 1
+    runtime = _adapter.engine_status()
+    return {
+        "schema": STATUS_SCHEMA,
+        "service_state": "READY" if manifest["frozen_before_execution"] else "UNAVAILABLE",
+        "preregistration": {
+            "protocol_id": manifest["protocol_id"],
+            "state": manifest["state"],
+            "manifest_sha256": _adapter.digest_json(manifest),
+            "inputs_frozen": manifest["frozen_before_execution"],
+            "case_count": len(_case_index()),
+            "confirmatory_case_count": manifest["expected_case_counts"]["confirmatory"],
+            "exploratory_case_count": manifest["expected_case_counts"]["exploratory"],
+        },
+        "result_ledger": {
+            "row_count": len(rows),
+            "classification_counts": classifications,
+            "append_only": True,
+            "ingest_gate": "CONFIGURED" if _ingest_configured() else "UNAVAILABLE",
+            "path_disclosed": False,
+        },
+        "local_runtime": {
+            "octave": runtime["engines"]["octave"]["execution_state"],
+            "matlab": runtime["engines"]["matlab"]["execution_state"],
+            "network_isolation": runtime["controls"]["network_isolation"],
+            "network_denial_evidence": "NOT_EVALUATED",
+            "substrate_evidence": "UNKNOWN",
+        },
+        "reference_state": "MEASURED_PER_ROW_ONLY_WHEN_PINNED_EVIDENCE_IS_INGESTED",
+        "formula_curriculum": {
+            "state": curriculum["state"],
+            **curriculum["counts"],
+            "proof_uplift": 0,
+            "trust_uplift": 0,
+        },
+        "interpretation_guard": "MATCH is bounded cross-engine agreement for one frozen case; it is not proof or general correctness.",
+        **ZERO_UPLIFT,
+    }
+
+
+def _page_int(raw: str | None, default: int, name: str) -> int:
+    if raw is None:
+        return default
+    try:
+        value = int(raw)
+    except ValueError as exc:
+        raise DatasetContractError(f"{name} must be an integer") from exc
+    return value
+
+
+def register(app: Any, ns: str = "a11oy") -> str:
+    """Register read APIs and the authenticated append-only result endpoint."""
+
+    from fastapi.responses import JSONResponse
+
+    prefix = f"/api/{ns}/v1/numerics/dataset"
+
+    @app.get(f"{prefix}/status")
+    async def numerics_dataset_status() -> JSONResponse:
+        try:
+            return JSONResponse(dataset_status())
+        except DatasetUnavailable as exc:
+            return JSONResponse({"schema": STATUS_SCHEMA, "service_state": "UNAVAILABLE", "reason": str(exc), **ZERO_UPLIFT}, status_code=503)
+
+    @app.get(f"{prefix}/cases")
+    async def numerics_dataset_cases(request: Request) -> JSONResponse:
+        try:
+            result = list_cases(
+                offset=_page_int(request.query_params.get("offset"), 0, "offset"),
+                limit=_page_int(request.query_params.get("limit"), 25, "limit"),
+                family=request.query_params.get("family"),
+                operation=request.query_params.get("operation"),
+            )
+        except (DatasetContractError, DatasetUnavailable) as exc:
+            return JSONResponse({"state": "REJECTED", "error": str(exc), **ZERO_UPLIFT}, status_code=422)
+        return JSONResponse(result)
+
+    @app.get(f"{prefix}/cases/{{case_id}}")
+    async def numerics_dataset_case(case_id: str) -> JSONResponse:
+        try:
+            return JSONResponse(get_case(case_id))
+        except DatasetContractError as exc:
+            return JSONResponse({"state": "REJECTED", "error": str(exc), **ZERO_UPLIFT}, status_code=404)
+
+    @app.get(f"{prefix}/results")
+    async def numerics_dataset_results(request: Request) -> JSONResponse:
+        try:
+            result = list_results(
+                offset=_page_int(request.query_params.get("offset"), 0, "offset"),
+                limit=_page_int(request.query_params.get("limit"), 25, "limit"),
+                case_id=request.query_params.get("case_id"),
+            )
+        except (DatasetContractError, DatasetUnavailable) as exc:
+            return JSONResponse({"state": "UNAVAILABLE", "error": str(exc), **ZERO_UPLIFT}, status_code=503)
+        return JSONResponse(result)
+
+    @app.get(f"{prefix}/curriculum/formulas")
+    async def numerics_formula_curriculum() -> JSONResponse:
+        try:
+            return JSONResponse(formula_curriculum())
+        except DatasetUnavailable as exc:
+            return JSONResponse({
+                "schema": CURRICULUM_SCHEMA,
+                "state": "UNAVAILABLE",
+                "reason": str(exc),
+                **ZERO_UPLIFT,
+            }, status_code=503)
+
+    @app.post(f"{prefix}/results")
+    async def numerics_dataset_ingest(request: Request) -> JSONResponse:
+        if not _ingest_configured():
+            return JSONResponse({"state": "UNAVAILABLE", "reason": "INGEST_TOKEN_NOT_CONFIGURED", **ZERO_UPLIFT}, status_code=503)
+        if not _authorized(request.headers.get("x-a11oy-numerics-ingest-key")):
+            return JSONResponse({"state": "REFUSED", "reason": "INGEST_AUTHENTICATION_FAILED", **ZERO_UPLIFT}, status_code=401)
+        try:
+            payload = await _adapter._bounded_json_body(request)
+            row = ingest_result(payload)
+        except DatasetContractError as exc:
+            return JSONResponse({"state": "REJECTED", "error": str(exc), **ZERO_UPLIFT}, status_code=422)
+        except DatasetUnavailable as exc:
+            return JSONResponse({"state": "UNAVAILABLE", "error": str(exc), **ZERO_UPLIFT}, status_code=503)
+        return JSONResponse(row, status_code=201)
+
+    return (
+        "Numerics dataset registered: "
+        f"{prefix}/status · cases · case detail · append-only results; proof uplift=0"
+    )
+
+
+__all__ = [
+    "CASE_SCHEMA",
+    "CURRICULUM_SCHEMA",
+    "DatasetContractError",
+    "DatasetUnavailable",
+    "INGEST_SCHEMA",
+    "ROW_SCHEMA",
+    "dataset_status",
+    "formula_curriculum",
+    "get_case",
+    "ingest_result",
+    "list_cases",
+    "list_results",
+    "preregistration",
+    "register",
+]

szl_numerics_experiment.py

@@ -0,0 +1,482 @@
+# SPDX-License-Identifier: Apache-2.0
+"""Fail-closed executor for the preregistered MATLAB/Octave comparison.
+
+Taxonomy home: services/numerics.  The frozen 1,328-case design is read from
+``szl_numerics_dataset``.  A run starts only when both external engines, POSIX
+resource limits, a fresh ``unshare --net`` namespace, explicit operator
+license review, and a 100-decimal-place mpmath reference are available.
+Missing evidence produces a blocker receipt and zero engine invocations.
+
+This module never installs or bundles MATLAB, Octave, mpmath, licenses, model
+weights, or datasets.  ``MATCH`` means bounded agreement for one frozen case;
+it is not mathematical proof or general correctness.
+"""
+
+import argparse
+import datetime as _datetime
+import hashlib
+import importlib
+import json
+import os
+import platform
+import subprocess
+import sys
+import tempfile
+import time
+from pathlib import Path
+from typing import Any, Iterable, Mapping
+
+import szl_numerics_adapter as _adapter
+import szl_numerics_dataset as _dataset
+
+
+PREFLIGHT_SCHEMA = "szl.numerics.experiment-preflight/v1"
+EXPERIMENT_SCHEMA = "szl.numerics.preregistered-experiment/v1"
+REFERENCE_SCHEMA = "szl.numerics.mpmath-reference/v1"
+ZERO_UPLIFT = {"proof_uplift": 0, "trust_uplift": 0}
+_ROOT = Path(__file__).resolve().parent
+_ISOLATION_HELPER = _ROOT / "numerics" / "isolation_probe.py"
+_MAX_VERSION_OUTPUT_BYTES = 64 * 1024
+
+
+class ExperimentUnavailable(RuntimeError):
+    """A mandatory execution or evidence boundary is unavailable."""
+
+
+def _sha256_bytes(value: bytes) -> str:
+    return hashlib.sha256(value).hexdigest()
+
+
+def _sha256_file(path: Path) -> str:
+    digest = hashlib.sha256()
+    with path.open("rb") as handle:
+        for block in iter(lambda: handle.read(1024 * 1024), b""):
+            digest.update(block)
+    return digest.hexdigest()
+
+
+def _utc_now() -> str:
+    return _datetime.datetime.now(_datetime.timezone.utc).isoformat().replace("+00:00", "Z")
+
+
+def _child_env(work: Path) -> dict[str, str]:
+    """Return the fixed, secret-free environment for evidence-only children."""
+
+    return {
+        "HOME": str(work),
+        "TMPDIR": str(work),
+        "LANG": "C.UTF-8",
+        "LC_ALL": "C.UTF-8",
+        "PATH": "/usr/bin:/bin",
+    }
+
+
+def experiment_plan() -> dict[str, Any]:
+    manifest = _dataset.preregistration()
+    return {
+        "protocol_id": manifest["protocol_id"],
+        "protocol_version": manifest["protocol_version"],
+        "preregistration_sha256": _adapter.digest_json(manifest),
+        "frozen_before_execution": manifest["frozen_before_execution"],
+        "matrix_families": [item["id"] for item in manifest["confirmatory_matrix_families"]],
+        "exploratory_families": [item["id"] for item in manifest["exploratory_matrix_families"]],
+        "dimensions": manifest["matrix_dimensions"],
+        "condition_number_strata": manifest["condition_number_strata"],
+        "seeds": manifest["deterministic_seeds"],
+        "tolerance": manifest["tolerance"],
+        "engines": manifest["engines"],
+        "case_counts": manifest["expected_case_counts"],
+        "planned_engine_runs": manifest["expected_case_counts"]["total"] * len(manifest["engines"]),
+        "result_claim": "NO_ENGINE_RESULT_IN_PLAN",
+    }
+
+
+def _mpmath_status() -> dict[str, Any]:
+    try:
+        module = importlib.import_module("mpmath")
+    except (ImportError, OSError):
+        return {"state": "UNAVAILABLE", "version": None}
+    version = str(getattr(module, "__version__", "")).strip()
+    if not version:
+        return {"state": "UNAVAILABLE", "version": None}
+    return {"state": "AVAILABLE_UNPROBED", "version": version}
+
+
+def _engine_path(status: Mapping[str, Any], engine: str) -> Path | None:
+    details = status["engines"][engine]
+    raw = details.get("executable_path") if engine == "octave" else details.get("service_executable_path")
+    if not raw:
+        return None
+    path = Path(str(raw))
+    return path if path.is_absolute() and path.is_file() else None
+
+
+def preflight(
+    *,
+    status: Mapping[str, Any] | None = None,
+    environ: Mapping[str, str] | None = None,
+    os_name: str | None = None,
+    mpmath_status: Mapping[str, Any] | None = None,
+) -> dict[str, Any]:
+    environment = os.environ if environ is None else environ
+    runtime = dict(_adapter.engine_status() if status is None else status)
+    host_os = os.name if os_name is None else os_name
+    controls = runtime["controls"]
+    reasons: list[str] = []
+    if host_os != "posix":
+        reasons.append("POSIX_RESOURCE_AND_NETWORK_ISOLATION_UNAVAILABLE")
+    if not controls.get("network_launcher"):
+        reasons.append("NETWORK_NAMESPACE_LAUNCHER_UNAVAILABLE")
+    if controls.get("resource_limits") != "PRESENT":
+        reasons.append("POSIX_RESOURCE_LIMITS_UNAVAILABLE")
+    engines: dict[str, Any] = {}
+    for engine in ("octave", "matlab"):
+        path = _engine_path(runtime, engine)
+        reviewed = environment.get(f"A11OY_{engine.upper()}_LICENSE_REVIEWED") == "1"
+        state = runtime["engines"][engine].get("execution_state", "UNAVAILABLE")
+        if state != "READY_TO_ATTEMPT" or path is None:
+            reasons.append(f"{engine.upper()}_ENGINE_UNAVAILABLE")
+        if not reviewed:
+            reasons.append(f"{engine.upper()}_LICENSE_REVIEW_UNAVAILABLE")
+        engines[engine] = {
+            "execution_state": state,
+            "executable_sha256": _sha256_file(path) if path is not None else None,
+            "license_review": "OPERATOR_REVIEWED" if reviewed else "REVIEW_REQUIRED",
+            "offline_license_state": (
+                "CONFIGURED_UNVERIFIED"
+                if engine == "matlab" and runtime["engines"][engine].get("offline_license_configuration") == "CONFIGURED_UNVERIFIED"
+                else ("NOT_APPLICABLE" if engine == "octave" else "UNAVAILABLE")
+            ),
+        }
+    reference = dict(_mpmath_status() if mpmath_status is None else mpmath_status)
+    if reference.get("state") == "UNAVAILABLE":
+        reasons.append("MPMATH_100DP_REFERENCE_UNAVAILABLE")
+    core = {
+        "schema": PREFLIGHT_SCHEMA,
+        "state": "READY_TO_PROBE" if not reasons else "BLOCKED",
+        "observed_at_utc": _utc_now(),
+        "host": {
+            "os_name": host_os,
+            "system": platform.system(),
+            "machine": platform.machine(),
+            "python": platform.python_version(),
+        },
+        "plan": experiment_plan(),
+        "engines": engines,
+        "controls": {
+            "network_isolation": controls.get("network_isolation", "SOURCE_UNAVAILABLE"),
+            "network_launcher_sha256": _sha256_file(Path(controls["network_launcher"])) if controls.get("network_launcher") and Path(controls["network_launcher"]).is_file() else None,
+            "resource_limits": controls.get("resource_limits", "SOURCE_UNAVAILABLE"),
+            "memory_limit_bytes": controls.get("memory_limit_bytes"),
+            "output_limit_bytes": controls.get("output_limit_bytes"),
+            "timeout_limit_seconds": controls.get("timeout_limit_seconds"),
+        },
+        "reference": {**reference, "precision_decimal_digits": 100},
+        "blockers": sorted(set(reasons)),
+        "engine_invocations": 0,
+        "result_rows": 0,
+        "network_denial_evidence": "NOT_EVALUATED",
+        "substrate_evidence": "UNKNOWN",
+        "interpretation_guard": "A ready preflight is permission to probe, not an engine result or agreement claim.",
+        **ZERO_UPLIFT,
+    }
+    return {**core, "receipt_sha256": _adapter.digest_json(core)}
+
+
+def _isolation_probe(status: Mapping[str, Any]) -> dict[str, Any]:
+    if os.name != "posix" or not _ISOLATION_HELPER.is_file():
+        raise ExperimentUnavailable("NETWORK_NAMESPACE_EVIDENCE_UNAVAILABLE")
+    launcher = status["controls"].get("network_launcher")
+    if not launcher:
+        raise ExperimentUnavailable("NETWORK_NAMESPACE_EVIDENCE_UNAVAILABLE")
+    parent_namespace = os.readlink("/proc/self/ns/net")
+    with tempfile.TemporaryDirectory(prefix="a11oy-numerics-netprobe-") as tmp:
+        evidence_path = Path(tmp) / "network-evidence.json"
+        command = [launcher, "--net", "--", sys.executable, "-I", str(_ISOLATION_HELPER), str(evidence_path)]
+        try:
+            completed = subprocess.run(
+                command,
+                cwd=tmp,
+                env=_child_env(Path(tmp)),
+                stdin=subprocess.DEVNULL,
+                stdout=subprocess.DEVNULL,
+                stderr=subprocess.DEVNULL,
+                shell=False,
+                timeout=5,
+                check=False,
+                preexec_fn=_adapter._preexec_limits(5),
+            )
+        except (OSError, subprocess.TimeoutExpired) as exc:
+            raise ExperimentUnavailable("NETWORK_NAMESPACE_PROBE_FAILED") from exc
+        if completed.returncode != 0 or not evidence_path.is_file() or evidence_path.stat().st_size > 16 * 1024:
+            raise ExperimentUnavailable("NETWORK_NAMESPACE_PROBE_FAILED")
+        try:
+            child = json.loads(evidence_path.read_text(encoding="utf-8"))
+        except (OSError, json.JSONDecodeError) as exc:
+            raise ExperimentUnavailable("NETWORK_NAMESPACE_EVIDENCE_INVALID") from exc
+    if child.get("schema") != "szl.numerics.network-namespace-evidence/v1":
+        raise ExperimentUnavailable("NETWORK_NAMESPACE_EVIDENCE_INVALID")
+    if child.get("network_operations_performed") != 0 or child.get("network_namespace") == parent_namespace:
+        raise ExperimentUnavailable("NETWORK_NAMESPACE_NOT_SEPARATE")
+    if child.get("interfaces") != ["lo"] or child.get("loopback_operstate") not in ("down", "unknown"):
+        raise ExperimentUnavailable("NETWORK_NAMESPACE_NOT_DENY_BY_DEFAULT")
+    core = {
+        **child,
+        "state": "DENIED",
+        "parent_network_namespace": parent_namespace,
+        "launcher_sha256": _sha256_file(Path(launcher)),
+        "helper_sha256": _sha256_file(_ISOLATION_HELPER),
+    }
+    return {**core, "evidence_sha256": _adapter.digest_json(core)}
+
+
+def _probe_engine_version(engine: str, status: Mapping[str, Any]) -> dict[str, Any]:
+    path = _engine_path(status, engine)
+    launcher = status["controls"].get("network_launcher")
+    if path is None or not launcher:
+        raise ExperimentUnavailable(f"{engine.upper()}_VERSION_PROBE_UNAVAILABLE")
+    if engine == "octave":
+        command = [launcher, "--net", "--", str(path), "--version"]
+    else:
+        command = [launcher, "--net", "--", str(path), "--version"]
+    try:
+        with tempfile.TemporaryDirectory(prefix=f"a11oy-numerics-{engine}-version-") as tmp:
+            completed = subprocess.run(
+                command,
+                cwd=tmp,
+                env=_child_env(Path(tmp)),
+                stdin=subprocess.DEVNULL,
+                stdout=subprocess.PIPE,
+                stderr=subprocess.STDOUT,
+                shell=False,
+                timeout=8,
+                check=False,
+                preexec_fn=_adapter._preexec_limits(8),
+            )
+    except (OSError, subprocess.TimeoutExpired) as exc:
+        raise ExperimentUnavailable(f"{engine.upper()}_VERSION_PROBE_FAILED") from exc
+    output = completed.stdout or b""
+    if completed.returncode != 0 or not output or len(output) > _MAX_VERSION_OUTPUT_BYTES:
+        raise ExperimentUnavailable(f"{engine.upper()}_VERSION_PROBE_FAILED")
+    try:
+        lines = [line.strip() for line in output.decode("utf-8").splitlines() if line.strip()]
+    except UnicodeDecodeError as exc:
+        raise ExperimentUnavailable(f"{engine.upper()}_VERSION_PROBE_INVALID") from exc
+    if not lines or len(lines[0]) > 120:
+        raise ExperimentUnavailable(f"{engine.upper()}_VERSION_PROBE_INVALID")
+    return {
+        "version": lines[0],
+        "version_evidence_sha256": _sha256_bytes(output),
+        "executable_sha256": _sha256_file(path),
+    }
+
+
+def _iter_cases() -> Iterable[dict[str, Any]]:
+    offset = 0
+    total = experiment_plan()["case_counts"]["total"]
+    while offset < total:
+        page = _dataset.list_cases(offset=offset, limit=min(100, total - offset))
+        for descriptor in page["items"]:
+            yield _dataset.get_case(descriptor["case_id"])
+        offset += len(page["items"])
+        if not page["items"]:
+            raise ExperimentUnavailable("PREREGISTERED_CASE_ENUMERATION_INCOMPLETE")
+
+
+def _reference(case: Mapping[str, Any]) -> tuple[dict[str, Any], dict[str, Any]]:
+    try:
+        mp = importlib.import_module("mpmath")
+    except ImportError as exc:
+        raise ExperimentUnavailable("MPMATH_100DP_REFERENCE_UNAVAILABLE") from exc
+    mp.mp.dps = 100
+    matrix = mp.matrix([[mp.mpf(format(value, ".17g")) for value in row] for row in case["request"]["inputs"]["matrix"]])
+    operation = case["operation"]
+    if operation == "SYMMETRIC_EIGENVALUES":
+        computed = mp.eigsy(matrix, eigvals_only=True)
+        values_mp = [computed[index] for index in range(len(computed))]
+    else:
+        rhs = mp.matrix([mp.mpf(format(value, ".17g")) for value in case["request"]["inputs"]["rhs"]])
+        computed = mp.lu_solve(matrix, rhs)
+        values_mp = [computed[index] for index in range(len(computed))]
+    decimal_values = [mp.nstr(value, 105, strip_zeros=False) for value in values_mp]
+    evidence_core = {
+        "schema": REFERENCE_SCHEMA,
+        "case_id": case["case_id"],
+        "fixture_sha256": case["fixture_sha256"],
+        "implementation": "PYTHON_MPMATH_100DP",
+        "mpmath_version": str(mp.__version__),
+        "precision_decimal_digits": 100,
+        "decimal_values": decimal_values,
+    }
+    evidence_sha256 = _adapter.digest_json(evidence_core)
+    return (
+        {
+            "state": "MEASURED",
+            "implementation": "PYTHON_MPMATH_100DP",
+            "values": [float(value) for value in values_mp],
+            "evidence_sha256": evidence_sha256,
+        },
+        {**evidence_core, "evidence_sha256": evidence_sha256},
+    )
+
+
+def _child_cpu_snapshot() -> tuple[int | None, int | None]:
+    try:
+        import resource
+
+        usage = resource.getrusage(resource.RUSAGE_CHILDREN)
+    except (ImportError, OSError):
+        return None, None
+    return int(usage.ru_utime * 1_000_000_000), int(usage.ru_stime * 1_000_000_000)
+
+
+def _observe_case(
+    engine: str,
+    case: Mapping[str, Any],
+    version: Mapping[str, Any],
+    isolation: Mapping[str, Any],
+) -> tuple[dict[str, Any], dict[str, Any]]:
+    request = case["request"]
+    before_user, before_system = _child_cpu_snapshot()
+    started = time.perf_counter_ns()
+    result = _adapter.run_engine(engine, request)
+    elapsed = time.perf_counter_ns() - started
+    after_user, after_system = _child_cpu_snapshot()
+    user_ns = after_user - before_user if before_user is not None and after_user is not None else None
+    system_ns = after_system - before_system if before_system is not None and after_system is not None else None
+    reference, reference_evidence = _reference(case)
+    outcome = (
+        {"state": "RESULT", "values": result["values"]}
+        if result["state"] == "RESULT"
+        else {"state": "UNAVAILABLE", "reason": str(result.get("reason") or "ENGINE_UNAVAILABLE")[:160]}
+    )
+    # Keep the append-ledger identifier inside the strict 96-character ID
+    # boundary without sacrificing uniqueness or reproducibility.  The case
+    # request digest is frozen by the preregistration.
+    run_id = f"{engine}-{str(case['case_id'])[:40]}-{str(case['request_sha256'])[:16]}"
+    payload = {
+        "schema": _dataset.INGEST_SCHEMA,
+        "run_id": run_id,
+        "case_id": case["case_id"],
+        "engine": engine,
+        "outcome": outcome,
+        "engine_evidence": {
+            **version,
+            "license_state": "OPERATOR_REVIEWED",
+            "offline_license_state": "CONFIGURED" if engine == "matlab" else "NOT_APPLICABLE",
+        },
+        "containment": {"network_state": "DENIED", "evidence_sha256": isolation["evidence_sha256"]},
+        "resources": {
+            "wall_time_ns": elapsed,
+            "child_user_cpu_ns": user_ns,
+            "child_system_cpu_ns": system_ns,
+            "peak_resident_bytes": None,
+            "request_bytes": len(_adapter.canonical_json(request)),
+            "response_bytes": len(_adapter.canonical_json(result)),
+            "log_bytes": None,
+        },
+        "reference": reference,
+        "observed_at_utc": _utc_now(),
+    }
+    return _dataset.ingest_result(payload), reference_evidence
+
+
+def _write_json(path: Path, value: Mapping[str, Any]) -> None:
+    encoded = json.dumps(value, indent=2, sort_keys=True, ensure_ascii=False) + "\n"
+    path.parent.mkdir(parents=True, exist_ok=True)
+    temporary = path.with_suffix(path.suffix + ".tmp")
+    with temporary.open("w", encoding="utf-8", newline="\n") as handle:
+        handle.write(encoded)
+        handle.flush()
+        os.fsync(handle.fileno())
+    os.replace(temporary, path)
+
+
+def run_preregistered(*, execute_all: bool = False) -> dict[str, Any]:
+    check = preflight()
+    core: dict[str, Any] = {
+        "schema": EXPERIMENT_SCHEMA,
+        "state": "BLOCKED" if check["state"] == "BLOCKED" else ("READY_NOT_EXECUTED" if not execute_all else "RUNNING"),
+        "observed_at_utc": _utc_now(),
+        "plan": check["plan"],
+        "preflight_receipt_sha256": check["receipt_sha256"],
+        "preflight": check,
+        "engine_invocations": 0,
+        "engine_invocation_semantics": "ADAPTER_CALLS; CHILD_PROCESS_STARTS_NOT_INDEPENDENTLY_COUNTED",
+        "result_rows": 0,
+        "pair_outcomes": {"MATCH": 0, "CONFLICT": 0, "UNAVAILABLE": 0},
+        "reference_rows": 0,
+        "substrate_evidence": "UNKNOWN",
+        "interpretation_guard": "MATCH is case-scoped numerical agreement, not proof or a general engine-quality claim.",
+        **ZERO_UPLIFT,
+    }
+    if check["state"] == "BLOCKED" or not execute_all:
+        return {**core, "receipt_sha256": _adapter.digest_json(core)}
+
+    runtime = _adapter.engine_status()
+    try:
+        isolation = _isolation_probe(runtime)
+        versions = {engine: _probe_engine_version(engine, runtime) for engine in ("octave", "matlab")}
+    except ExperimentUnavailable as exc:
+        core.update({"state": "BLOCKED", "blocker": str(exc)})
+        return {**core, "receipt_sha256": _adapter.digest_json(core)}
+
+    reference_chain: list[dict[str, Any]] = []
+    outcomes = {"MATCH": 0, "CONFLICT": 0, "UNAVAILABLE": 0}
+    invocations = 0
+    result_rows = 0
+    for case in _iter_cases():
+        pair: list[dict[str, Any]] = []
+        for engine in ("octave", "matlab"):
+            row, reference_evidence = _observe_case(engine, case, versions[engine], isolation)
+            invocations += 1
+            result_rows += 1
+            pair.append(row)
+            if not reference_chain or reference_chain[-1]["case_id"] != case["case_id"]:
+                reference_chain.append(reference_evidence)
+        final_state = pair[-1]["comparison_state"] if pair[-1]["comparison_state"] in ("MATCH", "CONFLICT") else "UNAVAILABLE"
+        outcomes[final_state] += 1
+
+    complete = (
+        result_rows == core["plan"]["planned_engine_runs"]
+        and sum(outcomes.values()) == core["plan"]["case_counts"]["total"]
+        and outcomes["UNAVAILABLE"] == 0
+    )
+    core.update({
+        "state": "COMPLETE" if complete else "INCOMPLETE",
+        "engine_invocations": invocations,
+        "result_rows": result_rows,
+        "pair_outcomes": outcomes,
+        "reference_rows": len(reference_chain),
+        "reference_evidence": reference_chain,
+        "reference_chain_sha256": _adapter.digest_json(reference_chain),
+        "network_denial_evidence_sha256": isolation["evidence_sha256"],
+        "engine_versions": versions,
+        "substrate_evidence": "UNKNOWN",
+    })
+    return {**core, "receipt_sha256": _adapter.digest_json(core)}
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = argparse.ArgumentParser(description="Run or preflight the frozen MATLAB/Octave comparison")
+    parser.add_argument("--execute-all", action="store_true", help="run all 1,328 cases on both engines after every gate passes")
+    parser.add_argument("--output", type=Path, required=True, help="write one atomic JSON experiment receipt")
+    args = parser.parse_args(argv)
+    receipt = run_preregistered(execute_all=args.execute_all)
+    _write_json(args.output, receipt)
+    print(json.dumps({"state": receipt["state"], "receipt_sha256": receipt["receipt_sha256"]}, sort_keys=True))
+    return 0 if receipt["state"] in ("READY_NOT_EXECUTED", "COMPLETE") else 2
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())
+
+
+__all__ = [
+    "EXPERIMENT_SCHEMA",
+    "PREFLIGHT_SCHEMA",
+    "ExperimentUnavailable",
+    "experiment_plan",
+    "preflight",
+    "run_preregistered",
+]

szl_provider_http.py

@@ -0,0 +1,463 @@
+"""Bounded, fail-closed HTTP JSON transport for provider control planes.
+
+This module is deliberately independent from the provider registry so every
+provider adapter can share one outbound-security boundary.  It does not log
+URLs, headers, request bodies, response bodies, or exception text.  Failures
+return stable error codes and never synthesize a document.
+
+Public destinations are allowed by default.  Operator-controlled self-hosted
+destinations (loopback, RFC1918/ULA, and CGNAT/Tailscale space) require the
+caller to pass ``allow_private=True`` explicitly.  Link-local destinations,
+including cloud metadata ranges, remain forbidden even with that opt-in.
+"""
+
+from __future__ import annotations
+
+import http.client
+import ipaddress
+import json
+import math
+import queue
+import socket
+import ssl
+import threading
+import time
+from dataclasses import dataclass
+from typing import Any, Mapping
+from urllib.parse import quote, urljoin, urlsplit
+
+
+DEFAULT_TIMEOUT_S = 4.0
+MAX_TIMEOUT_S = 120.0
+DEFAULT_MAX_RESPONSE_BYTES = 1_048_576
+MAX_RESPONSE_BYTES = 8_388_608
+MAX_REQUEST_BYTES = 8_388_608
+DEFAULT_MAX_REDIRECTS = 2
+MAX_REDIRECTS = 5
+MAX_LOCATION_BYTES = 8_192
+
+_REDIRECT_STATUSES = frozenset({301, 302, 303, 307, 308})
+_SENSITIVE_REDIRECT_HEADERS = frozenset(
+    {"authorization", "proxy-authorization", "cookie"}
+)
+_RESERVED_REQUEST_HEADERS = frozenset(
+    {"host", "content-length", "transfer-encoding", "connection"}
+)
+
+
+@dataclass(frozen=True)
+class _Target:
+    """A parsed target pinned to the addresses validated for this hop."""
+
+    url: str
+    scheme: str
+    hostname: str
+    port: int
+    request_target: str
+    host_header: str
+    origin: tuple[str, str, int]
+    addresses: tuple[str, ...]
+
+
+class _PinnedHTTPSConnection(http.client.HTTPSConnection):
+    """HTTPS connection that uses a validated IP while verifying the URL host."""
+
+    def __init__(
+        self,
+        hostname: str,
+        address: str,
+        port: int,
+        *,
+        timeout: float,
+        context: ssl.SSLContext,
+    ) -> None:
+        super().__init__(hostname, port=port, timeout=timeout, context=context)
+        self._validated_address = address
+
+    def connect(self) -> None:
+        self.sock = socket.create_connection(
+            (self._validated_address, self.port),
+            self.timeout,
+            self.source_address,
+        )
+        self.sock = self._context.wrap_socket(self.sock, server_hostname=self.host)
+
+
+def _remaining(deadline: float) -> float:
+    return max(0.0, deadline - time.monotonic())
+
+
+def _contains_control(value: str) -> bool:
+    return any(ord(ch) < 32 or ord(ch) == 127 for ch in value)
+
+
+def _resolve_bounded(hostname: str, port: int, deadline: float) -> tuple[Any, str | None]:
+    """Run DNS in a daemon thread so a resolver stall cannot exceed the call budget."""
+
+    remaining = _remaining(deadline)
+    if remaining <= 0:
+        return None, "TIMEOUT"
+
+    result: queue.Queue[tuple[Any, str | None]] = queue.Queue(maxsize=1)
+
+    def _worker() -> None:
+        try:
+            infos = socket.getaddrinfo(
+                hostname,
+                port,
+                family=socket.AF_UNSPEC,
+                type=socket.SOCK_STREAM,
+            )
+            item: tuple[Any, str | None] = (infos, None)
+        except Exception:  # DNS details can contain a secret-bearing URL on some stacks.
+            item = (None, "DNS_RESOLUTION_FAILED")
+        try:
+            result.put_nowait(item)
+        except queue.Full:
+            pass
+
+    threading.Thread(target=_worker, name="provider-dns", daemon=True).start()
+    try:
+        return result.get(timeout=remaining)
+    except queue.Empty:
+        return None, "TIMEOUT"
+
+
+def _classify_address(value: str, *, allow_private: bool) -> str | None:
+    try:
+        address = ipaddress.ip_address(value)
+    except ValueError:
+        return "DNS_INVALID_ADDRESS"
+
+    # Apply the IPv4 policy to IPv4-mapped IPv6 values as well.
+    if isinstance(address, ipaddress.IPv6Address) and address.ipv4_mapped:
+        address = address.ipv4_mapped
+
+    # Link-local is always denied: it includes the common cloud metadata path.
+    # ``ipaddress`` also classifies IPv6 loopback (``::1``) as reserved on some
+    # Python versions.  Loopback is an explicitly supported self-hosted target,
+    # so do not let that implementation detail override ``allow_private=True``.
+    if (
+        address.is_unspecified
+        or address.is_multicast
+        or address.is_link_local
+        or (address.is_reserved and not address.is_loopback)
+    ):
+        return "DESTINATION_FORBIDDEN"
+
+    # is_global=False covers loopback, RFC1918/ULA, and CGNAT/Tailscale space.
+    if not address.is_global and not allow_private:
+        return "PRIVATE_DESTINATION_REQUIRES_OPT_IN"
+    return None
+
+
+def _validate_target(
+    url: str,
+    *,
+    allow_private: bool,
+    deadline: float,
+) -> tuple[_Target | None, str | None]:
+    if not isinstance(url, str) or not url or _contains_control(url):
+        return None, "INVALID_URL"
+    try:
+        parts = urlsplit(url)
+    except (TypeError, ValueError):
+        return None, "INVALID_URL"
+
+    scheme = parts.scheme.lower()
+    if scheme not in {"http", "https"}:
+        return None, "INVALID_URL_SCHEME"
+    if parts.username is not None or parts.password is not None:
+        return None, "URL_CREDENTIALS_FORBIDDEN"
+    if parts.fragment:
+        return None, "URL_FRAGMENT_FORBIDDEN"
+    if not parts.hostname or "\\" in parts.netloc:
+        return None, "INVALID_URL"
+
+    try:
+        hostname = parts.hostname.encode("idna").decode("ascii").lower()
+        port = parts.port or (443 if scheme == "https" else 80)
+    except (UnicodeError, ValueError):
+        return None, "INVALID_URL"
+
+    infos, resolve_error = _resolve_bounded(hostname, port, deadline)
+    if resolve_error:
+        return None, resolve_error
+
+    addresses: list[str] = []
+    for family, _socktype, _proto, _canonname, sockaddr in infos or []:
+        if family not in {socket.AF_INET, socket.AF_INET6} or not sockaddr:
+            continue
+        address = str(sockaddr[0])
+        policy_error = _classify_address(address, allow_private=allow_private)
+        if policy_error:
+            # Reject a mixed public/private DNS answer; never select only its safe half.
+            return None, policy_error
+        if address not in addresses:
+            addresses.append(address)
+    if not addresses:
+        return None, "DNS_NO_ADDRESSES"
+
+    path = quote(parts.path or "/", safe="/%:@-._~!$&'()*+,;=")
+    query = quote(parts.query, safe="/%?:@-._~!$&'()*+,;=")
+    request_target = path + (("?" + query) if query else "")
+    default_port = 443 if scheme == "https" else 80
+    display_host = "[" + hostname + "]" if ":" in hostname else hostname
+    host_header = display_host if port == default_port else f"{display_host}:{port}"
+    return (
+        _Target(
+            url=url,
+            scheme=scheme,
+            hostname=hostname,
+            port=port,
+            request_target=request_target,
+            host_header=host_header,
+            origin=(scheme, hostname, port),
+            addresses=tuple(addresses),
+        ),
+        None,
+    )
+
+
+def _prepare_headers(headers: Mapping[str, str] | None) -> tuple[dict[str, str] | None, str | None]:
+    prepared = {
+        "Accept": "application/json",
+        "User-Agent": "a11oy-provider-http/1.0",
+    }
+    if headers is None:
+        return prepared, None
+    if not isinstance(headers, Mapping):
+        return None, "INVALID_HEADERS"
+    for name, value in headers.items():
+        if not isinstance(name, str) or not isinstance(value, str):
+            return None, "INVALID_HEADERS"
+        normalized = name.strip().lower()
+        if (
+            not normalized
+            or normalized in _RESERVED_REQUEST_HEADERS
+            or ":" in name
+            or _contains_control(name)
+            or _contains_control(value)
+        ):
+            return None, "INVALID_HEADERS"
+        prepared[name] = value
+    return prepared, None
+
+
+def _request_once(
+    target: _Target,
+    *,
+    method: str,
+    body: bytes | None,
+    headers: Mapping[str, str],
+    deadline: float,
+) -> tuple[http.client.HTTPResponse | None, http.client.HTTPConnection | None, str | None]:
+    last_error = "NETWORK_FAILURE"
+    for address in target.addresses:
+        remaining = _remaining(deadline)
+        if remaining <= 0:
+            return None, None, "TIMEOUT"
+        connection: http.client.HTTPConnection
+        try:
+            if target.scheme == "https":
+                connection = _PinnedHTTPSConnection(
+                    target.hostname,
+                    address,
+                    target.port,
+                    timeout=remaining,
+                    context=ssl.create_default_context(),
+                )
+            else:
+                connection = http.client.HTTPConnection(
+                    address,
+                    port=target.port,
+                    timeout=remaining,
+                )
+            hop_headers = dict(headers)
+            hop_headers["Host"] = target.host_header
+            connection.request(
+                method,
+                target.request_target,
+                body=body,
+                headers=hop_headers,
+            )
+            response_budget = _remaining(deadline)
+            if response_budget <= 0:
+                connection.close()
+                return None, None, "TIMEOUT"
+            if connection.sock is not None:
+                connection.sock.settimeout(response_budget)
+            return connection.getresponse(), connection, None
+        except (TimeoutError, socket.timeout):
+            last_error = "TIMEOUT"
+        except ssl.SSLError:
+            last_error = "TLS_FAILURE"
+        except Exception:
+            last_error = "NETWORK_FAILURE"
+        try:
+            connection.close()
+        except Exception:
+            pass
+    return None, None, last_error
+
+
+def http_json(
+    url: str,
+    *,
+    method: str = "GET",
+    body: bytes | None = None,
+    headers: Mapping[str, str] | None = None,
+    timeout: float = DEFAULT_TIMEOUT_S,
+    max_response_bytes: int = DEFAULT_MAX_RESPONSE_BYTES,
+    max_redirects: int = DEFAULT_MAX_REDIRECTS,
+    allow_private: bool = False,
+) -> tuple[Any, str | None]:
+    """Fetch one JSON document through the bounded provider transport.
+
+    Returns ``(document, None)`` only after a real 2xx response containing valid
+    UTF-8 JSON.  Every failure returns ``(None, STABLE_ERROR_CODE)``.  The caller
+    must set ``allow_private=True`` only for an operator-controlled self-hosted
+    base URL (for example local Ollama at ``127.0.0.1:11434``).
+    """
+
+    method = method.upper() if isinstance(method, str) else ""
+    if method not in {"GET", "POST"}:
+        return None, "INVALID_METHOD"
+    # Private routing is an explicit capability grant, not a truthy option.
+    if not isinstance(allow_private, bool):
+        return None, "INVALID_PRIVATE_OPT_IN"
+    if body is not None and not isinstance(body, (bytes, bytearray)):
+        return None, "INVALID_BODY"
+    body_bytes = bytes(body) if body is not None else None
+    if body_bytes is not None and len(body_bytes) > MAX_REQUEST_BYTES:
+        return None, "REQUEST_TOO_LARGE"
+    try:
+        timeout_value = float(timeout)
+    except (TypeError, ValueError):
+        return None, "INVALID_TIMEOUT"
+    if (
+        isinstance(timeout, bool)
+        or not math.isfinite(timeout_value)
+        or timeout_value <= 0
+        or timeout_value > MAX_TIMEOUT_S
+    ):
+        return None, "INVALID_TIMEOUT"
+    if (
+        isinstance(max_response_bytes, bool)
+        or not isinstance(max_response_bytes, int)
+        or max_response_bytes <= 0
+        or max_response_bytes > MAX_RESPONSE_BYTES
+    ):
+        return None, "INVALID_RESPONSE_LIMIT"
+    if (
+        isinstance(max_redirects, bool)
+        or not isinstance(max_redirects, int)
+        or max_redirects < 0
+        or max_redirects > MAX_REDIRECTS
+    ):
+        return None, "INVALID_REDIRECT_LIMIT"
+
+    active_headers, header_error = _prepare_headers(headers)
+    if header_error or active_headers is None:
+        return None, header_error or "INVALID_HEADERS"
+    if body_bytes is not None and not any(k.lower() == "content-type" for k in active_headers):
+        active_headers["Content-Type"] = "application/json"
+
+    deadline = time.monotonic() + timeout_value
+    current_url = url
+    current_method = method
+    current_body = body_bytes
+    redirects_followed = 0
+    previous_origin: tuple[str, str, int] | None = None
+
+    while True:
+        target, validation_error = _validate_target(
+            current_url,
+            allow_private=allow_private,
+            deadline=deadline,
+        )
+        if validation_error or target is None:
+            return None, validation_error or "INVALID_URL"
+
+        if previous_origin is not None and target.origin != previous_origin:
+            active_headers = {
+                key: value
+                for key, value in active_headers.items()
+                if key.lower() not in _SENSITIVE_REDIRECT_HEADERS
+            }
+
+        response, connection, request_error = _request_once(
+            target,
+            method=current_method,
+            body=current_body,
+            headers=active_headers,
+            deadline=deadline,
+        )
+        if request_error or response is None or connection is None:
+            return None, request_error or "NETWORK_FAILURE"
+        try:
+            status = int(response.status)
+            if status in _REDIRECT_STATUSES:
+                location = response.getheader("Location")
+                if not location:
+                    return None, "REDIRECT_MISSING_LOCATION"
+                if len(location.encode("utf-8", "ignore")) > MAX_LOCATION_BYTES:
+                    return None, "REDIRECT_LOCATION_TOO_LARGE"
+                if redirects_followed >= max_redirects:
+                    return None, "REDIRECT_LIMIT_EXCEEDED"
+                next_url = urljoin(current_url, location)
+                if status == 303:
+                    current_method = "GET"
+                    current_body = None
+                    active_headers = {
+                        key: value
+                        for key, value in active_headers.items()
+                        if key.lower() != "content-type"
+                    }
+                previous_origin = target.origin
+                current_url = next_url
+                redirects_followed += 1
+                continue
+
+            if not 200 <= status < 300:
+                return None, f"HTTP_STATUS:{status}"
+
+            content_length = response.getheader("Content-Length")
+            if content_length:
+                try:
+                    parsed_length = int(content_length)
+                    if parsed_length < 0:
+                        return None, "INVALID_CONTENT_LENGTH"
+                    if parsed_length > max_response_bytes:
+                        return None, "RESPONSE_TOO_LARGE"
+                except ValueError:
+                    return None, "INVALID_CONTENT_LENGTH"
+            read_budget = _remaining(deadline)
+            if read_budget <= 0:
+                return None, "TIMEOUT"
+            if connection.sock is not None:
+                connection.sock.settimeout(read_budget)
+            raw = response.read(max_response_bytes + 1)
+            if len(raw) > max_response_bytes:
+                return None, "RESPONSE_TOO_LARGE"
+            try:
+                return json.loads(raw.decode("utf-8")), None
+            except (UnicodeDecodeError, json.JSONDecodeError):
+                return None, "INVALID_JSON"
+        except (TimeoutError, socket.timeout):
+            return None, "TIMEOUT"
+        except Exception:
+            return None, "NETWORK_FAILURE"
+        finally:
+            connection.close()
+
+
+__all__ = [
+    "DEFAULT_MAX_REDIRECTS",
+    "DEFAULT_MAX_RESPONSE_BYTES",
+    "DEFAULT_TIMEOUT_S",
+    "MAX_REDIRECTS",
+    "MAX_RESPONSE_BYTES",
+    "MAX_TIMEOUT_S",
+    "http_json",
+]

szl_quant_qbio_holo.py

@@ -103,10 +103,19 @@ def _qbio_status() -> Dict[str, Any]:
         comp = qb.compass(50.0)
         lam = qb.lambda_v5(0.9, 121.5, 130.0)
         sources = dict(getattr(qb, "SOURCES", {}))
+        verification_scope = getattr(
+            qb, "VERIFICATION_SCOPE", "COMPUTATIONAL_REPRODUCIBILITY_ONLY"
+        )
+        verification_boundary = getattr(
+            qb,
+            "VERIFICATION_BOUNDARY",
+            "Executed deterministic model output; not experimental validation.",
+        )
         models = [
             {"model": "Mitchell proton-motive force",
              "equation": "Δp = ΔΨ − (2.3 RT / F)·ΔpH (mV)",
              "value_mV": pmf_single, "status": "VERIFIED",
+             "verification_scope": verification_scope,
              "source": sources.get("Mitchell pmf (Nobel)"),
              "endpoint": f"{base}/pmf"},
             {"model": "Two-ion K+/H+ pmf correction",
@@ -115,10 +124,12 @@ def _qbio_status() -> Dict[str, Any]:
             {"model": "Lindblad / GKSL coherence decay",
              "equation": "dρ/dt = −(i/ħ)[H,ρ] + Σ γ_k (L_k ρ L_k† − ½{L_k†L_k, ρ})",
              "fitted_tau_c": coh.get("tau_c"), "status": "VERIFIED",
+             "verification_scope": verification_scope,
              "endpoint": f"{base}/coherence"},
             {"model": "Radical-pair magnetoreception (singlet yield)",
              "angular_contrast": comp.get("angular_contrast"),
              "compass_works": comp.get("works"), "status": "VERIFIED",
+             "verification_scope": verification_scope,
              "fidelity": "reduced single-nucleus closed-form (full model contrast ~0.378)",
              "endpoint": f"{base}/compass"},
             {"model": "SZL Λ-v5 closure gate",
@@ -150,8 +161,12 @@ def _qbio_status() -> Dict[str, Any]:
         "live_paths": live_paths,
         "summary_endpoint": summary_src,
         "models": models,
+        "verification_scope": verification_scope if models else "UNAVAILABLE",
+        "verification_boundary": verification_boundary if models else (
+            "Backing model unavailable; no verification claim emitted."
+        ),
         "status_legend": {
-            "VERIFIED": "executed model, reproduces on every call",
+            "VERIFIED": "executed deterministic model, reproduces on every call; not experimental validation",
             "PROPOSED": "SZL-proposed construct (two-ion pmf, Λ-v5 gate)",
             "NARRATIVE": "Jack Kruse framing only — NOT load-bearing math",
         },

szl_quantum_bio.py

@@ -55,6 +55,17 @@ SOURCES = {
     "AdS/CFT (Maldacena)":       "https://en.wikipedia.org/wiki/Holographic_principle",
 }
 
+# ``VERIFIED`` is retained for backward compatibility with existing clients, but its
+# scope is deliberately narrow: the implementation executes deterministically and
+# reproduces the reported model output.  It is not an experimental validation of a
+# biological mechanism, a physical device measurement, or evidence of quantum
+# advantage.
+VERIFICATION_SCOPE = "COMPUTATIONAL_REPRODUCIBILITY_ONLY"
+VERIFICATION_BOUNDARY = (
+    "Executed deterministic model output; not experimental validation, not an "
+    "instrument measurement, and not evidence of quantum advantage."
+)
+
 
 def _now():
     return datetime.now(timezone.utc).isoformat()
@@ -160,6 +171,8 @@ def _h_pmf(req: Request):
         "model": "Mitchell proton-motive force",
         "equation": "Δp = ΔΨ − (2.3 RT / F)·ΔpH (mV)",
         "status": "VERIFIED",
+        "verification_scope": VERIFICATION_SCOPE,
+        "verification_boundary": VERIFICATION_BOUNDARY,
         "two_ion_status": "PROPOSED",
         "inputs": {"d_psi_mV": d_psi, "d_pH": d_pH, "d_pK": d_pK, "K_weight": w},
         "pmf_single_ion_mV": single,
@@ -174,7 +187,9 @@ def _h_coherence(req: Request):
     return JSONResponse({
         "model": "Lindblad / GKSL open-quantum-system coherence",
         "equation": "dρ/dt = −(i/ħ)[H,ρ] + Σ γ_k (L_k ρ L_k† − ½{L_k†L_k, ρ})",
-        "status": "VERIFIED", "fitted_tau_c": s["tau_c"], "series": s,
+        "status": "VERIFIED", "verification_scope": VERIFICATION_SCOPE,
+        "verification_boundary": VERIFICATION_BOUNDARY,
+        "fitted_tau_c": s["tau_c"], "series": s,
         "source": SOURCES["Lindblad path integral"], "computed_at": _now(),
     })
 
@@ -188,6 +203,8 @@ def _h_compass(req: Request):
         angles = (0.0, 30.0, 60.0, 90.0)
     out = compass(B, angles)
     out.update({"model": "Radical-pair magnetoreception (singlet yield)", "status": "VERIFIED",
+                "verification_scope": VERIFICATION_SCOPE,
+                "verification_boundary": VERIFICATION_BOUNDARY,
                 "honest_note": "Reduced single-nucleus closed-form here gives a real angle-dependent yield (contrast ~0.025); the FULL multi-spin density-matrix model in the payload yields contrast ~0.378. A toy isotropic cos(ωt) model fails (contrast~0). Anisotropy is genuine, not fabricated.",
                 "fidelity": "reduced (single-nucleus closed-form)",
                 "source": SOURCES["Hore PNAS 2009"], "computed_at": _now()})
@@ -207,14 +224,19 @@ def _h_lambda(req: Request):
 def _h_summary(req: Request):
     return JSONResponse({
         "title": "SZL Quantum-Bio Master Payload (v5) — verified results",
-        "status_legend": {"VERIFIED": "executed model, reproduces on call",
+        "verification_scope": VERIFICATION_SCOPE,
+        "verification_boundary": VERIFICATION_BOUNDARY,
+        "status_legend": {"VERIFIED": "executed deterministic model, reproduces on call; not experimental validation",
                           "PROPOSED": "SZL-proposed construct",
                           "NARRATIVE": "Jack Kruse framing only — NOT load-bearing math"},
         "results": [
-            {"quantity": "Lindblad τ_c", "value": 6.05, "status": "VERIFIED"},
-            {"quantity": "pmf single-ion (mV)", "value": round(pmf(150.0, 0.5), 1), "status": "VERIFIED"},
+            {"quantity": "Lindblad τ_c", "value": 6.05, "status": "VERIFIED",
+             "verification_scope": VERIFICATION_SCOPE},
+            {"quantity": "pmf single-ion (mV)", "value": round(pmf(150.0, 0.5), 1), "status": "VERIFIED",
+             "verification_scope": VERIFICATION_SCOPE},
             {"quantity": "pmf two-ion K+/H+ (mV)", "value": round(pmf_two_ion(150.0, 0.5, 0.30), 1), "status": "PROPOSED"},
-            {"quantity": "compass angular contrast", "value": compass(50.0)["angular_contrast"], "status": "VERIFIED"},
+            {"quantity": "compass angular contrast", "value": compass(50.0)["angular_contrast"], "status": "VERIFIED",
+             "verification_scope": VERIFICATION_SCOPE},
             {"quantity": "Λ-v5 gate", "value": "coherent AND charged -> execute; else recharge", "status": "PROPOSED"},
             {"quantity": "Lean closure theorems", "value": 3, "status": "VERIFIED (proofs, no sorry)"},
         ],

szl_quantum_utility.py

@@ -0,0 +1,724 @@
+# SPDX-License-Identifier: Apache-2.0
+"""Bounded, proof-carrying quantum workflow utility proposals.
+
+This clean-room module is deliberately smaller than a quantum SDK.  It accepts
+typed QUBO and Hamiltonian descriptions, produces deterministic *proposals*,
+and makes unsupported advantage language fail closed.  It performs no network,
+filesystem, subprocess, provider, simulator, QPU, credential, or deployment
+operation.  ``effectors`` and ``provider_calls`` are always zero.
+
+The finance ``szl_gpu_quant`` engine is a separate system and is not imported.
+The repository's ``szl_vqc`` state-vector demonstration remains a small
+``MODELED`` / ``SIMULATED`` capability; it is described by the manifest but is
+not treated as hardware evidence or an advantage baseline.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import json
+import math
+import re
+import time
+from dataclasses import asdict, dataclass
+from enum import Enum
+from typing import Any, Mapping, Sequence
+
+
+SCHEMA_VERSION = "szl.quantum-utility.v1"
+RECEIPT_SCHEMA_VERSION = "szl.quantum-utility.receipt.v1"
+MODE = "PROPOSAL_ONLY"
+EFFECTORS = 0
+PROVIDER_CALLS = 0
+MAX_QUBO_VARIABLES = 16
+MAX_EXACT_STATES = 1 << MAX_QUBO_VARIABLES
+MAX_EXACT_RUNTIME_MS = 2_000
+MAX_HAMILTONIAN_QUBITS = 128
+MAX_HAMILTONIAN_TERMS = 2_048
+MIN_SHOTS = 1
+MAX_SHOTS = 1_000_000
+MIN_REPEATED_MEASUREMENTS = 3
+_SHA256_RE = re.compile(r"^[0-9a-f]{64}$")
+
+
+class ContractError(ValueError):
+    """Raised when an input cannot be represented by the bounded contract."""
+
+
+class EvidenceLabel(str, Enum):
+    DECLARED = "DECLARED"
+    MEASURED = "MEASURED"
+    UNKNOWN = "UNKNOWN"
+
+
+@dataclass(frozen=True)
+class QUBOTerm:
+    left: str
+    right: str
+    coefficient: float
+
+
+@dataclass(frozen=True)
+class QUBOProblem:
+    problem_id: str
+    variables: tuple[str, ...]
+    offset: float
+    linear: tuple[tuple[str, float], ...]
+    quadratic: tuple[QUBOTerm, ...]
+
+
+@dataclass(frozen=True)
+class HamiltonianTerm:
+    term_id: str
+    pauli: str
+    coefficient: float
+    declared_priority: float
+
+
+@dataclass(frozen=True)
+class HamiltonianProblem:
+    problem_id: str
+    qubit_count: int
+    terms: tuple[HamiltonianTerm, ...]
+
+
+UTILITY_FIELDS = (
+    "bounded_value_usd",
+    "compute_cost_usd",
+    "queue_cost_usd",
+    "energy_cost_usd",
+    "verification_cost_usd",
+    "operational_risk_cost_usd",
+    "estimated_accuracy",
+)
+
+
+def canonical_json(value: Any) -> bytes:
+    return json.dumps(
+        value,
+        sort_keys=True,
+        separators=(",", ":"),
+        ensure_ascii=False,
+        allow_nan=False,
+    ).encode("utf-8")
+
+
+def sha256_json(value: Any) -> str:
+    return hashlib.sha256(canonical_json(value)).hexdigest()
+
+
+def _mapping(value: Any, name: str) -> Mapping[str, Any]:
+    if not isinstance(value, Mapping):
+        raise ContractError(f"{name} must be an object")
+    return value
+
+
+def _text(value: Any, name: str) -> str:
+    if not isinstance(value, str) or not value.strip():
+        raise ContractError(f"{name} must be a non-empty string")
+    return value.strip()
+
+
+def _number(value: Any, name: str) -> float:
+    if isinstance(value, bool) or not isinstance(value, (int, float)):
+        raise ContractError(f"{name} must be a finite number")
+    out = float(value)
+    if not math.isfinite(out):
+        raise ContractError(f"{name} must be a finite number")
+    return out
+
+
+def _integer(value: Any, name: str, minimum: int, maximum: int) -> int:
+    if isinstance(value, bool) or not isinstance(value, int):
+        raise ContractError(f"{name} must be an integer")
+    if not minimum <= value <= maximum:
+        raise ContractError(f"{name} must be between {minimum} and {maximum}")
+    return value
+
+
+def _digest(value: Any, name: str) -> str:
+    text = _text(value, name).lower()
+    if not _SHA256_RE.fullmatch(text):
+        raise ContractError(f"{name} must be a lowercase SHA-256 digest")
+    return text
+
+
+def _strict_keys(value: Mapping[str, Any], allowed: set[str], name: str) -> None:
+    extras = sorted(set(value) - allowed)
+    if extras:
+        raise ContractError(f"{name} has unsupported fields: {', '.join(extras)}")
+
+
+def parse_qubo(payload: Mapping[str, Any]) -> QUBOProblem:
+    obj = _mapping(payload, "QUBO")
+    _strict_keys(obj, {"kind", "problem_id", "variables", "offset", "linear", "quadratic"}, "QUBO")
+    if obj.get("kind") != "QUBO":
+        raise ContractError("kind must be QUBO")
+    raw_variables = obj.get("variables")
+    if not isinstance(raw_variables, Sequence) or isinstance(raw_variables, (str, bytes)):
+        raise ContractError("variables must be an array")
+    variables = tuple(_text(v, "variable") for v in raw_variables)
+    if not variables or len(variables) > MAX_QUBO_VARIABLES:
+        raise ContractError(f"QUBO must contain 1..{MAX_QUBO_VARIABLES} variables")
+    if len(set(variables)) != len(variables):
+        raise ContractError("variables must be unique")
+    allowed_variables = set(variables)
+
+    raw_linear = obj.get("linear", {})
+    if not isinstance(raw_linear, Mapping):
+        raise ContractError("linear must be an object")
+    unknown_linear = sorted(set(raw_linear) - allowed_variables)
+    if unknown_linear:
+        raise ContractError(f"linear references unknown variables: {', '.join(unknown_linear)}")
+    linear = tuple(sorted((str(k), _number(v, f"linear.{k}")) for k, v in raw_linear.items()))
+
+    raw_quadratic = obj.get("quadratic", [])
+    if not isinstance(raw_quadratic, Sequence) or isinstance(raw_quadratic, (str, bytes)):
+        raise ContractError("quadratic must be an array")
+    terms: list[QUBOTerm] = []
+    seen: set[tuple[str, str]] = set()
+    for index, raw in enumerate(raw_quadratic):
+        term = _mapping(raw, f"quadratic[{index}]")
+        _strict_keys(term, {"left", "right", "coefficient"}, f"quadratic[{index}]")
+        left = _text(term.get("left"), f"quadratic[{index}].left")
+        right = _text(term.get("right"), f"quadratic[{index}].right")
+        if left not in allowed_variables or right not in allowed_variables:
+            raise ContractError(f"quadratic[{index}] references an unknown variable")
+        if left == right:
+            raise ContractError("diagonal QUBO terms belong in linear")
+        pair = tuple(sorted((left, right)))
+        if pair in seen:
+            raise ContractError(f"duplicate quadratic pair: {pair[0]},{pair[1]}")
+        seen.add(pair)
+        terms.append(QUBOTerm(pair[0], pair[1], _number(term.get("coefficient"), "coefficient")))
+    terms.sort(key=lambda row: (row.left, row.right))
+    return QUBOProblem(
+        problem_id=_text(obj.get("problem_id"), "problem_id"),
+        variables=variables,
+        offset=_number(obj.get("offset", 0.0), "offset"),
+        linear=linear,
+        quadratic=tuple(terms),
+    )
+
+
+def solve_qubo_exact(payload: Mapping[str, Any]) -> dict[str, Any]:
+    """Enumerate a small binary QUBO exactly, with hard state/time ceilings."""
+
+    problem = parse_qubo(payload)
+    max_runtime_ms = MAX_EXACT_RUNTIME_MS
+    deadline = time.perf_counter() + max_runtime_ms / 1_000.0
+    linear = dict(problem.linear)
+    best_energy: float | None = None
+    best_bits: tuple[int, ...] | None = None
+    state_count = 1 << len(problem.variables)
+    if state_count > MAX_EXACT_STATES:
+        raise ContractError("exact QUBO state ceiling exceeded")
+
+    for state in range(state_count):
+        if state % 1_024 == 0 and time.perf_counter() > deadline:
+            raise ContractError("exact QUBO time limit exceeded; no partial baseline emitted")
+        bits = tuple((state >> index) & 1 for index in range(len(problem.variables)))
+        assignment = dict(zip(problem.variables, bits))
+        energy = problem.offset
+        energy += sum(linear.get(name, 0.0) * assignment[name] for name in problem.variables)
+        energy += sum(term.coefficient * assignment[term.left] * assignment[term.right] for term in problem.quadratic)
+        if best_energy is None or energy < best_energy or (energy == best_energy and bits < best_bits):
+            best_energy = energy
+            best_bits = bits
+
+    assert best_energy is not None and best_bits is not None
+    return {
+        "problem_id": problem.problem_id,
+        "problem_digest": sha256_json(asdict(problem)),
+        "solver": "EXACT_BINARY_ENUMERATION",
+        "evidence_label": EvidenceLabel.MEASURED.value,
+        "measurement_scope": "deterministic classical computation",
+        "complete": True,
+        "variable_count": len(problem.variables),
+        "states_evaluated": state_count,
+        "objective": best_energy,
+        "assignment": dict(zip(problem.variables, best_bits)),
+        "max_runtime_ms": max_runtime_ms,
+        "quantum_hardware_used": False,
+        "quantum_advantage_claimed": False,
+        "mode": MODE,
+        "effectors": EFFECTORS,
+    }
+
+
+def exact_baseline(request: Mapping[str, Any]) -> dict[str, Any]:
+    obj = _mapping(request, "exact baseline request")
+    _strict_keys(obj, {"problem", "max_runtime_ms"}, "exact baseline request")
+    problem_payload = dict(_mapping(obj.get("problem"), "problem"))
+    limit = _integer(obj.get("max_runtime_ms", MAX_EXACT_RUNTIME_MS), "max_runtime_ms", 1, MAX_EXACT_RUNTIME_MS)
+    problem = parse_qubo(problem_payload)
+    # Avoid widening the typed QUBO schema merely to carry an execution bound.
+    deadline = time.perf_counter() + limit / 1_000.0
+    linear = dict(problem.linear)
+    best: tuple[float, tuple[int, ...]] | None = None
+    state_count = 1 << len(problem.variables)
+    for state in range(state_count):
+        if state % 1_024 == 0 and time.perf_counter() > deadline:
+            raise ContractError("exact QUBO time limit exceeded; no partial baseline emitted")
+        bits = tuple((state >> index) & 1 for index in range(len(problem.variables)))
+        assignment = dict(zip(problem.variables, bits))
+        energy = problem.offset
+        energy += sum(linear.get(name, 0.0) * assignment[name] for name in problem.variables)
+        energy += sum(t.coefficient * assignment[t.left] * assignment[t.right] for t in problem.quadratic)
+        candidate = (energy, bits)
+        if best is None or candidate < best:
+            best = candidate
+    assert best is not None
+    return {
+        "problem_id": problem.problem_id,
+        "problem_digest": sha256_json(asdict(problem)),
+        "solver": "EXACT_BINARY_ENUMERATION",
+        "evidence_label": EvidenceLabel.MEASURED.value,
+        "measurement_scope": "deterministic classical computation",
+        "complete": True,
+        "variable_count": len(problem.variables),
+        "states_evaluated": state_count,
+        "objective": best[0],
+        "assignment": dict(zip(problem.variables, best[1])),
+        "max_runtime_ms": limit,
+        "quantum_hardware_used": False,
+        "quantum_advantage_claimed": False,
+        "mode": MODE,
+        "effectors": EFFECTORS,
+    }
+
+
+def parse_hamiltonian(payload: Mapping[str, Any]) -> HamiltonianProblem:
+    obj = _mapping(payload, "Hamiltonian")
+    _strict_keys(obj, {"kind", "problem_id", "qubit_count", "terms"}, "Hamiltonian")
+    if obj.get("kind") != "HAMILTONIAN":
+        raise ContractError("kind must be HAMILTONIAN")
+    qubit_count = _integer(obj.get("qubit_count"), "qubit_count", 1, MAX_HAMILTONIAN_QUBITS)
+    raw_terms = obj.get("terms")
+    if not isinstance(raw_terms, Sequence) or isinstance(raw_terms, (str, bytes)):
+        raise ContractError("terms must be an array")
+    if not 1 <= len(raw_terms) <= MAX_HAMILTONIAN_TERMS:
+        raise ContractError(f"terms must contain 1..{MAX_HAMILTONIAN_TERMS} rows")
+    terms: list[HamiltonianTerm] = []
+    seen: set[str] = set()
+    for index, raw in enumerate(raw_terms):
+        row = _mapping(raw, f"terms[{index}]")
+        _strict_keys(row, {"term_id", "pauli", "coefficient", "declared_priority"}, f"terms[{index}]")
+        term_id = _text(row.get("term_id"), "term_id")
+        if term_id in seen:
+            raise ContractError(f"duplicate term_id: {term_id}")
+        seen.add(term_id)
+        pauli = _text(row.get("pauli"), "pauli").upper()
+        if len(pauli) != qubit_count or any(symbol not in "IXYZ" for symbol in pauli):
+            raise ContractError("pauli must contain exactly qubit_count symbols from I,X,Y,Z")
+        priority = _number(row.get("declared_priority", 1.0), "declared_priority")
+        if priority < 0:
+            raise ContractError("declared_priority must be non-negative")
+        terms.append(HamiltonianTerm(term_id, pauli, _number(row.get("coefficient"), "coefficient"), priority))
+    terms.sort(key=lambda row: row.term_id)
+    return HamiltonianProblem(_text(obj.get("problem_id"), "problem_id"), qubit_count, tuple(terms))
+
+
+def allocate_hamiltonian_shots(request: Mapping[str, Any]) -> dict[str, Any]:
+    obj = _mapping(request, "Hamiltonian shot request")
+    _strict_keys(obj, {"hamiltonian", "shot_budget"}, "Hamiltonian shot request")
+    problem = parse_hamiltonian(_mapping(obj.get("hamiltonian"), "hamiltonian"))
+    budget = _integer(obj.get("shot_budget"), "shot_budget", MIN_SHOTS, MAX_SHOTS)
+    if budget < len(problem.terms):
+        raise ContractError("shot_budget must allocate at least one shot per term")
+
+    weights = []
+    for term in problem.terms:
+        locality = sum(symbol != "I" for symbol in term.pauli)
+        weights.append(abs(term.coefficient) * max(1, locality) * term.declared_priority)
+    total_weight = sum(weights)
+    if total_weight <= 0:
+        weights = [1.0] * len(problem.terms)
+        total_weight = float(len(weights))
+
+    remaining = budget - len(problem.terms)
+    exact_extra = [remaining * weight / total_weight for weight in weights]
+    floors = [int(math.floor(value)) for value in exact_extra]
+    leftover = remaining - sum(floors)
+    order = sorted(range(len(problem.terms)), key=lambda i: (-(exact_extra[i] - floors[i]), problem.terms[i].term_id))
+    extras = list(floors)
+    for index in order[:leftover]:
+        extras[index] += 1
+
+    allocations = []
+    for index, term in enumerate(problem.terms):
+        allocations.append({
+            "term_id": term.term_id,
+            "pauli": term.pauli,
+            "coefficient": term.coefficient,
+            "declared_priority": term.declared_priority,
+            "importance": weights[index],
+            "shots": 1 + extras[index],
+        })
+    return {
+        "problem_id": problem.problem_id,
+        "problem_digest": sha256_json(asdict(problem)),
+        "shot_budget": budget,
+        "shots_allocated": sum(row["shots"] for row in allocations),
+        "allocation": allocations,
+        "method": "DECLARED_ABS_COEFFICIENT_X_LOCALITY_X_PRIORITY_LARGEST_REMAINDER",
+        "method_evidence_label": EvidenceLabel.DECLARED.value,
+        "scientific_optimality_claimed": False,
+        "execution_performed": False,
+        "provider_calls": PROVIDER_CALLS,
+        "mode": MODE,
+        "effectors": EFFECTORS,
+    }
+
+
+def _evidence_datum(value: Any, name: str, expected_unit: str) -> dict[str, Any]:
+    obj = _mapping(value, name)
+    _strict_keys(obj, {"value", "label", "unit", "source_ref"}, name)
+    try:
+        label = EvidenceLabel(_text(obj.get("label"), f"{name}.label"))
+    except ValueError as exc:
+        raise ContractError(f"{name}.label must be DECLARED, MEASURED, or UNKNOWN") from exc
+    unit = _text(obj.get("unit"), f"{name}.unit")
+    if unit != expected_unit:
+        raise ContractError(f"{name}.unit must be {expected_unit}")
+    source_ref = _text(obj.get("source_ref"), f"{name}.source_ref")
+    raw = obj.get("value")
+    if label is EvidenceLabel.UNKNOWN:
+        if raw is not None:
+            raise ContractError(f"{name}.value must be null when label is UNKNOWN")
+        numeric = None
+    else:
+        numeric = _number(raw, f"{name}.value")
+        if numeric < 0:
+            raise ContractError(f"{name}.value must be non-negative")
+    return {"value": numeric, "label": label.value, "unit": unit, "source_ref": source_ref}
+
+
+def score_counterfactuals(request: Mapping[str, Any]) -> dict[str, Any]:
+    obj = _mapping(request, "counterfactual request")
+    _strict_keys(obj, {"workload_digest", "candidates"}, "counterfactual request")
+    workload_digest = _digest(obj.get("workload_digest"), "workload_digest")
+    raw_candidates = obj.get("candidates")
+    if not isinstance(raw_candidates, Sequence) or isinstance(raw_candidates, (str, bytes)):
+        raise ContractError("candidates must be an array")
+    if not 1 <= len(raw_candidates) <= 64:
+        raise ContractError("candidates must contain 1..64 rows")
+    seen: set[str] = set()
+    scored: list[dict[str, Any]] = []
+    expected_units = {name: ("ratio" if name == "estimated_accuracy" else "USD") for name in UTILITY_FIELDS}
+    for index, raw in enumerate(raw_candidates):
+        candidate = _mapping(raw, f"candidates[{index}]")
+        _strict_keys(candidate, {"candidate_id", "backend_id", "compile_plan_id", "inputs"}, f"candidates[{index}]")
+        candidate_id = _text(candidate.get("candidate_id"), "candidate_id")
+        if candidate_id in seen:
+            raise ContractError(f"duplicate candidate_id: {candidate_id}")
+        seen.add(candidate_id)
+        inputs = _mapping(candidate.get("inputs"), "inputs")
+        if set(inputs) != set(UTILITY_FIELDS):
+            raise ContractError("inputs must contain every utility field exactly once")
+        evidence = {name: _evidence_datum(inputs[name], name, expected_units[name]) for name in UTILITY_FIELDS}
+        accuracy = evidence["estimated_accuracy"]["value"]
+        if accuracy is not None and accuracy > 1:
+            raise ContractError("estimated_accuracy.value must be between 0 and 1")
+        labels = {row["label"] for row in evidence.values()}
+        unknown = sorted(name for name, row in evidence.items() if row["label"] == EvidenceLabel.UNKNOWN.value)
+        if unknown:
+            margin = None
+            score_label = EvidenceLabel.UNKNOWN.value
+            disposition = "UNKNOWN_INPUTS"
+        else:
+            margin = evidence["bounded_value_usd"]["value"] - sum(
+                evidence[name]["value"] for name in UTILITY_FIELDS
+                if name.endswith("_cost_usd") or name == "operational_risk_cost_usd"
+            )
+            score_label = EvidenceLabel.MEASURED.value if labels == {EvidenceLabel.MEASURED.value} else EvidenceLabel.DECLARED.value
+            disposition = "POSITIVE_MARGIN" if margin > 0 else "NON_POSITIVE_MARGIN"
+        scored.append({
+            "candidate_id": candidate_id,
+            "backend_id": _text(candidate.get("backend_id"), "backend_id"),
+            "compile_plan_id": _text(candidate.get("compile_plan_id"), "compile_plan_id"),
+            "inputs": evidence,
+            "unknown_inputs": unknown,
+            "utility_margin_usd": margin,
+            "score_evidence_label": score_label,
+            "disposition": disposition,
+        })
+
+    comparable = [row for row in scored if row["utility_margin_usd"] is not None]
+    front: list[str] = []
+    for row in comparable:
+        dominated = False
+        for other in comparable:
+            if other is row:
+                continue
+            row_accuracy = row["inputs"]["estimated_accuracy"]["value"]
+            other_accuracy = other["inputs"]["estimated_accuracy"]["value"]
+            if (
+                other["utility_margin_usd"] >= row["utility_margin_usd"]
+                and other_accuracy >= row_accuracy
+                and (other["utility_margin_usd"] > row["utility_margin_usd"] or other_accuracy > row_accuracy)
+            ):
+                dominated = True
+                break
+        if not dominated:
+            front.append(row["candidate_id"])
+    return {
+        "workload_digest": workload_digest,
+        "candidates": sorted(scored, key=lambda row: row["candidate_id"]),
+        "pareto_front_candidate_ids": sorted(front),
+        "score_model": "DECLARED_VALUE_MINUS_TOTAL_DECLARED_OR_MEASURED_COST",
+        "universal_provider_ranking_claimed": False,
+        "execution_performed": False,
+        "provider_calls": PROVIDER_CALLS,
+        "mode": MODE,
+        "effectors": EFFECTORS,
+    }
+
+
+def _receipt_body(operation: str, request: Mapping[str, Any], output: Mapping[str, Any]) -> dict[str, Any]:
+    return {
+        "schema_version": RECEIPT_SCHEMA_VERSION,
+        "operation": operation,
+        "mode": MODE,
+        "effectors": EFFECTORS,
+        "provider_calls": PROVIDER_CALLS,
+        "input": request,
+        "input_sha256": sha256_json(request),
+        "output": output,
+        "output_sha256": sha256_json(output),
+        "signature_state": "UNSIGNED_DETERMINISTIC_HASH_ONLY",
+    }
+
+
+def create_receipt(operation: str, request: Mapping[str, Any], output: Mapping[str, Any]) -> dict[str, Any]:
+    body = _receipt_body(operation, request, output)
+    return {**body, "receipt_sha256": sha256_json(body)}
+
+
+def evaluate_advantage_claim(request: Mapping[str, Any]) -> dict[str, Any]:
+    obj = _mapping(request, "advantage claim")
+    allowed = {
+        "claim_type", "claim_id", "claim_owner", "classical_baseline_receipt",
+        "quantum_observations", "uncertainty", "provenance", "utility_margin",
+    }
+    _strict_keys(obj, allowed, "advantage claim")
+    reasons: list[str] = []
+    if obj.get("claim_type") != "QUANTUM_ADVANTAGE":
+        reasons.append("QUG-001 claim_type must be QUANTUM_ADVANTAGE")
+    try:
+        _text(obj.get("claim_id"), "claim_id")
+        _text(obj.get("claim_owner"), "claim_owner")
+    except ContractError:
+        reasons.append("QUG-002 claim_id and accountable claim_owner are required")
+
+    baseline = obj.get("classical_baseline_receipt")
+    baseline_input_digest: str | None = None
+    try:
+        baseline_obj = _mapping(baseline, "classical_baseline_receipt")
+        if baseline_obj.get("operation") != "QUBO_EXACT_BASELINE":
+            raise ContractError("baseline receipt must be QUBO_EXACT_BASELINE")
+        baseline_check = replay_receipt(baseline_obj)
+        baseline_output = _mapping(baseline_obj.get("output"), "baseline output")
+        if (
+            not baseline_check["valid"]
+            or not baseline_output.get("complete")
+            or baseline_output.get("evidence_label") != EvidenceLabel.MEASURED.value
+        ):
+            reasons.append("QUG-003 exact replayable classical baseline is required")
+        else:
+            baseline_input_digest = str(baseline_obj.get("input_sha256"))
+    except (ContractError, TypeError, KeyError):
+        reasons.append("QUG-003 exact replayable classical baseline is required")
+
+    observations = obj.get("quantum_observations")
+    observation_rows = observations if isinstance(observations, Sequence) and not isinstance(observations, (str, bytes)) else []
+    if len(observation_rows) < MIN_REPEATED_MEASUREMENTS:
+        reasons.append(f"QUG-004 at least {MIN_REPEATED_MEASUREMENTS} repeated measurements are required")
+    else:
+        run_ids: set[str] = set()
+        for index, raw in enumerate(observation_rows):
+            try:
+                row = _mapping(raw, f"quantum_observations[{index}]")
+                _strict_keys(row, {"run_id", "task_digest", "backend_id", "shots", "raw_result_sha256", "label"}, f"quantum_observations[{index}]")
+                run_id = _text(row.get("run_id"), "run_id")
+                if run_id in run_ids:
+                    raise ContractError("run_id must be unique")
+                run_ids.add(run_id)
+                if row.get("label") != EvidenceLabel.MEASURED.value:
+                    raise ContractError("observation label must be MEASURED")
+                if baseline_input_digest is None or _digest(row.get("task_digest"), "task_digest") != baseline_input_digest:
+                    raise ContractError("task digest must match the classical baseline")
+                _text(row.get("backend_id"), "backend_id")
+                _integer(row.get("shots"), "shots", 1, MAX_SHOTS)
+                _digest(row.get("raw_result_sha256"), "raw_result_sha256")
+            except ContractError:
+                reasons.append(f"QUG-005 observation {index} is incomplete, incomparable, or not MEASURED")
+                break
+
+    margin_value: float | None = None
+    try:
+        margin = _evidence_datum(obj.get("utility_margin"), "utility_margin", "USD")
+        margin_value = margin["value"]
+        if margin["label"] != EvidenceLabel.MEASURED.value or margin_value is None or margin_value <= 0:
+            reasons.append("QUG-006 a positive MEASURED utility margin is required")
+    except ContractError:
+        reasons.append("QUG-006 a positive MEASURED utility margin is required")
+
+    try:
+        uncertainty = _mapping(obj.get("uncertainty"), "uncertainty")
+        _strict_keys(uncertainty, {"label", "method", "source_ref", "lower_margin_usd", "upper_margin_usd", "confidence"}, "uncertainty")
+        lower = _number(uncertainty.get("lower_margin_usd"), "lower_margin_usd")
+        upper = _number(uncertainty.get("upper_margin_usd"), "upper_margin_usd")
+        confidence = _number(uncertainty.get("confidence"), "confidence")
+        if (
+            uncertainty.get("label") != EvidenceLabel.MEASURED.value
+            or lower <= 0
+            or upper < lower
+            or not 0.5 <= confidence <= 1.0
+            or margin_value is None
+            or not lower <= margin_value <= upper
+        ):
+            raise ContractError("uncertainty interval does not support a positive margin")
+        _text(uncertainty.get("method"), "uncertainty.method")
+        _text(uncertainty.get("source_ref"), "uncertainty.source_ref")
+    except ContractError:
+        reasons.append("QUG-007 measured uncertainty with a positive lower margin bound is required")
+
+    provenance = obj.get("provenance")
+    provenance_rows = provenance if isinstance(provenance, Sequence) and not isinstance(provenance, (str, bytes)) else []
+    if not provenance_rows:
+        reasons.append("QUG-008 provenance is required")
+    else:
+        try:
+            for index, raw in enumerate(provenance_rows):
+                row = _mapping(raw, f"provenance[{index}]")
+                _strict_keys(row, {"source_uri", "content_sha256", "observed_at"}, f"provenance[{index}]")
+                _text(row.get("source_uri"), "source_uri")
+                _digest(row.get("content_sha256"), "content_sha256")
+                _text(row.get("observed_at"), "observed_at")
+        except ContractError:
+            reasons.append("QUG-008 complete provenance is required")
+
+    unique_reasons = sorted(set(reasons))
+    if any(reason.startswith("QUG-006") for reason in unique_reasons) and margin_value is not None and margin_value <= 0:
+        evidence_state = "REFUTED"
+    elif unique_reasons:
+        evidence_state = "UNKNOWN"
+    else:
+        evidence_state = "SUPPORTED"
+    passed = not unique_reasons
+    return {
+        "claim_id": obj.get("claim_id"),
+        "claim_type": obj.get("claim_type"),
+        "gate_passed": passed,
+        "evidence_state": evidence_state,
+        "reasons": unique_reasons,
+        "eligible_for_human_review": passed,
+        "quantum_advantage_verified": False,
+        "claim_authorized": False,
+        "publication_authorized": False,
+        "execution_authorized": False,
+        "note": "Passing this gate means evidence completeness for human review, not verified quantum advantage.",
+        "mode": MODE,
+        "effectors": EFFECTORS,
+        "provider_calls": PROVIDER_CALLS,
+    }
+
+
+OPERATIONS = {
+    "QUBO_EXACT_BASELINE": exact_baseline,
+    "HAMILTONIAN_SHOT_PLAN": allocate_hamiltonian_shots,
+    "COUNTERFACTUAL_SCORE": score_counterfactuals,
+    "QUANTUM_ADVANTAGE_GATE": evaluate_advantage_claim,
+}
+
+
+def run_with_receipt(operation: str, request: Mapping[str, Any]) -> dict[str, Any]:
+    if operation not in OPERATIONS:
+        raise ContractError(f"unsupported operation: {operation}")
+    normalized_request = dict(_mapping(request, "request"))
+    output = OPERATIONS[operation](normalized_request)
+    return {"result": output, "receipt": create_receipt(operation, normalized_request, output)}
+
+
+def replay_receipt(receipt: Mapping[str, Any]) -> dict[str, Any]:
+    obj = _mapping(receipt, "receipt")
+    required = set(_receipt_body("x", {}, {})) | {"receipt_sha256"}
+    if set(obj) != required:
+        raise ContractError("receipt fields do not match the receipt schema")
+    if obj.get("schema_version") != RECEIPT_SCHEMA_VERSION:
+        raise ContractError("unsupported receipt schema_version")
+    if (
+        obj.get("mode") != MODE
+        or obj.get("effectors") != EFFECTORS
+        or obj.get("provider_calls") != PROVIDER_CALLS
+        or obj.get("signature_state") != "UNSIGNED_DETERMINISTIC_HASH_ONLY"
+    ):
+        raise ContractError("receipt violates the proposal-only boundary")
+    operation = _text(obj.get("operation"), "operation")
+    request = dict(_mapping(obj.get("input"), "receipt.input"))
+    output = dict(_mapping(obj.get("output"), "receipt.output"))
+    stored = _digest(obj.get("receipt_sha256"), "receipt_sha256")
+    body = {key: obj[key] for key in obj if key != "receipt_sha256"}
+    hash_valid = sha256_json(body) == stored
+    input_valid = sha256_json(request) == obj.get("input_sha256")
+    output_valid = sha256_json(output) == obj.get("output_sha256")
+    if operation not in OPERATIONS:
+        replay_output: Mapping[str, Any] = {}
+        replay_equal = False
+    elif operation == "QUANTUM_ADVANTAGE_GATE":
+        # Advantage requests embed a baseline receipt. Replaying remains pure,
+        # bounded, and recursive only by one validated baseline level.
+        replay_output = OPERATIONS[operation](request)
+        replay_equal = replay_output == output
+    else:
+        replay_output = OPERATIONS[operation](request)
+        replay_equal = replay_output == output
+    valid = bool(hash_valid and input_valid and output_valid and replay_equal)
+    return {
+        "valid": valid,
+        "receipt_sha256": stored,
+        "hash_valid": hash_valid,
+        "input_digest_valid": input_valid,
+        "output_digest_valid": output_valid,
+        "replay_equal": replay_equal,
+        "mode": MODE,
+        "effectors": EFFECTORS,
+        "provider_calls": PROVIDER_CALLS,
+    }
+
+
+def info() -> dict[str, Any]:
+    return {
+        "service": "szl-quantum-utility-gate",
+        "schema_version": SCHEMA_VERSION,
+        "ready": True,
+        "label": "STRUCTURAL-ONLY",
+        "label_detail": "Classical exact baselines may be MEASURED within their stated computation scope; no QPU measurement is made here.",
+        "mode": MODE,
+        "effectors": EFFECTORS,
+        "provider_calls": PROVIDER_CALLS,
+        "qpu_calls": 0,
+        "finance_quant_engine_imported": False,
+        "capabilities": {
+            "qubo_exact_classical_baseline": {"label": "MEASURED", "max_variables": MAX_QUBO_VARIABLES},
+            "hamiltonian_shot_allocation": {"label": "DECLARED", "max_terms": MAX_HAMILTONIAN_TERMS},
+            "counterfactual_backend_compile_scoring": {"labels_required": [label.value for label in EvidenceLabel]},
+            "quantum_advantage_rupture_gate": {"auto_verifies_advantage": False},
+            "deterministic_receipt_replay": True,
+        },
+        "existing_simulator_boundary": {
+            "module": "szl_vqc.py",
+            "label": "MODELED",
+            "sim_kind": "SIMULATED",
+            "used_as_hardware_evidence": False,
+            "used_as_advantage_evidence": False,
+        },
+        "non_goals": [
+            "QPU or provider execution",
+            "universal provider rankings",
+            "quantum advantage verification",
+            "finance portfolio analysis",
+        ],
+        "operations": sorted(OPERATIONS),
+    }

szl_release_identity.py

@@ -0,0 +1,114 @@
+"""Canonical, machine-readable A11oy release identity.
+
+The software-version DOI is intentionally absent until an immutable GitHub
+release is archived and Zenodo returns a resolvable record. Existing research
+DOIs remain separately typed so a UI cannot present either as the new release.
+"""
+
+from __future__ import annotations
+
+import os
+import re
+import json
+from pathlib import Path
+from typing import Any
+
+
+SOFTWARE_NAME = "A11oy"
+SOFTWARE_VERSION = "1.1.0"
+CANONICAL_URL = "https://a-11-oy.com"
+LEGACY_ALIAS = "https://a11oy.net"
+REPOSITORY_URL = "https://github.com/szl-holdings/a11oy"
+CONCEPT_DOI = "10.5281/zenodo.19944926"
+FORMAL_ARTIFACT_DOI = "10.5281/zenodo.20434276"
+
+_ZENODO_DOI_RE = re.compile(r"^10\.5281/zenodo\.\d+$")
+_EXPECTED_RELEASE_TAG = f"v{SOFTWARE_VERSION}"
+_READBACK_PATH = Path(__file__).with_name("zenodo-readback.json")
+
+
+def _configured_version_doi() -> str | None:
+    value = os.getenv("A11OY_VERSION_DOI", "").strip()
+    if not value or not _ZENODO_DOI_RE.fullmatch(value):
+        return None
+    if value in {CONCEPT_DOI, FORMAL_ARTIFACT_DOI}:
+        return None
+    return value
+
+
+def _configured_release_tag() -> str | None:
+    value = os.getenv("A11OY_RELEASE_TAG", "").strip()
+    return value if value == _EXPECTED_RELEASE_TAG else None
+
+
+def _verified_readback() -> dict[str, Any] | None:
+    try:
+        payload = json.loads(_READBACK_PATH.read_text(encoding="utf-8"))
+    except (OSError, ValueError, TypeError):
+        return None
+    if not isinstance(payload, dict) or payload.get("status") != "VERIFIED":
+        return None
+    if payload.get("software_version") != SOFTWARE_VERSION:
+        return None
+    if payload.get("release_tag") != _EXPECTED_RELEASE_TAG:
+        return None
+    doi = str(payload.get("doi") or "")
+    if not _ZENODO_DOI_RE.fullmatch(doi) or doi in {CONCEPT_DOI, FORMAL_ARTIFACT_DOI}:
+        return None
+    if not str(payload.get("metadata_sha256") or ""):
+        return None
+    return payload
+
+
+def release_identity() -> dict[str, Any]:
+    """Return release identity without upgrading unverified state.
+
+    ``A11OY_VERSION_DOI`` and ``A11OY_RELEASE_TAG`` are accepted only when both
+    have valid syntax. Their presence means CONFIGURED, not independently
+    VERIFIED; deployment or archive verification must establish resolution.
+    """
+
+    readback = _verified_readback()
+    version_doi = str(readback["doi"]) if readback else _configured_version_doi()
+    release_tag = str(readback["release_tag"]) if readback else _configured_release_tag()
+    configured = bool(version_doi and release_tag)
+    verified = bool(readback)
+    release_url = f"{REPOSITORY_URL}/releases/tag/{release_tag}" if configured else f"{REPOSITORY_URL}/releases"
+
+    return {
+        "name": SOFTWARE_NAME,
+        "version": SOFTWARE_VERSION,
+        "expected_release_tag": _EXPECTED_RELEASE_TAG,
+        "release_state": "VERIFIED" if verified else ("CONFIGURED_UNVERIFIED" if configured else "CANDIDATE"),
+        "release_tag": release_tag,
+        "release_url": release_url,
+        "surfaces": {
+            "canonical": CANONICAL_URL,
+            "legacy_alias": LEGACY_ALIAS,
+            "legacy_alias_policy": "PERMANENT_REDIRECT_TO_CANONICAL",
+            "repository": REPOSITORY_URL,
+        },
+        "doi": {
+            "concept": {
+                "value": CONCEPT_DOI,
+                "url": f"https://doi.org/{CONCEPT_DOI}",
+                "role": "ASSOCIATED_RESEARCH_PROGRAM",
+            },
+            "formal_artifacts": {
+                "value": FORMAL_ARTIFACT_DOI,
+                "url": f"https://doi.org/{FORMAL_ARTIFACT_DOI}",
+                "role": "EXISTING_FORMAL_ARTIFACT_RECORD",
+            },
+            "software_version": {
+                "value": version_doi,
+                "url": f"https://doi.org/{version_doi}" if version_doi else None,
+                "status": "VERIFIED" if verified else ("CONFIGURED_UNVERIFIED" if configured else "PENDING_ZENODO_READBACK"),
+                "readback": readback,
+            },
+        },
+        "honesty": {
+            "configured_is_operational": False,
+            "conjecture_promoted": False,
+            "doi_invented": False,
+        },
+    }

szl_waqay.py

@@ -816,11 +816,11 @@ def register(app, ns: str = "a11oy") -> Dict[str, Any]:
     n_before = len(app.router.routes)
 
     @app.get(f"/api/{ns}/v1/waqay/doctrine", include_in_schema=False)
-    async def _doctrine() -> JSONResponse:
+    async def _doctrine():  # noqa: ANN202
         return JSONResponse({"doctrine": DOCTRINE, "trust_ceiling": TRUST_CEILING})
 
     @app.get(f"/api/{ns}/v1/waqay/demo", include_in_schema=False)
-    async def _demo(req: Request) -> JSONResponse:
+    async def _demo(req: Request):  # noqa: ANN202
         try:
             bw = int(req.query_params.get("bits", "2"))
         except Exception:
@@ -829,7 +829,7 @@ def register(app, ns: str = "a11oy") -> Dict[str, Any]:
         return JSONResponse(demo(query=q, bit_width=bw if bw in (2, 4) else 2))
 
     @app.post(f"/api/{ns}/v1/waqay/search", include_in_schema=False)
-    async def _search(req: Request) -> JSONResponse:
+    async def _search(req: Request):  # noqa: ANN202
         try:
             body = await req.json()
         except Exception:
@@ -839,7 +839,7 @@ def register(app, ns: str = "a11oy") -> Dict[str, Any]:
         return JSONResponse(demo(query=q, bit_width=bw if bw in (2, 4) else 2))
 
     @app.get(f"/api/{ns}/v1/waqay/receipts", include_in_schema=False)
-    async def _receipts() -> JSONResponse:
+    async def _receipts():  # noqa: ANN202
         tail = _RECEIPTS[-20:]
         return JSONResponse({"count": len(_RECEIPTS),
                              "receipts": [{"payload": r["payload"],
@@ -847,7 +847,7 @@ def register(app, ns: str = "a11oy") -> Dict[str, Any]:
                                           for r in tail]})
 
     @app.post(f"/api/{ns}/v1/waqay/verify", include_in_schema=False)
-    async def _verify(req: Request) -> JSONResponse:
+    async def _verify(req: Request):  # noqa: ANN202
         try:
             body = await req.json()
         except Exception:
@@ -856,7 +856,7 @@ def register(app, ns: str = "a11oy") -> Dict[str, Any]:
         return JSONResponse(verify_receipt(env))
 
     @app.get("/waqay", include_in_schema=False)
-    async def _page() -> HTMLResponse:
+    async def _page():  # noqa: ANN202
         return HTMLResponse(_PAGE_HTML.replace("{NS}", ns))
 
     # Move the WAQAY routes just appended (the tail beyond n_before) to the FRONT,

szl_yupaq_compute.py

@@ -0,0 +1,875 @@
+# SPDX-License-Identifier: Apache-2.0
+"""Yupaq governed computation plane.
+
+Yupaq ("the one who counts") binds the existing A11oy numerical, quant,
+formal, evidence, and trust organs behind one strict job contract.  It is an
+orchestrator, not a new calculator: every operation delegates to an existing
+versioned implementation and retains that implementation's honesty label.
+
+The public contract deliberately accepts no source code, expressions, paths,
+URLs, packages, shell arguments, provider credentials, or arbitrary function
+names.  A completed job produces a canonical result digest, an optional DSSE
+envelope, a Lake chain record, and OpenTelemetry-shaped timing spans.  Missing
+engines remain UNAVAILABLE and never receive synthetic proof or trust uplift.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import copy
+import hashlib
+import hmac
+import json
+import math
+import os
+import re
+import threading
+import time
+from collections import OrderedDict
+from contextlib import nullcontext
+from datetime import datetime, timezone
+from pathlib import Path
+from typing import Any, Mapping, Sequence
+
+try:
+    from fastapi import Request  # noqa: F401
+    from fastapi.responses import JSONResponse  # noqa: F401
+except Exception:  # pragma: no cover - register() is not called without FastAPI
+    Request = JSONResponse = Any  # type: ignore
+
+
+ROOT = Path(__file__).resolve().parent
+JOB_SCHEMA = "szl.compute-job/v1"
+RESULT_SCHEMA = "szl.compute-result/v1"
+RECEIPT_SCHEMA = "szl.compute-receipt/v1"
+PAYLOAD_TYPE = "application/vnd.szl.compute-receipt+json"
+MAX_BODY_BYTES = 128 * 1024
+MAX_OUTPUT_BYTES = 256 * 1024
+MAX_RUNTIME_MS = 8_000
+MAX_JOBS_IN_MEMORY = 256
+MAX_PROCESS_BINDINGS = 4_096
+ZERO_UPLIFT = {"proof_uplift": 0, "trust_uplift": 0}
+JOB_ID_RE = re.compile(r"^[A-Za-z0-9][A-Za-z0-9._:-]{0,95}$")
+
+OPERATIONS = (
+    "formula.org_lambda.weighted_geomean",
+    "quant.sample.pipeline",
+    "quantum.qubo.exact_baseline",
+    "numerics.external.run",
+    "numerics.external.compare",
+    "proof.lean.inventory",
+    "formula.admission.inventory",
+    "brain.corpus.inventory",
+    "lake.evidence.inventory",
+)
+
+_STORE: "OrderedDict[tuple[str, str], dict[str, Any]]" = OrderedDict()
+_REQUEST_BINDINGS: dict[tuple[str, str], str] = {}
+_STORE_LOCK = threading.RLock()
+
+
+class ContractError(ValueError):
+    """A compute job violates the fixed, data-only contract."""
+
+
+class AuthenticationError(PermissionError):
+    """A compute route has no valid configured bearer authority."""
+
+
+class BodyTooLarge(ContractError):
+    """A request exceeded the compute plane's fixed pre-parse body limit."""
+
+
+def _authorize_request(request: Any) -> str:
+    """Return a non-secret owner id for a configured compute bearer token.
+
+    The runtime stores only the expected SHA-256 in
+    ``A11OY_COMPUTE_TOKEN_SHA256``.  If it is absent, stateful compute routes
+    fail closed rather than becoming an unauthenticated public executor.
+    """
+    expected = os.environ.get("A11OY_COMPUTE_TOKEN_SHA256", "").strip().lower()
+    if not re.fullmatch(r"[0-9a-f]{64}", expected):
+        raise AuthenticationError("compute authority is not configured")
+    authorization = (request.headers.get("authorization") or "").strip()
+    if not authorization.lower().startswith("bearer "):
+        raise AuthenticationError("missing compute bearer authority")
+    token = authorization.split(" ", 1)[1].strip()
+    observed = hashlib.sha256(token.encode("utf-8")).hexdigest()
+    if not hmac.compare_digest(observed, expected):
+        raise AuthenticationError("invalid compute bearer authority")
+    return f"sha256:{expected[:16]}"
+
+
+def canonical_json(value: Any) -> bytes:
+    return json.dumps(
+        value,
+        sort_keys=True,
+        separators=(",", ":"),
+        ensure_ascii=False,
+        allow_nan=False,
+    ).encode("utf-8")
+
+
+def digest_json(value: Any) -> str:
+    return hashlib.sha256(canonical_json(value)).hexdigest()
+
+
+def _now_iso() -> str:
+    return datetime.now(timezone.utc).isoformat()
+
+
+def _mapping(value: Any, name: str) -> Mapping[str, Any]:
+    if not isinstance(value, Mapping):
+        raise ContractError(f"{name} must be an object")
+    return value
+
+
+def _strict(value: Mapping[str, Any], allowed: set[str], required: set[str], name: str) -> None:
+    extras = sorted(set(value) - allowed)
+    missing = sorted(required - set(value))
+    if extras:
+        raise ContractError(f"{name} has unsupported fields: {', '.join(extras)}")
+    if missing:
+        raise ContractError(f"{name} is missing fields: {', '.join(missing)}")
+
+
+def _finite(value: Any, name: str, minimum: float, maximum: float) -> float:
+    if isinstance(value, bool) or not isinstance(value, (int, float)):
+        raise ContractError(f"{name} must be a finite number")
+    result = float(value)
+    if not math.isfinite(result) or not minimum <= result <= maximum:
+        raise ContractError(f"{name} must be between {minimum} and {maximum}")
+    return result
+
+
+def _integer(value: Any, name: str, minimum: int, maximum: int) -> int:
+    if isinstance(value, bool) or not isinstance(value, int) or not minimum <= value <= maximum:
+        raise ContractError(f"{name} must be an integer between {minimum} and {maximum}")
+    return value
+
+
+def _json_object(path: Path, name: str) -> dict[str, Any]:
+    try:
+        value = json.loads(path.read_text(encoding="utf-8"))
+    except (OSError, UnicodeError, json.JSONDecodeError) as exc:
+        raise ContractError(f"{name} is unavailable") from exc
+    if not isinstance(value, dict):
+        raise ContractError(f"{name} must be a JSON object")
+    return value
+
+
+def _file_receipt(path: Path) -> dict[str, Any]:
+    data = path.read_bytes()
+    return {
+        "path": path.relative_to(ROOT).as_posix(),
+        "bytes": len(data),
+        "sha256": hashlib.sha256(data).hexdigest(),
+    }
+
+
+def _parse_lambda_inputs(value: Mapping[str, Any]) -> dict[str, Any]:
+    _strict(value, {"axes", "weights"}, {"axes", "weights"}, "inputs")
+    axes = value["axes"]
+    weights = value["weights"]
+    if (
+        not isinstance(axes, Sequence)
+        or isinstance(axes, (str, bytes, bytearray))
+        or not 1 <= len(axes) <= 32
+    ):
+        raise ContractError("inputs.axes must contain 1..32 scores")
+    if (
+        not isinstance(weights, Sequence)
+        or isinstance(weights, (str, bytes, bytearray))
+        or len(weights) != len(axes)
+    ):
+        raise ContractError("inputs.weights must match inputs.axes")
+    parsed_axes = [_finite(item, f"inputs.axes[{index}]", 0.0, 1.0) for index, item in enumerate(axes)]
+    parsed_weights = [
+        _finite(item, f"inputs.weights[{index}]", 0.0, 1.0)
+        for index, item in enumerate(weights)
+    ]
+    if sum(parsed_weights) <= 0.0:
+        raise ContractError("inputs.weights must have a positive sum")
+    return {"axes": parsed_axes, "weights": parsed_weights}
+
+
+def _parse_inputs(operation: str, raw: Mapping[str, Any]) -> dict[str, Any]:
+    value = dict(raw)
+    if operation == "formula.org_lambda.weighted_geomean":
+        return _parse_lambda_inputs(value)
+    if operation == "quant.sample.pipeline":
+        _strict(value, {"stress", "gamma", "kappa"}, {"stress", "gamma", "kappa"}, "inputs")
+        if not isinstance(value["stress"], bool):
+            raise ContractError("inputs.stress must be a boolean")
+        return {
+            "stress": value["stress"],
+            "gamma": _finite(value["gamma"], "inputs.gamma", 0.0, 10.0),
+            "kappa": _finite(value["kappa"], "inputs.kappa", 0.0, 10.0),
+        }
+    if operation == "quantum.qubo.exact_baseline":
+        _strict(value, {"request"}, {"request"}, "inputs")
+        return {"request": dict(_mapping(value["request"], "inputs.request"))}
+    if operation == "numerics.external.run":
+        _strict(value, {"engine", "request"}, {"engine", "request"}, "inputs")
+        if value["engine"] not in ("octave", "matlab"):
+            raise ContractError("inputs.engine must be octave or matlab")
+        return {"engine": value["engine"], "request": dict(_mapping(value["request"], "inputs.request"))}
+    if operation == "numerics.external.compare":
+        _strict(value, {"request"}, {"request"}, "inputs")
+        return {"request": dict(_mapping(value["request"], "inputs.request"))}
+    if operation in {
+        "proof.lean.inventory",
+        "formula.admission.inventory",
+        "brain.corpus.inventory",
+        "lake.evidence.inventory",
+    }:
+        _strict(value, set(), set(), "inputs")
+        return {}
+    raise ContractError("unsupported operation")
+
+
+def parse_job(payload: Mapping[str, Any]) -> dict[str, Any]:
+    obj = _mapping(payload, "job")
+    allowed = {"schema", "job_id", "operation", "inputs", "resource_budget"}
+    _strict(obj, allowed, allowed, "job")
+    if obj["schema"] != JOB_SCHEMA:
+        raise ContractError(f"schema must be {JOB_SCHEMA}")
+    job_id = obj["job_id"]
+    if not isinstance(job_id, str) or not JOB_ID_RE.fullmatch(job_id):
+        raise ContractError("job_id must be a bounded identifier")
+    operation = obj["operation"]
+    if operation not in OPERATIONS:
+        raise ContractError("operation is not registered")
+    budget = _mapping(obj["resource_budget"], "resource_budget")
+    _strict(
+        budget,
+        {"max_runtime_ms", "max_output_bytes"},
+        {"max_runtime_ms", "max_output_bytes"},
+        "resource_budget",
+    )
+    return {
+        "schema": JOB_SCHEMA,
+        "job_id": job_id,
+        "operation": operation,
+        "inputs": _parse_inputs(operation, _mapping(obj["inputs"], "inputs")),
+        "resource_budget": {
+            "max_runtime_ms": _integer(budget["max_runtime_ms"], "resource_budget.max_runtime_ms", 1, MAX_RUNTIME_MS),
+            "max_output_bytes": _integer(budget["max_output_bytes"], "resource_budget.max_output_bytes", 1_024, MAX_OUTPUT_BYTES),
+        },
+    }
+
+
+def _lambda_job(inputs: Mapping[str, Any]) -> dict[str, Any]:
+    from szl_org_lambda import weighted_geomean
+
+    value = weighted_geomean(inputs["axes"], inputs["weights"])
+    return {
+        "value": value,
+        "label": "ADVISORY",
+        "runtime_binding": "szl_org_lambda.weighted_geomean",
+        "formula_namespace": "org-lambda.weighted-geomean",
+        "zero_absorption": any(item == 0.0 for item in inputs["axes"]),
+        "uniqueness": "CONJECTURE_1_OPEN",
+        "proof_transfer": "DENIED_NAMESPACE_SCOPED",
+        **ZERO_UPLIFT,
+    }
+
+
+def _quant_job(inputs: Mapping[str, Any]) -> dict[str, Any]:
+    from szl_gpu_quant import run_pipeline
+
+    return run_pipeline(
+        stress=inputs["stress"],
+        gamma=inputs["gamma"],
+        kappa=inputs["kappa"],
+    )
+
+
+def _quantum_job(inputs: Mapping[str, Any]) -> dict[str, Any]:
+    from szl_quantum_utility import run_with_receipt
+
+    return run_with_receipt("QUBO_EXACT_BASELINE", inputs["request"])
+
+
+def _numerics_run(inputs: Mapping[str, Any], budget: Mapping[str, int]) -> dict[str, Any]:
+    from szl_numerics_adapter import run_engine
+
+    timeout = max(1, min(8, math.ceil(budget["max_runtime_ms"] / 1_000)))
+    return run_engine(inputs["engine"], inputs["request"], timeout_seconds=timeout)
+
+
+def _numerics_compare(inputs: Mapping[str, Any]) -> dict[str, Any]:
+    from szl_numerics_adapter import compare_engines
+
+    return compare_engines(inputs["request"])
+
+
+def _lean_inventory() -> dict[str, Any]:
+    path = ROOT / "proofs" / "lean-theorem-tree.json"
+    source = _json_object(path, "Lean theorem inventory")
+    meta = source.get("meta") or {}
+    return {
+        "state": "INVENTORY_ONLY_NOT_FRESH_KERNEL_EXECUTION",
+        "toolchain": "Lean 4.13.0 + mathlib 4.13.0 (repository pin)",
+        "commit": str(meta.get("commit") or "UNKNOWN"),
+        "total_declarations": int(meta.get("total_declarations") or 0),
+        "inventory": _file_receipt(path),
+        "kernel_execution_this_job": False,
+        **ZERO_UPLIFT,
+    }
+
+
+def _formula_inventory() -> dict[str, Any]:
+    path = ROOT / "research" / "formula-training-admission" / "admission-manifest.json"
+    source = _json_object(path, "formula admission manifest")
+    summary = source.get("decision_summary") or {}
+    thesis = ((source.get("source_snapshot") or {}).get("thesis") or {})
+    return {
+        "state": source.get("status", "UNKNOWN"),
+        "admission": summary.get("training_admission", "UNKNOWN"),
+        "crosswalk_rows": summary.get("formula_crosswalk_rows", 0),
+        "holdout_rows": summary.get("holdout_rows", 0),
+        "train_rows": summary.get("train_rows", 0),
+        "resolved_status_counts": summary.get("resolved_status_counts", {}),
+        "thesis_extracted_formula_count": thesis.get("extracted_formula_count", 0),
+        "requested_200_status": "NOT_VERIFIED_BY_CURRENT_VERSIONED_SOURCES",
+        "manifest": _file_receipt(path),
+        **ZERO_UPLIFT,
+    }
+
+
+def _brain_inventory() -> dict[str, Any]:
+    path = ROOT / "model_release" / "m1" / "corpus-ingestion-manifest.json"
+    source = _json_object(path, "Brain corpus manifest")
+    coverage = source.get("coverage") or {}
+    return {
+        "state": "RETRIEVAL_AND_EVAL_AVAILABLE_TRAINING_QUARANTINED",
+        "raw_nodes": int(coverage.get("node_decisions_total") or 0),
+        "distinct_artifacts": int(coverage.get("distinct_artifacts") or 0),
+        "training_eligible_nodes": int(coverage.get("training_eligible_nodes") or 0),
+        "missing_item_level_license_nodes": int(coverage.get("missing_item_level_license_nodes") or 0),
+        "missing_source_timestamp_nodes": int(coverage.get("missing_source_timestamp_nodes") or 0),
+        "manifest": _file_receipt(path),
+        **ZERO_UPLIFT,
+    }
+
+
+def _lake_inventory() -> dict[str, Any]:
+    path = ROOT / "data" / "szl-lake" / "evidence-manifest.json"
+    source = _json_object(path, "SZL Lake evidence manifest")
+    entries = source.get("entries") or []
+    return {
+        "state": "EVIDENCE_AND_RECEIPT_SUBSTRATE",
+        "entry_count": len(entries),
+        "proof_statuses": sorted(
+            {
+                str(((entry.get("artifact_receipt") or {}).get("proof_status") or "UNKNOWN"))
+                for entry in entries
+                if isinstance(entry, Mapping)
+            }
+        ),
+        "manifest": _file_receipt(path),
+        **ZERO_UPLIFT,
+    }
+
+
+def _execute(operation: str, inputs: Mapping[str, Any], budget: Mapping[str, int]) -> dict[str, Any]:
+    if operation == "formula.org_lambda.weighted_geomean":
+        return _lambda_job(inputs)
+    if operation == "quant.sample.pipeline":
+        return _quant_job(inputs)
+    if operation == "quantum.qubo.exact_baseline":
+        return _quantum_job(inputs)
+    if operation == "numerics.external.run":
+        return _numerics_run(inputs, budget)
+    if operation == "numerics.external.compare":
+        return _numerics_compare(inputs)
+    if operation == "proof.lean.inventory":
+        return _lean_inventory()
+    if operation == "formula.admission.inventory":
+        return _formula_inventory()
+    if operation == "brain.corpus.inventory":
+        return _brain_inventory()
+    if operation == "lake.evidence.inventory":
+        return _lake_inventory()
+    raise ContractError("operation is not registered")
+
+
+def _state_for(operation: str, output: Mapping[str, Any]) -> tuple[str, str]:
+    if operation == "numerics.external.run" and output.get("state") == "UNAVAILABLE":
+        return "UNAVAILABLE", "UNKNOWN"
+    if operation == "numerics.external.compare" and output.get("comparison_state") == "UNAVAILABLE":
+        return "UNAVAILABLE", "UNKNOWN"
+    if operation == "quant.sample.pipeline":
+        return "COMPLETED", "SAMPLE"
+    if operation.startswith("proof."):
+        return "COMPLETED", "INVENTORY"
+    if operation.startswith(("formula.admission", "brain.", "lake.")):
+        return "COMPLETED", "VERSIONED_LOCAL_EVIDENCE"
+    if operation.startswith("quantum."):
+        return "COMPLETED", "MEASURED_CLASSICAL_BASELINE"
+    return "COMPLETED", "COMPUTED_ADVISORY"
+
+
+def _span(name: str, operation: str):
+    try:
+        from szl_observability import span
+
+        return span(name, operation=operation, component="yupaq-compute")
+    except Exception:
+        return nullcontext()
+
+
+def _sign_receipt(body: Mapping[str, Any]) -> tuple[dict[str, Any], dict[str, Any]]:
+    try:
+        from szl_dsse import sign_payload, verify_envelope
+
+        envelope = sign_payload(dict(body), PAYLOAD_TYPE)
+        verification = verify_envelope(envelope)
+        return envelope, verification
+    except Exception as exc:
+        return (
+            {
+                "payloadType": PAYLOAD_TYPE,
+                "payload": "",
+                "signatures": [],
+                "signed": False,
+                "honesty": f"UNSIGNED: DSSE unavailable ({type(exc).__name__})",
+            },
+            {"verified": False, "reason": "DSSE_UNAVAILABLE"},
+        )
+
+
+def _append_to_lake(record: Mapping[str, Any]) -> dict[str, Any]:
+    try:
+        from szl_lake_store import get_default_ledger
+
+        return get_default_ledger().append(dict(record))
+    except Exception as exc:
+        return {
+            "accepted": False,
+            "duplicate": False,
+            "state": "UNAVAILABLE",
+            "reason": type(exc).__name__,
+        }
+
+
+def _lookup_memory(owner_id: str, job_id: str) -> dict[str, Any] | None:
+    key = (owner_id, job_id)
+    with _STORE_LOCK:
+        found = _STORE.get(key)
+        if found is None:
+            return None
+        _STORE.move_to_end(key)
+        return copy.deepcopy(found)
+
+
+def _remember(owner_id: str, job: Mapping[str, Any]) -> None:
+    key = (owner_id, str(job["job_id"]))
+    with _STORE_LOCK:
+        _STORE[key] = copy.deepcopy(dict(job))
+        _STORE.move_to_end(key)
+        while len(_STORE) > MAX_JOBS_IN_MEMORY:
+            _STORE.popitem(last=False)
+
+
+def run_job(
+    payload: Mapping[str, Any],
+    *,
+    persist: bool = True,
+    owner_id: str = "local-direct",
+) -> dict[str, Any]:
+    """Execute one strict, bounded job and return its result plus receipts."""
+
+    request = parse_job(payload)
+    request_sha256 = digest_json(request)
+    owner = str(owner_id or "").strip()
+    if not owner or len(owner) > 96:
+        raise ContractError("owner_id must be a bounded non-empty identifier")
+    key = (owner, request["job_id"])
+    with _STORE_LOCK:
+        existing = _STORE.get(key)
+        if existing is not None:
+            if existing["request_sha256"] != request_sha256:
+                raise ContractError("job_id is already bound to a different request")
+            replay = copy.deepcopy(existing)
+            replay["idempotent_replay"] = True
+            return replay
+        prior = _REQUEST_BINDINGS.get(key)
+        if prior is not None:
+            if prior != request_sha256:
+                raise ContractError("job_id is already bound to a different request")
+            raise ContractError("job_id is already in progress or retained by the replay guard")
+        if len(_REQUEST_BINDINGS) >= MAX_PROCESS_BINDINGS:
+            raise ContractError("process-local replay guard is at capacity")
+        _REQUEST_BINDINGS[key] = request_sha256
+
+    try:
+        started = time.perf_counter()
+        with _span("yupaq.compute", request["operation"]):
+            output = _execute(request["operation"], request["inputs"], request["resource_budget"])
+        duration_ms = round((time.perf_counter() - started) * 1_000, 3)
+    except Exception:
+        with _STORE_LOCK:
+            _REQUEST_BINDINGS.pop(key, None)
+        raise
+
+    output_bytes = canonical_json(output)
+    if len(output_bytes) > request["resource_budget"]["max_output_bytes"]:
+        state = "FAILED"
+        evidence_label = "OUTPUT_BUDGET_EXCEEDED"
+        output = {
+            "error": "output exceeded the declared byte budget",
+            "observed_output_bytes": len(output_bytes),
+        }
+    else:
+        state, evidence_label = _state_for(request["operation"], output)
+    if duration_ms > request["resource_budget"]["max_runtime_ms"]:
+        state = "FAILED"
+        evidence_label = "RUNTIME_BUDGET_EXCEEDED"
+
+    result = {
+        "schema": RESULT_SCHEMA,
+        "job_id": request["job_id"],
+        "operation": request["operation"],
+        "state": state,
+        "evidence_label": evidence_label,
+        "request_sha256": request_sha256,
+        "duration_ms": duration_ms,
+        "output": output,
+        "resource_budget": request["resource_budget"],
+        "runtime_budget_enforcement": "POST_HOC_EXCEPT_ENGINE_SPECIFIC_TIMEOUT",
+        "arbitrary_code_allowed": False,
+        "network_requested": False,
+        **ZERO_UPLIFT,
+    }
+    result_sha256 = digest_json(result)
+    receipt_body = {
+        "schema": RECEIPT_SCHEMA,
+        "organ": "yupaq-compute",
+        "owner_id": owner,
+        "job_id": request["job_id"],
+        "operation": request["operation"],
+        "request_sha256": request_sha256,
+        "result_sha256": result_sha256,
+        "code_commit": os.environ.get("A11OY_GIT_COMMIT", "UNKNOWN"),
+        "trace_id": os.environ.get("A11OY_TRACE_ID", "UNKNOWN"),
+        "created_at": _now_iso(),
+        "state": state,
+        "evidence_label": evidence_label,
+        "lambda_uniqueness": "CONJECTURE_1_OPEN",
+        **ZERO_UPLIFT,
+    }
+    receipt_body["receipt_sha256"] = digest_json(receipt_body)
+    dsse, dsse_verification = _sign_receipt(receipt_body)
+    response = {
+        "job_id": request["job_id"],
+        "owner_id": owner,
+        "request": request,
+        "request_sha256": request_sha256,
+        "result": result,
+        "result_sha256": result_sha256,
+        "receipt": receipt_body,
+        "dsse": dsse,
+        "dsse_verification": dsse_verification,
+        "idempotent_replay": False,
+    }
+    if persist:
+        response["lake"] = _append_to_lake(
+            {
+                "organ": "yupaq-compute",
+                "action": "compute.job",
+                "ts": receipt_body["created_at"],
+                "job_id": request["job_id"],
+                "request_sha256": request_sha256,
+                "result_sha256": result_sha256,
+                "receipt": receipt_body,
+                "dsse": dsse,
+            }
+        )
+    else:
+        response["lake"] = {"state": "NOT_REQUESTED"}
+    _remember(owner, response)
+    return copy.deepcopy(response)
+
+
+def get_job(job_id: str, *, owner_id: str = "local-direct") -> dict[str, Any] | None:
+    if not JOB_ID_RE.fullmatch(job_id):
+        raise ContractError("job_id must be a bounded identifier")
+    return _lookup_memory(owner_id, job_id)
+
+
+def verify_job_record(value: Mapping[str, Any]) -> dict[str, Any]:
+    obj = _mapping(value, "job record")
+    required = {
+        "job_id", "owner_id", "request", "request_sha256", "result",
+        "result_sha256", "receipt", "dsse",
+    }
+    missing = sorted(required - set(obj))
+    if missing:
+        raise ContractError(f"job record is missing fields: {', '.join(missing)}")
+    request_obj = _mapping(obj["request"], "request")
+    result_obj = _mapping(obj["result"], "result")
+    request_match = digest_json(request_obj) == obj["request_sha256"]
+    result_match = digest_json(result_obj) == obj["result_sha256"]
+    receipt = _mapping(obj["receipt"], "receipt")
+    receipt_material = dict(receipt)
+    claimed_receipt_sha256 = receipt_material.pop("receipt_sha256", None)
+    receipt_digest_match = (
+        isinstance(claimed_receipt_sha256, str)
+        and digest_json(receipt_material) == claimed_receipt_sha256
+    )
+    schema_match = (
+        request_obj.get("schema") == JOB_SCHEMA
+        and result_obj.get("schema") == RESULT_SCHEMA
+        and receipt.get("schema") == RECEIPT_SCHEMA
+    )
+    semantic_links = (
+        receipt.get("owner_id") == obj.get("owner_id")
+        and receipt.get("job_id") == obj.get("job_id")
+        == request_obj.get("job_id")
+        == result_obj.get("job_id")
+        and receipt.get("operation") == request_obj.get("operation")
+        == result_obj.get("operation")
+        and receipt.get("state") == result_obj.get("state")
+        and receipt.get("evidence_label") == result_obj.get("evidence_label")
+        and result_obj.get("request_sha256") == obj.get("request_sha256")
+    )
+    receipt_links = (
+        receipt.get("request_sha256") == obj["request_sha256"]
+        and receipt.get("result_sha256") == obj["result_sha256"]
+    )
+    try:
+        from szl_dsse import verify_envelope
+
+        dsse = verify_envelope(dict(_mapping(obj["dsse"], "dsse")))
+    except Exception:
+        dsse = {"verified": False, "reason": "DSSE_UNAVAILABLE"}
+    payload_match = dsse.get("payload_decoded") == dict(receipt)
+    return {
+        "valid": bool(
+            request_match
+            and result_match
+            and receipt_links
+            and receipt_digest_match
+            and schema_match
+            and semantic_links
+            and payload_match
+            and dsse.get("verified")
+        ),
+        "request_hash_match": request_match,
+        "result_hash_match": result_match,
+        "receipt_links_match": receipt_links,
+        "receipt_digest_match": receipt_digest_match,
+        "schema_match": schema_match,
+        "semantic_links_match": semantic_links,
+        "dsse_payload_match": payload_match,
+        "signature_verified": bool(dsse.get("verified")),
+        "unsigned_records_are_valid": False,
+    }
+
+
+def capabilities() -> dict[str, Any]:
+    try:
+        from szl_numerics_adapter import engine_status
+
+        numerics = engine_status()
+    except Exception:
+        numerics = {"mode": "UNAVAILABLE", "substrate_evidence": "UNKNOWN", **ZERO_UPLIFT}
+    brain = _brain_inventory()
+    formulas = _formula_inventory()
+    lean = _lean_inventory()
+    return {
+        "schema": "szl.compute-capabilities/v1",
+        "name": "Yupaq Governed Computation Plane",
+        "mode": "BOUNDED_TYPED_OPERATIONS_ONLY",
+        "operations": list(OPERATIONS),
+        "lanes": {
+            "quant": "CPU_REFERENCE_SAMPLE_ONLY",
+            "quantum_utility": "CLASSICAL_BASELINE_PROPOSAL_ONLY",
+            "numerics": numerics,
+            "lean_mathlib": lean,
+            "formula_registry": formulas,
+            "brain": brain,
+            "szl_lake": "BEST_EFFORT_LOCAL_KHIPU_APPEND_REDEPLOY_DURABILITY_NOT_VERIFIED",
+            "ouroboros": "ORCHESTRATION_LOOP_OUTSIDE_WEIGHTS",
+            "codex_workers": "PROPOSAL_BUILD_TEST_REVIEW_WITH_SIGNED_HANDOFFS",
+            "invariant": "NOT_WIRED_TO_RUN_JOB",
+            "lambda": "ADVISORY_CONJECTURE_1_OPEN",
+        },
+        "formula_accounting": {
+            "requested_200": "NOT_VERIFIED",
+            "thesis_extracted": formulas["thesis_extracted_formula_count"],
+            "crosswalk_rows": formulas["crosswalk_rows"],
+            "holdout_rows": formulas["holdout_rows"],
+            "train_rows": formulas["train_rows"],
+            "lean_declarations": lean["total_declarations"],
+        },
+        "brain_nodes": brain["raw_nodes"],
+        "brain_nodes_in_gradients": brain["training_eligible_nodes"],
+        "arbitrary_code_allowed": False,
+        "arbitrary_urls_allowed": False,
+        "model_weight_role": "MODEL_PROPOSES_TYPED_JOB; PLANE_VALIDATES_AND_EXECUTES",
+        "authorization": {
+            "stateful_routes_require_bearer": True,
+            "configured": bool(re.fullmatch(
+                r"[0-9a-f]{64}",
+                os.environ.get("A11OY_COMPUTE_TOKEN_SHA256", "").strip().lower(),
+            )),
+            "secret_name": "A11OY_COMPUTE_TOKEN_SHA256",
+            "owner_isolation": "TOKEN_SHA256_PREFIX",
+            "replay_scope": "PROCESS_LOCAL_BOUNDED",
+        },
+        **ZERO_UPLIFT,
+    }
+
+
+async def _bounded_body(request: Any) -> dict[str, Any]:
+    declared = request.headers.get("content-length")
+    if declared is not None:
+        try:
+            size = int(declared)
+        except ValueError as exc:
+            raise ContractError("content-length must be a non-negative integer") from exc
+        if size < 0 or size > MAX_BODY_BYTES:
+            raise BodyTooLarge("request body exceeds 128 KiB")
+    data = bytearray()
+    async for chunk in request.stream():
+        if len(data) + len(chunk) > MAX_BODY_BYTES:
+            raise BodyTooLarge("request body exceeds 128 KiB")
+        data.extend(chunk)
+    try:
+        value = json.loads(bytes(data).decode("utf-8"))
+    except (UnicodeDecodeError, json.JSONDecodeError) as exc:
+        raise ContractError("request body must be one JSON object") from exc
+    if not isinstance(value, dict):
+        raise ContractError("request body must be one JSON object")
+    return value
+
+
+def register(app: Any, ns: str = "a11oy") -> dict[str, Any]:
+    """Register the computation plane before proxy and SPA catch-alls."""
+
+    from fastapi import Request
+    from fastapi.responses import JSONResponse
+
+    prefix = f"/api/{ns}/v1/compute"
+
+    @app.get(f"{prefix}/capabilities")
+    async def compute_capabilities() -> JSONResponse:
+        return JSONResponse(capabilities())
+
+    @app.post(f"{prefix}/jobs")
+    async def compute_jobs(request: Request) -> JSONResponse:
+        try:
+            owner_id = _authorize_request(request)
+        except AuthenticationError as exc:
+            status = 503 if "not configured" in str(exc) else 401
+            return JSONResponse(
+                {"state": "UNAVAILABLE" if status == 503 else "UNAUTHORIZED",
+                 "error": str(exc), **ZERO_UPLIFT},
+                status_code=status,
+            )
+        try:
+            payload = await _bounded_body(request)
+            record = await asyncio.to_thread(
+                run_job, payload, persist=True, owner_id=owner_id)
+        except BodyTooLarge as exc:
+            return JSONResponse(
+                {"state": "REJECTED", "error": str(exc), **ZERO_UPLIFT},
+                status_code=413,
+            )
+        except ContractError as exc:
+            return JSONResponse({"state": "REJECTED", "error": str(exc), **ZERO_UPLIFT}, status_code=422)
+        except Exception as exc:
+            return JSONResponse(
+                {"state": "UNAVAILABLE", "reason": type(exc).__name__, **ZERO_UPLIFT},
+                status_code=503,
+            )
+        status = 503 if record["result"]["state"] == "UNAVAILABLE" else 200
+        return JSONResponse(record, status_code=status)
+
+    @app.get(f"{prefix}/jobs/{{job_id}}")
+    async def compute_job(request: Request, job_id: str) -> JSONResponse:
+        try:
+            owner_id = _authorize_request(request)
+        except AuthenticationError as exc:
+            status = 503 if "not configured" in str(exc) else 401
+            return JSONResponse(
+                {"state": "UNAVAILABLE" if status == 503 else "UNAUTHORIZED",
+                 "error": str(exc), **ZERO_UPLIFT},
+                status_code=status,
+            )
+        try:
+            record = get_job(job_id, owner_id=owner_id)
+        except ContractError as exc:
+            return JSONResponse({"state": "REJECTED", "error": str(exc), **ZERO_UPLIFT}, status_code=422)
+        if record is None:
+            return JSONResponse({"state": "NOT_FOUND", "job_id": job_id, **ZERO_UPLIFT}, status_code=404)
+        return JSONResponse(record)
+
+    @app.get(f"{prefix}/receipts/{{job_id}}")
+    async def compute_receipt(request: Request, job_id: str) -> JSONResponse:
+        try:
+            owner_id = _authorize_request(request)
+        except AuthenticationError as exc:
+            status = 503 if "not configured" in str(exc) else 401
+            return JSONResponse(
+                {"state": "UNAVAILABLE" if status == 503 else "UNAUTHORIZED",
+                 "error": str(exc), **ZERO_UPLIFT},
+                status_code=status,
+            )
+        try:
+            record = get_job(job_id, owner_id=owner_id)
+        except ContractError as exc:
+            return JSONResponse({"state": "REJECTED", "error": str(exc), **ZERO_UPLIFT}, status_code=422)
+        if record is None:
+            return JSONResponse({"state": "NOT_FOUND", "job_id": job_id, **ZERO_UPLIFT}, status_code=404)
+        return JSONResponse(
+            {
+                "job_id": job_id,
+                "receipt": record["receipt"],
+                "dsse": record["dsse"],
+                "dsse_verification": record["dsse_verification"],
+                "lake": record["lake"],
+            }
+        )
+
+    @app.post(f"{prefix}/receipts/verify")
+    async def compute_verify(request: Request) -> JSONResponse:
+        try:
+            verdict = verify_job_record(await _bounded_body(request))
+        except ContractError as exc:
+            return JSONResponse({"valid": False, "error": str(exc), **ZERO_UPLIFT}, status_code=422)
+        return JSONResponse(verdict, status_code=200 if verdict["valid"] else 409)
+
+    return {
+        "registered": True,
+        "routes": [
+            f"{prefix}/capabilities",
+            f"{prefix}/jobs",
+            f"{prefix}/jobs/{{job_id}}",
+            f"{prefix}/receipts/{{job_id}}",
+            f"{prefix}/receipts/verify",
+        ],
+        "operation_count": len(OPERATIONS),
+        "stateful_routes_require_auth": True,
+        "auth_secret": "A11OY_COMPUTE_TOKEN_SHA256",
+        **ZERO_UPLIFT,
+    }
+
+
+__all__ = [
+    "ContractError",
+    "JOB_SCHEMA",
+    "OPERATIONS",
+    "RECEIPT_SCHEMA",
+    "RESULT_SCHEMA",
+    "capabilities",
+    "digest_json",
+    "get_job",
+    "parse_job",
+    "register",
+    "run_job",
+    "verify_job_record",
+]

szl_yupay.py

@@ -638,16 +638,16 @@ def register(app, ns: str = "a11oy") -> Dict[str, Any]:
     n_before = len(app.router.routes)
 
     @app.get(f"/api/{ns}/v1/yupay/doctrine", include_in_schema=False)
-    async def _doctrine() -> JSONResponse:
+    async def _doctrine():  # noqa: ANN202
         return JSONResponse(doctrine())
 
     @app.get(f"/api/{ns}/v1/yupay/demo", include_in_schema=False)
-    async def _demo(req: Request) -> JSONResponse:
+    async def _demo(req: Request):  # noqa: ANN202
         q = req.query_params.get("task")
         return JSONResponse(demo(task_prompt=q))
 
     @app.post(f"/api/{ns}/v1/yupay/compare", include_in_schema=False)
-    async def _compare(req: Request) -> JSONResponse:
+    async def _compare(req: Request):  # noqa: ANN202
         try:
             body = await req.json()
         except Exception:
@@ -659,7 +659,7 @@ def register(app, ns: str = "a11oy") -> Dict[str, Any]:
         return JSONResponse(governed_compare(task=t, data_label="MODELED"))
 
     @app.get(f"/api/{ns}/v1/yupay/receipts", include_in_schema=False)
-    async def _receipts() -> JSONResponse:
+    async def _receipts():  # noqa: ANN202
         tail = _RECEIPTS[-20:]
         return JSONResponse({"count": len(_RECEIPTS),
                              "receipts": [{"payload": r["payload"],
@@ -667,7 +667,7 @@ def register(app, ns: str = "a11oy") -> Dict[str, Any]:
                                           for r in tail]})
 
     @app.post(f"/api/{ns}/v1/yupay/verify", include_in_schema=False)
-    async def _verify(req: Request) -> JSONResponse:
+    async def _verify(req: Request):  # noqa: ANN202
         try:
             body = await req.json()
         except Exception:
@@ -676,7 +676,7 @@ def register(app, ns: str = "a11oy") -> Dict[str, Any]:
         return JSONResponse(verify_receipt(env))
 
     @app.get("/yupay", include_in_schema=False)
-    async def _page() -> HTMLResponse:
+    async def _page():  # noqa: ANN202
         return HTMLResponse(_PAGE_HTML.replace("{NS}", ns))
 
     # Move the YUPAY routes just appended (the tail beyond n_before) to the FRONT,