---
id: scaffold-workspace
name: Cargo workspace scaffold (three crates per ADR-001)
status: completed
depends_on: []
scope: narrow
risk: low
impact: project
level: implementation
tags: [wave-1, workspace]
---

## Description

Create the Cargo workspace and the three crates of the ADR-001 split,
so every later task lands in an existing, compiling structure:

- `alkstore` — the core crate (contract surface only; no driver
  dependencies, ever).
- `alkstore-sqlite` — engine crate stub; manifest carries the rusqlite
  dependency (^0.40, `bundled` feature per ADR-003) and the core path
  dependency. No code yet beyond an empty lib.
- `alkstore-postgres` — engine crate stub; manifest carries
  tokio-postgres 0.7.x + deadpool-postgres 0.14.x (ADR-004) and the
  core path dependency. No code yet beyond an empty lib.

Workspace-level: shared `[workspace.package]` fields (edition, license
MIT OR Apache-2.0, repository), `resolver = "2"` (or 3 per edition),
and a root `Cargo.toml` with `members`. Crate versions are `0.1.0`
placeholders — ADR-017 §1 pins the initial *release* at 1.0.0; that
bump is wave 7's release task, not this one.

The engines' manifests must pin the core dependency as a path
dependency with the version field set (the ADR-017 §4.1 manifest-pin
carrier) — `alkstore = { version = "0.1", path = "../alkstore" }`
shape, so the pin exists from the first commit.

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 build` at the workspace root compiles all three crates
- [ ] `alkstore` has zero non-dev dependencies (serde/serde_json are
      the allowed exception — ADR-020 §4 puts payload encoding in core)
- [ ] `alkstore-sqlite` depends only on `alkstore` + rusqlite;
      `alkstore-postgres` only on `alkstore` + tokio-postgres +
      deadpool-postgres (+ tokio)
- [ ] Engine manifests carry the versioned core path pin (ADR-017 §4.1
      carrier 1)
- [ ] `cargo clippy --all-targets -- -D warnings` and
      `cargo fmt --check` pass
- [ ] No CI wiring is added (manual CI per docs/plans/implementation.md)

## References

- docs/architecture/decisions/001-crate-split.md
- docs/architecture/decisions/003-sqlite-driver.md (rusqlite pin)
- docs/architecture/decisions/004-postgres-driver.md (pg driver pins)
- docs/architecture/decisions/017-contract-versioning.md §4.1
- docs/plans/implementation.md

## Notes

- Edition **2024** with `resolver = "3"` (the task left "2 or 3 per
  edition" open): wave 2 ports honker-core — an edition-2024 crate —
  into `alkstore-sqlite` as a module subtree (ADR-011/013); a 2021
  workspace would force an edition down-migration of the forked lineage
  for no benefit. rusqlite 0.40 already forces rustc ≥ 1.99, so no new
  toolchain floor is introduced.
- Family conventions copied from alknet/alktty: repository URL
  `https://git.alk.dev/alkdev/alkstore`, `Cargo.lock` committed,
  `.gitignore` of `target/` + `.worktrees/`. LICENSE-MIT/LICENSE-APACHE
  files at repo root are **not** added here — they belong with the
  release-readiness/publish-prep work (wave 7), matching the repo's
  no-honest-artifact-yet posture; the manifests already declare the
  license field per the task spec.
- Engine manifests pin the core path dependency with the version field
  set per ADR-017 §4.1 carrier 1:
  `alkstore = { version = "0.1", path = "../alkstore" }`.
- `alkstore-postgres` carries tokio with `rt-multi-thread` + `macros`
  features (a usable runtime + `#[tokio::test]` out of the box); the
  acceptance criterion permits tokio on the postgres side only.
- No CI wiring added, per docs/plans/implementation.md (manual CI).

## Summary

Workspace scaffold complete: root `Cargo.toml` (resolver 3, shared
`[workspace.package]`: version 0.1.0 placeholder, edition 2024, MIT OR
Apache-2.0, repository) with three members — `alkstore` (empty lib,
zero dependencies), `alkstore-sqlite` (core path pin + rusqlite ^0.40
`bundled`), `alkstore-postgres` (core path pin + tokio + tokio-postgres
0.7 + deadpool-postgres 0.14). All acceptance criteria verified:
`cargo build` compiles all three; dependency trees confirmed via
`cargo tree`; versioned core pins present in both engine manifests;
clippy `-D warnings` and `cargo fmt --check` clean.