glm-5.3-flash
327b952e4d
- tests/conformance/README.md: the convention doc — row naming (property- stated names, engine dimension is the column), the Contract stamp: format (the alkstore ADR-017 §4.2 convention adapted), the one- normative-owner-per-property rule, the factory contract (fresh isolated instance per open, idempotent teardown, safe over an abandoned instance), the SKIP posture (SQL-attached columns skip cleanly server-less; acceptance requires green against the server), the invariant backlog (the seven store-api.md §Invariants registered as the rows-to-grow table with pinning citations), and the mem-first column plan (mem is the contract-reference engine, ADR-011 §2) - harness skeleton, compile-able with zero rows: StoreFactory (fresh + isolated + idempotent-teardown contract; the Store associated type is wave 2's binding point for the facade type), stamp.rs (the marker + convention anchor), backlog.rs (in-code registry with a traceability gate asserting INV-1..7 mirror §Invariants in order) - no engine-specific code; no dependencies added Verification: cargo test (33 passed across lib + 3 targets), cargo clippy --all-targets -- -D warnings, cargo fmt --check
102 lines
4.8 KiB
Markdown
102 lines
4.8 KiB
Markdown
---
|
||
id: suite-scaffold
|
||
name: Conformance suite — home, convention, and invariant backlog
|
||
status: completed
|
||
depends_on: [scaffold-crate-features]
|
||
scope: narrow
|
||
risk: low
|
||
impact: project
|
||
level: implementation
|
||
tags: [wave-1, suite]
|
||
---
|
||
|
||
## Description
|
||
|
||
Establish `tests/conformance/` — the in-crate conformance harness home
|
||
(decided point: engines are features of one crate, so the suite lives
|
||
in-crate, factory-parameterized over engine constructors; the
|
||
alkstore ADR-017/022 pattern adapted) — with the convention that waves
|
||
2–6 grow columns against:
|
||
|
||
- **The convention document** (a `tests/conformance/README.md` or
|
||
module doc): row naming, the ADR-stamp format (every row cites the
|
||
ADR § / spec § that pins it — the alkstore version-stamping
|
||
convention), the one-normative-owner-per-property rule, and the
|
||
factory contract: each factory opens a **fresh, isolated** store
|
||
instance (no shared state between rows) with **idempotent
|
||
teardown**; engine factories for SQL engines skip cleanly when no
|
||
server is reachable (the alkstore SKIP posture) while acceptance
|
||
requires green against the server.
|
||
- **The invariant backlog**: store-api.md's seven invariants
|
||
registered as the rows-to-grow table (round-trips per engine/tier/
|
||
put-path; dedup; stage hygiene; sweep safety incl. the engine-gated
|
||
fleet form; list-correctness-through-sweep-outcomes; `stat`-without-
|
||
content; engine-conformance uniformity) — each row's first column
|
||
lands with the mem engine in wave 2 (mem is the contract-reference
|
||
engine; every other engine's rows mirror its column).
|
||
- **The harness skeleton**: the factory trait shape and the row
|
||
registration structure, compile-able as a stub (the `Store` facade
|
||
type arrives in wave 2 — the skeleton pins the shape, wave 2's
|
||
first column binds it; if binding reveals a shape correction, that
|
||
is wave 2's to make and record).
|
||
|
||
This task is deliberately convention-first: the harness shape is
|
||
easier to grow row by row as engines land than to retrofit onto five
|
||
finished engines (the alkstore wave-1 rationale, which applies
|
||
identically here).
|
||
|
||
## Acceptance Criteria
|
||
|
||
- [ ] `tests/conformance/` exists with the convention doc (row naming,
|
||
ADR-stamp format, one-owner rule, factory isolation + teardown
|
||
contract, SKIP posture)
|
||
- [ ] The invariant backlog table registered, traceable to
|
||
store-api.md's seven invariants, with the mem-first column plan
|
||
noted
|
||
- [ ] The harness skeleton compiles (`cargo test` green — a stub with
|
||
no rows yet is acceptable and expected)
|
||
- [ ] No engine-specific code; the task adds no dependencies
|
||
|
||
## References
|
||
|
||
- docs/architecture/store-api.md (§Invariants — the test gate)
|
||
- docs/architecture/backends-and-dispatch.md (§Per-engine conformance; POC #7 gate as the norm)
|
||
- /workspace/@alkdev/alkstore/docs/plans/implementation.md (wave 1 + wave 5 sections — the convention's source pattern)
|
||
- docs/plans/implementation.md (Decided points — suite home)
|
||
|
||
## Notes
|
||
|
||
- The convention doc landed as `tests/conformance/README.md` (normative
|
||
home) with the in-code anchors: `stamp.rs` (the `Contract stamp:`
|
||
marker, alkstore ADR-017 §4.2 adapted), `factory.rs` (the
|
||
`StoreFactory` shape + contract), `backlog.rs` (the backlog as an
|
||
in-code registry with a traceability gate).
|
||
- The skeleton's wave-2 binding point: `StoreFactory::Store` is an
|
||
associated type placeholder for the `Store` facade type (which
|
||
arrives in wave 2 — no public type exists to bind today). Wave 2's
|
||
mem column binds it; a binding-revealed shape correction is wave
|
||
2's to make and record in README + factory.rs, per the task text.
|
||
- SKIP posture is pinned as convention text (README §SKIP posture +
|
||
factory.rs docs) rather than typed machinery: the mechanism lands
|
||
with the first column that needs it (postgres, wave 4). Mem/sqlite/
|
||
local never skip.
|
||
- The backlog table cites per-entry: restated invariant, planned row
|
||
family, pinning texts (spec §/ADR §), first column/wave. INV-4's
|
||
fleet form is recorded as its own engine-gated family (wave 6).
|
||
- Harness self-checks (4 tests): backlog traceability (order mirrors
|
||
store-api.md §Invariants 1–7, every field populated), stamp marker
|
||
identity, and a probe factory proving the trait is implementable
|
||
with async methods (the alkstore exemplar-against-mock posture,
|
||
sized to the no-rows state). No engine-specific code; no
|
||
dependencies added.
|
||
|
||
## Summary
|
||
|
||
`tests/conformance/` established: README.md (row naming, stamp
|
||
format, one-owner rule, factory isolation + idempotent-teardown
|
||
contract, SKIP posture, the seven-invariant backlog table traceable
|
||
to store-api.md, mem-first column plan), plus the compile-able
|
||
skeleton (factory trait, stamp module, backlog registry) with zero
|
||
rows as expected. Verified: `cargo test` (33 total across lib + 3
|
||
targets), `cargo clippy --all-targets -- -D warnings`, `cargo fmt
|
||
--check` all green. |