Enum Envelope 

pub enum Envelope {
    Handshake {
        protocol_version: String,
    },
    HandshakeAck {
        protocol_version: String,
        provider: ProviderInfo,
        capabilities: Capabilities,
    },
    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

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

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