---
id: contract-suite-scaffold
name: Contract-suite crate scaffold + ADR-022 (suite layout decision)
status: pending
depends_on: [core-trait-surface]
scope: narrow
risk: low
impact: phase
level: implementation
tags: [wave-1, contract-suite]
---

## Description

Scaffold the contract suite as a fourth, internal, unpublished crate —
`alkstore-contract-suite` — per the layout decision recorded in
docs/plans/implementation.md (option (a)): property tests
parameterized over a `Store` factory, consumed by each engine crate as
a dev-dependency. This discharges ADR-017 §4.2's "layout decided at
implementation" deferral; the decision gets its own ADR (ADR-022) since
it shapes the pairing instrument ADR-017 §4 names.

The crate:

- Workspace member, `publish = false`, depends on `alkstore` only.
- Exposes a `StoreFactory` trait (or function alias — implementer's
  choice, but one shape, documented): something that yields a fresh
  `Box<dyn Store>`-shaped store over an isolated backing store (fresh
  file / fresh schema), plus teardown. The exact factory shape may
  evolve when engines adopt it (wave 3/4 feedback) — the ADR records
  the layout decision, not a frozen API.
- A `tests/` harness that runs the property set against a supplied
  factory, structured so each backlog row is one named, independently
  runnable property with a version-stamp slot (ADR-017 §4.2: each row
  version-stamped with the contract change that added it — a
  doc-comment or attribute convention, decided here and used by every
  later row).
- One exemplar property implemented end-to-end to prove the harness
  works — the reserved-name/empty-name validation property (pure
  contract, engine-independent, runnable against any factory): every
  name-bearing entry point rejects empty with `InvalidName` and
  reserved-prefix with `ReservedName`, on auto-commit and tx paths
  alike. This row is version-stamped `ADR-008 §4`.
- Engine crates get the dev-dependency edge now (empty suite compiles
  against them trivially once they have code; the edge existing early
  means wave 3/4 tasks adopt the harness rather than debate it).

## Acceptance Criteria

- [ ] `alkstore-contract-suite` crate exists, `publish = false`,
      depends on core only, compiles in the workspace
- [ ] Factory abstraction defined and documented; exemplar property
      (name validation) green against a trivial in-crate mock store
- [ ] Version-stamp convention established and documented in the
      crate (used by the exemplar row)
- [ ] ADR-022 written (`docs/architecture/decisions/022-contract-suite-layout.md`):
      option (a) chosen, rationale (one normative owner per property,
      ADR-012 §2 mirror), the factory-shape latitude stated, ADR-017
      §4.2 deferral discharged; ADR index tables in
      docs/architecture/README.md and overview.md updated
- [ ] Engine crate manifests carry the dev-dependency edge
- [ ] `cargo test` workspace-wide, clippy `-D warnings`, fmt clean

## References

- docs/architecture/decisions/017-contract-versioning.md §4.2
- docs/plans/implementation.md (Decided points)
- docs/architecture/core-contract.md §Verification backlog

## Notes

> To be filled by implementation agent

## Summary

> To be filled on completion