Tooling: 6.47× faster production R420 mutants geometry cache with identical receipts

research/e8-bit-r420/MANIFEST.sha256

@@ -8,7 +8,7 @@ c71d239df91726fc519c6eb72d318ec65820627232b2f796219e87dcf35d0ab4  LICENSE
 46c205f6036bb8635a34ab6ef2c54a9e446bec1435fcc14ab55949a5dbee8aa4  code/adapt11.py
 1770f4eb61e130e3cc6e23f67507d8bb7587baaf8391d749c2e7fe5c66089044  code/cited.py
 d5c802447c99255db1bdfcae62b2116bfc9612c9dc9000d41aa4f5f2fec9f2f2  code/gen_l3.py
-e2fd3429e2db4389ae8a5ab47dda89f551b0d0952c42fad5ac8d38a85d670594  code/mutants.py
+bc6b010641dd3b2f6f33928ce2004189e0671bd9865eab7e70cfcd0d0c6cf9b9  code/mutants.py
 231cbf26bfe5e6824347e4556959941d8b4dea1efa06d7f88d7a73cca8b03158  code/mutrec_b.py
 6a5896f60b1fe05c41ab28ce822dff782c635e12d0c74fad20b5ce2a4010fa3f  code/nodeopt.py
 c0a687f61aed29455cea953d8a3e49a32136edb3cd4213c46880c146a6ca7fa3  code/planio.py

research/e8-bit-r420/code/mutants.py

@@ -16,8 +16,14 @@
   9 move a cleanup gate off the full frame (to the frame of the gate it inverts)
 Positive control:
   P a cancelled pair of target-to-target reads at frame 0 (y_t += y_u twice: V = I, allowed by the lemma)
-Prepared by eumemic with substantial Anthropic Claude assistance; Apache-2.0."""
+
+Production path reuses exact Word.__init__/labels geometry across evaluate() calls when h/v/R/form/lines/frames
+match (research/r420-geometry-cache/). full() and interface() always rerun on a fresh Word. Equivalence: same
+check API and mutation receipts as the pairwise harness.
+Prepared by eumemic with substantial Anthropic Claude assistance; production geometry cache by Wentao Li with
+substantial AI assistance; Apache-2.0."""
 import copy
+from collections import OrderedDict
 import gzip
 import importlib.util
 import json
@@ -32,6 +38,59 @@
 is_z = lambda r: not is_y(r)
 ZERO = next(k for k, f in enumerate(w0["frames"]) if not f)
 
