alkblobs/tasks/split-postgres-pg-lo.md

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

id	name	status	depends_on	scope	risk	impact	level	tags
split-postgres-pg-lo	postgres.rs → postgres/, pg_lo.rs → pg_lo/ — the engine giants split; re-exports unchanged	completed	mem-default-on	moderate	medium	component	implementation	wave-8 review-001 split structure

Description

Review-001 D-1's other two god files: src/postgres.rs (2,936) and src/pg_lo.rs (3,089) — the two SQL-tier engines. Same method as the sibling splits: pure moves, no behavior change, lib.rs re-exports unchanged, #[cfg(feature)] gates moving with the module. The file boundaries between the engines are already clean (the wave-4/5 seam pattern); the splits are within-engine.

postgres.rs (feature postgres) — proposed shape, the task's to adjust with a recorded note:

• postgres/mod.rs — module doc + intra-re-exports.
• postgres/schema.rs — bootstrap/ensure, the session options, the busy_timeout-analogue posture text.
• postgres/pool.rs — the pool setup and the per-connection prepared-statement discipline (PgOpts itself is not here — it lives in pg_common.rs, which stays as it is).
• postgres/cas.rs — the CAS rows, the stable-cursor list, batch-delete, synchronous_commit parity.
• postgres/pins.rs — the pin clause family (pin_commit/ pin_renew/pin_check/arbitrate's SQL half).
• postgres/windows.rs — the window family + reap_orphans' kv-side neighbors.
• postgres/joint.rs — PgJointTx and the sweep lock (sweep_lock_acquire/release).
• tests ride their subject modules.

pg_lo.rs (feature pg-lo) — proposed shape:

• pg_lo/mod.rs — module doc + intra-re-exports.
• pg_lo/staging.rs — PgLoStaging (the staged chunked lowrite tx, its Drop body).
• pg_lo/windows.rs — descriptorless lo_get windows + the companion rows + the size probes.
• pg_lo/reap.rs — reap_orphans/reap_orphans_tx (wave 9's F-4 work concentrates here — that is why it gets its own file).
• tests ride their subject modules.

pg_common.rs (321 lines) stays as it is — it is not a god file and its shared clauses are already the extracted shape. The blanket dead-code allows follow the sibling splits' discipline. No fixing: F-2/F-4 are wave 9's; the D-2 coverage work is wave 9's too.

Acceptance Criteria

• both files are directory modules; lib.rs's re-export set byte-identical (audited)
• every moved region is a move, not a rewrite (move detection on the diff; spot-reads against the old blobs)
• the feature gates intact: pg-lo without postgres still compiles (ADR-010 §1's consequence), the pg-pure builds check clean
• the pg_lo staging/joint-tx Drop bodies land unmodified in their new homes (F-2's wave-9 anchor points preserved)
• the full suite green (default, --all-features server-less; the live-pg acceptance runs at the wave gate)
• gates green: cargo test, cargo test --all-features server-less, clippy across variants (incl. the pg-pure), fmt, doc

References

• docs/reviews/001-storage-surface-general-review.md (D-1; F-2/F-4 as the wave-9 anchors this split prepares)
• docs/plans/implementation.md (§Wave 8; §Review gates — the split gate)
• src/postgres.rs, src/pg_lo.rs (the files this task splits)
• docs/architecture/decisions/007-two-kv-engines-sqlite-and-postgres.md, 009-pg-lo-large-tier-engine.md, 010-backend-io-seams-and-fleet-state-home.md (the engines' contracts — the module docs the splits inherit)
• tasks/split-store.md, tasks/split-ops.md (the sibling splits; the same method and audit)

Summary

Completed 2026-10-16. Both god files became directory modules as pure moves — every moved region is a byte-identical slice of the old blob (slice-based assembly with anchor assertions, then a line-diff audit showing only the expected edit classes: module-doc headers, import headers, visibility widenings, scoped allow lines, test-mod wrappers). lib.rs is byte-unchanged (the pub mod declarations resolve to the directories as-is) and store.rs's imports (crate::postgres::{PgJointTx, PostgresBackend, PostgresCursor}, crate::pg_lo::{PgLoBackend, PgLoCursor, PgLoStaging}, crate::postgres::DEFAULT_PIN_TTL_SECS, crate::pg_lo::LOWRITE_CHUNK) all hold their paths via the intra-module re-exports.

Design-point adjustments (recorded per the task charter):

• The impl EngineFleetState is one trait impl and cannot split (it carries the JointTx associated type) — so it lives whole in pins.rs: begin_joint_tx/joint_put joined the pin clauses (pin_commit/pin_renew/pin_check/pin_reap/arbitrate) and the sweep lease. joint.rs still gets its task shape: the PgJointTx impl, the sweep_lock_key helper (pub(super), the lock-key namespace), and the joint-tx + sweep-lease tests. The window-family trait impl stayed whole in windows.rs; the Backend impls stayed whole in cas.rs/windows.rs.
• The shared structs stay on the module roots — PostgresBackend
  • PgJointTx in postgres/mod.rs, PgLoBackend + PgLoStaging in pg_lo/mod.rs — so the sibling impl blocks keep their field access without visibility edits per field; PgLoCursor is wholly in pg_lo/windows.rs (constructed and read only there). DDL helpers live in schema.rs/pg_lo's mod root (pub(super)); the LO statement primitives (lo_create/lo_open/lowrite_all) live in pg_lo/staging.rs, the window machinery (lo_get_window/read_windows) in pg_lo/windows.rs.
• The blanket #![allow(dead_code)] is gone from both engines (the sibling splits' discipline). The truly not-yet-consumed items carry scoped allowances with the consumer named: PostgresBackend::delete_batch (the sweep-batch shape; the store core's delete paths arbitrate and delete per key), PostgresBackend::system_identifier and PgLoBackend::system_identifier (the pg-lo fleet constructor, feature pg-lo / all(postgres, pg-lo)), the pg_lo reaper impl (reap_orphans/reap_orphans_tx — wave 9's F-4 anchor, whose consumer is the embedder's operator runbook), and the pg-lo test-only mid-driver failure-injection knob (its store-core consolidation driver is the all(postgres, pg-lo) build's consumer). nanos_to_time moved into the cfg(test) fixture modules (its only consumers), new_schemaless with it.
• pg_lo/testing.rs (cfg test): the per-test dedicated-database harness, the DSN plumbing, the read-seam/staged helpers, and the catalog probes for the zero-residue gates. postgres/testing.rs the schema-per-test harness twin. The pg-lo Harness.dsn field is the joint-form tests' second-engine handle.
• Shared test fixtures (pg_common.rs's test_support) untouched; the crate::postgres::test_support re-export preserved.

Verification (live pg harness, the dockerized pglo-poc postgres:16-alpine on :15432 — thanks to the session's flag): with ALKBLOBS_PG_* set, cargo test --features postgres (186 lib

• 87 conformance), --features pg-lo (155 + 71), and --all-features (271 + 125) ran for real, all green — and the lib test lists diff 1:1 against pre-split (only path relocations postgres::tests::X → postgres/<file>::tests::X, counts exact). Server-less variants (cargo test, cargo test --all-features without env) skip the pg columns cleanly and are green. Gates: cargo clippy across default/postgres/pg-lo/--all-features (-D warnings), cargo fmt --check, cargo doc --no-deps (zero warnings). Audit exceptions (doc touches, not code): the two module-doc allow paragraphs rewritten to describe the scoped allowances + the split layout; stale file references ( src/postgres.rs/src/pg_lo.rs prose in the pg_lo module doc and pg_common.rs's shared-helper doc) updated to the directory forms. One pre-existing, unreproduced flake observed during the runs: ops::harness::the_paused_fleet_token_expires_reaps_and_the_reput_ backstop_never_loses_silently (ops.rs — untouched by this split) failed once in two live full-suite runs and passed everywhere else, including three consecutive live runs after; watch it at the wave gate. The pristine-baseline cargo clippy --no-default-features --all-targets failure (empty engine-enum exhaustiveness in store.rs) is pre-existing and outside this task's gate list.