alkblobs/tasks/scaffold-crate-features.md

---
id: scaffold-crate-features
name: Crate scaffold — ADR-013 §4 feature graph and module skeleton
status: completed
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

- 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.