Crate contextgraph_trace 

contextgraph-trace — the host execution trace (journal) and its replay oracles.

Sketch stage. This crate implements docs/sketches/host-trace.md. It is published so downstream hosts can depend on the trace vocabulary by version instead of by git rev, but nothing here is part of the contextgraph/1.0 surface: the journal wire format may change in any 0.x release. Gate on TRACE_FORMAT, not on the crate version. It exists so the shape can be exercised against real journals before any of it is proposed for the spec.

The conformance suite holds a provider honest; nothing holds the host-side agent loop honest. This crate is that missing half, split the same way the rest of the protocol is:

• The journal (TraceEvent, Journal) — an append-only NDJSON recording a harness (or a thin adapter observing one) emits while it works: turns, prompt assemblies, tool-call pairing, verify observations, side effects, crashes and resumes. It reuses the protocol’s identity spine — frames are named by FrameId, verify observations carry the wire Verdict — and no frame body ever travels in it.
• The oracles (run_oracles) — pure replay checks over a parsed journal, in the conformance suite’s vocabulary: named checks, pass/fail/skip, evidence naming the exact seq numbers. They catch the defects an outcome-graded benchmark structurally cannot see: citing evidence verified stale, budget arithmetic drifting from the itemization, phantom tool executions, side effects replayed across a crash-resume, resumes blind to their own durable record.

The oracles never talk to the harness — they read the journal. That split is what makes an eventual benchmark runner agent-agnostic: one adapter per harness maps its native logs onto this vocabulary, and every check downstream is shared.

Depends on contextgraph-types and serde only, so the oracles stay runnable anywhere the journal can be read.

Structs

CheckResult

One check’s outcome: which check, its verdict, and human-readable evidence naming the exact seq numbers involved.

Journal

A parsed journal: the recording of one session, including its resumes, in file order. The oracles (crate::oracle::run_oracles) judge it; this type only carries it.

RenderedFrame

One frame at its point of use: the identity that names its exact bytes, what rendering it was given, what the harness declared it cost, and the label a human would see it cited under.

TraceEvent

One journal line: a dense sequence number, a timestamp in the protocol’s RFC 3339 UTC profile (SPEC.md §F4), the session it belongs to, the open turn (when inside one), and the event body flattened alongside.

TraceReport

The result of running the oracles over one journal.

Enums

CheckStatus

The verdict for a single oracle check.

EventBody

The event bodies. Serialized internally tagged on event and flattened into the TraceEvent envelope, so a journal line reads {"seq":5,…,"event":"tool_call","call_id":"call_1",…}.

JournalError

Why a journal failed to parse. Carries the 1-based line number so the failure is actionable against the file.

SessionOutcome

How a session ended — when it ended at all. A journal whose last event is not session_end records a crash, and that absence is load-bearing: the oracles treat dangling work before a EventBody::Resume as expected and the same work replayed after one as the defect.

ToolStatus

The outcome of executing (or declining) one model-requested tool call.

Constants

ALL_CHECKS

Every check this suite runs, in report order.

CHECK_ASSEMBLY_BUDGET

CHECK_CITATION

CHECK_COMPOSITION

CHECK_EFFECT_ONCE

CHECK_RESUME

CHECK_SEQUENCE

The stable check names, so reports and callers agree on identifiers.

CHECK_STALENESS

CHECK_TURN_LOOP

TRACE_FORMAT

The trace-format identifier a recorder SHOULD stamp into EventBody::SessionStart::trace_format, so an oracle suite can refuse a journal written to a vocabulary it does not understand.

Functions

check_assembly_budget_honesty

assembly-budget-honesty — §B1/§B3 held at the point of assembly, where the harness is the declaring party: the itemized frame costs must sum to the total the harness declared, the sum must fit the budget it announced, and a reference frame — which inlines nothing — must cost 0.

check_citation_at_use

citation-at-use — §F3’s “never a bare uuid”, held where it actually matters: a frame rendered into a prompt must carry a non-empty citation label at that moment, not merely have carried one at the provider boundary.

check_deterministic_composition

deterministic-composition — prefix stability (docs/context-reuse.md §1), finally checkable: two prompts rendering the identical frame set (same identities, same representations, same order) must compose to the identical composition_digest. A harness whose composition wobbles under an unchanged set is silently destroying the prompt-cache economics the canonical order exists to buy.

check_effect_exactly_once

effect-exactly-once — the crash-replay double-side-effect bug, by construction: effect_id names an intended-once effect (a deliberate re-execution is a new id), so the same id performed twice is a defect — and the evidence says whether it was replayed across a resume boundary (the classic durability bug) or duplicated within one live run.

check_resume_integrity

resume-integrity — a resume must recover exactly what the journal records. last_seq_seen above the recorded prefix is a recovery of events that never happened (a corrupt recovery); below it is quantified work loss — the resumed harness is blind to events its own durable record holds, which is how a harness re-does work it already did.

check_sequence_integrity

sequence-integrity — the recording itself is trustworthy: seq is dense from 1, there is one session, timestamps are in the protocol profile (SPEC.md §F4), turn markers balance, and nothing follows session_end.

check_staleness_at_use

staleness-at-use — the reuse rule (docs/context-reuse.md §4, V2) held at the point of use: a frame whose exact identity was last verified stale or gone must never be rendered again.

check_turn_loop_pairing

turn-loop-pairing — the tool loop’s contract: every call the model requested is resolved exactly once before the next prompt is assembled, nothing is executed that the model never requested (phantom execution), and no result arrives for a call that was never made or was already resolved.

run_oracles

Run every oracle over the journal, returning a typed report. Never panics: every defect becomes a failing check whose evidence names the exact seq numbers involved.