alkblobs/tasks/store-postgres-construction.md

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

id	name	status	depends_on	scope	risk	impact	level	tags
store-postgres-construction	postgres constructor wiring — the fleet-capable store shapes	pending	engine-postgres engine-postgres-fleet	narrow	low	component	implementation	wave-4 store postgres construction

Description

Slot postgres 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"):

• KvEngine::Postgres variant behind #[cfg(feature = "postgres")] + the dispatch arms (put/get/has/size/ delete/list). The kv cursor dispatch slots the postgres materializing body into KvCursor (the recorded sub-enum design point: "postgres (wave 4) slots one arm in here" — the store.rs doc note is updated to the landed state).
• Named constructors, feature-gated on postgres (default-off — they construct under --features postgres):
  • dual-tier kv = postgres + large = local — the fleet-capable-kv production shape (non-fleet here; see below); fallible (config parse, connect, schema bootstrap, the local root creation). Size-threshold dispatch at the constructor-tunable threshold as in the sqlite shape.
  • kv-only(postgres) — no large tier; threshold is the put-time rejection point (ADR-012 §6.2; the rejection machinery is the put seam's, already landed — only the constructor slots in).
  • Both take the connection settings + engine opts (recorded design point: the DSN form — the tokio-postgres Config-parseable string, the alkstore open(config, PgOpts) pin adapted to the named-constructor shape — and the opts shape carrying schema name, pool size, synchronous_commit; engine-configuration concerns ride the constructor parameters, never invented defaults) and the delete-window delay parameter (Duration, default DEFAULT_DELETE_WINDOW_DELAY, 0 the legal degenerate tuning — the sqlite constructors' signature shape).
• Non-fleet posture — these constructors are implicitly fleet: false (ADR-012 §3): the ADR-005 in-process protocol applies verbatim regardless of engine; pins are in-process guards, the sweep lease is the in-process lock, and none of the EngineFleetState clauses run. The fleet: true declaration is wave 6 (the fleet-validity predicate + constructor declarations) — no fleet parameter is added here; wave 6 slots it in without reshaping. Recorded in the constructor docs so the wave-6 slotting is a non-event.
• ensure_gc_schema at construction — the store-core call (engine-neutral; the postgres arm creates gc_pins + gc_window per the fleet host's applicability row). A construction failure is Err(Error::Io) per the fallible-constructor pattern.
• The one-window-host rule's store-core posture — already recorded (the durable window hosts on the kv engine when it is SQL-backed); the postgres arm slots in under it with no reshaping. Verify the recorded posture's wording covers postgres (it names "sqlite or postgres" already — ADR-012 §5) and that the form branch keys off the kv-engine enum, never a flag.
• Stale scope notes updated — the engine-representation doc's "postgres (wave 4)" forward references, the KvCursor design-point note, and any #![allow(dead_code)] scope notes whose scope changes (the batch-delete helper's note stays — its consumer is still wave 6).
• Constructor unit tests: the modes construct and introspect correctly (mode()/threshold()), ensure_gc_schema ran (both GC tables exist in the fresh schema), the window-delay default is the pinned constant, kv-only rejection wiring unchanged, the dual-tier shape round-trips end-to-end (a smoke put/get through both tiers). Env-driven, skipping cleanly server-less (the engine tests' convention).
• The pg-pure build — cargo check --no-default-features --features postgres (and the tests target under it): ADR-013 §4's supported non-default configuration first becomes constructible here; verify it compiles clean.

Acceptance Criteria

• KvEngine::Postgres slots in; all six kv ops dispatch; the kv cursor body slots into KvCursor (the design-point note updated to the landed state)
• dual_tier_postgres_local + kv_only_postgres constructors exist behind feature postgres, take connection settings + engine opts + threshold + window delay, fallible where I/O is fallible
• ensure_gc_schema runs at construction (both GC tables in the fresh schema); the window-delay shipped default is 5 min (pinned constant) and constructor-tunable; 0 legal
• The non-fleet posture recorded (in-process protocol verbatim; the fleet: true declaration is wave 6, slotting in without reshaping)
• The one-window-host posture verified to cover postgres; the form branch keys off the kv-engine enum
• The pg-pure build (--no-default-features --features postgres) compiles clean
• cargo test (default) green; cargo test --features postgres green server-less (skipping); cargo clippy --all-targets -- -D warnings and cargo fmt --check green (default + --features postgres)

References

• src/store.rs (the engine-representation design point; the constructor modes; the slotting-in pattern; the KvCursor sub-enum design point)
• docs/architecture/decisions/011-vocabulary-tiers-engines-and-fleet-state.md §4 (modes; the constructor table)
• docs/architecture/decisions/012-pre-decomposition-consistency-rulings.md §3 (fleet activation is a declaration — wave 6), §5 (the one-window-host rule), §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/013-family-composition-reactive-boundary-and-feature-graph.md §4 (the feature graph; the pg-pure build)
• tasks/engine-postgres.md, tasks/engine-postgres-fleet.md (the engine
  • seam bodies this wires)
• tasks/store-sqlite-construction.md (the structural twin's recorded design points)

Notes

To be filled by implementation agent

Summary

To be filled on completion