perf(runtime): batch exact source fingerprint reads

[huangruiteng]

Goal And Delivered Outcome

Fresh CLI processes read every packaged TypeScript/JSON source serially before using the managed runtime. Reuse the existing bounded ordered file reader to overlap those reads while hashing the same relative names and original bytes. Public text scanning shares the queue; no new cache or domain decision owner is added.

This advances the shared-authority retirement cadence's B lane (caller-cost qualification). It does not select a default provider, close D2, truncate a Goal response or authorize legacy-writer deletion. Base: main at 3fae8cc40.

Scope And Continuation

• Replace the internal file_text_reads module with file_reads; both active consumers use it. Binary errors propagate, partial fingerprints never become cache entries, topology retry and request-scoped freshness stay intact. Python remains the existing filesystem/managed-process adapter; TypeScript policy is unchanged.
• At most eight reads are pending. Results and failures retain source order, and generator close joins the reader pool.
• Update the existing bilingual RFC checkpoint. Whole-Goal payload/consumer work and sustained provider qualification remain with their existing owners.
• Future-facing refactor: one ordered queue replaces the temptation to add a second binary-only executor. No new capability, extension or provider contract.

Validation

• Tested revision: 6e36f43725632b7265c63feda565adfc3a02cef9
• Run state: finished
• Input classes: synthetic, public_fixture, authorized_private_read_only

Check	Result	Evidence / limitation
Runtime and reader regressions	Passed	100 tests across test_runtime_source_read_batching.py, test_public_boundary_parallel_reads.py, and Effect request-scope/restart/integration suites. Original bytes, changed/deleted source, errors, bounded scheduling, private exclusion and real subprocess recovery.
Static checks	Passed	Repository mypy, changed-file Ruff, diff hygiene and public-boundary scan.
Real CLI / backend parity	Passed	Detached real File and SQLite stores, independent Effect processes, production entrypoint.main, identical source directory; 20 paired responses differed only at enumerated observation-time fields. Raw state/traces stay private.
Installed wheel	Passed	Built and verified Chat assets; installed final wheel in an isolated environment. Its actual CLI File/SQLite responses match a fresh source run except observation times. Default local installation unchanged.
Risk-based premerge	Failed	Five direct checks and 18/19 selected checks passed. semantic-vocabulary-drift-smoke.py fails four pre-existing history.py registry-census locations on both immutable base and head; #5321 owns that repair. No passing quality/readiness claim.

The initial frontend build lacked local npm dependencies; after npm ci, bundle and final wheel builds passed. The prototype's two mypy errors were fixed before the final tests/build.

On macOS arm64, Python 3.13.13 and Node 24.21.0, nine alternating post-warmup fresh-process samples per variant used 246 TS/JSON files (3,003,024 bytes):

Real status workload	Serial median	Batched median
File whole command	1.985 s	1.874 s
SQLite whole command	2.106 s	1.937 s
File fingerprint stage	249.7 ms	51.7 ms
SQLite fingerprint stage	228.3 ms	55.8 ms

OS caches were not flushed; command timings vary and are not provider-throughput claims. Counterexample: repeated same-process hashing with memoization explicitly cleared regressed from 9.3 to 17.7 ms. Normal unchanged requests still use the existing memoization. This is local evidence, not universal platform/fleet qualification. Public tests reproduce semantic invariants; private snapshot timings are not a public benchmark.

Frontend / Shared-Authority Impact

UI impact: none. No frontend, renderer, payload-selection or provider-state logic changed; complete File/SQLite response comparisons cover records and metadata. The shipped frontend bundle was built/verified, but no new visual journey or PostgreSQL performance claim is made. No migration, runtime route or persisted contract changes.

Boundary Checklist

• Private snapshots, identifiers, paths, traces and measurement scripts are excluded.
• DCO sign-off present; single-purpose runtime refactor plus durable tests/checkpoint.
• Independent exact-head review requested; this draft is held for baseline/readiness repair and is not merged or installed.