Add reference authority check, live export helper, and invariant tests

fraware · fraware · commit 677431e313a2 · 2026-05-25T21:40:44.000-07:00
diff --git a/Makefile b/Makefile
@@ -23,7 +23,7 @@ else
   PYTHON ?= python
 endif
 
-.PHONY: test test-reference test-slow test-solver test-vendor-moreau smoke-solver smoke-check env-check reference-correctness perf-benchmark diff-check trust-dashboard parity-native-licensed artifact-validation-report parity-report audit dashboard validate-fixture lint typecheck format format-check cov cov-gates compile-deps verify-extended bootstrap-moreau upgrade-host-realistic-vendor host-realistic-rehearsal export-upstream-rehearsal batch-solve-report verify-reference-system
+.PHONY: test test-reference test-slow test-solver test-vendor-moreau smoke-solver smoke-check env-check reference-correctness perf-benchmark diff-check trust-dashboard parity-native-licensed artifact-validation-report parity-report audit dashboard validate-fixture lint typecheck format format-check cov cov-gates compile-deps verify-extended bootstrap-moreau upgrade-host-realistic-vendor host-realistic-rehearsal export-upstream-rehearsal batch-solve-report verify-reference-system reference-authority-check refresh-live-upstream-export
 
 test:
 	$(PYTHON) -m pytest -q
@@ -73,12 +73,19 @@ export-upstream-rehearsal:
 upgrade-host-realistic-vendor:
 	$(PYTHON) scripts/upgrade_host_realistic_vendor.py --force
 
-verify-reference-system:
-	$(PYTHON) scripts/refresh_published_run_index.py --check
+reference-authority-check:
+	$(PYTHON) scripts/reference_authority_check.py
+
+refresh-live-upstream-export:
+	@echo "Usage: $(PYTHON) scripts/refresh_live_upstream_export.py --graph-json <path/to/offline_transition_graph.json>"
+
+verify-reference-system: reference-authority-check
 	$(PYTHON) -m pytest \
 		tests/governance/test_published_run_index.py \
 		tests/governance/test_host_realistic_publish_evidence.py \
 		tests/governance/test_reference_evidence_tiers.py \
+		tests/governance/test_reference_authority_invariants.py \
+		tests/governance/test_native_arm_publish_evidence.py \
 		tests/governance/test_run_host_realistic_publish.py \
 		tests/governance/test_batch_solve_report.py \
 		tests/bench/test_inter_sim_export.py \
