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,128 @@
+---
+id: suite-column-postgres
+name: Conformance suite — the postgres column (the SKIP-posture column)
+status: pending
+depends_on: [store-postgres-construction]
+scope: moderate
+risk: medium
+impact: phase
+level: implementation
+tags: [wave-4, suite, postgres]
+---
+
+## Description
+
+Grow the **postgres column** — the suite's first SKIP-posture column
+(README §SKIP posture: SQL-attached factories ride a server; when no
+server is reachable the column **skips cleanly** — a skip is not a
+failure — and the wave's acceptance requires green **against the
+server**). The column runs under `--features postgres` (feature
+`postgres`, default-off).
+
+- **Factories** (`tests/conformance/postgres_column.rs`):
+  - dual-tier `kv = postgres + large = local` at a column-declared
+    threshold and the **test tuning of the window delay (`0` —
+    execute-on-next-sweep)**;
+  - `kv-only(postgres)` at a column-declared threshold (the rejection
+    row's host; threshold materializable per the README's
+    configuration contract).
+  **The alkstore pg-factory pattern, reused** (`alkstore-postgres`
+  tests/contract_suite.rs): a **fresh engine-owned schema per
+  `open()`** — unique per call (seeded per tag/pid/time so two factory
+  instances never share a schema name, racing opens included), tracked
+  per-instance in a schema registry, teardown
+  `DROP SCHEMA IF EXISTS … CASCADE` over exactly the schemas the
+  instance minted (idempotent, owned — never the shared server's other
+  schemas; safe against an abandoned store: `CASCADE` removes
+  dependents server-side while the store's pooled connections fail
+  closed on next use). Panicking-row-safe — the sqlite column's
+  instance-tracks-its-own-site pattern over schemas instead of temp
+  dirs.
+- **Connection settings ride the environment** — the alkstore harness
+  convention: `ALKBLOBS_PG_HOST/PORT/USER/PASSWORD/DB` (db defaulting
+  `postgres` if unset), a reachability probe gating the rows (the SKIP
+  posture's factory-owner responsibility). **The harness server**:
+  dockerized `pglo-poc` (`postgres:16-alpine`) on :15432, db `blobs`,
+  user/password `postgres`/`poc` — verified live 2026-10-12; the
+  container is long-running in the dev environment (the alkstore
+  harness's same server).
+- **Mirror the form-independent reference rows** (README §The
+  reference row set): INV-1 round-trips (content matrix × both put
+  paths, in-body), INV-6 stat discipline, the `NoLivenessSources`/
+  `ProtectFailed` abort shapes (form-independent — abort before
+  staging), and the kv-only rejection row (threshold-agnostic by
+  discovery, unchanged).
+- **The durable-schedule sweep rows** — the sqlite column's family
+  (README §The schedule-relative reading for SQL-backed columns):
+  INV-2 dedup and INV-3 stage hygiene with counts read against the
+  staged schedule, the two-sweep exact-count row over the full
+  protection set (both tiers, the window observed), the
+  sweep-vs-put race across the window delay (execution-time
+  re-arbitration), the holder-stages-only lease shape, and INV-5 list
+  correctness through durable-schedule outcomes.
+- **The dual-tier dispatch rows** mirror the sqlite column's family
+  (pure-function routing, threshold boundaries, fall-through per op)
+  with the placement oracle adapted by medium: kv entries live as rows
+  in the pg schema's `blobs` table, large entries under the local
+  root — the oracle distinguishes by medium (an independent
+  connection counting the schema's rows vs the root's committed
+  files).
+- **Virgin-store row**: reads are no-ops on a fresh schema (pool,
+  both GC tables, and committed tree all empty) — the constructor
+  always ensures the schema (the engine's recorded posture), this row
+  being the facade form.
+- **Structural factory tests** (the mem/sqlite columns' pattern):
+  factory isolation (fresh schema per open, nothing shared — two
+  opens never observe one another) and teardown-against-a-panicking-row
+  (schemas really dropped).
+- **README amendments** (the convention's normative test-side home):
+  the postgres rows table in §Columns beyond the reference set; the
+  column plan's SKIP-posture note now naming a landed column; current
+  state (four columns; the first SKIP-posture column, green against
+  the harness server).
+
+## Acceptance Criteria
+
+- [ ] The postgres column green **against the harness server**
+      (`pglo-poc`, :15432): the mirrored form-independent reference
+      rows + the durable-schedule sweep rows + the dispatch rows + the
+      virgin-store row, every row ADR-stamped and traceable to the
+      backlog
+- [ ] Server-less runs skip cleanly (the reachability probe; the
+      default-build gates stay green with the column skipped)
+- [ ] Factory isolation + idempotent teardown hold (fresh schema per
+      open; `DROP SCHEMA … CASCADE` over exactly the minted schemas;
+      teardown safe against a panicking row), structurally exercised
+- [ ] README amendments recorded (the postgres rows table; current
+      state)
+- [ ] `cargo test` (default) green — the column compiles out;
+      `cargo test --features postgres` green server-less (skipping)
+      and green against the server at acceptance;
+      `cargo clippy --all-targets -- -D warnings` and
+      `cargo fmt --check` green (default + `--features postgres`)
+
+## References
+
+- tests/conformance/README.md (the conventions this grows against;
+  §SKIP posture, §Columns beyond the reference set, §The
+  schedule-relative reading for SQL-backed columns)
+- tests/conformance/factory.rs (the factory contract this implements)
+- tests/conformance/rows.rs (the reference row set being mirrored)
+- tests/conformance/sqlite_column.rs (the SQL-backed column pattern —
+  the durable-schedule rows' first host)
+- /workspace/@alkdev/alkstore/alkstore-postgres/tests/contract_suite.rs
+  (the pg-factory pattern reused: fresh schema per open, the schema
+  registry, the CASCADE teardown, the env-driven DSN)
+- docs/architecture/store-api.md (§Invariants — the test gate)
+- docs/architecture/decisions/012-pre-decomposition-consistency-rulings.md
+  §6.7 (the schedule the sweep rows assert against)
+- docs/architecture/decisions/007-two-kv-engines-sqlite-and-postgres.md
+  §5 (the exact-count sweep-outcome gate against dockerized postgres)
+
+## Notes
+
+> To be filled by implementation agent
+
+## Summary
+
+> To be filled on completion