alkblobs/tasks/scaffold-crate-features.md

id, name, status, depends_on, scope, risk, impact, level, tags

id	name	status	depends_on	scope	risk	impact	level	tags
scaffold-crate-features	Crate scaffold — ADR-013 §4 feature graph and module skeleton	completed		narrow	low	project	implementation	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

• Feature graph declared exactly per ADR-013 §4's table: default = ["sqlite"]; sqlite = ["dep:rusqlite"]; postgres = ["dep:tokio-postgres", "dep:deadpool-postgres"]; pg-lo pulls the same shared pg driver cluster by dep: reference only (no feature implications — the postgres feature name appears nowhere in its declaration); mem = []; ops = ["dep:alkcall"]. local ungated, no feature, no dependency.
• Driver versions verified at implementation time (crates.io + the alkstore engine manifests as the family baseline): rusqlite = "0.40" (bundled; resolves 0.40.2, matching alkstore-sqlite's baseline), tokio-postgres = "0.7" (0.7.18), deadpool-postgres = "0.14" (0.14.2), alkcall = "0.8.1" (the exact pin the task specified — present on the public registry).
• Module skeleton: lib.rs re-export shape with one module per file — ungated stubs hashing, error, backend, facade, dispatch, gc, local; gated stubs mem, pg_lo, postgres, sqlite, ops behind #[cfg(feature)]. All stubs are doc-comment-only; pub fn placeholder() removed. Stub content stays empty so the wave-1 implementation tasks (core-hashing-keys, core-error-model, core-trait-and-types) own their module bodies.
• Cargo.lock is untracked in this repo (workspace-wide exclude, consistent with all prior commits) — left untracked.
• No CI wiring added (manual CI per docs/plans/implementation.md).

Summary

Crate scaffold complete per ADR-013 §4: the full decided feature graph (sqlite default-on with rusqlite bundled; postgres, mem, pg-lo default-off; ops with alkcall 0.8.1; local ungated) is declared in the manifest with inert optional driver dependencies, and the module skeleton (lib.rs re-export shape + 12 doc-comment-only module stubs, engine modules behind #[cfg(feature)]) replaces the placeholder body. All acceptance criteria verified: cargo test green with defaults (rusqlite only non-base dep in the default tree), cargo check --all-features resolves the whole graph including alkcall, cargo check --no-default-features --features pg-lo resolves with rusqlite provably absent (cargo tree -i rusqlite matches nothing) proving pg-lo implies no other engine feature, and cargo clippy --all-targets -- -D warnings + cargo fmt --check are clean.