glm-5.3-flash
49743c690e
docs/plans/implementation.md records the wave structure (core -> substrate fork || pg engine -> sqlite engine -> contract suite -> release), the decided points (contract-suite layout = option (a), engine-tests vs equivalence-suite split, no CI, mem-engine/fuzzing deferrals surfaced), and the review-gate rhythm. Wave 1 (foundations): workspace scaffold, core errors/validation, value types, trait surface, contract-suite scaffold (+ADR-022), review gate. Wave 2 (substrate fork): fork scaffold/provenance, connection+watcher port, queue-op re-derivation on contract v1, provenance/floor close, review gate.
76 lines
3.2 KiB
Markdown
76 lines
3.2 KiB
Markdown
---
|
|
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 |