Crate contextgraph_host 

contextgraph-host — the Context Graph Protocol host runtime.

A Context Graph Protocol host is the side of the protocol that asks for context: it discovers providers, negotiates capabilities, routes a ContextQuery to the ones that can answer, budgets and cites what comes back, and gates what may leave the machine. This crate is that host runtime: today it is exercised by the Context Graph Protocol conformance suite and drives the contextgraph-inspect tool, and it is usable by any Rust agent that wants Context Graph Protocol support (SPEC.md §1). Note that the in-tree context providers do not yet route through this host — they share contextgraph-types values via in-process calls — so this is the host runtime and conformance harness for the protocol, not (yet) the path every built-in source is served through. SPEC.md is the normative specification; every module cites the section it implements.

Shape

• Envelope + wire — the versioned NDJSON message envelope and its framing (SPEC.md §2). Version mismatch is a named error, never a hang.
• ContextProvider — the one trait every source implements, whether in-process, a stdio child, or a remote HTTP endpoint (SPEC.md §3, SPEC.md §5).
• StdioProvider / RawStdioConnection — child-process transport with scrubbed-environment isolation and process-group teardown. StdioProvider demultiplexes correlated replies on their id via a dedicated reader task, so a provider that negotiated correlation can have concurrent queries in flight over one connection while a non-correlating provider stays lock-step (ADR 0002).
• HttpProvider — remote streamable-HTTP transport (SPEC.md §3).
• ConsentStore — the gate that keeps an egress provider un-queried until the user consents, naming what leaves (SPEC.md §4).
• ingest — the ingestion-side dual of compose: turns a user’s paste into a local, egress-free provider serving content-addressed frames, so the prompt’s biggest un-disciplined input is budgeted and cited like any other (ADR 0006).
• Host — registers all three provider kinds behind one handle and Host::query_all fans a query out concurrently, enforcing timeouts, consent, and budget honesty (SPEC.md §4 and §7).
• trust — the keys a host trusts for provenance attestation, and the verifier that consumes them (SPEC.md §6.5). The operator is the trust root: nothing is discovered and nothing is trusted on first use. An attestation the host cannot check degrades its frame to unattested and never removes it (F9).
• verify — the bytes half of F5: re-reads the local source a file provenance addresses and checks its declared digest against the actual bytes (SPEC.md §6.2). A host API, not an automatic re-read of any provider uri; the end-to-end harness that calls it is issue #14.

Isolation invariants (SPEC.md §4 and §10)

What is enforced today: a stdio child is spawned with a scrubbed environment (env_clear plus a PATH/HOME allowlist), so it inherits no credentials or secrets the host holds via environment variables; each call is bounded by a timeout, and on Unix the child leads its own process group so a crash or hang is contained and reaped without touching its siblings. An egress provider is never auto-enabled. Frame content is untrusted data; this crate only ever transports it — it never executes frame content, and a host composing frames into a prompt must delimit them as quoted material.

Not yet enforced — filesystem confinement. A child runs with the host’s working directory and ordinary filesystem access; there is no cwd jail, chroot, mount namespace, or seccomp sandbox. Environment scrubbing blocks credentials passed via env vars, but a provider can still read files the host user can read. Treat a stdio provider as trusted code you chose to run, not as a sandboxed principal — real filesystem isolation is future work.

Re-exports

pub use compose::ranking::PerProviderQuota;

pub use compose::ranking::RankingStrategy;

pub use compose::ranking::RoundRobinByRank;

pub use compose::ranking::ScoreDescending;

pub use compose::ranking::is_ranking_permutation;

pub use compose::ranking::rank_with;

pub use compose::AuditEntry;

pub use compose::Citation;

pub use compose::ComposedPrompt;

pub use compose::CompositionAudit;

pub use compose::DedupDrop;

pub use compose::Deduped;

pub use compose::ExclusionReason;

pub use compose::FrameDisposition;

pub use compose::VerificationState;

pub use compose::budget_split;

pub use compose::compose_context;

