From 33a2b78e346c2f1da64c803d97ee631bf49dc4cc Mon Sep 17 00:00:00 2001 From: Dylan Roy Date: Sat, 26 Sep 2026 16:04:01 +0000 Subject: [PATCH 1/2] The pinned-source index missed 13 pinned files, and told me one was free to edit research/PINNED_SOURCES.md exists so that nobody has to learn a byte binding by breaking it. Its first version read only the JSON files on disk under research/, so the dependency declarations sealed INSIDE the campaign archives were invisible to it. Thirteen repository paths were byte-pinned by a live checker and absent from the index whose only purpose is to name them. That is not hypothetical. research/rn/moment_envelope.py is one of the thirteen. A NON-CERTIFYING label was added to it BECAUSE this page said it was not pinned, and tools/rn_bernstein_sharp_check.py refused the tree on replay. An incomplete "the only way to learn a binding was to break it" page is worse than no page, because it is trusted. That sentence is now in the index itself. The thirteen: research/rn/moment_envelope.py, density_majorant.py, n6_inputs.py, side24_wedge.py, spatial_cover.py; engine/operations/trial.py; research/parallel/lpw/lpw_modulus.py and ARGUMENT.md; docs/OPEN_PROBLEMS.md; two drive/ and drive/search/ files; and tools/h3_rn_n6_check.py plus tools/twelve_project_check.py -- two checkers pinned by the very campaign they enforce. LIVENESS IS TAKEN FROM THE CHECKERS, NOT FROM PIN SHAPE. This matters more than the fix. A campaign archive holds 137 pin-shaped JSON members. Most are manifests of the archive's own contents, or blocks named context_only_reads and governance_context recording what an agent had open -- several name CLAUDE.md and README.md at byte counts they no longer have, because nothing enforces them and nothing should. Listing those as "do not edit" would put a FALSE statement in the one document people read before editing, which is worse than the omission it replaced. So a declaration counts only when a tools/ checker passes it to repository_inputs, which compares it against the tree and refuses. That is four declarations across three archives, plus one set held in code (twelve_project_check.SUPPLEMENTAL_DEPENDENCIES), and each row names its enforcing checker so a reader learns WHO will refuse. Anti-drift: enforcing_checkers() scans tools/ for calls to repository_inputs and refuses any checker not named in the table -- the original defect cannot recur silently when a new campaign lands. The declared counts (25/30/32/24) are the ones the checkers themselves assert, so this index cannot read a subset and understate what may not be edited. Three mistakes made while writing this, all caught by the controls: - The first regex used a negative lookbehind excluding `.`, so it found only tools/twelve_project_check.py and missed the two that call runtime.repository_inputs(...). It would have declared the table complete with two checkers unlisted. A control now asserts all three are found. - main() merged the archive declarations and the index-equality control called survey() + render() directly, so the control compared the index against a render that had never seen an archive declaration. Two paths for one document is exactly how one kind of pin goes unchecked -- the defect being repaired, reproduced in the repair. Both now go through full_survey(). - The "pinned by" column basenamed its source, so two archives each holding a bernstein/DEPENDENCIES.json-shaped member both rendered as DEPENDENCIES.json, naming neither. Also closes the count drift in CLAUDE.md, which is the same defect in another place: it said eight records and 34 files where the checker finds eleven and 55. Those numbers are now written in a parseable form and COMPARED against the checker's own summary line by a control, with a second control asserting the comparison would notice a drifted number. A count in the file people read before editing is load-bearing; it had drifted twice as prose nobody compared. Scoping: archive declarations are read only in a root holding research/campaigns, so the synthetic-root controls are not failed for the wrong reason, and test_the_real_tree_reads_its_archive_declarations asserts this repository is never the skipped case. The summary line prints archive_scope so a skipped run is visible rather than silent. 29 controls pass, 10 of them verified to fail against the pre-fix tool in a real copy outside the tree. pinned_sources_check problems=0 with pinned_files=55, pinned_archive_members=6, archive_declarations=4. claims_check, quarantine_check, verify_manifests, consumers_check, registers_check, disclosure_check and rn_bernstein_sharp_check all clean -- the last one confirming no pinned byte moved. Scientific effect: NONE. This is an inventory of byte identities. A pin is custody, not correctness, and no claim, premise, obligation or gate is discharged here. Co-Authored-By: Claude Claude-Session: https://claude.ai/code/session_01Cz7WZybv8znP64SpPj6sWY --- CLAUDE.md | 19 ++- research/PINNED_SOURCES.md | 134 ++++++++++----- tests/test_pinned_sources.py | 178 +++++++++++++++++++- tools/pinned_sources_check.py | 300 ++++++++++++++++++++++++++++++++-- 4 files changed, 573 insertions(+), 58 deletions(-) diff --git a/CLAUDE.md b/CLAUDE.md index 366fa4ba6..42c9fa3c0 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -37,14 +37,19 @@ 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`. +Candidate records under `research/` bind repository content by SHA-256 as +*source identity*, and so do dependency declarations sealed **inside** the +campaign archives. 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, generated 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 + +certificates=11 archive_declarations=4 pinned_files=55 pinned_archive_members=6 + +Some of the bound files are checkers in `tools/` -- two of them pinned by the +very campaign they enforce -- and others are documents in `docs/`, `governance/` +and `drive/`, 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. diff --git a/research/PINNED_SOURCES.md b/research/PINNED_SOURCES.md index d78631e49..22e97d56e 100644 --- a/research/PINNED_SOURCES.md +++ b/research/PINNED_SOURCES.md @@ -3,21 +3,38 @@ # 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. +Candidate records under `research/`, and dependency declarations held **inside** +the campaign archives, 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 record 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/`.** +did, in four days. + +**A fourth did, after this page existed.** Its first version read only the JSON +files on disk under `research/`, so it never saw the declarations sealed inside a +campaign `.zip`. Thirteen pinned files were therefore absent from the index whose +only purpose is to name them, including `research/rn/moment_envelope.py`: a +NON-CERTIFYING label was added to that file *because this page said it was not +pinned*, and `tools/rn_bernstein_sharp_check.py` refused the tree on replay. The +bytes were restored and the archive declarations are now read. A "the only way to +learn a binding was to break it" page that is itself incomplete is worse than no +page, because it is trusted. + +**Some of the files below are checkers in `tools/`** — two of them are pinned by +the very campaign they enforce — **and several are documents in `docs/`, +`governance/` and `drive/`.** Counts are in the summary line after the table; +they are computed, not typed. 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. +a quiet edit to the expected digest — and never a NON-CERTIFYING label, a +docstring fix or a typo correction on the assumption that a small edit is safe. +The digest does not care how small the edit was. **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, @@ -29,55 +46,68 @@ 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 | +| `docs/OPEN_PROBLEMS.md` | 28417 | `8f404f87e44d2861…` | tools/twelve_project_check.py (SUPPLEMENTAL_DEPENDENCIES) | +| `drive/inventory.jsonl` | 2807455 | `48766f1807efaba6…` | inner_wedge_20260920_v1.json, rn_bernstein_sharp_variance_20260921_v1.zip::sharp_variance/DEPENDENCIES.json | +| `drive/mirrors/02_RESEARCH_CARRY_FORWARD_CANON/LPW — RAW ARCHIVE INTAKE R05/03_RAYLEIGH_REPAIR_AND_INTERVAL_CERTIFICATE.md` | 9628 | `840c75a7825c67b8…` | candidate.json, q0_twelve_20260920_v1.zip::verification_plan.json | +| `drive/mirrors/02_RESEARCH_CARRY_FORWARD_CANON/LPW — RAW ARCHIVE INTAKE R05/checks/interval_repair.py` | 6843 | `b37150f0eb79ff5d…` | candidate.json, q0_twelve_20260920_v1.zip::verification_plan.json | +| `drive/mirrors/02_RESEARCH_CARRY_FORWARD_CANON/LPW — RAW ARCHIVE INTAKE R05/raw_reports/LPW_CONSTANT_REPORT.md` | 12790 | `289d9f40e725bd51…` | q0_twelve_20260920_v1.zip::verification_plan.json | +| `drive/mirrors/02_RESEARCH_CARRY_FORWARD_CANON/LPW — RAW ARCHIVE INTAKE R05/raw_reports/lpw_constant.py` | 25380 | `e258322cfbb71dbb…` | candidate.json, q0_twelve_20260920_v1.zip::verification_plan.json | +| `drive/mirrors/2026-09-17_RN5_MOMENT_REPAIR_AND_REVIEW_ERRATUM/RN5_NEAR_MOMENT_REPAIR.md` | 13725 | `ac89f60b8206bfe0…` | h3_rn_n6_20260920_v1.zip::verification_plan.json, inner_wedge_20260920_v1.json, rn_bernstein_sharp_variance_20260921_v1.zip::sharp_variance/DEPENDENCIES.json, side24_density_20260920_v1.json, side24_point_20260920_v1.json, side24_spatial_20260920_v1.json, tools/twelve_project_check.py (SUPPLEMENTAL_DEPENDENCIES) | +| `drive/mirrors/2026-09-17_RN5_MOMENT_REPAIR_AND_REVIEW_ERRATUM/RN5_REPAIR_AND_ERRATUM_BUNDLE.zip` | 140170 | `28c1c385406452a7…` | h3_rn_n6_20260920_v1.zip::verification_plan.json, inner_wedge_20260920_v1.json, q0_twelve_20260920_v1.zip::verification_plan.json, rn_bernstein_sharp_variance_20260921_v1.zip::sharp_variance/DEPENDENCIES.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 | +| `drive/search/2026-09-20/deliveries/RECON_RN_REGISTRATION_20260920_v1.json` | 310770 | `540bf83b37b7b4d5…` | q0_twelve_20260920_v1.zip::verification_plan.json | +| `drive/source_map/Payloads.csv` | 2957503 | `1b1b94a784ebc87c…` | inner_wedge_20260920_v1.json, rn_bernstein_sharp_variance_20260921_v1.zip::sharp_variance/DEPENDENCIES.json | +| `engine/operations/__init__.py` | 343 | `818cb3d139128e78…` | DEPENDENCIES.json, candidate.json, h3_rn_n6_20260920_v1.zip::verification_plan.json, inner_wedge_20260920_v1.json, q0_twelve_20260920_v1.zip::verification_plan.json, rn_bernstein_sharp_variance_20260921_v1.zip::bernstein/DEPENDENCIES.json, rn_bernstein_sharp_variance_20260921_v1.zip::sharp_variance/DEPENDENCIES.json | +| `engine/operations/rn_applicability.py` | 4129 | `f28a93613d0995b8…` | DEPENDENCIES.json, candidate.json, h3_rn_n6_20260920_v1.zip::verification_plan.json, inner_wedge_20260920_v1.json, q0_twelve_20260920_v1.zip::verification_plan.json, rn_bernstein_sharp_variance_20260921_v1.zip::bernstein/DEPENDENCIES.json, rn_bernstein_sharp_variance_20260921_v1.zip::sharp_variance/DEPENDENCIES.json | +| `engine/operations/rn_family_applicability.py` | 2241 | `3a55870d2129a3b4…` | DEPENDENCIES.json, candidate.json, h3_rn_n6_20260920_v1.zip::verification_plan.json, inner_wedge_20260920_v1.json, q0_twelve_20260920_v1.zip::verification_plan.json, rn_bernstein_sharp_variance_20260921_v1.zip::bernstein/DEPENDENCIES.json, rn_bernstein_sharp_variance_20260921_v1.zip::sharp_variance/DEPENDENCIES.json | +| `engine/operations/trial.py` | 47797 | `f3bbd18c30383030…` | rn_bernstein_sharp_variance_20260921_v1.zip::bernstein/DEPENDENCIES.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 | +| `quarantine/EXCLUSIONS.json` | 19555 | `8a5a89012dcd0fec…` | h3_rn_n6_20260920_v1.zip::verification_plan.json, inner_wedge_20260920_v1.json, q0_twelve_20260920_v1.zip::verification_plan.json, rn_bernstein_sharp_variance_20260921_v1.zip::sharp_variance/DEPENDENCIES.json | +| `research/bands/__init__.py` | 4171 | `d9fb9686306523ae…` | DEPENDENCIES.json, candidate.json, h3_rn_n6_20260920_v1.zip::verification_plan.json, inner_wedge_20260920_v1.json, q0_twelve_20260920_v1.zip::verification_plan.json, rn_bernstein_sharp_variance_20260921_v1.zip::bernstein/DEPENDENCIES.json, rn_bernstein_sharp_variance_20260921_v1.zip::sharp_variance/DEPENDENCIES.json | +| `research/bands/falsifier.py` | 13281 | `0d1b4abf48c4f5b5…` | DEPENDENCIES.json, candidate.json, h3_rn_n6_20260920_v1.zip::verification_plan.json, inner_wedge_20260920_v1.json, q0_twelve_20260920_v1.zip::verification_plan.json, rn_bernstein_sharp_variance_20260921_v1.zip::bernstein/DEPENDENCIES.json, rn_bernstein_sharp_variance_20260921_v1.zip::sharp_variance/DEPENDENCIES.json | +| `research/bands/hermite_gaussian.py` | — | `f37e4657aceb95ab…` | DEPENDENCIES.json, candidate.json, h3_rn_n6_20260920_v1.zip::verification_plan.json, hermite_gaussian_20260919.json, inner_wedge_20260920_v1.json, q0_twelve_20260920_v1.zip::verification_plan.json, rn_bernstein_sharp_variance_20260921_v1.zip::bernstein/DEPENDENCIES.json, rn_bernstein_sharp_variance_20260921_v1.zip::sharp_variance/DEPENDENCIES.json | +| `research/bands/ladder.py` | 26286 | `9ea576708e146aa5…` | DEPENDENCIES.json, candidate.json, h3_rn_n6_20260920_v1.zip::verification_plan.json, inner_wedge_20260920_v1.json, q0_twelve_20260920_v1.zip::verification_plan.json, rn_bernstein_sharp_variance_20260921_v1.zip::bernstein/DEPENDENCIES.json, rn_bernstein_sharp_variance_20260921_v1.zip::sharp_variance/DEPENDENCIES.json | +| `research/bands/lattice.py` | — | `ee7144a98a689094…` | DEPENDENCIES.json, candidate.json, h3_rn_n6_20260920_v1.zip::verification_plan.json, hermite_gaussian_20260919.json, inner_wedge_20260920_v1.json, q0_twelve_20260920_v1.zip::verification_plan.json, rn_bernstein_sharp_variance_20260921_v1.zip::bernstein/DEPENDENCIES.json, rn_bernstein_sharp_variance_20260921_v1.zip::sharp_variance/DEPENDENCIES.json | +| `research/campaigns/h3_rn_n6_20260920_v1.zip` | 571735 | `73b9e63800f77c67…` | inner_wedge_20260920_v1.json, rn_bernstein_sharp_variance_20260921_v1.zip::sharp_variance/DEPENDENCIES.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 | +| `research/cover/__init__.py` | 4113 | `5f3afc075dc40e51…` | h3_rn_n6_20260920_v1.zip::verification_plan.json, inner_wedge_20260920_v1.json, rn_bernstein_sharp_variance_20260921_v1.zip::bernstein/DEPENDENCIES.json, rn_bernstein_sharp_variance_20260921_v1.zip::sharp_variance/DEPENDENCIES.json | +| `research/cover/driver.py` | 21760 | `7daaced91c179a75…` | h3_rn_n6_20260920_v1.zip::verification_plan.json, inner_wedge_20260920_v1.json, rn_bernstein_sharp_variance_20260921_v1.zip::bernstein/DEPENDENCIES.json, rn_bernstein_sharp_variance_20260921_v1.zip::sharp_variance/DEPENDENCIES.json | +| `research/cover/ledger.py` | 37974 | `58ebe18fbc3fc44e…` | h3_rn_n6_20260920_v1.zip::verification_plan.json, inner_wedge_20260920_v1.json, rn_bernstein_sharp_variance_20260921_v1.zip::bernstein/DEPENDENCIES.json, rn_bernstein_sharp_variance_20260921_v1.zip::sharp_variance/DEPENDENCIES.json | +| `research/cover/regions.py` | 23358 | `bf2d981772f3e35e…` | h3_rn_n6_20260920_v1.zip::verification_plan.json, inner_wedge_20260920_v1.json, rn_bernstein_sharp_variance_20260921_v1.zip::bernstein/DEPENDENCIES.json, rn_bernstein_sharp_variance_20260921_v1.zip::sharp_variance/DEPENDENCIES.json | +| `research/interval/__init__.py` | 2371 | `a6a185d24615288d…` | DEPENDENCIES.json, candidate.json, h3_rn_n6_20260920_v1.zip::verification_plan.json, inner_wedge_20260920_v1.json, q0_twelve_20260920_v1.zip::verification_plan.json, rn_bernstein_sharp_variance_20260921_v1.zip::bernstein/DEPENDENCIES.json, rn_bernstein_sharp_variance_20260921_v1.zip::sharp_variance/DEPENDENCIES.json | +| `research/interval/core.py` | — | `3f9e699cdb215957…` | DEPENDENCIES.json, candidate.json, h3_rn_n6_20260920_v1.zip::verification_plan.json, hermite_gaussian_20260919.json, inner_wedge_20260920_v1.json, q0_twelve_20260920_v1.zip::verification_plan.json, rn_bernstein_sharp_variance_20260921_v1.zip::bernstein/DEPENDENCIES.json, rn_bernstein_sharp_variance_20260921_v1.zip::sharp_variance/DEPENDENCIES.json | +| `research/interval/transcendental.py` | — | `7db4b5a6d868a731…` | DEPENDENCIES.json, candidate.json, h3_rn_n6_20260920_v1.zip::verification_plan.json, hermite_gaussian_20260919.json, inner_wedge_20260920_v1.json, q0_twelve_20260920_v1.zip::verification_plan.json, rn_bernstein_sharp_variance_20260921_v1.zip::bernstein/DEPENDENCIES.json, rn_bernstein_sharp_variance_20260921_v1.zip::sharp_variance/DEPENDENCIES.json | +| `research/parallel/lpw/ARGUMENT.md` | 10526 | `207f401d8810d397…` | q0_twelve_20260920_v1.zip::verification_plan.json | +| `research/parallel/lpw/lpw_modulus.py` | 11462 | `56030a63838d5d66…` | q0_twelve_20260920_v1.zip::verification_plan.json | +| `research/rn/certificate.py` | 16550 | `ddbbb25270c01c13…` | h3_rn_n6_20260920_v1.zip::verification_plan.json, inner_wedge_20260920_v1.json, rn_bernstein_sharp_variance_20260921_v1.zip::bernstein/DEPENDENCIES.json, rn_bernstein_sharp_variance_20260921_v1.zip::sharp_variance/DEPENDENCIES.json | +| `research/rn/conditioning.py` | — | `1d3ca89d9bc2b2ea…` | candidate.json, h3_rn_n6_20260920_v1.zip::verification_plan.json, inner_wedge_20260920_v1.json, q0_twelve_20260920_v1.zip::verification_plan.json, rn_bernstein_sharp_variance_20260921_v1.zip::bernstein/DEPENDENCIES.json, rn_bernstein_sharp_variance_20260921_v1.zip::sharp_variance/DEPENDENCIES.json | +| `research/rn/density_majorant.py` | 11301 | `96e680e47b6484e1…` | rn_bernstein_sharp_variance_20260921_v1.zip::bernstein/DEPENDENCIES.json, rn_bernstein_sharp_variance_20260921_v1.zip::sharp_variance/DEPENDENCIES.json | +| `research/rn/gaussian_families.py` | 5348 | `ecd1958dd9e02f82…` | DEPENDENCIES.json, candidate.json, h3_rn_n6_20260920_v1.zip::verification_plan.json, inner_wedge_20260920_v1.json, q0_twelve_20260920_v1.zip::verification_plan.json, rn_bernstein_sharp_variance_20260921_v1.zip::bernstein/DEPENDENCIES.json, rn_bernstein_sharp_variance_20260921_v1.zip::sharp_variance/DEPENDENCIES.json | +| `research/rn/gaussian_moments.py` | 8133 | `d545e4d31ef87605…` | DEPENDENCIES.json, candidate.json, h3_rn_n6_20260920_v1.zip::verification_plan.json, inner_wedge_20260920_v1.json, q0_twelve_20260920_v1.zip::verification_plan.json, rn_bernstein_sharp_variance_20260921_v1.zip::bernstein/DEPENDENCIES.json, rn_bernstein_sharp_variance_20260921_v1.zip::sharp_variance/DEPENDENCIES.json | +| `research/rn/moment_envelope.py` | 6778 | `107c873ffd7565e8…` | rn_bernstein_sharp_variance_20260921_v1.zip::bernstein/DEPENDENCIES.json | +| `research/rn/n6_inputs.py` | 4644 | `4eed3bc9a5684da2…` | rn_bernstein_sharp_variance_20260921_v1.zip::bernstein/DEPENDENCIES.json, rn_bernstein_sharp_variance_20260921_v1.zip::sharp_variance/DEPENDENCIES.json | +| `research/rn/side24.py` | 11239 | `dd6b5aa73442c8d5…` | DEPENDENCIES.json, candidate.json, h3_rn_n6_20260920_v1.zip::verification_plan.json, inner_wedge_20260920_v1.json, q0_twelve_20260920_v1.zip::verification_plan.json, rn_bernstein_sharp_variance_20260921_v1.zip::bernstein/DEPENDENCIES.json, rn_bernstein_sharp_variance_20260921_v1.zip::sharp_variance/DEPENDENCIES.json | +| `research/rn/side24_cell.py` | 13149 | `38cf5632f4689943…` | h3_rn_n6_20260920_v1.zip::verification_plan.json, inner_wedge_20260920_v1.json, rn_bernstein_sharp_variance_20260921_v1.zip::bernstein/DEPENDENCIES.json, rn_bernstein_sharp_variance_20260921_v1.zip::sharp_variance/DEPENDENCIES.json | +| `research/rn/side24_density.py` | 8289 | `3ad0b3b6fc3a5124…` | h3_rn_n6_20260920_v1.zip::verification_plan.json, inner_wedge_20260920_v1.json, rn_bernstein_sharp_variance_20260921_v1.zip::bernstein/DEPENDENCIES.json, rn_bernstein_sharp_variance_20260921_v1.zip::sharp_variance/DEPENDENCIES.json | +| `research/rn/side24_wedge.py` | 11684 | `70fa2563564a0601…` | rn_bernstein_sharp_variance_20260921_v1.zip::bernstein/DEPENDENCIES.json | +| `research/rn/spatial_cover.py` | 4169 | `d20bbebe14020245…` | rn_bernstein_sharp_variance_20260921_v1.zip::bernstein/DEPENDENCIES.json | | `research/side24/source_recovery/SIDE24_GAP_FILL_SUPPLEMENT.md` | 105980 | `05967f14a8b8d6a9…` | SOURCE_RECOVERY.json | | `research/side24/source_recovery/SIDE24_THEOREM_PACKAGE_v1.0.md` | 26045 | `703eefd5297afd45…` | SOURCE_RECOVERY.json | | `research/side24/source_recovery/custody/SIDE24_V3_4_AUDIT_REPLAY_FULL_ARCHIVE.zip` | 12465983 | `ba2a296b6a9c438e…` | SOURCE_RECOVERY.json | | `research/side24/source_recovery/custody/arithmetic_ledgers/40ad76a1973248d9/arithmetic_ledgers.py` | 3915 | `40ad76a1973248d9…` | SOURCE_RECOVERY.json | | `research/side24/source_recovery/custody/arithmetic_ledgers/ffbc6ccb48c08f78/arithmetic_ledgers.py` | 4191 | `ffbc6ccb48c08f78…` | SOURCE_RECOVERY.json | | `tools/drive_coverage.py` | — | `98b33fe9f97fe7a3…` | candidate.json | +| `tools/h3_rn_n6_check.py` | 15250 | `4935a003245878a3…` | rn_bernstein_sharp_variance_20260921_v1.zip::bernstein/DEPENDENCIES.json, rn_bernstein_sharp_variance_20260921_v1.zip::sharp_variance/DEPENDENCIES.json | | `tools/hermite_envelope_report.py` | — | `7a60f412a008e3bc…` | hermite_gaussian_20260919.json | | `tools/manifest_integrity_check.py` | — | `8b30cf5768318754…` | candidate.json | +| `tools/twelve_project_check.py` | 25462 | `54146780a912bbb6…` | rn_bernstein_sharp_variance_20260921_v1.zip::bernstein/DEPENDENCIES.json, rn_bernstein_sharp_variance_20260921_v1.zip::sharp_variance/DEPENDENCIES.json | -42 files and 6 members sealed inside a ZIP carrier, bound at 133 sites across 11 certificates. +55 files and 6 members sealed inside a ZIP carrier, bound at 133 sites across 11 certificates, plus 113 sites in 4 dependency declarations held INSIDE campaign archives and enforced by the checkers named below. ## Every container of pins, and what its keys are relative to @@ -113,3 +143,29 @@ flipping between the two fails this index's drift comparison by name. | `research/side24/source_recovery/SOURCE_RECOVERY.json` | `arithmetic_ledgers[]` | 2 | repository | | `research/side24/source_recovery/SOURCE_RECOVERY.json` | `custody_files[]` | 1 | repository | | `research/side24/source_recovery/SOURCE_RECOVERY.json` | `recovered[]` | 2 | repository | + +## Dependency declarations held inside a campaign archive + +These are not certificates on disk. Each is a JSON member **inside** a +campaign `.zip` that names repository paths by digest, and each is live +because a checker in `tools/` passes it to `repository_inputs`, which +compares it against this tree and refuses. The files they name are in the +table above, so this section says who will refuse and where the digest +came from. + +A campaign archive also holds many pin-*shaped* members that are **not** +pins: manifests of the archive's own contents, and blocks named +`context_only_reads` or `governance_context` recording what an agent had +open — several name `CLAUDE.md` and `README.md` at byte counts they no +longer have, because nothing enforces them and nothing should. Those are +deliberately absent. Listing them as "do not edit" would put a false +statement in the one document people read before editing, which is worse +than the omission this section replaced. + +| archive | member | key | enforced by | paths | +|---|---|---|---|---:| +| `h3_rn_n6_20260920_v1.zip` | `verification_plan.json` | `repository_inputs` | `tools/h3_rn_n6_check.py` | 25 | +| `rn_bernstein_sharp_variance_20260921_v1.zip` | `bernstein/DEPENDENCIES.json` | `files` | `tools/rn_bernstein_sharp_check.py` | 30 | +| `rn_bernstein_sharp_variance_20260921_v1.zip` | `sharp_variance/DEPENDENCIES.json` | `files` | `tools/rn_bernstein_sharp_check.py` | 32 | +| `q0_twelve_20260920_v1.zip` | `verification_plan.json` | `repository_dependencies` | `tools/twelve_project_check.py` | 24 | +| *(none — held in code)* | — | `SUPPLEMENTAL_DEPENDENCIES` | `tools/twelve_project_check.py` | see that file | diff --git a/tests/test_pinned_sources.py b/tests/test_pinned_sources.py index f1152a1cf..77445bb9e 100644 --- a/tests/test_pinned_sources.py +++ b/tests/test_pinned_sources.py @@ -309,8 +309,13 @@ def test_the_real_tree_verifies_every_binding(): s = summary(out.stdout) # SOURCE_RECOVERY.json binds two proof bodies, one archive, and two scripts. assert s["certificates"] == 11 - assert s["pinned_files"] == 42 + # 42 before the campaign archives' own dependency declarations were read. The + # thirteen paths that jump adds are pinned by a checker and were absent from the + # index that exists to name them -- see + # test_the_index_names_what_only_a_campaign_archive_pins. + assert s["pinned_files"] == 55 assert s["pinned_archive_members"] == 6 + assert s["archive_declarations"] == 4 assert s["digest_matches"] == s["pinned_files"] + s["pinned_archive_members"] assert s["unresolved"] == 0 assert s["problems"] == 0 @@ -365,8 +370,177 @@ def test_the_index_is_what_the_certificates_say(): sys.path.insert(0, os.path.join(ROOT, "tools")) import pinned_sources_check as P - files, containers, problems, counts = P.survey(ROOT, "research") + # full_survey, not survey: the index includes the pins declared inside campaign + # archives, and calling survey() here compared the index against a render that + # had never seen one. Two paths for one document is how a kind of pin goes + # unchecked. + files, containers, problems, counts = P.full_survey(ROOT, "research") assert problems == [] want = P.render(files, containers, counts) with open(os.path.join(ROOT, INDEX_REL), encoding="utf-8") as handle: assert handle.read() == want + + +# ------------------- pins declared INSIDE a campaign archive ----------------- +# The defect these close: the first version of this tool read only the JSON files +# on disk under `research/`, so the dependency declarations sealed inside a +# campaign `.zip` were invisible. Thirteen pinned repository paths were absent +# from the index whose only purpose is to name them, and one of them -- +# `research/rn/moment_envelope.py` -- was then edited BECAUSE the index said it +# was not pinned, which made `tools/rn_bernstein_sharp_check.py` refuse the tree. + +ARCHIVE_ONLY_PINS = ( + "research/rn/moment_envelope.py", # the one that was broken + "research/rn/density_majorant.py", + "research/rn/n6_inputs.py", + "research/rn/side24_wedge.py", + "research/rn/spatial_cover.py", + "engine/operations/trial.py", + "research/parallel/lpw/lpw_modulus.py", + "research/parallel/lpw/ARGUMENT.md", + "docs/OPEN_PROBLEMS.md", + "tools/h3_rn_n6_check.py", # a checker pinned by the campaign it enforces + "tools/twelve_project_check.py", # and the other one +) + + +def test_the_index_names_what_only_a_campaign_archive_pins(): + """Every one of these is pinned by an archive declaration and by nothing on + disk, so each is absent from the index unless the archives are read.""" + with open(os.path.join(ROOT, INDEX_REL), encoding="utf-8") as handle: + index = handle.read() + for path in ARCHIVE_ONLY_PINS: + assert f"| `{path}` |" in index, path + + +def test_the_real_tree_reads_its_archive_declarations(): + """The scope guard must never silently apply to this repository. + + `archive_declared` skips a root with no `research/campaigns`, so the controls + above can use synthetic roots of three files. If that skip ever applied here, + every archive-declared pin would vanish from the index and the run would still + be green -- so the real tree asserts it is reading them.""" + out = run(ROOT) + assert out.returncode == 0, out.stdout + assert "archive_scope='read'" in out.stdout, out.stdout + assert summary(out.stdout)["archive_declarations"] == 4 + + +def test_every_enforcing_checker_is_named_by_the_table(): + """The anti-drift guard. A new campaign checker that enforces a pin set against + the tree must appear in ARCHIVE_DEPENDENCY_SOURCES or CHECKER_HELD_DEPENDENCIES, + or whatever it pins is invisible here -- the original defect, recurring.""" + sys.path.insert(0, os.path.join(ROOT, "tools")) + import pinned_sources_check as P + + named = ({row[3] for row in P.ARCHIVE_DEPENDENCY_SOURCES} + | {row[0] for row in P.CHECKER_HELD_DEPENDENCIES}) + found = P.enforcing_checkers(ROOT) + assert found, "no enforcing checker found at all; the scan has stopped working" + assert found <= named, sorted(found - named) + # And the scan really does see the attribute-call form, which is how two of the + # three call it. A lookbehind excluding `.` found only one and would have + # declared the table complete with two checkers unlisted. + assert "tools/h3_rn_n6_check.py" in found + assert "tools/rn_bernstein_sharp_check.py" in found + assert "tools/twelve_project_check.py" in found + + +def test_a_declared_count_that_no_longer_matches_is_refused(tmp_path): + """If a declaration grows or shrinks, this index must refuse rather than list a + subset: understating what may not be edited is the failure mode.""" + sys.path.insert(0, os.path.join(ROOT, "tools")) + import pinned_sources_check as P + + original = P.ARCHIVE_DEPENDENCY_SOURCES + try: + arc, member, key, checker, declared = original[1] + P.ARCHIVE_DEPENDENCY_SOURCES = ((arc, member, key, checker, declared + 1),) + _files, problems, _counts = P.archive_declared(ROOT) + assert any("must read exactly what the checker reads" in p for p in problems), problems + finally: + P.ARCHIVE_DEPENDENCY_SOURCES = original + + +def test_a_missing_declaration_key_is_refused(): + sys.path.insert(0, os.path.join(ROOT, "tools")) + import pinned_sources_check as P + + original = P.ARCHIVE_DEPENDENCY_SOURCES + try: + arc, member, _key, checker, declared = original[0] + P.ARCHIVE_DEPENDENCY_SOURCES = ((arc, member, "no_such_key", checker, declared),) + _files, problems, _counts = P.archive_declared(ROOT) + assert any("no 'no_such_key' key" in p for p in problems), problems + finally: + P.ARCHIVE_DEPENDENCY_SOURCES = original + + +def test_an_absent_declared_archive_is_refused(tmp_path): + sys.path.insert(0, os.path.join(ROOT, "tools")) + import pinned_sources_check as P + + (tmp_path / "research" / "campaigns").mkdir(parents=True) + (tmp_path / "tools").mkdir() + _files, problems, _counts = P.archive_declared(str(tmp_path)) + assert any("declared as an archive pin source and absent" in p for p in problems), problems + + +def test_dependency_rows_reads_both_declaration_shapes(): + """`bernstein/DEPENDENCIES.json` keys its records by path; `sharp_variance`'s + carries a list of rows. Reading only one shape silently drops 30 or 32 pins.""" + sys.path.insert(0, os.path.join(ROOT, "tools")) + import pinned_sources_check as P + + as_dict = {"a.py": {"bytes": 1, "sha256": "a" * 64}} + as_list = [{"path": "b.py", "bytes": 2, "sha256": "b" * 64}] + assert P.dependency_rows(as_dict) == {"a.py": {"bytes": 1, "sha256": "a" * 64}} + assert P.dependency_rows(as_list) == {"b.py": {"bytes": 2, "sha256": "b" * 64}} + assert P.dependency_rows({"schema": "not-a-record"}) == {} + assert P.dependency_rows([{"no": "path"}]) == {} + + +def test_the_source_label_does_not_collide_between_archives(): + """A bare basename put `DEPENDENCIES.json` in the "pinned by" column, which names + neither of the two archives that hold a member of that name.""" + sys.path.insert(0, os.path.join(ROOT, "tools")) + import pinned_sources_check as P + + a = P.source_label("research/campaigns/one.zip::bernstein/DEPENDENCIES.json") + b = P.source_label("research/campaigns/two.zip::bernstein/DEPENDENCIES.json") + assert a != b and a == "one.zip::bernstein/DEPENDENCIES.json" + assert P.source_label("tools/twelve_project_check.py (SUPPLEMENTAL_DEPENDENCIES)").startswith("tools/") + + +CLAUDE_MD = os.path.join(ROOT, "CLAUDE.md") +COUNT_KEYS = ("certificates", "archive_declarations", "pinned_files", + "pinned_archive_members") + + +def test_claude_md_counts_match_the_checker(): + """CLAUDE.md told readers how much is pinned, in prose nobody compared, and the + numbers drifted twice: it said eight records and 34 files where the checker + found eleven and 55. A count in the file people read BEFORE editing is + load-bearing, so it is compared rather than trusted.""" + out = run(ROOT) + assert out.returncode == 0, out.stdout + computed = summary(out.stdout) + with open(CLAUDE_MD, encoding="utf-8") as handle: + text = handle.read() + stated = dict(re.findall(r"(\w+)=(\d+)", text)) + for key in COUNT_KEYS: + assert key in stated, f"CLAUDE.md states no {key}" + assert int(stated[key]) == computed[key], (key, stated[key], computed[key]) + + +def test_the_count_control_would_notice_a_drifted_number(tmp_path): + """Without this, the control above could be comparing nothing.""" + out = run(ROOT) + computed = summary(out.stdout) + with open(CLAUDE_MD, encoding="utf-8") as handle: + text = handle.read() + drifted = text.replace(f"pinned_files={computed['pinned_files']}", + f"pinned_files={computed['pinned_files'] + 1}") + assert drifted != text, "the control cannot find the number it claims to check" + stated = dict(re.findall(r"(\w+)=(\d+)", drifted)) + assert int(stated["pinned_files"]) != computed["pinned_files"] diff --git a/tools/pinned_sources_check.py b/tools/pinned_sources_check.py index 1ae1e8244..fae149495 100644 --- a/tools/pinned_sources_check.py +++ b/tools/pinned_sources_check.py @@ -65,9 +65,11 @@ import argparse import hashlib +import importlib.util import json import os import re +import sys import zipfile REPO = os.path.dirname(os.path.dirname(os.path.abspath(__file__))) @@ -123,6 +125,187 @@ def list_record_pin(node) -> tuple[str, dict] | None: return path, {"sha256": digest, "bytes": size} +# --------------------------------------------------------------------------- +# Pins declared INSIDE an archive member, and enforced against the tree. +# +# This is the shape the first version of this index missed completely, and the +# miss had a consequence: the index said `research/rn/moment_envelope.py` was not +# pinned, a NON-CERTIFYING label was added to it on that basis, and +# tools/rn_bernstein_sharp_check.py refused the tree on replay. The index whose +# whole purpose is to name the files a certificate binds by digest did not name +# thirteen of them. +# +# These are NOT discovered heuristically. A campaign archive holds a hundred and +# thirty-seven pin-shaped JSON members, and most are manifests of the archive's +# own contents or records of what was in an agent's context -- `context_only_reads` +# and `governance_context` blocks naming CLAUDE.md and README.md at byte counts +# they no longer have, because nothing enforces them and nothing should. Listing +# those as "do not edit" would be a false statement in the one document people +# consult before editing, which is worse than the omission it replaced. +# +# So liveness is taken from the checkers themselves: a declaration is live when a +# tools/ checker passes it to `repository_inputs`, which compares it against the +# tree and refuses. Each row below names that checker, and +# `enforcing_checkers()` + `tests/test_pinned_sources.py` refuse a tools/ checker +# that starts enforcing an archive declaration without appearing here. +# +# (archive, member, key holding repository paths, enforcing checker, count the +# checker itself asserts) +ARCHIVE_DEPENDENCY_SOURCES = ( + ("research/campaigns/h3_rn_n6_20260920_v1.zip", "verification_plan.json", + "repository_inputs", "tools/h3_rn_n6_check.py", 25), + ("research/campaigns/rn_bernstein_sharp_variance_20260921_v1.zip", + "bernstein/DEPENDENCIES.json", "files", "tools/rn_bernstein_sharp_check.py", 30), + ("research/campaigns/rn_bernstein_sharp_variance_20260921_v1.zip", + "sharp_variance/DEPENDENCIES.json", "files", "tools/rn_bernstein_sharp_check.py", 32), + ("research/campaigns/q0_twelve_20260920_v1.zip", "verification_plan.json", + "repository_dependencies", "tools/twelve_project_check.py", 24), +) + +# A checker may also hold pins in its own source rather than in an archive. +# tools/twelve_project_check.py unions SUPPLEMENTAL_DEPENDENCIES into what it +# enforces, so those paths are pinned by code with no certificate behind them. +CHECKER_HELD_DEPENDENCIES = ( + ("tools/twelve_project_check.py", "SUPPLEMENTAL_DEPENDENCIES"), +) + + +def dependency_rows(node) -> dict[str, dict]: + """{path: {bytes, sha256}} from a dict-of-records or a list-of-records. + + The four declarations use both shapes: `bernstein/DEPENDENCIES.json` keys its + records by path, `sharp_variance/DEPENDENCIES.json` carries a list of + `{path, bytes, sha256}` rows. + """ + out: dict[str, dict] = {} + if isinstance(node, dict): + for key, value in node.items(): + if isinstance(value, dict) and isinstance(value.get("sha256"), str): + out[value.get("path", key)] = {"bytes": value.get("bytes"), + "sha256": value["sha256"]} + return out + if isinstance(node, list): + for row in node: + if isinstance(row, dict) and isinstance(row.get("sha256"), str) and row.get("path"): + out[row["path"]] = {"bytes": row.get("bytes"), "sha256": row["sha256"]} + return out + + +def enforcing_checkers(root: str) -> set[str]: + """tools/ modules that call `repository_inputs(`, i.e. enforce a pin set. + + A literal scan on purpose. The point is to notice a NEW enforcing checker + that ARCHIVE_DEPENDENCY_SOURCES does not mention, and a scan that reads the + source sees one the moment it lands. `repository_inputs` is also the name of + a JSON key, so the call form with the open bracket is what is matched. + """ + found = set() + tools_dir = os.path.join(root, "tools") + for name in sorted(os.listdir(tools_dir)): + if not name.endswith(".py"): + continue + with open(os.path.join(tools_dir, name), encoding="utf-8") as handle: + body = handle.read() + # `runtime.repository_inputs(...)` is the call form in two of the three + # campaign checkers, so an attribute access must count. A negative lookbehind + # excluding `.` found only one of the three and would have declared the table + # complete while two checkers went unlisted. The JSON KEY of the same name is + # never followed by an open bracket, so requiring the bracket is enough. + if re.search(r"repository_inputs\s*\(", body) and name != "pinned_sources_check.py": + found.add("tools/" + name) + return found + + +def archive_declared(root: str) -> tuple[dict[str, dict], list[str], dict]: + """(files, problems, counts) for every live archive-declared repository pin.""" + files: dict[str, dict] = {} + problems: list[str] = [] + counts = {"declarations": 0, "declared_sites": 0, "archive_scope": "read"} + + # Scoped to a root that actually holds the campaign tree. The controls for this + # tool run it against synthetic roots of two or three files; requiring the real + # campaign archives there would fail every one of them for the wrong reason, and + # the fix for that must not be to weaken the requirement on the real tree. So the + # rule is explicit: a root WITH research/campaigns must have every declared + # archive, and a root without one is a different tree. + # `test_the_real_tree_reads_its_archive_declarations` asserts this repository is + # never the second case, so the skip cannot drift onto it. + if not os.path.isdir(os.path.join(root, "research", "campaigns")): + counts["archive_scope"] = "no research/campaigns in this root" + return files, problems, counts + + def add(path: str, pin: dict, named_by: str) -> None: + counts["declared_sites"] += 1 + rec = files.setdefault(path, {"pin": pin, "certificates": []}) + rec["certificates"].append(named_by) + if rec["pin"]["sha256"] != pin["sha256"]: + problems.append( + f"{path}: two archive declarations pin different bytes -- " + f"{rec['pin']['sha256'][:16]} and {pin['sha256'][:16]}; one of them " + f"cannot be the content in this tree") + + for arc, member, key, checker, declared in ARCHIVE_DEPENDENCY_SOURCES: + full = os.path.join(root, arc) + if not os.path.isfile(full): + problems.append(f"{arc}: declared as an archive pin source and absent from " + f"this tree, so {checker} cannot be enforcing it") + continue + try: + with zipfile.ZipFile(full) as handle: + doc = json.loads(handle.read(member)) + except (OSError, KeyError, ValueError) as exc: + problems.append(f"{arc}::{member}: unreadable as JSON ({exc}); the pins " + f"{checker} enforces cannot be listed") + continue + if key not in doc: + problems.append(f"{arc}::{member}: no {key!r} key, so this index cannot see " + f"what {checker} enforces") + continue + rows = dependency_rows(doc[key]) + if len(rows) != declared: + problems.append( + f"{arc}::{member}[{key}]: reads {len(rows)} paths and {checker} asserts " + f"{declared}. This index must read exactly what the checker reads, or it " + f"understates what may not be edited") + continue + counts["declarations"] += 1 + for path, pin in rows.items(): + add(path, pin, f"{arc}::{member}") + + for checker, attr in CHECKER_HELD_DEPENDENCIES: + module_path = os.path.join(root, checker) + if not os.path.isfile(module_path): + problems.append(f"{checker}: declared as holding {attr} and absent from this tree") + continue + try: + spec = importlib.util.spec_from_file_location("_pin_probe_" + attr, module_path) + module = importlib.util.module_from_spec(spec) + sys.modules[spec.name] = module + spec.loader.exec_module(module) + held = getattr(module, attr) + except Exception as exc: # noqa: BLE001 + problems.append(f"{checker}: {attr} could not be read ({type(exc).__name__}: " + f"{exc}). A pin set held in code and not readable here is a pin " + f"this index cannot report") + continue + for path, pin in dependency_rows(held).items(): + add(path, pin, f"{checker} ({attr})") + + if not os.path.isdir(os.path.join(root, "tools")): + counts["archive_scope"] = "no tools/ in this root" + return files, problems, counts + missing = sorted(enforcing_checkers(root) + - {row[3] for row in ARCHIVE_DEPENDENCY_SOURCES} + - {row[0] for row in CHECKER_HELD_DEPENDENCIES}) + for checker in missing: + problems.append( + f"{checker}: enforces a repository pin set against the tree and is named by no " + f"row in ARCHIVE_DEPENDENCY_SOURCES or CHECKER_HELD_DEPENDENCIES, so whatever " + f"it pins is absent from this index. That is the exact defect this section " + f"exists to prevent: add the row before the next replay refuses somebody") + return files, problems, counts + + def certificate_paths(root: str, search_rel: str) -> list[str]: """Every JSON under the searched directory, repository-relative, sorted.""" found = [] @@ -263,6 +446,35 @@ def survey(root: str, search_rel: str, recorded: dict | None = None): return files, containers, problems, counts +def full_survey(root: str, search_rel: str, recorded: dict | None = None): + """`survey()` plus the pins declared inside campaign archives. + + ONE entry point for both kinds, used by the CLI and by the controls. They were + two paths for one commit: `main()` merged the archive declarations and + `test_the_index_is_what_the_certificates_say` called `survey()` + `render()` + directly, so the test compared the index against a render that had never seen + an archive declaration. A second path is exactly how one of two kinds of pin + ends up unchecked -- which is the defect this whole section exists to repair, + reproduced in the repair. + """ + files, containers, problems, counts = survey(root, search_rel, recorded) + declared, declared_problems, declared_counts = archive_declared(root) + problems = problems + declared_problems + counts.update(declared_counts) + for path, rec in declared.items(): + existing = files.get(path) + if existing is None: + files[path] = rec + continue + existing["certificates"] += rec["certificates"] + if existing["pin"]["sha256"] != rec["pin"]["sha256"]: + problems.append( + f"{path}: a certificate and an archive declaration pin different bytes -- " + f"{existing['pin']['sha256'][:16]} and {rec['pin']['sha256'][:16]}; one of " + f"them cannot be the 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 @@ -302,21 +514,38 @@ def verify(root: str, files: dict): # 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. +Candidate records under `research/`, and dependency declarations held **inside** +the campaign archives, 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 record 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/`.** +did, in four days. + +**A fourth did, after this page existed.** Its first version read only the JSON +files on disk under `research/`, so it never saw the declarations sealed inside a +campaign `.zip`. Thirteen pinned files were therefore absent from the index whose +only purpose is to name them, including `research/rn/moment_envelope.py`: a +NON-CERTIFYING label was added to that file *because this page said it was not +pinned*, and `tools/rn_bernstein_sharp_check.py` refused the tree on replay. The +bytes were restored and the archive declarations are now read. A "the only way to +learn a binding was to break it" page that is itself incomplete is worse than no +page, because it is trusted. + +**Some of the files below are checkers in `tools/`** — two of them are pinned by +the very campaign they enforce — **and several are documents in `docs/`, +`governance/` and `drive/`.** Counts are in the summary line after the table; +they are computed, not typed. 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. +a quiet edit to the expected digest — and never a NON-CERTIFYING label, a +docstring fix or a typo correction on the assumption that a small edit is safe. +The digest does not care how small the edit was. **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, @@ -331,11 +560,28 @@ def verify(root: str, files: dict): CRULE = "|---|---|---:|---|" +def source_label(name: str) -> str: + """Short, UNAMBIGUOUS name for whatever pinned a file. + + A bare basename is what the first version used, and it collides: two archives + each hold a `bernstein/DEPENDENCIES.json`-shaped member, so `DEPENDENCIES.json` + in the "pinned by" column would name neither of them. An archive declaration + keeps `::`; a checker that holds pins in code keeps its own + path, because that is where a reader has to go. + """ + if "::" in name: + arc, member = name.split("::", 1) + return f"{os.path.basename(arc)}::{member}" + if name.startswith("tools/"): + return name + return os.path.basename(name) + + 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"]})) + certs = ", ".join(sorted({source_label(c) for c in rec["certificates"]})) out.append(f"| `{path}` | {rec['pin'].get('bytes', '—')} | " f"`{rec['pin']['sha256'][:16]}…` | {certs} |") out += [ @@ -343,7 +589,10 @@ def render(files: dict, containers: list, counts: dict) -> str: 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.", + f"{counts['certificates']} certificates, plus " + f"{counts.get('declared_sites', 0)} sites in " + f"{counts.get('declarations', 0)} dependency declarations held INSIDE campaign " + f"archives and enforced by the checkers named below.", "", "## Every container of pins, and what its keys are relative to", "", @@ -359,6 +608,35 @@ def render(files: dict, containers: list, counts: dict) -> str: 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 += [ + "", + "## Dependency declarations held inside a campaign archive", + "", + "These are not certificates on disk. Each is a JSON member **inside** a", + "campaign `.zip` that names repository paths by digest, and each is live", + "because a checker in `tools/` passes it to `repository_inputs`, which", + "compares it against this tree and refuses. The files they name are in the", + "table above, so this section says who will refuse and where the digest", + "came from.", + "", + "A campaign archive also holds many pin-*shaped* members that are **not**", + "pins: manifests of the archive's own contents, and blocks named", + "`context_only_reads` or `governance_context` recording what an agent had", + "open — several name `CLAUDE.md` and `README.md` at byte counts they no", + "longer have, because nothing enforces them and nothing should. Those are", + "deliberately absent. Listing them as \"do not edit\" would put a false", + "statement in the one document people read before editing, which is worse", + "than the omission this section replaced.", + "", + "| archive | member | key | enforced by | paths |", + "|---|---|---|---|---:|", + ] + for arc, member, key, checker, declared in ARCHIVE_DEPENDENCY_SOURCES: + out.append(f"| `{os.path.basename(arc)}` | `{member}` | `{key}` | " + f"`{checker}` | {declared} |") + for checker, attr in CHECKER_HELD_DEPENDENCIES: + out.append(f"| *(none — held in code)* | — | `{attr}` | `{checker}` | " + f"see that file |") out.append("") return "\n".join(out) @@ -376,7 +654,7 @@ def main(argv=None) -> int: 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) + files, containers, problems, counts = full_survey(root, args.search, recorded) verify_problems, matched, unresolved, compared = verify(root, files) problems += verify_problems @@ -442,6 +720,8 @@ def main(argv=None) -> int: 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"archive_declarations={counts.get('declarations', 0)} " + f"archive_scope={counts.get('archive_scope', 'read')!r} " f"sites={counts['sites']} compared={compared} digest_matches={matched} " f"unresolved={unresolved} " f"keys_not_repository_relative={counts['other_sites']} " From 85ee72090d57a271446f3530133d3567d1742a3c Mon Sep 17 00:00:00 2001 From: Cursor Agent Date: Sun, 27 Sep 2026 18:08:54 +0000 Subject: [PATCH 2/2] Correct two false sentences in the pinned-source preamble and state the guard's scope Review 5848434306 item 1: tools/h3_rn_n6_check.py and tools/twelve_project_check.py are pinned by the downstream rn_bernstein_sharp_variance campaign members, not by the campaigns they enforce, and no pinned path begins with governance/. Both sentences (CLAUDE.md and the PREAMBLE rendered into research/PINNED_SOURCES.md) now say what the index rows show; the index is regenerated with --write. Item 2: enforcing_checkers() docstring states that only top-level tools/*.py is scanned and that the guard is per checker, with the index-equality control covering a single missing row. Ran: tools/pinned_sources_check.py (problems=0, 61/61 digests); pytest tests/test_pinned_sources.py (29 passed). Co-authored-by: Dylan Roy --- CLAUDE.md | 8 +++++--- research/PINNED_SOURCES.md | 10 ++++++---- tools/pinned_sources_check.py | 18 ++++++++++++++---- 3 files changed, 25 insertions(+), 11 deletions(-) diff --git a/CLAUDE.md b/CLAUDE.md index 9ff1dcdd8..c5a52de17 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -47,9 +47,11 @@ of it, generated and verified in CI by `tools/pinned_sources_check.py`: summary line; they drifted twice while they were prose nobody compared --> certificates=11 archive_declarations=4 pinned_files=55 pinned_archive_members=6 -Some of the bound files are checkers in `tools/` -- two of them pinned by the -very campaign they enforce -- and others are documents in `docs/`, `governance/` -and `drive/`, so this is not deducible from where a file lives. The remedy for a +Some of the bound files are checkers in `tools/` -- `h3_rn_n6_check.py` and +`twelve_project_check.py` are pinned by the downstream `rn_bernstein_sharp_variance` +campaign whose replay depends on them, not by the campaigns they enforce -- and +others are documents in `docs/` and `drive/`, 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. diff --git a/research/PINNED_SOURCES.md b/research/PINNED_SOURCES.md index 22e97d56e..830ee71ec 100644 --- a/research/PINNED_SOURCES.md +++ b/research/PINNED_SOURCES.md @@ -24,10 +24,12 @@ bytes were restored and the archive declarations are now read. A "the only way t learn a binding was to break it" page that is itself incomplete is worse than no page, because it is trusted. -**Some of the files below are checkers in `tools/`** — two of them are pinned by -the very campaign they enforce — **and several are documents in `docs/`, -`governance/` and `drive/`.** Counts are in the summary line after the table; -they are computed, not typed. +**Some of the files below are checkers in `tools/`** — `tools/h3_rn_n6_check.py` +and `tools/twelve_project_check.py` are pinned by the downstream +`rn_bernstein_sharp_variance` campaign whose replay depends on them, not by the +campaigns they themselves enforce — **and several are documents in `docs/` and +`drive/`.** Counts are in the summary line after the table; they are computed, +not typed. Before editing anything in this table, read [`tools/pinned_sources_check.py`](../tools/pinned_sources_check.py). The remedy diff --git a/tools/pinned_sources_check.py b/tools/pinned_sources_check.py index fae149495..4d0597251 100644 --- a/tools/pinned_sources_check.py +++ b/tools/pinned_sources_check.py @@ -194,6 +194,14 @@ def dependency_rows(node) -> dict[str, dict]: def enforcing_checkers(root: str) -> set[str]: """tools/ modules that call `repository_inputs(`, i.e. enforce a pin set. + Scope: top-level `tools/*.py` only. A module elsewhere (for example + `research/rn/n6_inputs.py`, which today re-reads the h3 plan that + `tools/h3_rn_n6_check.py` already enforces) is not scanned, so a NEW pin set + enforced only from outside `tools/` would not trip this guard. The guard is + also per checker: it notices a checker missing from ARCHIVE_DEPENDENCY_SOURCES, + not a single missing row for a checker that is still named there — the + index-equality control covers that case. + A literal scan on purpose. The point is to notice a NEW enforcing checker that ARCHIVE_DEPENDENCY_SOURCES does not mention, and a scan that reads the source sees one the moment it lands. `repository_inputs` is also the name of @@ -535,10 +543,12 @@ def verify(root: str, files: dict): learn a binding was to break it" page that is itself incomplete is worse than no page, because it is trusted. -**Some of the files below are checkers in `tools/`** — two of them are pinned by -the very campaign they enforce — **and several are documents in `docs/`, -`governance/` and `drive/`.** Counts are in the summary line after the table; -they are computed, not typed. +**Some of the files below are checkers in `tools/`** — `tools/h3_rn_n6_check.py` +and `tools/twelve_project_check.py` are pinned by the downstream +`rn_bernstein_sharp_variance` campaign whose replay depends on them, not by the +campaigns they themselves enforce — **and several are documents in `docs/` and +`drive/`.** Counts are in the summary line after the table; they are computed, +not typed. Before editing anything in this table, read [`tools/pinned_sources_check.py`](../tools/pinned_sources_check.py). The remedy