Colibri Protocol Specifications

Purpose

spec/ is the legislative body of Colibri. Every s0X file defines one invariant that Colibri must obey. Unlike phase-scoped guides, specs are phase-spanning — s01 Constitution binds the system from R75 (today, Phase 0) through R216 (Phase 8, identity/governance). A single spec does not become obsolete when a phase ends; it accumulates.

Three properties distinguish a spec from other documentation:

  1. Locked. Changes require an ADR and, for protected rules, a supermajority (see s19-governance).
  2. Referenced by runtime. 3-world concepts (docs/3-world/physics/laws/*.md) narrate the law; specs formalize the invariant. Rule engine (κ) compiles guards from spec text. A rule that passes its test corpus = a verified spec invariant.
  3. Falsifiable. Every spec must be expressible as either a checked guard (κ) or a monitored ratio (μ, integrity-monitor). If neither applies, the spec is aspirational, not normative.

Reading order

There is no single correct path through 19 specs. Three paths are useful:

Foundation path (what a Phase 0 implementer must know)

  1. s01-constitution — the 7 axioms (AX-01..AX-07), protected rules, permanent prohibitions
  2. s02-event-taxonomy — the 6 categories × 19 codes that every log line belongs to
  3. s03-state-model — replicated vs local vs derived; bootstrap procedure; object FSMs
  4. s17-mcp-surface — the Phase 0 contract: 14 tools × 5 domains, Zod schemas (ADR-004 R75 Wave H amendment)

Everything else can be deferred to later phases without blocking src/server.ts.

Legitimacy path (why an action is allowed)

  1. s04-reputation — 3 domains, decay rates, damage table, derived limits
  2. s06-consensus — BFT quorum ⌊2n/3⌋+1, 5 finality levels, clock-drift tolerance
  3. s07-fork-protocol — 5 fork triggers, 3 isolation modes, merge protocol
  4. s09-arbitration — 3 escalation levels, VRF arbiter selection, commit-reveal
  5. s19-governance — proposal FSM, supermajority, entropy injection, protected axioms

Hardening path (what keeps the system honest)

  1. s10-admission — 4 intent types × rate limits with reputation bonus; VRF 5–20% audit
  2. s13-hardening — Merkle trees, Shamir secret sharing, row-level security, threat model
  3. s14-integrity-monitor — circular logic detection, coercion traps, axiom drift
  4. s18-identity — soul-vector, 8 domains × 7 traits, Shamir recovery

Spec index

Depth verdicts as of R75 PR #114 (2026-04-16).

# Axis Target Phase Spec Depth Essence
s01 legitimacy 0+ constitution DEEP 7 axioms AX-01–AX-07, protected rules, permanent prohibitions
s02 legitimacy 3+ event-taxonomy MEDIUM 6 categories × 19 codes, irreversibility levels
s03 legitimacy 4+ state-model DEEP replicated vs local vs derived, bootstrap procedure, object FSMs
s04 legitimacy 2+ reputation MEDIUM 3 domains, decay rates, damage table, derived limits
s05 legitimacy 2–3 experience-tokens DEEP (R75) L0–L2b, promotion rules, witness registry, pattern-matching
s06 legitimacy 3+ consensus MEDIUM BFT quorum ⌊2n/3⌋+1, 5 finality levels, STA clock-drift
s07 legitimacy 5+ fork-protocol MEDIUM 5 fork triggers, 3 isolation modes, merge protocol
s08 legitimacy 3+ gossip DEEP IHAVE/IWANT, Bloom dedup, adaptive fanout, triple-anchor validation
s09 legitimacy 4+ arbitration MEDIUM 3 escalation levels, VRF arbiter selection, commit-reveal
s10 legitimacy 2+ admission DEEP 4 intents × rate limits with rep bonus, VRF 5–20% audit
s11 legitimacy 1+ rule-engine DEEP guard-effect DSL, integer math, 4 rule types
s12 legitimacy 1+ dsl DEEP (R75) grammar, type system, WASM compilation target
s13 legitimacy 0+ hardening MEDIUM Merkle, Shamir, row-level-security, threat model
s14 legitimacy 4+ integrity-monitor MEDIUM circular logic, coercion trap, axiom drift
s15 execution 0+ gsd-contract DEEP GATHER→SYNC→DISPATCH→VERIFY→DONE FSM, writeback
s16 execution 0+ skill-taxonomy DEEP 6 tiers, 8-state lifecycle, 5 pool strategies
s17 execution 0 mcp-surface DEEP Phase 0 contract: 14 tools × 5 domains, Zod schemas
s18 legitimacy 8+ identity DEEP soul-vector, 8 domains × 7 traits, Shamir recovery
s19 legitimacy 6+ governance DEEP proposal FSM, supermajority, entropy injection, 7 axioms

Counts (post R75 depth pass): 10 DEEP · 9 MEDIUM · 0 THIN. R75 promoted s05 and s12 from THIN/MEDIUM to DEEP.

Canonical-axes coverage

Colibri has three axes (execution · intelligence · legitimacy). Spec coverage is not symmetric — that asymmetry is intentional.

Axis Spec coverage Rationale
execution s15, s16, s17 Execution specs are narrow and concrete: the GSD FSM, the skill taxonomy, the Phase 0 MCP tool surface. The bulk of execution semantics lives in docs/3-world/execution/ and docs/2-plugin/, not in spec/.
intelligence (none in spec/) Intelligence (δ context, memory retrieval, LLM orchestration) is specified in docs/3-world/social/llm.md and docs/concepts/delta/. It is deliberately not a spec/ citizen because its invariants (recall quality, context hit rate) are statistical, not guardable.
legitimacy s01–s14, s18, s19 Legitimacy is 16 of 19 specs. Every rule about who-may-do-what collapses to a guardable invariant, which is what spec/ is for.

How specs relate to 3-world

3-world (docs/3-world/) is the runtime truth — how the system behaves when Phase N is live. Spec is the law that binds 3-world. The two views must agree; when they drift, spec is authoritative, and 3-world is updated to match.

spec/s06-consensus.md           <--- formalized invariant (guardable)
  ↑
docs/3-world/physics/laws/consensus.md   <--- narrative description
  ↑
docs/3-world/social/actors.md             <--- who participates

A reader should be able to follow a citation chain from any 3-world law back to its spec number.

How specs relate to the rule engine (κ)

κ (rule-engine, s11 + s12) is the mechanism that executes spec invariants at runtime. The chain is:

  1. A spec states a guard (e.g. “an actor with rep < 200 cannot be a witness”).
  2. The DSL (s12) compiles that guard into a wasm check() function.
  3. The rule engine (s11) evaluates check() on every relevant event.
  4. A passing test corpus → the spec invariant is verified; a failing replay → the spec is violated and the event is rejected.

This loop is why spec changes require an ADR: changing s04 changes the guards that κ evaluates, which changes which events are admissible, which changes system behavior observable to every agent.

How specs relate to the integrity monitor (μ)

Not every invariant is guardable by κ at event time. Some invariants are statistical — they hold across a population of events, not on a single one. Examples:

  • “No single actor should account for > 30% of finalizations in a rolling epoch” (s06-consensus)
  • “Arbiter selection must have entropy ≥ H_min” (s09-arbitration)
  • “No more than 0.5% of admissions are VRF-audited false-reject” (s10-admission)

These invariants are enforced by the integrity monitor (μ) (s14-integrity-monitor), which samples the event stream and computes ratios. A spec that is neither guardable (κ) nor monitorable (μ) is documentation only, not law — such a spec should be moved to 3-world/ rather than retained in spec/.

Amendment procedure (short form)

Every spec is amendable, but not identically. The full process is in s19-governance §amendment; the spec-side summary:

Spec type Threshold Notes
Protected axioms (AX-01..03) Forbidden Constitutionally immutable; forking the network is the only exit
Constitutional non-protected 5-of-6 supermajority e.g. rule-set version cutovers
Operational parameters Simple majority e.g. decay rates, admission rate-limits
Editorial (typos, reordering) ADR merge No vote required

A passing vote triggers an ADR, which updates both the spec and the κ rule set. Spec and rule set are never allowed to diverge; if a vote passes the spec amendment but the rule change fails compilation, the amendment is reverted in the next round.

Phase 0 posture

As of R75 Wave I (2026-04-18), src/server.ts registers the 14 shipped Phase 0 MCP tools across α β γ ε ζ η; none of them invokes the rule engine (κ is Phase 1). Specs in spec/ remain protocol-level documents — s17 graduates to colibri_code: partial because its Phase 0 slice shipped; every other spec retains colibri_code: none pending its own phase.

Concretely, the Phase 0 tool surface (s17) touches only three spec-relevant tables: mcp_tasks (β task pipeline), mcp_thoughts (ζ decision trail), and mcp_merkle_leaves (η proof store). Every other table referenced by specs — mcp_events, mcp_reputation, mcp_tokens, mcp_witnesses, mcp_rules — exists as schema stubs only.

Dependency graph

Specs are not independent. A spec may depend on another in three ways:

Relation Meaning Example
defines Spec A provides a term or type that spec B uses s02 defines event codes used throughout s04–s11
constrains Spec A’s guards restrict what spec B may state s01 constrains every other spec (axioms are supreme)
completes Spec A is incomplete without B’s runtime mechanics s11 is the engine; s12 is the language it runs

Key dependency chains:

  • s01 → s02 → s03 — axioms → events → state (the foundation triad)
  • s04 → s05 → s18 — reputation → tokens → identity (the legitimacy stack)
  • s11 ↔ s12 — engine and language are co-defined (mutual)
  • s17 depends on s15, s16 — the Phase 0 tool surface must reflect the execution contracts

A spec change cascades: editing s02 forces a review of every downstream spec in the graph.

Spec file conventions

Every spec file obeys:

  1. Frontmatter. title, tags, spec (the S-number), status (always spec-only today), updated (ISO date).
  2. Status block. The ## Implementation Status table at the bottom of each file is authoritative — when a spec gains code, the Status column flips and the spec carries a PR reference.
  3. No inline code. Specs describe behavior, not implementation. Code examples are pseudocode or DSL only; actual TypeScript lives in src/ under the corresponding domain.
  4. Cross-refs at the foot. A ## Cross-references list, one per dependency, pointing to the related spec or 3-world narrative.
  5. No phase-scoped language. Specs are phase-spanning; avoid phrasing like “in Phase 2 we will…” — put that in guides/implementation/ instead.

Cross-references

  • docs/colibri-system.md — canonical vision that ties axes to specs
  • docs/architecture/decisions/ — ADRs that amend specs (ADR-004 tool surface, ADR-006 DSL)
  • docs/3-world/physics/laws/ — narrative counterpart to spec invariants
  • docs/guides/implementation/task-breakdown.md — Phase 0 task list, referenced by s17

Back to top

Colibri — documentation-first MCP runtime. Apache 2.0 + Commons Clause.

This site uses Just the Docs, a documentation theme for Jekyll.