Stable JSON contracts
Stable JSON contracts
← index
colibri-contracts holds the stable, language-agnostic wire shapes shared
between Colibri (Rust) and Clawdie agents (TypeScript). It owns _schemas and
(De)serialize_, not business logic.
Why a separate contracts crate
- Prevent duplicated definitions between Rust and TypeScript lanes.
- Keep committed manifests in
manifests/parseable by both sides. - Centralize schema strings, field renaming aliases, and backward-compat
Active schemas
| Schema | Rust struct | Purpose |
|---|---|---|
clawdie.interagent.run-manifest.v1 | RunManifest | Records a build/test run — role, agent, artifacts, summary. |
clawdie.runtime-version-inventory.v1 | RuntimeInventory | Host runtime snapshot — OS, package versions, npm/node/zot/pi. |
clawdie.provider-smoke.result.v1 | ProviderSmokeResult | DeepSeek cache-hit probe result and token accounting. |
Schema constants and structs live in crates/colibri-contracts/src/lib.rs.
Evolution rules
- The crate carries no logic — only
serdestructs and schema constants. - New fields are normally optional with
#[serde(default)]so old manifests
RuntimeInventory.piis optional because not every host installspior
zot.
HostStatus.rawis a catch-allserde_json::Valueso hostile collector
Golden tests
crates/colibri-contracts/tests/golden.rs parses every committed manifest in
manifests/ and asserts round-trip equality. The fixtures are intended to be
cross-platform — if a manifest produced on Linux differs from one produced
on FreeBSD 15, the difference must be understood and documented before it is
merged.
See also
- cost-model — how the provider-smoke result feeds cache-hit
- runtime-inventory — where the runtime inventory is