diff --git a/CHANGELOG.md b/CHANGELOG.md index 0532633..408d71b 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -3,7 +3,8 @@ All notable changes to the Context Graph Protocol crates and this specification repository are documented in this file. -The Context Graph Protocol crates (`contextgraph-types`, `contextgraph-host`, `contextgraph-conformance`) track **crate +The Context Graph Protocol crates (`contextgraph-types`, `contextgraph-host`, +`contextgraph-conformance`, `contextgraph-trace`) track **crate version** (`0.x` today) and **protocol version** (`contextgraph/1.0-draft`) as two independent axes — see [docs/stability.md](./docs/stability.md). This changelog records crate releases and spec-repository milestones together, noting which is @@ -16,6 +17,34 @@ drafts the missing entries from the merge's actual diff bot PR for review — the file never falls silently behind main, and no drafted text lands without a human merge. +## [0.1.2] — 2026-08-01 (crate release) + +All four crates published from `main`: `contextgraph-types`, +`contextgraph-host`, `contextgraph-conformance`, and — for the first time — +`contextgraph-trace`. Protocol version is unchanged (`contextgraph/1.0-draft`); +this is a crate-version release only. + +### Added +- **`contextgraph-trace` is now published.** It was `publish = false` and + documented as "deliberately NOT published", which did not stop anyone + depending on it — it only forced its downstream (stella's `stella arena`, via + `EventBody` / `TraceEvent` / `Journal` / `run_oracles` / `ToolStatus`) to pin + the entire workspace by git rev to reach it. The crate remains **sketch + stage**: it implements `docs/sketches/host-trace.md`, is not part of the + `contextgraph/1.0` surface, and its journal wire format may change in any + `0.x` release. Downstreams should gate on `TRACE_FORMAT`, not on the crate + version. Adds a crate README and the metadata the other three already carry. + +### Fixed +- **`contextgraph-types` 0.1.0/0.1.1 shipped without `record.rs`.** Both were + published from a tree that predates this repository's history re-root, so the + `ContextRecord` module — `ContextRecord`, `RecordBody`, `RecordProvenance`, + `RecordAttestation`, `RecordLink`, `RecordScope`, `RecordStatus`, + `LIFECYCLE_SCHEMA_VERSION`, and the rest of the lifecycle vocabulary — was + declared in `lib.rs` on `main` but absent from the published crate. 0.1.2 is + cut from `main` and contains it. **0.1.1 corresponds to no commit on `main` + and should not be depended on**; use 0.1.2 or later. + ## [Unreleased] ### Added diff --git a/Cargo.lock b/Cargo.lock index 2a77570..fb03eed 100644 --- a/Cargo.lock +++ b/Cargo.lock @@ -211,7 +211,7 @@ dependencies = [ [[package]] name = "contextgraph-conformance" -version = "0.1.0" +version = "0.1.2" dependencies = [ "async-trait", "clap", @@ -227,7 +227,7 @@ dependencies = [ [[package]] name = "contextgraph-host" -version = "0.1.0" +version = "0.1.2" dependencies = [ "async-trait", "contextgraph-types", @@ -244,7 +244,7 @@ dependencies = [ [[package]] name = "contextgraph-mcp-bridge" -version = "0.1.0" +version = "0.1.2" dependencies = [ "clap", "contextgraph-host", @@ -257,7 +257,7 @@ dependencies = [ [[package]] name = "contextgraph-mcp-server" -version = "0.1.0" +version = "0.1.2" dependencies = [ "async-trait", "contextgraph-host", @@ -269,7 +269,7 @@ dependencies = [ [[package]] name = "contextgraph-refprov" -version = "0.1.0" +version = "0.1.2" dependencies = [ "contextgraph-host", "contextgraph-types", @@ -279,7 +279,7 @@ dependencies = [ [[package]] name = "contextgraph-ripgrep" -version = "0.1.0" +version = "0.1.2" dependencies = [ "contextgraph-refprov", "contextgraph-types", @@ -287,7 +287,7 @@ dependencies = [ [[package]] name = "contextgraph-trace" -version = "0.1.0" +version = "0.1.2" dependencies = [ "contextgraph-types", "serde", @@ -297,7 +297,7 @@ dependencies = [ [[package]] name = "contextgraph-treesitter" -version = "0.1.0" +version = "0.1.2" dependencies = [ "contextgraph-refprov", "contextgraph-types", @@ -305,7 +305,7 @@ dependencies = [ [[package]] name = "contextgraph-types" -version = "0.1.0" +version = "0.1.2" dependencies = [ "serde", "serde_json", diff --git a/Cargo.toml b/Cargo.toml index dc7364a..4ba9c4f 100644 --- a/Cargo.toml +++ b/Cargo.toml @@ -13,14 +13,15 @@ members = [ ] [workspace.package] -version = "0.1.0" +version = "0.1.2" edition = "2024" rust-version = "1.90" license = "MIT OR Apache-2.0" repository = "https://github.com/macanderson/context-graph-protocol" homepage = "https://contextgraphprotocol.org" -# Default: crates opt IN to publishing. The three Context Graph Protocol crates each set -# `publish = true`; any future internal/helper crate stays unpublished by default. +# Default: crates opt IN to publishing. The four published Context Graph Protocol +# crates (types, host, conformance, trace) each set `publish = true`; any future +# internal/helper crate stays unpublished by default. publish = false [workspace.dependencies] diff --git a/contextgraph-trace/Cargo.toml b/contextgraph-trace/Cargo.toml index 596818e..e93cd00 100644 --- a/contextgraph-trace/Cargo.toml +++ b/contextgraph-trace/Cargo.toml @@ -7,10 +7,21 @@ rust-version.workspace = true license.workspace = true repository.workspace = true homepage.workspace = true -# Deliberately NOT published: this crate implements docs/sketches/host-trace.md, -# which is a sketch, not part of the contextgraph/1.0 surface. It inherits the -# workspace default (publish = false); publication is an open question recorded -# in the sketch. +documentation = "https://docs.rs/contextgraph-trace" +readme = "README.md" +keywords = ["contextgraph", "trace", "replay", "agents", "llm"] +categories = ["encoding", "development-tools::debugging"] +# Published as of 0.1.2 — the open question the sketch recorded is now answered. +# This crate still implements docs/sketches/host-trace.md, which is a sketch and +# NOT part of the contextgraph/1.0 stable surface: the journal wire format may +# change in any 0.x release, and `TRACE_FORMAT` is what downstreams should gate +# on, not the crate version. It is published anyway because leaving it out +# forced its only downstream (stella's `stella arena`) to pin the whole +# workspace by git rev — an unreviewed, unversioned, GC-eligible commit — to get +# a vocabulary the other three crates already publish. A published crate with an +# honest stability caveat is a smaller supply-chain risk than an unpublished one +# consumed by SHA. See docs/stability.md for what 0.x does and does not promise. +publish = true [dependencies] # Floor requirement — see the note in contextgraph-host/Cargo.toml: caret reqs diff --git a/contextgraph-trace/README.md b/contextgraph-trace/README.md new file mode 100644 index 0000000..a1b5fe7 --- /dev/null +++ b/contextgraph-trace/README.md @@ -0,0 +1,62 @@ +# contextgraph-trace + +[![crates.io](https://img.shields.io/crates/v/contextgraph-trace.svg)](https://crates.io/crates/contextgraph-trace) +[![docs.rs](https://img.shields.io/docsrs/contextgraph-trace)](https://docs.rs/contextgraph-trace) + +The host execution trace (journal) and its replay oracles for the **Context +Graph Protocol**. + +> **Sketch stage — not `contextgraph/1.0`.** This crate implements +> [`docs/sketches/host-trace.md`](../docs/sketches/host-trace.md), a sketch. It +> is published so downstream hosts can depend on the trace vocabulary by +> version rather than by git rev, but the journal wire format may change in any +> `0.x` release. Gate on the `TRACE_FORMAT` constant, not on the crate version. + +The conformance suite (`contextgraph-conformance`) 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 record 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 +`contextgraph_types::FrameId`, verify observations carry the wire +`contextgraph_types::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 defects an outcome-graded benchmark structurally +cannot see: + +- evidence cited after it was verified stale +- budget arithmetic drifting from the itemization +- phantom tool executions (a result with no matching call) +- 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. + +```rust,no_run +use contextgraph_trace::{Journal, run_oracles}; + +let journal = Journal::from_ndjson(&std::fs::read_to_string("trace.ndjson")?)?; +for check in &run_oracles(&journal).checks { + println!("{}: {:?} — {}", check.name, check.status, check.evidence); +} +# Ok::<(), Box>(()) +``` + +Depends on `contextgraph-types` and serde only, so the oracles stay runnable +anywhere the journal can be read. + +## License + +MIT OR Apache-2.0 diff --git a/contextgraph-trace/src/lib.rs b/contextgraph-trace/src/lib.rs index 78bcf4f..05a8291 100644 --- a/contextgraph-trace/src/lib.rs +++ b/contextgraph-trace/src/lib.rs @@ -2,10 +2,12 @@ //! oracles. //! //! **Sketch stage.** This crate implements -//! [`docs/sketches/host-trace.md`] and is deliberately **unpublished**: -//! nothing here is part of the `contextgraph/1.0` surface. It exists so the -//! shape can be exercised against real journals before any of it is proposed -//! for the spec. +//! [`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. //! //! [`docs/sketches/host-trace.md`]: https://github.com/macanderson/context-graph-protocol/blob/main/docs/sketches/host-trace.md //!