Worktree spec schema conformance - #76
Open
macanderson wants to merge 4 commits into
Open
Conversation
Three defects, all the same shape: a normative claim nothing checked. 1. SPEC.md §9's `verify` example was invalid against the schema SPEC.md ships. Both envelopes carried `"id": "v1"`, but §3.2 grants an `id` only to `query`/`frames`/`error`, `Envelope::Verify`/`Verified` have no such field, and the schema is `additionalProperties: false`. Removed — verify correlates by full frame identity, not by envelope id. Root cause: validate-examples.py checked `examples/` but never SPEC.md, so the one example surface with no machine check was the one that drifted. It now validates every fenced jsonc block in SPEC.md (comments and documented placeholders normalized; structure checked), so CI's existing `schema` job catches this class. Verified by re-introducing the `id`: the harness fails both envelopes and exits non-zero. 2. An ordinary ContextQuery was un-representable in conformant JSON. `kinds` and `anchors` were `required` while both are skip_serializing_if = "Vec::is_empty", so an unfiltered, unanchored query failed validation — the bug PR #44 fixed for ContextFrame, one type over. A test now asserts an ordinary query satisfies the schema's own `required` array (reads the schema, so it cannot drift), and a cross-audit of all 16 shared types confirms no other type demands a field its serializer elides. 3. §G2 claimed "Verified by frame-validity" while `target_uri` appeared nowhere in the conformance or validation code — the self-attestation §11.1 exists to reject. Implemented rather than downgraded: check_frames now rejects an edge with an empty target_uri. Auditing the other ten rules citing frame-validity found §D1 unenforced too: the frame's own content_digest was never format-checked, and the evidence string claimed "well-formed digests" while accepting `sha256:abc` — the very placeholder validate.rs exists to reject. Also fixed; the remaining nine were confirmed enforced. Both new checks are mutation-tested: disabling either makes its test fail. Also corrects contextgraph-host::wire, which said correlation is "negotiated by observation, not by a capability flag" — contradicting §3.2 and the shipped Capabilities::correlation, and inverting a MUST NOT. cargo test --workspace: 243 passed, 0 failed. fmt, clippy -D warnings, validate-examples.py, and conformance-{green,red}/host all pass.
Signed-off-by: Mac Anderson <mac@oxagen.sh>
Resolving the conflict with #63 kept this branch's version of `schema/validate-examples.py` wholesale, silently discarding both checks #63 had added to it on main: * the reference-SERIALIZED vector validation (issue #54) — the half that catches schema/serializer disagreement, which curated examples cannot; * the `$id` + served-copy check, asserting `$id` names the live domain and `site/public/schema/` is byte-identical to the source. Neither loss was visible in CI: both are additive validations, so deleting them removes coverage without failing anything. The PR was green with the checks gone. The second loss was not merely theoretical. This branch had edited the ContextQuery `$comment`, so the served copy under `site/public/schema/` had already drifted from the source — the exact "stale schema that still resolves" failure #63's comment warns about. The merge introduced the drift and deleted the detector in one move. Restoring the check fails immediately on it, which is how the drift was found. Also drops this branch's ContextQuery `required` edit in favour of main's. #63 fixed that bug independently and identically; its `$comment` is the better of the two (it names the conformance suite's own sample_query and records that absence and mean the same thing). `schema/` is now byte-identical to main, and the CHANGELOG entry is reworded to claim only what this branch still contributes: the regression test and the cross-audit, not the schema change. Section numbering reconciled: 1-2 examples/, 3 reference vectors, 4 SPEC.md, 5 schema identity. validate-examples.py: 39 checks pass (24 before the merge, 0 dropped). cargo test --workspace: 292 passed, 0 failed. fmt, clippy -D warnings, and conformance-{green,red}/host all pass.
![sourcery-ai[bot]](https://avatars.githubusercontent.com/in/48477?s=60&v=4){kind=small}
This comment was marked as low quality.
This comment was marked as low quality.
Sorry, something went wrong.
Reviewer's GuideExtends schema validation and conformance around worktree spec examples, enforces previously un-checked protocol rules, and adds regression guards to keep the JSON Schema, Rust types, and SPEC examples in sync. Flow diagram for extended schema/validate-examples.py checksflowchart TD
ROOT["Run validate-examples.py"] --> EXAMPLES["Validate examples/ messages against schema"]
EXAMPLES --> VECTORS["Validate reference-vectors.ndjson against schema"]
VECTORS --> SPEC["Validate SPEC.md fenced jsonc examples"]
SPEC --> IDCHECK["Fetch schema $id URL and compare bytes to local schema"]
IDCHECK --> RESULT["Exit 0 if all checks pass, else 1"]
File-Level Changes
Possibly linked issues
Tips and commandsInteracting with Sourcery
Customizing Your ExperienceAccess your dashboard to:
Getting Help
|
Signed-off-by: Mac Anderson <mac@oxagen.sh>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Spec Conformance Tooling
Extends schema validation and conformance around worktree spec examples, enforces previously un-checked protocol rules, and adds regression guards to keep the JSON Schema, Rust types, and SPEC examples in sync.
Flow diagram for extended schema/validate-examples.py checks
flowchart TD ROOT["Run validate-examples.py"] --> EXAMPLES["Validate examples/ messages against schema"] EXAMPLES --> VECTORS["Validate reference-vectors.ndjson against schema"] VECTORS --> SPEC["Validate SPEC.md fenced jsonc examples"] SPEC --> IDCHECK["Fetch schema $id URL and compare bytes to local schema"] IDCHECK --> RESULT["Exit 0 if all checks pass, else 1"]File-Level Changes
schema/validate-examples.pycontextgraph-conformance/tests/golden_fixtures.rscontextgraph-types/src/frame.rscontextgraph-conformance/src/lib.rscontextgraph-conformance/tests/ingest_conformance.rsCHANGELOG.mdcontextgraph-host/src/wire.rsSPEC.mdPossibly linked issues