contextgraph-types

The wire types for the Context Graph Protocol: context frames, queries, capabilities, and provenance.

contextgraph-types is the industry-facing artifact of the Context Graph Protocol crates: MIT licensed, zero dependencies beyond serde. You can implement a CGP provider or host in Rust against this crate alone, with no dependency on Stella or any of its other crates.

Protocol version: contextgraph/1.0 (see stability.md for what that means for this crate's semver).

What's in here

• ContextFrame, FrameKind, Provenance, Relation — the unit of exchange a provider returns from a query: budgeted, scored, and provenance-carrying, so a host can compose and cite it honestly.
• ContextQuery, ContextQueryResult — the retrieval request/response shape, budget-aware by construction (max_tokens, max_frames).
• Capabilities, ProviderInfo, DataFlow — the handshake shapes: what a provider can do, and what it does with your data (reads / writes / egress).

Optional features

All off by default, so the zero-dependency promise above holds for anyone who opts into nothing. Every wire type compiles regardless — a host must be able to parse, relay, and store an attestation it was not built to check — and these features add only the hashing and the signature checking.

The split is not cosmetic. A frame's attestation preimage is a length-prefixed encoding of typed fields and needs no JSON canonicalizer; a record is an open-ended JSON document and genuinely does. Neither layer's consumer pays for the other's dependencies.

Example

use contextgraph_types::{ContextFrame, FrameKind};

let frame = ContextFrame {
    id: "frm_1".into(),
    kind: FrameKind::Doc,
    title: "Getting Started".into(),
    content: "Install with `cargo add contextgraph-types`.".into(),
    uri: Some("file:///docs/getting-started.md".into()),
    score: 0.82,
    token_cost: 64,
    valid_from: None,
    valid_to: None,
    recorded_at: None,
    provenance: vec![],
    citation_label: Some("getting-started.md L1-40".into()),
    embedding: None,
    relations: vec![],
};

assert!(frame.has_valid_score());
let json = serde_json::to_string(&frame)?;
# Ok::<(), serde_json::Error>(())

Every type here round-trips through serde_json — that JSON shape is the protocol; there is no separate IDL.

Building on this crate

• contextgraph-host — a host runtime (provider discovery, stdio/HTTP transports, consent gating, fan-out routing) built on these types, for anyone who wants a ready-made Context Graph Protocol host rather than hand- rolling the wire protocol.
• contextgraph-conformance — the public conformance suite. Green on it is what "Context Graph Protocol conformant" means for your declared capability set.

Docs

• Protocol surface — the full wire shape, field by field.
• Implementing a provider — how to build a CGP provider against contextgraph-types (with or without contextgraph-host).
• Running conformance — proving your provider is conformant.
• Stability — the crate-semver vs. protocol-version relationship.

License

MIT — see LICENSE-MIT in the workspace root.