rea/experiments/atomic-codemode/string-span-study.md

Incoming reference spans and pooled strings

This experiment adds individually traceable incoming reference occurrences for inclusive target-address spans. It does not establish whole-string use from a reference into shared storage. No PR or integration is intended.

Before this work, the branch refreshed main to 0c7b6d834 in c8d831936. The native overlay remains based on Kuna fe01d6294eb0d1053ce343c8943646df88e143fc. The immutable tested executable SHA-256 is 2e398e7229e30b6d2387a802db8a0050764119a6b457020d334855e36e69d6c5; the full overlay is kuna-native-ir.patch. Node is 24.18.0 / npm 11.16.0.

Existing capability and missing composition

Native Kuna already aggregates xrefs and owner functions over a string's encoded extent. Its string output does not include each reference's source/target pair. REA's cheap inventory intentionally skips that analysis; the existing reference operation selects exact addresses, so complete occurrence retrieval previously required enumerating the encoded span. This is an interface/composition gap, not evidence that Kuna had no string-span aggregation.

On real Linux SQLite, exact no such table occupies 0x11b376–0x11b383 and sqlite_schema occupies 0x11b33f–0x11b34c, both including NUL. Base-address queries return one occurrence each; their full spans retain seven and four. Nine interior occurrences target the table / schema suffixes. Calling all seven references uses of the complete error message would be wrong. The frozen task oracle separates occurrence completeness, symbol membership, bytes, register passing and conditional message selection.

Implementation and bounds

The existing named references operation accepts explicit ranges, preserving the old exact-address and outgoing-function selectors. CLI, SDK, Direct MCP and Code Mode use the same contract and owner. There remain 19 named methods, 22 Direct tools and four Code Mode tools. Both advertised catalogs were validated after actual SDK conversion, including valid/invalid reference selectors.

The native BTreeMap index owns sparse inclusive range lookup, including u64 max without end-address increment. The string aggregate also uses this owner, removing its per-byte lookup loop and quadratic function deduplication. Legacy and range wire rows share endpoint/function interpretation and one JSON escaping writer. A batch builds one index, supports 16 spans and 128 selected rows per span, and streams into an 8 MiB encoded-output budget. Selected row pointers are bounded; serialization failure returns an error without partial JSON stdout. These bounds cap native work/serialization and match the experimental fact page.

The TypeScript provider boundary owns exact u64 parsing, row consistency and normalization for both formats. Range metadata binds by explicit query index, not catalog/array order. Overlapping and duplicate caller ranges remain separate; source_row indexes the retained batch's original flat xrefs array. It is not a global occurrence ID. Malformed or unavailable data remains an error with source Evidence where captured, never an empty observation.

Native capture cache keys cover target/engine identity, ordered spans, kinds, offset and limit. Fields project the same retained source. One immutable parsed range batch is retained per lease and cleared after successful close. Different pages still rebuild a native index; this is not a persistent analysis database. Coverage explicitly leaves discovery, indirect targets, runtime binding, memory access overlap and whole-string use unknown/not established. Target-coordinate membership does not expand import aliases or establish all bytes touched by an access.

Executed verification

