Where Truth Lives

Colibri has a single source of truth: a SQLite database in WAL (Write-Ahead Log) mode, opened once per server process, written to by exactly one writer, read by unlimited readers. All mutations flow through this database. All ζ records live here. All η proof leaves are anchored here.

This document explains why SQLite is the single source of truth, how WAL mode works, what the four-surface topology is, and how truth flows between surfaces.

Single Source: SQLite at data/colibri.db

The location is:

E:\AMS\data\colibri.db

This file (and its WAL sidecars) is the authoritative copy of all runtime state in Colibri. It is created at server startup in WAL mode (shipped in Phase 0 task P0.2.2) and is not committed to the repo — the schema definition at src/db/schema.sql is the repo-side source of truth. During the Phase 0 bootstrap, the donor task store at data/ams.db is retained for writeback continuity per CLAUDE.md §1.

The Phase 0 database carries three load-bearing tables:

  1. thought_records — The ζ decision trail. Every tool call, every request, every system event. 100% append-only. Hash-chained.
  2. merkle_nodes — The η proof store. Leaves and internal nodes of the Merkle tree. Immutable after creation.
  3. tasks — The β task pipeline. One row per task. Mutable (state transitions and assignee changes).

Additional tables will exist (tasks_history for audit, skill_registry for ε, etc.), but these three are the conceptual core.

Why SQLite?

SQLite is the single source of truth for seven reasons:

1. ACID Atomicity

All writes in a single transaction either succeed together or fail together. If a mutation writes a task row, a ζ observation record, and a ζ reflection record, either all three land in the database or none do. There is no partial state. This is ACID (Atomicity, Consistency, Isolation, Durability), and SQLite guarantees it.

2. Single Writer Pattern

Colibri uses a single writer with unlimited readers. Only the MCP server process writes. Multiple client processes read via SQL queries or receive results via JSON-RPC. The single-writer pattern eliminates distributed consensus. The latest committed state in the database is always truth — no other process can claim authority.

3. WAL Mode: Concurrent Reads + Single Writer

SQLite can be opened in WAL (Write-Ahead Log) mode. In WAL mode:

  • One writer opens the database and writes to it.
  • Unlimited readers connect at the same time without blocking the writer.
  • The writer’s changes are logged in a -wal file before being merged into the main .db file.
  • Readers see a consistent snapshot of the database at a specific timestamp.

This is why Colibri uses WAL mode. The MCP server (one writer) can dispatch a tool while 10 clients (readers) query the database at the same time. No one blocks.

4. Transactional Integrity of Hash Chains

The ζ chain hashes are computed and verified in the same transaction as the records are written. If a transaction rolls back, the chain hashes roll back with it. The chain cannot be partially written. This makes hash chain validation instant: read the latest record, verify its hash against its parent, and you know the chain is intact. No need to walk the entire chain on every check.

5. Deterministic Ordering

Every record in the thought_records table has a created_at timestamp. SQLite guarantees that timestamps are monotonically increasing (no two records have the same timestamp, and rows are always ordered by creation time). This makes the history a total order. There is no ambiguity about which record came first.

6. Immutability Primitives

SQLite supports PRIMARY KEY constraints, UNIQUE constraints, and FOREIGN KEY constraints. The thought_records table is append-only (no DELETE, no UPDATE). The id column is a primary key. Every ζ record is immutable once written. SQLite enforces this at the database level.

7. File-Based Durability

SQLite writes to disk. If the server crashes, the database is not lost. The next server startup reconnects to the database and continues where it left off. The -wal file ensures that in-flight writes are not lost even in a power failure.

WAL Mode File Structure 

data/colibri.db         # Main database file (all tables, final state)
data/colibri.db-wal     # Write-ahead log (pending commits, auto-managed)
data/colibri.db-shm     # Shared memory index (reader coordination, auto-managed)

The .db file is the canonical copy. The -wal and -shm files are SQLite’s internal coordination mechanism. Agents never touch them directly. SQLite manages them automatically.

Four-Surface Topology

Colibri exists on four surfaces simultaneously. Each surface has a role and a direction of truth.

Surface 1: The Repository (E:\AMS on disk, github.com/LastEld/AMS on cloud)

This is the authoritative copy of all specifications, documentation, skills, and code. The repository does not contain runtime state (not the .db file, not the WAL sidecars). It contains the schema definitions, the initial SQL, the skill definitions, and the agent contracts.

Editors cannot edit the repository main checkout directly. All edits happen in worktrees (Surface 2), merged via PR, and then the main checkout is updated.

Purpose: Specification source for all code and docs. CI/CD source. Editable: Only via PR from a worktree. Truth flows: Repository → Worktree (via git clone/fetch) and Repository → Obsidian (via sync script).

Surface 2: Worktrees (.worktrees/claude/)

These are isolated copies of the repository on disk, one per task. An executor (e.g., Claude) clones the main checkout into a worktree, makes edits, commits, and pushes to a feature branch. The feature branch is then merged to main by the human via PR.

