Tooling: faster SharedPointCircuit.__init__ and verify_frames with identical receipts

research/shared-point-frame-contains/NOTICE.md

@@ -0,0 +1,22 @@
+# Notice
+
+This package accelerates the historical shared-point frame nesting check in
+`scripts/shared_point_circuit.py:SharedPointCircuit.verify_frames` (and the
+`support_in` / `contained` helpers it uses) while preserving nesting predicates
+and receipt fields.
+
+Predecessor credit:
+
+- Douglas R. Colkitt — shared-point circuits, exclusion circuits, bit-compression
+  screens and the historical certificates.
+- Closest tooling priors on *related* shared-point surfaces:
+  CrocSwap/integer-mult-bounds PRs #1994 (verify digests; merged) and open #2054
+  (`__init__` merge construction). This package leaves both alone and targets
+  the residual `verify_frames` / `support_in` LRU thrash.
+- Quality-bar priors on *different* objects: #756 (balanced-Fano packed replay),
+  #1793 (inplace-side prefix), #1861 (parity-side basis/contains), #2117
+  (DisjointTensor.frame_data).
+
+Prepared by Wentao Li with substantial AI assistance under Apache-2.0.
+This is not independent human peer review and is not a formal proof of the
+multiplication theorem.

research/shared-point-frame-contains/README.md

