Reduce complete R2 replay time by 54.25% (no new κ)

research/r2-frame-span-cache/README.md

@@ -0,0 +1,145 @@
+# Bounded frame-span reuse in the complete R2 replay
+
+This contribution was produced by Nick Petalas.
+
+Scoped implementation-preservation proof with a local performance measurement.
+The complete PR3240 path-copy caller takes **54.25% less median wall time**
+with a bounded cache of exact binary frame spans. This answers PR3240's
+remaining source/frame/event reconstruction handoff. No new kappa or supplier
+admission is claimed.
+
+Five alternating fresh-process pairs measured the identical complete caller:
+
+| Span implementation | Median seconds | Range in seconds |
+|---|---:|---:|
+| Original span function | 1.961916 | 1.954481 to 2.083084 |
+| Content-keyed span reuse | 0.897650 | 0.883717 to 0.986586 |
+
+All ten executions pass, with zero failures and identical full scientific
+payloads. Each retains all 32 original semantic mutants, exact rejection
+messages, original-fixture immutability checks and all 253 operator decisions,
+244 accepted and nine rejected. Source authentication, temporary snapshots,
+process startup and result serialization are inside the measured interval.
+Native artifact generation is excluded. These are one-host CPython 3.12.15,
+macOS arm64 measurements on a shared 18-core machine, not a portable timing
+promise. [BENCHMARK.json](BENCHMARK.json) is generated by
+[benchmark.py](benchmark.py) and binds every run to implementation, harness
+and all 45 input hashes. The receipt contains the complete scientific result
+for every run. It is checked as evidence, not regenerated during normal replay.
+
+An unreported cProfile run located 372,952 span calls, taking 1.003 of 2.728
+instrumented seconds. The optimization also avoids repeatedly hashing newly
+constructed equal frozensets in the caller's frame dictionaries. Profile times
+identify the bottleneck and are not used for the wall-time ratio.
+
+## Exact preservation argument
+
+The pinned original `span` starts at `{0}`, extends by XOR with each basis
+row, checks that each row is an integer in 1 through 511 outside the current
+span, and returns a frozenset. Its result and exceptions depend only on the
+ordered integer tuple, not on the list's identity. The audit consumes spans
+through set equality, subset comparison and dictionary lookup. It does not
+observe their identities.
+
+The wrapper keys successes by the complete ordered tuple. A hit therefore
+returns the same immutable set that the original call would construct.
+Noninteger elements bypass the cache, so a warmed integer key cannot accept
+an equal-valued bool or float. Inputs outside the caller's list/tuple,
+at-most-nine-row domain also use the original function. Misses execute the
+original validation. Failed calls are never stored. Mutating a frame changes
+its key, including when mutation makes it dependent or invalid.
+
+One cache belongs to one newly loaded audit module. It can store at most
+4,096 results, each with at most 512 elements and a key of at most nine
+integers. At capacity, misses still execute normally without insertion.
+Python requires dynamic allocation; this finite entry/element bound is the
+managed-runtime deviation from fixed allocation. This is not a cache of
+acceptance decisions, native operators, entire audits or mutable artifacts.
+
+The complete caller records 371,802 hits and 1,150 misses, with 1,150 retained
+entries. [replay.py](replay.py) loads the unchanged PR3240 implementation,
+adds one source-bound span installation, and preserves its full execution.
+The additional executed-audit hash distinguishes the hook from the historical
+source hash. All predecessor files remain unchanged.
+
+[verify.py](verify.py) compares against the pinned original span on every
+ordered sequence of length zero through four over the three-bit ambient
+space, including repeats, zero and dependent sequences. Eight further
+malformed cases bring the count to 4,689. Mutable-content, warmed-invalid-key,
+independent-lifetime and capacity-fallback checks supplement these cases.
+Three source-byte mutations and a missing-hook mutation reject. The complete
+cached caller also compares every original mutant payload with the original
+mutation applied to full deepcopy. This verifies the new implementation;
+it is not an independent audit of the predecessor theorem.
+
+## Reproduce
+
+From the repository root, using CPython 3.12 and the standard library:
+
+```sh
+/Users/nick/git/integer-mult-bounds/.venv/bin/python3.12 -B scripts/research_package.py --package research/r2-frame-span-cache
+/Users/nick/git/integer-mult-bounds/.venv/bin/python3.12 -I -W error -B research/r2-frame-span-cache/verify.py
+/Users/nick/git/integer-mult-bounds/.venv/bin/python3.12 -B scripts/check_research_commit.py --package research/r2-frame-span-cache --check-source-history
+```
+
+On another machine, substitute its CPython 3.12 executable. Expected markers
+are `PASS_R2_FRAME_SPAN_CACHE conformance=4689 controls=4 mutants=32 decisions=253 hits=371802`
+and `PASS_REGISTERED_RESEARCH_PACKAGE`. The registered commands run normal
+and optimized Python. Each takes about ten seconds locally, well below its
+120-second timeout.
+
+To repeat timing, choose a fresh directory outside the checkout:
+
+```sh
+python3.12 -I -W error -B research/r2-frame-span-cache/benchmark.py --directory /absolute/fresh/scratch-directory --pairs 5
+```
+
+To use only the cached complete caller, supply a fresh output file:
+
+```sh
+python3.12 -I -W error -B research/r2-frame-span-cache/replay.py --output /absolute/fresh/result.json
+```
+
+## Sources and limits
+
+Base canonical main is `2485805a6d47f36ea83ddde6327d453ac82d44dc`, priority
+revision 8. Exact Git blob and SHA256 pins are in [SOURCES.json](SOURCES.json);
+all live reads are declared in [VERIFY.json](VERIFY.json). Direct replay needs
+no Git or network. Metadata and publication checks require repository history.
+The selected source-binding orientation passes at kappa `781451/250000000`.
+The selected frontier and all five framework assumptions remain unchanged.
+
+Credit Tekalign / [PR3240](https://github.com/CrocSwap/integer-mult-bounds/pull/3240)
+for the complete path-copy caller and its handoff,
+[PR3218](https://github.com/CrocSwap/integer-mult-bounds/pull/3218) for the
+comparator integration, 24kHandsome1201 /
+[PR3202](https://github.com/CrocSwap/integer-mult-bounds/pull/3202) for the
+source/event audit, jackmgaller / PR1939 for the stronger copy baseline,
+Sagar Thakrar / PR1781, ywz65 / PR2638, Charles Bethin / PR662 and the full
+native/construction lineage preserved in the predecessor notices.
+Memoization is classical. The new contribution is this scoped cache,
+preservation argument, complete-caller integration and measurements.
+New material is Apache-2.0. Independent human and formal proof-kernel review
+are unclaimed.
+
+The overlap helper covered 363 open PR records and 6,096 Discussion records;
+its local note coverage was sparse. Targeted main-history README and merged
+PR searches found PR3240's existing copy improvement before the target was
+reserved. The remaining frame-span step was not found in those searches.
+These checks do not establish global novelty or cover unpublished work.
+
+The scope remains the exact retained finite R2 caller. No current selected
+cold replay, regenerated native artifacts, new native semantics, physical
+ownership, precision/tape, all-size compiler, supplier admission or complete
+multiplication theorem is established. Hosted replay does not certify the
+local timing percentage. The cache does retain additional immutable sets;
+no peak-memory improvement is claimed.
+
+## Open next questions
+
+Does another complete native caller repeat enough long frame bases to benefit
+from this cache? First profile a named caller against its fastest existing
+implementation, and enumerate its input types and mutation boundaries.
+Caller-specific source lifetimes and invalidation remain blockers to general
+adoption. No second caller or further optimization is reserved.
+The structured question is in [TASK.json](TASK.json).