docs(plans): implementation plan — wave-based decomposition; wave 1 decomposed into tasks/

- docs/plans/implementation.md: the meta plan (alkstore pattern) — nine
  waves, dependency logic, decided points, review gates. Scope authority:
  v0.1.0 ships the full surface (all five engines, fleet GC, ops).
- Wave 1 decomposed: scaffold-crate-features, core-error-model,
  core-hashing-keys, core-trait-and-types, suite-scaffold,
  review-wave-1 (the one-way-door gate).
- Waves 2-9 shaped in the plan; each decomposes after the prior wave's
  review gate.

Verification: cargo test / clippy -D warnings / fmt --check green
(docs-only change).
This commit is contained in:
glm-5.3-flash committed 2026-10-11 17:43:02 +00:00
1 parent 6f6ab19b8e
commit 8a2df4fa57
7 files changed
+829

No files matched your search

+73
View File
@@ -0,0 +1,73 @@
---
id: suite-scaffold
name: Conformance suite — home, convention, and invariant backlog
status: pending
depends_on: [scaffold-crate-features]
scope: narrow
risk: low
impact: project
level: implementation
tags: [wave-1, suite]
---
## Description
Establish `tests/conformance/` — the in-crate conformance harness home
(decided point: engines are features of one crate, so the suite lives
in-crate, factory-parameterized over engine constructors; the
alkstore ADR-017/022 pattern adapted) — with the convention that waves
2–6 grow columns against:
- **The convention document** (a `tests/conformance/README.md` or
module doc): row naming, the ADR-stamp format (every row cites the
ADR § / spec § that pins it — the alkstore version-stamping
convention), the one-normative-owner-per-property rule, and the
factory contract: each factory opens a **fresh, isolated** store
instance (no shared state between rows) with **idempotent
teardown**; engine factories for SQL engines skip cleanly when no
server is reachable (the alkstore SKIP posture) while acceptance
requires green against the server.
- **The invariant backlog**: store-api.md's seven invariants
registered as the rows-to-grow table (round-trips per engine/tier/
put-path; dedup; stage hygiene; sweep safety incl. the engine-gated
fleet form; list-correctness-through-sweep-outcomes; `stat`-without-
content; engine-conformance uniformity) — each row's first column
lands with the mem engine in wave 2 (mem is the contract-reference
engine; every other engine's rows mirror its column).
- **The harness skeleton**: the factory trait shape and the row
registration structure, compile-able as a stub (the `Store` facade
type arrives in wave 2 — the skeleton pins the shape, wave 2's
first column binds it; if binding reveals a shape correction, that
is wave 2's to make and record).
This task is deliberately convention-first: the harness shape is
easier to grow row by row as engines land than to retrofit onto five
finished engines (the alkstore wave-1 rationale, which applies
identically here).
## Acceptance Criteria
- [ ] `tests/conformance/` exists with the convention doc (row naming,
ADR-stamp format, one-owner rule, factory isolation + teardown
contract, SKIP posture)
- [ ] The invariant backlog table registered, traceable to
store-api.md's seven invariants, with the mem-first column plan
noted
- [ ] The harness skeleton compiles (`cargo test` green — a stub with
no rows yet is acceptable and expected)
- [ ] No engine-specific code; the task adds no dependencies
## References
- docs/architecture/store-api.md (§Invariants — the test gate)
- docs/architecture/backends-and-dispatch.md (§Per-engine conformance; POC #7 gate as the norm)
- /workspace/@alkdev/alkstore/docs/plans/implementation.md (wave 1 + wave 5 sections — the convention's source pattern)
- docs/plans/implementation.md (Decided points — suite home)
## Notes
> To be filled by implementation agent
## Summary
> To be filled on completion