alkstore/docs/plans/implementation.md

status, last_updated

status	last_updated
draft	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	Workspace scaffold; core crate (errors, value types, full trait surface); contract-suite scaffold	—	decomposed (tasks/)
2	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.