Module diagnostics 

Cache-prefix diagnostics (Task 12, spec §6.6) and the /context report.

Canonicalization (documented approximations)

The tools-prefix / system-prefix / history-tail digests are keyed HMAC over canonical component bytes, derived from the same structural inputs the request builder used — the registered tool schemas, the caller-supplied system prompt, and the annotated message array:

• tools prefix: for each tool, in send order: name ++ 0x1f ++ canonical-JSON(input_schema) ++ 0x1e. This matches stable-prefix semantics (a tool added, removed, reordered, or with a changed schema changes the digest) but is not the exact wire slice — provider-specific envelope keys and separators are excluded by design, so the digest is stable across cosmetic wire changes.
• system prefix: the exact UTF-8 bytes of the system prompt string.
• history tail: for each message strictly after the last message-level cache boundary (cache_control annotation this process applied), canonical-JSON(message) ++ 0x1e. When no boundary exists the tail is the whole history. Canonical JSON is serde_json::to_vec of the already-built message value — the same value the wire body was serialized from, but not byte-sliced out of the wire buffer.

None of these bytes are retained: only lengths and keyed digests (installation-scoped HMAC key, see trace::key) leave this module.

Session snapshot

CacheSnapshotStore keeps the previous emitted request’s component digests (bounded metadata only — digests, byte lengths, tool IDs) inside the session’s TraceContext. Compare-and-update is atomic under one mutex, per emitted request: a retried identical request compares equal (all segments Unchanged); an intentional tool order/schema change is flagged with the precise tool IDs. No provider or prompt content is ever stored.

Structs

CacheActivity

Latest cache diagnostics, retained for the /context report. Bounded metadata only (digests, byte lengths, enums, tool IDs).

CacheDiagnostics

Computed diagnostics for one outgoing request.

CacheSnapshotStore

Session-scoped previous-component snapshot (see module docs). Shared via Arc inside TraceContext; all mutation is under one internal mutex so compare-and-update is atomic per emitted request.

ContextReport

Structured /context report: counts, bytes, enums, and counters only — never prompt/tool/skill/memory content.

Enums

ReportValue

Why a /context line has no number: honest provenance, never a fabricated zero.

Functions

history_tail_bytes

Canonical history-tail bytes (see module docs).

system_prefix_bytes

Canonical system-prefix bytes: the system prompt itself.

tools_prefix_bytes

Canonical tools-prefix bytes (see module docs for the exact recipe).