alkblobs/tasks/store-pg-lo-construction.md

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

id	name	status	depends_on	scope	risk	impact	level	tags
store-pg-lo-construction	pg-lo constructor wiring — the consolidation shape and the window-host completion	pending	engine-pg-lo engine-pg-lo-window	moderate	medium	component	implementation	wave-5 store pg-lo construction

Description

Slot pg-lo into the facade's engine representation — the slotting-in pattern src/store.rs's module doc pinned ("adding an enum variant and a named constructor is slotting in"). This task also completes the one-window-host rule's store-core wiring, which is more than slotting: the durable window gains its large-engine host arm.

• LargeEngine::PgLo variant behind #[cfg(feature = "pg-lo")] + the six large-op dispatch arms (put_staged/get/has/size/ delete/list).
• The large cursor bodies slot in — AnyCursor::Large and AnyStaging::Large are currently concrete over the local bodies (LocalCursor/LocalStaging). Named design point (the recorded KvCursor sub-enum pattern's large-tier twin): grow a LargeCursor/LargeStaging sub-enum behind AnyCursor/AnyStaging's one large arm (local + pg-lo variants) rather than one AnyCursor variant per large engine — the same bounded-memory argument as the kv side, recorded for the review gate, with the store.rs design-point notes updated to the landed state.
• Named constructors, feature-gated on pg-lo (default-off):
  • dual_tier_postgres_pglo — kv = postgres + large = pg-lo: the consolidation posture (ADR-009's "one engine to operate"); its landing completes the fleet-valid engine set (the store.rs module doc's recorded forward reference — pg-lo's wave-5 constructor is the last fleet-valid engine). Implicitly fleet: false (ADR-012 §3): the ADR-005 in-process protocol applies verbatim; the fleet: true declaration is wave 6 (the composite fleet-validity predicate + constructor declarations) slotting in without reshaping — no fleet parameter carried; recorded in the constructor doc. Connection-settings design point: two DSN + opts parameter pairs (kv and large) — cross-instance kv=postgres + large=pg-lo is valid non-fleet (ADR-012 §4), and the consolidation shape passes the same DSN/opts to both; the suite factory's schema-sharing corollary (one minted schema passed to both engines vs two schemas) is recorded with it.
  • dual_tier_mem_pglo — kv = mem + large = pg-lo (features mem + pg-lo): the one-window-host rule's named test topology (ADR-012 §5: the durable window hosts on the large engine when the kv engine is not SQL-backed). Non-fleet (mem is never fleet-valid).
  • No kv_only(pg-lo) — pg-lo is a large engine; kv-only modes take kv engines only. No sqlite+pg-lo constructor this wave — valid non-fleet per ADR-012 §5 but not named by the plan; added on demand (recorded).
  • Both take the delete-window delay parameter (the DEFAULT_DELETE_WINDOW_DELAY signature shape; 0 the legal degenerate tuning) — the durable form's cadence knob on either host.
• The one-window-host rule's store-core completion (the substance of this task):
  • ensure_gc_schema at construction — the call currently dispatches on the kv-engine enum only. It must follow the host rule: kv SQL-backed (sqlite/postgres) → the kv host's call (pg-lo's window clauses dormant — the consolidation shape's pg-lo schema carries no gc_window); kv = mem + large = pg-lo → the pg-lo host's call (gc_window in the pg-lo schema). The dispatch consults the large engine only when the kv engine is not SQL-backed; it keys off the engine representation, never a flag.
  • The sweep form branch — currently KvEngine::Mem runs the inline form unconditionally. It gains the large-host arm: mem kv + LargeEngine::PgLo runs the durable form on the pg-lo host (sweep_window_durable is already generic over W: EngineWindowState — the pg-lo arm slots in); mem kv + LargeEngine::Local (or no large tier) stays inline. The sqlite/postgres arms are untouched (their hosts win the window per the rule). The module doc's recorded "pg-lo dormancy slots in without reshaping" note is updated to the landed state (dormancy did; the large-host arm is the reshaping the rule always named).
• Stale scope notes / forward references updated — the store.rs module doc's wave-5 mentions (the engine-representation note, the fleet-valid-set note, the one-window-host paragraph, the LargeEngine doc's "pg-lo slots in at wave 5"), the PUT_CHUNK doc note ("pg-lo's measured 512 KiB lowrite knee is that engine wave's concern" — now landed; the engine's constant is the authority), and any #![allow(dead_code)] scope notes whose scope changes (the batch-delete helper's wave-6 note stays).
• Constructor unit tests: the modes construct and introspect correctly (mode()/threshold()); ensure_gc_schema ran on the right host in both shapes (consolidation: gc_pins + gc_window on the kv schema, no gc_window on the pg-lo schema — the dormancy assertion; mem-pglo: gc_window on the pg-lo schema); the window-delay default is the pinned constant, tunable, 0 legal; the dual-tier shapes round-trip end-to-end (a smoke put/get through both tiers with LO placement asserted — the companion row + LO present, kv entries not in pg); a mem-pglo durable-form sweep smoke (zero-delay: first sweep stages into the pg-lo schema's gc_window and executes nothing, second sweep executes the overdue set re-arbitrated at execution time — the form-branch-is-large-host proof). Env-driven (ALKBLOBS_PG_*), skipping cleanly server-less (the engine tests' convention); the janitor discipline rides from the start (amendment A2).
• The pg-lo pure builds — the supported non-default configurations are cargo check/test --no-default-features --features "pg-lo,mem" (the one-window-host topology's build; the mem-pglo constructor constructible) and cargo check --no-default-features --features "postgres,pg-lo" (ADR-013 §4's pg-pure consolidation build); verify both compile clean. The literal kv-less config (--no-default-features --features pg-lo) is not a gate and cannot compile the whole crate — do not burn time on it: with no kv feature enabled, KvEngine/KvCursor go empty (E0004) and the facade's by-reference dispatch matches are non-exhaustive (references are always considered inhabited, so an empty enum behind & still requires arms). This is structural, not a bug: per ADR-011 §4 every constructor mode pairs a kv engine, so a build with zero kv engines is not a supported configuration (ADR-013 §4's supported non-default configurations all include one). The shared pieces themselves (pg_common, the engines) compile in the literal config — only store.rs errors. The finding is the wave-5 engine task's (d69d9a3, recorded in its Notes); this task's verification uses the two meaningful builds above.

