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:
1 parent
611d30a3c4
commit
7ea6dd6bcb
6 files changed
+752
-2
No files matched your search
@@ -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
|
||||
Reference in new issue
Block a user