Tooling: 2.07× faster shared-point verify digests with identical receipts

research/shared-point-digest/NOTICE.md

@@ -0,0 +1,19 @@
+# Notice
+
+This package accelerates the historical shared-point verify digest in
+`scripts/shared_point_circuit.py:SharedPointCircuit.verify` while preserving
+support checks and `circuit_sha256`.
+
+Predecessor credit:
+
+- Douglas R. Colkitt — shared-point circuits, exclusion circuits, bit-compression
+  screens and the historical certificates.
+- Closest tooling priors on *different* objects: CrocSwap/integer-mult-bounds
+  PRs #756 (balanced-Fano packed replay), #1793 (inplace-side prefix), #1861
+  (parity-side basis/contains), #1922 (joint-frame cleared product), #1984
+  (mixed-point scalar digests; explicit open question this package answers),
+  and #1874 (hosted-audit digest path).
+
+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-digest/README.md

@@ -0,0 +1,102 @@
+# Faster exact shared-point verify digests with identical receipts
+
+**Tooling improvement; no new kappa.** At base
+`0b1cccf86e2f5132ed286a26ef0a681a495740ea`, `SharedPointCircuit.verify` builds
+`circuit_sha256` with per-active-node and per-partial-output
+`json.dumps(..., separators=(',',':'))` updates. Profiling on the historical
+full-size circuit (`h=46`, 501510 active nodes, 45540 partial outputs) shows
+about half of verify wall time in that JSON encoder path. Open
+[CrocSwap/integer-mult-bounds#1984](https://github.com/CrocSwap/integer-mult-bounds/pull/1984)
+left this object as an explicit next question after shipping mixed-point
+`scalar_check` digests.
+
+This change writes the same UTF-8 digest lines with an equivalent hand-rolled
+formatter (`[node,null,null]`, `[node,[a,b],[common,local]]`,
+`[common,[t0,t1,t2],node]`), keeps every support and topology assertion, and
+leaves `circuit_sha256` unchanged. 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-digest/verify.py
+python3.12 -I -O -B research/shared-point-digest/verify.py
+python3.12 -B scripts/research_package.py --package research/shared-point-digest
+python3.12 -I -B research/shared-point-digest/benchmark.py --rounds 5
+```
+
+Expected:
+
+```text
+PASS_SHARED_POINT_DIGEST verify_cases=5 encoding_cases=8 certs=0 no_new_kappa
+PASS_REGISTERED_RESEARCH_PACKAGE research/shared-point-digest outcome=completed
+PASS_IDENTICAL_SHARED_POINT_DIGEST_RECEIPTS
+```
+
+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.
+
+## Result
+
+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`
+(construction excluded; nested `ExclusionCircuit.verify` included) gave median
+wall time **2.212 → 1.070 seconds (2.07×)**. Timing is host-descriptive and is
+not a correctness gate; all samples and environment pins are in
+[RESULT.json](RESULT.json). Every verify receipt matches the baseline checker
+fieldwise (`roles`, `additions`, `merged_additions`, `circuit_sha256`, flags).
+
+## Equivalence
+
+For each active node the historical encoder emitted
+
+- `json.dumps((node, None, None), separators=(',',':'))+'\n'` → `[node,null,null]\n`
+- `json.dumps((node, (a,b), (common,local)), separators=(',',':'))+'\n'` → `[node,[a,b],[common,local]]\n`
+
+and for each partial output
+
+- `json.dumps((common, (t0,t1,t2), node), separators=(',',':'))+'\n'` → `[common,[t0,t1,t2],node]\n`
+
+with default JSON integer formatting (no whitespace). The hand-rolled writer
+emits those exact byte strings. A `None` vs `null` spelling mutant and a flat
+`[node,a,b,common,local]` mutant differ and are rejected by the package
+controls. Support and topology checks remain the historical `assert` gates.
+
+## Open next questions
+
+1. **Question:** Should `research/bit-compression-provenance` refresh its live
+   `scripts/shared_point_circuit.py` SHA-256 pin after this equivalence-preserving
+   digest rewrite?
+   **Why it matters:** That provenance package binds working-tree bytes; leaving
+   the old pin keeps this tooling PR focused.
+   **First step:** Dedicated provenance follow-up that only rewrites that one
+   `SOURCES.json` entry after confirming `circuit_sha256` identity.
+   **Blocked by:** Pin repair is outside this tooling change.
+
+2. **Question:** Is `ExclusionCircuit.verify`'s leave-two-out expected-support
+   genexpr worth a separate identical-receipt rewrite?
+   **Why it matters:** Its single `json.dumps` is not hot; the support sum is.
+   **First step:** Profile `ExclusionCircuit(45).verify` alone and prototype a
+   closed-form support mask if one matches the historical expected bits.
+   **Blocked by:** Out of this session’s stop rule.
+
+## Overlap and credit
+
+Closest priors (different objects):
+[CrocSwap/integer-mult-bounds#756](https://github.com/CrocSwap/integer-mult-bounds/pull/756),
+[CrocSwap/integer-mult-bounds#1793](https://github.com/CrocSwap/integer-mult-bounds/pull/1793),
+[CrocSwap/integer-mult-bounds#1861](https://github.com/CrocSwap/integer-mult-bounds/pull/1861),
+[CrocSwap/integer-mult-bounds#1922](https://github.com/CrocSwap/integer-mult-bounds/pull/1922),
+[CrocSwap/integer-mult-bounds#1984](https://github.com/CrocSwap/integer-mult-bounds/pull/1984)
+(mixed-point `scalar_check`; this package answers its SharedPoint open question),
+[CrocSwap/integer-mult-bounds#1874](https://github.com/CrocSwap/integer-mult-bounds/pull/1874).
+No competing open PR on the `SharedPointCircuit.verify` digest object at refresh.
+
+Douglas R. Colkitt authored the shared-point / exclusion circuits and
+bit-compression screens. Prepared by Wentao Li
+([VictorLiwentao](https://github.com/VictorLiwentao),
+[@Is__Victor](https://x.com/Is__Victor)) with substantial AI assistance, under
+Apache-2.0.

research/shared-point-digest/RESULT.json

@@ -0,0 +1,50 @@
+{
+  "environment": {
+    "executable": "/usr/bin/python3.12",
+    "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]"
+  },
+  "fixture": "SharedPointCircuit(46).verify only (construction excluded); includes nested ExclusionCircuit.verify",
+  "median_baseline_seconds": 2.212151175000031,
+  "median_optimized_seconds": 1.0697961950000945,
+  "median_ratio": 2.0678248673335724,
+  "no_new_kappa": true,
+  "rounds": 5,
+  "samples": [
+    {
+      "baseline_seconds": 2.2307621030000746,
+      "optimized_seconds": 1.0840965989999631,
+      "ratio": 2.0577152488605406,
+      "round": 0
+    },
+    {
+      "baseline_seconds": 2.531811613000059,
+      "optimized_seconds": 1.049210721999998,
+      "ratio": 2.4130630386372127,
+      "round": 1
+    },
+    {
+      "baseline_seconds": 2.1824195049999844,
+      "optimized_seconds": 0.999130652999952,
+      "ratio": 2.1843184356791916,
+      "round": 2
+    },
+    {
+      "baseline_seconds": 2.212151175000031,
+      "optimized_seconds": 1.0697961950000945,
+      "ratio": 2.0678248673335724,
+      "round": 3
+    },
+    {
+      "baseline_seconds": 2.1475713770000766,
+      "optimized_seconds": 1.0859181539999554,
+      "ratio": 1.97765491726015,
+      "round": 4
+    }
+  ],
+  "source_sha256": {
+    "baseline": "c9bb7a5df92d260a4e3ad532b53e26936730d7c93f7facfb0784957c1e81c8ba",
+    "production": "f5abbf6d61f3c10349416a3e1a1ed038bbd1279ed223367f2df549de46dd7ea5"
+  },
+  "status": "PASS_IDENTICAL_SHARED_POINT_DIGEST_RECEIPTS"
+}

research/shared-point-digest/SOURCES.json

@@ -0,0 +1,66 @@
+{
+  "schema_version": 1,
+  "base_commit": "0b1cccf86e2f5132ed286a26ef0a681a495740ea",
+  "files": [
+    {
+      "path": "docs/research/agent-task-catalog.json",
+      "usage": "provenance",
+      "git_blob": "06c96f5579bb67ed1b86d334e78fbed7da6945f1",
+      "sha256": "6686ad58f1fbdbc87134a78901b60fd53a20d3984355e91defbbebc9e9fa8075"
+    },
+    {
+      "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": "8347a0bda63fbfb51b86c6c6d10a7bf541816308",
+      "sha256": "c9bb7a5df92d260a4e3ad532b53e26936730d7c93f7facfb0784957c1e81c8ba"
+    },
+    {
+      "path": "scripts/exclusion_circuit.py",
+      "usage": "provenance",
+      "git_blob": "aaa99986c4b81c5d4fbe016fd216a4818940bb95",
+      "sha256": "b253f9d7318becda1c1f3b24e2287ed44a9c27fcea00cf9d531afb950d0457a0"
+    },
+    {
+      "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-digest/TASK.json

@@ -0,0 +1,70 @@
+{
+  "schema_version": 1,
+  "task_id": "replay-runtime",
+  "priority_revision": 3,
+  "base_commit": "0b1cccf86e2f5132ed286a26ef0a681a495740ea",
+  "chooser_seed": "7c2a91e04f8b3d65a1e0c9d2478f5b36",
+  "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 emit the same circuit_sha256 digest lines (and the same support/topology assertion checks) without per-node json.dumps, so full-size shared-point and bit-compression verify receipts stay fieldwise identical?",
+  "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 open tooling PR #1984 left SharedPointCircuit.verify / ExclusionCircuit.verify digests as an explicit next question. Profiling named SharedPointCircuit.verify's per-node json.dumps stream (about half of h=46 verify time) as the bottleneck; ExclusionCircuit.verify's single json.dumps is not hot.",
+  "bottleneck_link": "Side result on review throughput: shared-point verify and bit-compression certificates call SharedPointCircuit.verify. A faster identical digest does not change kappa or the binding complex supplier.",
+  "budget_minutes": 60,
+  "stop_rule": "Ship an equivalence-preserving SharedPointCircuit.verify digest change with frozen baseline, identical receipts on the historical h=46 circuit, registered replay and a measured before/after median. Do not reopen the mathematical screens, rewrite ExclusionCircuit support enumeration, or run the selected cold frontier replay.",
+  "outcome": "completed",
+  "evidence": "PASS_SHARED_POINT_DIGEST via research/shared-point-digest/verify.py (also under -O); PASS_IDENTICAL_SHARED_POINT_DIGEST_RECEIPTS via benchmark.py; bit-compression certificate does not pin scripts/shared_point_circuit.py in source_sha256.",
+  "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 digest 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 circuit_sha256 identity.",
+      "blocked_by": "Pin repair is outside this tooling change."
+    },
+    {
+      "question": "Is ExclusionCircuit.verify's leave-two-out expected-support genexpr worth a separate identical-receipt rewrite?",
+      "why_it_matters": "Profiling shows that single json.dumps is negligible there; the hot path is the per-output support sum genexpr, a different object from digest formatting.",
+      "first_step": "Profile ExclusionCircuit(45).verify alone and prototype a closed-form support mask if one matches the historical expected bits.",
+      "blocked_by": "Out of this session's stop rule; SharedPointCircuit.verify digests were the measured bottleneck."
+    }
+  ]
+}

research/shared-point-digest/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 receipts on h in {6,8,10,12,46}; encoding foil rejects wrong null and flat encodings; support-core rejection preserved; bit-compression certificate does not pin shared_point_circuit.py."
+    },
+    {
+      "argv": [
+        "{python}",
+        "-I",
+        "-O",
+        "-B",
+        "{package}/verify.py"
+      ],
+      "timeout_seconds": 300,
+      "checks": "Same digest equivalence under -O. Historical support checks use assert and are stripped under -O; circuit_sha256 identity remains the gate."
+    },
+    {
+      "argv": [
+        "{python}",
+        "-I",
+        "-B",
+        "-m",
+        "unittest",
+        "discover",
+        "-s",
+        "tests",
+        "-p",
+        "test_shared_point_digest.py",
+        "-v"
+      ],
+      "timeout_seconds": 120,
+      "checks": "Focused shared-point digest package controls."
+    }
+  ]
+}