Skip to content

Commit 8d10ac8

Browse files
committed
Add verify_v1_lock script and quick lock target
Auditor-facing v1 lock checks with JSON output; CONTRIBUTING routes consumers to COMMUNITY_LAYER; compare metrics example in public smoke.
1 parent 5b7985f commit 8d10ac8

10 files changed

Lines changed: 138 additions & 8 deletions

CHANGELOG.md

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -2,6 +2,10 @@
22

33
## Reference system (host-realistic flagship)
44

5+
### 2026-05-28 — v1 lock verification script
6+
7+
- `scripts/verify_v1_lock.py` + `make verify-v1-lock-quick`; CONTRIBUTING leads with Community layer for consumers.
8+
59
### 2026-05-28 — Community onboarding hub and read-only verify gate
610

711
- `docs/COMMUNITY_LAYER.md`, `docs/PUBLISHED_RUNS_API.md`; `community-verify` no longer mutates bundles in CI.

CONTRIBUTING.md

Lines changed: 4 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -2,7 +2,9 @@
22

33
Thank you for contributing. This repository separates **public structural CI** from **vendor Moreau validation** by design.
44

5-
**Audience guides:** [Researcher](docs/QUICKSTART_RESEARCHER.md) · [Integrator](docs/QUICKSTART_INTEGRATOR.md) · [Maintainer](docs/QUICKSTART_MAINTAINER.md) · [Public claims](docs/PUBLIC_CLAIMS.md) · [Examples](examples/README.md)
5+
**Using the repo (not changing it)?** Start at [Community layer](docs/COMMUNITY_LAYER.md) — quickstarts, published-run API, and runnable examples.
6+
7+
**Changing the repo?** Continue below. Audience guides: [Researcher](docs/QUICKSTART_RESEARCHER.md) · [Integrator](docs/QUICKSTART_INTEGRATOR.md) · [Maintainer](docs/QUICKSTART_MAINTAINER.md) · [Public claims](docs/PUBLIC_CLAIMS.md)
68

79
## Before you open a PR
810

@@ -20,7 +22,7 @@ These checks run on every PR to `main` and should be green:
2022
| `quality` | Lint, types, default pytest, verification scripts |
2123
| `conic-trusted-shape` | CLARABEL/SCS structural conic correctness (no vendor secrets) |
2224
| `governance-audit` | Published-run index integrity, governance audit CLI, publish rehearsal |
23-
| `reference-authority` | `verify-reference-system`, batch viability, published bundle profile |
25+
| `reference-authority` | `verify-reference-system`, `community-verify`, batch viability, bundle profile |
2426

2527
## Path-filtered checks
2628

Makefile

Lines changed: 5 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -26,7 +26,7 @@ else
2626
endif
2727
endif
2828

29-
.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 check-batch-acceptance check-batch-throughput-advisory validate-published-bundle-profile sync-community-metadata sync-published-run-readmes sync-published-readmes finalize-community-dataset community-verify check-reference-refresh-cadence check-flagship-full-refresh-cadence verify-v1-lock verify-reference-system reference-authority-check reference-authority-snapshot reference-system-status reference-system-status-check capture-inter-sim-graph refresh-live-upstream-export refresh-live-upstream-export-live host-realistic-refresh-cycle host-realistic-refresh-cycle-licensed host-realistic-refresh-milestone sync-published-readmes
29+
.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 check-batch-acceptance check-batch-throughput-advisory validate-published-bundle-profile sync-community-metadata sync-published-run-readmes sync-published-readmes finalize-community-dataset community-verify check-reference-refresh-cadence check-flagship-full-refresh-cadence verify-v1-lock verify-v1-lock-quick verify-reference-system reference-authority-check reference-authority-snapshot reference-system-status reference-system-status-check capture-inter-sim-graph refresh-live-upstream-export refresh-live-upstream-export-live host-realistic-refresh-cycle host-realistic-refresh-cycle-licensed host-realistic-refresh-milestone sync-published-readmes
3030

3131
test:
3232
$(PYTHON) -m pytest -q
@@ -124,6 +124,10 @@ refresh-live-upstream-export-live: capture-inter-sim-graph
124124

125125
verify-v1-lock: verify-reference-system community-verify reference-system-status-check
126126
$(PYTHON) scripts/refresh_published_run_index.py --check
127+
$(PYTHON) scripts/verify_v1_lock.py
128+
129+
verify-v1-lock-quick:
130+
$(PYTHON) scripts/verify_v1_lock.py
127131

