Contract-suite scaffold: alkstore-contract-suite crate + ADR-022 (suite layout decision), engine dev-dep edges (ADR-017 §4.2 discharged, ADR-012 §2 mirror)

tasks/contract-suite-scaffold.md

@@ -1,7 +1,7 @@
 ---
 id: contract-suite-scaffold
 name: Contract-suite crate scaffold + ADR-022 (suite layout decision)
-status: pending
+status: completed
 depends_on: [core-trait-surface]
 scope: narrow
 risk: low
@@ -69,8 +69,73 @@ The crate:
 
 ## Notes
 
-> To be filled by implementation agent
+- **Factory shape (the implementer's choice)**: a named trait,
+  `StoreFactory { open() -> BoxedFuture<Result<Box<dyn Store>>>;
+  teardown() -> BoxedFuture<Result<()>> }` — chosen over a function
+  alias because teardown needs an identity to be idempotent *per
+  instance* (a bare fn can't carry "this factory's backing store"),
+  and the async surface rides core's `BoxedFuture` posture so
+  implementers need no macros. One shape, documented in
+  `src/factory.rs`; the ADR records the layout, not a frozen API —
+  wave 3/4 feedback may evolve it.
+- **Version-stamp convention (the "decided here" row convention)**:
+  a row's doc comment carries one `Contract stamp:` item per contract
+  change pinning the behavior tested, citing ADR § (never bare "v1"
+  or dates); stamps *accumulate* on amendment; greppable via the
+  exported `STAMP_MARKER` constant. Normative statement lives in
+  `src/version_stamp.rs` — every later row cites against it. The
+  exemplar row is stamped `ADR-008 §4` + `ADR-021 §3` + `ADR-015 §2`
+  (its assertions span all three changes' behavior).
+- **Assertion posture**: rows panic on violation (labeled with the
+  entry point and expectation) — the test-side-artifact relaxation of
+  the family no-panic rule, documented in the crate docs as
+  deliberate.
+- **Exemplar scope**: the property runs the full validation surface —
+  all four `Store` constructor kinds (`listen`/`stream`/`queue`/
+  `outbox`), `try_lock` (both name and owner), `schedule` (both name
+  and queue argument — ADR-021 §3), `notify`, and *every* name-bearing
+  `*_tx` twin on `TxHandle` (all eleven, incl. ADR-015 §2's
+  non-empty-key rule on `publish_with_key_tx`), plus a `with_tx`
+  spot-check proving the commit-atomic path can't bypass validation.
+  Happy-path spot-checks (`stream`/`queue`/`try_lock` with a
+  reserved-prefixed owner) prove the rejections are the validation's
+  doing, not store-wide failure.
+- **`Schedule` is `#[non_exhaustive]`** (ADR-017 §3): the mock cannot
+  struct-construct it, so the mock's `schedule()` returns a `Database`
+  stub after running the row-validation; the row asserts only the
+  validation outcomes, and `Schedule` construction stays core's own
+  tests' business. Same for the mock's `subscribe` (never exercised by
+  the row). Noted so wave 3/4 factory impls copy the posture knowingly.
+- **serde_json is a direct dep of the suite** (not just core's): rows
+  construct payload `Value`s as contract surface (ADR-020 §4's trait
+  crossing). No driver deps — the ADR-001 §2 mirror holds.
+- **Dev-dep edges are path deps** (`path = "../alkstore-contract-suite"`)
+  with no version: correct for an unpublished internal crate — a
+  `version` key would be meaningless.
+- ADR-017 §4.2's text gained a layout-resolution annotation (dated,
+  citing ADR-022) at the deferral site — the discharge is visible from
+  the deferring document itself.
 
 ## Summary
 
-> To be filled on completion
+The `alkstore-contract-suite` crate is scaffolded per the option-(a)
+layout decision: `publish = false`, workspace member, depends on
+`alkstore` only (+ serde_json for payload construction). It defines
+the `StoreFactory` trait (open/teardown over an isolated backing
+store), the version-stamp convention (`Contract stamp:` doc-comment
+items, `STAMP_MARKER` constant, normative statement in
+version_stamp.rs), and the exemplar property
+`name_validation_rejects_empty_and_reserved` — full auto-commit + tx
+validation surface, stamped ADR-008 §4 / ADR-021 §3 / ADR-015 §2. A
+`tests/suite_harness.rs` runs it green against a trivial in-crate mock
+store + factory (3 tests: the exemplar row, happy-path construction,
+stamp-marker check). Engine crates carry the dev-dependency edge
+(path-dep). ADR-022 written
+(docs/architecture/decisions/022-contract-suite-layout.md): option (a)
+chosen, one-normative-owner-per-property rationale (ADR-012 §2
+mirror), factory-shape latitude stated, ADR-017 §4.2 deferral
+discharged (with an annotation added at the deferral site);
+ADR index tables in docs/architecture/README.md and overview.md
+updated. Workspace `cargo build`, `cargo test` (26 tests workspace
+wide), `cargo clippy --all-targets -- -D warnings`, `cargo fmt
+--check` all clean.