diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index bfb48a4f0..fd010e2a9 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -73,6 +73,8 @@ jobs: run: python tools/mirror_quotes_check.py - name: Mirror lane index is generated from the manifests, not typed run: python tools/mirrors_index_check.py + - name: Certificate source bindings still match the tree, and the index names them + run: python tools/pinned_sources_check.py - name: Drive source map is queryable run: python tools/drive_index.py stats - name: Scoped Drive coverage and exact packed-byte reconstruction diff --git a/CLAUDE.md b/CLAUDE.md index 742e7882a..2014f0730 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -35,6 +35,19 @@ met. A computational test establishes what it actually checks. Resolve real correctness failures and reconcile obsolete procedural checks rather than hiding either. Neither this delegation nor a merge proves a theorem. +## Before editing a file: it may be bound by a certificate + +Eight candidate records under `research/` bind repository content by SHA-256 as +*source identity*, and the replay checkers that consume them refuse the tree +when a byte moves. [`research/PINNED_SOURCES.md`](research/PINNED_SOURCES.md) +lists all of it -- 34 files and 6 archive members, generated from the +certificates and verified in CI by `tools/pinned_sources_check.py`. + +Three of the bound files are checkers in `tools/` and one is a document in +`docs/`, so this is not deducible from where a file lives. The remedy for a +deliberate change is a re-pin on the lane that owns the certificate. Never edit +an expected digest to match bytes you changed. + ## Technical navigation Start with [README.md](README.md), [RESEARCH_MAP](docs/RESEARCH_MAP.md) and diff --git a/research/PINNED_SOURCES.md b/research/PINNED_SOURCES.md new file mode 100644 index 000000000..c9f8065a8 --- /dev/null +++ b/research/PINNED_SOURCES.md @@ -0,0 +1,106 @@ + + +# Repository content a certificate binds by digest + +Several candidate records under `research/` name repository content by SHA-256 +as **source identity** — "this result was produced against these exact bytes". +Editing one of these files makes the replay checkers that consume the +certificate refuse the tree, by design. + +This page exists because nothing else in the repository said which files those +are. The rejection a replay prints names the dependency and not the certificate, +so the only way to learn a binding was to break it — and three separate changes +did, in four days. **Two of the files below are checkers in `tools/` and one is +a document in `docs/`.** + +Before editing anything in this table, read +[`tools/pinned_sources_check.py`](../tools/pinned_sources_check.py). The remedy +for a deliberate change is a re-pin on the lane that owns the certificate, never +a quiet edit to the expected digest. + +**What a pin is not.** It is an identity statement and nothing more. It says +nothing about whether the certificate is correct, whether its mathematics holds, +or whether the file is current or authoritative. A green run means the bytes +still match. No claim, premise, obligation or gate is discharged by anything on +this page. + + +| file | bytes | SHA-256 | pinned by | +|---|---:|---|---| +| `docs/HERMITE_GAUSSIAN_ENVELOPE.md` | — | `8c0dccdfd177b7ae…` | hermite_gaussian_20260919.json | +| `drive/inventory.jsonl` | 2807455 | `48766f1807efaba6…` | inner_wedge_20260920_v1.json | +| `drive/mirrors/02_RESEARCH_CARRY_FORWARD_CANON/LPW — RAW ARCHIVE INTAKE R05/03_RAYLEIGH_REPAIR_AND_INTERVAL_CERTIFICATE.md` | 9628 | `840c75a7825c67b8…` | candidate.json | +| `drive/mirrors/02_RESEARCH_CARRY_FORWARD_CANON/LPW — RAW ARCHIVE INTAKE R05/checks/interval_repair.py` | 6843 | `b37150f0eb79ff5d…` | candidate.json | +| `drive/mirrors/02_RESEARCH_CARRY_FORWARD_CANON/LPW — RAW ARCHIVE INTAKE R05/raw_reports/lpw_constant.py` | 25380 | `e258322cfbb71dbb…` | candidate.json | +| `drive/mirrors/2026-09-17_RN5_MOMENT_REPAIR_AND_REVIEW_ERRATUM/RN5_NEAR_MOMENT_REPAIR.md` | 13725 | `ac89f60b8206bfe0…` | inner_wedge_20260920_v1.json, side24_density_20260920_v1.json, side24_point_20260920_v1.json, side24_spatial_20260920_v1.json | +| `drive/mirrors/2026-09-17_RN5_MOMENT_REPAIR_AND_REVIEW_ERRATUM/RN5_REPAIR_AND_ERRATUM_BUNDLE.zip` | 140170 | `28c1c385406452a7…` | inner_wedge_20260920_v1.json, side24_density_20260920_v1.json, side24_point_20260920_v1.json, side24_spatial_20260920_v1.json | +| `drive/mirrors/2026-09-17_RN5_MOMENT_REPAIR_AND_REVIEW_ERRATUM/RN5_REPAIR_AND_ERRATUM_BUNDLE.zip::closure_round2/rn_field.py` | 16701 | `d9167ae821684f71…` | side24_density_20260920_v1.json, side24_point_20260920_v1.json, side24_spatial_20260920_v1.json | +| `drive/mirrors/2026-09-17_RN5_MOMENT_REPAIR_AND_REVIEW_ERRATUM/RN5_REPAIR_AND_ERRATUM_BUNDLE.zip::intake/rn_source/K3_SIDE24_LB/UPPER2D/H3_closure/H3_RUNG_FLOOR.md` | 7003 | `6347275d86c56842…` | side24_density_20260920_v1.json, side24_spatial_20260920_v1.json | +| `drive/mirrors/2026-09-17_RN5_MOMENT_REPAIR_AND_REVIEW_ERRATUM/RN5_REPAIR_AND_ERRATUM_BUNDLE.zip::round5/intake/rn.txt` | 12956 | `0c9446b7cb49e6e1…` | side24_spatial_20260920_v1.json | +| `drive/mirrors/2026-09-17_RN5_MOMENT_REPAIR_AND_REVIEW_ERRATUM/RN5_REPAIR_AND_ERRATUM_BUNDLE.zip::round5/near_moments.py` | 8673 | `03c6e35c426eee8e…` | side24_density_20260920_v1.json, side24_point_20260920_v1.json, side24_spatial_20260920_v1.json | +| `drive/mirrors/2026-09-17_RN5_MOMENT_REPAIR_AND_REVIEW_ERRATUM/RN5_REPAIR_AND_ERRATUM_BUNDLE.zip::round5/verify_round5.py` | 5074 | `614daf280f503775…` | side24_density_20260920_v1.json, side24_point_20260920_v1.json, side24_spatial_20260920_v1.json | +| `drive/source_map/Payloads.csv` | 2957503 | `1b1b94a784ebc87c…` | inner_wedge_20260920_v1.json | +| `engine/operations/__init__.py` | 343 | `818cb3d139128e78…` | DEPENDENCIES.json, candidate.json, inner_wedge_20260920_v1.json | +| `engine/operations/rn_applicability.py` | 4129 | `f28a93613d0995b8…` | DEPENDENCIES.json, candidate.json, inner_wedge_20260920_v1.json | +| `engine/operations/rn_family_applicability.py` | 2241 | `3a55870d2129a3b4…` | DEPENDENCIES.json, candidate.json, inner_wedge_20260920_v1.json | +| `engine/rn_engine/frozen/K3_SIDE24_LB/UPPER2D/D3_percolation/d3_rn_unif.py` | — | `85d7725fab42eeb0…` | hermite_gaussian_20260919.json | +| `engine/rn_engine/frozen/K3_SIDE24_LB/UPPER2D/H2_foundations/pin_transform.py` | 17623 | `c6988ac7fcfa32dc…` | side24_density_20260920_v1.json, side24_spatial_20260920_v1.json | +| `quarantine/EXCLUSIONS.json` | 19555 | `8a5a89012dcd0fec…` | inner_wedge_20260920_v1.json | +| `research/bands/__init__.py` | 4171 | `d9fb9686306523ae…` | DEPENDENCIES.json, candidate.json, inner_wedge_20260920_v1.json | +| `research/bands/falsifier.py` | 13281 | `0d1b4abf48c4f5b5…` | DEPENDENCIES.json, candidate.json, inner_wedge_20260920_v1.json | +| `research/bands/hermite_gaussian.py` | — | `f37e4657aceb95ab…` | DEPENDENCIES.json, candidate.json, hermite_gaussian_20260919.json, inner_wedge_20260920_v1.json | +| `research/bands/ladder.py` | 26286 | `9ea576708e146aa5…` | DEPENDENCIES.json, candidate.json, inner_wedge_20260920_v1.json | +| `research/bands/lattice.py` | — | `ee7144a98a689094…` | DEPENDENCIES.json, candidate.json, hermite_gaussian_20260919.json, inner_wedge_20260920_v1.json | +| `research/campaigns/h3_rn_n6_20260920_v1.zip` | 571735 | `73b9e63800f77c67…` | inner_wedge_20260920_v1.json | +| `research/campaigns/h3_rn_n6_20260920_v1.zip::rn_n6/side24_taylor.py` | 23681 | `32c4933c2ab543f7…` | inner_wedge_20260920_v1.json | +| `research/cover/__init__.py` | 4113 | `5f3afc075dc40e51…` | inner_wedge_20260920_v1.json | +| `research/cover/driver.py` | 21760 | `7daaced91c179a75…` | inner_wedge_20260920_v1.json | +| `research/cover/ledger.py` | 37974 | `58ebe18fbc3fc44e…` | inner_wedge_20260920_v1.json | +| `research/cover/regions.py` | 23358 | `bf2d981772f3e35e…` | inner_wedge_20260920_v1.json | +| `research/interval/__init__.py` | 2371 | `a6a185d24615288d…` | DEPENDENCIES.json, candidate.json, inner_wedge_20260920_v1.json | +| `research/interval/core.py` | — | `3f9e699cdb215957…` | DEPENDENCIES.json, candidate.json, hermite_gaussian_20260919.json, inner_wedge_20260920_v1.json | +| `research/interval/transcendental.py` | — | `7db4b5a6d868a731…` | DEPENDENCIES.json, candidate.json, hermite_gaussian_20260919.json, inner_wedge_20260920_v1.json | +| `research/rn/certificate.py` | 16550 | `ddbbb25270c01c13…` | inner_wedge_20260920_v1.json | +| `research/rn/conditioning.py` | — | `1d3ca89d9bc2b2ea…` | candidate.json, inner_wedge_20260920_v1.json | +| `research/rn/gaussian_families.py` | 5348 | `ecd1958dd9e02f82…` | DEPENDENCIES.json, candidate.json, inner_wedge_20260920_v1.json | +| `research/rn/gaussian_moments.py` | 8133 | `d545e4d31ef87605…` | DEPENDENCIES.json, candidate.json, inner_wedge_20260920_v1.json | +| `research/rn/side24.py` | 11239 | `dd6b5aa73442c8d5…` | DEPENDENCIES.json, candidate.json, inner_wedge_20260920_v1.json | +| `research/rn/side24_cell.py` | 13149 | `38cf5632f4689943…` | inner_wedge_20260920_v1.json | +| `research/rn/side24_density.py` | 8289 | `3ad0b3b6fc3a5124…` | inner_wedge_20260920_v1.json | +| `tools/drive_coverage.py` | — | `98b33fe9f97fe7a3…` | candidate.json | +| `tools/hermite_envelope_report.py` | — | `7a60f412a008e3bc…` | hermite_gaussian_20260919.json | +| `tools/manifest_integrity_check.py` | — | `8b30cf5768318754…` | candidate.json | + +37 files and 6 members sealed inside a ZIP carrier, bound at 128 sites across 10 certificates. + +## Every container of pins, and what its keys are relative to + +A container whose keys are **repository** paths is verified above. One +marked **other** keys its entries inside a bundle the certificate +carries, so resolving them here would compare the wrong files; those are +counted and left alone. The classification is read off the evidence, not +a list — see `classify()` — and it is recorded here so that a container +flipping between the two fails this index's drift comparison by name. + +| certificate | container | keys | keys are | +|---|---|---:|---| +| `research/bands/candidates/hermite_gaussian_20260919.json` | `inputs` | 7 | repository | +| `research/formal/candidates/LEAN_RECOVERY_VERIFICATION_20260920_v1.manifest.json` | `members` | 30 | other | +| `research/parallel/c2/DEPENDENCIES.json` | `repository_python_imports[]` | 14 | repository | +| `research/parallel/c2/candidate.json` | `dependencies_sha256` | 4 | repository | +| `research/parallel/c2/candidate.json` | `source_sha256` | 2 | other | +| `research/parallel/h3/candidate.json` | `payload/computational_sources` | 17 | repository | +| `research/parallel/h3/candidate.json` | `payload/source` | 3 | other | +| `research/parallel/h3/candidate.json` | `payload/source/rn5/member_sha256` | 3 | other | +| `research/parallel/lpw/candidate.json` | `sources[]` | 6 | repository | +| `research/rn/candidates/inner_wedge_20260920_v1.json` | `auxiliary/pieces[]/source_binding/member_sha256` | 3 | other | +| `research/rn/candidates/inner_wedge_20260920_v1.json` | `majorant/source_binding/archives[]` | 2 | repository | +| `research/rn/candidates/inner_wedge_20260920_v1.json` | `majorant/source_binding/archives[]/members[]` | 9 | other | +| `research/rn/candidates/inner_wedge_20260920_v1.json` | `majorant/source_binding/authenticated_identities` | 29 | repository | +| `research/rn/candidates/inner_wedge_20260920_v1.json` | `source_identities` | 29 | repository | +| `research/rn/candidates/side24_density_20260920_v1.json` | `density_window/source_binding/member_sha256` | 3 | other | +| `research/rn/candidates/side24_density_20260920_v1.json` | `sources` | 7 | repository | +| `research/rn/candidates/side24_point_20260920_v1.json` | `sources` | 5 | repository | +| `research/rn/candidates/side24_spatial_20260920_v1.json` | `attempts[]/proof/source_binding/member_sha256` | 3 | other | +| `research/rn/candidates/side24_spatial_20260920_v1.json` | `sources` | 8 | repository | diff --git a/tests/test_pinned_sources.py b/tests/test_pinned_sources.py new file mode 100644 index 000000000..4994f454f --- /dev/null +++ b/tests/test_pinned_sources.py @@ -0,0 +1,368 @@ +"""Negative controls for tools/pinned_sources_check.py. + +The tool exists because a certificate's byte bindings were invisible until you +broke one. Its own failure mode is the mirror image: an inventory that looks +complete while silently skipping a container, a resolution rule that compares +the wrong file, or a green run that compared nothing. Every control below runs +the tool through its CLI against a synthetic root, so a path bound at import +time cannot quietly re-check the real repository. +""" +from __future__ import annotations + +import hashlib +import json +import os +import re +import subprocess +import sys +import zipfile + +ROOT = os.path.dirname(os.path.dirname(os.path.abspath(__file__))) +TOOL = os.path.join(ROOT, "tools", "pinned_sources_check.py") + +INDEX_REL = os.path.join("research", "PINNED_SOURCES.md") + + +def run(root, *extra): + return subprocess.run( + [sys.executable, TOOL, "--root", str(root)] + list(extra), + capture_output=True, text=True, cwd=ROOT) + + +def sha(raw): + return hashlib.sha256(raw).hexdigest() + + +def build(tmp_path, sources, certificate, cert_rel="research/c/candidate.json"): + """Lay out a synthetic tree: `sources` is {path: bytes}, plus one certificate.""" + for rel, raw in sources.items(): + p = tmp_path / rel + p.parent.mkdir(parents=True, exist_ok=True) + p.write_bytes(raw) + cert = tmp_path / cert_rel + cert.parent.mkdir(parents=True, exist_ok=True) + cert.write_text(json.dumps(certificate, indent=1), encoding="utf-8") + return tmp_path + + +def pinned(raw): + return {"bytes": len(raw), "sha256": sha(raw)} + + +BODY = b"def f():\n return 1\n" +OTHER = b"def f():\n return 2\n" + + +def simple(tmp_path, body=BODY): + return build(tmp_path, {"lib/mod.py": body}, + {"source_identities": {"lib/mod.py": pinned(body)}}) + + +# --- the inventory is generated, and drift fails -------------------------- + +def test_a_matching_pin_passes_and_writes_the_index(tmp_path): + root = simple(tmp_path) + assert run(root, "--write").returncode == 0 + out = run(root) + assert out.returncode == 0, out.stdout + assert "pinned_files=1" in out.stdout + assert "digest_matches=1" in out.stdout + assert "problems=0" in out.stdout + assert "lib/mod.py" in (root / INDEX_REL).read_text(encoding="utf-8") + + +def test_a_missing_index_is_refused(tmp_path): + out = run(simple(tmp_path)) + assert out.returncode != 0, out.stdout + assert "is missing; run --write" in out.stdout + + +def test_an_edited_index_is_refused_and_the_row_is_named(tmp_path): + root = simple(tmp_path) + run(root, "--write") + index = root / INDEX_REL + index.write_text(index.read_text(encoding="utf-8").replace("lib/mod.py", "lib/other.py"), + encoding="utf-8") + out = run(root) + assert out.returncode != 0, out.stdout + assert "the index says" in out.stdout and "lib/other.py" in out.stdout + assert "the certificates say" in out.stdout and "lib/mod.py" in out.stdout + assert "regenerate it with --write rather than editing it" in out.stdout + + +# --- the binding itself --------------------------------------------------- + +def test_a_changed_pinned_file_is_reported_with_the_remedy(tmp_path): + """The whole point: say it once, here, instead of four replay rejections.""" + root = simple(tmp_path) + run(root, "--write") + (root / "lib/mod.py").write_bytes(OTHER) + out = run(root) + assert out.returncode != 0, out.stdout + assert "lib/mod.py: pinned at" in out.stdout + assert "and this tree holds" in out.stdout + assert "re-pin on the lane that owns the certificate" in out.stdout + assert "never editing the expected digest to match" in out.stdout + + +def test_a_deleted_pinned_file_is_reported(tmp_path): + root = simple(tmp_path) + run(root, "--write") + os.remove(root / "lib/mod.py") + out = run(root) + assert out.returncode != 0, out.stdout + assert "this tree holds nothing there" in out.stdout + + +def test_a_digest_that_matches_with_a_wrong_byte_count_is_refused(tmp_path): + """An internally inconsistent certificate, which no replay would catch as one.""" + root = build(tmp_path, {"lib/mod.py": BODY}, + {"source_identities": {"lib/mod.py": + {"bytes": len(BODY) + 1, "sha256": sha(BODY)}}}) + out = run(root, "--write") + assert out.returncode == 0 + out = run(root) + assert out.returncode != 0, out.stdout + assert "the digest matches and the byte count does not" in out.stdout + + +def test_the_bare_digest_shape_is_recognised(tmp_path): + """`path -> ""`, which is how the H3 candidate binds ladder.py. + + A tool that knows only the {bytes, sha256} shape reports zero bindings here + and reads as a clean run. + """ + root = build(tmp_path, {"lib/mod.py": BODY}, + {"payload": {"computational_sources": {"lib/mod.py": sha(BODY)}}}) + run(root, "--write") + assert "pinned_files=1" in run(root).stdout + (root / "lib/mod.py").write_bytes(OTHER) + out = run(root) + assert out.returncode != 0, out.stdout + assert "lib/mod.py: pinned at" in out.stdout + + +def test_list_record_siblings_are_not_dropped(tmp_path): + """`[{path, bytes, sha256}, ...]` names the file in a sibling field. + + The LPW candidate binds its sources this way, and so does + `DEPENDENCIES.json`. A walker that only understands map keys, bare + digests and archive members drops every record in the list. With no + other shape present, that drop reads as a clean run that compared nothing. + """ + root = build(tmp_path, + {"lib/mod.py": BODY, "lib/other.py": OTHER}, + {"sources": [ + {"path": "lib/mod.py", "bytes": len(BODY), "sha256": sha(BODY), + "extraction": "complete local dependency bytes"}, + {"path": "lib/other.py", "bytes": len(OTHER), "sha256": sha(OTHER), + "module": "lib.other"}, + ]}) + written = run(root, "--write") + assert written.returncode == 0, written.stdout + out = run(root) + assert out.returncode == 0, out.stdout + assert "pinned_files=2" in out.stdout + assert "digest_matches=2" in out.stdout + assert "certificates=1" in out.stdout + index = (root / INDEX_REL).read_text(encoding="utf-8") + assert "`lib/mod.py`" in index + assert "`lib/other.py`" in index + assert "`sources[]`" in index + (root / "lib/mod.py").write_bytes(b"changed\n") + out = run(root) + assert out.returncode != 0, out.stdout + assert "lib/mod.py: pinned at" in out.stdout + assert "lib/other.py: pinned at" not in out.stdout + + +# --- resolution: the defect this repository already fixed once ------------ + +def test_a_bundle_relative_container_is_not_compared_at_the_root(tmp_path): + """The `README.md` case. + + A bundle member that shares a name with a repository file must not be + compared against it. Resolving by last component is exactly the seal-checker + bug this repository already found; a tool that repeats it reports a mismatch + on a file the certificate never named. + """ + root = build(tmp_path, {"README.md": b"the repository's own readme\n"}, + {"members": {"README.md": pinned(b"a different readme, inside a bundle\n"), + "verification/build.log": pinned(b"log\n")}}) + out = run(root, "--write") + assert out.returncode == 0, out.stdout + out = run(root) + assert "README.md: pinned at" not in out.stdout + assert "keys_not_repository_relative=2" in out.stdout + # and with nothing compared, the run is refused rather than read as clean + assert "VACUOUS RUN" in out.stdout + assert out.returncode != 0 + + +def test_a_repository_container_is_still_compared_when_a_bundle_one_is_present(tmp_path): + root = build(tmp_path, {"README.md": b"repo readme\n", "lib/mod.py": BODY}, + {"members": {"README.md": pinned(b"bundle readme\n")}, + "source_identities": {"lib/mod.py": pinned(BODY)}}) + run(root, "--write") + out = run(root) + assert out.returncode == 0, out.stdout + assert "pinned_files=1" in out.stdout + assert "keys_not_repository_relative=1" in out.stdout + + +def test_a_container_whose_every_pin_drifted_is_still_compared(tmp_path): + """The hole the evidence-based rule leaves on its own, closed by the index. + + `classify()` calls a container repository-relative when at least one key + resolves to the bytes it pins. If *every* pin drifts, that evidence is gone + and a self-deriving tool would reclassify the container as bundle-relative, + stop comparing it, and report a clean run over two changed files. So the + index records the classification and later runs use what was recorded. + """ + root = build(tmp_path, {"lib/a.py": BODY, "lib/b.py": BODY}, + {"source_identities": {"lib/a.py": pinned(BODY), + "lib/b.py": pinned(BODY)}}) + run(root, "--write") + (root / "lib/a.py").write_bytes(OTHER) + (root / "lib/b.py").write_bytes(OTHER) + out = run(root) + assert out.returncode != 0, out.stdout + assert "lib/a.py: pinned at" in out.stdout + assert "lib/b.py: pinned at" in out.stdout + assert "records 'source_identities' as repository and the evidence now reads other" in out.stdout + assert "VACUOUS RUN" not in out.stdout + + +def test_a_new_container_must_be_declared_by_regenerating(tmp_path): + """A certificate that grows a binding surface cannot add it in silence.""" + root = build(tmp_path, {"lib/a.py": BODY}, + {"source_identities": {"lib/a.py": pinned(BODY)}}) + run(root, "--write") + cert = root / "research/c/candidate.json" + doc = json.loads(cert.read_text(encoding="utf-8")) + doc["payload"] = {"computational_sources": {"lib/a.py": sha(BODY)}} + cert.write_text(json.dumps(doc, indent=1), encoding="utf-8") + out = run(root) + assert out.returncode != 0, out.stdout + assert "does not record that container" in out.stdout + assert "regenerate the index with --write" in out.stdout + + +# --- content sealed inside a carrier -------------------------------------- + +def member_zip(path, members): + with zipfile.ZipFile(path, "w") as z: + for name, raw in members.items(): + z.writestr(name, raw) + return path.read_bytes() + + +def test_an_archive_member_is_resolved_inside_its_carrier(tmp_path): + (tmp_path / "carriers").mkdir(parents=True) + arc = tmp_path / "carriers" / "bundle.zip" + member_zip(arc, {"inner/mod.py": BODY}) + root = build(tmp_path, {}, + {"source_identities": {"carriers/bundle.zip::inner/mod.py": pinned(BODY)}}) + run(root, "--write") + out = run(root) + assert out.returncode == 0, out.stdout + assert "pinned_archive_members=1" in out.stdout + assert "pinned_files=0" in out.stdout + + member_zip(arc, {"inner/mod.py": OTHER}) + out = run(root) + assert out.returncode != 0, out.stdout + assert "carriers/bundle.zip::inner/mod.py: pinned at" in out.stdout + + +# --- the vacuity floor ---------------------------------------------------- + +def test_a_run_with_no_certificates_is_refused(tmp_path): + (tmp_path / "research").mkdir(parents=True) + out = run(tmp_path, "--write") + assert out.returncode == 0 + out = run(tmp_path) + assert out.returncode != 0, out.stdout + assert "VACUOUS RUN" in out.stdout + assert "certificates=0" in out.stdout + + +def test_a_certificate_with_no_pins_does_not_count_as_one(tmp_path): + root = build(tmp_path, {}, {"notes": "no digests here"}) + out = run(root) + assert out.returncode != 0, out.stdout + assert "certificates=0" in out.stdout + assert "VACUOUS RUN" in out.stdout + + +# --- the repository as it stands ------------------------------------------ + +def summary(stdout): + line = [l for l in stdout.splitlines() if l.startswith("pinned_sources_check: certificates=")] + assert len(line) == 1, stdout + return {k: int(v) for k, v in re.findall(r"(\w+)=(\d+)", line[0])} + + +def test_the_real_tree_verifies_every_binding(): + out = run(ROOT) + assert out.returncode == 0, out.stdout + s = summary(out.stdout) + assert s["certificates"] == 10 + assert s["pinned_files"] == 37 + assert s["pinned_archive_members"] == 6 + assert s["digest_matches"] == s["pinned_files"] + s["pinned_archive_members"] + assert s["unresolved"] == 0 + assert s["problems"] == 0 + + +# The three LPW sources that no map-shaped pin names. The interval modules in +# the same `sources` list are already bound by other certificates; these drive +# mirrors are present only as `{path, bytes, sha256}` siblings, and their +# digests match the bytes in this tree. +LPW_LIST_RECORD_PATHS = ( + "drive/mirrors/02_RESEARCH_CARRY_FORWARD_CANON/LPW — RAW ARCHIVE INTAKE R05/" + "03_RAYLEIGH_REPAIR_AND_INTERVAL_CERTIFICATE.md", + "drive/mirrors/02_RESEARCH_CARRY_FORWARD_CANON/LPW — RAW ARCHIVE INTAKE R05/" + "checks/interval_repair.py", + "drive/mirrors/02_RESEARCH_CARRY_FORWARD_CANON/LPW — RAW ARCHIVE INTAKE R05/" + "raw_reports/lpw_constant.py", +) + + +def test_the_lpw_list_record_paths_are_present_against_this_tree(): + """Those three paths are listed when the check is run on this tree. + + Dropping list-record siblings removes them from the generated inventory + and from the comparison, which is the gap this control exists to close. + """ + out = run(ROOT) + assert out.returncode == 0, out.stdout + index = open(os.path.join(ROOT, INDEX_REL), encoding="utf-8").read() + for path in LPW_LIST_RECORD_PATHS: + assert f"`{path}`" in index, path + assert f"{path}: pinned at" not in out.stdout + + +def test_the_index_names_the_bindings_nobody_would_guess(): + """Three checkers and a document are bound by certificate. That is the fact + this page exists to publish, so it is asserted rather than left to the + generator.""" + index = open(os.path.join(ROOT, INDEX_REL), encoding="utf-8").read() + for surprising in ("tools/drive_coverage.py", + "tools/hermite_envelope_report.py", + "tools/manifest_integrity_check.py", + "docs/HERMITE_GAUSSIAN_ENVELOPE.md", + "quarantine/EXCLUSIONS.json"): + assert f"`{surprising}`" in index, surprising + + +def test_the_index_is_what_the_certificates_say(): + """Belt and braces: the CLI comparison above, asserted from the test too, so + a tool weakened to stop comparing is not the only thing standing here.""" + sys.path.insert(0, os.path.join(ROOT, "tools")) + import pinned_sources_check as P + + files, containers, problems, counts = P.survey(ROOT, "research") + assert problems == [] + want = P.render(files, containers, counts) + assert open(os.path.join(ROOT, INDEX_REL), encoding="utf-8").read() == want diff --git a/tools/pinned_sources_check.py b/tools/pinned_sources_check.py new file mode 100644 index 000000000..1ae1e8244 --- /dev/null +++ b/tools/pinned_sources_check.py @@ -0,0 +1,455 @@ +#!/usr/bin/env python3 +"""Which repository files a certificate binds by SHA-256, generated and verified. + +Several candidate records under `research/` bind repository content by digest as +*source identity*: the certificate says "this result was produced against these +exact bytes", and the replay checkers that consume it refuse to run when a byte +has moved. That is the right discipline and nothing here weakens it. + +What was missing is that **no document in the tree said which files those are**. +The only way to find out was to edit one and read a rejection that names the +dependency but not the certificate: + + tools/twelve_project_check.py REJECTED + tools/h3_rn_n6_check.py REJECTED: repository dependency mismatch: + quarantine/EXCLUSIONS.json + +Three separate changes paid a cycle for that in four days, on +`research/bands/ladder.py`, `research/cover/ledger.py` and +`quarantine/EXCLUSIONS.json`. Two of the bound files are checkers in `tools/` +and one is a document in `docs/`, which nobody would guess from either. + +So the inventory is generated. `research/PINNED_SOURCES.md` is written by this +tool from the certificates themselves, recomputed on every run, and any drift +fails. Every binding is also verified against the content in this tree, so a +mismatch is reported once -- by file, with the certificate that names it and +both digests -- instead of as four opaque replay rejections. + +## Four shapes, and one genuine ambiguity + +A tool that knows only one shape under-reports the surface: + + path -> {"bytes": 37974, "sha256": "58ebe18f..."} + path -> "58ebe18f..." a bare digest string + a::b -> {...} member `b` of ZIP carrier `a` + {"path", "bytes", "sha256"} siblings in a list, not keys + +The ambiguity is not the shape but the *root*. The recovered Lean bundle keys +its `members` inside the bundle, not from the repository root, and one of them +is called `README.md`. Resolving it here reports a mismatch against a file the +certificate was never talking about -- the same defect this repository already +found and fixed once in its seal checker, which "resolved each declared path by +its last component, so a line naming a file in a subdirectory was compared +against a same-named sibling". + +`classify()` settles it from evidence rather than from a hand-kept list: a +container is repository-relative when at least one of its keys resolves here to +the bytes it pins. A container that is repository-relative and has drifted +*entirely* would be reclassified by that rule, so the generated index records +every container's classification and pin count, and the drift comparison fails +by name when one flips. + +## What this does NOT establish + +A pin is an identity statement and nothing more: these are the bytes the +certificate was produced against. It says nothing about whether the certificate +is correct, whether its mathematics holds, or whether the file is current or +authoritative. A green run means the bytes still match. No claim, premise, +obligation or gate is discharged by anything here, and no status moves. + +Run: python3 tools/pinned_sources_check.py # recompute and compare + python3 tools/pinned_sources_check.py --write # regenerate the index +Every path is resolved when `main()` runs, never at import time. +""" +from __future__ import annotations + +import argparse +import hashlib +import json +import os +import re +import zipfile + +REPO = os.path.dirname(os.path.dirname(os.path.abspath(__file__))) +SEARCH_REL = "research" +INDEX_REL = os.path.join("research", "PINNED_SOURCES.md") + +SHA256 = re.compile(r"^[0-9a-f]{64}$") + + +def identity(raw: bytes) -> dict: + """The house shape, as tools/twelve_project_check.py writes it.""" + return {"bytes": len(raw), "sha256": hashlib.sha256(raw).hexdigest()} + + +def looks_like_a_pin(key: str, value) -> dict | None: + """The pin this key/value pair states, in the house shape, or None. + + `bytes` is absent from the bare-digest shape and is then not compared; the + digest alone already fixes the content. + """ + if isinstance(value, dict) and SHA256.match(str(value.get("sha256", ""))): + pin = {"sha256": value["sha256"]} + if isinstance(value.get("bytes"), int): + pin["bytes"] = value["bytes"] + return pin + if isinstance(value, str) and SHA256.match(value) and ("/" in key or "." in key): + return {"sha256": value} + return None + + +def list_record_pin(node) -> tuple[str, dict] | None: + """A `{path, bytes, sha256}` record, or None. + + Map pins name the file in the key. This shape names it in a sibling field + of a record, and certificates nest those records in a list. A walker that + only looks at keys never sees them: `path`, `bytes` and `sha256` are not + themselves pins, so the whole list is skipped. Extra sibling fields + (`extraction`, `drive_id`, `module`, `members`) are ignored here and walked + separately, which is how an archive record can carry both its own path and + a nested member list. + """ + if not isinstance(node, dict): + return None + path = node.get("path") + digest = node.get("sha256") + size = node.get("bytes") + if not isinstance(path, str) or ("/" not in path and "." not in path): + return None + if not isinstance(digest, str) or not SHA256.match(digest): + return None + if isinstance(size, bool) or not isinstance(size, int): + return None + return path, {"sha256": digest, "bytes": size} + + +def certificate_paths(root: str, search_rel: str) -> list[str]: + """Every JSON under the searched directory, repository-relative, sorted.""" + found = [] + for dirpath, dirnames, filenames in os.walk(os.path.join(root, search_rel)): + dirnames[:] = [d for d in dirnames if d not in ("__pycache__", ".git")] + for fn in filenames: + if fn.endswith(".json"): + found.append(os.path.relpath(os.path.join(dirpath, fn), root)) + return sorted(found) + + +def pins_in(doc) -> dict[str, dict[str, dict]]: + """container -> {key: pin} for every pin this certificate states. + + A container is the JSON path of the dict holding the pin, with list indices + collapsed to `[]` so the eleven `auxiliary/pieces[i]/source_binding/...` + blocks read as one container rather than eleven. A `{path, bytes, sha256}` + record is pinned under the path of that record, so siblings in one list + share a container such as `sources[]`. + """ + out: dict[str, dict[str, dict]] = {} + + def walk(node, path: str) -> None: + if isinstance(node, dict): + record = list_record_pin(node) + if record is not None: + key, pin = record + out.setdefault(path, {})[key] = pin + for k, v in node.items(): + if k in ("path", "bytes", "sha256"): + continue + walk(v, f"{path}/{k}" if path else k) + return + for k, v in node.items(): + pin = looks_like_a_pin(k, v) + if pin is not None: + out.setdefault(path, {})[k] = pin + else: + walk(v, f"{path}/{k}" if path else k) + elif isinstance(node, list): + for v in node: + walk(v, f"{path}[]") + + walk(doc, "") + return out + + +def resolve(root: str, key: str) -> dict | None: + """The identity of what `key` names in this tree, or None if it names nothing. + + `::` is read out of the archive, which is how these + certificates name content sealed inside a ZIP carrier. + """ + if "::" in key: + arc, member = key.split("::", 1) + full = os.path.join(root, arc) + if not os.path.isfile(full): + return None + try: + with zipfile.ZipFile(full) as handle: + return identity(handle.read(member)) + except (OSError, KeyError, ValueError): + return None + full = os.path.join(root, key) + if not os.path.isfile(full) or os.path.islink(full): + return None + with open(full, "rb") as handle: + return identity(handle.read()) + + +def classify(root: str, block: dict[str, dict]) -> str: + """"repository" when at least one key resolves here to the bytes it pins.""" + for key, pin in block.items(): + got = resolve(root, key) + if got is not None and got["sha256"] == pin["sha256"]: + return "repository" + return "other" + + +def recorded_kinds(index_path: str) -> dict[tuple[str, str], str]: + """The classification the generated index records, read back out of it. + + The index is the declaration, not a decoration. `classify()` bootstraps it + from evidence under `--write`; every later run uses what was written, so a + container whose every pin has drifted keeps being compared and keeps naming + its files, instead of quietly reclassifying itself out of the check. + """ + kinds: dict[tuple[str, str], str] = {} + if not os.path.isfile(index_path): + return kinds + row = re.compile(r"^\| `([^`]+)` \| `([^`]+)` \| \d+ \| (repository|other) \|$") + with open(index_path, encoding="utf-8") as handle: + for line in handle: + m = row.match(line.strip()) + if m: + cert, container, kind = m.groups() + kinds[(cert, "" if container == "/" else container)] = kind + return kinds + + +def survey(root: str, search_rel: str, recorded: dict | None = None): + """Returns (files, containers, problems, counts).""" + files: dict[str, dict] = {} + containers: list[dict] = [] + problems: list[str] = [] + counts = {"certificates": 0, "sites": 0, "other_sites": 0} + + for cert in certificate_paths(root, search_rel): + try: + with open(os.path.join(root, cert), encoding="utf-8") as handle: + doc = json.load(handle) + except (OSError, ValueError): + continue + found = pins_in(doc) + if not found: + continue + counts["certificates"] += 1 + for container in sorted(found): + block = found[container] + derived = classify(root, block) + kind = (recorded or {}).get((cert, container), derived) + containers.append({"certificate": cert, "container": container, + "kind": kind, "derived": derived, + "pins": len(block)}) + if kind != "repository": + counts["other_sites"] += len(block) + continue + for key in sorted(block): + counts["sites"] += 1 + rec = files.setdefault(key, {"pin": block[key], "certificates": []}) + rec["certificates"].append(cert) + if rec["pin"]["sha256"] != block[key]["sha256"]: + problems.append( + f"{key}: two certificates pin different bytes -- " + f"{rec['pin']['sha256'][:16]} and " + f"{block[key]['sha256'][:16]}; one of them cannot be the " + f"content in this tree") + return files, containers, problems, counts + + +def verify(root: str, files: dict): + """Compare every repository binding against the content in this tree.""" + problems, matched, unresolved, compared = [], 0, 0, 0 + for path in sorted(files): + rec = files[path] + want = rec["pin"] + got = resolve(root, path) + named = ", ".join(sorted(set(rec["certificates"]))) + if got is None: + unresolved += 1 + problems.append( + f"{path}: pinned by {named} and this tree holds nothing there; " + f"a replay of that certificate will refuse this tree") + continue + compared += 1 + if got["sha256"] != want["sha256"]: + problems.append( + f"{path}: pinned at {want['sha256'][:16]} and this tree holds " + f"{got['sha256'][:16]}. {named} names these bytes as source " + f"identity, so its replay will refuse this tree. The remedy is a " + f"re-pin on the lane that owns the certificate, or restoring the " + f"bytes -- never editing the expected digest to match") + continue + if "bytes" in want and got["bytes"] != want["bytes"]: + problems.append( + f"{path}: the digest matches and the byte count does not " + f"({got['bytes']} here, {want['bytes']} pinned); the certificate " + f"is internally inconsistent") + continue + rec["actual"] = got + matched += 1 + return problems, matched, unresolved, compared + + +PREAMBLE = """ + +# Repository content a certificate binds by digest + +Several candidate records under `research/` name repository content by SHA-256 +as **source identity** — "this result was produced against these exact bytes". +Editing one of these files makes the replay checkers that consume the +certificate refuse the tree, by design. + +This page exists because nothing else in the repository said which files those +are. The rejection a replay prints names the dependency and not the certificate, +so the only way to learn a binding was to break it — and three separate changes +did, in four days. **Two of the files below are checkers in `tools/` and one is +a document in `docs/`.** + +Before editing anything in this table, read +[`tools/pinned_sources_check.py`](../tools/pinned_sources_check.py). The remedy +for a deliberate change is a re-pin on the lane that owns the certificate, never +a quiet edit to the expected digest. + +**What a pin is not.** It is an identity statement and nothing more. It says +nothing about whether the certificate is correct, whether its mathematics holds, +or whether the file is current or authoritative. A green run means the bytes +still match. No claim, premise, obligation or gate is discharged by anything on +this page. +""" + +HEADER = "| file | bytes | SHA-256 | pinned by |" +RULE = "|---|---:|---|---|" +CHEADER = "| certificate | container | keys | keys are |" +CRULE = "|---|---|---:|---|" + + +def render(files: dict, containers: list, counts: dict) -> str: + out = [PREAMBLE, "", HEADER, RULE] + for path in sorted(files): + rec = files[path] + certs = ", ".join(sorted({os.path.basename(c) for c in rec["certificates"]})) + out.append(f"| `{path}` | {rec['pin'].get('bytes', '—')} | " + f"`{rec['pin']['sha256'][:16]}…` | {certs} |") + out += [ + "", + f"{len([k for k in files if '::' not in k])} files and " + f"{len([k for k in files if '::' in k])} members sealed inside a ZIP " + f"carrier, bound at {counts['sites']} sites across " + f"{counts['certificates']} certificates.", + "", + "## Every container of pins, and what its keys are relative to", + "", + "A container whose keys are **repository** paths is verified above. One", + "marked **other** keys its entries inside a bundle the certificate", + "carries, so resolving them here would compare the wrong files; those are", + "counted and left alone. The classification is read off the evidence, not", + "a list — see `classify()` — and it is recorded here so that a container", + "flipping between the two fails this index's drift comparison by name.", + "", + CHEADER, CRULE, + ] + for c in sorted(containers, key=lambda r: (r["certificate"], r["container"])): + out.append(f"| `{c['certificate']}` | `{c['container'] or '/'}` | " + f"{c['pins']} | {c['kind']} |") + out.append("") + return "\n".join(out) + + +def main(argv=None) -> int: + parser = argparse.ArgumentParser(description=__doc__.splitlines()[0]) + parser.add_argument("--root", default=REPO) + parser.add_argument("--search", default=SEARCH_REL, + help="directory scanned for certificates") + parser.add_argument("--index", default=INDEX_REL) + parser.add_argument("--write", action="store_true") + args = parser.parse_args(argv) + + root = os.path.abspath(args.root) + index_path = os.path.join(root, args.index) + + recorded = {} if args.write else recorded_kinds(index_path) + files, containers, problems, counts = survey(root, args.search, recorded) + verify_problems, matched, unresolved, compared = verify(root, files) + problems += verify_problems + + for c in containers: + where = (c["certificate"], c["container"]) + was = recorded.get(where) + if was is None and recorded: + problems.append( + f"{c['certificate']}: pins under {c['container'] or '/'!r} and " + f"{args.index} does not record that container; regenerate the " + f"index with --write so the new binding surface is declared") + elif was is not None and was != c["derived"]: + problems.append( + f"{c['certificate']}: {args.index} records {c['container'] or '/'!r} " + f"as {was} and the evidence now reads {c['derived']} -- either " + f"every one of its {c['pins']} pins has drifted, or the container " + f"changed meaning. The pins are still being compared as {was}; " + f"read the mismatches above before regenerating") + + if not compared: + # The floor verify_manifests.py and quarantine_check.py already carry. A + # run that compared nothing must not read as "every binding holds". The + # test is `compared`, not `matched`: a run in which every binding was + # read and every one of them differed is a loud failure, not a vacuous + # one, and calling it vacuous would bury the mismatches it just found. + problems.append( + f"VACUOUS RUN: {counts['certificates']} certificates and " + f"{len(files)} repository bindings under {args.search}/, and not one " + f"digest was compared. That is not the same as nothing being wrong") + + want = render(files, containers, counts) + + if args.write: + for where, was in sorted(recorded_kinds(index_path).items()): + now = next((c["kind"] for c in containers + if (c["certificate"], c["container"]) == where), None) + if now is not None and now != was: + print(f"pinned_sources_check: {where[0]}: {where[1] or '/'} moves " + f"from {was} to {now}; a repository container becomes `other` " + f"only when every one of its pins has drifted") + with open(index_path, "w", encoding="utf-8") as handle: + handle.write(want) + print(f"pinned_sources_check: wrote {args.index} files={len(files)}") + return 0 + + if not os.path.isfile(index_path): + problems.append(f"{args.index} is missing; run --write") + else: + with open(index_path, encoding="utf-8") as handle: + have = handle.read() + if have != want: + for line in sorted(set(have.splitlines()) ^ set(want.splitlines())): + if line.startswith("|") and not line.startswith("|---"): + side = "the index says" if line in have else "the certificates say" + problems.append(f"{args.index}: {side} {line.strip()}") + problems.append( + f"{args.index} differs from what the certificates say; regenerate " + f"it with --write rather than editing it") + + for p in problems: + print(f"pinned_sources_check: {p}") + print(f"pinned_sources_check: certificates={counts['certificates']} " + f"containers={len(containers)} " + f"pinned_files={len([k for k in files if '::' not in k])} " + f"pinned_archive_members={len([k for k in files if '::' in k])} " + f"sites={counts['sites']} compared={compared} digest_matches={matched} " + f"unresolved={unresolved} " + f"keys_not_repository_relative={counts['other_sites']} " + f"problems={len(problems)}") + print("A pass says the content a certificate names is still the content in this tree. " + "It verifies no mathematics, reviews no certificate and moves no status.") + return 1 if problems else 0 + + +if __name__ == "__main__": + raise SystemExit(main()) diff --git a/tools/run_checks.py b/tools/run_checks.py index 12afbb74d..a00e1b962 100644 --- a/tools/run_checks.py +++ b/tools/run_checks.py @@ -64,6 +64,7 @@ "python tools/operations_check.py", "python tools/mirror_quotes_check.py", "python tools/mirrors_index_check.py", + "python tools/pinned_sources_check.py", "python tools/drive_index.py stats", "python tools/drive_coverage.py --json", "python tools/hermite_envelope_report.py --check research/bands/candidates/hermite_gaussian_20260919.json",