clawdie/colibri
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions 33
colibri/docs/wiki/contracts.md
Sam & Claude f581433b29
Some checks failed
CI / rust (pull_request) Has been cancelled
Details
CI / markdown (pull_request) Has been cancelled
Details
CI / port (pull_request) Has been cancelled
Details
CI / agent-jail-pkgs (pull_request) Has been cancelled
Details
docs(wiki): add 9 subsystem pages (rebuilt on current main) 
Brings the wiki-expansion pages onto current main WITHOUT the stale baggage the
original feature/wiki-expansion branch carried (it predated the rename + date
PRs and would have reverted them). Cherry-picked only the 9 genuinely-new pages:
contracts, store-schema, external-mcp, operator-cli, tui, runtime-inventory,
skills-catalog, vault-provision, deployment. Added them to index.md.

Fixed on the way in: vault-provision referenced the pre-rename
VAULT-PROVISION-FIRST-PROOF → repointed to VAULT-PROVISION-RUNBOOK. (No US dates
in these pages.)

Gates: wiki-lint --strict clean (131 pass); markdown format clean.
2026-06-24 16:48:49 +02:00

2.2 KiB
Raw Permalink Blame History

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 defaults.

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 serde structs and schema constants.
  • New fields are normally optional with #[serde(default)] so old manifests still parse.
  • RuntimeInventory.pi is optional because not every host installs pi or zot.
  • HostStatus.raw is a catch-all serde_json::Value so hostile collector output can be captured without forcing a schema bump.

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 metering.
  • runtime-inventory — where the runtime inventory is produced.