128132
sync-community-metadata:
129133
$(PYTHON) scripts/sync_community_metadata.py

benchmarks/reports/reference_system_status.json

Lines changed: 5 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
{
22
"schema_version": "conicshield_reference_system_status/v1",
3-
"generated_at_utc": "2026-05-28T18:10:04Z",
3+
"generated_at_utc": "2026-05-28T18:14:08Z",
44
"flagship_run_id": "host-realistic-20260525",
55
"family_id": "conicshield-transition-bank-v1",
66
"reference_authority_aligned": true,
@@ -10,7 +10,7 @@
1010
"refresh_count": 4,
1111
"full_cycle_refresh_count": 1,
1212
"last_full_refresh_at_utc": "2026-05-28T17:00:56Z",
13-
"cadence_age_days": 0.04801319055555556,
13+
"cadence_age_days": 0.05083969313657408,
1414
"cadence_policy_ok": true,
1515
"full_refresh_cadence_ok": true,
1616
"batch_story": "throughput_win",
@@ -44,6 +44,8 @@
4444
"docs/HOST_REALISTIC_CADENCE_POLICY.md",
4545
"docs/PUBLISHED_RUN_INDEX_FOR_CONSUMERS.md",
4646
"docs/PUBLIC_CLAIMS.md",
47-
"docs/QUICKSTART_RESEARCHER.md"
47+
"docs/QUICKSTART_RESEARCHER.md",
48+
"docs/COMMUNITY_LAYER.md",
49+
"docs/PUBLISHED_RUNS_API.md"
4850
]
4951
}

docs/COMMUNITY_LAYER.md

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -42,6 +42,7 @@ Each bundle ships **`COMMUNITY_METADATA.json`** (scope, uses, limitations) — r
4242
|--------|----------|
4343
| [verify_published_run_index.py](../examples/verify_published_run_index.py) | Researcher |
4444
| [inspect_flagship_bundle.py](../examples/inspect_flagship_bundle.py) | Researcher |
45+
| [compare_reference_vs_native_metrics.py](../examples/compare_reference_vs_native_metrics.py) | Researcher |
4546
| [minimal_reference_projection.py](../examples/minimal_reference_projection.py) | Integrator |
4647
| [true_batched_compiled_projection.py](../examples/true_batched_compiled_projection.py) | Integrator (vendor) |
4748

docs/V1_LOCK_CHECKLIST.md

Lines changed: 4 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -5,10 +5,12 @@ Use this before declaring the **host-realistic flagship** reference system locke
55
## 1. Local verification (any maintainer machine)
66

77
```bash
8-
make verify-v1-lock
8+
make verify-v1-lock # full gate (includes governance pytest subset)
9+
make verify-v1-lock-quick # fast auditor summary (no verify-reference-system)
10+
python scripts/verify_v1_lock.py --json
911
```
1012

11-
Equivalent to: `verify-reference-system`, `community-verify` (API + public examples, read-only), index `--check`, and reference status `--check`.
13+
Full target: `verify-reference-system`, `community-verify`, index/status `--check`, and `verify_v1_lock.py` report.
1214

1315
## 2. Flagship cadence
1416

scripts/generate_reference_system_status.py

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -119,6 +119,8 @@ def build_reference_system_status(*, repo_root: Path) -> dict[str, Any]:
119119
"docs/PUBLISHED_RUN_INDEX_FOR_CONSUMERS.md",
120120
"docs/PUBLIC_CLAIMS.md",
121121
"docs/QUICKSTART_RESEARCHER.md",
122+
"docs/COMMUNITY_LAYER.md",
123+
"docs/PUBLISHED_RUNS_API.md",
122124
],
123125
}
124126

scripts/verify_v1_lock.py

