Files
hq/03-DESIGN/01-to-be/55-the-knowledge-base.md
T
jschoubben aac8494ca3 Say manifest validator, not judge: the operator asked why a new word was needed for the indexer's rules
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
2026-11-04 23:32:13 +01:00

907 lines
78 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
---
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.