Implementation plan: wave-based decomposition; waves 1-2 decomposed (11 tasks)

docs/plans/implementation.md records the wave structure (core ->
substrate fork || pg engine -> sqlite engine -> contract suite ->
release), the decided points (contract-suite layout = option (a),
engine-tests vs equivalence-suite split, no CI, mem-engine/fuzzing
deferrals surfaced), and the review-gate rhythm.

Wave 1 (foundations): workspace scaffold, core errors/validation,
value types, trait surface, contract-suite scaffold (+ADR-022),
review gate.
Wave 2 (substrate fork): fork scaffold/provenance, connection+watcher
port, queue-op re-derivation on contract v1, provenance/floor close,
review gate.

docs/plans/implementation.md

@@ -0,0 +1,111 @@
+---
+status: draft
+last_updated: 2026-10-07 (initial wave plan; waves 1–2 decomposed)
+---
+
+# alkstore — Implementation plan
+
+Wave-based decomposition of the architecture
+(`docs/architecture/`) into units of implementable work. This is a
+deliberate deviation from the SDD process's decompose-everything-upfront
+step: the architecture is large, early waves change the shape of later
+ones (the fork's outcomes feed the SQLite engine tasks; the contract
+suite's harness shape feeds both engines' verification work), and
+decomposing only the next wave or two at a time keeps each session's
+task set reviewable and lets later decompositions absorb earlier waves'
+course corrections.
+
+Rhythm: decompose a wave → implement it → review gate → decompose the
+next wave. Task files live in `tasks/` (taskgraph-managed; frontmatter
+carries the categorical estimates). Wave boundaries are also review
+boundaries.
+
+## The waves
+
+Dependency logic in one line: core → (substrate fork ∥ postgres
+engine) → sqlite engine → contract suite → release readiness. The
+substrate fork is contract-blind (ADR-012 §2), so it needs only the
+workspace scaffold from wave 1; the Postgres engine needs only the core
+crate. Waves 2 and 4 are therefore independent of each other and could
+run in either order (or in parallel, if agents are ever available in
+parallel).
+
+| Wave | Contents | Depends on | Status |
+|---|---|---|---|
+| [1](#wave-1--foundations) | Workspace scaffold; core crate (errors, value types, full trait surface); contract-suite scaffold | — | decomposed (`tasks/`) |
+| [2](#wave-2--sqlite-substrate-fork) | honker-core fork into `alkstore-sqlite/src/substrate/`: port, deltas, provenance, test floor | wave 1 (workspace scaffold only) | decomposed (`tasks/`) |
+| 3 | SQLite engine: connection architecture, re-derived queue ops on contract v1, scheduler/outbox, tx seam, SQLite backlog column | waves 1 + 2 | not yet decomposed |
+| 4 | Postgres engine: schema bootstrap, pool/open, listener/forwarder, all mechanisms, tx seam, pg backlog column | wave 1 | not yet decomposed |
+| 5 | Contract suite: the cross-engine equivalence properties (core-contract.md §Verification backlog), version-stamped per ADR-017 | waves 3 + 4 | not yet decomposed |
+| 6 | Release readiness: crate docs, deployment matrix final pass, README (written last, honestly), publish prep; mem-engine and fuzzing decisions | wave 5 | not yet decomposed |
+
+## Wave 1 — Foundations
+
+The core crate is contract v1 in code: the error taxonomy (ADR-008 §5),
+the value types (ADR-019 §3, ADR-020), the full trait surface
+(ADR-008 §1–§3/§8, ADR-014, ADR-019, ADR-021), and the payload encoding
+posture (ADR-020 §4). Nothing engine-specific lives here — no
+resolution arithmetic, no SQL. The equal-jitter curve, opts-stamping
+resolution, and boundary math are deliberately *not* core: ADR-012 §2
+pins each engine as the owner of one implementation, with equivalence
+pinned by the contract suite (wave 5).
+
+The contract suite gets scaffolded now (not in wave 5) because its
+harness shape — a `Store`-factory-parameterized property crate — is
+easier to grow row by row as engines land than to retrofit onto two
+finished engines. Wave 5 fills it with the cross-engine equivalence
+rows; waves 3 and 4 adopt the harness for their own backlog columns.
+
+## Wave 2 — SQLite substrate fork
+
+The fork per ADR-011/012/013: port honker-core at `f4e53c6` into
+`alkstore-sqlite/src/substrate/`, apply the three watcher port deltas
+and the bootstrap re-keying, drop cron/experimental/cut-flag machinery,
+re-own the table family as `__alkstore_*`, carry `PROVENANCE.md` and
+the dual-license notice in-tree (ADR-018), and stand up the inherited
+test suites as the floor. The substrate stays sync and contract-blind;
+the engine layer that maps it onto the core contract is wave 3, not
+here. Reviewability against the lineage (ADR-012 §3) is a property the
+wave-2 review gate checks explicitly.
+
+## Decided points
+
+- **Contract-suite layout — option (a)**: a small internal
+  `alkstore-contract-suite` crate (not published) exposing property
+  tests parameterized over a `Store` factory; each engine crate takes
+  it as a dev-dependency. One normative owner per property, mirroring
+  ADR-012 §2's one-owner rule. This discharges ADR-017 §4.2's
+  "decided at implementation" deferral; recorded as ADR-022 by the
+  scaffold task.
+- **Engine tests vs. contract suite**: each engine wave carries its own
+  mechanism tests (does the engine work); wave 5 carries the
+  cross-engine *equivalence* properties (do the engines agree). The
+  verification-backlog rows are mostly equivalence-shaped, so this
+  split keeps wave 5 from re-testing engine internals.
+- **CI**: none, deliberately. CI and publishing are run manually
+  (self-hosted Gitea; supply-chain posture). No CI-wiring task exists;
+  the merge gates (`cargo test`, `cargo clippy --all-targets --
+  -D warnings`, `cargo fmt --check`) are run coordinator-side.
+- **Mem engine** (ADR-001 §4) and **fuzzing adoption** (the
+  alksocks/alktty/alktunnels pattern): both are "decided at
+  implementation" deferrals, recorded here so they surface as explicit
+  decision points in wave 6 (or earlier if the test story demands the
+  mem engine sooner) rather than ambushing a later session.
+
+## Review gates
+
+Each wave ends in a review task (`review-wave-N`) before the next wave
+decomposes. Specific gates:
+
+- **Wave 1 review** — the trait surface is versioned contract surface
+  from the first release (ADR-017); a shape error found here is cheap,
+  found in wave 5 it is a migration. Review checks the code against the
+  pinned ADR text line by line.
+- **Wave 2 review** — diff reviewability against the honker lineage
+  (ADR-012 §3's fidelity posture), provenance register completeness
+  (ADR-018), floor tests green.
+- **Wave 3/4 reviews** — engine-vs-contract conformance; the backlog
+  columns each engine owns.
+- **Wave 5 review** — the suite as compatibility instrument: every
+  backlog row present, version-stamped, green on both engines; this is
+  the gate that flips the engine specs to `stable`.