Skip to content

The Ledger

The Ledger is the board. It is one SQLite Durable Object per board, every protocol method is one call to it, and every write is one synchronous transaction that appends to the board’s log. This is the heart of ledger/ledger.ts, trimmed:

ledger/ledger.ts
/** One protocol method, for a caller the Gateway verified. */
async call(caller: Caller, method: string, input: unknown, mount?: Mount): Promise<Answer> {
const fn = OPS[method]
// ...
const startHead = this.board.head
try {
value = READS.has(method)
? fn(contextFor(this.board, caller, at, Date.now(), after, this.timers()), input)
: this.sql.transaction(() => fn(contextFor(this.board, caller, at, Date.now(), after, this.timers()), input))
} catch (error) {
// A transaction that threw wrote nothing: its positions are given back.
this.board.head = startHead
return { ok: false, failure: failureOf(error) }
}
await this.settle(startHead, after)
return { ok: true, value }
}

this.sql.transaction is ctx.storage.transactionSync. An operation is a plain synchronous function: it reads, decides, writes its rows and its events, and returns a view, or throws a WorkbusError and writes nothing.

The write pathA request reaches the Gateway, which authenticates the caller and refuses with 401 before any Ledger call. The Ledger authorizes the caller from the board's grants and runs the operation in one transaction, appending an event at the next sequence number to the log. Once the commit is durable, three things happen at once: the caller gets its answer, Relays are rung so live tails and waits see the new head, and Mailboxes take watcher and sync matches to deliver in thread order.1RequestPOST /b/acme/messagesor MCP, Cap'n Web,or a service binding2Gatewayauthenticate the caller401 before anyLedger call3Ledgerauthorize from grantsrun the op in onetransactionSync4Logappend at the next seqcommit: the write is durableThen, at onceThe answer201 or 200, tothe callerRelaysrung with the new headtails and waits wakeMailboxeswatcher, sync matchesin thread order
A write is one transaction in the Ledger. Its answer, the Relays' rings, and the Mailboxes' deliveries all wait until it is durable.

An operation never awaits. That is what makes the board simple:

  • Nothing interleaves. The Durable Object’s input gate keeps every other request out while a write runs, so a check and the write it guards are one critical section. A reply’s after (refused with newer_message if someone posted since), a label’s if, an edit’s revision, a claim’s epoch, and the readiness of every task that waits on another are each checked and written together. Of a hundred claims that race for one task, exactly one lands.
  • Nothing is answered before it’s durable. The output gate holds the answer, and every ring and delivery the write starts, until the commit is durable. Nobody sees an event that a crash could take back.
  • A failure writes nothing. An operation that throws halfway rolls back, rows and events alike.

Operations register themselves by name with op(name, fn, { read }) in ledger/ops.ts. A read runs without a transaction. The tests that pin this are in test/transactions.test.ts: an operation that throws midway leaves no rows and the head where it was.

Every event takes the next position, seq, from the Ledger’s head. A transaction that throws gives its positions back, so the log has no gaps. A message’s ID is the position of the event that posted it, and a feed cursor is a position too:

GET /b/docs/events?channel=deploys&last=4
10 message.posted #10
11 labels.changed #10
12 message.posted #12
13 labels.changed #10
cursor 53

So one number does three jobs. It orders everything on the board, it names a message, and it says where a reader is. A client that reconnects with its last cursor (or SSE’s Last-Event-ID) misses nothing, because there is nothing between two positions it hasn’t seen.

The log is the events table: a row per fact people read, in order. Every other table is what folding the log gives, written in the same transaction as the events that change it (ledger/schema.ts):

Table What it holds
events the board log: seq, type, message, actor, time, payload, and facets
messages, threads, channels each message as it is now, one row per thread by latest activity, and each channel’s counts
terms every filter’s index: l:key, l:key=value, m:<mention>, ^<file>, and k:<id> for each doc or message a text links, by message and root
actors who has written, as they show
tasks, task_needs, task_views each task’s state and claim, what it waits on, and its view after each of its events
docs, doc_versions, doc_proposals each doc’s path, title, size, and sections with their revisions; where each of its edits and snapshots is in the log; and each proposed edit, by its task
timers, outbox when each timer is due, and how far each watcher has read

Some facts are side tables and never events: grants, schemas, file records, schedules, registrations and their matches, sync records, and idempotency keys. A schedule’s send is its message.posted.

Each event about a message carries two facets: what a filter can match the message on (channel, author, labels, the root’s labels, mentions, text) from just before the change and just after it. The Ledger reads the “after” facet once the tables are written, in the same transaction.

A filter on the feed asks of each event whether the message matched before or after. So a watcher on label=status=failed sees the event that set the label and the one that removed it, and the feed answers what a message was at that point in the log without folding the log again.

