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
This commit is contained in:
glm-5.3-flash committed 2026-10-12 05:49:28 +00:00
1 parent 611d30a3c4
commit 7ea6dd6bcb
6 files changed
+752 -2

No files matched your search

+114
View File
@@ -0,0 +1,114 @@
---
id: review-wave-4
name: Wave 4 review gate — the postgres engine vs the contract
status: pending
depends_on: [suite-column-postgres]
scope: narrow
risk: low
impact: phase
level: review
tags: [wave-4, review]
---
## Description
The wave-4 review gate — the engine-wave review shape
(docs/plans/implementation.md §Review gates: "engine-vs-contract
conformance"), before wave 5 decomposes. The gate reads the
implementation against the pinned ADR text line by line (the
wave-1/2/3 gates' method).
Gate checks:
- **Engine-vs-contract conformance**: the suite column green against
dockerized postgres (server-less runs skip cleanly — a skip never
substitutes for acceptance); the engine-state clause families
contract-tested per the applicability row (ADR-012 §5's postgres
row — every family yes); virgin-store semantics; the `size`
metadata-only discipline (the size-column probe never loads the
value blob).
- **The postgres posture vs ADR-007**: the B5 deltas carried as
requirements, not hedges — the `synchronous_commit` parity knob
(configurable, per-connection wiring, default `on`); pooled
connections with per-connection prepared-statement discipline
(statements die with sessions); autovacuum + fillfactor tuning
stated in the module doc; the ~40× small-tier storage overhead
accepted and documented; the B5 tuning numbers recorded as
POC-derived posture defaults (ADR-007 §6's deferred-cost pattern).
- **The sweep-safety proof vs ADR-007 §5**: `list()` complete and
well-formed as a stable MVCC-snapshot cursor over a vacuuming
table; the batch-delete helper (`key = ANY($1)`) contract-tested;
the exact-count sweep-outcome rows green against the server.
- **The seam families vs ADR-010 §2 / ADR-012 §4/§5**: the full
clause families on postgres (the fleet host) — `ensure_gc_schema`
(both tables, the embedder's liveness table never created),
`window_stage`/`window_take` (the sqlite semantics' dialect twin),
the joint tx ownership rule honored in the `JointTx` shape (the
store holds; the engine contributes), `pin_commit`'s atomicity
(publish + protection in one step, zero residue on failure),
`pin_renew`'s never-resurrect semantics, `pin_check`'s
classification-only discipline, `arbitrate`'s finger-lock fold,
the advisory lock's ADR-013 §2 lease semantics (atomic
test-and-set, session-scoped holdership, same-connection
release). **Fleet activation absent by construction** — no
`fleet:` parameter, no store-core fleet wiring (wave 6); the
clause bodies exist and are contract-tested per applicability.
- **The non-fleet posture vs ADR-012 §3**: the constructors are
implicitly `fleet: false` — the in-process protocol verbatim; the
recorded posture names wave 6's slotting-in as a non-event.
- **Async/blocking discipline**: tokio-postgres natively async — no
`spawn_blocking` seam (the sqlite discipline does not carry); no
blocking I/O on the async path; the pool is the concurrency
posture; no `unwrap`/`expect` outside tests.
- **Named design points audited as resolved** (each recorded in its
task's Notes): the schema name + quoted-identifier boundary; the
pool default size; the prepared-statement discipline; the DSN +
opts constructor shape; the virgin-store tolerance split; the
list-cursor fetch shape; the timestamp encoding; the `JointTx`
concrete type; the `pin_renew` successor-time source; the lock
key + scope; the lease's connection holding.
- **Family conventions**: no comments in code (doc comments on public
API fine), thiserror, tokio-only async, no unwrap/expect outside
tests, naming, one-module-per-file re-export shape, the
`#![allow(dead_code)]` scope notes matching their remaining scope
(the batch-delete helper's wave-6 note intact).
- **Gates green**: `cargo test` (default), `cargo test --features
mem`, `cargo test --features postgres` (server-less: skipping),
`cargo test --all-features`, `cargo check --no-default-features
--features postgres` (the pg-pure build), `cargo clippy
--all-targets -- -D warnings` (default + `--features postgres` +
`--all-features`), `cargo fmt --check`.
Findings are fixed inline where cheap, or recorded as wave-5
amendments where they shape the next decomposition. The gate's
completion is what unblocks wave 5's decomposition.
## Acceptance Criteria
- [ ] Every gate check above read and verified against the cited ADR
text (not from memory of it)
- [ ] Named design points each decided, recorded, and consistent with
the specs
- [ ] Findings fixed inline or recorded as wave-5 amendments with
owners
- [ ] All gates re-run green after any fixes
- [ ] Wave 5 decomposition unblocked (recorded in this task's Summary)
## References
- docs/plans/implementation.md (§Wave 4, §Review gates — engine wave
reviews)
- docs/architecture/decisions/007-two-kv-engines-sqlite-and-postgres.md
- docs/architecture/decisions/010-backend-io-seams-and-fleet-state-home.md §2
- docs/architecture/decisions/012-pre-decomposition-consistency-rulings.md §3/§4/§5/§6.6/§6.7
- docs/architecture/decisions/013-family-composition-reactive-boundary-and-feature-graph.md §2/§4
- docs/architecture/store-api.md
- tasks/review-wave-3.md (the gate method; the structural twin's gate)
## Notes
> To be filled by the review agent
## Summary
> To be filled on completion