diff --git a/README.md b/README.md
@@ -53,7 +53,7 @@ Optional: replace the committed export with a **live** inter-sim dump ([`docs/HO
 
 ---
 
-Contributing and merge policy: [`CONTRIBUTING.md`](CONTRIBUTING.md), [`docs/CI_MERGE_GATES.md`](docs/CI_MERGE_GATES.md). Evidence tiers: [`docs/REFERENCE_EVIDENCE_TIERS.md`](docs/REFERENCE_EVIDENCE_TIERS.md). Local gate: `make verify-reference-system`.
+Contributing and merge policy: [`CONTRIBUTING.md`](CONTRIBUTING.md), [`docs/CI_MERGE_GATES.md`](docs/CI_MERGE_GATES.md). Reference authority map: [`docs/REFERENCE_AUTHORITY.md`](docs/REFERENCE_AUTHORITY.md). Evidence tiers: [`docs/REFERENCE_EVIDENCE_TIERS.md`](docs/REFERENCE_EVIDENCE_TIERS.md). Local gates: `make reference-authority-check`, `make verify-reference-system`.
 
 ## Installation
 
@@ -198,6 +198,7 @@ See also [`docs/README.md`](docs/README.md) for a compact index.
 
 **Status & roadmap**
 
+- [`docs/REFERENCE_AUTHORITY.md`](docs/REFERENCE_AUTHORITY.md) — flagship release, gates, and maintainer checklist
 - [`docs/ENGINEERING_STATUS.md`](docs/ENGINEERING_STATUS.md) — what is implemented, CI, solver pins
 - [`docs/ROADMAP.md`](docs/ROADMAP.md) — external dependencies and deferred work
 
diff --git a/benchmarks/external_evidence/EXPORT_PROVENANCE.json b/benchmarks/external_evidence/EXPORT_PROVENANCE.json
@@ -3,6 +3,8 @@
   "export_json": "benchmarks/external_evidence/offline_graph_export_upstream.json",
   "upstream_repository": "https://github.com/fraware/inter-sim-rl",
   "upstream_revision_pin": "third_party/inter-sim-rl/REVISION",
+  "export_kind": "structural_committed",
   "graph_shape": "host_realistic_fork",
-  "notes": "Multi-branch offline graph export (Root to NodeA/NodeB/NodeC). Structural host-shaped evidence committed for the export to bank to publish loop. Re-export from a patched inter-sim-rl host and replace this file when a live upstream dump is available; keep RUN_PROVENANCE.source_export_json aligned."
+  "flagship_run_id": "host-realistic-20260525",
+  "notes": "Multi-branch offline graph export (Root to NodeA/NodeB/NodeC). Structural host-shaped evidence committed for the export to bank to publish loop. For a live upstream dump use scripts/refresh_live_upstream_export.py then make upgrade-host-realistic-vendor."
 }
diff --git a/benchmarks/reports/README.md b/benchmarks/reports/README.md
@@ -0,0 +1,17 @@
+# Benchmark reports (committed examples)
+
+Optional JSON reports that illustrate public benchmark evidence shapes. They are **not** live vendor timing claims unless regenerated on a licensed host and committed intentionally.
+
+| File | Purpose |
+|------|---------|
+| [`batch_solve_report.example.json`](batch_solve_report.example.json) | Schema example for `scripts/batch_solve_report.py` output (`native_microbatch` vs `native_compiled_real_batch`) |
+
+## Regenerate real batch evidence (licensed host)
+
+```bash
+python scripts/performance_benchmark.py --batch-size 4
+python scripts/batch_solve_report.py output/performance_summary.json \
+  --out benchmarks/reports/batch_solve_report.latest.json
+```
+
+Document the workflow in [`docs/SOLVER_PATHS_AND_BATCHING.md`](../../docs/SOLVER_PATHS_AND_BATCHING.md).
diff --git a/benchmarks/reports/batch_solve_report.example.json b/benchmarks/reports/batch_solve_report.example.json
@@ -0,0 +1,22 @@
+{
+  "schema_version": "conicshield_batch_solve_report/v1",
+  "example_only": true,
+  "generated_at_utc": "2026-05-26T00:00:00Z",
+  "source": "illustrative — regenerate via scripts/performance_benchmark.py on a licensed host",
+  "comparisons": [
+    {
+      "scenario_id": "default",
+      "conditioning": "well",
+      "device": "cpu",
+      "auto_tune": false,
+      "batch_size": 4,
+      "mean_sec_sequential": 0.002,
+      "mean_sec_batched": 0.001,
+      "speedup_ratio": 2.0
+    }
+  ],
+  "summary": {
+    "pairs": 1,
+    "max_speedup_ratio": 2.0
+  }
+}
diff --git a/docs/HOST_REALISTIC_RUNBOOK.md b/docs/HOST_REALISTIC_RUNBOOK.md
@@ -40,4 +40,4 @@ You have a committed `run_id` under `benchmarks/published_runs/` whose `RUN_PROV
 |------|---------|
 | Full vendor rebuild | `make upgrade-host-realistic-vendor` or `python scripts/upgrade_host_realistic_vendor.py --force` |
 | Governance + parity only | `python scripts/upgrade_host_realistic_vendor.py --refresh-governance` |
-| Live upstream dump | Re-export to `benchmarks/external_evidence/offline_graph_export_upstream.json`, update `EXPORT_PROVENANCE.json`, then upgrade as above |
+| Live upstream dump | `python scripts/refresh_live_upstream_export.py --graph-json <dump.json>` then `make upgrade-host-realistic-vendor` |
diff --git a/docs/MAINTAINER_RUNBOOK.md b/docs/MAINTAINER_RUNBOOK.md
@@ -49,6 +49,17 @@ Use the fixture regeneration procedure. Do not overwrite the fixture casually.
 ### Case E: a run appears good and all gates are green
 Use **`release_cli`** for a full publish (updates `CURRENT.json`, `HISTORY.json`, and `benchmarks/registry.json`). To refresh gate columns on `CURRENT.json` for an **already published** run after new parity evidence, use **`finalize_cli`** with **`--parity-summary-path`** and **`--sync-current-release`** — do not edit `CURRENT.json` by hand.
 
+## Reference authority (flagship release)
+
+Family **`conicshield-transition-bank-v1`** points at **`host-realistic-20260525`** (`vendor_native`, external export evidence). See [`REFERENCE_AUTHORITY.md`](REFERENCE_AUTHORITY.md).
+
+```bash
+make reference-authority-check    # index + audit --strict + flagship alignment
+make verify-reference-system      # above + governance/bench pytest bundle
+```
+
+Live upstream re-export: `python scripts/refresh_live_upstream_export.py --graph-json <dump.json>` then `make upgrade-host-realistic-vendor`.
+
 ## Standard commands
 
 Tests marked `@pytest.mark.slow` (stress-scale replay, heavy subprocess work) are **excluded** from the default suite by [`pyproject.toml`](../pyproject.toml) (`not slow`), matching [`ci.yml`](../.github/workflows/ci.yml). Run them locally with `python -m pytest tests/ -q -m "slow or not slow"` (see [`DEVENV.md`](DEVENV.md)). Add a scheduled or manual workflow if you want slow tests in CI.
diff --git a/docs/NATIVE_ARM_PUBLISH_CHECKLIST.md b/docs/NATIVE_ARM_PUBLISH_CHECKLIST.md
@@ -2,19 +2,27 @@
 
 ## Canonical command block (licensed host)
 
+**Flagship (in-repo):** `host-realistic-20260525` is the family `current_run_id` with `vendor_native` evidence. Refresh with `make upgrade-host-realistic-vendor` or `--refresh-governance`.
+
 ```bash
 # Export → bundle (real projector + native arm)
+make upgrade-host-realistic-vendor
+
+# Or explicit run_id:
 python scripts/publish_native_arm_bundle.py \
   --export-json benchmarks/external_evidence/offline_graph_export_upstream.json \
-  --run-id <run_id> \
+  --run-id host-realistic-20260525 \
   --force
 
-# Or step-by-step:
+# Step-by-step:
 python scripts/run_host_realistic_publish.py \
-  --export-json <path/to/export.json> \
-  --run-id <run_id> \
+  --export-json benchmarks/external_evidence/offline_graph_export_upstream.json \
+  --run-id host-realistic-20260525 \
   --no-passthrough \
-  --include-native-arm
+  --include-native-arm \
+  --governance-scaffold \
+  --copy-to-published \
+  --refresh-index
 
 python scripts/governed_local_promotion.py all --source benchmarks/runs/<run_id>
 ```
diff --git a/docs/README.md b/docs/README.md
@@ -4,6 +4,7 @@ Policy and runbooks for ConicShield. The repository root [`README.md`](../README
 
 | Document | Purpose |
 |----------|---------|
+| [REFERENCE_AUTHORITY.md](REFERENCE_AUTHORITY.md) | Flagship release, closed loop, maintainer gates |
 | [ARCHITECTURE.md](ARCHITECTURE.md) | System layers and design intent |
 | [ENGINEERING_STATUS.md](ENGINEERING_STATUS.md) | What ships in-tree vs vendor-only |
 | [ROADMAP.md](ROADMAP.md) | External deps, closed milestones, open backlog |
diff --git a/docs/REFERENCE_AUTHORITY.md b/docs/REFERENCE_AUTHORITY.md
@@ -0,0 +1,54 @@
+# Reference authority
+
+ConicShield is maintained as a **governed reference system** for one primary benchmark family (`conicshield-transition-bank-v1`). This page is the single map of what “reference authority” means in practice.
+
+## Flagship release
+
+| Item | Value |
+|------|--------|
+| Family | `conicshield-transition-bank-v1` |
+| `current_run_id` | **`host-realistic-20260525`** |
+| Evidence tier | `vendor_native` (`RUN_PROVENANCE.json`) |
+| Export | [`benchmarks/external_evidence/offline_graph_export_upstream.json`](../benchmarks/external_evidence/offline_graph_export_upstream.json) |
+| Integrity | [`benchmarks/PUBLISHED_RUN_INDEX.json`](../benchmarks/PUBLISHED_RUN_INDEX.json) (schema v2) |
+
+Historical bundles (`wsl-real-*`, `wsl-native-*`) remain in `benchmark_bundle_paths` for comparison.
+
+## Closed loop (in-repo)
+
+```text
+export → transition_bank → reference_run → published_runs/<run_id>/ → parity → finalize → release
+```
+
+Orchestration: [`scripts/run_host_realistic_publish.py`](../scripts/run_host_realistic_publish.py), [`scripts/upgrade_host_realistic_vendor.py`](../scripts/upgrade_host_realistic_vendor.py).
+
+## Maintainer gates
+
+| Gate | Command |
+|------|---------|
+| Reference authority (index + audit + flagship) | `make reference-authority-check` or `python scripts/reference_authority_check.py` |
+| Public verification bundle | `make verify-reference-system` |
+| Strict governance audit | `python -m conicshield.governance.audit_cli --strict` |
+
+## Solver evidence (three paths)
+
+See [`SOLVER_PATHS_AND_BATCHING.md`](SOLVER_PATHS_AND_BATCHING.md): reference CVXPY, sequential native (`batch_size=1`), true compiled batch (`NATIVE_MOREAU_BATCH`).
+
+## Merge trust (binding)
+
+Solver-touching PRs require documented vendor proof (`vendor-ci-moreau` or maintainer attestation). See [`CI_MERGE_GATES.md`](CI_MERGE_GATES.md), [`BRANCH_PROTECTION.md`](BRANCH_PROTECTION.md).
+
+## Optional refresh
+
+| When | Action |
+|------|--------|
+| Live inter-sim dump available | `python scripts/refresh_live_upstream_export.py --graph-json <dump.json>` then `make upgrade-host-realistic-vendor` |
+| Governance only | `python scripts/upgrade_host_realistic_vendor.py --refresh-governance` |
+
+## Explicitly deferred
+
+- Production shield autograd product claims (FD validation only)
+- Second benchmark family until published
+- `progress` / `clearance` constraint semantics
+
+See [`ROADMAP.md`](ROADMAP.md) open backlog.
diff --git a/docs/ROADMAP.md b/docs/ROADMAP.md
@@ -41,7 +41,7 @@ The following were delivered and are kept auditable in Git:
 
 What is **not** closed or only partially addressed:
 
-1. **Live inter-sim re-export** — Replace committed structural export with a fresh dump from a patched `inter-sim-rl` host; update [`EXPORT_PROVENANCE.json`](../benchmarks/external_evidence/EXPORT_PROVENANCE.json); re-run `make upgrade-host-realistic-vendor` when the dump is available.
+1. **Live inter-sim re-export** — `python scripts/refresh_live_upstream_export.py --graph-json <dump.json>` then `make upgrade-host-realistic-vendor` when a patched-host dump is available.
 2. **Shield autograd vs finite differences** — **Decision: defer autograd product claim.** Inter-sim shield **FD** (`tests/vendor/diff/`) and `python scripts/differentiation_check.py --shield-inter-sim` support internal validation only; **autograd / `enable_grad` vs FD** on the production shield QP remains out of scope for external narrative until explicitly promoted.
 3. **Conic suite: failure clustering** — Optional richer **CI artifacts** or dashboards aggregating `conic_suite_report.py` by regime (suite rows already carry case metadata).
 4. **Physical test tree** — Continue incremental moves per [`tests/STRUCTURE.md`](../tests/STRUCTURE.md); no mass rename required for correctness.
diff --git a/scripts/reference_authority_check.py b/scripts/reference_authority_check.py
@@ -0,0 +1,131 @@
+#!/usr/bin/env python3
+"""Single maintainer/CI gate for reference-authority invariants.
+
+Runs published-run index checks, canonical evidence tiers, strict governance audit,
+and flagship release alignment (``host-realistic-20260525`` as family ``current_run_id``).
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import subprocess
+import sys
+from pathlib import Path
+from typing import Any
+
+
+def _repo_root() -> Path:
+    return Path(__file__).resolve().parents[1]
+
+
+def _load_json(path: Path) -> dict[str, Any]:
+    return json.loads(path.read_text(encoding="utf-8"))
+
+
+def _assert_flagship_alignment(*, root: Path) -> dict[str, Any]:
+    family_id = "conicshield-transition-bank-v1"
+    flagship = "host-realistic-20260525"
+    current_path = root / "benchmarks" / "releases" / family_id / "CURRENT.json"
+    current = _load_json(current_path)
+    registry = _load_json(root / "benchmarks" / "registry.json")
+    fam = next(f for f in registry["benchmark_families"] if f["family_id"] == family_id)
+
+    errors: list[str] = []
+    if current.get("current_run_id") != flagship:
+        errors.append(f"CURRENT.current_run_id={current.get('current_run_id')!r} expected {flagship!r}")
+    if fam.get("current_run_id") != flagship:
+        errors.append(f"registry current_run_id={fam.get('current_run_id')!r} expected {flagship!r}")
+    if current.get("state") != "published":
+        errors.append(f"CURRENT.state={current.get('state')!r} expected 'published'")
+
+    gov_path = root / "benchmarks" / "published_runs" / flagship / "governance_status.json"
+    if not gov_path.is_file():
+        errors.append(f"missing {gov_path}")
+    else:
+        gov = _load_json(gov_path)
+        for gate in ("artifact_gate", "parity_gate", "promotion_gate"):
+            if current.get(gate) != gov.get(gate):
+                errors.append(f"CURRENT.{gate}={current.get(gate)!r} != governance {gov.get(gate)!r}")
+        if "shielded-native-moreau" not in (current.get("publishable_arms") or []):
+            errors.append("CURRENT.publishable_arms missing shielded-native-moreau")
+
+    prov_path = root / "benchmarks" / "published_runs" / flagship / "RUN_PROVENANCE.json"
+    if prov_path.is_file():
+        prov = _load_json(prov_path)
+        if prov.get("evidence_tier") != "vendor_native":
+            errors.append(f"flagship evidence_tier={prov.get('evidence_tier')!r} expected vendor_native")
+        if prov.get("projector_mode") != "real_projector":
+            errors.append(f"flagship projector_mode={prov.get('projector_mode')!r} expected real_projector")
+
+    bundle = f"benchmarks/published_runs/{flagship}"
+    if bundle not in (current.get("benchmark_bundle_paths") or []):
+        errors.append(f"{bundle} not in CURRENT.benchmark_bundle_paths")
+
+    if errors:
+        raise AssertionError("; ".join(errors))
+
+    return {
+        "family_id": family_id,
+        "flagship_run_id": flagship,
+        "current_state": current.get("state"),
+        "evidence_tier": _load_json(prov_path).get("evidence_tier") if prov_path.is_file() else None,
+        "publishable_arms": current.get("publishable_arms"),
+    }
+
+
+def main() -> int:
+    p = argparse.ArgumentParser(description=__doc__)
+    p.add_argument("--json", action="store_true", help="Emit machine-readable summary on stdout.")
+    args = p.parse_args()
+    root = _repo_root()
+    py = sys.executable
+    failures: list[str] = []
+
+    steps: list[tuple[str, list[str]]] = [
+        ("published_run_index", [py, str(root / "scripts" / "refresh_published_run_index.py"), "--check"]),
+        ("governance_audit_strict", [py, "-m", "conicshield.governance.audit_cli", "--strict"]),
+    ]
+    for name, cmd in steps:
+        rc = subprocess.call(cmd, cwd=str(root))
+        if rc != 0:
+            failures.append(f"{name} exited {rc}")
+
+    try:
+        from conicshield.published_run_index import assert_canonical_evidence_tiers
+
+        assert_canonical_evidence_tiers(repo_root=root)
+    except Exception as exc:
+        failures.append(f"canonical_evidence_tiers: {exc}")
+
+    flagship_summary: dict[str, Any] | None = None
+    try:
+        flagship_summary = _assert_flagship_alignment(root=root)
+    except Exception as exc:
+        failures.append(f"flagship_alignment: {exc}")
+
+    summary = {
+        "ok": not failures,
+        "failures": failures,
+        "flagship": flagship_summary,
+    }
+    if args.json:
+        print(json.dumps(summary, indent=2))
+    else:
+        if flagship_summary:
+            print(
+                f"Flagship: {flagship_summary['flagship_run_id']} "
+                f"({flagship_summary.get('evidence_tier')}, state={flagship_summary.get('current_state')})"
+            )
+        if failures:
+            print("FAILURES:", file=sys.stderr)
+            for item in failures:
+                print(f"  - {item}", file=sys.stderr)
+        else:
+            print("reference_authority_check: OK")
+
+    return 1 if failures else 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())
diff --git a/scripts/refresh_live_upstream_export.py b/scripts/refresh_live_upstream_export.py
diff --git a/tests/governance/test_reference_authority_invariants.py b/tests/governance/test_reference_authority_invariants.py
