Schema Compatibility

Runtime configuration and agent documents are unversioned authored files parsed against the current shape. They reject schema and schema_version fields as hard errors rather than migrating or ignoring them. Session event history is also versionless and read best-effort. Versioned persisted and wire surfaces emit only their current version and reject unsupported versions.

Surface	Current write	Accepted reads
Runtime configuration	unversioned	unversioned current shape
Agent document	unversioned	unversioned current shape
Protocol	19	19
Events and session JSONL	versionless	versionless plus legacy schema markers
Session metadata	unversioned	unversioned current shape
Runtime snapshot	5	5
Catalog cache	2	2
Provider store	3	3
Family recipe registry	1	1
In-memory model manifest (recorded run bindings)	1	1

Agent snapshots embedded in readable events upconvert supported historical shapes before validation. Delegation lifecycle records are ordinary parent session events; the removed delegations.jsonl surface and its schema versions are not read.

The protocol crate exports a JSON Schema set for the wire roots on demand through cargo run -p cookie_agent_protocol --example generate -- --output <directory>; no generated tree is checked in. crates/protocol/scripts/check-schema-additive.sh regenerates the schemas into a temporary directory and enforces that the event payload and extension protocol only ever grow relative to the checked-in baselines. The Rust API documentation describes the public Rust types; the protocol reference summarizes the active method surface.