@@ -0,0 +1,96 @@
+# Faster exact shared-point frame nesting
+
+**Folded into open [CrocSwap/integer-mult-bounds#2054](https://github.com/CrocSwap/integer-mult-bounds/pull/2054)** (same `scripts/shared_point_circuit.py` as `__init__`). Do not open a second upstream PR.
+
+**Tooling improvement; no new kappa.** At base
+`0fdd7d82de03e43c9e5a1000dfbcd380d1b687d2` (after merged
+[CrocSwap/integer-mult-bounds#1994](https://github.com/CrocSwap/integer-mult-bounds/pull/1994)
+verify digests), `SharedPointCircuit.support_in` uses
+`@lru_cache(maxsize=16384)`. Profiling
+`SharedPointCircuit(46).verify_frames` with a precompiled program shows
+`contained` / `support_in` dominate the timed window, with far more than
+16384 distinct `(node, common)` pairs — the small LRU thrashes. Open
+[#2054](https://github.com/CrocSwap/integer-mult-bounds/pull/2054) speeds
+`__init__` merge construction on the same file; this package leaves that
+surface alone.
+
+This change memoizes `support_in` in a per-instance dense table indexed by
+`node * h + common`, unpacks leaf and two-point pairs without a generator or
+`sorted` call, and runs the `verify_frames` nesting walk through local
+closures that share that table. Nesting predicates, `circuit_sha256`, and the
+`verify_frames` receipt fields stay identical. The bit-compression certificate
+does not list `scripts/shared_point_circuit.py` in `source_sha256`.
+
+## Reproduce
+
+Python **3.12**, standard library only, from the repository root:
+
+```sh
+python3.12 -I -B research/shared-point-frame-contains/verify.py
+python3.12 -I -O -B research/shared-point-frame-contains/verify.py
+python3.12 -B scripts/research_package.py --package research/shared-point-frame-contains
+python3.12 -I -B research/shared-point-frame-contains/benchmark.py --rounds 5
+```
+
+Expected:
+
+```text
+PASS_SHARED_POINT_FRAME_CONTAINS cases=5 json_files=… certs=0 no_new_kappa
+PASS_REGISTERED_RESEARCH_PACKAGE research/shared-point-frame-contains outcome=completed
+PASS_IDENTICAL_SHARED_POINT_FRAME_CONTAINS_RECEIPTS
+```
+
+On Linux / CPython 3.12.3 (Linux-6.12.94+-x86_64-with-glibc2.39), five
+alternating fresh-process pairs timing only
+`SharedPointCircuit(46).verify_frames(code)` (construction and compile
+excluded) gave median wall time **2.888 → 1.729 seconds (1.67×)**. Timing is
+host-descriptive and is not a correctness gate; see `RESULT.json`.
+
+Default verify is read-only. Full `make verify`, selected cold replay, Lean, and
+multiplication-theorem obligations were not rerun for this isolated
+historical-checker change.
+
+## Equivalence argument
+
+- Dense-table hits return the same bitmask previously returned by the LRU path.
+- Leaf triples still select the unique pair complementary to `common`; the
+  branchless unpack yields the same ordered pair as
+  `tuple(x for x in triple if x != common)`.
+- Two-point stars still OR the same `pair_ids[common][pair]` bits over
+  `union & ~core`.
+- `verify_frames` still compiles (or accepts) the same program, walks the same
+  forward and reverse role slots, and applies the same
+  `contained(prev, node)` / `contained(node, prev)` predicates.
+- `SharedPointCircuit.verify` digests from #1994 are untouched in structure;
+  they continue to call `support_in` and receive identical masks.
+
+## Coverage preserved
+
+- `verify.py` compares baseline vs optimized `verify` and `verify_frames`
+  receipts on `h ∈ {6,8,10,12,46}`, plus pointwise `support_in` on sampled
+  active nodes.
+- Corrupting a node's recorded core intersection still raises `AssertionError`
+  in both engines (skipped under `-O` because historical checks use `assert`).
+- Package JSON manifests are scanned for duplicate keys.
+- Existing `tests/test_shared_point_network.py` and `tests/test_bit_compression.py`
+  remain valid consumers; focused
+  `tests/test_shared_point_frame_contains.py` covers the package controls.
+
+## Open next questions
+
+1. **Question:** Should `research/bit-compression-provenance` refresh its live
+   `scripts/shared_point_circuit.py` SHA-256 pin after this rewrite?
+   **Why it matters:** That package binds working-tree bytes; a later provenance
+   replay would otherwise see a hash mismatch.
+   **First step:** Dedicated pin-only follow-up after confirming receipt identity.
+
+2. **Question:** After open #2054 merges, does folding its `__init__` rewrite
+   onto this frame-contains cache keep `circuit_sha256` and frame receipts
+   identical on one host?
+   **Why it matters:** Both edit the same production file; a clean fold preserves
+   combined review-throughput gain without dueling pins.
+   **First step:** Rebase onto the merged #2054 tip and rerun verify + benchmark.
+
+## Credit
+
+Prepared by Wentao Li with substantial AI assistance. See `NOTICE.md`.

research/shared-point-frame-contains/RESULT.json

@@ -0,0 +1,48 @@
+{
+  "base_commit": "0fdd7d82de03e43c9e5a1000dfbcd380d1b687d2",
+  "fixture": "SharedPointCircuit(46).verify_frames(code) only (construction and compile excluded)",
+  "machine": "x86_64",
+  "median_baseline_seconds": 2.8884478999998464,
+  "median_optimized_seconds": 1.7294277519999923,
+  "median_ratio": 1.6701755228916086,
+  "platform": "Linux-6.12.94+-x86_64-with-glibc2.39",
+  "python": "3.12.3 (main, Aug 31 2026, 10:18:26) [GCC 13.3.0]",
+  "rounds": 5,
+  "samples": [
+    {
+      "baseline_seconds": 2.859907246000148,
+      "optimized_seconds": 1.7422272750000047,
+      "ratio": 1.6415236330174776,
+      "round": 0
+    },
+    {
+      "baseline_seconds": 2.8022404520002056,
+      "optimized_seconds": 1.7294277519999923,
+      "ratio": 1.6203281396170275,
+      "round": 1
+    },
+    {
+      "baseline_seconds": 2.8884478999998464,
+      "optimized_seconds": 1.7094040510000923,
+      "ratio": 1.6897397068352276,
+      "round": 2
+    },
+    {
+      "baseline_seconds": 2.918537890999687,
+      "optimized_seconds": 1.7926036090002526,
+      "ratio": 1.6280999750008178,
+      "round": 3
+    },
+    {
+      "baseline_seconds": 2.903088261999983,
+      "optimized_seconds": 1.7288781760003076,
+      "ratio": 1.6791745666638958,
+      "round": 4
+    }
+  ],
+  "source_pins": {
+    "research/shared-point-frame-contains/baseline.py": "f5abbf6d61f3c10349416a3e1a1ed038bbd1279ed223367f2df549de46dd7ea5",
+    "scripts/shared_point_circuit.py": "360d9bffc0f55315fe294789b72c71c79e0991524555b3a5f42a2ca504d7da95"
+  },
+  "status": "PASS_IDENTICAL_SHARED_POINT_FRAME_CONTAINS_RECEIPTS"
+}

research/shared-point-frame-contains/SOURCES.json

@@ -0,0 +1,66 @@
+{
+  "schema_version": 1,
+  "base_commit": "0fdd7d82de03e43c9e5a1000dfbcd380d1b687d2",
+  "files": [
+    {
+      "path": "docs/research/agent-task-catalog.json",
+      "usage": "provenance",
+      "git_blob": "e8870e5917057d59b730eb14721a778639eca050",
+      "sha256": "d46eb6d5b3e279428753d770653663fbdf1063e55c255ea073d768f344927ef7"
+    },
+    {
+      "path": "certificates/selected-result.json",
+      "usage": "provenance",
+      "git_blob": "ae6a99f28aa468649eb66a361e764d769363bf11",
+      "sha256": "10b9e340fd8e354a37a0c4813c90e5de1dd42044b5f6aca4a3fc5a42b685fa32"
+    },
+    {
+      "path": "certificates/bit-compression-audit.json",
+      "usage": "provenance",
+      "git_blob": "2c8b221ad7935d49d2479fd44762cf8299066d19",
+      "sha256": "53effc15424ca20be4e92e8d7b66599b513f208cce1863176fdd1347a46faf90"
+    },
+    {
+      "path": "docs/research/bit-compression-audit.md",
+      "usage": "provenance",
+      "git_blob": "644c6587e436e3577e121dab27bfb817a6e92249",
+      "sha256": "d97764832d3ea1fe813623431b42383e3ffd713d83863de275425853fd85469d"
+    },
+    {
+      "path": "scripts/shared_point_circuit.py",
+      "usage": "provenance",
+      "git_blob": "32bdbb7e0e7fc4658b7885bc3755d7813a3eba0d",
+      "sha256": "f5abbf6d61f3c10349416a3e1a1ed038bbd1279ed223367f2df549de46dd7ea5"
+    },
+    {
+      "path": "scripts/exclusion_circuit.py",
+      "usage": "provenance",
+      "git_blob": "b0e2f3e03d7de791ca936dfd92cee2134c7dd4f5",
+      "sha256": "f9fbcd6e85e442cbd0926ac0887414e20735b2dc923d2d5822c803ceb46726d3"
+    },
+    {
+      "path": "scripts/shared_point_network.py",
+      "usage": "provenance",
+      "git_blob": "0ec7e75046fe714968c49178cd7f83e80e9f9d94",
+      "sha256": "a85e7f0d8c42d6a27e3846308571ca324a1824ac5c2d59e4daa5c7673c33c697"
+    },
+    {
+      "path": "scripts/audit_bit_compression.py",
+      "usage": "provenance",
+      "git_blob": "bc2521f862b1710b4afb060f07bcbeb595f78bce",
+      "sha256": "f0ed48592a885b54669d3f9086530fc84c467c39fd9281b357ba7550549aaa25"
+    },
+    {
+      "path": "tests/test_shared_point_network.py",
+      "usage": "provenance",
+      "git_blob": "bbf18de66f35c36c91701ff1975cdc1c7aacdcee",
+      "sha256": "94704721cdf97c8173f4dd5448aa4e82b83b705c3ecfe9769d38aaef4e74975f"
+    },
+    {
+      "path": "tests/test_bit_compression.py",
+      "usage": "provenance",
+      "git_blob": "a021dbf98d06b794e16538bf8c0c6536903086c7",
+      "sha256": "865e6f32fbf36b9c1571e4654f87e5ce2116f568494383cf1b64954180ef4bc8"
+    }
+  ]
+}

research/shared-point-frame-contains/TASK.json

@@ -0,0 +1,70 @@
+{
+  "schema_version": 1,
+  "task_id": "replay-runtime",
+  "priority_revision": 3,
+  "base_commit": "0fdd7d82de03e43c9e5a1000dfbcd380d1b687d2",
+  "chooser_seed": "c8e1a04f7b29d65e3a90c1482f6d7b51",
+  "original_card": {
+    "id": "replay-runtime",
+    "question": "Can one measured replay bottleneck be sped up without dropping coverage?",
+    "starting_points": [
+      "scripts/run_isolated_tests.py",
+      "scripts/verify_replay_coverage.py",
+      "certificates/selected-result.json"
+    ],
+    "methods": [
+      "Profile one isolated replay and optimize the measured bottleneck.",
+      "Design source-bound reuse with explicit dependency invalidation and negative controls."
+    ],
+    "acceptance_gate": "Report before/after wall time on the same fixture, retained checks and invalidation behavior.",
+    "first_step": {
+      "command": [
+        "python3",
+        "-B",
+        "scripts/research_baseline.py"
+      ],
+      "expected": "PASS_RESEARCH_BASELINE_BINDINGS_ONLY",
+      "inspect": "Read the selected reproduction command and choose a single replay stage for profiling.",
+      "scope": "Positive control / source-bound orientation only; this is not a new construction or full cold replay."
+    },
+    "first_experiment": "Measure one unchanged fixture, preserve check coverage, and test one optimization with invalidation controls.",
+    "bottleneck_link": "Faster trustworthy replays increase review throughput and let mechanism candidates be checked sooner.",
+    "allowed_variations": [
+      "Profile one stage or design one source-bound cache boundary."
+    ],
+    "scope_change_triggers": [
+      "Skipping coverage or comparing different fixtures to claim speedup."
+    ],
+    "overlap_terms": [
+      "replay runtime",
+      "cache invalidation",
+      "isolated tests"
+    ]
+  },
+  "scope_status": "refined",
+  "actual_scope": "Can scripts/shared_point_circuit.py:SharedPointCircuit.verify_frames (and its support_in / contained helpers) keep identical nesting receipts on the historical h=46 circuit after replacing the thrashing lru_cache(maxsize=16384) with a per-instance dense table and local hot-path closures, without touching SharedPointCircuit.__init__, verify digests, or ExclusionCircuit.compile?",
+  "scope_change_reason": "The catalogue card asks for one measured replay bottleneck with before/after wall time and retained checks. Expertise override selected verifier-engineering after merged #1994 (verify digests) and open #2054 (__init__ merge construction) left verify_frames / support_in as the residual hot path in bit-compression frame checks. Profiling on SharedPointCircuit(46).verify_frames with a precompiled program showed contained/support_in dominating, with CacheInfo misses far above the 16384 LRU cap.",
+  "bottleneck_link": "Side result on review throughput: audit_bit_compression calls SharedPointCircuit.verify_frames on full-size circuits. Faster identical nesting does not change kappa or the binding complex supplier.",
+  "budget_minutes": 60,
+  "stop_rule": "Ship an equivalence-preserving SharedPointCircuit.verify_frames / support_in change with frozen baseline, identical frame receipts on the historical h=46 circuit, registered replay and a measured before/after median at or above the ~1.5\u00d7 tooling bar. Do not reopen #1994 digests, #2054 __init__, ExclusionCircuit.compile, or run the selected cold frontier replay.",
+  "outcome": "completed",
+  "evidence": "PASS_SHARED_POINT_FRAME_CONTAINS via research/shared-point-frame-contains/verify.py (also under -O); PASS_IDENTICAL_SHARED_POINT_FRAME_CONTAINS_RECEIPTS via benchmark.py; bit-compression certificate does not pin scripts/shared_point_circuit.py in source_sha256. Folded into open CrocSwap #2054 with SharedPointCircuit.__init__ (same production file).",
+  "author": "Wentao Li",
+  "github": "VictorLiwentao",
+  "email": "wentaol4@illinois.edu",
+  "ai_assistance": "Substantial AI assistance for orientation, overlap search, profiling, implementation, packaging, benchmarking and writing. Not independent human peer review.",
+  "open_questions": [
+    {
+      "question": "Should research/bit-compression-provenance refresh its live scripts/shared_point_circuit.py SHA-256 pin after this equivalence-preserving frame-contains rewrite?",
+      "why_it_matters": "That provenance package binds working-tree bytes of shared_point_circuit.py; leaving the old pin keeps this tooling PR focused, but a later full provenance replay on main would see a hash mismatch until refreshed.",
+      "first_step": "Open a dedicated provenance follow-up that only rewrites the shared_point_circuit.py entry in SOURCES.json after confirming verify and verify_frames identity.",
+      "blocked_by": "Pin repair is outside this tooling change."
+    },
+    {
+      "question": "After open #2054 merges, does folding its __init__ rewrite onto this verify_frames cache still keep circuit_sha256 and frame receipts identical on one host?",
+      "why_it_matters": "Both edit scripts/shared_point_circuit.py; a clean fold avoids dueling source pins and preserves the combined review-throughput gain.",
+      "first_step": "Rebase this package onto the merged #2054 tip and rerun verify.py plus benchmark.py.",
+      "blocked_by": "Open PR #2054 has not merged."
+    }
+  ]
+}

research/shared-point-frame-contains/VERIFY.json

@@ -0,0 +1,56 @@
+{
+  "schema_version": 1,
+  "status": "ready",
+  "python": "3.12",
+  "requirements": [],
+  "inputs": [
+    "scripts/shared_point_circuit.py",
+    "scripts/exclusion_circuit.py",
+    "scripts/shared_point_network.py",
+    "scripts/audit_bit_compression.py",
+    "certificates/bit-compression-audit.json",
+    "docs/research/bit-compression-audit.md",
+    "tests/test_shared_point_network.py",
+    "tests/test_bit_compression.py"
+  ],
+  "commands": [
+    {
+      "argv": [
+        "{python}",
+        "-I",
+        "-B",
+        "{package}/verify.py"
+      ],
+      "timeout_seconds": 300,
+      "checks": "Exact baseline copy of the base-commit shared_point_circuit.py; identical SharedPointCircuit.verify and verify_frames receipts on h in {6,8,10,12,46}; support_in bitmask identity; corrupted-core nesting rejection; duplicate JSON-key scan; bit-compression certificate does not pin shared_point_circuit.py."
+    },
+    {
+      "argv": [
+        "{python}",
+        "-I",
+        "-O",
+        "-B",
+        "{package}/verify.py"
+      ],
+      "timeout_seconds": 300,
+      "checks": "Same receipt equivalence under -O. Historical nesting checks use assert and are stripped under -O; fieldwise receipt identity remains the gate."
+    },
+    {
+      "argv": [
+        "{python}",
+        "-I",
+        "-B",
+        "-m",
+        "unittest",
+        "discover",
+        "-s",
+        "tests",
+        "-p",
+        "test_shared_point_frame_contains.py",
+        "-v"
+      ],
+      "timeout_seconds": 180,
+      "checks": "Focused shared-point frame-contains package controls."
+    }
+  ]
+}