0055f59b3c
JCR-1 ships ten conformance vectors with three independent verifier
implementations byte-equal. The triangle primitives (conservation,
cone, oracle, elicitor) had no equivalent — implementers in other
languages had to read the Rust source to know what "compliant" means.
This commit closes that gap. Each primitive gets:
conformance/vectors.json — the canonical fixture set
conformance/README.md — the conformance contract spec
tests/conformance.rs — Rust verifier wired into cargo test
Vectors:
conservation/1 — 5 vectors: conforming, below_spec, hallucination,
missing_delta, plus a multi-finding case
cone/1 — 6 vectors: every datum_default band entry,
jouleclaw_cascade_default L0, escalate-lut-to-
formulaic, escalate-from-apex (refused)
oracle/1 — 5 vectors: always_pass, always_fail, composite
all-pass with chain dedup, composite short-
circuit on first fail, empty-composite trivial-
pass
elicitor/1 — 5 vectors: empty-walker-done, single-required-
ask, two-required-fill-first-ask-second, fully-
filled-done, optional-slot-never-asked
Each verifier asserts byte-equality between the reference impl's
serde_json output and the vector's `expected_*`. Adding a vector
extends the conformance contract for every implementer.
The Python and Go reference verifiers (the JCR-1 multi-language
pattern) are roadmap, not part of this commit — the vectors are
language-neutral so other-language verifiers can be added without
changing the contract.
4 new tests, one per primitive — all green.
Co-Authored-By: Claude Opus 4.7 <[email protected]>
51 lines
2 KiB
Markdown
51 lines
2 KiB
Markdown
# conservation/1 — conformance
|
|
|
|
Test vectors for any implementation claiming to implement the
|
|
JouleClaw Information Conservation Law (`conservation/1`). The
|
|
reference [`DeterministicVerifier`] in this crate passes every
|
|
vector; any other implementation (alternate verifier, FFI binding,
|
|
re-implementation in another language) is conformant iff it produces
|
|
the same `Vec<VerificationFinding>` — same variants, same field
|
|
values, same order — for every input fixture.
|
|
|
|
## Files
|
|
|
|
- `vectors.json` — the canonical fixture set. 5 vectors covering
|
|
every finding variant (`conforming`, `below_spec`, `hallucination`,
|
|
`missing_delta`) plus one multi-finding case.
|
|
|
|
## Verifier
|
|
|
|
`../tests/conformance.rs` is the Rust verifier. It is wired into
|
|
this crate's standard test target:
|
|
|
|
```
|
|
cargo test -p jouleclaw-conservation --test conformance
|
|
```
|
|
|
|
Other-language verifiers (Python, Go, JavaScript, …) MUST parse
|
|
`vectors.json` directly, compute the findings, and assert byte-
|
|
equality against `expected_findings` under the same snake_case-
|
|
tagged enum serialization the reference uses. The order of
|
|
findings in the output MUST match the order in `expected_findings`.
|
|
|
|
## Encoding
|
|
|
|
- `spec_bytes_utf8` / `output_bytes_utf8` — UTF-8 bytes to measure.
|
|
- `delta_fields` — a JSON object of name → string value. The
|
|
reference verifier sums per-field byte counts in BTreeMap
|
|
iteration order (sorted), so the choice is deterministic.
|
|
- `substrate_*` — the amortized arrangement store id, optional
|
|
content hash, and the bytes contributed to the output by the
|
|
substrate (not by the spec or delta).
|
|
- `residual_tolerance` — bytes of acceptable shortfall on
|
|
`output ≥ spec`. `0` for strict conservation.
|
|
- `required_slots` — names that MUST appear in `delta_fields`
|
|
with a non-empty value; missing or empty fields produce a
|
|
`missing_delta` finding.
|
|
|
|
## Adding a vector
|
|
|
|
Add an entry to `vectors`, bump `vector_count`, and re-run the
|
|
verifier. Any added vector becomes part of the conformance contract
|
|
for every implementer.
|