The glossary gets the entry in the Delivery domain with the records that decide it, and retires the noun in hq's prose on a Not line; the verb stays. Where "judge" named something else, the design now uses that thing's word: the node-engine's look at health, an account or the network; the composition check built from a change; the claude-code module's judgement tool. Five issue narratives keep the word of their day. Claude-Session: https://claude.ai/code/session_01JG73KJNrH5EgFXMKKYSrig
907 lines
78 KiB
Markdown
907 lines
78 KiB
Markdown
---
|
||
layer: to-be
|
||
status: in-progress
|
||
code: [mesh-catalog, hq]
|
||
updated: 2026-11-04
|
||
decisions:
|
||
- "ADR 0290"
|
||
- "ADR 0321"
|
||
- "ADR 0423"
|
||
- "ADR 0424"
|
||
- "ADR 0592"
|
||
- "ADR 0593"
|
||
- "ADR 0595"
|
||
- "ADR 0596"
|
||
- "ADR 0597"
|
||
- "ADR 0616"
|
||
- "ADR 0613"
|
||
---
|
||
|
||
# 55 — The knowledge base
|
||
|
||
**Where it stands, 2026-10-17** (the records cleanup, issue 1072; playbook 07, "The design's state is written back"). Built and live since 2026-10-11: the knowledge base is the module mesh-knowledge in mesh-catalog, holding every decision record and research effort (issues 425 and 426, resolved and delivered). Left: the later slices, issues 428 and 429.
|
||
|
||
**Amended, 2026-11-02** (ADR 0592, on the operator's word: "our knowledge base must be nats-native"; "don't use
|
||
file references or local files anymore"). The records leave the store for the bus: each record's head in the
|
||
module's state, its versions on a stream, its sections' bodies once each in an object bucket by digest. A record is
|
||
written one section at a time in a draft, and reviewed one section at a time. A section is a part with a title,
|
||
never a file. § 1, § 2, § 4, § 5, § 8.1 and the fifth slice of § 9 say how; until it is built, the module keeps its
|
||
records in the store as before.
|
||
|
||
**Amended, 2026-11-03** (ADR 0597, ADR 0595 and ADR 0596, from research 082; the operator, 2026-11-02 21:53: "the
|
||
writes are the record"). The knowledge base is the first **ledger**: a record is an instance of a ledger type, every
|
||
change to it is an operation kept in the ledger's history, and its head is the ledger's state, derived from those
|
||
operations by the tool runner's `apply` and never written by the module. A section's text lives only in the
|
||
`write-section` operation that wrote it, with its digest; the head names each section by its title, digest and that
|
||
operation's sequence. So the object bucket `sections`, the state `names`, the stream `versions` and the module's own
|
||
commit rule fall away (ADR 0597 §12, changing ADR 0592 §1 to §12, §17, §25, §32, §33). Its kept data is asked for in
|
||
`requires` by template (ADR 0595), and no other module reads it: another module asks the knowledge base's tools or
|
||
hears its events (ADR 0596). The ledger itself, the same for every module, is designed in
|
||
[design 25](25-the-bus-on-nats.md) § 12; how a module asks for it, in [design 32](32-what-a-module-declares.md) § 4.
|
||
|
||
**Amended, 2026-11-04** (ADR 0616; the operator, 2026-11-03, on issue 1968: "I'm starting to lose the overview"). The
|
||
knowledge base serves a read-only overview page for the operator, built from its own ledger and three other modules'
|
||
verbs and events (§ 11), in the milestone that moves it onto the ledger (ADR 0613 §1).
|
||
§ 1, § 1.1, § 2.1, § 4, § 8.1, § 9 and § 10 say what changes here.
|
||
|
||
**The mesh keeps its decision records and research efforts whole in a module of its own, `mesh-knowledge`, one
|
||
instance on the control-node, holding the seat `knowledge-base`: each record's number, status, topic, typed links,
|
||
its clauses with their own status, and its reasoning in titled sections, with every version kept, all of it on the
|
||
bus. A record is written section by section, checked when it is submitted, reviewed section by section by the
|
||
knowledge base's own judgement and accepted there; the operator's Approve is asked when a record needs it. Agents
|
||
ask what holds, and why, in one bounded call.**
|
||
(ADR 0290, ADR 0592 and ADR 0597,
|
||
from research 045 and research 082.)
|
||
|
||
A **clause** is one numbered statement a decision record makes, with its own status. A **section** is one titled
|
||
part of a record's reasoning. The **knowledge base** is the module that holds the records; the seat it holds is
|
||
`knowledge-base`. The glossary holds these words.
|
||
|
||
**Acceptance.** A session started in any folder on any node asks "what holds about the merge window, and why" and
|
||
gets, in one call under 4 KiB, the clauses in force, the records they come from, what changed them since, and how to
|
||
read the reasoning behind each. A session writes a research effort of more than 100 KiB one section at a time, a
|
||
session on another node takes the draft over and submits it, and every section is judged.
|
||
|
||
This document designs the first slice in detail, tracked by issue 425, and the fifth, the records on the bus
|
||
(ADR 0592), kept as a ledger (ADR 0597). The slices after the first are in
|
||
[§ 9](#9-the-slices-after-the-first), which also designs the third: designs and the glossary's entries become records,
|
||
and the knowledge base works out each design's state (ADR 0423, ADR 0424).
|
||
|
||
## 1. The parts
|
||
|
||
```
|
||
control-node
|
||
|
||
mesh-knowledge (seat knowledge-base, held once for the mesh)
|
||
├ its process, launched by the node runtime
|
||
├ on the bus, asked for in requires by template (ADR 0595), read by it alone (§ 2)
|
||
│ ledger records one instance per record (decision/0290, research/082):
|
||
│ history every operation, in order, each section's text in its write-section
|
||
│ state the head, derived by apply: fields, clauses, links, sections as
|
||
│ title, digest and sequence
|
||
│ snapshot the latest head per record, never expiring
|
||
│ state drafts one key per record being written: its author and its sections as title,
|
||
│ digest and the sequence of their write-section
|
||
│ state asked one key per part asked of the judgement tool, not yet answered: ticket, node, when
|
||
│ state findings the whole-set findings standing now, and the told marks (told.<topic>)
|
||
│ state sent per record, the last operation whose event was sent
|
||
│ stream reviews one message per part reviewed: the digest judged, the verdict, the findings
|
||
├ written through the tool runner's apply on the control-node, the only publisher on the
|
||
│ ledger's history (ADR 0597 §3, §9)
|
||
├ in its memory the search index, built from the bus at start and kept by watching the
|
||
│ ledger's state
|
||
├ verbs ask, get, list, holds, links, history, findings, progress,
|
||
│ reserve, open, write, remove, order, submit, drop, take-over, propose,
|
||
│ withdraw, retract, import, return
|
||
│ served by the control-node's tool runner
|
||
├ events reserved, opened, written, removed, ordered, submitted, dropped, taken-over, proposed,
|
||
│ part-reviewed, reviewed, accepted, changed, moved, checked, formed,
|
||
│ imported, drafted, confirmed, returned
|
||
├ consumes the router's warrants: the operator's Approve for a record that needs it (§ 5)
|
||
├ consumes claude-code's judged: the judgement tool's answer to a part (§ 5)
|
||
├ consumes the delivery module's delivery-done announcement: a design's state (§ 9)
|
||
├ consumes the issue tracker's, mesh-delivery's and the router's events for the overview page (§ 11)
|
||
└ serves the overview page, read-only, on a port it declares, through the route proxy (§ 11)
|
||
|
||
mesh-issues (control-node) the counters for decision and research numbers (§ 6);
|
||
the issues' design links, read for a design's state (§ 9)
|
||
mesh-delivery (its seat) announces each delivery done, on the bus (§ 9)
|
||
claude-code (same node) claude_code_judge: review a section or a head (§ 5), draft and confirm clauses (§ 7);
|
||
emits judged with the answer of each ticket (§ 5, a dependency of the fifth slice)
|
||
records (any node) records_read at a commit: the import's source (§ 8)
|
||
messenger (control-node) the router: the operator's ask and its warrant
|
||
|
||
any agent session, on any node
|
||
mesh MCP server ── mesh_search, mesh_describe, mesh_call ──▶ the verbs, over the bus
|
||
```
|
||
|
||
The module is written in Go against the SDK. It holds no checkout of this repository; the import reads it through
|
||
the records module, as the issue tracker's import does. Until the move of § 8.1, its records are in a database in
|
||
the store; from the move on, it requires no database (ADR 0592 §1, changing ADR 0290 §7).
|
||
|
||
**A record is changed by an operation, and the head follows from it** (ADR 0597 §1 to §8). Every change to a record
|
||
is one operation the module hands to `apply`: among them `reserve`, `propose`, `write-section`, `submit`,
|
||
`take-over`, `review` (a part's verdict), `ask` and `warrant` (the operator's ask and answer), `accept` and
|
||
`withdraw`. The module checks its own rules first (an `accept` needs the operator's Approve where the record needs
|
||
it, § 5; only the author writes a draft, § 4), then calls `apply`, which checks the operation against the record's
|
||
type, appends it to the instance's history with the sequence it expects, derives the head by the operation's effect,
|
||
and writes the head and its snapshot. The author is the account the bus proved for the caller of the module's verb:
|
||
the module names the tool call it serves, and the tool runner stamps the caller it proved for it, never a name the
|
||
caller or the module gave (ADR 0597 §7; [design 25](25-the-bus-on-nats.md) § 12.4).
|
||
|
||
**Every operation's event is sent once, after a restart too.** `apply` emits nothing; the module sends the event of
|
||
each operation it applied (`submitted`, `reviewed` and the rest) with the operation's sequence as the message's
|
||
id, so the bus drops a second send within its duplicate window, and keeps the last sequence it sent per record in a
|
||
state of its own, `sent` (one key `<kind>.<number>`). The duplicate window of its event stream and of `reviews` is
|
||
one day, far longer than a start (40 seconds at most, § 10); a module stopped between a send and its `sent` key for
|
||
longer than a day sends that one event again, which a consumer already takes as a bus delivered at least once. A
|
||
missed send is never chosen over a second one. At start it sends the events of every later operation in each record's history, so a
|
||
module stopped between `apply` and its event loses none, and a consumer of `mesh-knowledge.reviewed` never waits for
|
||
one that was never sent.
|
||
|
||
**A write is whole or refused, and an operation commits when its history takes it** (ADR 0597 §5, §6, changing
|
||
ADR 0592 §10). The commit point of every change to a record is the operation appended to the ledger's history: a
|
||
failure before it is appended refuses the call, and nothing is taken; a racing writer is refused by the bus, which
|
||
expects the history's last sequence for the instance. Once it is appended, the call answers that it is taken, with
|
||
its sequence; the head is derived by `apply` as an update of the revision it read, and a head behind its history is
|
||
caught up by the next `apply` (ADR 0597 §6). A full state bucket answers that the operation is taken and the head behind,
|
||
never that it was refused. So nothing an author was told was refused takes effect later. A reservation is an
|
||
operation `reserve` on an instance with no history, so two sessions reserving at once get two numbers or one
|
||
refusal. The module's other state (`drafts`, `asked`, `findings`) keeps the compare-and-set on the key's revision,
|
||
retried at most three times and then refused with the reason (ADR 0597 §12).
|
||
|
||
**The search index** is a full-text index in the module's own memory, written with the pure Go library bleve. At
|
||
start the module reads every head from the ledger's state and the bodies of every current version from their
|
||
`write-section` operations into it, then keeps it current by watching the ledger's state, noting the last sequence it
|
||
took in (ADR 0597 §12, changing ADR 0592 §11). The index is the module's own, in its memory; the ledger's declared
|
||
index (ADR 0597 §4) is not used for it, because a full-text index is not a key-value bucket. `ask` and `holds` answer from it, ranked by title, clauses
|
||
and sections as before, and refuse with "index not built" while it is built; `get`, `list` and `propose` answer from
|
||
the ledger's state at once (ADR 0592 §11). The integration test measures the start; the estimate is 20 to 40 seconds and about
|
||
100 MB of memory for today's 736 records. Nothing but the module writes it, and nothing outside it reads it.
|
||
|
||
### 1.1 Its tools, health and events
|
||
|
||
Every piece of state has a tool that reads it, and every act the module does by itself can be done by hand
|
||
(ADR 0592 §32, changed by ADR 0597 §12: the sweep and the digest check become the ledger's repairs):
|
||
|
||
| Tool | Reads or does |
|
||
|---|---|
|
||
| read a head | one instance's state in the ledger, whole, with the sequence of the last operation it holds |
|
||
| read a record's history | the instance's operations in order, each with its sequence, author and when; a version is its `submit` |
|
||
| read a section | one `write-section` operation, by its sequence, its text checked against its digest |
|
||
| read a draft | one key of `drafts`, with its author and since when |
|
||
| read a review | the part verdicts of one version, from `reviews` |
|
||
| in-flight parts | the keys of `asked`: each part waiting on the judgement tool, its ticket and since when; ask one again |
|
||
| told marks | the `told.<topic>` keys; clear one, so it is told again |
|
||
| fill | each bucket's and stream's size and count against its cap |
|
||
| rebuild the index | the search index, built again from the bus |
|
||
| review again | asks one part's review again, for a version still proposed |
|
||
| the ledger's repairs | the tool runner's `rebuild` (a head from the history or the snapshot), `snapshot` and `lag` (how far each head is behind its history), served for the module's own ledger (ADR 0597 §10) |
|
||
| integrity | checks every section a head or draft names resolves to a `write-section` whose text hashes to its digest |
|
||
| form-only | lists, dry-runs and runs the form-only versions of § 2.2 |
|
||
| move, and check the move | § 8.1, each with a dry run |
|
||
|
||
**Health** (ADR 0592 §33) is unhealthy, naming the cause, when a bucket or stream does not answer, when the index is
|
||
behind the ledger's state, when a head lags behind its history (the ledger's lag, ADR 0597 §12, changing
|
||
ADR 0592 §33), and when a bucket or stream is at its cap. It names the source it serves from (the database or the bus) and the result
|
||
of the move's last check, and counts drafts idle more than a week, records the form-only check refused, and parts
|
||
waiting more than 30 minutes. A part waiting more than 30 minutes is asked of the operator once through the operator
|
||
channel, and the ask clears when the part is judged; the module stays healthy meanwhile, because a record waiting on
|
||
its review is not the module failing (issue 508). The condition at 75 percent of a cap is the bus module's (ADR 0595 §6; [design 25](25-the-bus-on-nats.md) § 12).
|
||
|
||
**Events** (ADR 0592 §34) are kept 30 days; what a later reader needs is also in the `submit` operation, in the ledger's history. Each carries:
|
||
|
||
| Event | Carries |
|
||
|---|---|
|
||
| `opened` | the record, the version it starts from, the author |
|
||
| `written`, `removed` | the record, the section's title and digest, the author |
|
||
| `ordered` | the record, the titles in order, the author |
|
||
| `submitted` | the record, the new version, its section digests, the author |
|
||
| `dropped` | the record, the author, the reason (asked, or idle 14 days) |
|
||
| `taken-over` | the record, the previous author, the new author, the reason |
|
||
| `part-reviewed` | the record, the version, the part, its digest, the verdict |
|
||
| `reviewed` | the record, the version, every part's verdict: one event per version, as before |
|
||
| `moved` | the record, its counts on the bus |
|
||
| `checked` | the move's check: records compared, every difference |
|
||
| `formed` | the record, the version, the names changed |
|
||
|
||
None is named `drafted`, which stays the event of a clause the import's judgement wrote.
|
||
|
||
## 2. What one record holds
|
||
|
||
- `number` and `kind` (decision or research; with the third slice also design and glossary entry, § 9), its key
|
||
together; `title`, `topic`, `status`, `date`, `deciders`;
|
||
- its **reasoning**, in **sections**, each a plain title and its text in markdown: for a decision, Context,
|
||
Considered Options, Consequences, How it is checked, References; for a research effort, its overview and each of its
|
||
parts by title; for a design, its `to-be` section and, where something of it runs, its `as-is` section (§ 9);
|
||
- for a decision, its **clauses** (§ 3);
|
||
- its **links**, typed, each stored once and read from both ends;
|
||
- its **versions**: every `submit` is a new version with who made it, when, and why in one line; `history` lists them
|
||
and gives the difference between any two. A progressive insight is a version marked as one, dated, saying what stood
|
||
before. A form-only version (§ 2.2) is marked `form`.
|
||
|
||
| Link | From → to |
|
||
|---|---|
|
||
| `supersedes` | a record → a record it replaces whole |
|
||
| `changes` | a clause or a record → a clause it replaces part of |
|
||
| `extends` | a record → a record it builds on |
|
||
| `became` | a research effort → a decision record or design |
|
||
| `rests-on` | a decision → a decision it stands on |
|
||
| `touches` | a research effort → a record, issue or design it bears on (by link), or an area (as text) |
|
||
| `cites` | any record → any record or issue it names |
|
||
|
||
### 2.1 Where it is kept
|
||
|
||
A record is kept as one instance of the knowledge base's ledger `records` (ADR 0597 §11), so that a new version
|
||
costs only the sections it changes; the forms of ADR 0592 §1 to §9 that it replaces are named in its §12.
|
||
|
||
```
|
||
records: history (stream, one subject per instance) records: state (key-value, derived)
|
||
┌───────────────────────────────────────────────┐ ┌─────────────────────────────────┐
|
||
│ 101 decision/0290 propose fields, … │ │ decision/0290 │
|
||
│ 102 decision/0290 write-section "Context" │ │ title, status, clauses, links │
|
||
│ text, digest 3f9a… │ apply │ current sections: │
|
||
│ 103 decision/0290 write-section "Options" │ ───────▶ │ Context 3f9a… 102 │
|
||
│ text, digest 81c2… │ │ Options 81c2… 103 │
|
||
│ 104 decision/0290 submit sections 102, 103 │ │ pending sections: none │
|
||
│ 230 decision/0290 write-section "Context" │ │ after operation 231 │
|
||
│ text, digest 0d77… │ └─────────────────────────────────┘
|
||
│ 231 decision/0290 submit sections 230, 103 │ records: snapshot (one per instance,
|
||
└───────────────────────────────────────────────┘ the latest head, never expiring)
|
||
```
|
||
|
||
- **The head** is the instance's state, `<kind>/<number>`: the record's fields, its clauses with their status and
|
||
source, its links, the operator's ask and warrant, its current and pending version, the latest verdict of each
|
||
part's review (§ 5), and its sections in order, each a title, a digest and the sequence of the `write-section`
|
||
that wrote it, never the text. A section's title is held to 200 bytes, so an entry is at most about 300 bytes,
|
||
and a head with 64 pending and 64 current sections holds at most about 40 KiB of them, within a state value's
|
||
256 KiB (ADR 0597 §11). A reserved number is a head at `reserved`, with who reserved it, when, for what and when it
|
||
expires. It is derived by `apply` and never written by the module.
|
||
- **A version** is the operation `submit`: who wrote it (the caller the bus proved), when, why, its mark, the
|
||
reason of any take-over since the version before, and the version's sections (title, digest and sequence each),
|
||
which its effect sets as the head's current sections. It never copies a section's text. Who wrote each section is
|
||
the author of its `write-section`.
|
||
- **A section's text** is in the `write-section` operation that wrote it, with its digest, at most 40 KiB within a
|
||
history entry's 256 KiB: a section unchanged in a new version costs nothing, since no operation is written for it.
|
||
`apply` refuses a `write-section` whose digest does not match its text, and the module checks the text against
|
||
the digest each time it reads one. A dropped draft's operations stay in the history, named by no version
|
||
(ADR 0597 §11).
|
||
- **The history** is kept for good: the ledger template's history refuses a new operation when full, rather than
|
||
dropping its oldest, and the bus module raises its condition at 75 percent of the cap (ADR 0595 §3, §6). Each
|
||
instance's snapshot, the latest head on a subject of its own, makes a rebuild fast (ADR 0597 §8).
|
||
- **A draft** is a key in the state `drafts` (§ 4). **A part's verdict** is the operation `review` on the record's
|
||
history first, then a message on the stream `reviews`; a `review` with no message on `reviews` is sent at start
|
||
with the operation's sequence as its id, so the consumers of `reviews` miss none and hear none twice. A part
|
||
asked of the judgement tool and not yet answered a key in the state `asked` (§ 5). **The whole-set findings** standing
|
||
now are keys in the state `findings`, and what was told to the operator once is a key `told.<topic>` there. These
|
||
keep their own forms (ADR 0597 §12), asked for in `requires`: the states by the template state; `reviews`, kept for
|
||
good and heard only where granted (ADR 0592 §6, §8), as a bare stream with its own configuration (kept for good,
|
||
refusing when full, a grant), because no template both keeps for good and takes a grant (ADR 0595 §2); the bus module's read of fill every minute
|
||
covers it like any entry that refuses when full.
|
||
|
||
**Caps** (ADR 0592 §25, its object bucket's cap lapsing by ADR 0597 §12). Each is set from the move's dry run, within
|
||
its template's bound (ADR 0595 §3): a history at most 8192 MiB, a state or a ledger's state at most 64 MiB. The
|
||
starting figures, from today's 83 MB for 736 records with every version copying every section, are:
|
||
|
||
| Kept data | Template | Cap |
|
||
|---|---|---|
|
||
| `records` (history) | ledger | 1 GiB |
|
||
| `records` (state) | ledger | 64 MiB |
|
||
| `reviews` | a bare stream, its own configuration | 512 MiB |
|
||
| `drafts` | state | 64 MiB |
|
||
| `asked`, `findings`, `sent` | state | 64 MiB, the template's bound |
|
||
|
||
A write refused at a cap names the cap, and the module's health turns unhealthy naming it.
|
||
|
||
**The ledger's state is the tightest cap.** 64 MiB is already the template's top. A head holds no text, only fields,
|
||
clauses, links and its sections' titles and digests; estimated at most 8 KiB for a usual record, the 736 heads of
|
||
today need about 6 MiB, and about 1000 once designs and glossary entries become records (slice 3, § 9) about 8 MiB.
|
||
Those are estimates; the move's dry run measures the real total, and a total above 32 MiB is told to the operator
|
||
before the move.
|
||
|
||
**Nobody else reads any of it** (ADR 0596 §2, ADR 0597 §9, changing ADR 0592 §8 and §9). Only the knowledge base's
|
||
own account reads its ledger's history, snapshot and state and its other kept data; the ledger's history is published
|
||
on only by the tool runner's ledger credential. Another module asks the knowledge base's verbs (`get`, `history`,
|
||
`ask`) or hears its events (`reviewed`, `accepted` and the rest); the reads of `heads` and `sections` that ADR 0592
|
||
let another module declare lapse once those verbs answer what each reader needed. `reviews` stays a restricted event
|
||
family (ADR 0363 §4), heard only by a module granted it in mesh-knowledge's trusted config value `readers`, which
|
||
names nothing today. A draft is answered by the verbs to its author only, and a version's bodies as `get` answers
|
||
them, so the text in the history is no more open than ADR 0592 kept it. No secret is kept in any of it.
|
||
|
||
### 2.2 A section is a part with a title
|
||
|
||
A section's name is a plain title, unique in its record: "Context", "Direction", "The move". It is never a file's
|
||
name: a name with an extension, a number prefix such as `00-`, or a slash is refused, and so is a text that holds a
|
||
local path (in a person's home folder or the temporary folder), a reference to a file and line, or a link whose
|
||
target is a relative path or a file (ADR 0592 §29).
|
||
|
||
**A reference has one form** (ADR 0592 §30): the record, a section's title, then a row or clause inside that
|
||
section's text, joined by ›, such as "research 081 › Direction › D3"; a clause as its record and number,
|
||
"ADR 0290 §7". Sections never nest: `get` resolves a record and a section's title, and the row is an anchor in the
|
||
section's text, which a web page links.
|
||
|
||
**The records imported with file-named sections** (the research efforts' `00-overview.md` and the like) get titles in
|
||
one form-only version per record, written after the move by the move's tool alone; no verb writes one. It changes only section names and the
|
||
targets of links, each link to a record's file becoming a reference in the form above. It is marked `form`, lists the
|
||
names it changed, and is accepted without a judgement because a check proves only form changed: each section's text,
|
||
with every link replaced by its label, is the same before and after, and each new link target resolves to the record
|
||
the old name named. `get` accepts the old section names as aliases, recorded in that version. A part's review carries
|
||
over to it, its meaning being unchanged. It is not a change of meaning; `history` shows it as a change of form
|
||
(ADR 0592 §31).
|
||
|
||
## 3. Clauses
|
||
|
||
A clause holds its record's number and its own (`0276 §4`), its wording, a `status` and a `source`:
|
||
|
||
| Status | Meaning |
|
||
|---|---|
|
||
| `proposed` | its record is not accepted yet |
|
||
| `in force` | holds, and nothing later changes it |
|
||
| `changed` | a later clause replaces part of it; the `changes` link names which |
|
||
| `superseded` | its record is superseded, or a later clause replaces it whole |
|
||
|
||
| Source | Meaning |
|
||
|---|---|
|
||
| `written` | written as a clause by the record's author |
|
||
| `drafted` | written by the judgement from a prose `Decision` section at the import; never served as in force |
|
||
| `confirmed` | drafted, then confirmed by a second, independent judgement (§ 7) |
|
||
|
||
## 4. Writing a record
|
||
|
||
`reserve` gives a number (§ 6). A record is then written in a **draft**, one section per call, and submitted as a
|
||
version (ADR 0592 §17):
|
||
|
||
| Verb | Does |
|
||
|---|---|
|
||
| `open` | opens a draft of a reserved or existing record, with its fields, clauses and links; called again by its author, changes them |
|
||
| `write` | writes one section: its title and its text; one call per section |
|
||
| `remove` | removes one section from the draft |
|
||
| `order` | sets the sections' order |
|
||
| `submit` | makes the draft a version: every rule below is checked, every reason of a refusal named at once, and the review asked (§ 5) |
|
||
| `drop` | discards the draft |
|
||
| `take-over` | makes the caller the author of a draft or a proposal, with a reason |
|
||
| `propose` | `open`, a `write` of each section and `submit` in one call, for a record that fits one bus message |
|
||
|
||
```
|
||
open ──▶ write ──▶ write ──▶ … ──▶ submit ──▶ proposed, reviewed by part (§ 5)
|
||
▲ │ │
|
||
└─ remove, order └── refused: every reason named, the draft kept as it was
|
||
|
||
drop: the draft is gone take-over: another session becomes its author, with a reason
|
||
```
|
||
|
||
A draft is a key in the state `drafts`: its author, when it was opened, the version it starts from, the record's
|
||
fields and clauses, and its sections in order as title, digest and the sequence of the `write-section` that wrote
|
||
each. Each `write` appends a `write-section` operation with the section's title, text and digest to the record's
|
||
history at once, through `apply`, and names its sequence in the draft (ADR 0597 §11, changing ADR 0592 §17), so an
|
||
unsubmitted draft's text is already in the history, the knowledge base holds the only copy of a draft, and a
|
||
session on any node can read it through the verbs; `submit` carries the draft's sections into the version. A draft holds at most 64 sections and 1 MiB; one untouched for a week is counted in
|
||
the health, and one idle for 14 days is dropped and its author told by `dropped`.
|
||
|
||
**A draft and a proposal have one author** (ADR 0592 §19). Only the author writes a draft or revises a proposal;
|
||
another caller is refused, naming the author. `take-over` makes the caller the author, keeps the reason on the
|
||
record, and tells the previous author by the event `taken-over`. It answers a proposal that only the machine that
|
||
wrote it could revise (issue 1102) and one left proposed for ever by a version from an unproven writer (issue 465).
|
||
A proposal waiting for the operator's Approve cannot be taken over: its author withdraws it first. The reason of a
|
||
take-over is carried in the next version's message.
|
||
|
||
**Only a proven caller writes** (ADR 0592 §20, §21): `open`, `write`, `submit`, `propose` and `take-over` refuse a caller
|
||
the runtime could not prove. The operator's Approve binds the section digests of the version shown; a version with
|
||
any other section is asked again.
|
||
|
||
`submit` and `propose` are refused, with every reason at once, when one of the rules that judge one record or its
|
||
prose fails, among them:
|
||
|
||
- a link names a record or clause that does not exist;
|
||
- a decision has no clause, or a clause has no bold lead;
|
||
- a record it supersedes or changes is not accepted, or one it cites as live is superseded without naming the record
|
||
that replaced it;
|
||
- its topic is not one of the reading order's;
|
||
- a research effort graduates without naming what it became;
|
||
- its text uses a retired word of the glossary, or a daemon's command line;
|
||
- a section is over 40 KiB (it says: split it), or the clauses together are;
|
||
- a section's name looks like a file, or its text holds a local path, a file and line, or a link to a file (§ 2.2).
|
||
|
||
`write` refuses a section over 40 KiB, or one whose name or text breaks § 2.2, at once, so a session learns it on the
|
||
section it just wrote.
|
||
|
||
A proposed record can be revised by its author as new versions until it is accepted. Nothing proposed is ever served
|
||
as in force.
|
||
|
||
## 5. Review and acceptance
|
||
|
||
When a version is submitted (by `submit` or `propose`, a new version of a proposed record included), the knowledge
|
||
base reviews it itself, **in parts** (ADR 0592 §22 to §28, changing ADR 0290 §4): one judgement per part, each in a
|
||
separate call, with no tools, that answers `approve` or `changes` with its findings, the way the issue tracker's
|
||
triage judges an issue. The judgement goes through the agent module's judgement tool (`claude_code_judge`) today, and through
|
||
the mesh's inference layer once one exists; nothing in this design depends on which.
|
||
|
||
- **The head** is one part: the title, the brief, the clauses (at most 40 KiB together) and the links, judged
|
||
against the clauses of the records it links, in what room is left, those not shown named.
|
||
- **Each changed section** is a part of its own, judged with **the frame** of at most 16 KiB: the title, the links,
|
||
and only what the section names (rows of other sections, clauses, the clauses of linked records), with the digest
|
||
of the Context section (the Overview, for a research effort) it is read beside. What does not fit is cut, and the
|
||
question says what was cut. A section is at most 40 KiB, so each question stays under the judgement tool's 60 KiB.
|
||
- **What is judged again.** A section is judged again only when its own text or what it names changes; the Context
|
||
only when it changes. So a usual revision judges only the sections it changed.
|
||
- **At most two judgements of one version run at once.** A revision of eight sections takes a few minutes, and
|
||
about four times the tokens of one whole judgement.
|
||
- **The rules on the whole record** (§ 4) stay code, run at `submit`; no judgement is asked to find a link to nothing.
|
||
|
||
```
|
||
version 3 of research 081
|
||
├ head title, brief, clauses, links ── judged ──▶ approve
|
||
├ Overview unchanged since version 2, same frame ── kept ──▶ approve (version 2's)
|
||
├ Direction changed ── judged ──▶ changes: "D3 contradicts ADR 0290 §7"
|
||
└ Findings changed ── judged ──▶ approve
|
||
version 3 stays proposed, with the findings of Direction
|
||
```
|
||
|
||
**The parts wait on the bus** (ADR 0592 §23). Each part asked of the judgement tool is a key in the state `asked` (the part,
|
||
the tool's ticket, the node, when it was asked), collected again at start, so a restart loses no review. The tool's
|
||
answer comes as the event `judged`, which the claude-code module emits for each ticket and the knowledge base
|
||
consumes; until claude-code emits it, the knowledge base polls the ticket, which is not NATS-native and is tracked by
|
||
issue 1956. The judgement tool is the claude-code module's own tool, not a seat's verb: a seat for judgements (held by the
|
||
mesh's inference layer once one exists) is a note on that issue. A part waiting more than 30 minutes asks the
|
||
operator once through the operator channel, and the ask clears when the part is judged.
|
||
|
||
**A part's verdict** is the event `part-reviewed` and a message on the stream `reviews`: the record, its version, the
|
||
part, the digest judged, the verdict, the findings, who judged and when; the head keeps the latest verdict of each
|
||
part. **`reviewed` keeps its meaning**: one event per version, once every part is judged, carrying each part's
|
||
verdict, so every wait on it keeps working. A part's review is kept for a new version when what it was judged with is
|
||
unchanged, and for a form-only version (§ 2.2); any other part is judged again. **A version is accepted when every
|
||
part's review approves.** On `changes`, the record stays proposed, the findings are kept with that version and the
|
||
part they name, and its author revises it with a new version. A part that cannot be judged (the judgement tool unreachable,
|
||
or its answer unreadable) leaves the version proposed and says which; it is never taken as an approval. When every
|
||
part approves:
|
||
|
||
1. a record that does not need the operator is accepted at once;
|
||
2. a record whose author marked it `needs operator` gets an ask on the router with Approve and Decline, shown on a
|
||
channel that proves who answered (ADR 0274);
|
||
the knowledge base accepts it only on the warrant for Approve, which it keeps with the record.
|
||
|
||
On acceptance the record and its clauses move to `accepted` and `in force`, every clause its `changes` and
|
||
`supersedes` name moves to `changed` or `superseded`, and `accepted` and `changed` events are emitted. Then the 4
|
||
rules that judge the whole record set run (an accepted decision cited by nothing, and the like). A failure does not
|
||
undo the acceptance. It is a fault of the records, which their authors repair, not of the module: it is told to the
|
||
operator once, as a warning naming the rule and the records, kept in the state `findings`, and cleared once the rule
|
||
holds again. The module's health names it and stays healthy, because health says only whether the module works, and
|
||
a finding never holds a rollout at the module's first-node gate (the operator's decision of 2026-10-12 on issue 504,
|
||
as issue 508 decided for a proposal never reviewed).
|
||
|
||
The rule `cited` is also judged ahead, in the review, before the judgement: a decision that names no home and that no
|
||
accepted record links is not accepted. Its review, by the knowledge base itself, asks changes naming the rule (issue
|
||
504). It is not refused at `submit`, because no record can link a number only reserved: a record that cites a new
|
||
decision is proposed after it and accepted, and the new decision is proposed again.
|
||
|
||
An accepted record is changed only by a new record, by a progressive insight (a new version marked as one, which is
|
||
reviewed like a proposal), or by a form-only version of § 2.2, which a check, not a judgement, accepts.
|
||
|
||
## 6. Numbers
|
||
|
||
`reserve` takes a kind and asks the issue tracker for the next number of that sequence (issue 424, ADR 0275 rule 8).
|
||
The number is spent: a record that is never accepted keeps it as `withdrawn`, with who reserved it and when. The
|
||
knowledge base keeps no counter.
|
||
|
||
## 7. Drafting and confirming clauses at the import
|
||
|
||
For a decision whose `Decision` section is prose, the import asks the agent's judgement
|
||
(ADR 0278)
|
||
for its clauses: the section in, numbered statements out, each one sentence, each saying nothing the section does not.
|
||
They are stored `drafted`. A second judgement, in a separate call that sees only the record and the drafts, answers
|
||
per clause whether the record says exactly that; an accepted clause becomes `confirmed`, a rejected one stays
|
||
`drafted` with the reason. Which clause of an older record a `supersedes-in-part` changes is judged and confirmed the
|
||
same way. When every record of a topic has been through both, the operator is told once per topic, with the counts
|
||
confirmed and still drafted. `return` with a record's number and a reason sends it back to be drafted again.
|
||
|
||
**A drafted clause may be changed, and a linked clause keeps its number** (ADR 0321, issue 494). A later record's
|
||
`changes` may name a drafted clause, confirmed or not, as it may one in force or changed; only a superseded or proposed
|
||
clause is refused. On that record's acceptance the drafted clause is marked `changed`, naming the clause that changed
|
||
it, keeps its number and stays `drafted`: it is still never served as in force, and `get` and `ask` say both. Because
|
||
a redraft numbers a record's clauses anew, `return` refuses a record any of whose clauses another record changed or
|
||
links by number, in a version served or proposed, naming each such link; a record that changes the drafted clause is
|
||
the way to correct it. A record no other record links by clause is returned as before.
|
||
|
||
## 8. The import
|
||
|
||
`import` takes a commit of this repository (and `dry-run`) and writes every decision record and research effort
|
||
whole, at its own number, as its first version, naming the commit. It creates what is absent, never overwrites, never
|
||
advances a counter; a second run changes nothing and says so. Records written in this repository after the import,
|
||
while the first slice does not take writes yet, are taken in by running it again.
|
||
|
||
**Refresh.** `import` with `refresh` re-reads, at the commit given, every record whose versions were all written by
|
||
the import, a refresh, or the knowledge base's own drafting and confirming of clauses, with nothing waiting over
|
||
it, and writes the corrected record as a new version naming why; a record anyone else wrote a version of is
|
||
never touched. Clauses already drafted and confirmed are kept when the Decision section's text is unchanged, and
|
||
drafted again when it changed. It repairs what an earlier import misread (issue 487) and is idempotent: a second run changes
|
||
nothing. `dry-run` lists what it would change. Once this repository holds no records, `import` refuses rather than
|
||
reporting nothing created (issue 488).
|
||
|
||
Before the records leave this repository (issue 426), every record is compared with its file at the import's commit,
|
||
field by field and section by section, and the result is written on issue 426.
|
||
|
||
### 8.1 The move off the store
|
||
|
||
The records leave the store once, and the database is dropped only after a check and the operator's yes
|
||
(ADR 0592 §12 to §16; the forms the records are copied into are those of ADR 0597 §12):
|
||
|
||
1. **Order.** The ledger is built first, in the order of ADR 0595 §10: mesh-sdk's typed `requires`, binding and
|
||
package of the new calls; the manifest validator's rules; the bus module's process, verbs and events; the tool
|
||
runner's calls, `apply` among them, with its ledger credential per module assignment (ADR 0597 §9, as its
|
||
progressive insight of 2026-11-03 has it, waiting for the operator's Approve); then mesh-knowledge moves, asking for
|
||
its ledger, states and stream in `requires`. An indexer whose manifest validator predates the new form refuses a manifest
|
||
that uses it, and the placement holds the module off a machine whose tool runner does not read the typed
|
||
binding, so mesh-knowledge cannot be delivered before them. The release sdk1 (issue 1585, ADR 0593 §10), which
|
||
created object buckets and history streams through the grants part, is no longer needed by the move: the
|
||
knowledge base asks for no object bucket and no stream `versions`. The claude-code module's `judged` event is
|
||
delivered beside, and is not needed for the move (§ 5).
|
||
2. **Copy.** The move copies everything the database holds onto the bus, every record, version, clause, link,
|
||
review, finding, ask with its warrant, reservation and told mark: each record's versions as operations on its
|
||
instance in the ledger, in order (a `write-section` for each section a version changed, then its `submit`, then
|
||
the record's review, ask, warrant and acceptance), through `apply`, so each head is derived and never copied; each operation is stamped with the knowledge base's own
|
||
account and keeps the database's author as a separate field marked imported, which `history` shows as the author
|
||
of an imported version;
|
||
each standing finding into `findings`, each told mark as `told.<topic>`. A clause keeps its number, status and source as the database holds
|
||
them (ADR 0321). It emits `moved` per record, writes nothing twice, and a second run changes nothing and says so.
|
||
A dry run lists what it would write and the size each bucket and stream will need, from which the caps are set.
|
||
3. **The window.** From the move's final copy through the check to the switch, every writing verb is refused with
|
||
its reason ("the knowledge base is moving"). Reading verbs answer throughout.
|
||
4. **Check.** A tool compares the database and the bus record by record: for each record the count of each of
|
||
those, the digest of every section of every version, computed from the database's text and read from its
|
||
`write-section` on the bus, that each text hashes to its digest, that each head derived equals the head the
|
||
database holds, and a digest of every review's, finding's and ask's content. It emits
|
||
`checked` with every difference, and the health shows its last result.
|
||
5. **Switch.** Only once the check shows no difference, the module answers from the bus. The switch is a key on the
|
||
bus, so a restart never falls back to the database. A difference is told to the operator, and the module stays on
|
||
the database.
|
||
6. **Rollback.** Until the database is dropped, the module writes each change to the database too, after `apply`
|
||
has taken its operation, so a rollback of the delivery reads a current database. What the database holds is
|
||
kept as a key in the state `findings`, `database.sequence`: the last history sequence written to it. At start,
|
||
and after a write the database refused, the module catches the database up from the history from that sequence
|
||
on, so a restart between `apply` and the database write loses nothing. A database still behind after three tries
|
||
raises the condition `database-behind`, naming each record it lacks and saying that a rollback now would lose
|
||
them, and never answers the author that the write was refused; the module's health is unhealthy while it stands,
|
||
the drop (step 8) is refused while it stands, and the catch-up tool copies the records again from the ledger and
|
||
clears it. A rollback is a person's act, and the condition is what tells them it is unsafe. **After a rollback**,
|
||
the older module wrote to the database alone, and not only versions: acceptances, verdicts, asks, warrants,
|
||
reservations and changed clauses too. So until the drop, every start of the module refuses every writing verb
|
||
and runs the check of step 4 before it serves writes; a difference it finds is copied from the database onto the
|
||
ledger as operations, and the check runs again, so writes are served only once it is clean. A record changed on
|
||
both sides (an operation the database never took, and a change the older module made) never checks clean: it is
|
||
told to the operator at once, naming the record and both changes, so the refused writes read as a decision
|
||
waiting and not as a stall. A rollback is safe
|
||
only until the drop. This settles the rollback ADR 0597 §13 left to the design.
|
||
7. **Tell and ask.** Once the check is clean, the operator is told its result and asked, once, whether the database
|
||
may be dropped, because dropping it removes data.
|
||
8. **Drop.** On the operator's yes, the delivery after it removes the module's requirement of a database, and the
|
||
database is dropped by the store's module, through its tool for it, which is built there first if it has none.
|
||
9. **Titles.** The move's tool then writes the form-only versions of § 2.2, one per record with file-named sections.
|
||
|
||
## 9. The slices after the first
|
||
|
||
| Slice | Delivers | Done when the operator sees | Tracked by |
|
||
|---|---|---|---|
|
||
| 1 | this document: the module, the import, clauses, answers, `propose`, its own review and acceptance | the acceptance sentence above, live, and a record proposed, reviewed and accepted without a pull request | issue 425 |
|
||
| 2 | the decision records and research efforts leave this repository; path mentions become "ADR NNNN" and "research NNN"; playbooks 01 and 02 changed | this repository holds no decision record, and `get` answers every one | issue 426 |
|
||
| 3 | designs and the glossary's entries as records, moved in one delivery, and each design's state worked out by the knowledge base (§ 9.1 to § 9.3; ADR 0423, ADR 0424) | `get` answers design 47 with its sections and links, a word's entry answers from the knowledge base, and a design's state follows its issues' deliveries without anyone writing it | issue 428 |
|
||
| 4 | meeting notes, drawings and blog posts | not decided; needs its own decision | issue 429 |
|
||
| 5 | the records on the bus, written and reviewed by section, the move off the store and the titles (§ 1, § 2, § 4, § 5, § 8.1; ADR 0592), kept as the first ledger (ADR 0597), delivered after the ledger's build (ADR 0595 §10), then mesh-knowledge, with claude-code's `judged` event beside | the acceptance tests of the fifth slice in § 10, live; the knowledge base requires no database | the issues its hand-off opens (playbook 04) |
|
||
|
||
Numbers from the issue tracker, which `reserve` needs, are the tracker's own slice, tracked by issue 424. This
|
||
repository keeps no copy of the records, generated or otherwise (issue 435, answered by the operator). Playbooks
|
||
stay in this repository as files: they are how work is done here, not records of what was decided (research 061).
|
||
|
||
### 9.1 Designs and glossary entries as records
|
||
|
||
**A design** is a record of the kind `design`, named "design NN" and keeping its number (ADR 0423). Its text is its
|
||
sections: the `to-be` section, what is being built, and the `as-is` section, what runs. Each of the as-is documents
|
||
becomes the as-is section of the design it describes, never a record of its own: the import matches 3 of the 18 by
|
||
name and 15 by topic, and shows the operator the list before it runs. Its owning repositories are its field `code`;
|
||
its decisions, and every design it names, are `cites` links. It holds no state written by anyone (§ 9.2). A new
|
||
design takes its number from `reserve` and is written with `propose`, and is reviewed as every record is (§ 5).
|
||
|
||
**A glossary entry** is a record of the kind `glossary entry`, one per entry of the glossary page, kept whole: its
|
||
head word or words (an entry may name several with one meaning, as research effort, graduation, hand-off and playbook
|
||
do), its domain, its meaning, its *Not:* line with each retired word's scope, and its identifier line. Each row of
|
||
the page's homonym table becomes an entry of its own, naming the qualified form each domain uses. The entries replace
|
||
the page as the authority on words (ADR 0423, changing ADR 0244).
|
||
|
||
**The readers change with them.** Everything that read the page or the design folders reads the records instead:
|
||
|
||
| Reader | Reads, after the move |
|
||
|---|---|
|
||
| the knowledge base's own rule on a retired word (§ 4) | the *Not:* and identifier lines of the entries, no longer the page through the records module; it judges a design when it is proposed, as it judges a decision |
|
||
| hq's word check | the entries' *Not:* and identifier lines, and its uniqueness check (a head word heading two entries, or also retired) over the entries; it covers what stays in this repository, and designs leave its coverage |
|
||
| the catalog's repository check | the retired words of no scope or *(tools)* from the entries; its copied list is retired, so hq has no copy to compare |
|
||
| hq's cycle check | the design records, for every design naming its decisions, not files under `03-DESIGN/` |
|
||
|
||
Each of the four fails, saying so, when the knowledge base does not answer, and never passes on nothing.
|
||
|
||
**Links become links between records, and the old paths go.** At the import every file link inside a design becomes
|
||
a link between records, which the rule on a link to nothing then checks (§ 4). The links from documents that stay in
|
||
this repository are rewritten to name the design ("design 47"). No page stays at an old path: afterwards this
|
||
repository holds no file under `03-DESIGN/` and no `00-META/glossary.md`.
|
||
|
||
**It moves in one delivery**, as the records did: the import, the two kinds, the four readers, the rewritten links,
|
||
the playbooks' steps that write a design, and the instruction text sessions read, which names the glossary's place.
|
||
A reader left behind would pass on nothing, so none moves alone.
|
||
|
||
### 9.2 A design's state
|
||
|
||
**The knowledge base says a design's state, and nobody writes it** (ADR 0424): proposed, designed, in progress or
|
||
implemented, kept matching what runs. No person, session or document sets it, and `propose` refuses a design that
|
||
carries one.
|
||
|
||
It reads two things. The issues are those the issue tracker holds with a `design` link to the design. Whether one
|
||
is done comes from its deliveries: an issue is done when it is resolved and the delivery its fix went out in reached
|
||
`delivered`, whether a hotfix alone or a delivery group. The delivery module announces each delivery done on the
|
||
bus, and on each announcement the knowledge base works the state of every design that issue links out again.
|
||
|
||
```
|
||
issue tracker ── issues with a design link ──┐
|
||
├──▶ knowledge base ── works out ──▶ the design's state
|
||
mesh-delivery ── "delivery done", bus ───────┘ (served by get, ask)
|
||
```
|
||
|
||
**The rules.**
|
||
|
||
| Case | State |
|
||
|---|---|
|
||
| a decision the design names is not accepted | proposed |
|
||
| no linked issue done, or no linked issue at all | designed |
|
||
| some linked issues done | in progress |
|
||
| every linked issue done | implemented |
|
||
|
||
Three kinds of issue count apart: an issue closed won't fix is left out; an issue resolved with nothing to deliver,
|
||
a fix of documents only, is done when resolved; and a new issue linked to an implemented design makes it in progress
|
||
again, until that issue is done. Milestones are not read: a milestone is a group of a design's issues delivered
|
||
together, and the state depends only on the issues and their deliveries.
|
||
|
||
**Imported designs say what they lack.** A design imported with no linked issue shows `no issues linked yet` beside
|
||
designed, until an issue is linked to it; the import names each such design by number. Linking their issues is
|
||
tracked by issue 428.
|
||
|
||
### 9.3 Its place beside design 47
|
||
|
||
The delivery-done announcement this slice reads is design 47's
|
||
([47 — Delivery](47-delivery-from-commit-to-delivered.md)): its hotfixes and delivery groups, and each delivery's
|
||
end at `delivered`. This slice is an extension after design 47's last milestone. It changes none of design 47's
|
||
milestones and nothing of how a delivery runs; it only listens for the announcement.
|
||
|
||
## 10. How it is checked
|
||
|
||
| Rule | Checked by |
|
||
|---|---|
|
||
| A proposal that breaks a per-record rule is refused, naming every reason | the module's table test, one case per rule of § 4 |
|
||
| A record is accepted only after the knowledge base's own judgement approves it, and, when it needs the operator, only on the warrant | the module's tests: a proposal whose judgement answers changes, or cannot be had, stays proposed; a `needs operator` record unaccepted without the warrant, accepted with it |
|
||
| A decision is not accepted cited by nothing | the module's test: a decision with no home and no record linking it gets changes from the review, with no judgement asked; with a home, or once a record citing it is accepted, it is accepted |
|
||
| A whole-set rule that fails is loud, and leaves the module healthy | the module's test: a correction that leaves a decision cited by nothing tells the operator once, as a warning naming the rule and the record, not again after a restart, and clears it once a record cites it; the module's health stays healthy throughout |
|
||
| Every version is kept and comparable | the module's test: three versions, `history` lists them, the difference of the first and third is exact |
|
||
| The import changes nothing on a second run, and loses nothing | the module's test over a fixture repository; and the comparison of § 8 on issue 426 |
|
||
| A drafted clause is never served as in force | the module's test: `holds` over a record with only drafted clauses answers none, and `ask` marks them |
|
||
| A drafted clause may be changed, and a linked clause is never renumbered | the module's tests: a record changing a drafted clause is accepted, and the clause is then `changed`, keeps its number, stays drafted and is not served; `return` of a record whose clause another record changed or links by number is refused naming the link, and writes nothing |
|
||
| An answer stays within its bound | the module's test over the full import of `main` at a recorded commit: every `ask`, `get` and `holds` of a fixed question list |
|
||
| A record written in this repository meanwhile writes its clauses | `records.py`, check `clauses`, on every hq pull request, until the records left this repository (issue 426); since then `records.py`, check `no-records`, refuses any record written here |
|
||
| Live | the acceptance sentence, asked from a session outside this repository |
|
||
| A record is kept as a ledger instance, a section's text once in its operation, and read by no other module | one integration test that starts the module whole against a real bus server: a record of three sections and a second version changing one give one head, two `submit` operations and four `write-section` operations, the changed section's text found only in its operation; another module's account reading the ledger's history, snapshot or state, the head among them, is refused (ADR 0597 How it is checked, clauses 9, 11, 12) |
|
||
| Search answers from the index as it did from the store | a unit test over a fixed set of records and a fixed question list; the integration test restarts the module and asks again |
|
||
| A draft is written by section and has one author, and a take-over tells the previous one | unit tests of each verb of § 4, of a refusal naming the author, and of `take-over` emitting `taken-over`; a take-over refused while the operator's Approve is waited for |
|
||
| A ledger that keeps its history | in the integration test: the history at its cap refuses a new operation and keeps its oldest; a draft's written section is in the history before `submit` and named by no version after `drop`; a section title over 200 bytes is refused |
|
||
| A long record is judged whole, one part at a time | unit tests: the frame never passes 16 KiB and says what it cut, with twenty clauses of 2000 bytes and a 40 KiB Context; every question stays under 60 KiB with a 40 KiB section and that frame, and the head part with 40 KiB of clauses; a section over 40 KiB is refused saying split it; an unchanged section keeps its review, a changed frame asks it again |
|
||
|
||
**The fifth slice's tests, one per failure path** (ADR 0592; the review by architectural domain's testing ruling). Unit tests are
|
||
table-driven; one integration test starts the module whole against the real bus server. The module's count today is
|
||
1 integration and 104 unit tests; these add about 20 table cases and stay within the budget of 50 and 500.
|
||
|
||
| Failure path | Test |
|
||
|---|---|
|
||
| two writes race on one draft | unit: the second compare-and-set loses, is retried, and is refused with the reason past its tries |
|
||
| `submit` races `take-over` | unit: one wins; the other is refused naming the new author or the new version |
|
||
| two reservations race | unit: two numbers, or one refused; never one number twice |
|
||
| a write cut between the history and the head | the ledger's integration test (design 25 § 12.7): the call answered that the operation is taken; the next `apply` derives the head. The module's own integration test: stopped after `apply`, restarted, it sends the event once |
|
||
| a failure before the operation is appended | unit: the call is refused, and no head, event or version follows later |
|
||
| a change through the bus during the move | unit: read back from the database, so a rollback of the delivery reads a current database (ADR 0592 §14) |
|
||
| a section changed after the operator's Approve | unit: the record is asked again; a version with every section unchanged is not (ADR 0592 §21) |
|
||
| a head behind its history | unit: health unhealthy naming the lag; the ledger's `rebuild` clears it |
|
||
| a text does not hash to its digest | unit: `apply` refuses the `write-section`, and a read refuses it, naming the digest |
|
||
| a full ledger state | integration: `submit` answers taken with the head behind; health unhealthy naming the cap |
|
||
| a full ledger history | integration: `submit` refused with the head unchanged |
|
||
| a judgement timeout for one part | unit: that part stays asked and the version proposed, saying which; the others keep their verdicts |
|
||
| a restart with parts asked | integration: the parts in `asked` are collected again and judged |
|
||
| `reviewed` once per version | unit: one `reviewed` after the last `part-reviewed`, carrying every verdict |
|
||
| told once | unit: a whole-set finding told once across a restart, again only after its mark is cleared |
|
||
| a second run of the move | unit: changes nothing and says so |
|
||
| the move's check | unit: a changed review, a missing finding and a missing ask, each named |
|
||
| writes during the switch | unit: every writing verb refused with its reason; reading verbs answer |
|
||
| an older manifest validator | the manifest validator's test (ADR 0595 §8): a manifest asking for a ledger in `requires` refused by a manifest validator that does not know the template, accepted by one that does |
|
||
| the bus module's forms | the bus module's test (design 25 § 12), against a real bus server: the ledger, states and stream created for their module, `reviews` heard by a module granted it in `readers` and by no other; the condition at 75 percent raised and cleared below |
|
||
| a reference | unit: "record › title › row" resolves to the section; a nested title is refused |
|
||
| a form-only version | unit: accepted when only names and links changed and each target resolves; refused otherwise |
|
||
| an unproven caller | unit: `open`, `write`, `submit`, `propose` and `take-over` refuse it |
|
||
| the index behind | unit: health unhealthy while the index's sequence is behind the ledger's state; `ask` refuses "index not built" |
|
||
| a forward delivery after a rollback | unit: an acceptance and a verdict made by the older module are found by the check at start, the writing verbs refused meanwhile, the changes copied and checked, then writes served; a record changed on both sides is told to the operator |
|
||
| a restart between `apply` and the database write | unit: the module is stopped after `apply` and before the database write, restarted, and the database matches the history; health showed it behind meanwhile |
|
||
| the database refuses past its tries | unit: `database-behind` names the record; the drop is refused while it stands; the catch-up tool clears it |
|
||
| a restart between `apply` and its event | unit: the module is stopped after `apply` of a `review`, restarted, and sends one `reviewed`; a second start sends none |
|
||
| the move as operations | unit: each record's versions copied as `write-section` and `submit` operations in order; the derived head equals the database's; a second run appends nothing |
|
||
| the start | integration: the time to a built index measured and reported, failing above 40 seconds, the estimate's top |
|
||
| A section is a part with a title | a table test, one case per refused name and text of § 2.2; a form-only version whose text changed beyond its links is refused |
|
||
| Every bucket has a tool, and health says the index | the manifest test compares tools and events with the code; a unit test of the health before and after the index is built |
|
||
|
||
**The third slice's acceptance tests** (§ 9.1 to § 9.3; research 062's direction), what its build proves before it
|
||
is done:
|
||
|
||
1. After the import, `knowledge-base.get` of design 47 returns its sections and its links, and every link from a
|
||
design resolves to a record: none is refused by the rule on a link to nothing.
|
||
2. This repository's main holds no file under `03-DESIGN/` and no `00-META/glossary.md`, and its link check passes
|
||
with the 76 links from documents that stay here rewritten.
|
||
3. hq's cycle check and word check read the knowledge base, and fail, saying so, when it does not answer.
|
||
4. A proposal holding a retired word is refused after the move, the word read from the entries; the entries are
|
||
175 and hold 183 head words and 29 retired words, 0 unparsed, both counts checked.
|
||
5. In the module's tests, each state rule of § 9.2 gives its state from fixture issues; live, an issue linked to a
|
||
design whose hotfix is delivered turns the design implemented within a minute of the delivery being done, and
|
||
a new issue linked to it turns it in progress.
|
||
6. The import reports every design with no linked issue as `no issues linked yet`, by number.
|
||
7. The instruction text sessions read names the glossary's new place.
|
||
8. Every entry of the glossary's Config section is filed under the Config domain, and the domains the entries name
|
||
are the twelve of ADR 0354.
|
||
9. Tests 1 to 8 pass together after the one delivery, run against main and the live knowledge base, with nothing
|
||
in this repository, the catalog or the instruction text pointing at a removed path.
|
||
|
||
**The fifth slice's acceptance tests** (§ 1, § 2, § 4, § 5, § 8.1; ADR 0592), what its build proves before it is
|
||
done:
|
||
|
||
1. The move's check, run live, names no difference between the database and the bus: 656 decision records and 80
|
||
research efforts (the counts of 2026-11-02, or the counts on the day), every version, clause and link, and the
|
||
digest of every section of every version.
|
||
2. The operator is told that result and asked before the database is dropped; after the yes and the delivery, the
|
||
module's manifest requires no database and the store holds none for it.
|
||
3. A session writes a research effort of more than 100 KiB one section at a time from one node; a session on another
|
||
node takes the draft over with a reason, the first session hears `taken-over`, and the second submits it.
|
||
4. Every changed section of that effort is judged on its own, each question under 60 KiB, and the effort is
|
||
accepted once every part approves.
|
||
5. A section named like a file, a text holding a local path, and a section over 40 KiB are each refused, the last
|
||
saying split it.
|
||
6. After the titles' form-only versions, no record holds a section named like a file, `history` shows each as a
|
||
change of form, and `get` of "research 062 › Direction" answers that section.
|
||
7. The fill tool shows each bucket and stream against its cap; the second version of a record with one changed
|
||
section adds one `write-section` and one `submit`, not one operation per section.
|
||
8. During the move's window a `write` is refused saying the knowledge base is moving; after the switch a restart
|
||
still serves from the bus; the health names the source and the check's result.
|
||
9. A part's review waiting on the judgement tool survives a restart of the module, and one past 30 minutes reaches the
|
||
operator once.
|
||
10. Every test of the table above passes in the one check of the pull requests, within the test budget.
|
||
11. As a ledger (ADR 0597 How it is checked, clauses 11 and 12): `get` answers the same digest for every record
|
||
before and after the move; `ask` answers from bodies read from their operations; `mesh-knowledge.reviewed` is
|
||
emitted once per review; the module's manifest asks for no stream `versions`, no object bucket `sections` and
|
||
no state `names`, and the bus holds none for it once the move's check is clean; its tools and health name the
|
||
ledger's repairs and lag, and no digest store; the consumers of `reviews` still hear it.
|
||
|
||
## 11. The overview page
|
||
|
||
**The knowledge base serves one read-only web page for the operator** (ADR 0616 §1), so the state of the work is one
|
||
address away rather than an answer read in chat. It shows three blocks: every design in progress with its milestones
|
||
and their issues (the tree the `progress` verb answers); the decisions and research efforts accepted in the last seven
|
||
days and those waiting (proposed, or waiting for the operator's Approve); and what waits on the operator: records
|
||
waiting for an Approve, the operator channel's open asks and the delivery groups waiting for an Approve. The seven days
|
||
are counted from the ledger's dates when the page or its tool answers, never kept as a window in the model. What
|
||
reached which nodes is not on it: a merged group no longer waits on the operator.
|
||
|
||
```
|
||
mesh-knowledge's process
|
||
├ its own ledger records, their status and dates (no first view needed)
|
||
├ issue tracker first view: milestones, list then its events
|
||
├ seat mesh-delivery first view: groups then group, transition, merged
|
||
├ seat operator-channel first view: asks then the router's offered, closed
|
||
│ (a restricted stream granted to the knowledge base alone)
|
||
▼
|
||
the page's model, in memory ──▶ the page (GET only) ──▶ route proxy ──▶ the operator
|
||
└▶ its tool (the model as data)
|
||
```
|
||
|
||
- **Built from mesh paths alone** (ADR 0616 §2). Besides its own ledger, the model comes from three other modules, each through
|
||
a verb for the first view and events after it: the issue tracker's `milestones` and `list` and its events; the seat
|
||
`mesh-delivery`'s `groups` and its `group`, `transition` and `merged` events, a group leaving the block on `merged`;
|
||
and the seat `operator-channel`'s `asks` and the router's events `offered` and `closed`, an ask entering the block on
|
||
`offered` and leaving it on `closed`. It never hears an asker's `decided` family. It reads no other module's bus
|
||
state (ADR 0596 §2), and its manifest holds no `reads` entry, which the manifest validator refuses (ADR 0595 §8).
|
||
- **The router says when an ask starts and ends** (ADR 0616 §7). The router holding `operator-channel` emits `offered` when it
|
||
offers an ask on a channel, and `closed` once for every end of an ask: answered, expired, cancelled by its asker,
|
||
replaced by a newer ask about the same subject, or ended by the router itself on an `unlink` or `allow-link`. Each
|
||
carries the ask's id, asker, headline and the channels it was offered on, and `closed` how it ended; never an option,
|
||
a token or a warrant's proofs, so neither says more than `asks` already answers. Both go on a restricted stream of
|
||
the router (ADR 0363 §4), heard only by a module the router's trusted config value `readers` grants, which names the
|
||
knowledge base alone; `decided` stays read by its asker only. The stream is of the template events: kept seven
|
||
days, capped at 64 MiB, dropping its oldest when full, so a page down longer than a week rebuilds from `asks`.
|
||
- **Current on events, never polled** (ADR 0616 §3). Each source's block is built once at start from its verb, its first view,
|
||
and then kept in memory from that source's events. A verb is asked again only for a source marked unanswered.
|
||
- **A source that does not answer says so, never shows as empty** (ADR 0616 §6). A source is marked unanswered for one of two
|
||
causes, named in the mark: its verb did not answer within its bound, or its subscription missed the bus's idle
|
||
heartbeat past its bound, so a lost subscription or a silent source is found, not taken for a quiet one. Its block,
|
||
on the page and in the tool's answer, then says so with the time of its last answer (the verb's last answer or the
|
||
subscription's last event or heartbeat, whichever is later). A mark from the verb: the verb is asked again on a
|
||
bounded backoff (from 10 seconds, doubling, at most every 5 minutes), and its first answer rebuilds the block and
|
||
clears the mark. A mark from the subscription: nothing is asked while it is silent; its next event or heartbeat
|
||
makes the module ask the verb once, to rebuild the block with what it missed, and that answer clears the mark (an
|
||
unanswered verb then turns the mark into one from the verb). These are the only asks the page makes after start.
|
||
- **It writes nothing** (ADR 0616 §4). The page has no form and no verb behind it and answers GET only. It is served by the
|
||
module's own process on a port the module declares, reached through the route proxy by a route the module
|
||
requires, which only the operator may open. The port listens `from: machine`, the narrowest listening scope the
|
||
manifest has today, so a connection from another node is refused. That scope does not name a module: every local
|
||
process of the knowledge base's node reaches the port, not only the route proxy, until issue 1968 gives a scope
|
||
that grants one module's process. That scope is a change to mesh-sdk's manifest types, so it rebuilds every module
|
||
that imports them, and it rides a later milestone's one rebuild rather than adding one here. A route proxy runs on
|
||
the knowledge base's node (read from placement, 2026-11-04), so the page is reachable through it; a route proxy on
|
||
another node cannot reach a port listening `from: machine`, so a page placed where none runs is unreachable until
|
||
issue 1968.
|
||
- **Every number on it can be read by a tool** (ADR 0616 §5): a tool of the knowledge base answers the page's model as data,
|
||
marked reads, so the page shows nothing a tool cannot read (tools-are-how-a-module-is-spoken-to); a second tool,
|
||
marked acts, asks one source's verb again by hand and rebuilds its block, recorded as a hand act.
|
||
- **Health.** The module's health carries the page's last rebuild and each source's last answer, and is degraded while
|
||
any source is unanswered.
|
||
- **Built after the ledger store**: the page reads the records from the ledger (§ 2.1), so it is built after the
|
||
knowledge base's ledger store, in the same milestone (ADR 0613 §1).
|
||
|
||
How it is checked (ADR 0616 *How it is checked*): a unit test builds the model from fixture issues, milestones,
|
||
records, groups and asks and sees the three blocks; a fixture `group` or `transition` event changes the delivery block
|
||
and `merged` takes the group out; `offered` adds an ask and `closed` takes it out; no verb is asked again in either
|
||
case; a record accepted eight days before the answer's time is not in the seven-day block, with no event between. The
|
||
manifest has no `reads` entry, names `groups` and `asks` among what it invokes, and consumes no `decided` family. The
|
||
handler refuses any method but GET, and the route's grant names only the operator. The tool's answer equals the model
|
||
the page renders. For each source, a verb failing at start marks it unanswered from the verb on the page, in the tool
|
||
and in the health, never as an empty list, asked again on the backoff alone, its first answer clearing every mark;
|
||
and a subscription stopping its heartbeat marks it unanswered from the subscription, asks nothing while silent, and
|
||
asks the verb once on its next event or heartbeat. In the router, an ask offered emits `offered` once and each of its
|
||
five ends emits `closed` once with how it ended, with no option, token or proof in either body; the knowledge base
|
||
hears the stream and another module, an asker among them, is refused. A connection to the page's port from another node
|
||
is refused (what `from: machine` gives; a local process other than the route proxy is not refused before issue 1968). The re-read tool rebuilds one source's block and asks no other. Live: after its delivery the operator opens the
|
||
page and sees design 47's milestones, rendered headless and looked at before it is handed over.
|
||
|
||
## What it leaves out
|
||
|
||
Semantic or vector search; a browser view other than the overview page of § 11 (its reading of the buckets is
|
||
announced, ADR 0592); line comments on a proposal (the judgement's findings name the section and clause instead),
|
||
and any form or writing from the overview page; and the rules of how-we-build, which are not decision records. Each
|
||
needs a decision of its own.
|
||
|
||
## Reviewed by architectural domain
|
||
|
||
The fifth slice was reviewed by architectural domain on 2026-11-02 (four reviewers, two architectural domains each; the knowledge base's own
|
||
review of ADR 0592's fourth version beside), and the lead ruled on every finding. What was found, and what answers it:
|
||
|
||
| Architectural domain | Found | Answered by |
|
||
|---|---|---|
|
||
| security | unproven callers could write or take over; an Approve did not bind the sections shown; readers were named outside ADR 0363's grant (the knowledge base's review of version 6); a proposal waiting on the operator could be taken over; readers' grants and a body's match with its name were unsaid; a draft had no bound | ADR 0592 §4, §8, §9, §17, §19, §20, §21; § 2.1, § 4 |
|
||
| seams | asked parts lived only in memory; told marks and reservations had no form on the bus; the judgement tool's ticket is polled; who creates buckets and grants was unsaid; the judgement tool is a module's tool, not a seat | ADR 0592 §2, §7, §16, §23; § 1, § 5 (a seat for judgements a note on issue 1956), § 8.1 |
|
||
| running qualities | three writes could stop halfway; caps had no figures; a usual revision judged every section again, with no limit on parallel calls; start time unknown | ADR 0592 §10, §22, §25; § 1, § 2.1 (caps), § 5 |
|
||
| health | a stale index, a missing body, a full bucket and the move's state were not visible; waiting reviews and idle drafts were not counted | ADR 0592 §25, §33; § 1.1 |
|
||
| events and logs | per-part verdicts would have broken every wait on `reviewed`; events did not say what they touched; a take-over's reason and each section's author were lost after 30 days | ADR 0592 §3, §27, §34; § 1.1 (the events table) |
|
||
| testing | each failure path lacked a test; the budget was not counted | ADR 0592's How it is checked; § 10 (the failure-path table) |
|
||
| upgrade | writes during the switch, a rollback after it, and the order of the three deliveries were unsaid; the form-only check did not prove new link targets | ADR 0592 §13 to §16, §31; § 8.1, § 2.2 |
|
||
| tools | unnamed objects, missing bodies, form-only versions, asked parts and told marks had no tool | ADR 0592 §32; § 1.1 (the tools table) |
|
||
|
||
The knowledge base's review of the fourth version found that the reference form read as nested sections: ADR 0592
|
||
§30 and § 2.2 say sections never nest.
|
||
|
||
### The amendment of 2026-11-03
|
||
|
||
The amendment of 2026-11-03 to ADR 0595, ADR 0596 and ADR 0597 (designs 25 § 12, 32 § 4 and 55 together) was
|
||
reviewed by the four reviewers by architectural domain side by side (playbook 01), over three rounds, and the lead
|
||
ruled on every finding. What was found, and what answers it:
|
||
|
||
| Domain | Found | Answered by |
|
||
|---|---|---|
|
||
| security | the author could be words the module chose; a person's dangerous tools had no role, mark or path to the process; the caller travelled as a plain field | design 25 § 12.3 (marks, the process's own tool subject, the identity seat's signed token), § 12.4 (the tool runner stamps the caller it proved; the move's authors marked imported) |
|
||
| seams | the bus module asked for its own events in the new form, which it would have to create itself (ADR 0595 §10); a person's tool had no join to the process; a verdict was written twice with no order | design 25 § 12.3 (its events on its old `streams` section; the process's own tool subject); design 55 § 2.1 (the `review` operation first, `reviews` caught up from it) |
|
||
| running qualities | overdue creation was undefined and raised by nobody; the database's rollback write lived in memory; a forward delivery after a rollback could miss acceptances and verdicts; no size estimate of the heads | design 25 § 12.2 (five minutes, the watchman, durable consumers, `check` at start); design 55 § 8.1 step 6 (`database.sequence`, the check at every start before the drop), § 2.1 (the heads' estimate) |
|
||
| health | the bus module's health would have fired on a quiet mesh; conditions had no clearing; `database-behind` had no clearing | design 25 § 12.2 and § 12.3 (each condition with what clears it); design 55 § 8.1 step 6 |
|
||
| events and logs | an event lost when the module stopped after `apply`; the bus module's events had no reader | design 55 § 1 (each event sent with its operation's sequence as id, the state `sent`); design 25 § 12.3 (`history` of one entry) |
|
||
| testing | the bus module had no test that starts it whole; live tests would have filled the live bus; the budget was not counted | design 25 § 12.7 (the nats module's integration test, live drift only by a manifest change, the budget paragraph); design 55 § 10 |
|
||
| upgrade | the build order lacked the grants part's binding and two undo steps | design 25 § 12.6 |
|
||
| tools | the ledger's repairs had no tool for the next owner; the bus module's events had no read tool | design 25 § 12.5 (served for every ledger owner), § 12.3 |
|
||
|
||
**Left to the operator**, because each changes an accepted record: a margin between raising and clearing the
|
||
condition `full` (ADR 0595 §6 raises and clears it at 75 percent, so an entry sitting there flaps), and an event of
|
||
its own for `drop` and `recreate`. **A correction of fact** for ADR 0595 §4: the bus module deletes through `recreate`
|
||
as well as `drop`. Each is noted on issue 1966.
|