The worktree is ephemeral. Once the PR is merged, the worktree is deleted with git worktree remove.

Purpose: Isolated editing surface. One task per worktree. Editable: Yes. This is where all code and spec edits happen. Truth flows: Worktree → Repository (via PR). Repository → Worktree (via git fetch).

Surface 3: Obsidian Vault (C:\Users\Kamal\Documents\Obsidian Vault\Colibri)

This is a read-only mirror of the repository’s docs/ directory. The colibri-docs-sync skill mirrors the docs one-way: from the repository to the vault. The vault is the human’s reading and planning surface.

The vault has two zones:

  • Mirror zone (docs/): Read-only. Never edit files here. Changes flow from repository only.
  • Planning zone (_vault/): Read-write. The human can write daily notes, meeting notes, and round planning notes here. These are never committed to the repository.

Purpose: Human reading + planning surface. Editable: Only in the _vault/ planning zone. The mirror zone is read-only. Truth flows: Repository → Obsidian (via sync). Obsidian _vault/ → nowhere (never committed).

Surface 4: GitHub Pages (https://LastEld.github.io/AMS/)

This is a public read-only copy of the repository’s docs/ directory, built by GitHub Actions and rendered via Jekyll. The just-the-docs remote theme provides the navigation and styling.

Pages is never written to directly. It is rebuilt on every push to main.

Purpose: Public documentation and specification website. Editable: Never. Read-only. Truth flows: Repository (via CI/CD) → Pages.

Direction of Truth

Truth always flows away from the repository. It never flows back in except through PRs (which are merged by a human).

┌─────────────────┐
│   Repository    │
│ (authoritative) │
└────┬─────┬──┬───┘
     │     │  │
  CI │     │  └─ sync script
     ▼     ▼     │
  ┌──────┐       │
  │ Pages│       │
  │(public)      │
  └──────┘       │
              ┌──▼──────────┐
              │   Obsidian  │
              │    Vault    │
              └─────────────┘
                      ▲
                      │ (mirror, never back)
                      │
         ┌────────────┴──────┐
         │    Worktrees      │
         │   (editable)      │
         └────────┬──────────┘
                  │ (PR)
                  ▼
         ┌─────────────────┐
         │   Repository    │
         │   (main merge)  │
         └─────────────────┘

Repository → Pages (CI/CD)

Every push to the main branch triggers GitHub Actions. Jekyll builds the docs/ directory and publishes to GitHub Pages. This is automatic and one-way.

Repository → Obsidian (Sync Script)

The colibri-docs-sync skill copies files from docs/ in the repository into docs/ in the Obsidian vault. This is an on-demand or per-round operation. It is idempotent (safe to run multiple times). The sync never deletes files in the vault’s _vault/ zone.

Worktree → Repository (PR)

An executor makes changes in a worktree, commits, and pushes to a feature branch. The human reviews the PR and merges it to main. This is the only way changes get back into the repository from worktrees.

Obsidian Planning Zone (Isolated)

Files created in _vault/ are never synced to the repository. They live only in the vault. The human uses _vault/ for scratch notes, daily planning, and round planning. None of this becomes canonical.

Single Writer, Unlimited Readers

The SQLite database operates under the single-writer pattern:

  • One writer: The MCP server process holds an exclusive lock on writes.
  • Unlimited readers: Any client process can execute SELECT queries.
  • WAL mode: Readers don’t block the writer. The writer appends to the -wal file. Readers see a snapshot of the database at the moment they opened their connection.

This pattern is key to Colibri’s design. It means:

  • No distributed consensus needed. Writes are serialized by SQLite’s locking mechanism.
  • The latest committed state is always truth. There is only one version of truth at any moment.
  • Reads are fast because they don’t contend with writes (WAL mode).

Phase 0 Reality

Phase 0 is 100% on non-deferred tasks (28/28 shipped as of R75 Wave I, 2026-04-18). The data/colibri.db file is created at server startup in WAL mode; the schema ships in the repo at src/db/schema.sql (P0.2.2, Wave B). The three load-bearing tables (thought_records, merkle_nodes, tasks) are live, plus supporting tables for skills, sessions, and retention policies.

The donor data/ams.db (78 AMS pre-R53 tables) is retained for task-store writeback continuity through the Phase 0 bootstrap per CLAUDE.md §1, but Colibri’s authoritative state has moved to data/colibri.db at runtime.

Proof of Immutability

Because the SQLite database is the single source of truth, and ζ records are hash-chained, any proof of a mutation’s legitimacy comes from the database:

  1. Query the thought_records table for the mutation’s reflection record.
  2. Verify that the reflection’s chain_hash matches the SHA256 of its content + its parent’s chain_hash.
  3. Walk the chain backward to the genesis record (if needed).
  4. Compute a Merkle proof from the merkle_nodes table (if the mutation is proof-grade).

This is why truth lives in the database. The database is the keeper of proofs.

Next Steps

See lifecycle.md to understand how each mutation puts truth into the database. See ../3-world/physics/constitution.md to understand the seven axioms that govern what mutations are legitimate.

Back to top

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

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