Repository navigation
perf(storage): project authenticated properties before overlay materialization #1247
Description
Verified cause and measured baseline
During #1207 on integrated main 8b854b9b, PropertyOverlayExec::execute asks the catalog for every property, then projects the completed batches. The catalog already has an authenticated projected reader, but this public scan passes no selected-property set. Unrequested wide values therefore enter decoded rows and JSONL overlay spill.
The frozen facade probe at test-only 3925c91c49b31381957053fd1a8abb2ceef99897 constructs 4,097 random-ID nodes, a nullable score and sixteen nullable 256-byte text columns. All narrow/full/ordered LIMIT16/negative-lookup exact oracles pass. Executable SHA256 a1f565ac417cde5ddf23b9252ebd926ea23ad15ed7f84f90ff318f2e2a37ab65.
Three fresh processes per case, five queries per process: narrow first-query median321,275,312ns and reused median290,638,441ns. Separate tracing records227,678,948 successful read bytes and approximately131,441,481 write bytes per five-query process, including90,547,165 JSONL spill bytes. These are syscall returns, not physical disk I/O. Retained allocation17,768,448bytes; sampled private temporary peak18,309,120bytes. Disk sampling globally deduplicates shared inodes and excludes unlinked files/directories; it is not a hard bound. Full-projection, LIMIT and negative lookup have comparable execution latency.
This is a focused correctness-preserving query-efficiency repair selected for bounded evaluation under #1207. No other open issue owns this verified scan/materialization cause. Native parent/close gate: #1194.
Acceptance criteria
- Pass requested properties into the existing authenticated projected overlay reader before decoding/materialization. Reuse current readers; no parallel engine, new writer abstraction, durable format, compatibility shim or migration.
- Preserve output schema/order, nullable and absent fields, duplicate semantics, newest overlays and tombstones, mandatory identity/key checks, authentication and corruption refusal. Preserve cancellation/consumer-close behavior; do not silently skip unread integrity checks solely because LIMIT is satisfied.
- On the frozen representative narrow workload, eliminate at least76,267,520 successful syscall write bytes across five queries: one complete15,253,504-byte raw unrequested-payload pass per query. This threshold was fixed from baseline before candidate edits, not selected after seeing a result.
- Permanent allocated bytes must remain17,768,448; no extra publishing/maintenance pass. Sampled private/overlap disk must not exceed18,309,120/36,077,568bytes under the same sampler. Baseline-derived narrow whole-process CPU ceiling1.61s and RSS137,248KiB; record all repetitions and timing variance. Other cases retain their own baseline-span ceilings in the assessment protocol. These are observational selection limits, not portable deterministic native-memory bounds.
- Add deterministic representative assertions for avoided materialization/work and exact public results. Prove actual construction, scalar/map mutation and REMOVE, immediate query, retained snapshots, reopen, export/full verification/clean import and subsequent mutation. Preserve existing malformed/unselected-row and resource-admission regressions.
- Freeze baseline/candidate executables before measurements; report CPU, syscall and filesystem I/O, native RSS, retained/temporary allocation separately from logical counters. Keep failed experiments honest and integrate evidence into test(perf): assess practical query and storage efficiency opportunities #1207/epic(storage): reduce lifecycle amplification and improve persistent storage/query efficiency #1194.
- Focused PR to main, appropriate local gates, exact-head CI Gate, CLEAN merge state, verified review findings, squash merge and verified closure. No new scale workflow or S24/S26 execution.
Protocol and raw evidence are currently retained in /tmp/gf1207-projection-selection-protocol.json, /tmp/gf1207-wide-baseline-results.json, /tmp/gf1207-wide-*-trace.json and /tmp/gf1207-wide-workspace-results.json; commit the concise report with the accepted change/assessment.
Activity
perf(storage): project authenticated properties before overlay materi…
DecisionNerd commentedon Sep 29, 2026
Evidence relocated from the docs tree (#1625). The 1 file(s) below were committed under
docs/development/as measurement evidence for this issue. They are removed from the tree by #1628 (the #1625 pull request); the repository keeps method and content digests, results live here. Every file remains available at its permalink on commit29a7b34ebe44, and its SHA-256 is recorded next to it.Files (1 total, 1,147 lines)
docs/development/evidence/property-projection-1247.jsonsha256:47d274bad06d37555de82f4caa28460065bc667662f6a34657592abed54cf53e