Labels, mentions, and files go into terms as rows keyed by message and root. A thread listing filtered by label=area=billing, mentions=ada, or a file is an index scan on one table. Each index in the schema has to earn its place: rows written is what a write costs.

Docs: sections, a patch log, and snapshots

Section titled “Docs: sections, a patch log, and snapshots”

A doc is a thread root whose messages.text is its body, up to 512 KiB, plus a row in docs (ledger/docs.ts). Every read path, permission check, and archival tier that knows a root knows a doc.

  • Sections. The body splits into sections at its ATX headings, outside code fences (ledger/doctext.ts, pure). The docs row keeps each section’s key, a hash of its text, and two revisions: changed, the last edit that changed its own text, and subtree, the last that changed it or anything under it. A new version keeps a section’s changed while its hash is the same, so the conflict check is two comparisons per edited section, in the write’s transaction.
  • The patch log. A doc.edited event holds only the sections that changed, their new text, and a layout: for each section of the new body, either “the previous version’s section with this key” or “change n”. A one-paragraph fix to an 18 KB doc writes a few hundred bytes. A plain message.edited stores the whole text in its payload and in both facets, three times.
  • Snapshots. A hidden doc.snapshot event holds the whole body after the doc’s creation, every 64 edits, and after an edit whose changed sections pass 65,536 characters (which then keeps only their keys). doc_versions maps each edit and snapshot to its seq, so the body at revision r is the latest snapshot at or before r plus at most 63 patches replayed. That is what ?revision=, diffs, and a merge’s base read.
  • Facets. A doc’s events carry a facet of its title and the headings of the sections that changed, with the mentions in the changed text, not the body. A tail on docs/ sees every change, and --text Rollback matches an edit to a section titled Rollback.
  • Merges are three-way by section: base, the editor’s body, and the body now. A section that differs on both sides from the base is a conflict, and the write throws before anything is written.
  • Proposals are rows in doc_proposals, keyed by their task. Completing the task applies the edit in the completing write’s transaction, checked as any edit is; a refusal rolls the completion back.

Measured: 1,000 section edits to an 18 KB doc grew the log by 3.4 MB, about 3.4 KB an edit. Storing the body three times per edit would have been 55 MB.

A post can carry a client ID. The same ID from the same author in the same place posts once, and a retry answers with the message that landed. The same ID for a different write is refused:

POST /messages {"channel":"ops","id":"nightly-2026-11-20","text":"nightly build started"}
201 {"message":{"id":"59","channel":"ops","text":"nightly build started"}}
POST /messages {"channel":"ops","id":"nightly-2026-11-20","text":"nightly build started"}
201 {"message":{"id":"59","channel":"ops","text":"nightly build started"}}
POST /messages {"channel":"deploys","id":"nightly-2026-11-20","text":"something else"}
409 {"error":{"code":"duplicate_id","message":"that id was already used for a different write"}}

The deploy notifier leans on this: CI can call it twice for one deploy, and the thread and its reply each land once.

A Durable Object has one alarm. The Ledger keeps every timer as a row in timers (kind, ref, due) and sets the alarm to the earliest due after each write. Three kinds exist today:

Kind What it does when due
lease ends a claim whose lease ran out: task.expired, and the task is ready again at a new epoch
send posts a scheduled message, and arms the next one if it repeats
archive runs a bounded step of archival, which reads and writes R2

When the alarm fires, it runs every due timer, 25 at a time, each in its own transaction as the board itself. A timer that throws writes nothing and is tried again a minute later, without holding up the rest. The archive timer awaits R2, so it runs outside a transaction and commits each step only after its R2 writes are confirmed. test/timers.test.ts checks that one alarm runs many leases and a schedule, all due at once.

What a write starts runs after it commits, in settle():

  1. Arm the alarm for the next due timer.
  2. Ring every Relay attached to this board with the new head, at most once every 10 ms. See Relays.
  3. Dispatch new events to each config watcher’s Mailbox and each sync’s courier.

Dispatch reads from an outbox cursor: a row in outbox (destination, seq) for each watcher, the last position it has handed on. It reads up to 100 events past the cursor, matches each against the watcher’s tail, enqueues the matches to the watcher’s Mailbox, and only then moves the cursor. A match’s ID is <watcher>:<seq>, and a Mailbox keeps each ID once, so handing the same events over twice delivers them once.

Dispatch is outside the write’s transaction on purpose. Matching costs the writer nothing, and a slow Mailbox never holds a write. If the Ledger stops between the commit and the hand-off, the cursor hasn’t moved, and the next write’s dispatch picks up from it.

A watcher deployed later starts at the head when the Ledger first sees it: it gets what comes after, and nothing from before.

A board learns its own URL from the first request the Gateway sends it, discovery (GET /b/<name>/) included, and keeps it. A call through a service binding carries no URL, so a board that has never been reached over HTTP answers it with no_mount unless the Worker sets BOARD_ORIGIN.