feat(protocol): frame representations — full/compact/reference (CGEP phase 2)

[macanderson]

What this is

CGEP lifecycle phase 2 — frame representations. A ContextFrame now states
how it carries its content, per the lifecycle build prompt
§"ContextFrame representations". This is the implementation the pre-shipped
witness test (contextgraph-types/tests/frame_representation_witness.rs, added
by #35) has been asserting — and failing on main for.

Representation	Inline content	content_ref + canonical_content_hash	content_digest	transform
full	required	optional	optional	absent
compact	required (a transformed rendering)	required	required	required
reference	absent	required	absent	absent

Additive and backward-compatible: representation absent ⇒ full, and
full/legacy frames are byte-identical on the wire (the field is skipped when
full). Query-only providers are untouched.

Feature surface

• Types (contextgraph-types): Representation, ContentFidelity,
  ContentRef, Transform, InlineContentRequirement. ContextFrame.content →
  Option<String> (absent for references) plus the fields above,
  canonical_content_hash, canonical_token_cost, tokenizer_ref.
  ContextFrame::{full,reference} constructors and representation_invariants().
• Negotiation: ContextQuery.representation_preferences (+
  select_representation), Capabilities.representations + resolve (+
  representations_consistent — advertising compact/reference requires resolve).
• Wire: JSON Schema $defs + per-representation invariants (allOf/if-then,
  which reject e.g. a reference carrying inline content); content no longer
  globally required. New examples/ messages (compact + reference frames, a
  representation-capable handshake, a query with preferences) that validate.
• Docs: docs/protocol-surface.md representation section; ADR 0005; CHANGELOG.

The invariants are enforced in three places that agree: Rust, JSON Schema, and
tests.

Scope decision — token_cost kept required (deviation note)

The chosen scope said "token_cost → optional". I kept token_cost: u32
required and added canonical_token_cost/tokenizer_ref additively instead.
Making token_cost optional reopens PR #33's B3 decision on the same field and
the same budget-accounting functions PR #33 rewrites — a guaranteed conflict on
its headline. The witness passes with token_cost: 0 present, so the feature
does not need it. token_cost-optionality belongs in the B3 reconciliation (below).
Happy to flip it here instead if you'd rather.

Also unbreaks main

contextgraph-host and contextgraph-conformance did not compile on main
(a half-applied #37 merge): missing ConsentReceipt/EgressScope/FrameId/
DropReason imports, a DataFlow literal missing egress_scopes, a missing
CHECK_VERIFY_HONESTY test import, and a stale 6→7 check-count assertion.
Fixed here so the workspace builds — these are pre-existing and unrelated to the
feature, split out in the CHANGELOG's Fixed section.

Verification (local — see note)

cargo test --workspace                 all suites pass (incl. witness, both cases)
cargo clippy --workspace --all-targets -- -D warnings   clean
cargo fmt --all -- --check             clean
python3 schema/validate-examples.py    all examples validate

main has no CI workflows (PR #33 adds them), so this PR shows no GitHub
Actions checks — verification above is local. This does not by itself flip
PR #33's red test check: that check clears once PR #33 rebases onto this
once landed.

Rebase reconciliation for PR #33

This lands to main; PR #33 then rebases onto it. Expect these to touch the same
lines (all trivial, but flagged so nothing surprises):

• B3 × reference frames — PR Pre-freeze normative sweep: SPEC.md, canonical token accounting, conformance that actually catches things #33's B3 says token_cost == ceil(utf8_len(content)/4).
  A reference frame has no content and token_cost: 0, so on rebase B3 must
  define the absent-content cost as 0. This is the exact normative decision that
  started this thread.
• Capabilities — this adds representations/resolve; PR Pre-freeze normative sweep: SPEC.md, canonical token accounting, conformance that actually catches things #33 removes
  upsert/subscribe. Same struct, reconcile the literals.
• Overlapping unbreak fixes — PR Pre-freeze normative sweep: SPEC.md, canonical token accounting, conformance that actually catches things #33 also fixes the host/conformance build; the
  import/field/count fixes here overlap.
• ADR numbering — 0005 is provisional and may collide with PR Pre-freeze normative sweep: SPEC.md, canonical token accounting, conformance that actually catches things #33's set;
  renumber on rebase (noted in the ADR).

Known limitation (pre-existing, not fixed here)

The schema lists provenance/relations as required, but the Rust type skips
them when empty (skip_serializing_if = "Vec::is_empty"). So a bare
ContextFrame::reference(...) serializes without them and would fail the schema;
the bundled examples pass because they include [] explicitly. This mismatch
pre-dates representations (any minimal frame hits it) — reference frames just make
it more visible. Left for a separate schema/wire-strictness pass.

[sourcery-ai]

Sorry @macanderson, you have reached your weekly rate limit of 500000 diff characters.

Please try again later or upgrade to continue using Sourcery

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
context-graph-protocol	Ready	Preview, Comment	Jul 22, 2026 9:57pm