feat: context/verify — pull-based frame revalidation

[macanderson]

Implements #26 from scratch. The issue was auto-closed by PR #32's keyword with no implementation landed — only design prose in docs/context-reuse.md. There was zero verify code in any contextgraph-types or contextgraph-host source file; the #4-context-verification anchor, the verify capability mentioned in the spec-version note, and the D1/D4 cross-references all pointed at a section that did not exist. This builds it.

The exchange

The host sends the frame identities it holds; the provider answers one verdict each.

pub struct VerifyRequest { pub frames: Vec<FrameId> }        // identities only
pub struct FrameVerdict  { pub frame: FrameId, pub verdict: Verdict }

pub enum Verdict {
    Valid,                                          // unchanged — keep reusing
    Stale { replacement_digest: Option<String> },   // changed — drop it
    Gone,                                           // no longer exists
    Unknown,                                        // provider cannot say
}

No frame body travels in either direction — the economic point of the whole feature, and it is asserted against the serialized envelope rather than merely documented (verify_wire.rs). Even stale carries at most the provider's current digest: enough to tell a host what it would be re-fetching, never the replacement content.

Built directly on identity.rs from #23 — FrameId is the verify unit and its existing is_verifiable() is the digest gate. No parallel identity type was minted.

Correctness choices worth reviewing

Verdicts echo the full identity. FrameVerdict carries the FrameId it answers rather than relying on array position, so a provider that reorders, omits, or duplicates entries cannot shift a valid onto the wrong frame. Since the digest is part of the identity, a verdict about a different digest does not answer for the one asked — there is a test pinning exactly that.

Default-deny. A frame is retained only on an explicit valid. An identity that comes back with no verdict at all is treated as unknown, not as tacit approval — silence is not validity. Host::verify_frames returns a total partition of its input into retained + dropped, and a test asserts no held identity can be silently lost.

gone is the one reason that doesn't warrant a re-query — the frame is not there to re-fetch. Everything else (stale, unknown, no digest, unsupported, failed) drops the frame and marks it worth fetching again.

The host stays stateless. verify_frames caches no frames and tracks no turn boundaries. "Re-verify past a freshness window" is written as informative host guidance in the spec, not built as machinery — a turn-boundary cache is subscribe's lifecycle, and building one here would blur the exact line §4 exists to draw.

Capability gating and fallback

Capabilities.verify defaults to false, so a pre-§4 provider is treated as unsupported and its frames are re-queried. The host never even sends a request to such a provider (asserted, not assumed). ContextProvider::verify defaults to answering unknown for everything, so a provider that implements nothing can never accidentally bless a stale frame. Verify failures are isolated exactly like query fan-out legs — one provider's timeout drops its own frames and never another's.

Conformance: honest staleness without mutating a real source

The subtle part. Because the digest is provider-declared and opaque (§1), the suite cannot check the provider's answer — only that it distinguishes. So verify-honesty asks twice about frames the provider just served:

1. with the real digests → an honest provider says valid;
2. with those digests mutated → indistinguishable, from the provider's side, from a source that changed underneath the host → an honest provider says stale.

That is the issue's "provider answers honestly for a mutated source (digest mismatch ⇒ stale)" requirement, testable against any provider without the suite needing write access to anyone's sources.

Two fixture modes prove the check bites in both directions:

• --misbehave rubber-stamp-verify — always answers valid; fails ask 2. This is the dangerous lie: it would let a host go on citing evidence that changed.
• --misbehave hollow-verify — advertises the capability but answers unknown to everything; fails ask 1.

The check is skipped, not failed, when a provider doesn't advertise verify — that is the declared fallback, not a violation.

verify_wire.rs additionally drives the real stdio fixture end-to-end over an actual pipe: a served frame verifies valid, a mutated digest comes back stale carrying the current digest and is demonstrably evicted by the host, and an unserved frame comes back gone and is correctly not queued for re-query.

Verify vs subscribe (#6) for the freeze

docs/context-reuse.md §4 includes the comparison the issue asked for: who initiates, transport needs, detection latency, cost shape, and which providers each fits. They are complementary, not alternatives — push has no answer for a host that reconnects and wants to know whether its cache is still good; pull has no answer for a host needing millisecond invalidation. Both flags are independent and default false, so the freeze can keep both, either, or one with no flag day. I did not implement any of #6's scope.

Verification

cargo fmt --all -- --check                               # clean
cargo clippy --workspace --all-targets -- -D warnings    # clean
cargo test --workspace                                   # 92 passing (65 on main before this branch)
python3 schema/validate-examples.py                      # all 14 bundled messages validate

Schema and examples are kept in lockstep with the types per the repo convention, and verify_wire.rs makes that a test rather than a habit: the published reference messages must parse as envelopes and the verify exchange must round-trip byte-for-byte. That test is how I caught the FrameVerdict schema def being wrong — allOf against a closed Verdict subschema rejects the flattened frame field.

Notes for adjacent issues

• Specify subscribe (staleness push / frame invalidation) or drop it before the freeze #6 (subscribe): situated in the spec, not implemented.
• Structured error codes on the wire #9 (typed error codes): verify deliberately adds no new HostError. Verdicts are normal responses, and capability-gating removes any "unsupported" error case, so there is no code for Structured error codes on the wire #9 to reconcile.
• Define token_cost semantics: a canonical counting rule so budget honesty is actually checkable #8 (token_cost): untouched. Verify carries no cost field — it is priced in bytes, not tokens.
• Pre-freeze normative sweep: SPEC.md, canonical token accounting, conformance that actually catches things #33 / test(protocol): publish context graph golden fixtures #35: both are open and touch wire.rs, capability.rs, the conformance suite, schema, and docs. I read them rather than editing their files, so textual conflicts on those shared files are expected; none of the semantics overlap. Pre-freeze normative sweep: SPEC.md, canonical token accounting, conformance that actually catches things #33 adds error_code.rs and SPEC.md, which I stayed out of entirely.
• Overlap with the Consent-scope vocabulary + audit-grade consent receipts: make "did it leave the machine" answerable years later #25 receipts PR (feat(consent): egress-scope vocabulary + append-only consent receipts #37): that branch adds docs/context-reuse.md §3 and its own conformance check, so both PRs grow the conformance count and the same doc file. Adjacent sections, no semantic conflict.

Closes #26

[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

[macanderson]

Independently verified locally by the orchestrating session (this repo has no GitHub Actions workflows, so local gates are the only gate):

• cargo fmt --all -- --check — clean
• cargo test --workspace — 92 tests passing across 12 suites, 0 failures
• cargo clippy --workspace --all-targets -- -D warnings — clean

Also confirmed the implementation is real code rather than spec prose: contextgraph-types/src/verify.rs (new wire types), 66 verify references in contextgraph-host/src/host.rs, capability gating in capability.rs, provider/wire/stdio/http plumbing, and the new contextgraph-conformance/tests/verify_wire.rs conformance case. This is the check that was missed when #26 was auto-closed by PR #32's keyword with docs-only changes.

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
context-graph-protocol	Ready	Preview, Comment	Jul 22, 2026 7:36pm

[vercel]

Additional Suggestion:

run_query_and_shutdown_checks is called with 3 arguments but its signature requires 4 (caps), causing an E0061 compile error.