Struct ContextFrame 

pub struct ContextFrame {

    pub id: String,
    pub kind: FrameKind,
    pub title: String,
    pub content: Option<String>,
    pub content_digest: Option<String>,
    pub uri: Option<String>,
    pub representation: Representation,
    pub content_fidelity: Option<ContentFidelity>,
    pub canonical_content_hash: Option<String>,
    pub content_ref: Option<ContentRef>,
    pub transform: Option<Transform>,
    pub minimum_content_fidelity: Option<ContentFidelity>,
    pub inline_content_requirement: Option<InlineContentRequirement>,
    pub score: f32,
    pub token_cost: u32,
    pub canonical_token_cost: Option<u32>,
    pub tokenizer_ref: Option<String>,
    pub valid_from: Option<String>,
    pub valid_to: Option<String>,
    pub recorded_at: Option<String>,
    pub provenance: Vec<Provenance>,
    pub citation_label: Option<String>,
    pub embedding: Option<FrameEmbedding>,
    pub relations: Vec<Relation>,
}

One context frame returned from context/query.

Fields

id: String

Provider-scoped, stable for dedup across queries.

kind: FrameKind

title: String

Human label — never a bare uuid.

content: Option<String>

Text the host may quote into a prompt. Untrusted data: a conforming host delimits this as quoted material, never as instructions.

Present for full/compact frames; absent for reference frames, which carry only a content_ref. A reference is never encoded as content: "" — the field is omitted entirely.

content_digest: Option<String>

The provider-declared digest of this frame’s inline content bytes — the third component of its stable FrameId identity, opaque to the protocol (e.g. sha256:<hex>). This is the spec’s content_hash (SHA-256 over the exact inline UTF-8 content) under its established name; see canonical_content_hash for the full-source hash. Absent ⇒ the frame is not verifiable and a host re-queries it rather than reusing it unchecked (docs/context-reuse.md §1, §4). A reference frame omits it.

uri: Option<String>

representation: Representation

How this frame carries its content. Absent ⇒ Representation::Full, so legacy frames deserialize unchanged and full frames omit the field.

content_fidelity: Option<ContentFidelity>

Fidelity of the carried content relative to the source. Absent ⇒ exact for a legacy full frame.

canonical_content_hash: Option<String>

SHA-256 over the complete source content bytes (distinct from the inline content_digest). Required for compact/reference frames so a resolved rehydration is verifiable.

content_ref: Option<ContentRef>

The opaque resolver handle for a compact/reference frame’s content.

transform: Option<Transform>

The transformation a compact frame applied to its source. Omitted for full/reference frames.

minimum_content_fidelity: Option<ContentFidelity>

The lowest content fidelity acceptable at this frame’s point of use.

inline_content_requirement: Option<InlineContentRequirement>

Whether this frame’s point of use requires inline content.

score: f32

Provider-normalized relevance in [0, 1].

token_cost: u32

Honest, conformance-audited token cost of the inline rendering.

canonical_token_cost: Option<u32>

Token cost of the complete canonical source content, when the provider declares it. If present, tokenizer_ref SHOULD name the tokenizer it was measured with. Hosts compute model-specific costs when providers omit it.

tokenizer_ref: Option<String>

Identifies the tokenizer that produced the declared costs (e.g. openai:o200k_base).

valid_from: Option<String>

valid_to: Option<String>

recorded_at: Option<String>

provenance: Vec<Provenance>

citation_label: Option<String>

embedding: Option<FrameEmbedding>

relations: Vec<Relation>

Implementations

impl ContextFrame

pub fn full( id: impl Into<String>, kind: FrameKind, title: impl Into<String>, content: impl Into<String>, score: f32, token_cost: u32, ) -> Self

A full-representation frame carrying inline content — the shape every legacy provider emits. The representation/cost/resolver fields default to absent, so a call site need only supply the core, then set extras as needed (the build prompt asks for constructors to reduce source breakage).

pub fn reference( id: impl Into<String>, kind: FrameKind, title: impl Into<String>, content_ref: ContentRef, canonical_content_hash: impl Into<String>, score: f32, ) -> Self

A reference-representation frame: no inline content, only a resolver handle and the canonical source hash for honest, verifiable rehydration. token_cost is the inline cost (0 — nothing is inlined).

pub fn has_valid_score(&self) -> bool

Score must be normalized into [0, 1] per the protocol contract. Conformance suites assert this; providers should self-check too.

pub fn identity(&self, provider_id: impl Into<String>) -> FrameId

The frame’s stable identity under the given provider: (provider id, frame id, content digest). The digest is carried through from content_digest, so a frame without one yields an unverifiable identity (docs/context-reuse.md §1).

pub fn expected_inline_token_cost(&self) -> u32

The token cost this frame’s inline content is required to declare (SPEC.md §B3) — see budget_tokens. A reference frame carries no inline content, so its expected cost is 0.

Distinct from the canonical_token_cost field, which is the provider-declared cost of the full source content.

pub fn declares_honest_token_cost(&self) -> bool

Whether token_cost matches the canonical count for this frame’s content.

This is the check that turned budget honesty from arithmetic into truth: previously a provider could declare token_cost: 1 on a ten-thousand-token frame and pass every check in the suite.

pub fn invalid_temporal_fields(&self) -> Vec<&'static str>

The names of any temporal fields that are not in the protocol’s timestamp profile (SPEC.md §F4).

Returns the field names rather than a bare bool so a conformance failure can say which field was wrong — an evidence string reading “valid_from” is actionable in a way that “temporal validation failed” is not.

pub fn has_valid_temporal_fields(&self) -> bool

Whether every temporal field present on this frame is well-formed.

pub fn provenance_with_unusable_digests(&self) -> Vec<usize>

Provenance entries that address a file but carry a malformed or missing digest (SPEC.md §F5).

File provenance is held to a stricter standard than other kinds because it is the one the host can independently verify: the bytes are on disk. A derivation or episode link has no addressable bytes, so requiring a digest of it would be theatre.

pub fn has_usable_content_digest(&self) -> bool

Whether this frame’s own content_digest, if it carries one, is in the protocol’s digest form (SPEC.md §D1).

Absent is fine — §D1 binds the digest only “when present”. What is not fine is a present digest that no host can compare against, which is what sha256:abc is. §D1 named frame-validity as its verifier while nothing read this field: the digest that anchors deterministic composition, usage reports, and context/verify was the one digest in the protocol that went unchecked, and §F5 held provenance to a stricter standard than the frame’s own identity.

pub fn representation_invariants(&self) -> Result<(), String>

Whether this frame’s fields satisfy the invariants of its declared representation. Providers emit conforming frames; hosts reject a frame that lies about its shape (e.g. a reference carrying inline content, or a compact missing its canonical hash). The Err string names the exact violation.

Trait Implementations

impl Clone for ContextFrame

fn clone(&self) -> ContextFrame

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl Debug for ContextFrame

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

Formats the value using the given formatter.

impl<'de> Deserialize<'de> for ContextFrame

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

where __D: Deserializer<'de>,

Deserialize this value from the given Serde deserializer.

impl PartialEq for ContextFrame

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

Equality operator ==.

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

Inequality operator !=.

impl Serialize for ContextFrame

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 ContextFrame