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

+72
View File
@@ -0,0 +1,72 @@
---
id: scaffold-crate-features
name: Crate scaffold — ADR-013 §4 feature graph and module skeleton
status: pending
depends_on: []
scope: narrow
risk: low
impact: project
level: implementation
tags: [wave-1, workspace]
---
## Description
Replace the placeholder crate body with the real skeleton, so every
later task lands in an existing, compiling structure with the decided
feature graph present from the first commit:
- **Feature graph per ADR-013 §4** (backends-and-dispatch.md's table
is the spec home): `sqlite` (default-on, carries rusqlite with the
`bundled` feature — match alkstore's engine manifests as the family
baseline, verifying current compatible versions at implementation),
`postgres` (tokio-postgres + deadpool-postgres), `mem` (no driver —
dependency-free), `pg-lo` (the shared pg cluster: tokio-postgres +
deadpool-postgres; **must not** imply `postgres` — ADR-010 §1's
feature-graph consequence), `ops` (alkcall, default-off — published
crate, version dep per the sibling posture, `alkcall = "0.8.1"`).
`local` is ungated (no feature, no dependency). `default = ["sqlite"]`.
- **Module skeleton** under `src/`: `lib.rs` re-export shape with
module stubs for the planned tree (keys/hashing, error, backend,
facade, dispatch, gc; engine modules behind `#[cfg(feature)]`).
Remove `pub fn placeholder()`. Modules are one per file, re-exported
from `lib.rs` (AGENTS convention 10); engine module files exist
gated and empty.
- Base dependencies stay as-is (tokio, thiserror, parking_lot). Driver
deps declared now with no consuming code — unused optional deps are
inert, and the graph being a decided artifact (ADR-013 §4) is why it
lands whole.
Family standards apply from this commit onward: tokio async runtime,
`thiserror` errors, no panics in library code, no `unwrap()`/`expect()`
outside tests, no comments in code (doc comments on public API fine).
## Acceptance Criteria
- [ ] `cargo test` green with the default build (sqlite feature on,
no engine code yet)
- [ ] `cargo check --all-features` resolves the full feature graph
(sqlite, postgres, mem, pg-lo, ops) with their driver clusters
- [ ] `pg-lo` alone (`cargo check --no-default-features --features pg-lo`)
resolves without pulling postgres-only machinery (the
no-implication rule, ADR-010 §1)
- [ ] `cargo clippy --all-targets -- -D warnings` and
`cargo fmt --check` green
- [ ] `lib.rs` carries the module re-export shape; no placeholder
function remains
## References
- docs/architecture/overview.md (dependency posture table)
- docs/architecture/backends-and-dispatch.md (the engine/feature table)
- docs/architecture/decisions/013-family-composition-reactive-boundary-and-feature-graph.md §4
- docs/architecture/decisions/010-backend-io-seams-and-fleet-state-home.md §1 (pg-lo no-implication)
- /workspace/@alkdev/alkstore/tasks/scaffold-workspace.md (the family scaffold precedent)
## Notes
> To be filled by implementation agent
## Summary
> To be filled on completion