fix: hold the spec to its own schema, and its own conformance claims

[macanderson]

Three reported defects, all the same shape — a normative claim nothing checked — plus a fourth found by generalizing the third.

1. SPEC.md §9's verify example failed the schema SPEC.md ships

Both envelopes carried "id": "v1". But §3.2 grants an id only to query/frames/error, the reference Envelope::Verify/Verified have no such field, and the schema is additionalProperties: false. The spec's own example was invalid against the spec's own definition.

Removed. verify correlates by full frame identity, not by envelope id — which §9's prose already explains.

Root cause, and the actual fix: schema/validate-examples.py validated examples/ but never SPEC.md. The one example surface with no machine check was the one that drifted. It now validates every fenced jsonc block in SPEC.md — // comments stripped (string-aware), documented placeholders (sha256:<64 hex>, "…") normalized, then structure checked against the root schema or $defs/ContextFrame as appropriate. Substituting a placeholder never invents a member, so it cannot mask an additionalProperties violation.

CI's existing schema job now covers this. Confirmed by re-introducing the id:

FAIL  SPEC.md:442 [1/2] (envelope verify)
FAIL  SPEC.md:442 [2/2] (envelope verified)
2 failure(s)

2. An ordinary ContextQuery was un-representable in conformant JSON

kinds and anchors were listed as required while both are skip_serializing_if = "Vec::is_empty". An unfiltered, unanchored query — what a host sends when it wants anything relevant — serializes without them and failed validation. Precisely the bug PR #44 fixed for ContextFrame, one type over.

Fixed the schema to require only what the reference serializer always emits. A new test asserts an ordinary query satisfies the schema's own required array (it reads the schema, so it can't drift into a stale snapshot).

I also re-ran the audit that missed this, mechanically cross-referencing every skip_serializing_if field against every schema required list: ContextQuery was the only remaining mismatch across all 16 shared types. The audit flags it pre-fix and is clean post-fix.

3. §G2 claimed an enforcement that did not exist

target_uri appeared nowhere in the conformance or validation code. Implemented rather than downgraded — the schema has carried minLength: 1 from the start and §G1 immediately beside it is enforced, so making the claim true beats weakening it.

4. §D1 was unenforced too (found by generalizing #3)

Auditing the other ten rules citing frame-validity turned up a second instance: the frame's own content_digest was never format-checked. check_frames accepted sha256:abc — the very placeholder validate::tests::rejects_the_placeholder_digest_the_repo_used_in_examples exists to reject — while its evidence string claimed "well-formed digests." The digest anchoring deterministic composition, usage reports, and context/verify was held to a looser standard than the §F5 provenance digests directly below it.

Fixed. The remaining nine frame-validity rules (F1–F5, P1–P3, G1) were confirmed genuinely enforced.

Both new checks are mutation-tested — disabling either makes its test fail, so neither is vacuous:

a relation with target_uri "" passed frame-validity — §G2 is unenforced again

Also

contextgraph-host::wire documented correlation as "negotiated by observation, not by a capability flag" — contradicting §3.2 and the shipped Capabilities::correlation, and inverting a MUST NOT. An implementer following it would send an id to a provider that never declared correlation. Corrected.

Verification

Gate	Result
cargo test --workspace	243 passed, 0 failed
cargo fmt --all --check	clean
cargo clippy --workspace --all-targets -- -D warnings	clean
python3 schema/validate-examples.py	OK — all examples validate
conformance-green.sh / conformance-red.sh / host-conformance.sh	pass

The red suite matters here: it asserts every --misbehave mode is still caught, so the two new checks don't mask existing detections.

Review notes

• No wire-shape change. Nothing a conformant implementation emits today becomes invalid: Rename Open Context Protocol (OCP) → Context Graph Protocol #1 and P1: CI: require status checks on main and add a build badge (pipeline shipped in #33) #2 widen what validates, Make the spec self-contained: promote protocol-surface.md to the normative spec and remove dangling stella references #3 and P1: Pipeline correlated queries in the stdio transport: demux on id, shrink the mutex to the write half #4 reject only frames that were already violating a documented MUST.
• Providers emitting an empty target_uri or a malformed content_digest will now correctly fail conformance. That is the intent, but it is the one behavioral change worth a second opinion before the freeze.

[sourcery-ai]

Sorry @macanderson, you have reached your weekly rate limit of 500000 diff characters.

Please try again later or upgrade to continue using Sourcery

[sourcery-ai]

Sorry @macanderson, you have reached your weekly rate limit of 500000 diff characters.

Please try again later or upgrade to continue using Sourcery