pub use compose::compose_for_prompt;

pub use compose::compose_for_prompt_attested;

pub use compose::compose_for_prompt_with;

pub use compose::dedup_cross_provider;

pub use compose::fold_to_edges;

pub use compose::order_by;

pub use compose::order_by_value;

pub use compose::rendered_token_cost;

pub use consent::ConsentDecision;

pub use consent::ConsentRecord;

pub use consent::ConsentStore;

pub use error::HostError;

pub use host::DropReason;

pub use host::DroppedFrame;

pub use host::FanOut;

pub use host::Host;

pub use host::ProviderOutcome;

pub use host::ProviderResult;

pub use host::VerifyOutcome;

pub use http::Credential;

pub use http::HttpProvider;

pub use http::refuse_insecure_transport;

pub use ingest::IngestBundle;

pub use ingest::IngestConfig;

pub use ingest::IngestProvider;

pub use ingest::PasteIngest;

pub use ingest::SegmentKind;

pub use ingest::SegmentOutcome;

pub use ingest::SegmentReport;

pub use ingest::ingest_paste;

pub use provider::ContextProvider;

pub use provider::capability_matches;

pub use provider::frame_kind_name;

pub use stdio::RawStdioConnection;

pub use stdio::StdioProvider;

pub use trust::AttestationLedger;

pub use trust::AttestationState;

pub use trust::FrameAttestationOutcome;

pub use trust::TrustStore;

pub use trust::TrustedKey;

pub use verify::DigestVerification;

pub use verify::verify_file_provenance;

pub use verify::verify_provenance_digest;

pub use wire::AttesterKey;

pub use wire::Envelope;

pub use wire::decode_line;

pub use wire::encode_line;

pub use wire::envelope_kind;

pub use wire::versions_compatible;

Modules

compose

Deterministic context composition (docs/context-reuse.md §1).

consent

Consent gating for egress providers (SPEC.md §4 and §10; SPEC.md §7 point 4).

error

HostError — the one typed error the host runtime raises (SPEC.md §10 “fail loud”). Everything a fan-out or a single provider exchange can go wrong with is a named variant here; nothing in the hot path panics. contextgraph-host owns its own error type rather than borrowing stella’s so the crate stays industry-facing and dependency- light (SPEC.md §1 — depends only on contextgraph-types + transport crates).

host

The Host — one uniform handle over every provider, and the fan-out router.

http

Streamable-HTTP transport: a remote Context Graph Protocol provider reached by POSTing the envelope to its URL (SPEC.md §3 “remote providers: streamable HTTP”). The reference host uses request/response JSON — the Envelope as the POST body, one Envelope back as the response body — which any streamable-HTTP server satisfies; chunked frame streaming is a documented forward extension, not needed for the v1 shape.

ingest

Prompt ingestion as a local provider (ADR 0006).

provider

The uniform provider handle.

stdio

Stdio transport: a child-process Context Graph Protocol provider spoken to over its stdin/stdout (SPEC.md §3 “local providers: child processes over stdio”).

trust

Trust roots for provenance attestation, and the host-side verifier that consumes them (SPEC.md §6.5, F8–F9; ADR 0016).

verify

Host-side end-to-end provenance-digest verification (SPEC.md §6.2, §F5; issue #12) — the bytes half of F5.

wire

The CGP wire envelope and its framing (SPEC.md §Transport bindings).

Structs

FrameAttestation

The one FrameAttestation (SPEC.md §6.5.5). It is defined in contextgraph-types because it is a wire type that rides ContextQueryResult, and it is re-exported here so a host author has one import rather than two. This crate briefly defined two more of its own; see #161. What a result set says about one frame’s attestation — the wire carrier that keeps a ProvenanceAttestation beside the frame it covers (SPEC.md §6.5.5, F11).

Constants

PROTOCOL_VERSION

The Context Graph Protocol version this host speaks, re-exported from contextgraph-types (SPEC.md). The stable protocol version string this crate implements (SPEC.md §3.1).