Enum Envelope 

pub enum Envelope {
    Handshake {
        protocol_version: String,
    },
    HandshakeAck {
        protocol_version: String,
        provider: ProviderInfo,
        capabilities: Capabilities,
        attester_keys: Vec<AttesterKey>,
    },
    Query {
        id: Option<String>,
        query: ContextQuery,
    },
    Frames {
        id: Option<String>,
        result: ContextQueryResult,
    },
    Verify {
        request: VerifyRequest,
    },
    Verified {
        response: VerifyResponse,
    },
    Shutdown,
    Error {
        id: Option<String>,
        code: Option<ErrorCode>,
        message: String,
    },
}

One Context Graph Protocol message. Every variant is a small, versioned, type-tagged JSON object; the host writes exactly one per line (NDJSON) over stdio and one per HTTP body (SPEC.md §2).

Variants

Handshake

Host hello: opens the exchange with the protocol version the host speaks (SPEC.md §3 initialize).

Fields

protocol_version: String

HandshakeAck

Provider hello-back: its protocol version, identity + declared data-flow direction, and negotiated capabilities (SPEC.md §3). The host checks the version and surfaces provider.data_flow at consent time.

Fields

protocol_version: String

provider: ProviderInfo

capabilities: Capabilities

attester_keys: Vec<AttesterKey>

The public keys this provider signs its attestations with (SPEC.md §6.5). Empty ⇒ the provider offers no attestation, which is conformant: §6.5 makes the construction mandatory, never the signing.

Query

Host → provider retrieval request (context/query).

Fields

id: Option<String>

Correlation id. A provider MUST echo it on the reply.

query: ContextQuery

Frames

Provider → host budgeted, provenance-carrying frames.

Fields

id: Option<String>

The id of the query this answers, echoed verbatim.

result: ContextQueryResult

The answer, including any detached provenance attestations it carries. SPEC.md §6.5.5 puts those on the result and nowhere else: an in-process provider that never builds an Envelope must still be able to sign what it serves, and one wire home means two encodings of the same signature can never disagree (ADR 0014).

Verify

Host → provider revalidation request: are these held frames still valid (docs/context-reuse.md §4 context/verify)? Carries frame identities only — never bodies. Capability-gated: a host sends it only to a provider advertising Capabilities::verify.

Fields

request: VerifyRequest

Verified

Provider → host per-frame verdicts.

Fields

response: VerifyResponse

Shutdown

Lifecycle teardown; the provider should exit cleanly.

Error

Provider-reported failure — lets a provider report a bad request without dying (SPEC.md §R1 “fail loud”). The host maps this to HostError::Provider.

Fields

id: Option<String>

The id of the request that failed, when the failure is attributable to one.

code: Option<ErrorCode>

Machine-readable classification (SPEC.md §Errors). Optional so that a provider written against an earlier revision stays conformant; a host treats its absence as ErrorCode::Internal.

message: String

Human-readable detail. Always present: the code is for the machine, the message is for whoever reads the log.

Implementations

impl Envelope

pub fn correlation_id(&self) -> Option<&str>

The correlation id this envelope carries, if any.

None means one of two things, and the caller can tell them apart from context: either the envelope is a lifecycle message that never carries one (handshake, shutdown), or the peer does not implement correlation and the exchange must stay lock-step.

pub fn error_code(&self) -> Option<ErrorCode>

The error code carried by an error envelope, defaulting to ErrorCode::Internal when the provider declared none.

Defaulting to Internal rather than to something retryable is the conservative reading: a host must not infer “safe to retry” from a provider’s silence.

Trait Implementations

impl Clone for Envelope

fn clone(&self) -> Envelope

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for Envelope

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl<'de> Deserialize<'de> for Envelope

fn deserialize<__D>(__deserializer: __D) -> Result<Self, __D::Error>

where __D: Deserializer<'de>,

Deserialize this value from the given Serde deserializer.

impl PartialEq for Envelope

fn eq(&self, other: &Envelope) -> bool

Equality operator ==.

fn ne(&self, other: &Rhs) -> bool

Inequality operator !=.

impl Serialize for Envelope

fn serialize<__S>(&self, __serializer: __S) -> Result<__S::Ok, __S::Error>

where __S: Serializer,

Serialize this value into the given Serde serializer.

impl StructuralPartialEq for Envelope