diff --git a/registers/CONSUMERS.json b/registers/CONSUMERS.json index 38a4330cd..ecba49c4c 100644 --- a/registers/CONSUMERS.json +++ b/registers/CONSUMERS.json @@ -57,9 +57,9 @@ "counts": { "tabs": 44, "generic_files": 4, - "MACHINE": 23, + "MACHINE": 26, "PROSE_ONLY": 3, - "UNREAD": 18 + "UNREAD": 15 }, "tabs": { "active_work_claims": { @@ -95,6 +95,7 @@ "registers/collision_proposal_2026-09-19.json", "tests/test_collision_proposal.py", "tests/test_operations.py", + "tests/test_register_source_selection.py", "tools/collision_proposal_check.py", "tools/registers_check.py" ], @@ -221,6 +222,7 @@ "registers/KNOWN_FINDINGS.json", "registers/collision_proposal_2026-09-19.json", "tests/test_collision_proposal.py", + "tests/test_register_source_selection.py", "tools/collision_proposal_check.py", "tools/registers_check.py" ], @@ -244,8 +246,10 @@ "class": "MACHINE", "machine": [ "tests/test_frozen_check.py", + "tests/test_register_source_selection.py", "tools/frozen_check.py", - "tools/registers_check.py" + "tools/registers_check.py", + "tools/registers_preflight.py" ], "prose": [ "docs/FINDINGS_2026-09-18.md", @@ -263,8 +267,10 @@ "prose": [] }, "identity_drift_watch": { - "class": "UNREAD", - "machine": [], + "class": "MACHINE", + "machine": [ + "tests/test_register_source_selection.py" + ], "prose": [] }, "lpw_fold_dispositions": { @@ -418,10 +424,13 @@ "engine/lanes/D.json", "tests/test_claims.py", "tests/test_lanes.py", + "tests/test_register_preflight.py", + "tests/test_register_source_selection.py", "tests/test_reviews.py", "tools/closure_pipeline.py", "tools/lanes_check.py", "tools/registers_check.py", + "tools/registers_preflight.py", "tools/reviews_check.py" ], "prose": [ @@ -444,8 +453,10 @@ ] }, "start_here": { - "class": "UNREAD", - "machine": [], + "class": "MACHINE", + "machine": [ + "tests/test_register_source_selection.py" + ], "prose": [] }, "task_gates": { @@ -479,6 +490,7 @@ "engine/receipt.py", "engine/receipts/README.md", "tests/test_bridge.py", + "tests/test_register_source_selection.py", "tools/registers_check.py" ], "prose": [ @@ -488,8 +500,10 @@ ] }, "work_orders": { - "class": "UNREAD", - "machine": [], + "class": "MACHINE", + "machine": [ + "tests/test_register_source_selection.py" + ], "prose": [] } } diff --git a/registers/README.md b/registers/README.md index c33f5d2c6..20b4e09d4 100644 --- a/registers/README.md +++ b/registers/README.md @@ -22,6 +22,40 @@ The Drive's `GP-REG-032-v1.2 — Coupled Research Registers` workbook (Drive id * `EXPORT_DIFF_2026-09-17_to_2026-09-18.json` — the mechanical, every-column diff between the two exports (see *What moved between the two exports*). +## Verified source selection and successor preflight + +Normal import and `--check` now resolve `current_import_source` from +`source/SOURCES.json` at call time. The selected export must have one provenance +record, a safe local XLSX basename, matching SHA-256 and byte count, and +`exact: false` (native Sheet exports are renderings). Missing or ambiguous +metadata, duplicate JSON keys, symlinks, and identity mismatches are refused +before output writes. There is no independent normal-import filename pin. + +The stored Sept 23 R1 successor is **not activated**. Preview it without changing +the current selector, source files, or generated registers: + +```bash +python3 tools/registers_preflight.py \ + --source-name GP-REG-032_v1.2_export_2026-09-23_R1.xlsx > /tmp/register-r1-preview.json +``` + +Exit 0 means the named metadata/form interfaces are compatible; exit 1 reports +blockers; exit 2 means source/read failure. R1 currently returns 1: three source +status phrases are outside the R17 vocabulary (both register and review +checkers expose them); nine new frozen-object IDs lack entries in the older +inventory; two raw-file binding descriptions are uninterpreted. No missing +custody is called MATCH, no phrase is mapped to PASS, and no exception is added +to the live allowlist. The report preserves all diagnostics and states +`canonical_import_completed: false`. The R1 preview compares all 44 tabs and +checks 88 generated files in temporary directories. It is not full mathematical +CI, a scientific verdict, or a replacement governing register. + +Historical replay stays fixed: `--diff-exports` without `--source` retains the +Sept 17 markdown and Sept 18 XLSX inputs. Explicit `--source PATH` remains a +standalone inspection override, not manifest acceptance. Source/consumer +reconciliation must precede activation; owner permission is already supplied +by the standing directive. + Regenerate and verify: ```bash diff --git a/tests/test_register_preflight.py b/tests/test_register_preflight.py new file mode 100644 index 000000000..0bebc478d --- /dev/null +++ b/tests/test_register_preflight.py @@ -0,0 +1,93 @@ +"""Source-bound preflight: observable blockers, no activation or scientific verdict.""" +from __future__ import annotations + +import json +from pathlib import Path +import sys + +import pytest + +ROOT = Path(__file__).resolve().parents[1] +sys.path.insert(0, str(ROOT / "tools")) +import registers_preflight as PF +import registers_import as RI + +R1 = "GP-REG-032_v1.2_export_2026-09-23_R1.xlsx" + + +def test_current_snapshot_passes_only_covered_interfaces(): + report = PF.preview(Path(RI.resolve_current_source()).name) + assert report["compatible_for_covered_interfaces"] is True + assert not any(report["blockers"].values()) + assert report["comparison"]["changed_cells"] == [] + assert report["protected_files_unchanged"] is True + assert report["canonical_import_completed"] is False + assert report["scientific_status_changed"] is False + + +def test_r1_has_exact_unresolved_interfaces_and_never_activates(): + before = Path(RI.SOURCE_MANIFEST).read_bytes() + report = PF.preview(R1) + assert report["proposed_identity"] == {"bytes": 1979318, "sha256": + "6cec54cefa3ee8f9885dcfd763407a2e0274d2887d73bdc23ccc7793cd721469"} + assert report["tabs"] == 44 and report["generated_files_checked"] == 88 + assert report["row_counts"]["review_queue"] == 40 + assert {k: len(v) for k, v in report["blockers"].items()} == { + "transcription": 0, "register_structure": 3, "stale_known_findings": 0, + "bound_observations": 0, "review_interface": 3, "frozen_interface": 11} + assert report["frozen_status_counts"]["MATCH"] == 62 + assert report["frozen_status_counts"]["DRIVE_ID_NOT_IN_INVENTORY"] == 9 + assert report["frozen_status_counts"]["UNKNOWN_CLASS"] == 2 + assert report["frozen_status_counts"].get("MISMATCH", 0) == 0 + assert report["compatible_for_covered_interfaces"] is False + assert report["canonical_import_completed"] is False + assert report["scientific_status_changed"] is False + assert report["protected_files_unchanged"] is True + assert Path(RI.SOURCE_MANIFEST).read_bytes() == before + assert Path(RI.resolve_current_source()).name.endswith("2026-09-18.xlsx") + + +@pytest.mark.parametrize("name", ["../outside.xlsx", "not-declared.xlsx", "SOURCES.json"]) +def test_undeclared_or_unsafe_candidate_is_refused_before_preview(name): + with pytest.raises(RI.SourceError): + PF.preview(name) + + +def test_cli_exit_one_for_blockers_not_success(capsys): + assert PF.main(["--source-name", R1]) == 1 + report = json.loads(capsys.readouterr().out) + assert report["compatible_for_covered_interfaces"] is False + + +def test_cli_exit_two_for_source_failure(capsys): + assert PF.main(["--source-name", "not-declared.xlsx"]) == 2 + output = capsys.readouterr() + assert output.out == "" + assert json.loads(output.err)["canonical_import_completed"] is False + + +def test_record_form_error_is_not_hidden(monkeypatch): + monkeypatch.setattr(PF.RV, "check_all", lambda *args: ["deliberate invalid review form"]) + report = PF.preview(Path(RI.resolve_current_source()).name) + assert report["blockers"]["review_interface"] == ["deliberate invalid review form"] + assert report["compatible_for_covered_interfaces"] is False + + +def test_new_digest_mismatch_is_not_hidden(monkeypatch): + original = PF.FZ.check + def changed(*args): + rows, problems = original(*args) + rows.append({"status": "MISMATCH"}) + return rows, problems + ["deliberate whole-file digest mismatch"] + monkeypatch.setattr(PF.FZ, "check", changed) + report = PF.preview(Path(RI.resolve_current_source()).name) + assert report["blockers"]["frozen_interface"] == ["deliberate whole-file digest mismatch"] + assert report["frozen_status_counts"]["MISMATCH"] == 1 + assert report["compatible_for_covered_interfaces"] is False + + +def test_observation_drift_is_not_hidden(monkeypatch): + monkeypatch.setattr(PF.RC, "check_observations", lambda *args: (["deliberate observation drift"], 45)) + report = PF.preview(Path(RI.resolve_current_source()).name) + assert report["blockers"]["bound_observations"] == ["deliberate observation drift"] + assert report["compatible_for_covered_interfaces"] is False diff --git a/tests/test_register_source_selection.py b/tests/test_register_source_selection.py new file mode 100644 index 000000000..4134f69ff --- /dev/null +++ b/tests/test_register_source_selection.py @@ -0,0 +1,189 @@ +"""Manifest-bound import, immutable historical replay, and exact R1 source controls. + +These tests establish export identity and transcription, never mathematics or +review acceptance. Explicit --source remains a standalone inspection override. +""" +from __future__ import annotations + +import copy +import hashlib +import json +from pathlib import Path +import sys + +import pytest + +ROOT = Path(__file__).resolve().parents[1] +sys.path.insert(0, str(ROOT / "tools")) +import registers_import as RI +import registers_check as RC + +R1_NAME = "GP-REG-032_v1.2_export_2026-09-23_R1.xlsx" +R1 = ROOT / "registers/source" / R1_NAME +R1_SHA256 = "6cec54cefa3ee8f9885dcfd763407a2e0274d2887d73bdc23ccc7793cd721469" +ADDITIONS = {"start_here": 3, "review_queue": 15, "work_events": 131, + "artifact_index": 11, "evidence_lineage": 12, "work_orders": 1, + "frozen_objects": 11, "identity_drift_watch": 11} +EXPECTED_PHRASES = { + 34: ("RV-WITHDRAWAL-20260921-01", "OPEN / NONAUTHOR TECHNICAL REVIEW REQUIRED"), + 35: ("RV-ROLLOUT-R2-20260921-01", "OPEN / NONAUTHOR TECHNICAL REVIEW REQUIRED"), + 36: ("RV-H3-SOLVER-20260921-01", "OPEN / NONAUTHOR MATHEMATICAL AND SOFTWARE REVIEW REQUIRED"), +} + + +@pytest.fixture +def declared(tmp_path): + data = b"identity-only fixture: not a workbook" + source = tmp_path / "fixture.xlsx" + source.write_bytes(data) + manifest = {"drive_object": {"id": RI.DRIVE_OBJECT_ID}, + "current_import_source": source.name, + "exports": [{"file": source.name, "bytes": len(data), + "sha256": hashlib.sha256(data).hexdigest(), "exact": False}]} + path = tmp_path / "SOURCES.json" + path.write_text(json.dumps(manifest), encoding="utf-8") + return path, source, manifest + + +def test_manifest_chooses_exactly_its_declared_source(declared): + path, source, _ = declared + before = source.read_bytes(), path.read_bytes() + assert RI.resolve_current_source(str(path)) == str(source) + assert before == (source.read_bytes(), path.read_bytes()) + + +@pytest.mark.parametrize("mutation", [ + "missing_selector", "path_traversal", "absolute_path", "windows_path", "nul_path", + "wrong_suffix", "no_exports", "exports_not_list", "record_not_object", "absent_record", + "duplicate_record", "wrong_object", "missing_object", "wrong_hash", "uppercase_hash", + "wrong_size", "boolean_size", "string_size", "zero_size", "negative_size", + "exact_true", "exact_missing", "exact_zero", +]) +def test_invalid_manifest_is_refused_without_writes(declared, mutation): + path, source, original = declared + m = copy.deepcopy(original) + e = m["exports"][0] + if mutation == "missing_selector": m.pop("current_import_source") + elif mutation == "path_traversal": m["current_import_source"] = "../fixture.xlsx" + elif mutation == "absolute_path": m["current_import_source"] = str(source) + elif mutation == "windows_path": m["current_import_source"] = r"C:\fixture.xlsx" + elif mutation == "nul_path": m["current_import_source"] = "fixture\0.xlsx" + elif mutation == "wrong_suffix": m["current_import_source"] = "fixture.json" + elif mutation == "no_exports": m.pop("exports") + elif mutation == "exports_not_list": m["exports"] = {} + elif mutation == "record_not_object": m["exports"] = [1] + elif mutation == "absent_record": e["file"] = "other.xlsx" + elif mutation == "duplicate_record": m["exports"].append(dict(e)) + elif mutation == "wrong_object": m["drive_object"]["id"] = "different-native-sheet" + elif mutation == "missing_object": m.pop("drive_object") + elif mutation == "wrong_hash": e["sha256"] = "0" * 64 + elif mutation == "uppercase_hash": e["sha256"] = e["sha256"].upper() + elif mutation == "wrong_size": e["bytes"] += 1 + elif mutation == "boolean_size": e["bytes"] = True + elif mutation == "string_size": e["bytes"] = str(e["bytes"]) + elif mutation == "zero_size": e["bytes"] = 0 + elif mutation == "negative_size": e["bytes"] = -1 + elif mutation == "exact_true": e["exact"] = True + elif mutation == "exact_missing": e.pop("exact") + elif mutation == "exact_zero": e["exact"] = 0 + else: raise AssertionError(mutation) + path.write_text(json.dumps(m), encoding="utf-8") + before = source.read_bytes(), path.read_bytes() + with pytest.raises(RI.SourceError): + RI.resolve_current_source(str(path)) + assert before == (source.read_bytes(), path.read_bytes()) + + +@pytest.mark.parametrize("text", ["[]", "null", "{", '{"x":1,"x":2}', + '{"outer":{"sha256":"a","sha256":"b"}}']) +def test_malformed_and_duplicate_key_json_is_refused(tmp_path, text): + path = tmp_path / "SOURCES.json" + path.write_text(text) + with pytest.raises(RI.SourceError): + RI.resolve_current_source(str(path)) + + +@pytest.mark.parametrize("mutation", ["missing_manifest", "missing_export", "symlink_export", "corrupt_export"]) +def test_missing_or_changed_source_is_refused(declared, mutation): + path, source, _ = declared + if mutation == "missing_manifest": path.unlink() + elif mutation == "missing_export": source.unlink() + elif mutation == "symlink_export": + original = source.with_name("original.xlsx") + source.rename(original) + source.symlink_to(original) + else: source.write_bytes(b"corrupt") + with pytest.raises(RI.SourceError): + RI.resolve_current_source(str(path)) + + +def test_default_resolution_happens_at_call_time(declared, monkeypatch): + path, source, _ = declared + monkeypatch.setattr(RI, "SOURCE_MANIFEST", str(path)) + assert RI.resolve_current_source() == str(source) + path.unlink() + with pytest.raises(RI.SourceError): + RI.resolve_current_source() + + +def test_bad_manifest_prevents_output_creation(tmp_path, monkeypatch): + monkeypatch.setattr(RI, "SOURCE_MANIFEST", str(tmp_path / "missing.json")) + j, c = tmp_path / "json", tmp_path / "csv" + assert RI.main(["--out-json", str(j), "--out-csv", str(c)]) == 2 + assert not j.exists() and not c.exists() + + +def test_explicit_source_is_standalone_and_not_false_manifest_acceptance(tmp_path, monkeypatch): + monkeypatch.setattr(RI, "SOURCE_MANIFEST", str(tmp_path / "missing.json")) + j, c = tmp_path / "json", tmp_path / "csv" + args = ["--source", str(R1), "--out-json", str(j), "--out-csv", str(c)] + assert RI.main(args) == 0 + assert RI.main(args + ["--check"]) == 0 + + +def test_historical_diff_default_does_not_follow_current_selector(tmp_path, monkeypatch): + monkeypatch.setattr(RI, "SOURCE_MANIFEST", str(tmp_path / "missing.json")) + out = tmp_path / "historical.json" + assert RI.main(["--diff-exports", str(out)]) == 0 + assert out.read_bytes() == Path(RI.EXPORT_DIFF).read_bytes() + + +def test_r1_identity_preview_outputs_and_immutable_baseline(tmp_path): + assert RI.resolve_current_source() == RI.SOURCE + assert RI.resolve_declared_source(export_name=R1_NAME) == str(R1) + assert len(R1.read_bytes()) == 1979318 + assert hashlib.sha256(R1.read_bytes()).hexdigest() == R1_SHA256 + old, current = RI.parse(RI.SOURCE), RI.parse(str(R1)) + assert len(current) == 44 + j, c = str(tmp_path / "json"), str(tmp_path / "csv") + RI.write(current, j, c) + assert RI.check(current, j, c) == [] + d = {"comparison": RI.export_diff(old, current)} + assert d["comparison"]["summary"]["rows_added"] == ADDITIONS + assert len(d["comparison"]["changed_cells"]) == 27 + assert d["comparison"]["rows_removed"] == {} + assert d["comparison"]["header_changes"] == [] + assert d["comparison"]["status_word_changes"] == [] + before = next(t for t in old if t["tab"] == "work_events") + after = next(t for t in current if t["tab"] == "work_events") + assert after["rows"][:len(before["rows"])] == before["rows"] + assert len(after["rows"]) == 166 + rq = next(t for t in current if t["tab"] == "review_queue") + assert len(rq["rows"]) == 40 and len({r[0] for r in rq["rows"]}) == 40 + + +def test_new_findings_remain_unresolved_not_new_allowed_statuses(tmp_path): + current = RI.parse(str(R1)) + rq = next(t for t in current if t["tab"] == "review_queue") + expected = set() + for i, (key, phrase) in EXPECTED_PHRASES.items(): + assert rq["rows"][i][0] == key + assert rq["rows"][i][rq["header"].index("Technical status")] == phrase + assert phrase not in RC.R17_TECH_STATUS + expected.add(f"review_queue: row {i} status {phrase!r} not in R17 set") + j, c = str(tmp_path / "json"), str(tmp_path / "csv") + RI.write(current, j, c) + problems, _ = RC.check(j) + known = RC.load_known(str(ROOT / "registers/KNOWN_FINDINGS.json")) + assert set(problems) - set(known) == expected + assert not (expected & set(known)), "preview must not silently allowlist its own blockers" diff --git a/tools/registers_import.py b/tools/registers_import.py index 5203a1638..9cce441c7 100644 --- a/tools/registers_import.py +++ b/tools/registers_import.py @@ -4,6 +4,14 @@ Source ------ +Normal import and --check read current_import_source from SOURCES.json and verify +its unique provenance, byte count and SHA-256 before parsing. --source is an +explicit inspection override, not a claim of manifest acceptance. The retained +SOURCE constant and default --diff-exports still mean the frozen Sept 18 input; +a future refresh does not rewrite the Sept 17-to-Sept 18 historical comparison. +This mechanism verifies source identity and transcription, not mathematical truth. + +Historical baseline: The source is an ``.xlsx`` export of the live Google Sheet ``GP-REG-032-v1.2 — Coupled Research Registers`` (Drive id ``1O6x8ivmaVUxYqKmCOXmToIHpMXqDI362ibqBl8HY8no``), taken 2026-09-18 and kept @@ -105,6 +113,7 @@ import argparse import csv import filecmp +import hashlib import json import os import re @@ -117,7 +126,11 @@ from decimal import ROUND_HALF_UP, Decimal, InvalidOperation ROOT = os.path.dirname(os.path.dirname(os.path.abspath(__file__))) +# Historical comparison input, retained for standalone replay compatibility. +# Normal imports resolve SOURCES.json at call time; never infer "latest" from names. SOURCE = os.path.join(ROOT, "registers", "source", "GP-REG-032_v1.2_export_2026-09-18.xlsx") +SOURCE_MANIFEST = os.path.join(ROOT, "registers", "source", "SOURCES.json") +DRIVE_OBJECT_ID = "1O6x8ivmaVUxYqKmCOXmToIHpMXqDI362ibqBl8HY8no" OUT_JSON = os.path.join(ROOT, "registers", "json") OUT_CSV = os.path.join(ROOT, "registers", "csv") MARKDOWN_SOURCE = os.path.join(ROOT, "registers", "source", "GP-REG-032_v1.2_export_2026-09-17.md") @@ -189,6 +202,79 @@ class SourceError(Exception): """The source does not match what this importer is built for (exit 2).""" +def _unique_object(pairs: list[tuple[str, object]]) -> dict: + """Reject ambiguous manifests rather than accepting JSON's last-key-wins rule.""" + result: dict = {} + for key, value in pairs: + if key in result: + raise SourceError(f"duplicate manifest key: {key!r}") + result[key] = value + return result + + +def resolve_declared_source(manifest_path: str | None = None, + export_name: str | None = None) -> str: + """Resolve and verify one declared export; this verifies custody, not science. + + Missing/ambiguous declarations, unsafe paths, symlinks, identity mismatches, + and claims that a native Sheet export is exact all fail before output writes. + Explicit --source remains a standalone inspection/replay override. + """ + manifest_path = SOURCE_MANIFEST if manifest_path is None else manifest_path + try: + with open(manifest_path, encoding="utf-8") as f: + manifest = json.load(f, object_pairs_hook=_unique_object) + except (OSError, UnicodeError, json.JSONDecodeError) as exc: + raise SourceError(f"cannot read source manifest: {exc}") from exc + if not isinstance(manifest, dict): + raise SourceError("source manifest must be an object") + source_object = manifest.get("drive_object") + if not isinstance(source_object, dict) or source_object.get("id") != DRIVE_OBJECT_ID: + raise SourceError("source manifest names the wrong native Drive object") + name = manifest.get("current_import_source") if export_name is None else export_name + if (not isinstance(name, str) or not name.endswith(".xlsx") + or name in (".xlsx", "..xlsx") or "/" in name or "\\" in name + or ":" in name or "\0" in name): + raise SourceError("current_import_source must be a local .xlsx basename") + exports = manifest.get("exports") + if not isinstance(exports, list) or not all(isinstance(e, dict) for e in exports): + raise SourceError("source manifest exports must be a list of objects") + matches = [e for e in exports if e.get("file") == name] + if len(matches) != 1: + raise SourceError("current_import_source must have exactly one provenance record") + record = matches[0] + digest, size = record.get("sha256"), record.get("bytes") + if not isinstance(digest, str) or re.fullmatch(r"[0-9a-f]{64}", digest) is None: + raise SourceError("selected export must have a lowercase SHA-256 digest") + if type(size) is not int or size <= 0: + raise SourceError("selected export must have a positive integer byte count") + if record.get("exact") is not False: + raise SourceError("a native Sheet export must declare exact=false") + directory = os.path.realpath(os.path.dirname(os.path.abspath(manifest_path))) + candidate = os.path.join(directory, name) + if os.path.islink(candidate) or os.path.realpath(candidate) != candidate: + raise SourceError("selected export must not be a symlink") + if not os.path.isfile(candidate): + raise SourceError(f"selected export is missing: {name}") + try: + actual_size = 0 + actual_digest = hashlib.sha256() + with open(candidate, "rb") as f: + for block in iter(lambda: f.read(1024 * 1024), b""): + actual_size += len(block) + actual_digest.update(block) + except OSError as exc: + raise SourceError(f"cannot read selected export: {exc}") from exc + if actual_size != size or actual_digest.hexdigest() != digest: + raise SourceError(f"selected export identity mismatch: {name}") + return candidate + + +def resolve_current_source(manifest_path: str | None = None) -> str: + """Verify the current selector; an explicit successor preview never changes it.""" + return resolve_declared_source(manifest_path) + + def column_index(ref: str) -> int | None: """'A' -> 0, 'Z' -> 25, 'AA' -> 26; None when the reference is unreadable.""" m = CELL_REF.match(ref or "") @@ -636,7 +722,7 @@ def main(argv: list[str] | None = None) -> int: ap = argparse.ArgumentParser(description=__doc__.splitlines()[0]) ap.add_argument("--check", action="store_true", help="regenerate to a temp dir and fail if the committed outputs differ") - ap.add_argument("--source", default=SOURCE, help="the .xlsx workbook export to read") + ap.add_argument("--source", default=None, help="explicit .xlsx inspection/replay source; default: verified SOURCES.json selector") ap.add_argument("--out-json", default=OUT_JSON) ap.add_argument("--out-csv", default=OUT_CSV) ap.add_argument("--diff-exports", nargs="?", const=EXPORT_DIFF, default=None, metavar="PATH", @@ -646,6 +732,10 @@ def main(argv: list[str] | None = None) -> int: help="the 2026-09-17 markdown export, the old side of --diff-exports") args = ap.parse_args(argv) try: + # The dated markdown-to-XLSX diff is immutable history, not a live view. + # An explicit --source is required to compare that markdown with a successor. + if args.source is None: + args.source = SOURCE if args.diff_exports else resolve_current_source() tabs = parse(args.source) except SourceError as exc: print(f"registers_import: refusing the source: {exc}", file=sys.stderr) diff --git a/tools/registers_preflight.py b/tools/registers_preflight.py new file mode 100644 index 000000000..ab00ace21 --- /dev/null +++ b/tools/registers_preflight.py @@ -0,0 +1,110 @@ +#!/usr/bin/env python3 +"""Preview a declared register successor without activating it or editing a checkout. + +Output is a diagnostic, not a governing register or mathematical verdict. The +normal import selector, all source exports, and live JSON/CSV remain untouched. +The preview checks transcription, register observations, review form, and frozen +source-map compatibility; it does not execute every mathematical CI command. + +Usage: python3 tools/registers_preflight.py --source-name FILE.xlsx > /tmp/preview.json +Exit 0: covered interfaces compatible; 1: explicit blockers; 2: source/read error. +""" +from __future__ import annotations + +import argparse +from collections import Counter +import hashlib +import json +from pathlib import Path +import sys +import tempfile + +import registers_import as RI +import registers_check as RC +import reviews_check as RV +import frozen_check as FZ + + +def identity(path: str | Path) -> dict: + p = Path(path) + data = p.read_bytes() + return {"bytes": len(data), "sha256": hashlib.sha256(data).hexdigest()} + + +def preview(source_name: str) -> dict: + """Evaluate one provenance-declared export; diagnostics are never suppressed.""" + source = RI.resolve_declared_source(export_name=source_name) + current = RI.resolve_current_source() + protected = [Path(RI.SOURCE_MANIFEST), Path(current), Path(source)] + protected += sorted(Path(RI.OUT_JSON).glob("*.json")) + protected += sorted(Path(RI.OUT_CSV).glob("*.csv")) + before = {str(p): identity(p) for p in protected} + old, proposed = RI.parse(current), RI.parse(source) + delta = RI.export_diff(old, proposed) + with tempfile.TemporaryDirectory(prefix="register-preflight-") as tmp: + j, c = Path(tmp) / "json", Path(tmp) / "csv" + RI.write(proposed, str(j), str(c)) + drift = RI.check(proposed, str(j), str(c)) + structural, tab_count = RC.check(str(j)) + known = RC.load_known(RC.KNOWN_PATH) + new_structural = [p for p in structural if p not in known] + dead = sorted(set(known) - set(structural)) + obs_problems, bindings = RC.check_observations( + RC.load_observations(RC.KNOWN_PATH), str(j), + RC.INVENTORY_PATH, RC.PATH_CHANGES_PATH) + review_problems = RV.check_all(RV.RECORDS_DIR, RV.SCHEMA_PATH, + str(j / "review_queue.json")) + review_problems += RV.check_companion_prose(RV.RECORDS_DIR) + frozen_rows, frozen_problems = FZ.check( + str(j / "frozen_objects.json"), FZ.DEFAULT_INVENTORY, + FZ.DEFAULT_PAYLOADS, FZ.DEFAULT_MEMBERS) + # Remove only machine-dependent temp-directory prefixes from diagnostics. + # No source text, status, classification, or problem is changed. + import os + temp_relative = os.path.relpath(tmp, RI.ROOT) + review_problems = [p.replace(tmp, "").replace(temp_relative, "") + for p in review_problems] + after = {str(p): identity(p) for p in protected} + if after != before: + raise RI.SourceError("preflight input changed during inspection") + blockers = {"transcription": drift, "register_structure": new_structural, + "stale_known_findings": dead, "bound_observations": obs_problems, + "review_interface": review_problems, "frozen_interface": frozen_problems} + compatible = not any(blockers.values()) + return { + "schema": "q0.register-preflight/v1", + "current_source": Path(current).name, + "proposed_source": Path(source).name, + "current_identity": identity(current), "proposed_identity": identity(source), + "snapshot_only": True, "tabs": tab_count, "generated_files_checked": 2 * tab_count, + "row_counts": {t["tab"]: len(t["rows"]) for t in proposed}, + "comparison": delta, + "bound_observations_checked": bindings, + "frozen_status_counts": dict(sorted(Counter(r["status"] for r in frozen_rows).items())), + "blockers": blockers, "compatible_for_covered_interfaces": compatible, + "protected_files_checked": len(before), "protected_files_unchanged": True, + "canonical_import_completed": False, "scientific_status_changed": False, + "does_not_establish": "No activation, source repair, review filing, full repository CI, " + "mathematical correctness, or independence credit. A compatible " + "preview covers only the named metadata/form interfaces; R1 is a " + "dated snapshot, not current live Drive state.", + } + + +def main(argv: list[str] | None = None) -> int: + ap = argparse.ArgumentParser(description=__doc__.splitlines()[0]) + ap.add_argument("--source-name", required=True, + help="an XLSX basename declared in registers/source/SOURCES.json") + args = ap.parse_args(argv) + try: + report = preview(args.source_name) + except (RI.SourceError, OSError, ValueError, KeyError, TypeError) as exc: + print(json.dumps({"error": str(exc), "canonical_import_completed": False, + "scientific_status_changed": False}), file=sys.stderr) + return 2 + print(json.dumps(report, ensure_ascii=False, indent=2)) + return 0 if report["compatible_for_covered_interfaces"] else 1 + + +if __name__ == "__main__": + raise SystemExit(main())