kestrel.markets
Version:
A typed, token-efficient language + runtime for agentic trading: agents author bounded plans, the runtime fires them at the tick. CLI + typed library + MCP server.
35 lines (30 loc) • 2.38 kB
Markdown
# Legible text is the source of truth; binary stores are regenerable projections
There are exactly two truths in a Kestrel deployment, and both are legible text:
**authored truth** — `.kestrel` documents (versioned modules) — and **recorded truth**
— the session Bus (append-only JSONL, the canonical serialization certification hashes
are computed over). Everything else the platform persists is a **projection** of those
two: the Blotter (JSON projection of one bus), parquet files (columnar projections for
Grade's OVER-range scans), the sqlite Ledger (query index across Blotters), rendered
Frames (glyph projections). A projection is regenerable by construction — delete it and
rebuild it, byte-for-byte answers — and is therefore never a second writer, never a
second truth, and never load-bearing for correctness.
This extends ADR-0004 (text is a projection of the typed object model) from the
language to the whole persistence layer, and it is why the lake needs no transactions:
truth objects are immutable and content-addressed (write-local during the session,
archive-on-finalize); indexes contend, truths do not. The live-singleton lease is
control-plane, not storage — and that carve-out generalizes: a managed deployment's
**control-plane records** (leases, authority grants, commerce evidence) are a third
class, neither authored nor recorded truth. They are authority, not derivation — not
certifiable by re-projection — so they must carry their own honesty rule (append-only,
content-addressed, exportable to a legible audit log), and nothing on the deterministic
Session path may ever be load-bearing on them.
We chose this over database-as-truth because humans AND agents must be able to read
what happened directly — `grep` and `diff` are perception tools for the authoring
loop — and because certification is re-projection: rebuild the artifact from text and
byte-compare. A store you cannot regenerate from legible text is a store you cannot
certify.
Consequences: every new artifact must name the text truth it projects from and ship a
regeneration path (no orphan stores); binary/columnar formats are welcome as caches
and indexes but a migration of one is a rebuild, never a data migration; upgrading a
projection schema is re-projection, so projection formats may evolve freely while bus
and document schemas version conservatively.