alkblobs/tasks/split-store.md

id, name, status, depends_on, scope, risk, impact, level, tags

id	name	status	depends_on	scope	risk	impact	level	tags
split-store	store.rs → store/ — facade, dispatch, fleet, sweep, gc-glue, tests; re-exports unchanged	completed	mem-default-on	moderate	medium	component	implementation	wave-8 review-001 split structure

Description

Review-001 D-1's biggest file: src/store.rs at 10,553 lines — the facade (put seam x three tiers x fleet/non-fleet, the read paths, the constructor family), the engine-side enum dispatch, the fleet driver, the sweep executor, the GC glue, the window plumbing, and ten test sections in one file. The wave's method (docs/plans/implementation.md §Wave 8): pure moves — the split is mechanical, no behavior change anywhere, lib.rs re-exports unchanged (the public surface does not move; review D-1's own observation: this is not a one-way door). Convention 10 requires modules, not flatness — directories are in.

Proposed module shape (the decomposition's proposal; the task may adjust a boundary, recording the final shape as a design-point note on the module docs):

• store/mod.rs — the directory module: the module doc (what lives where and why, the old file's module doc carried over), the intra-store re-exports, and lib.rs's mod store; untouched.
• store/put.rs — the put seam's paths (known-length one-pass; unknown-length pre-threshold buffering; the staged-put restart derivation; the fleet put driver's store-side).
• store/read.rs — get/stat/read_range/has/delete/list dispatch fall-through and the direct-delete refusal path.
• store/construct.rs — the constructor family, the constructor modes, the fleet-validity predicate, the kv-only re-routing posture.
• store/engines.rs — the engine-side enum dispatch (the KvEngine/LargeEngine enum plumbing between the facade and the backends), unless reads cleaner staying with the facade text — the boundary is the task's to place.
• store/fleet.rs — the fleet driver, the joint entry+pin tx store-side, the engine-state clause consultation.
• store/sweep.rs — the sweep executor, the windows (sweep_window_fleet et al.), the GC glue (arbitrated_delete, delete_everywhere).
• the test sections ride their subject modules (#[cfg(test)] mod tests per file, matching the file's existing test layout), not one giant test file — each test section moves with the code it tests.

In-wave resolutions this task carries:

• D-3 — the dead KvEngine::ensure_gc_schema/LargeEngine:: ensure_gc_schema twins (zero callers; docs claim ensure_gc_schema_at_construction consults them and it does not). Decomposition preference: route the construction call through the methods and delete the re-implementation (one dispatch, honest docs). Deleting the methods + correcting the construction fn's docs is the accepted alternative — the chosen point recorded.
• The blanket #![allow(dead_code)] (review-001 D-3's enabler): removed from the split modules; if an item is genuinely not-yet-consumed, the allowance is scoped to it with the consumer named (the standing hygiene block's discipline — no blanket allows survive).

No fixing: review-001's findings F-1 et al. are wave 9's. If the split reveals a trivially-mechanical correction (a doc typo the moves touch anyway), it lands as a noted exception in the task Notes, not a fix sweep.

Acceptance Criteria

• src/store.rs is a store/ directory module with the moved code; lib.rs's public re-export set byte-identical (audited)
• every moved region is a move: line-shifted copies, not rewrites — verified by reading the diff with rename/move detection and spot-reading the moved regions against the old blob
• D-3 resolved (the route-through or the delete), the surviving docs honest, the chosen point recorded
• the blanket #![allow(dead_code)] gone; any remaining allow scoped and consumer-named
• the test sections ride their subject modules; the full suite green
• gates green: cargo test (default — post mem-default-on), cargo test --all-features server-less, clippy across the variants, fmt, cargo doc --no-deps (zero warnings)

Notes (the recorded shape, 2026-10-15)

• mod.rs: the old module doc carried over plus the directory layout section (what lives where, and the boundary notes below); lib.rs's mod store; and re-export list untouched — mod.rs re-exports the public surface from construct and re-exports AnyCursor (consumed by facade.rs's Blob) and FleetState crate-internally.
• The Store struct rides mod.rs (the directory's spine — every submodule impl-blocks it); the shared facade-boundary dispatch helpers (boundary_key, typed_keys) ride mod.rs too, as both read.rs and sweep.rs consult them.
• Boundary adjustments from the proposal (recorded in the module doc's layout section): the whole GC protocol block — including the direct delete verb the proposal put in read.rs — rides sweep.rs whole (delete is the arbitration domain's verb, not a fall-through read op; severing it from arbitrated_delete/ delete_everywhere would lift visibility across the refusal machinery); the fleet put drivers ride fleet.rs whole rather than splitting the dispatch caller into put.rs; the seven construction-themed test sections ride construct.rs; the window/ sweep sections ride sweep.rs; the two fleet-put sections ride fleet.rs.
• The mem reference suite rides store/tests.rs whole — one test module whose shared helper set spans every subject, so chopping it would rewrite call sites (the ops/tests.rs precedent). It sits at file top level — the four-space nesting indent dedented where a level was removed (whitespace-only), use super::* leaning on mod.rs's #[cfg(all(test, feature = "mem"))] import block (each subject file's own #[cfg(test)] import block feeds its riding sections analogously). mod tests' #[cfg(all(test, feature = "mem"))] gate moved to the mod declaration in mod.rs.
• D-3 chosen point: the route-through (the decomposition's preference). ensure_gc_schema_at_construction now consults the engine enums' own ensure_gc_schema methods (one dispatch); the KvEngine twin was the construction arms' body and is now live, and the LargeEngine twin — whose only consumer is the mem arm's large-host consult — is re-gated to feature mem with the pg-lo arm variant-gated, docs unchanged (they claimed the consultation; the route-through made the claim true). Recorded as a doc addendum on the construction fn.
• The blanket allow is gone. Every surviving allowance is a per-item #[allow(dead_code)] whose consumer is named (the fleet predicate/state vocabulary — its consumers compile only with feature postgres; the durable-form family on the sweep executor — SQL-backed hosts only; the inline form — mem hosts only; the construction dispatch and the engine-enum schema arms — per the feature sets that construct them; window_delay — the construction tests' instrument). The hygiene removal surfaced one genuinely dead item the blanket had masked — the key_for helper of postgres_pglo_fleet_put_tests (zero callers in the original too) — deleted as the split's noted exception.
• Audit exception (move-necessitated): visibility lifts — the compiler-demanded pub(crate) set on the cross-file items (the engine-enum and fleet-driver methods, PUT_CHUNK), the FleetState fields (struct-literal construction in construct.rs), and per-file cfg(test) import blocks feeding the riding test modules' use super::* globs (the glob sees the parent file's private bindings; lib-only builds would warn, hence the cfg discipline). Moved region text otherwise unchanged — the generated-then-edited replay (split script re-run against the old blob, diffed against the landed files) shows every hunk in the recorded classes.

References

• docs/reviews/001-storage-surface-general-review.md (D-1, D-3, D-2 — note D-1: "do it before wave 9's docs pass")
• docs/plans/implementation.md (§Wave 8; §Review gates — the split gate)
• src/store.rs (the file this task splits)
• src/lib.rs (the re-export surface that must not move)
• src/facade.rs, src/gc.rs, src/dispatch.rs (the adjacent modules the split must not swallow — they stay as they are)
• tasks/mem-default-on.md (the default matrix the gates read after this lands)