docs(tasks): decompose wave 4 — the postgres kv engine, the fleet host's full seam, the first SKIP-posture column

Five tasks against the wave-3 contract surface as reviewed (no amendments from the gate): - engine-postgres: the fleet-capable kv engine — the B5 row shape (fillfactor 90) in one engine-owned schema, the deadpool pool with per-connection prepared-statement discipline, the synchronous_commit parity knob wired per-connection, ON CONFLICT DO NOTHING CAS, the stable MVCC-snapshot list cursor, the batch-delete helper (key = ANY($1), consumer wave 6), the read-only virgin-store split - engine-postgres-fleet: the engine-state seam's full clause families (ADR-012 §5's postgres row — every family yes): gc_pins + gc_window, the joint tx ownership rule in the JointTx shape, pin_commit atomicity, pin_renew/pin_check/arbitrate, the pg advisory lock as the sweep lease's shipped provider; fleet activation stays wave 6 - store-postgres-construction: KvEngine::Postgres slots in, the KvCursor arm, the dual-tier/kv-only constructors (DSN + opts + threshold + window delay), the non-fleet posture recorded, the pg-pure build verified - suite-column-postgres: the first SKIP-posture column — the alkstore pg-factory pattern reused (fresh schema per open, CASCADE teardown, env-driven ALKBLOBS_PG_* settings), durable-schedule sweep rows, acceptance green against the harness server (pglo-poc :15432, verified live) - review-wave-4: the engine-wave gate (engine-vs-contract conformance) Verification: dependency graph validated (all ids resolve, no cycles, topological order clean); docs-only change. Refs: docs/plans/implementation.md §Wave 4
2026-10-12 05:49:28 +00:00
1 parent 611d30a3c4
commit 7ea6dd6bcb
@@ -0,0 +1,129 @@
+---
+id: store-postgres-construction
+name: postgres constructor wiring — the fleet-capable store shapes
+status: pending
+depends_on: [engine-postgres, engine-postgres-fleet]
+scope: narrow
+risk: low
+impact: component
+level: implementation
+tags: [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