Tooling: cache exact R420 geometry for 6.47x faster mutation replay

research/r420-geometry-cache/CLAIM.md

@@ -0,0 +1,47 @@
+# Verification-engineering claim: seed 91
+
+Base: `66849e1475c930fd7732b1a0067ffee7e1e95f60`, freshly fetched main.
+OS randomness `secrets.randbelow(100)` returned **91**, selecting verification
+engineering. This is a second, independent contribution by @mtpsl with
+substantial OpenAI Codex assistance; it does not depend on PR691.
+
+Three narrow candidates:
+
+0. Accelerate exact moment intervals. PR667/672 already address this area.
+1. Cache repeated validated E8 geometry in PR543's mutation verifier.
+2. Replace the repeated Fraction row reductions in one E8 frame initializer.
+
+Choose `91 mod 3 = 1`: a bounded in-process geometry cache, preserving the
+original arithmetic and all per-word checks. The exact geometry/header input
+must be part of the key; no persisted cache or unchecked old certificate.
+Expected deliverable: an opt-in adapter, same-input A/B benchmark, exact receipt
+comparison and cache invalidation/aliasing controls. No frontier change.
+
+Baseline observation: the original nine-negative/one-positive mutation suite,
+including its initial valid word, took 8.120 seconds locally. The experiment
+will rerun this same suite through each implementation and compare receipts.
+Stop after one implementation and bounded targeted verification. Expected finish:
+2026-10-13 12:55 Asia/Singapore; reserve the last quarter for verification/handoff.
+
+No pinned coordination issue exists (GitHub pinnedIssues query returned empty).
+Open issues contain only the unrelated Discussions request #650. PRs checked
+through #700. The review ledger marks PR452 (older PR358 prefix/arithmetic
+adapters) unreviewed; it is not a dependency. PR662 concerns complex Clifford
+helpers, not this E8 label/frame audit. PR661's frame-search negative result
+does not concern verifier performance. PR667/672 address interval arithmetic.
+The selected PR626 certificate, its actual PR543 supplier and review, and the
+repository contribution instructions remain as established at the recorded base.
+
+Result: **completed tooling improvement**, submitted as
+[PR709](https://github.com/CrocSwap/integer-mult-bounds/pull/709).
+The same original mutation suite takes 8.239 s uncached and 1.273 s cached
+(6.47x) in the recorded local pair. Complete diagnostics match byte for byte;
+receipts, all ten original controls and twenty supplemental checks agree.
+The adapter is optional, bounded and source-pinned. No existing verifier,
+selected construction or upstream file changes; no new kappa.
+
+The pre-submission metadata refresh reached #704 with no overlapping PR543
+geometry-cache task. Main still equals the recorded base. Evidence, source pins,
+reproduction command, dependency argument and limits are in this package.
+This is the single result update to the local claim; no coordination thread
+was available.

research/r420-geometry-cache/README.md

@@ -0,0 +1,139 @@
+# Cache exact E8 geometry across PR543 mutation checks
+
+**Verification tooling; no mathematical construction or kappa change.** This
+opt-in adapter speeds up the unmodified PR543 mutation harness by reusing a
+previously validated E8 label/frame calculation for exactly matching inputs.
+Every word still receives the predecessor's full scalar, frame-path, dirty
+restoration and H1–H5/interface checks.
+
+On macOS arm64 / Python 3.12.3, one sequential, same-input A/B took
+**8.239 seconds → 1.273 seconds (6.47× faster, 84.5% less wall time)**.
+Both runs started separate processes with empty application caches. The original
+and cached runs produced byte-identical diagnostics and equal complete JSON
+receipts: all nine negative controls reject for the same reasons and the positive
+control passes. OS caches were not flushed. This measures only this mutation
+suite, not the full supplier pipeline; timings are diagnostic, not test thresholds.
+
+## Reproduce
+
+From the repository root, Python 3.10+ and its standard library:
+
+```sh
+python3 -I -B research/r420-geometry-cache/verify.py
+```
+
+Expected first result line:
+
+```text
+PASS_R420_GEOMETRY_CACHE original_controls=10 supplemental_checks=20
+```
+
+The next line reports freshly measured A/B timings. The command runs one
+original/cached pair on the exact same word and unchanged mutation harness,
+compares receipts and full diagnostics, then checks twenty cache-specific cases.
+`--output /absolute/new/directory` retains both logs, receipts and `RESULT.json`;
+the directory must not already exist. Without it, scratch outputs are temporary.
+The recorded run is in `evidence/RESULT.json` and the adjacent logs/receipts.
+
+Use the adapter directly with the existing harness:
+
+```sh
+python3 -I -B research/e8-bit-r420/code/mutants.py \
+  research/r420-geometry-cache/cached_xcheck.py \
+  research/e8-bit-r420/data/bitE8mut-r420.json.gz
+```
+
+The adapter exposes the same `check(word)` and `Reject` API consumed by that
+harness. It returns the predecessor's six-item result; as with the original API,
+callers must inspect **all hypothesis and conclusion booleans**, not just absence
+of an exception. It is an importable adapter, not a standalone verifier CLI.
+`GeometryCache(capacity=2)` also permits an explicitly owned cache for a sequence
+of checks. The default holds at most two geometry entries, in memory only.
+
+## What is reused, and why it is sound
+
+`cached_xcheck.py` checks the exact SHA-256 of the unchanged predecessor source
+before importing it. It refuses source drift; a later checker must be reviewed
+for changed data dependencies before changing this pin.
+
+For the pinned implementation, `Word.__init__` and `labels()` read only these
+word fields: `h`, `v`, `R`, `form`, `lines`, `frames`. The cache key is their full
+JSON serialization, preserving list order, duplicates and numeric representations.
+It is **not a digest**, a filename, an object identity, a dimensions-only key or
+an assumed E8 catalogue. Equal keys therefore have equal JSON input values for
+every cached calculation. This adapter is scoped to ordinary finite JSON data,
+as loaded from the word files, and sequential calls in one process.
+
+On a miss, the original exact constructor and label/frame-closure audit run.
+Only successful geometry is retained. The cache stores immutable tuples of the
+derived geometry and the label receipt. On every call, including a hit, it
+creates a fresh original `Word`, supplies the current complete word, copies the
+derived geometry into fresh mutable containers and clears per-word nesting
+memoization. It then calls the unchanged `full()` and `interface()` methods.
+No scalar execution result or successful whole-word verdict is cached.
+
+The label audit covers exact root norms, pair inner products, even-unimodular
+lattice rank/determinant and closure of every listed frame. These obligations
+have identical inputs on a hit. Every obligation that depends on the current
+gates, starts, finals, retained totals or scatter is rerun. Geometry validated
+for a word whose later scalar check fails may be retained: the scalar result is
+not part of the cached evidence and cannot suppress the next word's replay.
+
+Returned `Word` objects and receipts share no mutable derived data with the
+cache. Changing a caller-owned input is detected by the next key computation;
+changing a previously returned result cannot poison the next check. Capacity
+eviction causes full geometry validation on the next miss. There is no disk
+cache, concurrent-call guarantee, approximate arithmetic or trusted old receipt.
+
+These statements are a code-dependency argument for this pinned finite checker,
+not a formal proof of the integer-multiplication theorem.
+
+## Verification and boundaries
+
+The original suite checks its valid baseline plus nine negatives and one positive.
+Additional checks compare exact outcomes and derived geometry against uncached
+execution, including failure reasons:
+
+- Eight cache-hit corruptions: start, final, A, B, C, D, retained totals, scatter.
+- Six geometry changes: h, v, R, form, a label, and an unclosed full frame.
+- Repeated failed geometry, a valid reflected E8 geometry, returned-result
+  mutation, in-place input mutation, capacity-one eviction and source-pin drift.
+
+The two successful geometry variants also compare the full derived geometry and
+all predecessor receipts. Source drift is tested by relocating the unchanged
+adapter beside altered predecessor bytes; it must refuse to import.
+`make selected-record-check` and staged whitespace validation pass.
+
+Only this new research package changes. No existing verifier, manifest, selected
+certificate or `upstream/` byte is edited. The complete repository suite, selected
+cold replay, hosted invoices, moment engines, Lean and remote CI were not run;
+this is an isolated, optional acceleration of one existing finite check.
+The inherited all-size, compiler, physical/common-label, hosting, precision,
+tape and analytic assumptions remain untouched. No new kappa or end-to-end
+supplier speedup is claimed.
+
+## Provenance and credit
+
+Base main: `66849e1475c930fd7732b1a0067ffee7e1e95f60`.
+PR543 supplier: `2065fe4f72a914d907f1046603f5a36f17018535`.
+`SOURCES.json` pins the exact three execution inputs by SHA-256 and Git blob.
+The selected PR626 composition still uses conditional
+`kappa=51110230636731/31250000000000000`.
+
+**Eumemic** supplied PR543's `xcheck.py`, mutation suite and R420 word, with
+substantial Anthropic Claude assistance. The original geometry, construction,
+dirty interface and mutation coverage are theirs. Credit also remains with
+PR493, Dylan Crow's E8 checker/decoder work, Jacob Sussman's E8 unit, Zhihao
+Chen's scalar interface, DreamingOfClouds' supplier/pricing work, and the complete
+lineage in [`research/e8-bit-r420/NOTICE.md`](../e8-bit-r420/NOTICE.md).
+
+PR452 (Aman) studies older PR358 prefix and arithmetic reuse; PR662 accelerates
+complex Clifford helper checks; PR667/672 concern interval arithmetic. Those
+distinct performance contributions are not imported or independently reviewed
+here. PR691 is our separate circuit contribution and is not a dependency.
+The seed-91 claim and overlap checks are recorded in `CLAIM.md`.
+
+Prepared for **@mtpsl with substantial OpenAI Codex assistance** in implementing
+the cache, analyzing dependencies, testing and packaging. No independent human
+review is claimed. New files are Apache-2.0 under the repository's LICENSE;
+predecessor attribution and files are preserved unchanged.

research/r420-geometry-cache/SOURCES.json

@@ -0,0 +1,18 @@
+{
+  "base_commit": "66849e1475c930fd7732b1a0067ffee7e1e95f60",
+  "source_pr543_commit": "2065fe4f72a914d907f1046603f5a36f17018535",
+  "execution_inputs": {
+    "research/e8-bit-r420/code/xcheck.py": {
+      "sha256": "5737d18a7826fd51e131035f2d7bebba2e2868af91dd7672a5f11208b036d424",
+      "git_blob": "fbff8607e4c61e18481f696b99dd38a32444e90d"
+    },
+    "research/e8-bit-r420/code/mutants.py": {
+      "sha256": "e2fd3429e2db4389ae8a5ab47dda89f551b0d0952c42fad5ac8d38a85d670594",
+      "git_blob": "5b0fa1922076d2e91367b58483c96b33b7b08661"
+    },
+    "research/e8-bit-r420/data/bitE8mut-r420.json.gz": {
+      "sha256": "9721a3819efd68307f66f00d84a952eb28eb7c3ad2ce79653ce295c98a764784",
+      "git_blob": "0c63ca62759dc63d302be6552aeeee1ede70350f"
+    }
+  }
+}

research/r420-geometry-cache/VALIDATION.json

@@ -0,0 +1,35 @@
+{
+  "status": "PASS_SCOPED_CACHE_TOOLING",
+  "platform": {
+    "machine": "arm64",
+    "platform": "Darwin",
+    "python": "3.12.3"
+  },
+  "paired_run": {
+    "command": "python3 -I -B research/r420-geometry-cache/verify.py --output ../geometry-cache-validation",
+    "result": "PASS_R420_GEOMETRY_CACHE original_controls=10 supplemental_checks=20",
+    "benchmark": {
+      "cached_seconds": 1.2731981249526143,
+      "method": "one original-then-cached pair, separate cold processes, identical harness/input; OS caches not flushed",
+      "original_seconds": 8.238810583017766,
+      "speedup": 6.470957207327333
+    }
+  },
+  "additional_checks": [
+    "make selected-record-check: PASS",
+    "direct adapter CLI refuses to masquerade as verification: PASS",
+    "staged git diff --check: PASS"
+  ],
+  "notes": [
+    "Final direct-CLI guard added after the paired run; targeted CLI guard check passes. Imported cache implementation is unchanged.",
+    "Original and cached mutation diagnostics match byte for byte; complete JSON receipts match.",
+    "No source or mathematical files outside this new package changed."
+  ],
+  "not_run": [
+    "full repository suite",
+    "selected cold replay",
+    "hosted invoices and moment engines",
+    "Lean",
+    "remote CI"
+  ]
+}

research/r420-geometry-cache/cached_xcheck.py

@@ -0,0 +1,94 @@
+"""Opt-in, bounded geometry reuse for the pinned PR543 exact checker.
+
+Only Word.__init__ and labels() results are reused. full() and interface()
+always run on a fresh Word instance. No persistent cache or approximate math.
+Prepared for mtpsl with substantial OpenAI Codex assistance; Apache-2.0.
+"""
+from collections import OrderedDict
+import hashlib
+import importlib.util
+import json
+from pathlib import Path
+import sys
+
+sys.dont_write_bytecode = True
+HERE = Path(__file__).resolve().parent
+ROOT = HERE.parents[1]
+SOURCE = ROOT / "research/e8-bit-r420/code/xcheck.py"
+PIN = "5737d18a7826fd51e131035f2d7bebba2e2868af91dd7672a5f11208b036d424"
+if hashlib.sha256(SOURCE.read_bytes()).hexdigest() != PIN:
+    raise RuntimeError("pinned xcheck source changed; review cache dependencies before use")
+spec = importlib.util.spec_from_file_location("r420_original_xcheck", SOURCE)
+original = importlib.util.module_from_spec(spec)
+spec.loader.exec_module(original)
+Reject = original.Reject
+
+# Complete data dependencies of the pinned Word.__init__ and labels methods.
+GEOMETRY_FIELDS = ("h", "v", "R", "form", "lines", "frames")
+
+
+class GeometryCache:
+    def __init__(self, capacity=2):
+        if type(capacity) is not int or capacity < 1:
+            raise ValueError("capacity must be a positive integer")
+        self.capacity = capacity
+        self._entries = OrderedDict()
+        self.hits = 0
+        self.misses = 0
+
+    def check(self, word):
+        # The full serialization, not its hash, is the equality key. Preserve
+        # array order, duplicate entries and raw numeric types. No normalization
+        # of labels or frames may hide invalid input from the original checker.
+        key = json.dumps({field: word[field] for field in GEOMETRY_FIELDS},
+                         sort_keys=True, separators=(",", ":"), allow_nan=False)
+        if key in self._entries:
+            self.hits += 1
+            snapshot = self._entries.pop(key)
+            self._entries[key] = snapshot
+        else:
+            self.misses += 1
+            checked = original.Word(word)
+            labels = checked.labels()  # Failures never populate the cache.
+            snapshot = (
+                checked.v, checked.R, checked.n, tuple(checked.lines),
+                tuple(checked.fdim),
+                tuple(tuple(tuple(row) for row in frame) for frame in checked.fperp),
+                checked.FULL, checked.ZERO, tuple(labels.items()),
+            )
+            self._entries[key] = snapshot
+            if len(self._entries) > self.capacity:
+                self._entries.popitem(last=False)
+
+        # Never return the cached mutable Word or share mutable derived data
+        # with it. In particular, caller mutation of a previous result cannot
+        # poison a later geometry hit. Per-word nesting memoization starts empty.
+        obj = original.Word.__new__(original.Word)
+        obj.w = word
+        obj.v, obj.R, obj.n = snapshot[:3]
+        obj.lines = list(snapshot[3])
+        obj.fdim = list(snapshot[4])
+        obj.fperp = [[list(row) for row in frame] for frame in snapshot[5]]
+        obj.FULL, obj.ZERO = snapshot[6:8]
+        obj._nest = {}
+        labels = dict(snapshot[8])
+        full = obj.full()
+        hypotheses, conclusion, info = obj.interface()
+        return obj, labels, full, hypotheses, conclusion, info
+
+
+_cache = GeometryCache()
+
+
+def check(word):
+    """Drop-in check/Reject API for PR543's unchanged mutants.py harness."""
+    return _cache.check(word)
+
+
+def cache_info():
+    return {"hits": _cache.hits, "misses": _cache.misses,
+            "entries": len(_cache._entries), "capacity": _cache.capacity}
+
+
+if __name__ == "__main__":
+    raise SystemExit("This is a check/Reject adapter, not a verifier CLI. Run the package's verify.py or pass this file to PR543 mutants.py.")