diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index 9bad97df7..bec90a5af 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -35,6 +35,8 @@ jobs: run: python tools/withdrawal_check.py check --before governance/withdrawal/examples/before.json --after governance/withdrawal/examples/after.json --ticket governance/withdrawal/examples/ticket.json - name: Governance rollout shadow controls (no live admission) run: python tools/rollout_guard.py governance/rollout/SYNTHETIC_metadata_plan.json + - name: Every float path is labelled NON-CERTIFYING, or declared with a reason + run: python tools/noncertifying_check.py - name: Logical quarantine is enforced run: python tools/quarantine_check.py - name: Vault listing matches inventory; vault ids stay unstored diff --git a/CLAUDE.md b/CLAUDE.md index c5a52de17..092a725dc 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -55,6 +55,30 @@ 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. +## If you compute in floats, say so + +`tools/noncertifying_check.py` runs in CI. Every repository-authored Python file +holding a float literal or a `float(` call must either contain the canonical +label `NON-CERTIFYING` or be named in the checker's `DECLARED` with the reason it +needs none. Exact rational arithmetic (`fractions.Fraction`) is the default +wherever a bound is claimed; a float that reaches a printed or compared number is +a display, and it must say so in the code *and in the output*. + +**A float is not always a float path**, and this matters more here than the rule +itself. Most float sites in this tree are **rejection probes**: the float is the +input a checker must REFUSE, and the test asserts the refusal. Pasting +`NON-CERTIFYING` onto such a file would state the opposite of what the file +demonstrates, so those are declared with the line they refuse, never labelled. +Wall-clock values (poll intervals, timeouts, elapsed seconds) are declared too. A +declaration is a claim a reviewer can check; silence is not, and a label that is +false is worse than either. + +Two cases are recorded as **unmet** obligations rather than absent ones: +`research/bands/ladder.py` and `research/rn/moment_envelope.py` both print float +conversions and both are pinned, so the label cannot be written into their bytes. +The declarations say so, with the pin that binds each, because a reader needs to +know the obligation exists. + ## Technical navigation Start with [README.md](README.md), [RESEARCH_MAP](docs/RESEARCH_MAP.md) and diff --git a/tests/test_noncertifying.py b/tests/test_noncertifying.py new file mode 100644 index 000000000..07ac0c18d --- /dev/null +++ b/tests/test_noncertifying.py @@ -0,0 +1,365 @@ +"""Negative controls for ``tools/noncertifying_check.py``. + +The checker exists because the `CLAUDE.md` Engineering-conventions bullet -- +"Where a path does compute in floats ... label it NON-CERTIFYING in the code and +in its output" -- was enforced by discipline only: two tools handled the string +at single sites (`math_status_check.py` requires a field to equal it, +`rn_bernstein_sharp_check.py` emits it) but none asked whether a file with a +float site carried the label. Printed output is still not checked. On this line +forty-one repository-authored files hold a float literal or a `float(` call and +twenty-four carried no label; six spellings of the word were in use. + +Reading all twenty-four changed the shape of the fix, and group 4 below is the +consequence: sixteen of them use a float ONLY as a REJECTION PROBE, so the +banner would be a FALSE statement about the file. Those are declared, and a +control asserts that a declaration is not interchangeable with a label. + +Each control runs the checker through its CLI against synthetic files, so a +path or a pattern bound at import time cannot silently re-check the real tree. +""" +from __future__ import annotations + +import os +import subprocess +import sys + +import pytest + +ROOT = os.path.dirname(os.path.dirname(os.path.abspath(__file__))) +CHECKER = os.path.join(ROOT, "tools", "noncertifying_check.py") + +sys.path.insert(0, os.path.join(ROOT, "tools")) +import noncertifying_check as NCC # noqa: E402 + + +def run(root, *files): + args = [sys.executable, CHECKER, "--root", root] + for f in files: + args += ["--file", f] + return subprocess.run(args, capture_output=True, text=True) + + +def write(tmp_path, name, body): + (tmp_path / name).write_text(body, encoding="utf-8") + return str(tmp_path), name + + +# --------------------------------------------------------------------------- +# 1. The rule +# --------------------------------------------------------------------------- + +def test_an_unlabelled_float_literal_is_refused(tmp_path): + root, name = write(tmp_path, "m.py", "def f():\n return 0.5\n") + out = run(root, name) + assert out.returncode == 1, out.stdout + assert "float site" in out.stdout and "NON-CERTIFYING" in out.stdout + + +def test_an_unlabelled_float_call_is_refused(tmp_path): + root, name = write(tmp_path, "m.py", "def f(x):\n return float(x)\n") + out = run(root, name) + assert out.returncode == 1, out.stdout + + +def test_a_labelled_float_path_passes(tmp_path): + root, name = write(tmp_path, "m.py", + 'def f(x):\n """NON-CERTIFYING display."""\n' + " return float(x)\n") + out = run(root, name) + assert out.returncode == 0, out.stdout + assert "with_float_sites=1" in out.stdout + + +def test_a_file_with_no_float_site_needs_no_label(tmp_path): + root, name = write(tmp_path, "m.py", + "from fractions import Fraction\n\n\n" + "def f():\n return Fraction(1, 2)\n") + out = run(root, name) + assert out.returncode == 0, out.stdout + assert "with_float_sites=0" in out.stdout + + +def test_a_float_inside_a_docstring_is_text_not_a_float(tmp_path): + """The numbers quoted in prose throughout this repository are strings.""" + root, name = write(tmp_path, "m.py", + 'def f():\n """The value is 6.239e-44 exactly."""\n' + " return 1\n") + out = run(root, name) + assert out.returncode == 0, out.stdout + assert "with_float_sites=0" in out.stdout + + +# --------------------------------------------------------------------------- +# 2. Spelling +# --------------------------------------------------------------------------- + +def test_a_prose_misspelling_without_the_canonical_label_is_refused(tmp_path): + root, name = write(tmp_path, "m.py", + 'def f():\n """This path is non_certifying."""\n' + " return 1\n") + out = run(root, name) + assert out.returncode == 1, out.stdout + assert "spelled" in out.stdout + + +def test_an_identifier_spelling_beside_the_canonical_label_is_allowed(tmp_path): + """A hyphen cannot appear in a Python name, so both must coexist.""" + root, name = write(tmp_path, "m.py", + 'NON_CERTIFYING = True\n\n\ndef f():\n' + ' """NON-CERTIFYING float display."""\n' + " return float(1)\n") + out = run(root, name) + assert out.returncode == 0, out.stdout + + +def test_a_longer_identifier_is_not_the_label_misspelled(tmp_path): + """`float_noncertifying` is a receipt FIELD NAME. This was a false positive.""" + root, name = write(tmp_path, "m.py", + 'def f():\n """Counts float_noncertifying rows."""\n' + " return 1\n") + out = run(root, name) + assert out.returncode == 0, out.stdout + assert "identifier_uses=0" in out.stdout + + +# --------------------------------------------------------------------------- +# 3. Declarations +# --------------------------------------------------------------------------- + +def test_the_declared_files_all_exist_and_still_need_their_declaration(): + out = run(ROOT) + assert out.returncode == 0, out.stdout + assert NCC.DECLARED, "an empty exemption list would make the rule vacuous" + for rel, reason in NCC.DECLARED.items(): + assert os.path.isfile(os.path.join(ROOT, rel)), rel + assert len(reason) > 40, f"{rel}: the reason must say something" + + +def test_a_declaration_for_a_file_with_no_float_is_refused(tmp_path, monkeypatch): + """A stale exemption hides the next real one.""" + root, name = write(tmp_path, "m.py", "def f():\n return 1\n") + scanned, floats, ident, problems = NCC.audit(root, [name]) + assert not problems + monkeypatch.setitem(NCC.DECLARED, name, "x" * 50) + scanned, floats, ident, problems = NCC.audit(root, [name]) + assert any("has none" in p for p in problems), problems + + +def test_a_declaration_for_a_file_that_is_labelled_is_refused(tmp_path, monkeypatch): + root, name = write(tmp_path, "m.py", + 'def f():\n """NON-CERTIFYING."""\n return 0.5\n') + monkeypatch.setitem(NCC.DECLARED, name, "x" * 50) + _, _, _, problems = NCC.audit(root, [name]) + assert any("carries one" in p for p in problems), problems + + +def test_a_declaration_for_a_missing_file_is_refused(tmp_path, monkeypatch): + """Checked on a default-roots run: an explicit --file list scopes it away.""" + monkeypatch.setitem(NCC.DECLARED, "not/here.py", "x" * 50) + _, _, _, problems = NCC.audit(str(tmp_path)) + assert any("not/here.py" in p and "not in the tree" in p for p in problems), problems + + +def test_an_empty_tree_is_a_vacuous_run_and_is_refused(tmp_path): + """The same lesson `verify_manifests.py` learned: scanning nothing is not a pass.""" + out = run(str(tmp_path)) + assert out.returncode == 1, out.stdout + assert "VACUOUS RUN" in out.stdout + assert "files=0" in out.stdout + + +# --------------------------------------------------------------------------- +# 4. Scope, stated rather than assumed +# --------------------------------------------------------------------------- + +def test_ported_bytes_are_out_of_scope(): + """Blobs and frozen bodies are byte-exact copies and are never edited.""" + for rel in ("engine/carriers/blobs", "engine/rn_engine/frozen"): + assert NCC.is_excluded(rel + "/x.py") + assert not NCC.is_excluded("research/cover/driver.py") + + +def test_the_scanner_is_not_vacuous(): + files = NCC.python_files(ROOT) + assert len(files) > 60 + assert "tools/noncertifying_check.py" in files + # A substring exclusion once dropped these two because their NAMES contain + # an excluded directory word; they are repository-authored and must be scanned. + assert "tools/quarantine_check.py" in files + assert "tests/test_quarantine_digest_coverage.py" in files + assert not any("blobs" in f for f in files) + assert not any(f.startswith(("sandbox/", "legacy/", "quarantine/")) for f in files) + + +def test_the_repository_passes_and_actually_found_float_sites(): + out = run(ROOT) + assert out.returncode == 0, out.stdout + assert "problems=0" in out.stdout + n = int(out.stdout.split("with_float_sites=")[1].split()[0]) + assert n >= 38, f"only {n} files with float sites; the tree had 41" + + +def test_the_one_file_that_could_be_labelled_carries_the_label(): + """Two files compute in floats where it matters; only one is editable. + + `research/rn/moment_envelope.py` and `research/bands/ladder.py` are both + PINNED, so neither can carry the banner in its bytes. Both are declared as + UNMET obligations by the test below rather than as absent ones. + """ + rel = "tests/test_rn_moment_envelope.py" + with open(os.path.join(ROOT, rel), encoding="utf-8") as f: + assert NCC.LABEL in f.read(), rel + + +def test_both_pinned_display_paths_are_declared_as_unmet_obligations(): + """The honest cases, and the ones a silent exclusion would have hidden: each + owes the label under the float-labelling rule and cannot carry it.""" + for rel in ("research/bands/ladder.py", "research/rn/moment_envelope.py"): + reason = NCC.DECLARED[rel] + assert "PINNED" in reason, rel + assert "cannot be added in place" in reason, rel + with open(os.path.join(ROOT, rel), encoding="utf-8") as f: + assert NCC.LABEL not in f.read(), rel # the bytes are untouched + + +def test_the_pinned_moment_envelope_bytes_match_the_archive_member_pin(): + """The control that would have stopped this branch adding a label to pinned + bytes, and did not exist because `research/PINNED_SOURCES.md` does not cover + pins declared inside an ARCHIVE MEMBER. `tools/rn_bernstein_sharp_check.py` + caught it on the CI replay instead, with "repository dependency mismatch". + + Asserted here against the archive itself, so a future edit to this file fails + in a test named after the reason rather than inside a campaign replay. + """ + import hashlib + import json + import zipfile + archive = os.path.join( + ROOT, "research", "campaigns", + "rn_bernstein_sharp_variance_20260921_v1.zip") + with zipfile.ZipFile(archive) as z: + deps = json.loads(z.read("bernstein/DEPENDENCIES.json")) + # `files` is a path -> {bytes, sha256} MAPPING in this member; the sibling + # `sharp_variance/DEPENDENCIES.json` uses the same shape. Both forms are + # handled so this control does not break on the other one. + files = deps["files"] + rows = (files if isinstance(files, dict) + else {r["path"]: r for r in files}) + rel = "research/rn/moment_envelope.py" + assert rel in rows, sorted(rows)[:5] + raw = open(os.path.join(ROOT, rel), "rb").read() + assert len(raw) == rows[rel]["bytes"], (len(raw), rows[rel]["bytes"]) + assert hashlib.sha256(raw).hexdigest() == rows[rel]["sha256"] + # The index a contributor would consult either omits this file -- the gap that + # cost a broken pin, recorded rather than papered over -- or names it with the + # SAME digest, once the index learns to read archive-member declarations. + # + # Asserted as an invariant rather than as the transient state on purpose. The + # first version asserted `"moment_envelope" not in` the index, which made this + # control incompatible with the very fix it argues for: the sibling change that + # teaches pinned_sources_check.py to read archive declarations adds this file to + # the index, so whichever of the two landed second would have broken the other. + # A control that has to be edited when the defect it describes is fixed is a + # control that penalises the fix. + with open(os.path.join(ROOT, "research", "PINNED_SOURCES.md"), + encoding="utf-8") as f: + index = f.read() + if "moment_envelope" in index: + # table rows only: the index preamble may also name the file in prose + row = [l for l in index.splitlines() + if l.startswith("| `") and rel in l] + assert len(row) == 1, row + assert rows[rel]["sha256"][:16] in row[0], ( + "the index names this file with a digest that is not the one the " + f"archive member pins: {row[0]}") + assert str(rows[rel]["bytes"]) in row[0], row[0] + + +def test_the_rejection_probe_files_are_declared_and_not_labelled(): + """The finding that shaped this port. A float fed to a checker so the + checker REFUSES it is not a float path: pasting NON-CERTIFYING onto such a + file states the opposite of what the file demonstrates. Declared, every one, + and none of them carries the banner.""" + probes = ("tests/test_c2_band.py", "tests/test_gaussian_moments.py", + "tests/test_hermite_gaussian.py", "tests/test_rn_certificate.py", + "tests/test_rn_conditioning.py", "tests/test_rn_side24.py", + "tests/test_rn_side24_cell.py", "tests/test_rn_side24_density.py", + "tests/test_rn_side24_wedge.py", "tests/test_rn_spatial_cover.py", + "tests/test_rn_density_majorant.py", "tests/test_gaussian_families.py", + "tests/test_manifest_integrity_hardening.py", "tests/test_bridge.py", + "tests/test_lpw_headline.py") + for rel in probes: + assert rel in NCC.DECLARED, rel + assert "refus" in NCC.DECLARED[rel].lower() or "reject" in NCC.DECLARED[rel].lower(), rel + with open(os.path.join(ROOT, rel), encoding="utf-8") as f: + assert NCC.LABEL not in f.read(), rel + + +def test_a_declaration_and_a_label_are_not_interchangeable(): + """A file cannot hold both: a declaration says "no label is owed here", so + carrying one means the declaration is stale. The checker already refuses + that, and this pins it, because the whole rejection-probe argument rests on + the two being different states rather than two spellings of the same one.""" + for rel, reason in sorted(NCC.DECLARED.items()): + path = os.path.join(ROOT, rel) + if not os.path.isfile(path): + continue + with open(path, encoding="utf-8") as f: + has_label = NCC.LABEL in f.read() + assert not has_label, f"{rel} is DECLARED and carries the label" + + +def test_the_wall_clock_declarations_say_so(): + for rel in ("tools/run_checks.py", "tools/twelve_project_check.py", + "tests/test_twelve_project_check.py", "tests/test_run_checks.py"): + reason = NCC.DECLARED[rel].lower() + assert ("wall-clock" in reason or "duration" in reason + or "timeout" in reason), rel + + +def test_the_recovered_custody_tree_is_excluded_not_declared(): + """Recovered Drive bytes, pinned. Same ground as the carrier blobs: the one + edit that would break them is adding a banner. Excluded, and the exclusion + is stated in the module docstring rather than only in a tuple.""" + assert "research/side24/source_recovery/custody" in NCC.EXCLUDED + assert NCC.is_excluded( + "research/side24/source_recovery/custody/arithmetic_ledgers/" + "40ad76a1973248d9/arithmetic_ledgers.py") + assert "source_recovery/custody" in NCC.__doc__ + # and it really does hold float sites, so the exclusion is load-bearing + scanned = [r for r in NCC.python_files(ROOT) if "source_recovery/custody" in r] + assert scanned == [], scanned + + +def test_the_spelling_declaration_is_a_stated_reason_not_a_silencer(): + """The checker's SECOND false positive of the same family as its first. + `research/cover/audit.py` has ZERO float sites and uses "noncertifying" as an + English adjective about a total's status; rule 2 fired on it anyway. The rule + is not narrowed -- a file that labels an mpmath path in prose and writes the + word badly must still be caught -- so the exemption is a declaration with the + reason, and the file's bytes are untouched.""" + reason = NCC.SPELLING_DECLARED["research/cover/audit.py"] + assert "adjective" in reason and "ZERO float sites" in reason + src = open(os.path.join(ROOT, "research", "cover", "audit.py"), + encoding="utf-8").read() + assert NCC.LABEL not in src # unedited + assert "noncertifying" in src + assert NCC.float_sites(__import__("ast").parse(src)) == 0 + + +def test_the_spelling_rule_still_fires_for_an_undeclared_file(tmp_path): + """SPELLING_DECLARED must not have disabled rule 2. An undeclared file that + writes the label badly is still refused.""" + root, name = write(tmp_path, "m.py", + '"""A noncertifying estimate."""\nX = 1.5\n') + os.makedirs(os.path.join(root, "tools"), exist_ok=True) + out = run(root, name) + assert out.returncode == 1, out.stdout + assert "spelled 'noncertifying' in prose" in out.stdout, out.stdout + + +def test_the_summary_reports_both_declaration_counts(): + out = run(ROOT) + assert out.returncode == 0, out.stdout + assert f"declared={len(NCC.DECLARED)}" in out.stdout, out.stdout + assert f"spelling_declared={len(NCC.SPELLING_DECLARED)}" in out.stdout, out.stdout diff --git a/tests/test_rn_moment_envelope.py b/tests/test_rn_moment_envelope.py index ca7509262..bebb74245 100644 --- a/tests/test_rn_moment_envelope.py +++ b/tests/test_rn_moment_envelope.py @@ -71,8 +71,24 @@ def test_published_rational_margins(): def test_published_decimal_values(): + """The published decimals, checked against the module's own display path. + + NON-CERTIFYING. The first assertion is exact -- an equality between + `Fraction`s. The two that follow are NOT: they take a float fourth root of an + exact rational and compare it to a float literal within a float tolerance, + which is the same arithmetic `research/rn/moment_envelope.py`'s labelled + display block performs. That is deliberate and it is the point of this test: + it pins the DIGITS the module prints, so a change in what a reader sees is a + test failure. It establishes nothing about the envelope. + + The envelope inequality itself is asserted exactly and without floats, in + `test_published_rational_margins` above (`defective_pow4 < F(63, 1000) ** 4`) + and in `test_defective_expression_is_not_an_upper_bound`. Nothing here may be + cited for it. + """ c = counterexample() assert c["typed_expectation_lower"] == F(207675035568, 10**12) + # NON-CERTIFYING: float fourth roots, float tolerance, display digits only. assert abs(float(c["defective_pow4"]) ** 0.25 - 0.0625040624) < 1e-9 assert abs(float(c["correct_pow4"]) ** 0.25 - 0.2500046250) < 1e-9 diff --git a/tools/noncertifying_check.py b/tools/noncertifying_check.py new file mode 100644 index 000000000..2ced7142a --- /dev/null +++ b/tools/noncertifying_check.py @@ -0,0 +1,418 @@ +#!/usr/bin/env python3 +"""Every float path in repository-authored code is labelled, or declared. + +The Engineering-conventions bullet of `CLAUDE.md` says, of float arithmetic: +"Where a path does compute in floats -- mpmath, Monte Carlo, a fitted exponent, +a sampling -- label it NON-CERTIFYING in the code and in its output." Until this +checker existed nothing enforced that across the tree. Two tools did handle the +string at single sites -- `tools/math_status_check.py` requires one status field +to equal it and `tools/rn_bernstein_sharp_check.py` emits it in its own output -- +but no tool asked whether a file with a float site carried the label, so the +rule was honoured by discipline, and a float could reach a printed number with +nothing saying so. Forty-one repository-authored files hold +a float literal or a `float(` call; on this line, twenty-four of them carried no +label. + +WHAT READING ALL OF THEM CHANGED, and the reason `DECLARED` below is long. +Sixteen of those files use a float ONLY as a REJECTION PROBE: the float is the +input a checker must REFUSE, and the test asserts the refusal. Labelling one of +them `NON-CERTIFYING` would be a FALSE label -- the file's whole content is that +floats are rejected -- so a checker that a contributor can satisfy by pasting the +banner is a checker that invites a false statement into the tree. They are +declared, with the line each one refuses, and the declaration is the deliverable +rather than the label. Six more are wall-clock (poll intervals, timeouts, +elapsed seconds, a heartbeat age) and one is a display path inside a PINNED file, whose label +cannot be written into the bytes at all; that one is declared as an UNMET +obligation rather than an absent one, because a reader needs to know it exists. + +Two files were computing in floats where it mattered. Exactly ONE could be +labelled: `tests/test_rn_moment_envelope.py`, which pins the digits +`research/rn/moment_envelope.py` prints, using a float fourth root against a +float literal inside a float tolerance. + +The other could not, and finding that out cost a broken pin. +`research/rn/moment_envelope.py`'s `__main__` block prints float fourth roots of +exact rationals, so the rule plainly applies -- and the file is pinned by an +ARCHIVE MEMBER, `research/campaigns/rn_bernstein_sharp_variance_20260921_v1.zip:: +bernstein/DEPENDENCIES.json`, which lists 30 Python files by digest. +`research/PINNED_SOURCES.md` does not cover pins of that shape, so the index +reported the file as unpinned; the label was added, and +`tools/rn_bernstein_sharp_check.py` rejected the tree with "repository dependency +mismatch: research/rn/moment_envelope.py" on the CI replay. The bytes are restored +and the obligation is DECLARED as unmet, alongside `research/bands/ladder.py`. +Two of the twenty-four therefore end as recorded unmet obligations rather than as +labels, which is the honest count. + +WHAT THIS CHECKS. + + 1. Every repository-authored Python file containing a FLOAT SITE -- a float + literal, or a call to the builtin `float` -- either contains the canonical + label `NON-CERTIFYING`, or is named in `DECLARED` below with a reason. A + declaration is a claim a reviewer can check; silence is not. + + 2. Where the label appears in PROSE -- a string, a comment or a docstring -- + it is spelled `NON-CERTIFYING`. Identifier spellings (`NON_CERTIFYING`, + `non_certifying`, `noncertifying`) are allowed wherever Python needs a + name, because a hyphen cannot appear in one; the tool counts them and + says so rather than pretending they are not there. + +WHAT IS OUT OF SCOPE, stated so the pass is not read as more than it is. +Ported Drive source under `engine/carriers/blobs/` and frozen bodies under +`engine/rn_engine/frozen/` are excluded: they are byte-exact copies and are +never edited, so a labelling rule cannot apply to them. `mpmath` and `numpy` +are floats too, and a file using them without a Python float literal is not +caught here -- that is a real limit of a syntactic check and is not hidden. +PRINTED OUTPUT IS NOT CHECKED: the rule's "and in its output" half is not +enforced by this tool, which reads source only and never runs a display path; +a labelled file whose stdout omits the banner passes here. +The SIDE24 custody tree under `research/side24/source_recovery/custody/` is +excluded on the same ground as the carrier blobs: recovered Drive source, held +byte-exact and pinned, so adding a banner is the one edit that would break it. + +WHAT THIS DOES NOT ESTABLISH. That a labelled path is correct, that an +unlabelled file computes nothing in floats by some other route, or that a +declared file's reason is true. It checks that a float site is accompanied by +a label or a stated reason. It reads no claim, grades nothing, moves no gate, +and a pass here certifies nothing. +""" +from __future__ import annotations + +import argparse +import ast +import os +import re +import sys + +ROOT = os.path.dirname(os.path.dirname(os.path.abspath(__file__))) + +#: The canonical label. One spelling, so it is greppable. +LABEL = "NON-CERTIFYING" + +#: Identifier spellings Python forces, allowed wherever a name is needed. +#: Matched as WHOLE TOKENS: `float_noncertifying` is a receipt field name, not +#: this label misspelled, and a docstring naming that field is not a defect. +IDENTIFIER_SPELLINGS = ("NON_CERTIFYING", "non_certifying", "noncertifying", + "NONCERTIFYING") + +#: Roots of repository-authored code. +CODE_ROOTS = ("tools", "tests", "research", "engine", "claims") + +#: Ported bytes. Never edited, so never labelled. The SIDE24 custody tree is +#: here for the same reason as the carrier blobs: recovered Drive source, held +#: byte-exact and pinned by a certificate, so a labelling rule cannot apply to +#: it -- editing it to add a banner is the one thing that would break it. +EXCLUDED = ("engine/carriers/blobs", "engine/rn_engine/frozen", + "research/side24/source_recovery/custody", + "__pycache__", "sandbox", "legacy", "quarantine") + +#: Files with a float site and no label, each with the reason. Adding a line +#: here is a deliberate, visible edit; a file quietly acquiring a float is not. +DECLARED: dict[str, str] = { + # --- incidental conversions --------------------------------------------- + "tools/registers_import.py": + "one `float(new)`, converting an Excel serial date. Not a mathematical " + "quantity and never part of a bound.", + "tools/drive_index.py": + "one `n /= 1024.0`, rendering a byte count as KiB/MiB for a human. No " + "quantity of the program passes through it.", + + # --- wall-clock: poll intervals, timeouts, elapsed seconds --------------- + # A float that measures TIME. None of these is a quantity of the + # mathematics, and none reaches a bound or a printed result. + "tools/run_checks.py": + "one `selector.select(timeout=0.05)`, the poll interval of the output " + "reader. Wall-clock, not arithmetic.", + "tools/twelve_project_check.py": + "`selector.select(min(0.05, timeout_seconds))` and " + "`process.wait(timeout=max(0.001, ...))`. Both are wall-clock bounds on " + "a subprocess, never quantities of the campaign.", + "tests/test_twelve_project_check.py": + "a `.15` run_bounded timeout, a `time.sleep(.5)` and a " + "`budget_seconds=0.000001` exercising the budget path. Wall-clock only.", + "tests/test_run_checks.py": + "one `assert report[...]['timeout_seconds'] < 0.4`, checking that a " + "wall-clock budget was recorded. The float is a duration.", + "tools/coordination_check.py": + "one `(now - parse_utc(hb)).total_seconds() / 3600.0`, the age of an " + "agent heartbeat in hours, compared against STALE_AFTER_HOURS. The float " + "is a duration: it decides whether a claim on the coordination board has " + "gone stale, and no quantity of the mathematics passes through it. " + "Labelling this path NON-CERTIFYING would say something false about the " + "file, which computes no bound at all.", + + # --- REJECTION PROBES ---------------------------------------------------- + # The dominant category in this tree, and the reason this dict is long. A + # float here is the INPUT a checker must REFUSE; the test asserts the + # refusal. Labelling one of these NON-CERTIFYING would be a FALSE label: + # the file's content is that floats are rejected. See the module docstring. + "tests/test_bridge.py": + "one `1.0` in a parametrize list of values the bridge schema must " + "REFUSE. The float is the test input, not a computed result.", + "tests/test_lpw_headline.py": + "one `parse_decimal(6.239e-44)`, a negative control asserting a float " + "literal is refused where an exact decimal string is required.", + "tests/test_c2_band.py": + "one `0.05`, id'd `float`, in a parametrize list of rejected radii.", + "tests/test_gaussian_families.py": + "two `1.0` entries in parametrize lists of values the family " + "constructors must refuse.", + "tests/test_gaussian_moments.py": + "one `MomentEngine((0.0,0,0), ...)` inside `pytest.raises(TypeError)`. " + "The float exists to be refused.", + "tests/test_hermite_gaussian.py": + "one `1.0` in a parametrize list of rejected arguments.", + "tests/test_manifest_integrity_hardening.py": + "one `1.5` in a parametrize list of byte sizes the manifest reader must " + "refuse.", + "tests/test_rn_certificate.py": + "`for value in (0.5, True)` -- two rejected replacements for an exact " + "field.", + "tests/test_rn_conditioning.py": + "one `((1.0,),)` matrix in a parametrize list of refused shapes.", + "tests/test_rn_side24.py": + "a `0.5` and a `1.0` in parametrize lists of refused arguments and " + "refused points.", + "tests/test_rn_side24_cell.py": + "one `192.0` in a parametrize list of refused precisions -- a float " + "where an int is required.", + "tests/test_rn_side24_density.py": + "a `0.0` centre and a `1.0` direction component, both refused.", + "tests/test_rn_side24_wedge.py": + "`6.0`, `256.0` and `12.0` in parametrize lists of refused order, bits " + "and piece counts.", + "tests/test_rn_spatial_cover.py": + "a `1.0` and a `192.0` in parametrize lists of refused arguments.", + "tests/test_rn_density_majorant.py": + "a `1.0` mahalanobis_lower and a `192.0` bits, both refused.", + + # --- one file in both categories ----------------------------------------- + "tests/test_rn_bernstein_sharp_check.py": + "`float('nan')` and `float('inf')` fed to the budget and timing " + "validators to assert they are refused, plus two " + "`elapsed_seconds=0.01` fixtures. Rejection probes and wall-clock; no " + "float reaches a bound.", + "tests/test_h3_rn_n6_check.py": + "a `25.0` replacing a boolean field, to assert the refusal, and a " + "`budget_seconds=0.000001`. A probe and a duration.", + + # --- display paths in PINNED files, which cannot carry the label --------- + # The two entries that record an UNMET obligation rather than an absent one. + # The rule says to label the path in the code and in its output; every float + # site in both files is a display conversion, so the rule applies -- and both + # are pinned, so the label cannot be written into the bytes without breaking + # the certificates that bind them. Declared rather than silently excluded, + # because the reader needs to know the obligation exists and why the bytes do + # not meet it. + # + # `moment_envelope.py` is here because attempting the label BROKE A PIN and + # the CI replay caught it: `tools/rn_bernstein_sharp_check.py` rejected the + # tree with "repository dependency mismatch". Its pin is declared inside an + # ARCHIVE MEMBER -- + # `research/campaigns/rn_bernstein_sharp_variance_20260921_v1.zip`, + # member `bernstein/DEPENDENCIES.json`, 30 Python files by digest -- and + # `research/PINNED_SOURCES.md` does not cover that shape, so the index said + # the file was free to edit. Recorded here because a reader checking the index + # would reach the same wrong conclusion. + "research/rn/moment_envelope.py": + "six float sites, all in the `__main__` display block: `float(...)` " + "conversions and two `** 0.25` fourth roots, printed for a reader to " + "compare by eye. The block's verdict line is NOT on that path -- it " + "compares `defective_pow4 < typed_expectation_lower ** 4` in exact " + "rationals -- so the module's result is exact and only its digits are " + "float. The file is PINNED by " + "`research/campaigns/rn_bernstein_sharp_variance_20260921_v1.zip::" + "bernstein/DEPENDENCIES.json` (bytes 6778, sha256 107c873f...), so the " + "label cannot be added in place. The obligation is recorded here and " + "unmet in the bytes; a successor edition should carry it.", + "research/bands/ladder.py": + "eleven float sites, every one a `float(...):.Nf` conversion inside a " + "report f-string (lines 262, 555, 564-567, 576-577, 585) -- display " + "only; no bound and no compared quantity passes through a float here. " + "The file is PINNED (see research/PINNED_SOURCES.md), so the label " + "cannot be added in place. The obligation is recorded here and unmet in " + "the bytes; a successor edition of this module should carry the label.", +} + +#: The spelling rule (2) fires on any identifier spelling in prose, whether or +#: not the file has anything to label. That is right for a file that owes a +#: label and wrote it badly, and WRONG for a file using "noncertifying" as an +#: ordinary English adjective -- which is this checker's SECOND false positive +#: of the same family as the first (a receipt field name, recorded in the +#: spelling loop below). A declaration keeps the finding visible and the reason +#: checkable, which is the point of DECLARED above; narrowing the rule silently +#: would lose the real case of a file that labels its mpmath path in prose +#: without ever writing a Python float literal. +SPELLING_DECLARED: dict[str, str] = { + "research/cover/audit.py": + "'noncertifying' is an adjective here, not a label: \"Well-formed " + "noncertifying or incomplete totals remain noncertifying/incomplete, " + "rather than being promoted\" describes a TOTAL's status. The file has " + "ZERO float sites, so it owes no label at all, and rewriting the " + "sentence to say NON-CERTIFYING would make it say something else.", +} + + +def is_excluded(rel: str) -> bool: + """Match EXCLUDED entries as whole path components or path prefixes. + + A substring test silently dropped `tools/quarantine_check.py` and + `tests/test_quarantine_digest_coverage.py` because their file names contain + an excluded directory name. Only a directory component equal to an entry, or + a path that starts with a multi-component entry, is excluded. + """ + rel = rel.replace("\\", "/").strip("/") + parts = rel.split("/") + for entry in EXCLUDED: + if "/" in entry: + if rel == entry or rel.startswith(entry + "/"): + return True + elif entry in parts: + return True + return False + + +def python_files(root: str) -> list[str]: + out = [] + for code_root in CODE_ROOTS: + base = os.path.join(root, code_root) + if not os.path.isdir(base): + continue + for dirpath, dirnames, filenames in os.walk(base): + dirnames[:] = [d for d in dirnames + if not is_excluded(os.path.relpath(os.path.join(dirpath, d), root))] + for fn in sorted(filenames): + if not fn.endswith(".py"): + continue + rel = os.path.relpath(os.path.join(dirpath, fn), root) + if not is_excluded(rel): + out.append(rel) + return sorted(out) + + +def float_sites(tree: ast.AST) -> int: + """Float literals plus calls to the builtin ``float``. + + A float literal inside a docstring is a string, not a float, so it does not + count -- the numbers quoted in prose throughout this repository are text. + """ + n = 0 + for node in ast.walk(tree): + if isinstance(node, ast.Constant) and isinstance(node.value, float): + n += 1 + elif (isinstance(node, ast.Call) and isinstance(node.func, ast.Name) + and node.func.id == "float"): + n += 1 + return n + + +def prose_spans(tree: ast.AST, source: str) -> list[str]: + """Every string constant, plus every comment line. + + Comments are recovered by line scan rather than by tokenize: a `#` inside a + string would be a false positive, and a false positive here only makes the + check stricter about spelling, never more permissive about labelling. + """ + out = [n.value for n in ast.walk(tree) + if isinstance(n, ast.Constant) and isinstance(n.value, str)] + for line in source.splitlines(): + if "#" in line: + out.append(line[line.index("#"):]) + return out + + +def audit(root: str, files=None) -> tuple[int, int, int, list[str]]: + """(files scanned, files with float sites, identifier uses, problems).""" + rels = python_files(root) if files is None else list(files) + scanned = with_floats = identifier_uses = 0 + problems: list[str] = [] + for rel in rels: + path = os.path.join(root, rel) + if not os.path.isfile(path): + problems.append(f"{rel}: declared or requested and not in the tree") + continue + with open(path, encoding="utf-8", errors="replace") as handle: + source = handle.read() + try: + tree = ast.parse(source) + except SyntaxError as exc: + problems.append(f"{rel}: will not parse ({exc})") + continue + scanned += 1 + prose = prose_spans(tree, source) + blob = "\n".join(prose) + for spelling in IDENTIFIER_SPELLINGS: + # Whole tokens only. `float_noncertifying` is a RECEIPT FIELD NAME, + # and a docstring naming that field is not the label written badly. + # Counting it was this checker's first false positive. + token = re.compile(rf"(? int: + parser = argparse.ArgumentParser(description=__doc__.splitlines()[0]) + parser.add_argument("--root", default=None) + parser.add_argument("--file", action="append", default=[], + help="check these files instead of walking the roots") + args = parser.parse_args(argv) + root = args.root if args.root is not None else ROOT + scanned, with_floats, ident, problems = audit(root, args.file or None) + for item in problems: + print(item) + print(f"noncertifying_check: files={scanned} with_float_sites={with_floats} " + f"declared={len(DECLARED)} spelling_declared={len(SPELLING_DECLARED)} " + f"identifier_uses={ident} " + f"problems={len(problems)}") + print("A pass here means a float site carries the label or a stated reason. It does not " + "mean the labelled path is correct, and it certifies nothing.") + return 1 if problems else 0 + + +if __name__ == "__main__": + raise SystemExit(main()) diff --git a/tools/run_checks.py b/tools/run_checks.py index 5884983f4..96be2b71b 100644 --- a/tools/run_checks.py +++ b/tools/run_checks.py @@ -45,6 +45,7 @@ "python tools/claims_check.py", "python tools/withdrawal_check.py check --before governance/withdrawal/examples/before.json --after governance/withdrawal/examples/after.json --ticket governance/withdrawal/examples/ticket.json", "python tools/rollout_guard.py governance/rollout/SYNTHETIC_metadata_plan.json", + "python tools/noncertifying_check.py", "python tools/quarantine_check.py", "python tools/vault_hygiene_check.py", "python tools/verify_manifests.py",