Acceptance Criteria

• LargeEngine::PgLo slots in; all six large ops dispatch; the large cursor/staging bodies slot through the recorded sub-enum design point (the store.rs notes updated to the landed state)
• dual_tier_postgres_pglo + dual_tier_mem_pglo constructors exist behind feature pg-lo, take connection settings + opts + threshold + window delay, fallible where I/O is fallible; the consolidation constructor's doc records the implicitly-non-fleet posture and the fleet-valid-set completion
• ensure_gc_schema follows the one-window-host rule at construction (kv host on dual-SQL — pg-lo schema carries no gc_window; pg-lo host on kv=mem — contract-tested both shapes)
• The sweep form branch runs the durable form on the pg-lo host for kv=mem + large=pg-lo and the inline form otherwise; the branch keys off the engine representation, never a flag
• The connection-settings design point (two DSN+opts pairs; the consolidation corollary) decided and recorded
• The pg-lo pure builds (--no-default-features --features "pg-lo,mem" and --features "postgres,pg-lo") compile clean (the literal kv-less config is not a gate — see the Description bullet)
• cargo test (default) green; cargo test --features pg-lo and --features "pg-lo,mem" green server-less (skipping); cargo clippy --all-targets -- -D warnings and cargo fmt --check green (default + the pg-lo feature variants)

References

• src/store.rs (the engine-representation design point; the constructor modes; the slotting-in pattern; the KvCursor sub-enum design point; the sweep form branch; the one-window-host paragraph)
• docs/architecture/decisions/011-vocabulary-tiers-engines-and-fleet-state.md §4 (the constructor table; the consolidation posture's mode reading)
• docs/architecture/decisions/012-pre-decomposition-consistency-rulings.md §3 (fleet activation is a declaration — wave 6), §4 (the GC-state host; cross-instance valid non-fleet), §5 (the one-window-host rule and the pg-lo dormancy), §6.3 (dual-tier shapes)
• docs/architecture/decisions/008-trait-size-probe-fleet-gc-and-large-engines.md §2 (the window delay, default 5 min)
• docs/architecture/decisions/009-pg-lo-large-tier-engine.md (the consolidation posture this constructor ships)
• docs/architecture/decisions/013-family-composition-reactive-boundary-and-feature-graph.md §4 (the feature graph; the pg-lo-pure builds)
• tasks/engine-pg-lo.md, tasks/engine-pg-lo-window.md (the engine + seam bodies this wires)
• tasks/store-postgres-construction.md (the structural twin's recorded design points)

Notes

To be filled by implementation agent

Summary

To be filled on completion