Crate contextgraph_conformance 

contextgraph-conformance — the public Context Graph Protocol conformance suite (SPEC.md §11).

“Context Graph Protocol conformant” means green on this suite for your declared capability set — a checkable claim, which is what makes third-party adoption safe. run_conformance drives a provider through the protocol and returns a typed ConformanceReport with a pass/fail verdict per check and an evidence string for each, so a failure says exactly what was wrong.

The checks (all against the frozen contextgraph-types contracts):

• handshake — the provider completes the handshake and reports a non-empty identity + capabilities (SPEC.md §3).
• consent-scope — the provider’s declared egress scopes are well-formed and consistent with its data_flow.egress (docs/context-reuse.md §3): no off-machine scope alongside egress: false, and custom scopes namespaced.
• frame-validity — queried frames pass contextgraph-types validation: score in [0, 1], a non-empty title, a non-empty citation_label (SPEC.md §6 — “NEVER a bare uuid”).
• verify-honesty — a provider advertising verify answers valid for frames it just served and stale when their digests are mutated (docs/context-reuse.md §4). Skipped when verify is not advertised — that is the declared fallback, not a failure.
• budget-honesty — returned frames’ summed token_cost never exceeds the query budget, every declared cost is the canonical count, and the frame count respects max_frames (SPEC.md §7 — “never lies about cost”).
• as-of-temporal — a query pinned with as_of gets back no frame whose valid_from is after the pin, i.e. no content that was not yet true at the pinned instant (SPEC.md §6.1). SHOULD-strength and one-sided: a provider that returns fewer frames, or none, never fails it.
• shutdown-clean — the provider tears down without error (SPEC.md §3).
• malformed-input-tolerance — a garbage line is ignored, or errored with code bad_request, never crashing the host (SPEC.md §R1). Staying alive is the MUST; the structured bad_request code is the SHOULD this check now inspects (#9), so an arbitrary error no longer passes. Wire-level, so it applies to stdio providers.
• embedding-fingerprint — a provider declaring an embeddings_fingerprint rejects a query embedding whose length contradicts its declared dimension with bad_request (SPEC.md §E1). A SHOULD, gated on the provider declaring a fingerprint; wire-level, so like the malformed probe it applies to stdio providers.
• provenance-fixture-consistency — every file provenance digest the provider serves matches the bytes on disk it names, re-read and re-hashed by the host (contextgraph_host::verify_file_provenance, §6.2/§F5). A grammatically valid digest that hashes wrong — a stale or forged claim — is caught here, where §F5’s grammar check cannot see it. Host-local: a link to files this host cannot read is skipped, not failed.

The suite is deliberately adversarial: pointed at a provider that lies about costs, emits an out-of-range score, omits a citation label, or dies mid-query, the matching check fails loudly. The bundled contextgraph-example-docs fixture has --misbehave flags that trip each one, proving the suite catches a broken provider (task deliverable).

The host side of the protocol has binding rules too, which the provider-facing checks above cannot exercise. Those live in host_conformance, the dual suite: run_host_conformance drives the reference Host against adversarial in-process providers and asserts it upholds them (SPEC.md §11.1; issue #14).

Both of those suites certify code in this repository. A third, composition_conformance, is for code that is not: it takes a ComposingHost and certifies someone else’s composition layer — the step above Host::query_all that turns a fan-out across several providers into the one frame set that reaches a prompt. That step is where a downstream host makes its own calls about a shared budget, and neither suite above can see it: three providers each returning one honest 400-token frame against a 1000-token query are individually conformant and jointly 200 over. Run run_composition_conformance against your own host; ReferenceComposingHost is the worked example that passes it.

Re-exports

pub use composition_conformance::CCHECK_BUDGET_BOUND;

pub use composition_conformance::CCHECK_DETERMINISM;

pub use composition_conformance::CCHECK_QUARANTINE;

pub use composition_conformance::CCHECK_TOTAL_PARTITION;

pub use composition_conformance::ComposingHost;

pub use composition_conformance::Composition;

pub use composition_conformance::ExcludedFrame;

pub use composition_conformance::ReferenceComposingHost;

pub use composition_conformance::run_composition_conformance;

pub use host_conformance::HCHECK_BUDGET_DROP;

pub use host_conformance::HCHECK_COMPOSITION_AUDIT;

pub use host_conformance::HCHECK_CONSENT_GATE;

pub use host_conformance::HCHECK_CONTENT_QUOTING;

pub use host_conformance::HCHECK_CRASH_ISOLATION;

pub use host_conformance::HCHECK_FRAME_LIMIT;

pub use host_conformance::HCHECK_PROVENANCE_BYTES;

pub use host_conformance::HCHECK_SCOPE_RECEIPT;

pub use host_conformance::HCHECK_VERSION_REJECT;

pub use host_conformance::run_host_conformance;

Modules

composition_conformance

Composition conformance (SPEC.md §11.1) — the suite a downstream host can run against its own composition layer.

host_conformance

Host-side conformance (SPEC.md §11.1; issue #14) — the dual of the provider-facing suite.

Structs

CheckResult

One check’s outcome: which check, its verdict, and human-readable evidence.

ConformanceReport

The result of a conformance run: every check, against a described target.

Enums

CheckStatus

The verdict for a single conformance check.

ProviderTarget

How to reach the provider under test. contextgraph-inspect builds one of these from its CLI arguments; tests build them directly.

Constants

CHECK_ANCHOR_RELEVANCE

CHECK_AS_OF

CHECK_BUDGET_HONESTY

CHECK_CONSENT_SCOPE

CHECK_CORRELATION

CHECK_EMBEDDING_FINGERPRINT

CHECK_FRAME_VALIDITY

CHECK_HANDSHAKE

The stable check names, so reports and callers agree on identifiers.

CHECK_KINDS_FILTER

CHECK_MALFORMED

CHECK_PROVENANCE_FIXTURE_CONSISTENCY

CHECK_SHUTDOWN

CHECK_VERIFY_HONESTY

Functions

check_budget

Validate a query result against the budget contract (SPEC.md §B1, §B3, §B4). Returns (passed, evidence).

check_frames

Validate a query result’s frames against the ContextFrame contract (SPEC.md §6). Returns (passed, evidence). Zero frames is permitted — a provider may simply have nothing relevant.

run_conformance

Run the full conformance suite against a provider, returning a typed report. Never panics: every failure mode becomes a failing check with evidence.

sample_query

The query the suite probes every provider with — no kinds filter, so any provider is asked for its best frames (SPEC.md §5).