• Native release tests: 25 listing::xrefs, two range CLI tests and 15 JSON writer tests passed, including sparse/full-u64 selection, selector conflicts and escaped-byte streaming bounds. Release binary rebuilt after final changes. A real one-byte output-budget query exited with the explicit capacity error and zero stdout bytes, confirming fail-closed serialization at the CLI boundary.
• Focused production boundary: 23 existing reference tests plus four new range groups passed (27 total), with full runtime compilation. Focused owner graph typecheck, changed-file lint and formatting passed. Full check:fast was attempted but stopped at the 3.25 GiB threshold after 45.806 s; sampled peak 3,330.8 MiB, sampled OOM=0, final payload counters unavailable. Its processes exited after owned-scope cleanup. This is not a passing full root typecheck. check:pr and an exhaustive native corpus were not run. Experiment pushes bypass the resource-limited pre-push gate rather than repeat it unbounded.
• All 90 experimental JavaScript tests passed. Five resource receipt/policy tests passed, including rejecting unsafe bounds before process acquisition.
• Real SDK, Direct MCP and Code Mode range verifiers passed all eleven exact occurrences/owners, field projection/source reuse, overlaps, repeated spans, empty u64-max page, pagination, selected bytes/instructions, raw source hashes and source-row traceability. Each verified cleanup.
• The public experimental CLI ran string-span-example.txt and returned totals seven/four. Native string aggregate JSON remained semantically identical to the previous engine, including counts and function lists. Real x86 SSH complete function/prototype fidelity and AArch64 xref/return verifiers passed on the new engine. Targets were never executed.
• verify-string-span-machine.py independently passed ELF loaded bytes, all eleven selected GNU LEA targets, exported function interval membership, RIP displacement math, mask/CMOV bytes and the two ELF PLT-slot relocations. This is not a proof of dynamic binding or global xref completeness.
• The canonical native overlay passed forward application against a temporary upstream index and reverse application against the owned patched worktree.

The first public SDK attempt exposed a stale registry refinement that rejected the new selector despite the standalone contract passing. That redundant guard was removed; the regression now checks the final registry, and the second SDK attempt passed. Preserve the failed attempt (range-sdk.log) in the record. An initial focused build crossed the default 3 GiB early stop, without OOM. A validated optional threshold allows the build to use 3.25 GiB; its successful focused run took 35.964 s / 35.703191 CPU s, peak 3,084.7 MiB. The hard cap remains 4 GiB, swap zero, one CPU and 192 tasks. Analysis/model runs retain the default 3 GiB early stop. Payload-exit counters verify cleanup and OOM=0 for all successful bounded runs here; kernel process-family memory includes file cache, not just RSS. Exited transient cgroup final counters are unavailable.

Measured equivalent reference task

The exact-address baseline enumerates both 14-byte spans and retains all raw sources. The new range query obtains the same eleven occurrences and owners with one native batch. These are reference-phase measurements after inventory selection, not complete model costs; cold means fresh lease/capture cache, not cold kernel file pages. The same new engine is used in both rows.

SDK reference workflow	Cold wall	Local family CPU	Warm wall
28 exact-address queries	48.123 s	47.791799 s	9.899 ms
One two-span batch	1.821 s	1.806206 s	0.984 ms

The selected cold phase is about 26.4 times faster. This is shared native work, not a Code Mode speedup. Old-engine exact enumeration also agreed on every fact and took 46.806 s. The independent Direct and Code Mode batch preflights took 1.755 / 1.798 s cold and 3.066 / 9.542 ms warm. They have different transport overheads and are single observations, not benchmark distributions.

Whole verifier resource receipts (which include additional validation queries):

Run	Wall	Local family CPU	Kernel family peak
New-engine exact baseline	50.557 s	50.055582 s	475.6 MiB
SDK range verifier	14.616 s	14.279055 s	482.7 MiB
Direct range verifier	15.120 s	14.742037 s	312.6 MiB
Code Mode range verifier	15.630 s	15.257697 s	331.8 MiB

These suites have different validation work; their peak values do not establish an equivalent-task memory reduction. Scripted checks have no model token usage. Raw receipts/captures live in the ignored .cache/atomic-codemode/range-* paths. Selected receipt SHA-256 values:

• range-exact-after.log: cb1d19a4f58face2d442868add0289c3ca62f070ef14f5e4bf0cc101b3bd9ed8
• range-sdk-v2.log: f203ab548d7509b37a15c39aaf8e466e61f7591eddcb1868be97477811a698c8
• range-direct.log: c4efbcee95e087fa676b560f70bbb8f6617475be122289c3052f19af02efb2b8
• range-codemode.log: 1d967347c31c99f8caf71391502a7e24ef5fcdcaaaddc5c8d1272eb5b8d7eeae

Real-model results will be recorded separately after the frozen three-profile trial. No token, general complex-software or adapter superiority claim follows from these preflights.