Lines changed: 92 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,92 @@
1+
#!/usr/bin/env python3
2+
"""Run v1 reference-system lock checks and print an auditor-facing summary."""
3+
4+
from __future__ import annotations
5+
6+
import argparse
7+
import json
8+
import subprocess
9+
import sys
10+
from pathlib import Path
11+
12+
13+
def _repo_root() -> Path:
14+
return Path(__file__).resolve().parents[1]
15+
16+
17+
def _run(cmd: list[str], *, cwd: Path, label: str) -> tuple[bool, str]:
18+
proc = subprocess.run(cmd, cwd=str(cwd), capture_output=True, text=True)
19+
ok = proc.returncode == 0
20+
detail = (proc.stdout or "") + (proc.stderr or "")
21+
if not detail.strip():
22+
detail = f"exit {proc.returncode}"
23+
return ok, f"{label}: {'OK' if ok else 'FAIL'}{detail.strip()[:240]}"
24+
25+
26+
def main() -> int:
27+
p = argparse.ArgumentParser(description=__doc__)
28+
p.add_argument(
29+
"--full",
30+
action="store_true",
31+
help="Also run make verify-reference-system (slow; same as verify-v1-lock).",
32+
)
33+
p.add_argument(
34+
"--json",
35+
action="store_true",
36+
help="Print machine-readable summary on stdout after human report.",
37+
)
38+
args = p.parse_args()
39+
root = _repo_root()
40+
py = sys.executable
41+
results: list[dict[str, object]] = []
42+
43+
steps: list[tuple[str, list[str]]] = [
44+
("index_integrity", [py, str(root / "scripts" / "refresh_published_run_index.py"), "--check"]),
45+
("reference_system_status", [py, str(root / "scripts" / "generate_reference_system_status.py"), "--check"]),
46+
("export_cadence", [py, str(root / "scripts" / "check_reference_refresh_cadence.py"), "--max-days", "35"]),
47+
("full_refresh_cadence", [py, str(root / "scripts" / "check_flagship_full_refresh_cadence.py"), "--max-days", "35"]),
48+
("bundle_profile", [py, str(root / "scripts" / "validate_published_bundle_profile.py")]),
49+
(
50+
"community_verify",
51+
[
52+
py,
53+
"-m",
54+
"pytest",
55+
"tests/test_published_runs_api.py",
56+
"tests/test_published_runs_cli.py",
57+
"tests/examples/test_public_examples_smoke.py",
58+
"-q",
59+
"--tb=line",
60+
],
61+
),
62+
]
63+
for name, cmd in steps:
64+
ok, msg = _run(cmd, cwd=root, label=name)
65+
results.append({"check": name, "ok": ok})
66+
print(msg)
67+
68+
if args.full:
69+
ok, msg = _run(["make", "verify-reference-system"], cwd=root, label="verify_reference_system")
70+
results.append({"check": "verify_reference_system", "ok": ok})
71+
print(msg)
72+
else:
73+
print("skip: verify-reference-system (pass --full or run make verify-v1-lock)")
74+
75+
status_path = root / "benchmarks" / "reports" / "reference_system_status.json"
76+
if status_path.is_file():
77+
status = json.loads(status_path.read_text(encoding="utf-8"))
78+
print("\nflagship:", status.get("flagship_run_id"))
79+
print("authority_aligned:", status.get("reference_authority_aligned"))
80+
print("full_refresh_cadence_ok:", status.get("full_refresh_cadence_ok"))
81+
community = status.get("community_dataset") or {}
82+
print("onboarding:", community.get("onboarding_doc"))
83+
84+
all_ok = all(bool(r["ok"]) for r in results)
85+
if args.json:
86+
print(json.dumps({"v1_lock_checks": results, "all_ok": all_ok}, indent=2))
87+
print("\n" + ("v1 lock checks PASSED" if all_ok else "v1 lock checks FAILED"))
88+
return 0 if all_ok else 1
89+
90+
91+
if __name__ == "__main__":
92+
raise SystemExit(main())

tests/examples/test_public_examples_smoke.py

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -32,3 +32,7 @@ def test_load_flagship_run_example() -> None:
3232

3333
def test_minimal_reference_projection_example() -> None:
3434
_run("minimal_reference_projection.py")
35+
36+
37+
def test_compare_reference_vs_native_metrics_example() -> None:
38+
_run("compare_reference_vs_native_metrics.py")
Lines changed: 17 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,17 @@
1+
from __future__ import annotations
2+
3+
import subprocess
4+
import sys
5+
from pathlib import Path
6+
7+
8+
def test_verify_v1_lock_quick_exits_zero() -> None:
9+
root = Path(__file__).resolve().parents[2]
10+
proc = subprocess.run(
11+
[sys.executable, str(root / "scripts" / "verify_v1_lock.py")],
12+
cwd=str(root),
13+
capture_output=True,
14+
text=True,
15+
)
16+
assert proc.returncode == 0, proc.stdout + proc.stderr
17+
assert "v1 lock checks PASSED" in proc.stdout

0 commit comments

Comments
 (0)