147 lines
7.6 KiB
Markdown
147 lines
7.6 KiB
Markdown
# ADR-022: Contract-suite layout — a shared internal suite crate, properties parameterized over a store factory
|
|
|
|
## Status
|
|
|
|
Accepted (2026-10-07, Phase 1 wave-1 — discharges
|
|
[ADR-017](017-contract-versioning.md) §4.2's "layout decided at
|
|
implementation" deferral)
|
|
|
|
## Context
|
|
|
|
[ADR-017](017-contract-versioning.md) §4.2 matured the verification
|
|
backlog ([core-contract.md](../core-contract.md)
|
|
§Verification backlog) into the *contract suite* — the pairing
|
|
instrument whose version-stamped rows make "this engine implements
|
|
contract vN" an auditable claim. What that ADR deliberately deferred
|
|
was the suite's *layout*: shared crate, workspace test target, or
|
|
per-engine module — "a test-side convenience decided at
|
|
implementation ([ADR-001](001-crate-split.md) §4's posture for test
|
|
artifacts)."
|
|
|
|
The implementation plan decoupled the decision from wave 5 (where the
|
|
suite fills with cross-engine equivalence rows) and pulled the
|
|
scaffold into wave 1, with the reasoning recorded in
|
|
[implementation.md](../../plans/implementation.md): the harness shape —
|
|
a `Store`-factory-parameterized property crate — is easier to grow row
|
|
by row as engines land than to retrofit onto two finished engines, and
|
|
the engine crates' dev-dependency edge existing early means wave 3/4
|
|
tasks *adopt* the harness rather than debate it.
|
|
|
|
The candidate layouts, at implementation:
|
|
|
|
- **(a) A shared internal suite crate** — `alkstore-contract-suite`,
|
|
`publish = false`, depending on core only; each engine crate takes
|
|
it as a dev-dependency and drives the rows against its own factory.
|
|
- **(b) A workspace test target** — the rows live as integration
|
|
tests inside one workspace member (core, or a dedicated tests-only
|
|
member), with engines contributing fixtures.
|
|
- **(c) Per-engine modules** — each engine crate carries its own copy
|
|
of the property set in its own test tree.
|
|
|
|
Shape facts that narrow the choice:
|
|
|
|
- The rows are parameterized over a *store factory*, not a store: each
|
|
property needs a fresh store over an isolated backing store (fresh
|
|
file / fresh schema) so rows never observe one another's state —
|
|
something a shared fixture alone does not give.
|
|
- The rows are *the same text* for both engines — that is the point of
|
|
the equivalence pinning ([ADR-012](012-forked-substrate-design.md)
|
|
§2: the engines' arithmetic is "tested into equivalence" by the
|
|
suite). Two copies of a property is the classic drift surface: one
|
|
copy gets strengthened and the other silently lags.
|
|
- The suite is a dev-side instrument; nothing in it belongs on any
|
|
published artifact's dependency graph (dev-dependency edges only).
|
|
- [ADR-017](017-contract-versioning.md) §4.2 also pinned *per-row
|
|
version stamps* (the contract change that added the row — the same
|
|
no-silent-change discipline §2), and the version-stamp convention
|
|
needed a normative owner decided now, since every later row cites it.
|
|
|
|
## Decision
|
|
|
|
**Option (a): the suite is a shared internal crate —
|
|
`alkstore-contract-suite`**, unpublished (`publish = false`), a
|
|
workspace member, depending on `alkstore` only (no driver deps, ever —
|
|
the mirroring of [ADR-001](001-crate-split.md) §2's core rule keeps the
|
|
suite compilable against any factory). Each engine crate takes it as a
|
|
**dev-dependency** and drives the rows in its own test target against
|
|
a factory it defines: a fresh store over an isolated backing store per
|
|
run, plus teardown.
|
|
|
|
- **One normative owner per property** —
|
|
[ADR-012](012-forked-substrate-design.md) §2's one-owner rule
|
|
applied to test artifacts: each property's text, assertion strength,
|
|
and version stamp live in exactly one place. Per-engine copies
|
|
(option (c)) double the owners and drift; the suite crate is the
|
|
single owner, engines are executors.
|
|
- **A crate, not a test target** (over option (b)): the suite's rows
|
|
must be *callable from each engine's* test binary — a dev-dependency
|
|
is the Cargo mechanism for exactly that shape. It also gives the
|
|
suite a compilation gate of its own and a `publish = false` marker
|
|
recording its internal posture in the manifest, where
|
|
[ADR-005](005-dependency-ownership.md)'s published-by-default
|
|
default is answered in the artifact itself.
|
|
- **The factory abstraction is the suite's API**: a minimal
|
|
`StoreFactory` trait (open/fresh, teardown) over the boxed-future
|
|
posture the contract traits use. The exact factory shape is
|
|
deliberately *not frozen* — it may evolve as engines adopt the
|
|
harness (wave 3/4 feedback); this ADR records the **layout**
|
|
decision. Suite-side changes (rows, assertion strength, factory
|
|
shape) are contract-non-events ([ADR-017](017-contract-versioning.md)
|
|
§2 class 4 — the suite tests the contract, it is not contract
|
|
surface); a suite row added to pin a *contract* addition carries
|
|
that addition's ADR as its version stamp, and the class-2/3 change
|
|
itself rides ADR-017's discipline on the core crate's side.
|
|
- **The version-stamp convention is the suite crate's, documented
|
|
there** ([version stamp module](../../../alkstore-contract-suite/src/version_stamp.rs)):
|
|
a row's doc comment carries one `Contract stamp:` item per contract
|
|
change that pinned the behavior tested, citing the ADR §. The
|
|
exemplar row (entry-point name validation — empty → `InvalidName`,
|
|
reserved prefix → `ReservedName`, auto-commit and tx paths alike)
|
|
is stamped `ADR-008 §4` (+ ADR-021 §3, ADR-015 §2 for the rows its
|
|
assertions encompass) and proves the harness end-to-end against a
|
|
trivial in-crate mock store.
|
|
|
|
## Consequences
|
|
|
|
**Positive**
|
|
|
|
- The equivalence discipline has a mechanical home: one row text, run
|
|
on both engines by their factories — the no-ghosts, ordering, and
|
|
arithmetic-equality claims (wave 5's rows later) are one property
|
|
each, not one per engine.
|
|
- The engine/dev-dependency edge existing from wave 1 makes adoption
|
|
the default path for waves 3/4 (their backlog-column tasks run the
|
|
rows, not re-derive them) — the reason the scaffold was pulled
|
|
forward from wave 5.
|
|
- `publish = false` plus core-only deps keeps the artifact off every
|
|
published graph and compilable anywhere (A mem-shaped engine, if
|
|
wave 6 wants one ([ADR-001](001-crate-split.md) §4's deferral), can
|
|
implement the same `StoreFactory` and reuse the suite verbatim).
|
|
|
|
**Negative**
|
|
|
|
- A dev-dependency edge is graph-visible but Cargo-weak: the suite
|
|
cannot enforce that an engine actually *ran* it (dev-deps can be
|
|
ignored by a careless release). The enforcement is process-side —
|
|
the wave-3/4 review gates and [ADR-017](017-contract-versioning.md)
|
|
§4.2's release-time suite requirement, the same honesty posture the
|
|
rest of the pairing carriers ride.
|
|
- The factory shape's latitude is a small standing surface: engines
|
|
will each own a factory impl, and a shapes-drift (e.g. someone adds
|
|
a pool-reuse knob) needs review discipline to keep the two
|
|
implementations comparable. The ADR's stated rule — factory changes
|
|
are suite-crate changes first — bounds it.
|
|
|
|
## References
|
|
|
|
- [ADR-017](017-contract-versioning.md) §4.2 — the deferral this ADR
|
|
discharges; the version-stamp duty the convention implements; class
|
|
4's suite-is-not-contract boundary.
|
|
- [ADR-001](001-crate-split.md) §4 — the test-artifact posture the
|
|
layout defers by; the mem-engine note's possible suite reuse.
|
|
- [ADR-012](012-forked-substrate-design.md) §2 — the one-normative-
|
|
owner rule the layout mirrors; the "tested into equivalence" framing.
|
|
- [core-contract.md](../core-contract.md) §Verification backlog — the
|
|
rows the suite matures from.
|
|
- docs/plans/implementation.md "Decided points" — the wave-1 pull-
|
|
forward rationale and the option-(a) record this ADR formalizes. |