docs(chord): slice 6b D2, Durable's records as declared tables

This commit is contained in:
Mario Zechner 2026-10-28 11:09:06 +00:00
parent bdb68f750e
commit 7dff3effa3
2 changed files with 13 additions and 12 deletions

View file

@ -1633,6 +1633,12 @@ validation and copies the v2 kernel added around Delta.
is used"):** in Durable's own `src` (an ordinary pi module, now that Chord v2 is upstream), importing
`@earendil-works/chord/next` (Chord's `./next` export comes with them). No package cycle: Durable already depends on
Chord, Chord imports nothing of Durable (S13). Durable's conformance suite runs in Durable's tests and CI.
- **Slice 6b D2: Durable's records are ordinary declared tables of the store (owner, 2026-10-27: "a, that's the whole
purpose of this slice"):** `StoreStorage` declares conversations, entries, tasks, submissions and `record_ids` as
`defineTable`s, writes them with `put` (Durable replaces complete records), and reads them with the store's queries;
the outbox, export, import, the applier and later `evolveTable` versions handle them as every table. The partial
head index becomes an index on `(conversation_id, has_head, id)`; indexed strings that must stay lossless keep
Durable's JSON encoding.
- **The performance and memory bar, and converging reviews (owner, 2026-10-27: "yes"):** supersedes "as good as
HEAD in everything" for Chord v2 slices and pi changes. CPU: each hot path (calls, changes, watches, links) within
about 5% of HEAD, measured in bursts with alternating processes pinned to one CPU; worse is fixed or goes to the

View file

@ -56,18 +56,13 @@ Chord imports nothing of Durable (S13); Durable's conformance suite runs in Dura
Durable's four record tables (conversations, entries, tasks, submissions) and its ID namespace.
> **Decision needed (D2): how Durable's records are stored.**
> (a) **Declared tables** in the store, written as ordinary `put` writes: `defineTable`s that `StoreStorage` declares
> for itself (SQL names `"<owner>:<table>"`, e.g. `"session:harness:entries"`), each row the record's indexed columns
> (`id`, `conversation_id`, `kind`, `status`, …) plus the whole record in a `json(...)` column. The outbox, export,
> import and the applier handle them as they handle every table; Durable's layout changes later through
> `evolveTable` (Durable's own SQLite migrations, such as v2's `sleeping`, become table versions). Durable's
> secondary indexes map to declared indexes; the partial head index becomes an index on `(conversation_id, has_head,
> id)` (index columns are non-`opt`). Indexed strings that must stay lossless (`kind`, `requestId`, document kinds and
> keys) keep Durable's JSON encoding in their columns (decision "Text is plain UTF-8").
> (b) **Internal tables** of `StoreStorage` with write kinds of their own (`durable.record`), which the outbox,
> export, import and the applier would each learn. More code, a second table mechanism.
> Proposal: (a).
**Layout (D2, owner, 2026-10-27: "the whole purpose of this slice"):** declared tables of the store, written as
ordinary `put` writes: `defineTable`s that `StoreStorage` declares for itself (SQL names `"<owner>:<table>"`, e.g.
`"session:harness:entries"`), each row the record's indexed columns (`id`, `conversation_id`, `kind`, `status`, …) plus
the whole record in a `json(...)` column. The outbox, export, import and the applier handle them as every table;
Durable's layout changes later through `evolveTable`. The partial head index becomes an index on `(conversation_id,
has_head, id)` (index columns are non-`opt`); indexed strings that must stay lossless (`kind`, `requestId`, document
kinds and keys) keep Durable's JSON encoding in their columns.
- **Writes:** every `StorageWrite` of a table record becomes a `put` of its row (Durable replaces complete records;
conversations and entries are immutable and written once). `record_ids` is a declared table too (`id`,