+# Complete data dependencies of Word.__init__ and labels(); see research/r420-geometry-cache/.
+GEOMETRY_FIELDS = ("h", "v", "R", "form", "lines", "frames")
+
+
+class GeometryCache:
+    """Reuse validated geometry across mutation checks with identical geometry fields."""
+
+    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):
+        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 = X.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.
+        obj = X.Word.__new__(X.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
+
+
+_geometry_cache = GeometryCache()
+
 
 def zgates(w):
     return [("A", i) for i, g in enumerate(w["A"]) if is_z(g[1])] + [("B", i) for i, g in enumerate(w["B"]) if is_z(g[1])]
@@ -44,7 +103,13 @@ def mirror(w, sec, i):
 
 def evaluate(w):
     try:
-        W, lab, fl, H, C, info = X.check(w)
+        # Production path caches geometry when argv[1] is a full xcheck module.
+        # Historical drop-in adapters (research/r420-geometry-cache/cached_xcheck.py)
+        # expose only check/Reject; call them directly.
+        if hasattr(X, "Word") and hasattr(X, "check"):
+            W, lab, fl, H, C, info = _geometry_cache.check(w)
+        else:
+            W, lab, fl, H, C, info = X.check(w)
     except X.Reject as e:
         return False, "replay: " + str(e)[:90]
     bad = [k for k, x in list(H.items()) + list(C.items()) if not x]

research/r420-geometry-cache-production/NOTICE.md

@@ -0,0 +1,23 @@
+# Attribution
+
+## This package
+
+Prepared by Wentao Li (GitHub [VictorLiwentao](https://github.com/VictorLiwentao),
+X [@Is__Victor](https://x.com/Is__Victor)) with substantial AI assistance.
+New work is Apache-2.0.
+
+## Predecessors
+
+- **eumemic** authored the PR543 independent exact replay (`xcheck.py`), the
+  interleaved-interface mutation harness (`mutants.py`), and the retained R420
+  word/pipeline under `research/e8-bit-r420/`.
+- **mtpsl** authored the opt-in geometry-reuse adapter
+  `research/r420-geometry-cache/` (identical-receipt `GeometryCache` over
+  `Word.__init__` / `labels()`), which this package wires into the shipped
+  `mutants.py` path.
+- Quality-bar and production-promotion pattern:
+  [CrocSwap/integer-mult-bounds#756](https://github.com/CrocSwap/integer-mult-bounds/pull/756)
+  and subsequent identical-receipt production tooling PRs.
+
+Original notices under `research/e8-bit-r420/NOTICE.md` and
+`research/r420-geometry-cache/` remain authoritative for predecessor bytes.

research/r420-geometry-cache-production/README.md

@@ -0,0 +1,85 @@
+# Production geometry reuse for the PR543 R420 mutation harness
+
+**Tooling improvement; no new kappa.** At base
+`0fdd7d82de03e43c9e5a1000dfbcd380d1b687d2`,
+`research/e8-bit-r420/code/mutants.py` still rebuilt `Word.__init__` / `labels()`
+on every gate-only mutation control. The opt-in adapter
+`research/r420-geometry-cache/` already proved an exact geometry cache with
+identical mutation receipts. This package wires that equivalent reuse into the
+**production** harness used by `research/e8-bit-r420/verify.sh`.
+
+Every mutation stdout field, the JSON control receipt, and the
+`PASS mutation controls: 9/9` marker are unchanged. `full()` and `interface()`
+still run on a fresh `Word` after every geometry hit. Selected frontier
+untouched. Production `xcheck.py:rref` is left alone (open #2263).
+
+## Reproduce
+
+Python **3.12**, standard library only, from the repository root:
+
+```sh
+python3.12 -I -B research/r420-geometry-cache-production/verify.py
+python3.12 -I -O -B research/r420-geometry-cache-production/verify.py
+python3.12 -B scripts/research_package.py --package research/r420-geometry-cache-production
+python3.12 -I -B research/r420-geometry-cache-production/benchmark.py --rounds 5 --write-result
+```
+
+Expected:
+
+```text
+PASS_R420_GEOMETRY_CACHE_PRODUCTION controls=10 corruption=... mutants_sha=8c2738b3258e certs=0 no_new_kappa
+PASS_REGISTERED_RESEARCH_PACKAGE research/r420-geometry-cache-production outcome=completed
+PASS_IDENTICAL_R420_GEOMETRY_CACHE_PRODUCTION_RECEIPTS
+```
+
+Default verify is read-only. Timing is host-descriptive and is not a
+correctness gate. On Linux / CPython 3.12.3, five alternating fresh-process
+pairs gave median harness wall time about **9.66 → 1.49 s (≈6.46×)** in the
+authoring screen; committed samples are retained in [`RESULT.json`](RESULT.json)
+after `--write-result`.
+
+## Why the geometry cache is equivalent
+
+Gate-only mutations in this harness keep `h`, `v`, `R`, `form`, `lines` and
+`frames` byte-identical. `Word.__init__` and `labels()` read only those fields.
+Equal JSON serializations of those fields therefore have equal derived geometry
+(`lines`, `fdim`, `fperp`, `FULL`, `ZERO`, label receipt). On a hit the harness
+builds a fresh `Word`, copies immutable geometry into fresh mutable containers,
+clears per-word nesting memoization, and always reruns `full()` and
+`interface()` against the current gates. Failures during construction/labels
+never populate the cache. Details match `research/r420-geometry-cache/`.
+
+## Overlap and credit
+
+Closest priors:
+
+- [`research/r420-geometry-cache/`](../r420-geometry-cache/) — opt-in adapter;
+  this package is the production wiring.
+- [CrocSwap/integer-mult-bounds#756](https://github.com/CrocSwap/integer-mult-bounds/pull/756)
+  — identical-receipt tooling quality bar.
+- Open leave-alone tooling on other objects (#1922 joint frames, #2054/#2150
+  shared/mixed-point, #2100 ternary, #2117 DisjointTensor.frame_data, #2194
+  production verify_factor, #2210 production leech_minor, #2231 sparse-fusion
+  orbits, #2239 joint-dual replay, #1861 parity-side, #2257 frameopt.close,
+  #2263 xcheck.rref) was not reopened. Fresh overlap refresh found no competing
+  production rewrite of `mutants.py` geometry reuse.
+
+**eumemic** authored the PR543 checker/harness/word. **mtpsl** authored the
+opt-in geometry cache. Prepared by Wentao Li
+([VictorLiwentao](https://github.com/VictorLiwentao),
+[@Is__Victor](https://x.com/Is__Victor)) with substantial AI assistance, under
+Apache-2.0.
+
+## Open next questions
+
+1. **Question:** Should other packages that pin live `mutants.py` bytes refresh
+   those SHA-256 entries after this equivalence-preserving rewrite?
+   **Why it matters:** Leaving old pins keeps this tooling PR focused.
+   **First step:** Dedicated provenance follow-up after confirming receipt
+   identity.
+   **Blocked by:** Pin repair outside registered VERIFY live inputs is outside
+   this change.
+
+2. **Answered in-tree:** `research/r420-geometry-cache/` demotes its
+   `mutants.py` execution pin to provenance in the same tip so its local
+   verify no longer fails working-source drift.

research/r420-geometry-cache-production/RESULT.json

@@ -0,0 +1,82 @@
+{
+  "base_commit": "0fdd7d82de03e43c9e5a1000dfbcd380d1b687d2",
+  "baseline_mutants_sha256": "e2fd3429e2db4389ae8a5ab47dda89f551b0d0952c42fad5ac8d38a85d670594",
+  "interpreter": "CPython 3.12.3",
+  "machine": "x86_64",
+  "median_seconds": {
+    "baseline": 9.601901119000104,
+    "production": 1.4851274809998358
+  },
+  "mutants_stdout_sha256": "8c2738b3258e207370597b60c2ebd318e740fc0feaca04cb8b0e3a26089258d8",
+  "no_new_kappa": true,
+  "platform": "Linux-6.12.94+-x86_64-with-glibc2.39",
+  "production_mutants_sha256": "bc6b010641dd3b2f6f33928ce2004189e0671bd9865eab7e70cfcd0d0c6cf9b9",
+  "python": "3.12.3 (main, Aug 31 2026, 10:18:26) [GCC 13.3.0]",
+  "records": [
+    {
+      "engine": "baseline",
+      "pair": 0,
+      "seconds": 9.601901119000104,
+      "stdout_sha256": "8c2738b3258e207370597b60c2ebd318e740fc0feaca04cb8b0e3a26089258d8"
+    },
+    {
+      "engine": "production",
+      "pair": 0,
+      "seconds": 1.4447330049999891,
+      "stdout_sha256": "8c2738b3258e207370597b60c2ebd318e740fc0feaca04cb8b0e3a26089258d8"
+    },
+    {
+      "engine": "production",
+      "pair": 1,
+      "seconds": 1.4851274809998358,
+      "stdout_sha256": "8c2738b3258e207370597b60c2ebd318e740fc0feaca04cb8b0e3a26089258d8"
+    },
+    {
+      "engine": "baseline",
+      "pair": 1,
+      "seconds": 9.44682381199982,
+      "stdout_sha256": "8c2738b3258e207370597b60c2ebd318e740fc0feaca04cb8b0e3a26089258d8"
+    },
+    {
+      "engine": "baseline",
+      "pair": 2,
+      "seconds": 9.493446924999944,
+      "stdout_sha256": "8c2738b3258e207370597b60c2ebd318e740fc0feaca04cb8b0e3a26089258d8"
+    },
+    {
+      "engine": "production",
+      "pair": 2,
+      "seconds": 1.4894828100000268,
+      "stdout_sha256": "8c2738b3258e207370597b60c2ebd318e740fc0feaca04cb8b0e3a26089258d8"
+    },
+    {
+      "engine": "production",
+      "pair": 3,
+      "seconds": 1.4384404740001173,
+      "stdout_sha256": "8c2738b3258e207370597b60c2ebd318e740fc0feaca04cb8b0e3a26089258d8"
+    },
+    {
+      "engine": "baseline",
+      "pair": 3,
+      "seconds": 9.728668628999912,
+      "stdout_sha256": "8c2738b3258e207370597b60c2ebd318e740fc0feaca04cb8b0e3a26089258d8"
+    },
+    {
+      "engine": "baseline",
+      "pair": 4,
+      "seconds": 10.305828164000104,
+      "stdout_sha256": "8c2738b3258e207370597b60c2ebd318e740fc0feaca04cb8b0e3a26089258d8"
+    },
+    {
+      "engine": "production",
+      "pair": 4,
+      "seconds": 1.5412987929998962,
+      "stdout_sha256": "8c2738b3258e207370597b60c2ebd318e740fc0feaca04cb8b0e3a26089258d8"
+    }
+  ],
+  "rounds": 5,
+  "speedup": 6.465371654516684,
+  "status": "PASS_IDENTICAL_R420_GEOMETRY_CACHE_PRODUCTION_RECEIPTS",
+  "timing_scope": "fresh subprocess wall time for the complete mutants.py harness (1 honest + 9 negative + 1 positive) including imports; warm OS caches, not flushed; host-descriptive only; not a correctness gate",
+  "xcheck_sha256": "5737d18a7826fd51e131035f2d7bebba2e2868af91dd7672a5f11208b036d424"
+}

research/r420-geometry-cache-production/SOURCES.json

@@ -0,0 +1,55 @@
+{
+  "schema_version": 1,
+  "base_commit": "0fdd7d82de03e43c9e5a1000dfbcd380d1b687d2",
+  "files": [
+    {
+      "path": "certificates/selected-result.json",
+      "usage": "provenance",
+      "git_blob": "ae6a99f28aa468649eb66a361e764d769363bf11",
+      "sha256": "10b9e340fd8e354a37a0c4813c90e5de1dd42044b5f6aca4a3fc5a42b685fa32"
+    },
+    {
+      "path": "docs/research/agent-task-catalog.json",
+      "usage": "provenance",
+      "git_blob": "e8870e5917057d59b730eb14721a778639eca050",
+      "sha256": "d46eb6d5b3e279428753d770653663fbdf1063e55c255ea073d768f344927ef7"
+    },
+    {
+      "path": "research/e8-bit-r420/code/mutants.py",
+      "usage": "provenance",
+      "git_blob": "5b0fa1922076d2e91367b58483c96b33b7b08661",
+      "sha256": "e2fd3429e2db4389ae8a5ab47dda89f551b0d0952c42fad5ac8d38a85d670594",
+      "note": "Base-commit pairwise harness bytes retained as baseline.py; production working tree differs (geometry cache)."
+    },
+    {
+      "path": "research/e8-bit-r420/code/xcheck.py",
+      "usage": "input",
+      "git_blob": "fbff8607e4c61e18481f696b99dd38a32444e90d",
+      "sha256": "5737d18a7826fd51e131035f2d7bebba2e2868af91dd7672a5f11208b036d424"
+    },
+    {
+      "path": "research/e8-bit-r420/data/bitE8mut-r420.json.gz",
+      "usage": "input",
+      "git_blob": "0c63ca62759dc63d302be6552aeeee1ede70350f",
+      "sha256": "9721a3819efd68307f66f00d84a952eb28eb7c3ad2ce79653ce295c98a764784"
+    },
+    {
+      "path": "research/e8-bit-r420/verify.sh",
+      "usage": "input",
+      "git_blob": "fbad38c694a0ce4fcbf39110dc403c75017ece07",
+      "sha256": "3192dea51acd17addb2750834a9dc3fb5b991e8dc5970ba9d2ac54608d79cafa"
+    },
+    {
+      "path": "research/r420-geometry-cache/cached_xcheck.py",
+      "usage": "input",
+      "git_blob": "dfeee952ef8fcaeaa92d9a735ac63eb1ee8e874a",
+      "sha256": "491b9e3e51508be3e9f6b23567ebdedfe135b0598511c13bb498cd2c5df7bb26"
+    },
+    {
+      "path": "research/r420-geometry-cache/README.md",
+      "usage": "provenance",
+      "git_blob": "bd3989dd7d6349622f49e1b78d53d094421bb97b",
+      "sha256": "9cc407be328a9d677527192c7f7c326b431c5a1d4b7784df2ee48c84bffd978d"
+    }
+  ]
+}