novox/hq
13
0
Fork 0
Code Issues Pull Requests 1 Releases Wiki Activity

Merge pull request 'Design 47: the six releases of ADR 0429 as milestones; glossary: the delivery domain, its parts and their words' (#423) from docs/design-47-delivery-releases into main

Browse Source
This commit was merged in pull request #423.
This commit is contained in:
mesh-tools
2026-10-18 15:50:42 +00:00
parent ba127e29b7 cd9336d05a
commit 0f8d778ec2
4 changed files with 143 additions and 38 deletions
Download Patch File Download Diff File Expand all files Collapse all files
00-META/glossary.md
+65 -28
View File
@@ -227,7 +227,7 @@ every other domain has something to run on. **Recorded by** the controller and t
the two and raises `mirror-drifted` on any difference
(ADR 0289, ADR 0356). Builds, rollouts and assignments are no mirrors: they are
the chain, kept on the bus as their only source (ADR 0408). Shortened to *mirror* where the
text is about the controller's records; the builder's *mirrored* `upstream` image (Change and delivery) is
text is about the controller's records; the builder's *mirrored* `upstream` image (Delivery) is
a different thing, a copy of an outside image in the artifact store.
## Placement — what runs on which node
@@ -343,7 +343,7 @@ and vault (Identity and access).
**Purpose.** To issue, hold, rotate and check the credentials and grants by which modules, nodes, agents
and the operator act. **Recorded by** the controller's `identity` and `licences` databases and the vault.
**Upstream of** Provisioning, Change and delivery, and Operator and conversation.
**Upstream of** Provisioning, Delivery, and Operator and conversation.
**Decided by** ADR 0085, 0113, 0183, 0225, 0234, 0386, 0387, 0388, 0411, 0413, 0414.
**Uses:** module, node, seat, tool (Module), operator, consumer and provision (Provisioning), agent and ask (Operator and conversation).
@@ -397,12 +397,13 @@ and the operator act. **Recorded by** the controller's `identity` and `licences`
agent can run as that account: the control-node, and a node whose agents run under an account of their own
(ADR 0272).
## Change and delivery — a commit on its way to the nodes
## Delivery — a commit on its way to the nodes
**Purpose.** To take one commit from its pull request to every node that should run it, and to put it
back when it fails. **Recorded by** the `mesh-delivery` module (deliveries) and the controller (the
planner, the rollout). **Downstream of** Module, Core, Health and repair and Data.
**Decided by** ADR 0162, 0218, 0236, 0237, 0238, 0239, 0250, 0267, 0270, 0276, 0323, 0401–0408.
back when it fails. The domain is continuous integration and delivery, named **delivery**, and its parts live in
the repository `mesh-delivery` (ADR 0429 §2). **Recorded by** the `mesh-delivery` module (deliveries) and the
controller (the planner, the rollout) until release 6 of ADR 0429; from each release on, by the parts it builds. **Downstream of** Module, Core, Health and repair and Data.
**Decided by** ADR 0162, 0218, 0236, 0237, 0238, 0239, 0250, 0267, 0270, 0276, 0323, 0401–0408, 0428, 0429.
**Uses:** module, node, declaration and send (Placement), health (Health and repair), person.
- **merge check** — the two statuses a pull request carries before it may merge: the **merge gate**
@@ -473,24 +474,58 @@ planner, the rollout). **Downstream of** Module, Core, Health and repair and Dat
- **delivery plan** — what a delivery does to the mesh: its **build plan** (the modules it moves and
their dependents, in tiers), its **deploy plan** (per node, what it receives and what waits for a
person) and its verdict (the composed nodes, the replays). Computed by the controller's planner from a
diffset; the controller's verb `delivery-plan` shows it. *Deploy* is used in this one place.
diffset; the controller's verb `delivery-plan` shows it. *Deploy* is used in this one place. Deleted at
release 6 of ADR 0429 (§8): the word stays in use until that release is delivered, and then retires.
*Not:* ~~change plan~~, ~~release plan~~
- **merge window** — the rolling wait in which the controller collects merges before it plans them: each
merge restarts it, and it closes when none arrived for its length (90 seconds by default) or at the latest
10 minutes after its first merge (ADR 0276). Kept as two keys with a time to live on the bus; the first to
expire closes the batch (ADR 0407).
expire closes the batch (ADR 0407). Goes at release 6 of ADR 0429, when nothing collects merges (§12).
- **batch** — the merges one merge window collected, planned once as one rollout. For a repository merged more
than once in it, the rollout takes the latest commit, and the earlier merges are answered by it. Not *group*,
which is a delivery group.
- **mesh-delivery** — the module that owns deliveries and delivery groups, holding the mesh-scoped seat
of the same name. It records and decides; the controller sends, judges and rolls back when it is asked.
which is a delivery group. Goes at release 6 of ADR 0429 (§11, §12).
- **mesh-delivery** — the repository of the delivery domain, holding its parts as modules prefixed
`mesh-delivery-` (ADR 0429 §2), made by the forge module from its config (ADR 0428). Until release 3 of
ADR 0429 also the module in the catalogue that owns deliveries and delivery groups, holding the mesh-scoped
seat of the same name: it records and decides, and the controller sends, judges and rolls back when it is
asked. Release 3 splits that module into the parts, and then the name means the repository alone.
- **part** — one independent process of the delivery domain with its own bus credential, which watches keys
and writes keys and never calls another part (ADR 0429 §1). Each key has one writer; the operator's
credential may also write a want, the one manual escape. The parts: the **forge bridge** (forge events in,
the only caller of the forge), the **indexer** (fingerprints, the candidates of a group, the modules of the
trunk), the **builder** (claims and builds one fingerprint once), the **checker** (the merge check on built
artifacts), the **gate** (merges a group and moves the source revision; *gate part* where it could be read
as another gate, see [Homonyms](#homonyms)), the **teller** (the operator's phone, and the only writer of an
ask's answer), the **assigner** (writes each node's wants by its six rules), the **node agent** (the
node-engine's own process, applying its wants), the **watchman** (presence and pulses) and the **status
view** (`mesh-delivery-cli` and a web view, writing only its answers to asks). The reviewer is the review
agent's session, not a part. Built over releases 1 to 6 of ADR 0429.
- **fingerprint** — what identifies a module's build by its content: a hash over its source files, its
manifest and the fingerprints of its build-time inputs, so equal content gives an equal fingerprint whatever
the commit (ADR 0429 §5). It is today's source fingerprint with a base entering by its module's
fingerprint, the builder by its own module's fingerprint, and a build resolving packages by its lock. From
release 4 a build's key, so one source is never built twice.
- **source revision** — one revision of the key `source.main`, written only by the gate: every repository's
merged head and the group that moved it. A group reaches the mesh as one source revision (ADR 0429 §11); a
source revision is **delivered** when every want equals its module's fingerprint and every have equals its
want and is healthy, derived from the keys and recorded by no part (§1).
- **canary** — the first node of a module's nodes, ordered by ring then name: a new fingerprint reaches it
first and the module's other nodes only once it runs healthy there (ADR 0429 §6). Replaces sending to every
machine at once from release 6 (§15).
- **want** and **have** — a want (`want.<node>.<module>`) is the fingerprint a node should run, written by the
assigner; a have (`have.<node>.<module>`) is what the node runs, its phase and health, written by that node's
agent (ADR 0429 §4, §6). A node's facts that no module owns are its node key. They replace assignments and
rollouts at release 6 (§17); haves are written from release 1.
- **pulse** — a key the watchman writes for each key whose next move a machine owes, with a time to live; its
expiry is a stall, raised as a condition, so no part needs a timer (ADR 0429 §1, research 063). A person's
wait carries none.
- **rollout** — the controller's sending of one batch's builds across nodes, at most one trunk commit per
repository, tier by tier, to every node that runs each module at once (ADR 0276, ADR 0360). Rollouts that share a
repository, a module or a graph edge run one after another; others run side by side (ADR 0407). It names every
merge it answers, and its record is one key of the bus's rollouts bucket, a link of the chain (ADR 0408). A primitive the delivering stage
asks for, not an object anyone manages. A **tier** is one step of a rollout: a module, then the modules
built against it. The controller's verb `plans` lists the rollouts. A module is rolled out by its `roll`
policy.
policy. Rollouts and tiers go at release 6 of ADR 0429 (§8, §15), replaced by wants and haves (§17).
*Not:* ~~walk~~ (hq)
- **first-node gate** — the judgement on a delivery's first node: healthy three times, no witness put it
back, no condition raised since the send (ADR 0236 §2). Not *the gate* bare (see [Homonyms](#homonyms)).
@@ -520,7 +555,7 @@ planner, the rollout). **Downstream of** Module, Core, Health and repair and Dat
**Purpose.** To notice what is wrong with the mesh, say it once, repair what may be repaired unattended,
and record what was done by hand. **Recorded by** the controller's condition store.
**Upstream of** Change and delivery (the first-node gate) and Operator and conversation (a condition
**Upstream of** Delivery (the first-node gate) and Operator and conversation (a condition
becomes a message). **Decided by** ADR 0227, 0231, 0240, 0252, 0283.
**Uses:** node, module, node-engine (Core).
@@ -562,7 +597,7 @@ becomes a message). **Decided by** ADR 0227, 0231, 0240, 0252, 0283.
**Purpose.** To know every item of data a module holds, how precious it is, and to keep it recoverable.
**Recorded by** the manifests' `data` declarations and every node's `node-backup` seat.
**Upstream of** Change and delivery and Health and repair. **Decided by** ADR 0232, 0233, 0235.
**Upstream of** Delivery and Health and repair. **Decided by** ADR 0232, 0233, 0235.
**Uses:** module, node, provider and consumer (Provisioning), person.
- **data class** — how precious an item of data is, ranked by the operator: `irreplaceable`,
@@ -609,10 +644,10 @@ it should not. **Recorded by** the controller. **Upstream of** Provisioning and
**Purpose.** To let the mesh and its operator talk: tell, ask, answer, and act only on an answer it can
trust. **Recorded by** the router (asks, warrants and the operator's identities).
**Downstream of** Health and repair, Change and delivery, and Identity and access. An authorising
**Downstream of** Health and repair, Delivery, and Identity and access. An authorising
answer acts in whichever domain asked, through that domain's own verb; the conversation owns the
asking, never the act. **Decided by** ADR 0152, 0175, 0234, 0259, 0272, 0383, 0384, 0385, 0390.
**Uses:** operator, person, node, module, seat, tool (Module), proof and identity (Identity and access), release (Change and delivery).
**Uses:** operator, person, node, module, seat, tool (Module), proof and identity (Identity and access), release (Delivery).
- **mesh MCP server** — the endpoint on a node's loopback through which every agent and person on that
node reaches the mesh: the MCP server named `mesh`, with its five tools `mesh_overview`,
@@ -804,22 +839,24 @@ renaming one sense, the old sense moves to a *Not:* line and becomes mechanical.
| Word | Sense | Say | Domain |
|---|---|---|---|
| plan | what the controller would send one node | that node's **declaration** (verb `plan`) | Placement |
| | what a delivery would do to the mesh | **delivery plan** | Change and delivery |
| | the sending of one batch of commits across nodes | **rollout** (verb `plans`) | Change and delivery |
| | what a delivery would do to the mesh | **delivery plan** | Delivery |
| | the sending of one batch of commits across nodes | **rollout** (verb `plans`) | Delivery |
| | a step a person starts, like the bus's | **planned step** | Core |
| membership | the subjects a bus account is issued | **membership** | Provisioning |
| | an account in a group of the machine | **account group** | Placement |
| push | the controller giving nodes their declarations | **send** (verb `push`) | Placement |
| | a git push | **git push** | The record |
| | a phone notification | **push notification** | Operator and conversation |
| release | a person letting a held delivery go on | **release** | Change and delivery |
| release | a person letting a held delivery go on | **release** | Delivery |
| | one milestone built, checked and delivered as one (playbook 07; releases 1 to 6 of ADR 0429) | **release** of a milestone | The record |
| | taking a consumer off a licence | **unbind** (verb `release`, to rename) | Identity and access |
| | a copy of a work an engine can fetch | **media release** | Media |
| gate | the judgement on a delivery's first node | **first-node gate** | Change and delivery |
| | the pull request status | **merge gate** | Change and delivery |
| gate | the judgement on a delivery's first node | **first-node gate** | Delivery |
| | the pull request status | **merge gate** | Delivery |
| | the part that merges a group and moves the source revision | **gate part** (`mesh-delivery-gate`) | Delivery |
| | a failed step stopping its module's later steps (ADR 0136) | *a failed step holds its module* | Placement |
| tier | a level of the mesh | **layer** | Core |
| | a step of a rollout | **tier** | Change and delivery |
| | a step of a rollout | **tier** | Delivery |
| | how much proof an ask needs | **assurance level** | Identity and access |
| harness | the part of `mesh-sdk` that serves a tools bundle | **SDK harness** | Module |
| | the program that runs an agent's sessions | **agent harness** | Operator and conversation |
@@ -827,9 +864,9 @@ renaming one sense, the old sense moves to a *Not:* line and becomes mechanical.
| role | what a seat names, at a scope | **seat**; the bare word in older designs is tracked by issue 872 | Module |
| | what an identity may call | **role** | Identity and access |
| ask | a request for the operator's input | **ask** | Operator and conversation |
| | an entry in the build queue | **build request** | Change and delivery |
| | an entry in the build queue | **build request** | Delivery |
| store | the one database server | **store** | Core |
| | the OCI registry | **artifact store** | Change and delivery |
| | the OCI registry | **artifact store** | Delivery |
| | a node's own copy of its last declaration | **last declaration** | Placement |
| record | a numbered decision | **decision record** | The record |
| | the literal reader of this repository, searched first for a symptom | **the record** (the `records` module) | Operator and conversation |
@@ -838,19 +875,19 @@ renaming one sense, the old sense moves to a *Not:* line and becomes mechanical.
| | the operator's terminal command, `mesh-cli` | **the `nox` command** | Operator and conversation |
| knowledge base | the module holding the decision records and research efforts whole | **knowledge base** | The record |
| | the predecessor's operational memory, in older playbooks (issue 430) | none: it no longer exists | — |
| check | a pull request's two statuses | **merge check**, **merge gate**, **repository check** | Change and delivery |
| | a delivery group's verdict | **composed check** | Change and delivery |
| check | a pull request's two statuses | **merge check**, **merge gate**, **repository check** | Delivery |
| | a delivery group's verdict | **composed check** | Delivery |
| | the controller's own examination | **self-check** | Health and repair |
| | a file in `00-META/checks/` | **hq check** | The record |
| agent | a coding agent | **agent** | Operator and conversation |
| | the build seat's holder | **builder** | Change and delivery |
| | the build seat's holder; from release 4 of ADR 0429 the part `mesh-delivery-builder` | **builder** | Delivery |
| the user | an account of a wrapped program, or of the bus server | **its account**, **bus account** | Identity and access |
| | a human | **operator** or **person** | words every domain uses |
| firewall | what the mesh enforces | **packet filter** | Connectivity |
| | what was found on a machine | **found firewall** | Connectivity |
| ticket | an answer's one-time token (ADR 0258) | **answer ticket** | Operator and conversation |
| | a question someone must answer | **issue** | The record |
| deploy | the per-node part of a delivery plan | **deploy plan** | Change and delivery |
| deploy | the per-node part of a delivery plan | **deploy plan** | Delivery |
| | a wrapped program's own deploy | its own word | — |
| managed | a placed file of which only named keys or a marked block are the mesh's | **managed** (`owner-at-runtime`) | Provisioning |
| | a file the mesh writes, such as the agent's instruction file or `managed_settings` | the file's own name, or *a file the mesh places* | — |
00-META/repos.md
+1
View File
@@ -36,6 +36,7 @@ one-for-one — `mesh-catalog`, `mesh-sdk` and `mesh-tools` exist where the tabl
| `mesh-surfaces` | 3 | tools, web, cli |
| `mesh-sdk` | — | the stable spine modules build against — the tool-serving SDK harness, the messaging/event framework, the contracts and core primitives. Holds nothing per-module and nothing volatile (ADR 0039). |
| `mesh-lab` | — | **exists.** The lab — scenario lifecycle, networking, placement. Ships to nobody; runs on a workstation. |
| `mesh-delivery` | — | the delivery domain: the parts that build, check and deliver a change by watching and writing keys on the bus, nine modules each whole in it, prefixed `mesh-delivery-` (ADR 0429). Made by the forge module from its config (ADR 0428). |
Tier 4's shape is open, and deliberately so: see ADR 0019 and
research 005.
03-DESIGN/01-to-be/47-delivery-from-commit-to-delivered.md
+71 -5
View File
@@ -1,9 +1,11 @@
---
layer: to-be
status: in-progress
code: [mesh-controller, mesh-catalog modules/mesh-delivery]
code: [mesh-controller, mesh-catalog modules/mesh-delivery, mesh-delivery, mesh-host, mesh-sdk]
updated: 2026-10-18
decisions:
- "ADR 0429"
- "ADR 0428"
- "ADR 0426"
- "ADR 0421"
- "ADR 0420"
@@ -62,6 +64,42 @@ commit's journey, in what order the steps are allowed, and where each fact of it
2026-10-16 from the decisions of research 055, which replaced the "release branches", the toolchain image, the
controller's delivery tables and the timers that polled them.
## Where it goes: parts that watch and write keys
ADR 0429 (accepted on 2026-10-18, from research 063) takes building and delivering out of the controller. They
become independent **parts**, each a process with its own bus credential that watches keys and writes keys:
no part calls another, there is no plan object and no orchestrator, and each key has one writer. A delivered
source revision is derived from the keys: every **want** equals its module's **fingerprint**, and every
**have** equals its want and is healthy.
- **The forge bridge** turns the forge's events into stream messages and is the only part that calls the
forge.
- **The indexer** computes each module's fingerprint at the merge preview and writes the candidates of each
group and the modules of the trunk.
- **The builder** claims a build by creating its key, once per fingerprint, and builds it; build-agent becomes
this part.
- **The checker** runs the merge check on built artifacts.
- **The gate** merges a group's pull requests once check, review and the operator's Approve agree on the same
heads, and then moves the mesh's source revision in one write.
- **The teller** carries conditions and asks to the operator's phone and is the only writer of an ask's answer.
- **The assigner** writes which fingerprint each node should run, by six rules: the build is done, the
fingerprint is not held, the node is the module's **canary** or the canary runs it healthy, at most `step`
other nodes are ahead when `step` is above zero, every provider runs healthy, and the module's credential for that fingerprint exists.
- **The node agent**, the node-engine's own process, applies its wants one module at a time, backs up a data
module first, and writes its haves.
- **The watchman** turns the bus's connections into presence and mirrors every key whose next move a machine
owes into a **pulse**, whose expiry is a stall.
- **The status view** is the operator's command `mesh-delivery-cli` and a web view; it reads every bucket and
writes only its own answers to asks.
Nine of these are modules of the repository `mesh-delivery`, prefixed `mesh-delivery-` (ADR 0429 §2); the
repository is made by the forge module from its config (ADR 0428; issue 1128 makes the config value reach the
node at once). The reviewer stays the review agent's session.
It lands in six releases, each leaving the mesh working, each one milestone below (ADR 0429 §7). Until the
release that replaces it is delivered, each section from here to *The bootstrap* stays this design and its rule
(ADR 0429 §21); each is rewritten when the release that replaces it is prepared (issue 1130).
## The parts
```
@@ -525,6 +563,25 @@ What the build proves before this design is implemented (research 055's directio
with no person's release and nothing held in mesh-delivery.
12. No table in the controller's store holds builds, rollouts or assignments.
From ADR 0429 (research 063's done-when, and the live proof each of its releases names):
13. The status view shows every module on every node from the have keys, and agrees with the controller's own
read of the nodes' reports.
14. A part stopped by hand shows stuck within two minutes, and no part holds a timer.
15. A group of two repositories merges as one source revision, and every module's fingerprint the indexer
writes equals the controller's source fingerprint.
16. A merge builds nothing its check built, and a hotfix's build waits for no other build.
17. A day of deliveries shows no difference between the assigner's wants and what the controller sent that the
six rules do not explain.
18. On the live mesh a milestone of three repositories reaches every node through the keys alone (research 063's
scenario A), and the assigner replaced in the middle of it resumes with nothing lost or repeated (scenario
D, once).
19. Plans, batches, the merge window, tiers, the plans hold and node declaration holds, the push of whole
declarations, their retries, takeovers and healers, and the node-engine's handling of whole declarations are
deleted from the code, and no verb that starts, stops, retries or closes a plan remains.
20. Each release's pull request reports the controller's code lines against research 063's baseline (111,386
lines on 2026-10-18).
## What retires
- The "release branches" and the controller's judge of them (ADR 0358, superseded by ADR 0401).
@@ -544,8 +601,12 @@ What the build proves before this design is implemented (research 055's directio
## Milestones
Confirmed by the operator on 2026-10-17 (playbook 04). Each is one release of playbook 07; the next starts
when the previous one's delivery is done.
Milestones 1 to 6 were confirmed by the operator on 2026-10-17 (playbook 04), and 5b on 2026-10-18. Releases 1
to 6 of ADR 0429 follow milestone 5b in its order, releases 1 and 2 as one milestone (ADR 0429 §7 allows it:
they need nothing of each other); they wait for the operator's confirmation (playbook 04 step 5), and their
issues are opened once it is given. Each milestone is one release of playbook 07; the next starts when the
previous one's delivery is done, and a release's clauses of ADR 0429 hold from its delivery (§21). Every
release reports the controller's code lines against research 063's baseline (acceptance test 20).
| # | Outcome | Acceptance tests | Repositories | Issues |
|---|---|---|---|---|
@@ -556,8 +617,13 @@ when the previous one's delivery is done.
| 4 | A delivery backs up the data it moves first, and a failed backup holds it and is said | 3 | mesh-controller, mesh-catalog (mesh-delivery, the backup seat's holder) | 980, split into 1065, 1066, 1067, 1068 |
| 3 fix | A group approved together merges in one pass and goes out in one delivery plan, also when its members' tests read each other's repositories | 1 | mesh-catalog (mesh-delivery, gitea) | 1082, 1049, 1047, 1083, 1079 (1084 closed as its duplicate) |
| 5 | One read of a module on a node names the commit, build and rollout that put it there | 10, 12 | mesh-controller, mesh-catalog (mesh-config, nats) | 981 |
| 5b | The controller makes no build or deploy plan: building and delivering a change are done outside it, driven by events on the bus, and the controller receives only what each node should run | — (its decision names them) | mesh-controller, mesh-catalog (mesh-delivery) | 1117 |
| 6 | Builds use installed toolchains with no container, builders fetch over SSH with their own key, and an SDK change ships in one group with its users | 2, 4 | mesh-catalog (build modules, build-agent, ssh-client, gitea), mesh-controller, mesh-sdk | 979, 971 |
| 5b | Decided: building and delivering leave the controller for parts that watch and write keys in the repository `mesh-delivery`, landing in six releases (ADR 0429); the forge module makes that repository from its config, protected before any team reaches it (ADR 0428) | — (ADR 0429 names them: 13 to 20) | hq, mesh-catalog (gitea) | 1117, 1124, 1128 |
| 6 | Folded into release 4 by ADR 0429 §10: installed toolchains, builders fetching over SSH with their own key, and an SDK change shipping with its users are built in the builder's new home, so the builder is changed once | (2, 4: proved by release 4) | — | 979, 971 (moved to release 4) |
| R1–2 | The operator sees every module on every node, with its fingerprint, phase and health, in `mesh-delivery-cli` and its web view, and a part that stops moving is raised as a condition within two minutes without a timer | 13, 14 | mesh-delivery (view, watchman), the node-engine (`mesh-host`: have keys; its alive message deleted), mesh-sdk (key layouts), mesh-controller (its silence timers deleted), mesh-catalog (zsh's `nox-delivery`) | opened once confirmed |
| R3 | A group reaches the mesh as one source revision written by the gate, the operator's asks come through the teller and can be answered in the view, but for the merge's Approve, answered on the phone until its way in proves who answered (issue 953), and today's module mesh-delivery is split into its parts and ends | 15 | mesh-delivery (forge bridge, gate, teller, indexer), mesh-catalog (mesh-delivery split), mesh-sdk | opened once confirmed |
| R4 | The controller asks no build: a build is keyed by its fingerprint, so a merge builds nothing its check built; with milestone 6, toolchains are installed, builders fetch over SSH, and an SDK change ships with its users | 16, 2, 4 | mesh-delivery (builder, checker), mesh-controller (build dispatch deleted; build-agent leaves), mesh-catalog (build modules, ssh-client, gitea), mesh-sdk | 979, 971; the rest opened once confirmed |
| R5 | The assigner writes what each node should run by its six rules, compared with what the controller sends, and the view shows every difference | 17 | mesh-delivery (assigner), mesh-controller (grants keys) | opened once confirmed |
| R6 | Each node applies from its wants, a new version reaches the module's canary first and the rest once it is healthy there, and the plans are deleted from the code | 18, 19 | the node-engine (`mesh-host`: the node agent), mesh-controller (plans deleted), mesh-delivery (the gate's delivery states go) | opened once confirmed |
The issues are linked `depends-on` in this order; 976 depends on 975, and 979 also on 971. Milestone 3's first live group (milestone 4's, on 2026-10-17) held one Approve but merged in two passes and went out in two delivery plans: a member's tests read the other member's repository, so the first merge made the second's verdict out of date, and a closed group never asked its composed verdict again (issues 1049, 1082). The operator put a fix of milestone 3 after milestone 4 and before milestone 5 on 2026-10-18; acceptance test 1 is proved again by it. The operator put milestone 5b after milestone 5 and before milestone 6 on 2026-10-18, as an issue rather than a research effort; where the planning goes is settled by a decision record before it is built (issue 1117), and milestone 6's build changes are read against it. Milestone 2b was
put before milestone 3 by the operator on 2026-10-17. Milestone 3 builds ADR 0418, ADR 0419 and ADR 0421
03-DESIGN/01-to-be/49-the-mesh-in-domains.md
+6 -5
View File
@@ -2,8 +2,9 @@
layer: to-be
status: in-progress
code: [hq 00-META/checks/words.py, mesh-catalog merge-check.sh]
updated: 2026-10-11
updated: 2026-10-18
decisions:
- "ADR 0429"
- "ADR 0244"
- "ADR 0006"
- "ADR 0008"
@@ -31,7 +32,7 @@ shape — what each is for, where its records live, and how they depend on one a
| **Placement** | to decide, send and apply what each node runs, and say why | the controller's `inventory` database |
| **Provisioning** | to resolve which module serves a provision for which consumer, and wire the two | the controller |
| **Identity and access** | to issue, hold, rotate and check credentials and grants | the controller's `identity` and `licences` databases, and the vault |
| **Change and delivery** | to take one commit from its pull request to every node that should run it, and put it back when it fails | the `mesh-delivery` module, and the controller's planner and rollout |
| **Delivery** | to take one commit from its pull request to every node that should run it, and put it back when it fails | the `mesh-delivery` module and the controller's planner and rollout today; from each release of ADR 0429 on, the parts of the repository `mesh-delivery` it builds |
| **Health and repair** | to notice what is wrong, say it once, repair what may be repaired unattended, and record what was done by hand | the controller's condition store |
| **Data** | to know every item of data a module holds, how precious it is, and keep it recoverable | the manifests' data declarations, and every node's `node-backup` seat |
| **Connectivity** | to make every node and module reachable by name where it should be, and unreachable where it should not | the controller |
@@ -61,7 +62,7 @@ a change of meaning upstream ripples down, never up. Arrows point downstream.
+-------------> Health and repair <-------------------+
| |
v v
Change and delivery Operator and conversation
Delivery Operator and conversation
| ^
+-------------------+
(a held delivery waits for a person's word)
@@ -70,7 +71,7 @@ a change of meaning upstream ripples down, never up. Arrows point downstream.
Media stands beside the diagram, below Module alone: its words are about what a person watches, not
about the mesh's machinery, and no other domain reads them.
Change and delivery sits low because it reads health and data; in time it runs first, and asks Placement
Delivery sits low because it reads health and data; in time it runs first, and asks Placement
to send. An authorising answer acts in whichever domain asked, through that domain's own verb: the
conversation owns the asking, never the act.
@@ -84,7 +85,7 @@ ADR 0006 named seven contexts of the controller. Each is a domain now, under the
| config | split: settings to Module and Placement, secrets to Identity and access |
| connectivity | Connectivity |
| provisioning | Provisioning |
| delivery | Change and delivery — owned by the `mesh-delivery` module, not by the controller (ADR 0239) |
| delivery | Delivery — owned by the `mesh-delivery` module, not by the controller (ADR 0239); named so by ADR 0429 §2, its parts living in the repository `mesh-delivery` |
| observability | Health and repair: the mesh built conditions, not "alerts", and half of the domain is repair |
| identity | Identity and access, with the licences store the seven did not name |