Issues 245, 246; 240 resolved, 242 located

245: a media server's previews were reached through a link its container never mounted — fixed by mounting them. 246: settings set replaces the whole layer with nothing to read it first and no history. 240 is fixed by mesh-controller#47; 242 has backups running and records what the rollout taught.
2026-10-05 14:54:38 +02:00
212 changed files with 822 additions and 18312 deletions
@@ -4,8 +4,6 @@
 python3 00-META/checks/records.py      structure: links, citations, supersession, topics
 python3 00-META/checks/index.py        the reading order in 02-DECISIONS/README.md is current
 python3 00-META/checks/index.py --write  regenerate it
 python3 00-META/checks/words.py        the glossary's retired words are not used, and no word is defined twice
 python3 00-META/checks/words.py --list tools   the words the catalogue's copy must list
 ```
 Non-zero exit on any problem, so it can be a gate rather than a report.
@@ -58,28 +56,4 @@ a to-be design names a decision, an in-progress/implemented design names its own
 located/fixed issue names its owner, a fixed/resolved issue says what fixed it, a graduated
 research overview says what it became, and no two issue records share a number (issue 155 — the
 number is how a record is cited, and `main` lags every open pull request, so two people reading it
-allocate the same one). And a core issue — one opened from 2026-10-07 whose `located-in` names a core
+allocate the same one). `python3 00-META/checks/cycle.py`
 repository — resolves only with `replay:` (an id in mesh-lab's replays register) or `replay-none:` saying
 why none is possible ([ADR 0237](../../02-DECISIONS/0237-a-change-is-judged-against-the-mesh-that-runs-before-it-merges-on-the-build-seat.md));
 it failed on a resolved core issue carrying neither before it passed. `python3 00-META/checks/cycle.py`
 ## words.py
 One word per thing, checked ([ADR 0244](../../02-DECISIONS/0244-the-mesh-is-described-in-domains-and-one-word-names-one-thing.md)).
 It reads the glossary's *Not:* lines (the retired words, each with its scope) and *Identifier until
 renamed* lines, and fails on a retired word or a bare identifier in running prose — what is left once code,
 quotations, struck-through text, link targets, comments and frontmatter are taken out — in `00-META/`,
 `03-DESIGN/`, `AGENTS.md`, `README.md`, and research and issues dated from 2026-10-07. Decision records are
 never checked. It also fails when a glossary head word heads two entries or is also retired.
 [`words-allowed.md`](words-allowed.md) names a document that could not be reworded at once, with a date, or
 a graduated research effort kept as written. With `MESH_CATALOG_DIR` set it compares the catalogue's copy
 of the tools' retired words (`retired-words`) with the glossary.
 It failed on something real before it passed: 581 uses of retired words in 63 documents on its first run, besides the glossary itself and research 034 —
 "the host" for the node-engine in 30 designs, "control plane" in 10, the glossary's own entry for the tool runner —
 and two glossary contradictions (the "console", the deprecated broker's seat), fixed in the change that
 added it. A retired word's plural (`s` or `es` on its last word) is matched as the word: until 2026-10-07
 it was not, so "alerts", "rollouts" and "the hosts" (the node-engines) passed while their singulars
 failed; the plural failed on 15 uses in 10 documents before it passed. A verb that reads like a plural
 ("a node hosts") is a finding too, and is reworded. Homonyms (*plan*, *gate*, *tier*, *ask*, *store*, *record*, *check*) are not checked by it: a
 word list cannot tell one sense from another, so they are reviewed.
@@ -16,11 +16,6 @@ What is enforced:
          once `resolved`, `fixed-by:` says what fixed it (prose counts --
          "nothing, the capability existed" is an answer). And no two records share a
          number -- the number is how a record is cited.
  replays a core issue -- one opened from 2026-10-07 whose `located-in:` names a core repository --
          resolves only with `replay:` (the replay's id in mesh-lab's replays register) or
          `replay-none:` (why no replay is possible): ADR 0237, to-be 45 §9. A replay is what
          proves a fix fails before and passes after; without one, a fixed class comes back
          through a different door (research 031: four such chains in one week).
  research a known `status:`; a `graduated` overview says what it `became:`, and every
          target it names exists.
  decisions every accepted record is REACHABLE from the cycle: cited by a design doc's
@@ -46,16 +41,6 @@ DESIGN_STATUSES = {"proposed", "designed", "in-progress", "implemented", "abando
 ISSUE_STATUSES = {"open", "diagnosing", "located", "resolved", "wontfix"}
 RESEARCH_STATUSES = {"active", "graduated", "abandoned"}
 # The core, as to-be 45 names it, by where its code lives: the controller, the node-engine, the node
 # tools and the console, the SDK's loops, and the catalogue's bus, forge (the announcer of merges) and
 # build agent. A `located-in:` entry naming any of these makes an issue a core issue.
 CORE = re.compile(r"\b(mesh-controller|mesh-host|mesh-tools|mesh-sdk|node-tools|"
                  r"mesh-catalog\s+modules/(nats|gitea|build-agent))\b")
 # The day the rule began (ADR 0237): issues opened before it are not held to it.
 REPLAYS_FROM = "2026-10-07"
 REPLAY_ID = re.compile(r"^R\d+\b")
 def rel(path):
    return os.path.relpath(path, ROOT)
@@ -174,16 +159,6 @@ def main():
            bad(path, "status %s but located-in is empty" % status)
        if status == "resolved" and not listy(front, "fixed-by"):
            bad(path, "status %s but fixed-by says nothing" % status)
        # A core issue resolves with its replay, or with why none is possible (ADR 0237).
        replay = " ".join(listy(front, "replay"))
        if replay and not REPLAY_ID.match(replay):
            bad(path, "replay: %r names no replay -- an id from mesh-lab's replays register, R<issue>" % replay)
        core = any(CORE.search(entry) for entry in listy(front, "located-in"))
        opened = str(front.get("opened") or "")
        if (status == "resolved" and core and opened >= REPLAYS_FROM and not replay
                and not " ".join(listy(front, "replay-none")).strip()):
            bad(path, "a core issue resolved with no replay: name it in `replay:` (mesh-lab replays "
                      "register.go) or say in `replay-none:` why none is possible (ADR 0237)")
    # ---- research ----------------------------------------------------------------------
    for path in sorted(glob.glob(os.path.join(ROOT, "01-RESEARCH", "*", "00-overview.md"))):
@@ -1,16 +0,0 @@
 # Words allowed — documents `words.py` does not hold to the glossary's retired words
 Read by [`words.py`](words.py) ([ADR 0244](../../02-DECISIONS/0244-the-mesh-is-described-in-domains-and-one-word-names-one-thing.md)).
 One row per document. *Until* is the date by which it is reworded — past it, the row fails like the words
 themselves — or `kept` for a graduated research effort, which records what was said and keeps its words
 the way a decision record does. A row whose document no longer uses a retired word fails too, so this
 list only shrinks.
 | Document | Until | Why |
 |---|---|---|
 | `01-RESEARCH/034-the-mesh-in-domains/00-overview.md` | kept | the effort that studied these words; its findings quote and propose them as they stood before ADR 0244 |
 | `01-RESEARCH/034-the-mesh-in-domains/01-the-concepts-in-use.md` | kept | as above: the inventory of the words in use |
 | `01-RESEARCH/034-the-mesh-in-domains/02-the-domains.md` | kept | as above: the proposed domains, in the words of the day |
 | `01-RESEARCH/034-the-mesh-in-domains/03-the-clashes.md` | kept | as above: every clash names the words that clashed |
 | `01-RESEARCH/034-the-mesh-in-domains/04-how-the-glossary-is-checked.md` | kept | as above: the check's own examples |
 | `01-RESEARCH/034-the-mesh-in-domains/05-a-glossary-by-domain.md` | kept | as above: the proposed glossary, with the entries of the day |
@@ -1,283 +0,0 @@
 #!/usr/bin/env python3
 """One word per thing, checked (ADR 0244).
 The glossary (00-META/glossary.md) is the authority on the mesh's words. It names the words it
 retired on one fixed kind of line, so a program can read them:
    *Not:* ~~control plane~~, ~~overlay~~ (hq)
 A struck word with no scope is retired everywhere; `(hq)` retires it in this repository's prose only;
 `(tools)` in the descriptions of the mesh's tools only. And it names code that still carries an old
 name until that code is renamed:
    *Identifier until renamed:* `mesh-host` — the repository, binary and service unit
 An identifier is allowed inside a code span and nowhere else.
 What is enforced:
  retired      no retired word of scope `hq` (or none), and no identifier, in running prose of a
               checked document. Running prose is what is left once code blocks, code spans, block
               quotes, text in quotation marks, struck-through text, link targets, HTML comments and
               frontmatter are taken out: a quotation keeps the words it quotes, a link target is a file
               name, and an identifier lives in a code span. A word's plural is the word: "alerts" fails
               as "alert" does.
  unique       no head word (a bolded word opening a glossary entry) heads two entries, and no head
               word is also struck through on a *Not:* line.
  tools list   with `--list tools` it prints the words retired in the tools' descriptions, which is the
               copy the catalogue's own check keeps (mesh-catalog `retired-words`). With
               MESH_CATALOG_DIR set to a checkout of the catalogue it also fails when that copy differs.
 Checked documents: 00-META/, 03-DESIGN/ (both layers), AGENTS.md and README.md, always; a research
 effort initiated, or an issue opened, on or after FROM. Never 02-DECISIONS/: a decision record keeps the
 words it was written with.
 A document the check fails on that cannot be reworded in the change that found it is named, with a date
 and a reason, in words-allowed.md beside this file. An entry past its date fails like the word itself, and
 an entry for a document that no longer needs it fails too. `kept` instead of a date is allowed only for a
 graduated research effort, which is a record of what was said, like a decision record.
    python3 00-META/checks/words.py
    python3 00-META/checks/words.py --list tools
 """
 import datetime
 import os
 import re
 import sys
 ROOT = os.path.normpath(os.path.join(os.path.dirname(__file__), "..", ".."))
 GLOSSARY = "00-META/glossary.md"
 ALLOWED = "00-META/checks/words-allowed.md"
 # The day the rule began (ADR 0244): research and issues from it on are held to it.
 FROM = "2026-10-07"
 ALWAYS = ("00-META/", "03-DESIGN/", "AGENTS.md", "README.md")
 NOT_LINE = re.compile(r"^\s*(?:[-*]\s+)?\*Not:\*(.*)$", re.M)
 STRUCK = re.compile(r"~~([^~]+)~~(?:\s*\((hq|tools)\))?")
 IDENT_LINE = re.compile(r"^\s*(?:[-*]\s+)?\*Identifier until renamed:\*(.*)$", re.M)
 CODE_SPAN = re.compile(r"`([^`]+)`")
 HEAD = re.compile(r"^\s*-\s+\*\*([^*]+)\*\*", re.M)
 def rel(path):
    return os.path.relpath(path, ROOT)
 def read(path):
    with open(os.path.join(ROOT, path), encoding="utf-8") as handle:
        return handle.read()
 def frontmatter_field(text, name):
    if not text.startswith("---\n"):
        return None
    end = text.find("\n---", 4)
    m = re.search(r"^%s:\s*(\S+)" % name, text[4:end], re.M)
    return m.group(1) if m else None
 def glossary():
    """The retired words with their scope, the identifiers, and the head words."""
    text = read(GLOSSARY)
    retired = []
    for line in NOT_LINE.findall(text):
        for word, scope in STRUCK.findall(line):
            for one in word.split(" / "):
                retired.append((one.strip(), scope or "all"))
    identifiers = []
    for line in IDENT_LINE.findall(text):
        identifiers += [i.strip() for i in CODE_SPAN.findall(line)]
    heads = []
    for head in HEAD.findall(text):
        heads += [h.strip() for h in head.split(" / ")]
    return retired, identifiers, heads
 def pattern(word):
    """A whole-word, case-insensitive match; a space in the word matches a space, a line break or a hyphen.
    The plural is the word too: its last part may end in `s` or `es` ("alerts", "control planes"), since
    a retired word does not come back by being counted. Anything else joined on is another word.
    """
    parts = [re.escape(p) for p in word.split()]
    return re.compile(r"(?i)(?<![\w-])" + r"[\s-]+".join(parts) + r"(?:e?s)?(?![\w-])")
 def blank(match):
    return re.sub(r"[^\n]", " ", match.group(0))
 def prose(text, glossary_file=False):
    """The text with everything that is not running prose blanked, keeping offsets and line numbers."""
    if text.startswith("---\n"):
        end = text.find("\n---", 4)
        if end != -1:
            text = re.sub(r"[^\n]", " ", text[: end + 4]) + text[end + 4:]
    steps = [
        r"(?ms)^\s*```.*?^\s*```",      # code blocks
        r"(?s)<!--.*?-->",              # comments
        r"(?m)^\s*>.*$",                # block quotes
        r"`[^`\n]+`",                   # code spans
        r"\]\([^)\s]*\)",               # link targets
        r"~~[^~\n]+~~",                 # struck through: a word named as retired
        r"\"[^\"\n]*\"",                # "quoted"
        r"\u201c[^\u201d]*\u201d",      # curly double quotes
        r"\u2018[^\u2019\n]*\u2019",    # curly single quotes
    ]
    if glossary_file:
        steps[:0] = [NOT_LINE.pattern, IDENT_LINE.pattern]
    for step in steps:
        text = re.sub(step, blank, text)
    return text
 def research_and_issues():
    """The research efforts and issue reports dated on or after FROM, file by file."""
    out = []
    for folder, key, first in (("01-RESEARCH", "initiated", "00-overview.md"), ("04-ISSUES", "opened", "00-report.md")):
        base = os.path.join(ROOT, folder)
        for effort in sorted(os.listdir(base)):
            head = os.path.join(base, effort, first)
            if not os.path.isfile(head):
                continue
            date = frontmatter_field(read(rel(head)), key)
            if not date or date < FROM:
                continue
            for name in sorted(os.listdir(os.path.join(base, effort))):
                if name.endswith(".md"):
                    out.append("%s/%s/%s" % (folder, effort, name))
    return out
 def checked_documents():
    docs = []
    for entry in ALWAYS:
        path = os.path.join(ROOT, entry)
        if os.path.isfile(path):
            docs.append(entry)
            continue
        for base, dirs, files in os.walk(path):
            dirs.sort()
            for name in sorted(files):
                if name.endswith(".md"):
                    docs.append(rel(os.path.join(base, name)))
    return docs + research_and_issues()
 def allowed():
    """words-allowed.md: one row per document — | `document` | until | why |.
    `until` is a date, after which the allowance fails like the words themselves, or `kept` for a
    document that records what was said and must keep its words: only a research effort that has
    graduated may be kept, because once it has become a decision it is a record like one.
    """
    out, problems = {}, []
    if not os.path.isfile(os.path.join(ROOT, ALLOWED)):
        return out, problems
    today = datetime.date.today().isoformat()
    for line in read(ALLOWED).splitlines():
        cells = [c.strip() for c in line.strip().strip("|").split("|")]
        if len(cells) != 3 or not cells[0].startswith("`"):
            continue
        doc, until, why = cells[0].strip("`"), cells[1], cells[2]
        if not why:
            problems.append("%s: the allowance for %s gives no reason" % (ALLOWED, doc))
        if until == "kept":
            overview = os.path.join(os.path.dirname(doc), "00-overview.md")
            status = frontmatter_field(read(overview), "status") if os.path.isfile(os.path.join(ROOT, overview)) else None
            if not doc.startswith("01-RESEARCH/") or status != "graduated":
                problems.append("%s: %s is kept, but only a graduated research effort may be" % (ALLOWED, doc))
                continue
        elif not re.match(r"^\d{4}-\d{2}-\d{2}$", until):
            problems.append("%s: the allowance for %s has neither a date nor `kept`" % (ALLOWED, doc))
            continue
        elif until < today:
            problems.append("%s: the allowance for %s ran out on %s — reword it" % (ALLOWED, doc, until))
            continue
        out[doc] = until
    return out, problems
 def check_retired(retired, identifiers):
    problems = []
    allowance, problems_allowed = allowed()
    problems += problems_allowed
    words = [(w, pattern(w), "retired") for w, scope in retired if scope in ("all", "hq")]
    words += [(i, pattern(i), "an identifier, allowed only in a code span") for i in identifiers]
    used = set()
    for doc in checked_documents():
        text = prose(read(doc), glossary_file=(doc == GLOSSARY))
        for word, rx, why in words:
            for m in rx.finditer(text):
                if doc in allowance:
                    used.add(doc)
                    continue
                line = text.count("\n", 0, m.start()) + 1
                problems.append("%s:%d: %r is %s (glossary)" % (doc, line, m.group(0).replace("\n", " "), why))
    for doc in allowance:
        if doc not in used:
            problems.append("%s: %s no longer uses a retired word — remove its allowance" % (ALLOWED, doc))
    return problems
 def check_unique(retired, heads):
    problems = []
    seen = {}
    for head in heads:
        key = head.lower()
        if key in seen:
            problems.append("%s: %r heads two entries" % (GLOSSARY, head))
        seen[key] = True
    for word, _ in retired:
        if word.lower() in seen:
            problems.append("%s: %r is a head word and also retired" % (GLOSSARY, word))
    return problems
 def tools_list(retired):
    return sorted({w for w, scope in retired if scope in ("all", "tools")}, key=str.lower)
 def check_copy(retired):
    catalogue = os.environ.get("MESH_CATALOG_DIR")
    if not catalogue:
        print("NOT COMPARED: MESH_CATALOG_DIR is not set, so the catalogue's copy of the list was not read")
        return []
    path = os.path.join(catalogue, "retired-words")
    try:
        with open(path, encoding="utf-8") as handle:
            copy = [l.strip() for l in handle if l.strip() and not l.startswith("#")]
    except OSError as err:
        return ["the catalogue's copy of the retired words cannot be read: %s" % err]
    want = tools_list(retired)
    if sorted(copy, key=str.lower) != want:
        return ["the catalogue's retired-words differs from the glossary: it should list %s" % ", ".join(want)]
    return []
 def main(argv):
    retired, identifiers, heads = glossary()
    if argv[1:2] == ["--list"]:
        scope = argv[2] if len(argv) > 2 else "tools"
        words = tools_list(retired) if scope == "tools" else sorted({w for w, s in retired if s in ("all", scope)})
        print("\n".join(words))
        return 0
    if not retired:
        print("words: the glossary names no retired word on a *Not:* line — the check would pass on anything")
        return 1
    problems = check_unique(retired, heads) + check_retired(retired, identifiers) + check_copy(retired)
    for p in problems:
        print(p)
    if problems:
        print("words: %d problem(s)" % len(problems))
        return 1
    print("words: %d retired words and %d identifiers, none in running prose; %d head words, each once"
          % (len(retired), len(identifiers), len(heads)))
    return 0
 if __name__ == "__main__":
    sys.exit(main(sys.argv))
@@ -11,7 +11,7 @@ Imagine the mesh works as intended. What is different?
 An agent says what it wants — from a terminal, a phone, a message — and the mesh takes it
 from there. It works out which nodes are involved, does the work, and returns a
-result. Nobody opens a terminal, recalls which node holds what, or follows a runbook
+result. Nobody opens a console, recalls which node holds what, or follows a runbook
 written months ago.
 The interface is intent. The mesh handles the rest.
@@ -1,505 +1,126 @@
-# Glossary — the words of the mesh, by domain, and the ones it stopped using
+# Glossary — the words this repository uses, and the ones it stopped using
 One name per thing. This page is the authority; where an older record says something else, that
-record keeps its words and this page says how to read them. It exists because the words kept drifting
+record is being superseded, not this page. It exists because the terms kept drifting in
-in conversation — "control plane", "controller" and "master" for one thing, "substrate" and
+conversation — control plane / controller / master / hub for one thing, substrate / foundation for
-"foundation" for another — and a mesh you cannot name precisely is a mesh two people describe differently. The rule and
+another — and a mesh you cannot name precisely is a mesh two people describe differently.
 its check are [ADR 0244](../02-DECISIONS/0244-the-mesh-is-described-in-domains-and-one-word-names-one-thing.md);
 the domains are drawn in [to-be 49](../03-DESIGN/01-to-be/49-the-mesh-in-domains.md).
-## How to read this page
+## The mesh and its machines
-A **domain** is an area of the mesh that owns a set of concepts: inside it each concept has one word,
+- **node** — a machine in the mesh. There are 0..n of them, and each runs the host agent. A node is
-and the domain decides what that word means. Other domains use the word as it is defined here and never
+  just a machine that has joined; being one implies nothing about what it runs.
-change its meaning. Every word is defined once, in the domain that owns it; a section lists the words
+- **operator account** — the login name of the person who works on a node, stated on the node
-it uses from other domains under *Uses*, with no second definition.
+  record; empty for a machine nobody logs into. Everything the mesh places under a person's home is
-
+  resolved against this account's home and owned by it
 Two fixed lines follow an entry where they apply, and `00-META/checks/words.py` reads them:
 - *Not:* followed by struck-through words — the words this entry replaced. A struck word with no scope
  is retired everywhere; *(hq)* retires it in this repository's prose only; *(tools)* in the
  descriptions of the mesh's tools and seat verbs only. A retired word may be quoted, never used.
 - *Identifier until renamed:* followed by a name in a code span — code that still carries an old name.
  It may stand in a code span and nowhere else until the code is renamed, and then the line goes.
 Nothing else on this page is struck through. A word that means different things in different domains
 is listed under [Homonyms](#homonyms), with the qualified form each domain uses.
 ## Words every domain uses
 - **mesh** — the whole: the nodes, the modules assigned to them, the controller that decides and the
  records it keeps. One mesh per operator; a second mesh is a second everything.
 - **domain** — an area of the mesh that owns a set of concepts and the one word for each, as described
  in the section above ([ADR 0244](../02-DECISIONS/0244-the-mesh-is-described-in-domains-and-one-word-names-one-thing.md)).
  ADR 0006 called seven of them the controller's *contexts*; they carry over as domains under the same
  names, except *observability*, which is now **Health and repair**. Where a domain's records live in
  the controller, the domain owns that store alone ([ADR 0008](../02-DECISIONS/0008-a-context-owns-its-store.md)).
  *Context* in that sense is not used in new writing; the word stays ordinary English, so this is
  checked by review, not by `words.py`.
 - **machine** — any computer: hardware, a virtual machine, before, during or outside its membership of
  the mesh. Prose about the computer itself — its disks, its kernel, the network it sits on, what was on
  it before the mesh — says machine.
 - **node** — a machine the mesh has adopted and owns. A machine becomes a node when it joins
  ([ADR 0004](../02-DECISIONS/0004-a-node-and-how-it-joins.md)), and from then on it runs the node-engine
  and is either **adopted** (the mesh holds what it found there as found) or **converged** (the mesh made
  it what it is) — [ADR 0100](../02-DECISIONS/0100-a-node-in-use-is-adopted-before-it-is-converged.md).
  Prose about a member of the mesh says node. A node is just a machine that has joined; being one
  implies nothing about what it runs.
 - **module** — the unit the mesh assigns: one named thing, defined by its manifest, that a node runs —
  a service, a container, files, packages, its own code — and the tools it serves
  ([ADR 0040](../02-DECISIONS/0040-what-a-module-is.md)). Everything configurable on a node is a module.
 - **seat** — a named role at a scope (node / site / mesh), held by a module assignment, from a **closed
  set** the mesh defines: a claim naming a seat outside the set is refused. A seat may **deliver a
  provision**, and its holder is then the mesh's answer for it when several modules provide it
  ([ADR 0126](../02-DECISIONS/0126-a-module-declares-its-own-seats.md)). The set, with who holds each
  seat, is the overview of what a mesh has ([26 — The seats](../03-DESIGN/01-to-be/26-the-seats.md)).
  A seat carries **verbs** — the tools every holder must serve. A verb added to a held seat is first
  promised as optional, then served, then required ([ADR 0246](../02-DECISIONS/0246-a-seats-new-verb-is-promised-before-it-is-required.md)).
 - **operator** — the person who runs the mesh, and the one the mesh talks to.
  *Not:* ~~master~~ (hq)
 - **person** — any human, as against the mesh acting unattended: *a person's word* releases a held
  delivery, *a person* deletes a consumer's data. The operator is one; the word says that a human, not
  the mesh, acted.
 ## Module — what a module is and declares
 **Purpose.** To say what one module is, in the one document every other domain reads.
 **Recorded in** the catalogue, one manifest per module. **Upstream of** every other domain; its words
 are a published vocabulary, fixed by the manifest's schema. **Decided by** ADR 0040, 0126, 0174, 0188,
 0207, 0236.
 **Uses:** module, seat, provision (Provisioning), data class (Data), health (Health and repair).
 - **manifest** — the file a module is defined by (`module.json`): what it is, what it provides and
  requires, the seats it claims, the resources it declares, its tools, its data and its health. Say
  manifest in prose, not the file's name.
  *Not:* ~~module definition~~ (hq)
 - **resource** — one thing a manifest declares a node must have: a file, a directory, a service, a
  container, a package, a bundle, an archive. A module **declares** resources; the verb *declares* is
  this domain's and means what a manifest states.
 - **claim** — a module taking a spot on a seat: `claims: [{name, scope}]` in a manifest. A mesh-scoped
  exclusive claim is how the mesh says "there is one of me". A foundation seat is named after the role
  it guards: the `mesh-controller`, `postgres` and `nats` modules claim the `mesh-controller`,
  `mesh-store` and `mesh-broker` seats ([ADR 0079](../02-DECISIONS/0079-the-foundation-seats-are-named-after-their-servers.md),
  [ADR 0116](../02-DECISIONS/0116-the-bus-is-built-in-five-steps.md)).
 - **setting** — a value a manifest declares and an assignment gives, one of the two ways a node varies
  a module ([ADR 0174](../02-DECISIONS/0174-a-node-varies-a-module-through-settings-and-kept-regions-never-an-edit.md)).
  What a "flavor" once varied is a setting or a separate module.
  *Not:* ~~flavor~~
 - **kept region** — a marked block in a managed file the mesh writes *into*, where the operator's own
  lines survive every send and are given back when the module goes (ADR 0174). The other way a node
  varies a module.
 - **bundle** — the artifact a module's own code is built into — its tools, a seat's implementation, a
  daemon — in any language the mesh has a toolchain for; never an image. A **tools bundle** speaks MCP to
  the tool runner. One module may declare several
  ([ADR 0188](../02-DECISIONS/0188-a-modules-own-code-is-bundles-in-any-language-and-a-tools-bundle-speaks-mcp-to-the-runtime.md)).
 - **tool** — one capability a module serves through the tool runner, addressed `<module>.<tool>`. A
  seat's **verb** is the same thing carried by a seat rather than a module.
 - **mesh-sdk** — the library a module's own code is written against, including the harness that serves a
  tools bundle to the tool runner. The harness is part of it, not a library of its own.
  *Not:* ~~tools-sdk~~
 - **invokes** — the manifest word for the tools a module calls, `<module>.<tool>` each or `*` for every
  one. A grant on the publish side and nothing else; a module that declares none calls nothing.
 - **upgrade policy** — how a module's new builds reach its nodes: `roll` (one node first, judged, then
  the rest), `together`, or `record` (register the build, send it nowhere)
  ([ADR 0236](../02-DECISIONS/0236-a-build-is-judged-on-its-first-machine-and-put-back-by-something-other-than-itself-and-so-it-rolls-out-unattended.md)).
  The controller's verb `upgrade` shows it.
 ## Core — the mesh's own machinery
 **Purpose.** To keep the controller, the bus, the store and every node's engine running and agreed, so
 every other domain has something to run on. **Recorded by** the controller and the store.
 **Upstream of** every domain but Module; the others use the bus and the store as they are.
 **Decided by** ADR 0005, 0006, 0067, 0106, 0141, 0175, 0227, 0229.
 **Uses:** node, module, seat.
 - **controller** — the component that decides what each node should be, holds the mesh's records, and
  tells nodes over the bus. The relationship is *controller and nodes*, and no node is subordinate: a
  node applies its declaration on its own and survives the control-node dying.
  *Not:* ~~control plane~~, ~~slave~~ (hq), ~~mesh-control~~ (hq)
 - **mesh-controller** — the module that runs the controller. It claims the `mesh-controller` seat at
  mesh scope, which is what makes it singular.
 - **control-node** — the one node that also holds the `mesh-controller` seat. There is exactly one per
  mesh. It is not a separate kind of node — it is a node that additionally runs the controller (and,
  today, the foundation). Lose it and the other nodes keep running what they were last told; they simply
  cannot be told anything new.
 - **node-engine** — the program on every node that applies what the controller declares: it receives
  the node's declaration, writes the files, runs the services and containers, and reports what it did.
  It is the engine, not a module: it owns no file's content, and every file it writes belongs to the
  module that declared it. *Agent* is avoided because that word means a coding agent here. A record
  written before the rename keeps the old name. "The host" is retired in this repository's prose only:
  in the tools' descriptions it is also an SSH server's or a container runtime's own word, so a
  description that means the node-engine by it is found by review.
  *Not:* ~~host agent~~, ~~the host~~ (hq), ~~node host~~
  *Identifier until renamed:* `mesh-host` — the repository, its binary and its service unit
 - **tool runner** — the one program on each node that loads every assigned module's tools bundle and
  serves every tool and every held seat's verb on the subjects the memberships issue; the node-engine
  supervises it as a process beside the services it runs, never a container
  ([ADR 0175](../02-DECISIONS/0175-one-tool-runtime-per-node-serves-every-modules-tools-on-the-host-side.md),
  which called it "node tools"). Its mode on loopback is the mesh MCP server.
  *Not:* ~~node tools~~, ~~tool runtime~~ (hq)
  *Identifier until renamed:* `node-tools` — the module, its unit and its bus account
 - **foundation** — the store and the bus, raised at genesis before any module system exists. The
  foundation is not a third thing beside the store and the bus — it *is* those two, named together.
  *Not:* ~~substrate~~
 - **genesis** — raising the foundation and the controller on an empty mesh, by the one installation
  done by hand ([ADR 0067](../02-DECISIONS/0067-genesis-is-a-pivot.md)).
 - **store** — the one postgres server. It holds the controller's own databases (`inventory`,
  `identity`, `licences`, each owned by one domain, ADR 0008) and every module's own database. One server,
  many databases — never one shared mesh database. Bare *store* means this and nothing else
  (see [Homonyms](#homonyms)).
 - **bus** — the mesh's own nervous system: NATS, one per mesh, carrying every link the mesh has —
  control, declarations, builds, events, tool calls ([ADR 0106](../02-DECISIONS/0106-the-bus-is-nats.md)).
  A module reaches it by requiring `mesh-bus` ([ADR 0128](../02-DECISIONS/0128-the-mesh-bus-is-required-not-ambient.md));
  one that does not require it has no account on it. Held by the `mesh-broker` seat, which is named
  after the role rather than the server, so the server can change without the seat doing so. The `nats`
  module holds it.
 - **the deprecated broker** — the lavinmq module. It was the mesh's bus and is not any more. It keeps
  running as an **ordinary provider** of the `amqp` provision, for modules that need a message broker
  of their own the way something needs a database
  ([ADR 0131](../02-DECISIONS/0131-everything-on-the-mesh-speaks-to-the-broker-seat.md)) — it claims no
  seat, is not foundation, is never raised at genesis, and a mesh that never installs it is complete.
  Say *the deprecated broker*, not *the compatibility broker* (it serves the mesh's own modules, not only
  the predecessor's) and not *the AMQP broker* (naming it after a protocol invites describing the bus by
  contrast with it, which is backwards).
 - **layer** — one of the four levels the mesh is built in, from the bottom: the node-engine, the
  foundation, the controller, the surfaces. The records' `topic: the tiers` and `repos.md` say *tier* for
  this; new prose says layer (see [Homonyms](#homonyms)).
 - **lease** and **epoch** — which controller may send (the lease, held in the bus and renewed), and the
  order of what it sent (the epoch, which a node reads before it accepts a declaration)
  ([ADR 0229](../02-DECISIONS/0229-the-cores-order-is-a-lease-the-store-remembers-and-an-epoch-a-machine-is-sent-once-it-reads-one.md)).
 ## Placement — what runs on which node
 **Purpose.** To decide, send and apply what each node runs, and to say why.
 **Recorded by** the controller's `inventory` database. **Upstream of** Provisioning, Connectivity, Data
 and Health and repair. **Decided by** ADR 0100, 0126, 0176, 0181, 0207, 0221.
 **Uses:** node, machine, module, seat, setting (Module), manifest (Module).
 - **assignment** — a module put on a node, with the settings that node gives it.
 - **scope** — where a seat or a claim holds: `node`, `site` or `mesh`. `node` is also the scope's
  value in a manifest.
 - **capacity** — how many holders a seat takes. A capacity-1 seat is exclusive. A higher-capacity seat
  is a **bench**: several holders coexist. A **replicated** bench has one holder per node, each on record
  and each answering the same, like `mesh-dns-resolver`
  ([ADR 0223](../02-DECISIONS/0223-the-mesh-has-two-resolvers-and-a-machine-lists-only-them.md)). A
  **kinded** bench has holders that are different modules, each claiming one **kind**, and a verb's
  subject carries the kind; `channel` and `intake` are the only ones (ADR 0234).
 - **installed / holding** — a module may be assigned (its package installed, its files placed) without
  holding the seat its family declares; *holding* is being the one — the login shell, the display session
  — on that node ([ADR 0176](../02-DECISIONS/0176-the-login-shell-is-a-node-seat-and-execute-is-its-contract.md)).
  The module that holds a seat is its **holder**.
 - **depends on a seat** — a module needing a seat held on its node by some module, without holding it.
  Derived from the resources it declares, never stated: a `service` depends on `node-service-manager`, a
  `package` on `node-package-manager`, a `container` on `node-container-runtime`
  ([ADR 0207](../02-DECISIONS/0207-a-module-depends-on-the-node-seats-that-apply-its-resources.md)).
  Not a claim: a module claims a seat it holds and declares resources.
 - **declaration** — what the controller sends one node: every resource of every module assigned there,
  composed. The noun is this domain's; what a manifest says is that it *declares* (Module), and a manifest
  is never called a declaration. The controller's verb `plan` previews a node's declaration.
 - **send** — the controller giving a node its declaration. The controller's verb `push` asks for a
  send (of one node, or of every node); prose says send. A git push and a phone's push notification are
  other things (see [Homonyms](#homonyms)).
 - **apply** — the node-engine making its node match its declaration; **reconcile** is doing so again
  until nothing differs.
 - **operator account** — the login name of the person who works on a node, stated on the node record;
  empty for a node nobody logs into. Everything the mesh places under a person's home is resolved
  against this account's home and owned by it
  ([ADR 0181](../02-DECISIONS/0181-the-operator-account-is-a-node-fact-and-a-home-is-a-placement-root.md)).
-  Not a name a manifest carries.
+  Not "the user" (ambiguous with a module's own account) and not a name a definition carries.
 - **control-node** — the one node that also holds the `mesh-controller` seat. There is exactly one
  per mesh. "control-node" is not a separate kind of machine — it is a node that additionally runs
  the controller (and, today, the foundation). Lose it and the other nodes keep running what they
  were last told; they simply cannot be told anything new.
 - ~~master / slave~~, ~~hub / peer~~ — not used. The relationship is *controller and nodes*, and no
  node is subordinate: a node applies declarations on its own and survives the control-node dying.
-## Provisioning — one module serving another
+## What runs the mesh
-**Purpose.** To resolve which module serves a provision for which consumer, and to wire the two.
+- **controller** — the component that decides what each node should be, holds the mesh's records,
-**Recorded by** the controller. **Upstream of** Data; downstream of Module, Placement and Identity.
+  and tells nodes over the broker. Replaces **"control plane"** (borrowed from networking's
-**Decided by** ADR 0027, 0084, 0138, 0225, 0230.
+  control-plane/data-plane, and opaque here).
-**Uses:** module, seat, credential (Identity and access).
+- **mesh-controller** — the module that runs the controller. It **claims** the `mesh-controller`
  seat at mesh scope, which is what makes it singular. Replaces the module name **`mesh-control`**.
  (The git repository has been renamed `mesh-control` -> `mesh-controller` on the forge; the module,
  container and image it produces are `mesh-controller`.)
 - **foundation** — the store and the broker, raised at genesis before any module system exists.
  Replaces **"substrate"** (a biology metaphor that landed for no one). The foundation is not a
  third thing beside the store and broker — it *is* those two, named together.
 - **store** — the one postgres server. It holds the controller's own context databases
  (`inventory`, `identity`, `licences` — a context owns its store, [ADR 0008](../02-DECISIONS/0008-a-context-owns-its-store.md))
  and every module's own database. One server, many databases — never one shared "mesh database".
 - **bus** — the mesh's own nervous system: NATS, one per mesh, carrying every link the mesh has —
  control, declarations, builds, events, tool calls
  ([ADR 0106](../02-DECISIONS/0106-the-bus-is-nats.md)). A module reaches it by requiring
  `mesh-bus` ([ADR 0128](../02-DECISIONS/0128-the-mesh-bus-is-required-not-ambient.md)); one that
  does not require it has no account on it. Held by the `mesh-broker` seat, which is named after
  the *role* rather than the server, so the server can change without the seat doing so.
 - **the deprecated broker** — the lavinmq module. It was the mesh's bus and is not any more. It
  keeps running as an **ordinary provider** of the `amqp` provision, for modules that need a
  message broker of their own the way something needs a database
  ([ADR 0127](../02-DECISIONS/0127-amqp-is-a-provision-not-the-bus.md) (superseded by [ADR 0131](../02-DECISIONS/0131-everything-on-the-mesh-speaks-to-the-broker-seat.md))) — no seat, not foundation,
  never raised at genesis, and a mesh that never installs it is complete.
- **provision** — a service one module `provides` and others `require`; the mesh resolves a provider
+  Say *the deprecated broker*, not "the compatibility broker" (it serves the mesh's own modules,
-  and wires the two with an endpoint and a credential. A provision is a service you offer, a seat is a
+  not only the predecessor's) and not "the AMQP broker" (naming it after a protocol invites
-  role you occupy, and the two meet where a seat delivers a provision: occupying the seat is what makes
+  describing the bus by contrast with it, which is backwards: the bus is the mesh's nervous
-  a module *the* provider of it.
+  system and this is a module).
 - **provider** and **consumer** — the module that provides a provision, and the module that requires
  it. Which of several providers serves a consumer is resolved
  ([ADR 0084](../02-DECISIONS/0084-which-provider-serves-a-consumer.md)).
 - **pin** — a person's choice of provider for a consumer, which resolution then respects.
 - **endpoint** — where a consumer reaches its provider; an assignment binds it and says how far it
  reaches ([ADR 0138](../02-DECISIONS/0138-an-assignment-binds-an-endpoint-and-says-how-far-it-reaches.md)).
 - **retire** — a provider stops serving a consumer the mesh no longer asks for; what it kept is deleted
  only by a person ([ADR 0230](../02-DECISIONS/0230-a-consumer-the-mesh-stops-asking-for-is-retired-and-deleted-only-by-a-person.md)).
-## Identity and access — who may do what
+## What the mesh stores and serves
-**Purpose.** To issue, hold, rotate and check the credentials and grants by which modules, nodes, agents
+- **package** — what code resolves when it is **compiled**: an npm/cargo/pypi dependency, by
-and the operator act. **Recorded by** the controller's `identity` and `licences` databases and the vault.
+  **version**. Served by the **package-registry** (gitea). Only a builder talks to it.
-**Upstream of** Provisioning, Change and delivery, and Operator and conversation.
+- **artifact** — anything a build produces and the mesh delivers to a machine by **digest**: an
-**Decided by** ADR 0085, 0113, 0183, 0225, 0234.
+  `image`, a mirrored `upstream` image, a `bundle` of the module's own code, an `archive`. Served by
-**Uses:** module, node, operator, consumer (Provisioning).
+  the **artifact-store**, an OCI registry that holds every kind as content-addressed blobs
 - **credential** — anything that proves an identity: a password, a key, a token. A **pair credential**
  is the two ends of one credential, the consumer's and the provider's.
 - **secret** — a credential or other value the vault keeps sealed and the node-engine unseals into a
  file at apply ([ADR 0085](../02-DECISIONS/0085-a-secret-is-a-provision.md)).
 - **vault** — the module that owns every secret (`mesh-vault`,
  [24 — The secrets vault](../03-DESIGN/01-to-be/24-the-secrets-vault.md)).
 - **grant** — what an identity may call or reach, bounded by the provisions it requires
  ([ADR 0225](../02-DECISIONS/0225-a-consumers-identity-is-bounded-by-the-provision-it-requires.md)).
 - **bus account** and **membership** — a module's or a node's account on the bus, and the subjects it
  is issued. The bus server calls its accounts *users*; the mesh says bus account.
 - **rotate** — replacing a credential without a consumer holding one the provider does not know.
 - **licence** — a model-access account the licence manager holds and **binds** to a consumer, the
  coding agent on a node ([ADR 0183](../02-DECISIONS/0183-the-anthropic-licence-manager-is-a-module-and-hands-tokens-to-the-agent-over-the-bus.md)).
  Taking a consumer off a licence is **unbinding** it; the licence manager's verb for it is still
  `release`, an identifier to rename.
 - **proof** — what an authorising answer carries: a verified sender, a one-time code, a security key's
  touch (ADR 0234). How much proof a kind of ask needs is its **assurance level**.
 ## Change and 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 walk). **Downstream of** Module, Core, Health and repair and Data.
 **Decided by** ADR 0162, 0218, 0236, 0237, 0238, 0239.
 **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**
  (`mesh/merge-gate`, the build seat's composed check of the modules the change touches) and the
  **repository check** (`mesh/repo-check`, the repository's own `merge-check.sh`)
  ([ADR 0238](../02-DECISIONS/0238-a-commit-is-the-build-at-hand-one-commit-one-change-plan-checked-off-the-trunk-and-published-only-on-it.md)).
 - **build seat** — the seat whose holder builds modules, `node-build-agent`; its holder on a node is the
  **builder**. Any node may hold the seat, so there is no build node by nature
  ([ADR 0237](../02-DECISIONS/0237-a-change-is-judged-against-the-mesh-that-runs-before-it-merges-on-the-build-seat.md)).
  *Not:* ~~build machine~~
 - **build queue** — the controller's queue of builds to run; one entry in it is a **build request**.
  The queue's verbs still say *ask* for an entry; the conversation's ask is another thing
  (see [Homonyms](#homonyms)).
 - **package** — what code resolves when it is **compiled**: an npm/cargo/pypi dependency, by **version**.
  Served by the **package-registry** (gitea). Only a builder talks to it.
 - **artifact** — anything a build produces and the mesh delivers to a node by **digest**: an `image`, a
  mirrored `upstream` image, a `bundle` of the module's own code, an `archive`. Served by the
  **artifact store**, an OCI registry that holds every kind as content-addressed blobs
  ([ADR 0156](../02-DECISIONS/0156-an-artifact-is-what-a-build-produces-and-the-store-is-named-for-its-scope.md)).
-  An image is one kind of artifact, and a module is not an image. A package and an artifact are two
+  Every node pulls from it. An image is one kind of artifact, and a module is not an image.
-  protocols, not one store being weak ([ADR 0075](../02-DECISIONS/0075-two-stores-and-which-provides-what.md)).
+- These are two protocols, not one store being weak — see [ADR 0075](../02-DECISIONS/0075-two-stores-and-which-provides-what.md).
 - **catalogue** — what the mesh holds of every module, at which commit; and the repository the
  modules live in. `mesh-catalog` and `catalog_modules` are identifiers and keep their spelling.
  *Not:* ~~catalog~~ (hq)
 - **delivery** — one commit in one repository on its way to the nodes, from its pull request's head
  being announced to delivered, failed, superseded or stopped: one pull request, one status, one note
  ([ADR 0239](../02-DECISIONS/0239-a-delivery-is-owned-by-the-mesh-delivery-module-and-runs-from-commit-to-delivered.md)).
  Its states are one table (`proposed`, `checked`, `ready` or `rejected`, `published`, `delivering`,
  `held`, and the final four). Not *change* (a diff). *Pipeline* is the predecessor's build-and-deploy
  mechanism, which the as-is designs describe; it is never a word for a delivery.
  *Not:* ~~deployment~~ (hq)
 - **delivery group** — two or more deliveries sharing a pull request head branch name across the mesh's
  repositories, delivered as one unit in an order declared (`after:`) or inferred by the planner. One
  level: a group holds deliveries, never groups. Its state is derived from its members, never set.
 - **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.
  *Not:* ~~change plan~~, ~~release plan~~
 - **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.
 - **walk** — the controller's sending of one trunk commit's builds across nodes, tier by tier, one node
  first and judged at the first-node gate, then the rest (ADR 0236). A primitive the delivering stage
  asks for, not an object anyone manages. A **tier** is one step of a walk: a module, then the modules
  built against it. The controller's verb `plans` lists the walks. Walking is not a noun of its own:
  a module *rolls out* by its `roll` policy.
  *Not:* ~~rollout~~ (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)).
 - **release** — a person's word that a held delivery goes on; the verb `mesh-delivery.release`. Used in
  this sense only.
 - **rollback** — putting a node back on the build it ran before, by something other than the build being
  judged (a witness, ADR 0236).
 - **the lab**, **scenario**, **replay** — a real mesh raised to run a change against before it reaches
  nodes; what a lab run declares; and a recorded failure run again to prove a fix (ADR 0016, ADR 0237).
-## Health and repair — what is wrong, and putting it right
+## How modules relate to the mesh
-**Purpose.** To notice what is wrong with the mesh, say it once, repair what may be repaired unattended,
+- **seat** — a named role at a scope (node / site / mesh), held by a module assignment, from a
-and record what was done by hand. **Recorded by** the controller's condition store.
+  **closed set** the mesh defines: a claim naming a seat outside the set is refused. A seat may
-**Upstream of** Change and delivery (the first-node gate) and Operator and conversation (a condition
+  **deliver a provision**, and its holder is then the mesh's answer for it when several modules
-becomes a message). **Decided by** ADR 0227, 0231, 0240.
+  provide it ([ADR 0126](../02-DECISIONS/0126-a-module-declares-its-own-seats.md) (superseding [ADR 0110](../02-DECISIONS/0110-a-seat-is-a-module-assignment-from-a-closed-set.md))).
-**Uses:** node, module, node-engine (Core).
+  The set, with who holds each seat, is the overview of what a mesh has
  ([26 — The seats](../03-DESIGN/01-to-be/26-the-seats.md)). A seat has a **capacity**: a
  capacity-1 seat is exclusive (one holder); a higher-capacity seat is a **bench** (several holders
  coexist).
 - **claim** — a module taking a spot on a seat. `claims: [{name, scope}]` in a manifest. A
  mesh-scoped exclusive claim is how the mesh says "there is one of me". A foundation seat is
  named after the server it guards: the `mesh-controller`, `postgres` and `lavinmq` modules claim
  the `mesh-controller`, `mesh-store` and `mesh-broker` seats ([ADR 0079](../02-DECISIONS/0079-the-foundation-seats-are-named-after-their-servers.md)).
 - **depends on a seat** — a module needing a seat held on its node by some module, without holding
  it. Derived from the resources it declares, never stated: a `service` depends on
  `node-service-manager`, a `package` on `node-package-manager`, a `container` on
  `node-container-runtime` ([ADR 0207](../02-DECISIONS/0207-a-module-depends-on-the-node-seats-that-apply-its-resources.md)).
  Not a claim: a module **claims** a seat it holds and **declares** resources. Nothing claims a
  package.
 - **provision** — a service one module `provides` and others `require`; the mesh resolves a provider
  and wires the two with an endpoint and a credential. A provision is a service you offer, a seat
  is a role you occupy, and the two meet where a seat delivers a provision: occupying the seat is
  what makes a module *the* provider of it.
- **health** — a module's or a core component's statement of how it is alive and ready, which the
+## The surfaces
  node-engine judges ([ADR 0240](../02-DECISIONS/0240-a-module-says-how-it-is-healthy-and-the-node-engine-judges-it.md)).
 - **probe** — one look at one thing's health, run by whoever owns the verdict; what a probe returns is a
  **finding**, before it becomes a condition.
 - **signal** and **watchdog** — something that must keep happening (a heartbeat, a report after a send),
  and the watcher that raises a condition when it stops (to-be 45 §3).
 - **condition** — one open fact about something the mesh owns that is wrong, with a key and a severity;
  raised and cleared only by observation
  ([ADR 0231](../02-DECISIONS/0231-a-healer-acts-on-what-observation-raised-and-only-observation-says-it-worked.md)).
  What a wrapped dashboard raises is its own; the mesh's notion is a condition.
  *Not:* ~~alert~~ (hq)
 - **self-check** — the controller's own examination of the mesh, run on demand and on a schedule
  (to-be 45 §4). Its verb is `doctor`, an identifier; prose says self-check.
  *Not:* ~~doctor~~ (hq)
 - **healer** — a registered response to one condition kind: its **repair** (the ordinary path again),
  its **budget**, its back-off and its brake. A healer may not withdraw, delete or recreate data.
 - **drill** — something broken on purpose to see the mesh raise and clear its condition; a drill is
  never counted as a repair.
 - **hand-act** — a repair a person made by hand, recorded so the mesh knows it happened.
 - **witness** — what rolls a core component back when its new build does not become healthy: never the
  component itself (to-be 45 §8).
-## Data — what the mesh keeps, and getting it back
+- **console** — the module (`mesh-console`) that puts the mesh's tools in front of whoever is on a
-
+  machine: an MCP endpoint on the machine's loopback for an agent, the same endpoint for a person. It
-**Purpose.** To know every item of data a module holds, how precious it is, and to keep it recoverable.
+  is assigned like any module, holds a credential the mesh minted, and calls tools under a grant its
-**Recorded by** the manifests' `data` declarations and every node's `node-backup` seat.
+  manifest declares (`invokes`). Loopback is the authority boundary: whoever is on the machine owns the
-**Upstream of** Change and delivery and Health and repair. **Decided by** ADR 0232, 0233, 0235.
+  mesh there ([ADR 0152](../02-DECISIONS/0152-the-operators-surface-is-a-module-the-console.md)).
-**Uses:** module, node, provider and consumer (Provisioning), person.
+  Not "the tool bridge", "the brain" or "the MCP server" — those name the predecessor's program or a
-
+  protocol, and the console is a module.
- **data class** — how precious an item of data is, ranked by the operator: `irreplaceable`,
+- **invokes** — the manifest word for the tools a module calls, `<module>.<tool>` each or `*` for
-  `valuable`, `rebuildable`, `cache`; and `none` for a provision that keeps nothing of anybody's
+  every one. A grant on the publish side and nothing else; a module that declares none calls nothing.
  ([ADR 0233](../02-DECISIONS/0233-a-module-declares-the-data-it-holds-and-the-mesh-protects-and-watches-it-from-that.md)).
 - **backup** — a copy kept elsewhere by the node's `node-backup` holder; **restore point** — one backup
  at one moment; **restore** — bringing it back beside the live data, never over it.
 - **stream snapshot** — the bus's own backup of each stream, taken by the module holding `mesh-broker`
  ([ADR 0235](../02-DECISIONS/0235-the-bus-is-backed-up-by-its-own-snapshot-of-each-stream.md)).
 - **sticky binding** — a consumer's tie to the data a provider keeps for it, which moves only by a
  person ([ADR 0232](../02-DECISIONS/0232-a-binding-to-a-consumers-data-moves-only-by-a-person.md)).
 ## Connectivity — how nodes and modules reach one another
 **Purpose.** To make every node and module reachable by name where it should be, and unreachable where
 it should not. **Recorded by** the controller. **Upstream of** Provisioning and Health and repair.
 **Decided by** ADR 0007, 0117, 0138, 0223, 0226, 0247.
 **Uses:** node, machine, assignment and endpoint.
 - **private network** — the mesh's own encrypted network between its nodes, on which every node has an
  address and a mesh name ([ADR 0226](../02-DECISIONS/0226-the-private-network-is-assigned-by-its-own-name-and-the-proxy-names-its-public-issuer.md)).
  The network the machine sits on without it is the **underlay**.
  *Not:* ~~overlay~~ (hq)
 - **anchor** and **hub** — the roles a node plays for the private network: the anchor is reachable from
  outside and every node reaches it; a hub relays for nodes that cannot reach each other directly.
 - **resolver** — a seat holder that answers the mesh's names; a node lists only the mesh's resolvers
  (ADR 0223), or, where it holds one, its own resolver, which asks them. **uplink** — a node's
  connection to the outside network, a seat ([ADR 0117](../02-DECISIONS/0117-a-machines-uplink-is-a-seat.md)). **hostname** — a node's own name,
  a seat.
 - **split DNS** — resolving names by domain on one machine: a VPN's domains through the VPN's servers
  over its link, every other name through the mesh's resolvers. The provision `split-dns`, provided by
  the holder of the node seat `node-resolver`, the machine's **own resolver**, which exists only where
  something requires it ([ADR 0247](../02-DECISIONS/0247-a-machine-with-a-vpn-client-routes-names-by-domain-through-a-resolver-of-its-own.md)).
 - **proxy** and **public name** — the module that answers a public name and forwards it to an
  endpoint on the private network.
 - **packet filter** — what the mesh enforces on a node about which packets pass, the
  `node-packet-filter` seat and its verb `rules`. A **found firewall** is a program the mesh found on a
  machine and keeps retired or in force; *firewall* says that, and a wrapped program's firewall is its own.
 - **intrusion prevention** and **ban** — refusing a source that misbehaved, and the refusal itself.
 - **reach** — how far an assignment's endpoint may be reached from: the node, the private network, or
  the outside (ADR 0138).
 ## Operator and conversation — the person the mesh works for
 **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 and the controller (authorising asks).
 **Downstream of** Health and repair, Change and 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.
 **Uses:** operator, person, proof (Identity and access), release (Change and 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`,
  `mesh_machine`, `mesh_search`, `mesh_describe` and `mesh_call`. It is the tool runner's loopback mode,
  not a module of its own. "Console" suggested a terminal or a shell, and the module `mesh-console` it
  once named no longer exists; "the tool bridge" and "the brain" named the predecessor's program.
  *Not:* ~~console~~ (hq), ~~mesh-console~~, ~~tool bridge~~
 - **channel / intake** — the two kinded benches the mesh talks to its operator through: `channel`
  sends, `intake` turns what arrives into one envelope. A holder of either declares **capabilities** from
  the fixed vocabulary `channel-capabilities/1`. Not *notifier* (that is the desktop's node seat, one
  holder of kind `desktop`) and not *bot* (that is one service's account).
 - **router** — the module that holds the `operator-channel` seat, orders the channels and checks every
  sender ([ADR 0234](../02-DECISIONS/0234-the-mesh-holds-a-conversation-with-its-operator.md)).
 - **ask** — a request for the operator's input, of a declared kind (yes-no, one-of, text, number,
  date, acknowledge). An **authorising ask** is one whose answer performs an action; the controller
  holds it and checks its proofs (ADR 0234).
 - **operator message / input** — what arrives on `intake`, once the router has checked the sender
  against the controller's list of the operator's identities: a **trusted** one is an operator message,
  addressed to an agent by `@name` or thread or else to the **responder** (`@mesh`, the router's own
  participant, which answers from read verbs); anything else is **untrusted input** — data, never
  instructions.
 - **reference** — an opaque token in a message's words standing for a detail the content rule keeps out
  of them (a path, an address); opened with `detail` only on a `private` channel or through the mesh MCP server.
 - **agent** — a coding agent: the operator's, or one the mesh runs. Not the node-engine, and not the
  build seat's holder, whose seat name `node-build-agent` is an identifier to rename.
 ## The record — how this repository works
 Not a domain of the mesh but of the way it is built, listed because its words meet the mesh's.
 **Recorded in** this repository. **Decided by** ADR 0019, 0080, 0244.
 - **research effort**, **graduation**, **hand-off**, **playbook** — an investigation in `01-RESEARCH/`;
  its closing into a decision and a design; a design given to a code repository; a documented workflow
  in `00-META/process/`.
 - **decision record** — one numbered file in `02-DECISIONS/`, never rewritten: **superseded** by a later
  record, or corrected by a marked **progressive insight**. Always qualified in this repository: bare
  *record* has other meanings (see [Homonyms](#homonyms)).
 - **design** — a document in `03-DESIGN/`: **as-is** (what runs) or **to-be** (what is being built).
 - **issue** — a report in `04-ISSUES/` of something wrong with the mesh at the level of design or
  governance; an **incident** is a past event that taught a rule.
 - **hq check** — one of `00-META/checks/`, run by `merge-check.sh` as this repository's check.
 ## Homonyms
 A word below means different things in different domains. In a governing document it is never bare;
 it is always the qualified form. **Checked by review, not by `words.py`:** a word list cannot tell one
 sense from another, so the reviewer looks for the bare word in the diff. Where a homonym is settled by
 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 commit across nodes | **walk** (verb `plans`) | Change and delivery |
 | | a step a person starts, like the bus's | **planned step** | Core |
 | 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 |
 | | taking a consumer off a licence | **unbind** (verb `release`, to rename) | Identity and access |
 | gate | the judgement on a delivery's first node | **first-node gate** | Change and delivery |
 | | the pull request status | **merge gate** | Change and 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 walk | **tier** | Change and delivery |
 | | how much proof an ask needs | **assurance level** | 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 |
 | store | the one database server | **store** | Core |
 | | the OCI registry | **artifact store** | Change and delivery |
 | | a node's own copy of its last declaration | **last declaration** | Placement |
 | record | a numbered decision | **decision record** | The record |
 | | the knowledge base agents search first | **the record** (the `records` module) | Operator and conversation |
 | | the upgrade policy that sends nowhere | `record` | Module |
 | 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 |
 | | 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 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 |
 | deploy | the per-node part of a delivery plan | **deploy plan** | Change and delivery |
 | | a wrapped program's own deploy | its own word | — |
 ## How this page is kept
-A new word for an existing thing lands here first, in the domain that owns it, in the same change that
+A new name for an existing thing lands here first, in the same change that introduces it in code. A
-introduces it in code. A word moves to another domain only with a decision record. A retired word goes
+record under `02-DECISIONS/` keeps whatever word it was written with — those are immutable — so a
-on a *Not:* line and nowhere else on this page, and `words.py` then fails on it in running prose. A
+term retired here may still appear there, and the mapping above is how to read it.
-record under `02-DECISIONS/` keeps whatever word it was written with — those are immutable — so a word
+
-retired here may still appear there, and the *Not:* lines are how to read it.
+## The operator's machine
 - **node tools** — the one tool runtime per node, a host-side process the host supervises, that loads
  every assigned module's tools bundle and serves every tool and held seat's verb on the subjects the
  memberships issue; its serving mode on loopback is what was called **the console**
  ([ADR 0175](../02-DECISIONS/0175-one-tool-runtime-per-node-serves-every-modules-tools-on-the-host-side.md)).
  Replaces **"console"** as the module's name; *console* remains the word for the person's end of it.
 - **bundle** — the artifact a module's own code is built into — its tools, a seat's implementation, a daemon — in any language the mesh has a toolchain for, interpreted or compiled; never an image. One module may declare several ([ADR 0188](../02-DECISIONS/0188-a-modules-own-code-is-bundles-in-any-language-and-a-tools-bundle-speaks-mcp-to-the-runtime.md)).
 - **kept region** — a marked block in a managed file the mesh writes *into*, where the operator's own
  lines survive every push and are given back when the module goes
  ([ADR 0174](../02-DECISIONS/0174-a-node-varies-a-module-through-settings-and-kept-regions-never-an-edit.md)).
  One of the two ways a node varies a module; the other is a **setting**.
 - **installed / holding** — a module may be assigned (its package installed, its files placed) without
  holding the seat its family declares; *holding* is being the one — the login shell, the display
  session — on that node ([ADR 0176](../02-DECISIONS/0176-the-login-shell-is-a-node-seat-and-execute-is-its-contract.md)).
 - ~~flavor~~ — not used. What a flavor varied is a setting or a separate module.
 **How it is checked** ([ADR 0244](../02-DECISIONS/0244-the-mesh-is-described-in-domains-and-one-word-names-one-thing.md)):
 `python3 00-META/checks/words.py`, run by `merge-check.sh` on every pull request, fails on a retired
 word or a bare identifier in running prose in `00-META/`, `03-DESIGN/`, `AGENTS.md`, `README.md`, and
 research and issues dated from 2026-10-07 — code spans, quotations and link targets excepted — and on a
 head word that heads two entries or is also retired. The words retired with no scope or with *(tools)*
 are copied into the catalogue as `retired-words`, whose own repository check holds the descriptions of
 the mesh's tools to them; a change here that retires such a word changes that copy in the same delivery.
 Homonyms are checked by review.
@@ -11,7 +11,7 @@ updated: 2026-08-22
 An agent states an intent — in words, from wherever they already are — and the mesh
 carries it out. It takes the request in, works out what it means, does the work across
-whichever nodes it needs, and returns a result. No terminal to open, no runbook to follow,
+whichever nodes it needs, and returns a result. No console to open, no runbook to follow,
 no remembering which node holds which thing.
 Not automation, which does what it was told to do in advance. Self-control: the mesh
@@ -42,11 +42,7 @@ incident someone must **clear**.
 2. Investigate in `01-diagnosis.md` in the same folder — the trail, dated, including what was
   ruled out. Move `status:` to `diagnosing`, then `located` once the owner is known.
 3. Resolve. Set `status: resolved`, fill `fixed-by:`, and if the root cause was a design gap,
-   run playbook [02](02-graduation.md) and fill `amended-design:`. **A core issue** — its `located-in`
+   run playbook [02](02-graduation.md) and fill `amended-design:`.
   names the controller, the node-engine, the tool runner, the SDK, or the catalogue's bus, forge or build
   agent — resolves with `replay:`, the id of its replay in mesh-lab's replays register, proved to fail on
   the commit before the fix and pass on it, or with `replay-none:` saying why none is possible
   ([ADR 0237](../../02-DECISIONS/0237-a-change-is-judged-against-the-mesh-that-runs-before-it-merges-on-the-build-seat.md); `cycle.py` checks it).
 ## Rules
@@ -52,7 +52,7 @@ Three questions, answered from the machine:
   the container env-file: [/var/lib/postgres/superuser.env]
   ```
-   The node-engine fills the hole on the machine, which is the only place both halves exist — the mesh
+   The host fills the hole on the machine, which is the only place both halves exist — the mesh
   discarded the value
   ([credentials and their rotation](../../03-DESIGN/01-to-be/13-credentials-and-their-rotation.md)).
   A **provisioner** is the exception: it reads a password file, so it mounts the `.secret`
@@ -89,7 +89,7 @@ Six attempts, one real bug. Recorded because the ratio is the lesson: **the mesh
 time and the scaffolding was not.**
 - A shape existed in the language and no host implemented it, so every declaration carrying one
-  was refused whole — correctly, and the node-engine said exactly that. **Nobody was reading the node-engine's
+  was refused whole — correctly, and the host said exactly that. **Nobody was reading the host's
  log.** Read it first; it is the only place that says why a machine did nothing.
 - A blind find-and-replace renamed a provision in quotes and missed the same word bare.
 - A command was tested only for the invocations that should fail, so it rejected every real one
@@ -99,7 +99,7 @@ time and the scaffolding was not.**
 ## Rules
- **Read the node-engine's log before theorising.** A declaration that was sent and not applied says so
+- **Read the host's log before theorising.** A declaration that was sent and not applied says so
  there and nowhere else.
 - **A failing test is kept, not skipped.** It is the reproduction.
 - **Never rotate during an adoption.** Rotation is a separate act, afterwards, deliberately.
@@ -30,7 +30,7 @@ one-for-one — `mesh-catalog`, `mesh-sdk` and `mesh-tools` exist where the tabl
 | Repository | Tier | Holds |
 |---|---|---|
-| `mesh-host` | 0 | **exists.** The node-engine — one statically linked binary, requiring nothing present ([ADR 0005](../02-DECISIONS/0005-the-node-host.md)) |
+| `mesh-host` | 0 | **exists.** The node host — one statically linked binary, requiring nothing present ([ADR 0005](../02-DECISIONS/0005-the-node-host.md)) |
 | `mesh-foundation` | 1 | the four pinned services, as declarations |
 | `mesh-controller` | 2 | **exists.** The controller and its contexts — one of seven built ([ADR 0006](../02-DECISIONS/0006-the-substrate-and-the-control-plane.md)) |
 | `mesh-surfaces` | 3 | tools, web, cli |
@@ -1,5 +1,5 @@
 ---
-status: graduated
+status: active
 initiated: 2026-10-04
 touches:
  - 04-ISSUES/187-the-mesh-tells-nobody-when-it-stops-working/00-report.md
@@ -10,17 +10,7 @@ touches:
  - 02-DECISIONS/0208-the-graphical-session-is-one-module-per-piece-on-the-meshs-seats.md
  - 02-DECISIONS/0210-a-tools-configuration-is-its-seat-holders-and-every-other-module-extends-it-through-the-seat.md
  - 03-DESIGN/01-to-be/32-what-a-module-declares.md
-  - 03-DESIGN/01-to-be/45-a-core-that-cannot-fail-silently.md
+became: []
  - 02-DECISIONS/0190-a-seats-work-is-shared-by-its-holders-and-building-is-the-first-such-role.md
  - 02-DECISIONS/0212-a-seat-says-what-it-receives-and-the-machines-hotkeys-are-a-seat.md
  - 02-DECISIONS/0223-the-mesh-has-two-resolvers-and-a-machine-lists-only-them.md
  - 02-DECISIONS/0227-the-core-holds-nine-rules-each-checked-and-is-built-to-them-in-six-phases.md
  - 02-DECISIONS/0228-a-value-given-by-hand-lives-only-until-its-modules-first-good-start.md
  - 02-DECISIONS/0230-a-consumer-the-mesh-stops-asking-for-is-retired-and-deleted-only-by-a-person.md
  - 02-DECISIONS/0232-a-binding-to-a-consumers-data-moves-only-by-a-person.md
 became:
  - 02-DECISIONS/0234-the-mesh-holds-a-conversation-with-its-operator.md
  - 03-DESIGN/01-to-be/46-the-conversation-with-the-operator.md
 ---
 # 028 — The mesh's output channel
@@ -42,34 +32,7 @@ The effort looks at:
 - **the life of a message:** deduplicated while it holds, resolved when it stops, acknowledged or
  silenced by the operator;
 - **the watcher's watcher:** who tells the operator when the parts that would tell them are the
-  ones that failed;
+  ones that failed.
 - **the conversation** (widened 2026-10-06): the mesh, its modules and its agents send messages and
  **asks** (a question, a choice, a value, an approval), and the operator answers or writes first, over
  channels chosen by their declared **capabilities** and by the operator's **work context**. Inputs
  from outside (a mail arriving) share the same envelope;
 - **asks that authorise:** one layer on top, for the answers that perform an action. These are checked
  by the controller, and allowed only on channels whose capabilities prove that the operator answered.
 ### Why this effort widened rather than a new one opened
 On 2026-10-06 the operator asked for these:
 - approving and rejecting through Telegram;
 - a generic shape in which Telegram simply holds a seat;
 - input triggers alongside output channels;
 - capabilities that decide which actions may travel on which channel;
 - the work context as a factor in choosing the channel;
 - asks that are not about permission at all.
 That could have opened a new effort. It did not, because:
 - every part of it hangs on this effort's open questions: Q1 (where a channel attaches), Q4
  (presence), Q7 (answering back) and Q8 (what may leave);
 - ADR 0227 kept answering back open **here**, and said this effort's graduation amends to-be 45 §5;
 - an answer belongs to the message or ask this seat sends. Splitting them would leave two efforts each
  owning half of one conversation.
 Input that is not an answer (a mail arriving, a webhook) shares the envelope and the seat shape, and
 is designed here only as far as that shape. Its consumers are later work.
 ## Why
@@ -106,19 +69,3 @@ for the mesh, sources that call it, and channels that deliver.
 2. [The channels](02-the-channels.md): the candidates, Telegram first, weighed on the same questions.
 3. [Open questions](03-open-questions.md): the seat, routing, life of a message, the watcher's
   watcher, what may leave the mesh.
 4. [Telegram, as the first holder](04-telegram-as-the-first-holder.md): making the bot, the bot
   API's limits and semantics, what Telegram sees, and ten defects in the built code.
 5. [The other holders, on the same axes](05-the-other-holders-on-the-same-axes.md): ntfy, Matrix,
   Pushover, Gotify, mail, Signal, SMS and a dead-man service, as away channel and as the watcher's
   path.
 6. [A conversation with the operator](06-a-conversation-with-the-operator.md): messages, asks and
   operator messages; asks' kinds and life; the kinded benches `channel` and `intake`; the capability
   vocabulary; agents as participants; the migration.
 7. [The work context, and the desk](07-the-work-context-and-the-desk.md): the signals, the routing
   by context and its escalation, presence kept inside the mesh, and the desk as a full participant
   (notification actions, the launcher's prompt).
 8. [Asks that authorise](08-asks-that-authorise.md): the actions that need a person, the trust
   capabilities, the three proofs and the three tiers, the controller's checks, why the desk needs a
   factor, and what a compromise can reach.
 9. [A proposed decision](09-a-proposed-decision.md): the recommendation, the operator's steps, the
   tables, and a record ready for graduation.
@@ -1,7 +1,6 @@
 # 03 — Open questions
-Each question names the options seen so far. None is decided here. Q1 and Q7 are taken further in
+Each question names the options seen so far. None is decided here.
 [06](06-a-conversation-with-the-operator.md) and [08](08-asks-that-authorise.md).
 ## Q1. The seat
@@ -1,222 +0,0 @@
 # 04 — Telegram, as the first holder of a channel
 Telegram was the operator's first required channel ([02](02-the-channels.md)) and it is built:
 the output seat's holder carries a Telegram client, and so does the watcher's watcher (to-be 45 §5).
 Neither is configured, because no bot exists yet. This document is what the operator needs to make one,
 what the mesh's use of the bot API must respect, and what the built code gets wrong against it.
 [06](06-a-conversation-with-the-operator.md) makes Telegram one holder of a generic channel seat rather
 than the subject of the design. Everything here stays true under that shape: it is the first holder's
 analysis.
 Facts are as of 2026-10-06, Bot API 10.3 (2026-08-24). Sources are listed at the end.
 ## What the mesh uses from Telegram
 Two programs send, and neither reads anything back yet:
 - **The output seat's holder**, on the control node. It sends a message when a condition is raised,
  says it again as a reminder, and edits the first message in place when the condition clears.
 - **The watcher's watcher**, on a machine that is not the control node. It sends straight to the bot
  API over HTTPS when the controller's self-check or the bus has been silent past its bound.
 Each holds a **bot token** as its own secret, issued outside the mesh (ADR 0228, `issued-by: outside`),
 and a **chat id** as a setting. Each sends plain text: no `parse_mode`, so no markup to escape and none
 to inject.
 ## Making the bot
 Telegram has no developer console. A bot is made by talking to Telegram's own bot, BotFather, from an
 ordinary Telegram account.
 - **An account is required, and an account needs a phone number.** There is no other sign-up. The
  number can be a virtual one bought on Telegram's own marketplace, at a price that makes it
  irrelevant here.
 - **`/newbot`** asks for a display name and a username. The username is 5–32 characters of Latin
  letters, digits and underscores, must end in `bot`, and cannot be changed later.
 - BotFather answers with the **token**: digits, a colon, then a key. Anyone holding it controls the bot.
 - **`/token`** issues a new token for the bot. The old one stops working at once. This is the rotation
  path, and it is the only one.
 - **`/setjoingroups` → Disable** stops anyone adding the bot to a group. The mesh's bot talks to one
  person; a group is only a way for someone else to see what it says.
 - **Privacy mode** (`/setprivacy`) governs what a bot sees **in groups**: with it on, only commands
  meant for it, replies to it and service messages. In a private chat a bot sees everything the person
  writes. With groups disabled, privacy mode does not matter; leave it on.
 ### A bot cannot speak first
 A bot cannot open a conversation. Until the person presses **Start** in the bot's chat, every send to
 them fails with a "Forbidden" error. So the operator presses Start once, on each bot.
 ### Finding the chat id, safely
 In a private chat the chat id equals the person's user id. There are two ways to learn it:
 - **Read `getUpdates` once by hand.** After pressing Start, a call to `getUpdates` returns the `/start`
  message with the chat's id. It works today. Its two weaknesses: the token appears in a command line
  (and so in a shell's history) unless read from a file, and it trusts that the `/start` it sees is the
  operator's. A bot's username is public, and anyone who finds it can press Start too.
 - **A linking verb with a one-time code.** The holder makes a short code and answers with a deep link
  (`https://t.me/<bot>?start=<code>`). The operator opens it on the phone; Telegram sends `/start <code>`.
  The holder reads it by `getUpdates`, and binds **that** chat and **that** user id only if the code
  matches and is fresh. This proves the chat belongs to whoever held the code, and it never shows the
  token to anyone. It needs the holder to read updates, which approvals need anyway
  ([08](08-asks-that-authorise.md)).
 The second is the one to build. The first is the stop-gap until it exists.
 ### One bot or two
 The holder and the watcher each have their own secret. They can hold the same token or two.
 **Two bots are better:**
 - Revoking one does not silence the other. The watcher exists for the day the rest is broken, and
  that day must not also be the day its token was rotated away.
 - The phone shows which program spoke.
 - **Only one program may read a bot's updates.** Two concurrent `getUpdates` callers on one token make
  Telegram answer the older with HTTP 409, "terminated by other getUpdates request". The moment the
  holder reads answers, the watcher could no longer share its token with anything that reads.
 ## The bot API, as the mesh uses it
 ### Limits
 - **Rate.** Telegram's FAQ: "In a single chat, avoid sending more than one message per second." In a
  group, 20 messages a minute. Broadcast across chats: about 30 a second. The holder's own cap is 20 an
  hour, so the limit is never near.
 - **Over the limit** the API answers HTTP 429 with `parameters.retry_after`, the seconds to wait
  before the request may be repeated. Repeating early prolongs the wait.
 - **Length.** A text message is at most 4096 characters after entity parsing. Longer is refused with
  HTTP 400, not cut.
 - **Callback data** on a button is 1–64 bytes ([08](08-asks-that-authorise.md)).
 ### Editing
 - **`editMessageText`** replaces a sent message's text. For an ordinary bot message there is no time
  limit. The 48-hour limit applies only to business messages, and deletion has its own 48-hour limit.
 - **An edit notifies nobody.** No sound, no banner, and the message stays where it was in the chat's
  history. This is why a clearing is cheap to say by edit. It is also why an edit must never be the
  only way something **new** is said.
 - **An identical edit is an error:** HTTP 400, "message is not modified". It is harmless and must be
  read as success, not as a failure to fall back from.
 - **A deleted message** answers "message to edit not found". Falling back to a new message is right
  then.
 ### Loudness
 Telegram has **no message priority**. The only lever is **`disable_notification`**: the message
 arrives without sound. It cannot break through the phone's do-not-disturb, so an urgent message at
 night is as quiet as the phone is set to be. Per-chat notification settings on the phone (a custom
 sound, an exception to do-not-disturb) are the operator's, not the mesh's.
 ### Formatting
 With no `parse_mode` the text is shown as written, and nothing in a message can be read as markup.
 That is the right default for words that pass a content rule rather than a template. If markup is ever
 wanted, `MarkdownV2` needs every reserved character escaped and fails the whole send on one miss, so
 plain text or `HTML` with escaping are the safer options.
 `disable_web_page_preview` was **deprecated in Bot API 7.0** in favour of
 `link_preview_options: {is_disabled: true}`. It still works, but the mesh's messages carry no links
 (the content rule refuses URLs), so the parameter can simply be dropped.
 ### Answering back
 Answers reach a bot two ways:
 - **Long polling with `getUpdates`**, over outbound HTTPS. Updates wait at Telegram for at most
  24 hours.
 - **A webhook** (`setWebhook`), which Telegram calls over HTTPS on port 443, 80, 88 or 8443. It may
  carry a secret header (`X-Telegram-Bot-Api-Secret-Token`) that proves the call came from the webhook
  that was set.
 Only one of the two at a time. [08](08-asks-that-authorise.md) chooses between them.
 ## What Telegram sees
 - **Everything in the message.** A bot chat is a "cloud chat": encrypted between the phone and
  Telegram, and between Telegram and the bot API caller, and readable by Telegram. Bots cannot take
  part in Telegram's end-to-end "secret chats".
 - **That is what the content rule is for.** The holder refuses any message carrying an address, a
  path or a secret's shape (to-be 45 §5), so what Telegram stores is roles, words and condition keys.
 - **Who the operator is.** The account's phone number, and the addresses the phone and the sending
  machines connect from. Since September 2024 Telegram's privacy policy says it may disclose a user's
  IP address and phone number to judicial authorities on a valid order.
 - **Machine names.** A condition key names the machine it is about, and so does the watcher's message
  ("told by mesh-watcher on …"). The content rule refuses host names with a top-level domain, not bare
  machine names. To-be 45 says a message's subject is "a machine's role". Whether a bare machine name
  may leave is a decision this effort has not taken; today it does.
 ## When Telegram is unreachable
 - **A send fails at the transport** (no DNS, no connection, timeout). The holder keeps what it held
  and tries again every minute. The watcher keeps what it owes and tries again at its next tick.
  Neither loses a message while it runs.
 - **A send fails because Telegram refuses** (400 or 403). It is permanent for that message. The holder
  today treats it like a transport failure and tries again every minute, for ever (see the defects).
 - **Telegram being down is invisible to Telegram.** The holder's status says the channel is failing.
  The operator sees that only through another channel or by asking. This is what a second holder of a
  different kind is for ([05](05-the-other-holders-on-the-same-axes.md)).
 - **Telegram is blocked** in some countries and on some networks. An operator travelling should know
  the mesh's phone channel may be one of them.
 ## Cost
 - **Free.** No per-message charge. Telegram's paid broadcasts (above 30 messages a second) are far
  out of range.
 - **One account**, which the operator very likely already has.
 - **Two secrets**, one token per bot, both `issued-by: outside`.
 ## The built code, checked against this
 Read from the code repository's main branch on 2026-10-06: the holder's `telegram.go`, `outbox.go`,
 `holder.go`, `content.go`, and the watcher's `telegram.go` and `watcher.go`. The two Telegram clients
 are copies of each other, kept apart on purpose so the watcher depends on nothing it watches.
 What is right:
 - **Plain text**, with no `parse_mode`.
 - **The token is kept out of every error.** The client rebuilds transport errors from their kind,
  because the URL carries the token. It also strips the token from the API's own description.
 - **Token and chat id are re-read at each send**, so accepting the secret or changing the setting needs
  no restart.
 - **A token's shape is checked.** A random value the mesh minted for an un-accepted secret is named as
  that, not sent to Telegram to be refused.
 - **A missing edit falls back to a new message.**
 - **The holder caps itself** at 20 messages an hour and folds bursts into digests, far inside
  Telegram's limits.
 ### Defects
 | # | Where | What | Effect | Weight |
 |---|---|---|---|---|
 | D1 | holder: `telegram.go`, `outbox.go` | Nothing bounds a message to 4096 characters. A long summary, or a digest of long titles, is refused with 400. `failed` keeps the whole batch and retries it every minute. | One oversized message wedges the Telegram channel: everything queued behind it waits for ever. | high |
 | D2 | holder: `holder.go` (`h.edit(old, "reopened", false)`) | A condition that clears and is raised again within ten minutes is said by **editing** the first message. On Telegram an edit notifies nobody. | A reopened urgent condition reaches the phone **silently**, high up in the chat's history. | high |
 | D3 | holder: `outbox.go` (`r.Sent[name]` keeps only the first id) | Reminders and escalations are new messages, but clearing edits only the first. | The newest thing on the phone still says "STILL OPEN" or "NOW URGENT" after the condition cleared. The "CLEARED" is a silent edit, out of sight. | medium |
 | D4 | both: `telegram.go` | `Message.Quiet` and `Message.Urgent` are ignored. `disable_notification` is never set. | A clearing, or a warning, rings as loudly as an urgent message. Telegram's only loudness lever is unused. | medium |
 | D5 | both: `telegram.go` (`call`) | HTTP 429's `parameters.retry_after` is not read. The retry is a flat minute. | Harmless at the holder's cap. Under a real flood wait, repeating early prolongs it. | low |
 | D6 | holder: `telegram.go`, `outbox.go` | Every refusal (400, 403) is retried like a transport failure. "message is not modified" on an edit is read as a failed edit, and a new message is sent instead. | Permanent errors loop every minute in the log. A no-op edit becomes a duplicate message. | low |
 | D7 | both: `telegram.go` | `disable_web_page_preview` is deprecated since Bot API 7.0. | Works today. Moot, since no message carries a link. Drop it. | low |
 | D8 | both: `telegram.go` (`call`) | The `json.Marshal` error is discarded. A non-numeric `message_id` (`json.Number`) makes the body empty. | A confusing refusal from Telegram instead of a local error. Ids come from Telegram, so it is unlikely. | low |
 | D9 | watcher: `watcher.go` (`Tick`) | A "silent" message that could not be sent is overwritten by the "CLEARED" message when the signal returns. | The operator can receive "heard again" for a silence they were never told of. Better to say both, or one line saying it was silent for N minutes and is back. | low |
 | D10 | both | `Ready()` is satisfied by a token and a chat id. It does not know whether the operator pressed Start, or whether the bot was blocked (403). | Status says "ready" until the first send fails. The watcher's own test verb is the only proof. A `getChat` check at status time would say it. | low |
 D1 and D2 matter before the channel is configured. D1 can silence the channel. D2 silences exactly the
 case (a flapping urgent condition) the operator most needs to hear.
 ## Sources
 - Telegram, *Bots FAQ*: rate limits, paid broadcasts. https://core.telegram.org/bots/faq
 - Telegram, *Bot API* (version 10.3, recent changes, `getUpdates` retention, `ResponseParameters`,
  `setWebhook`, `link_preview_options`). https://core.telegram.org/bots/api
 - Telegram, *Bot features*: BotFather, `/newbot`, `/token`, `/setprivacy`, deep linking.
  https://core.telegram.org/bots/features
 - `link_preview_options` replacing `disable_web_page_preview` (Bot API 7.0); the removal of the old
  argument in python-telegram-bot v22. https://docs.python-telegram-bot.org/en/v22.0/telegram.ext.defaults.html
 - "message is not modified" and "message to edit not found" in practice:
  https://github.com/tdlib/telegram-bot-api/issues/400
 - 409 "terminated by other getUpdates request":
  https://community.home-assistant.io/t/help-on-telegram-extension-error-while-getting-updates-conflict-terminated-by-other-getupdates-request-make-sure-that-only-one-bot-instance-is-running-409/177544
 - Telegram privacy policy change, September 2024:
  https://www.bleepingcomputer.com/news/security/telegram-now-shares-users-ip-and-phone-number-on-legal-requests/
 - Bots and secret chats; cloud-chat encryption:
  https://www.kaspersky.com/blog/telegram-privacy-security/38444/
 - Phone number required; anonymous numbers: https://en.wikipedia.org/wiki/Telegram_(software)
@@ -1,186 +0,0 @@
 # 05 — The other holders, on the same axes
 Every candidate is judged as a holder of the channel and intake seats in
 [06](06-a-conversation-with-the-operator.md): which capabilities it can honestly declare
 (the vocabulary is defined there), and what it needs. [02](02-the-channels.md) weighed the same
 candidates before any of this was measured. This document replaces its reading of them with facts as
 of 2026-10-06, and adds the question 02 could not ask: **can the operator answer through it, and
 authorise an action through it?** ([08](08-asks-that-authorise.md)).
 Two roles are judged separately, because they want different things:
 - **The away channel:** the mesh's urgent messages and its asks, wherever the operator is.
 - **The watcher's path:** the message that the mesh itself has gone silent. It must not depend on the
  control node, the bus or the controller. The mesh observed has its controller, its bus and its mail
  server on the anchor (the control node). Its Matrix server is on the home-server, behind a household
  connection.
 ## The candidates
 ### ntfy
 A small push server. Topics are published to over HTTP; the phone app subscribes.
 - **Self-hosted vs the public server.** Self-hosted keeps the words on the operator's machines.
  The public `ntfy.sh` takes no sign-up. Its free tier allows 250 messages a day **per IP address**,
  shared with whoever else sends from that address. Paid tiers (from about $5–6 a month) give
  reserved topics and higher quotas. An unreserved topic on the public server is readable by anyone
  who guesses its name.
 - **Phone delivery.**
  - **Android:** through Google's FCM from the public server, or through the app's own long-lived
    connection to a self-hosted server ("instant delivery"), which costs battery.
  - **iOS:** cannot be reached by a self-hosted server alone. The server must name an upstream
    (`upstream-base-url`, normally `ntfy.sh`), which receives a poll request carrying only a message
    id and a hash of the topic, and has Apple wake the phone. The words do not pass through the
    upstream. The dependency does.
 - **Loudness:** five priorities. The highest gives "really long vibration bursts" and a pop-over on
  Android.
 - **Answers:** up to three action buttons. An `http` action makes **the phone** send a request,
  which needs a route from the phone to the mesh and a credential carried inside the notification.
  Nothing tells the server **who** tapped, only that someone holding the notification did. No free-text
  reply.
 - **As the watcher's path:** self-hosted, it fails with the machine it runs on. The public server
  works, at the cost of a guessable topic or a subscription.
 ### Matrix (a homeserver is already one of the mesh's modules)
 The module runs Conduit and Element Web, on the home-server.
 - **Reach:** any Matrix client on the phone. Push goes from the homeserver to the client's **push
  gateway**: for the stock Element apps, Element's gateway at matrix.org, which hands it to Apple or
  Google. A self-hosted gateway needs a self-built app. UnifiedPush (via ntfy) is an option on Android.
 - **Push support in Conduit has lagged.** Its own documentation long listed mobile push as missing,
  and forks have since reworked pushers. Whether the running version pushes reliably is **unverified**
  and must be measured before Matrix is relied on for anything urgent.
 - **Answers:** free text, and reactions (`m.reaction` annotations) as one-tap choices. Clients add
  emoji variation selectors, which must be normalised before a reaction is read as a choice.
 - **Who answered:** the sender's Matrix id is authenticated **by the homeserver**, which the mesh
  runs. That is strong for an account on the mesh's own server, and only as strong as that server.
 - **Privacy:** end-to-end encrypted if the bot supports it. Otherwise readable by the homeserver,
  which is the mesh's own.
 - **As the watcher's path:** it survives the control node going down. It does not survive the home's
  connection going down, and its phone push still depends on matrix.org's gateway.
 - **Cost:** a bot account and its secret. No third party for the words.
 ### Pushover
 A paid push service with a stable API.
 - **Cost:** $4.99 one-time per platform after a 30-day trial. 10,000 messages a month per
  application.
 - **Limits:** 1024 characters, a 250-character title.
 - **Loudness:** the strongest of any candidate.
  - Priority 1 bypasses the user's quiet hours.
  - Priority 2 ("emergency") repeats every `retry` seconds (at least 30) until acknowledged or until
    `expire` (at most three hours). It returns a **receipt** that can be polled outbound to learn
    whether, and when, it was acknowledged.
 - **Answers:** acknowledgement only. No buttons, no reply.
 - **As the watcher's path:** yes. It is outbound HTTPS from any machine, to a third party.
 - **Where the words go:** to Pushover.
 ### Gotify
 Self-hosted, Android only. Delivers over a WebSocket the app keeps open. There is no official iOS app,
 and Apple's restrictions make a self-hosted iOS push impossible without a relay. It has no answer path
 beyond opening the app. **Not pursued:** it covers less than ntfy and nothing ntfy does not.
 ### Mail through an outside provider
 - **The mesh's own mail server is on the control node,** so it fails with it.
 - **An outside relay** (an SMTP account at a mail provider) reaches the operator from any machine.
 - **Urgency:** none. Mail is the digest and the record.
 - **Answers:** a reply, slowly. **Who answered is weak:** a From line can be forged, and checking
  DKIM only proves the operator's provider sent it.
 - **Mail as an intake** (a new mail arriving) is a trigger in its own right
  ([06](06-a-conversation-with-the-operator.md)), whatever its weakness as a channel for asks that authorise.
 ### Signal, through `signal-cli`
 - **An unofficial client,** and it needs its own phone number, registered with a captcha.
 - **It must be kept current.** Signal's own clients expire after three months, and the server then
  changes incompatibly. In March 2026 Signal began unregistering accounts whose client lacked a new
  protocol feature, and every `signal-cli` account registered before that date was dropped.
 - **Privacy:** end-to-end encrypted. Sender identity is strong (Signal's identity keys). Reactions
  and replies both work.
 - **Weight:** a phone number and a maintenance burden with a hard failure mode. It is the right
  choice only for an operator who requires end-to-end encryption on the phone and accepts that burden.
 ### SMS through a paid gateway
 The only candidate that reaches a phone with **no data connection**.
 - **Cost:** per message, with an account at a gateway.
 - **Privacy:** no encryption. Sender identity on replies is spoofable.
 - **Its place:** the last resort of an outside dead-man service (below), which offers SMS and phone
  calls on paid plans, rather than a channel of the mesh's own.
 ### An outside dead-man service
 A service the mesh **pings**, which alerts by its own means when the pings stop. It is not a channel
 of the mesh: it is the one thing that still speaks when **every** machine, or the home's connection
 and the anchor together, are gone. [03](03-open-questions.md) Q6 named it the cheapest answer that
 also covers "the whole house is offline".
 - **Healthchecks.io** (also self-hostable, which defeats the point here) monitors 20 checks free,
  without a card.
 - It notifies through Telegram, Signal, Matrix, ntfy, Pushover, mail and others.
 - Paid plans add SMS, WhatsApp and phone-call credits.
 ## The table
 Capabilities are those of [06](06-a-conversation-with-the-operator.md). ✓ declared honestly,
 — not, ~ conditional (the note says on what).
 | Holder | reaches-away | loud | silent | edit | choice | reply | verified-sender | exact-render | code-factor | private | off the control node | cost |
 |---|---|---|---|---|---|---|---|---|---|---|---|---|
 | Telegram | ✓ | — (do-not-disturb wins) | ✓ | ✓ | ✓ | ✓ | ✓ (user id) | ✓ | ✓ (code as a reply) | — | ~ (a holder on another machine) | free |
 | desktop notifier | — | ~ (critical urgency) | ✓ | ✓ | ~ (actions, read by nobody) | — | — (any program of the account) | ✓ | — | ✓ | — | none |
 | ntfy, self-hosted | ✓ | ✓ (priority 5) | ✓ | — | ~ (http action, phone → mesh) | — | — | ✓ | — | ✓ (iOS: relay sees ids) | — | a module |
 | ntfy.sh | ✓ | ✓ | ✓ | — | ~ | — | — | ✓ | — | — | ✓ | free (250/day/IP) or ~$5/mo |
 | Matrix (own server) | ~ (push unverified) | — | ✓ | ✓ | ✓ (reactions) | ✓ | ✓ (own homeserver) | ✓ | ✓ | ~ (E2E if the bot does it) | ~ (home-server, not anchor) | a bot account |
 | Pushover | ✓ | ✓✓ (emergency, repeats) | ✓ | — | ~ (acknowledge only) | — | ✓ (for acknowledge) | ✓ | — | — | ✓ | $4.99 once |
 | mail, outside relay | ✓ (slow) | — | ✓ | — | — | ✓ | — (forgeable) | ✓ | ~ (code in a reply) | — | ✓ | an account |
 | Signal (`signal-cli`) | ✓ | — | ✓ | ✓ | ✓ (reactions) | ✓ | ✓ | ✓ | ✓ | ✓ | ~ | a number + upkeep |
 | SMS gateway | ✓ (no data needed) | ✓ | — | — | — | ~ | — | ✓ | — | — | ✓ | per message |
 ## Reading it
 **For the away channel and for asks,** Telegram is the only candidate that is all of these at
 once: free, on both phone platforms, without a server of the mesh's own, and able to carry every tier
 of authorising ask ([08](08-asks-that-authorise.md)), including a code as a second proof. Its price is that
 Telegram reads the words, which is what the content rule is for.
 - **Matrix** is the self-hosted equivalent for asks. It waits on a measurement of Conduit's push.
 - **Signal** is the end-to-end-encrypted equivalent, at a maintenance cost that has already broken
  every installation once this year.
 **For waking the operator,** Pushover's emergency priority is the only thing that repeats until
 acknowledged and gets through quiet hours. Telegram cannot. It is a reasonable **second** away holder
 for urgent conditions only, if the operator wants to be woken. It cannot carry an answer beyond
 "acknowledged".
 **For the watcher's path,** the requirement is independence from what it watches:
 - **Telegram, sent directly** from a machine that is not the control node, with its own bot, meets it
  (to-be 45 §5).
 - **ntfy self-hosted does not.**
 - **Matrix only half meets it** (it is on the home-server, and its push goes through matrix.org).
 - **What none of them covers** is the watcher's own machine, or the home's connection, going down
  together with the anchor. Only an outside dead-man service covers that.
 ## Sources
 - ntfy, *Configuration* (iOS upstream relay, FCM, access control): https://docs.ntfy.sh/config/
 - ntfy, *Publishing* (priorities, actions, `http` action, message size): https://docs.ntfy.sh/publish/
 - ntfy.sh pricing: https://ntfy.sh/#pricing. Its free-tier rate limit is per IP:
  https://github.com/binwiederhier/ntfy/issues/1963
 - Pushover API (length, quota, priorities, emergency retry/expire, receipts): https://pushover.net/api
 - Pushover pricing: https://pushover.net/pricing
 - Gotify, platform support: https://play.google.com/store/apps/details?id=com.github.gotify and
  https://guancyxx.cn/en/blog/ntfy-vs-gotify-vs-nostr
 - Element push gateway (Sygnal at matrix.org):
  https://github.com/vector-im/element-android/blob/develop/docs/notifications.md
 - Matrix reactions (`m.annotation`): https://github.com/uhoreg/matrix-doc/blob/aggregations-reactions/proposals/2677-reactions.md
 - Conduit changelog: https://conduit.rs/changelog/
 - signal-cli, registration with a captcha: https://github.com/AsamK/signal-cli/wiki/Registration-with-captcha
 - signal-cli, unregistration of outdated clients in 2026: https://github.com/AsamK/signal-cli/issues/1993
 - Healthchecks.io pricing: https://healthchecks.io/pricing/. Its Telegram integration:
  https://healthchecks.io/integrations/telegram/
@@ -1,332 +0,0 @@
 # 06 — A conversation with the operator
 The operator's directions, 2026-10-06, in substance:
 - **Telegram is one output channel among many to come.** The setup must be generic, and Telegram
  simply fulfils a seat.
 - **The same holds for input:** a new mail, a new message from the operator.
 - **Each channel has capabilities.**
 - **Approval is only an example.** An agent may just as well want to ask a simple question, and "it
  doesn't have to be permission related".
 So the core of this effort is not a notifier and not an approval path. It is **a conversation with
 the operator, held over channels**:
 - the mesh, its modules and its agents **say** things and **ask** things;
 - the operator **answers**, or **writes first**;
 - each exchange goes over whichever channel is right for its needs and for where the operator is.
 This document is that general model. [07](07-the-work-context-and-the-desk.md) is how the work context
 chooses the channel. [08](08-asks-that-authorise.md) is one layer on top: asks whose answer performs an
 action, and the checks that makes necessary. [04](04-telegram-as-the-first-holder.md) and
 [05](05-the-other-holders-on-the-same-axes.md) are the first holders.
 ## What exists, and how it is shaped
 Read from the catalogue's main branch on 2026-10-06.
 - **The output seat's holder is one module doing three jobs.** It claims `operator-channel` (mesh
  scope, serving `open`, `history` and `notify`). It consumes the controller's three condition events.
  It holds the Telegram bot token as its own secret. It reaches the desktop through the `node-notifier`
  seat's `send`.
  - The router, the Telegram client and the desktop adapter are one process.
  - `notify` is a served verb, not the work queue to-be 32 §3 sketched.
 - **The desktop notifier** is the node seat `node-notifier`, held by the dunst module on each
  graphical machine.
 - **The watcher's watcher** has its own Telegram client and token, and is not assigned yet.
 - **Nothing reads anything back.** The operator speaks to the mesh only through an agent session or a
  shell.
 ## The three things said
 - **A message:** the mesh tells the operator something. A condition raised, a reminder, a clearing,
  a notice from a module. It expects no answer. It may be edited later (a clearing).
 - **An ask:** someone wants the operator's input, of a declared kind. The answer goes back to whoever
  asked.
 - **An operator message:** the operator writes first. It is a message to an agent, a note to the mesh,
  or an answer to an ask written in the thread instead of tapped.
 Inputs from outside that are not the operator (a mail arriving, a webhook) are the same kind of
 envelope as an operator message, with a sender that is not the operator. This effort designs their
 shape only. Their consumers are later work.
 ## Asks
 ### Kinds
 | Kind | The operator gives | Required capabilities of the channel |
 |---|---|---|
 | `yes-no` | yes or no | `choice`, or `reply` (read as yes or no) |
 | `one-of` | one of up to eight labelled options | `choice`, or `reply` with the option's number |
 | `text` | free text | `reply` |
 | `number`, `date` | a value of that type, within bounds | `reply`. Parsed and checked by the seat's holder; asked again once if it does not parse. |
 | `acknowledge` | "seen" | `choice` |
 An ask whose answer **performs an action** (approve a retirement, delete data) is the same ask with
 an **authorising** flag. It adds requirements of trust, which [08](08-asks-that-authorise.md)
 defines. Everything else about it is as below.
 ### What an ask carries
 - an id;
 - the asker (its bus principal and its machine);
 - the kind, with its options or bounds;
 - the words;
 - a priority (urgent or normal);
 - optionally a timeout and a default;
 - optionally a conversation handle (where the asker is talking with the operator);
 - optionally a group, for batching.
 The words pass the content rule like every message.
 ### Its life
 **open → answered | defaulted | expired | cancelled**
 - **Answered:** the first answer wins. Copies of the ask shown on other channels are edited to say
  where it was answered.
 - **Defaulted:** the timeout passed and the ask declared a default. The asker receives the default,
  marked as a default, never as the operator's answer.
 - **Expired:** the timeout passed with no default. The asker is told.
  - **An authorising ask never defaults to performing.** It expires. ADR 0230's rule, "a timer is the
    mesh acting alone again, only later", applies to every ask that authorises.
 - **Cancelled:** the asker no longer needs it (`ask cancel`), or its owner sees it is moot (the
  condition behind it cleared). Its copies are edited to "no longer needed".
 ### How the asker gets the answer
 - The answer is emitted as **`ask-answered`**, with the ask's id and, where there is one, the
  conversation handle.
 - An asker may **wait**: `ask` with a wait of up to a few minutes returns the answer if it comes in
  time, and otherwise returns the id.
 - An agent working through a long task can **poll** `asks <id>`.
 ### Batching
 - **Asks to the same channel within the burst window go out together.** A heading says how many are
  open ("3 questions waiting"), and each ask follows as its own message, so each can be answered and
  edited alone.
 - **An asker may hold at most three open asks.** A fourth is refused to it, in words, so an agent in
  a loop cannot flood the operator.
 - **Asks count against the router's hourly cap** like messages. Answers do not.
 ### History
 **`asks`** lists open asks, and closed ones for 30 days: the asker, the kind, the outcome, the channel,
 and the answer. A free-text answer is the operator's own words. It stays in the router's state and is
 never forwarded to a channel other than the one it came from.
 ## Who holds what
 ### The output seat's holder becomes the conversation's router
 It holds `operator-channel` and gains asks:
 - `ask` (create),
 - `ask cancel`,
 - `asks`,
 - `answer` (called by intake holders, below),
 - events `ask-opened`, `ask-answered`, `ask-closed`.
 It **owns** every ask that authorises nothing.
 An authorising ask is **owned by the controller** ([08](08-asks-that-authorise.md)). The router carries
 it like any other, but its answer goes to the controller, which alone can perform.
 ### Where a channel sits: [03](03-open-questions.md) Q1, asked again
 Q1 settled that **one seat speaks for the mesh** and that sources never learn channels. It assumed
 each channel attaches by contribution. With many channels to come, and channels that answer, that is
 the question to settle.
 The mesh's precedents:
 - A **seat** has one holder at its scope (ADR 0121, ADR 0126).
 - A **node seat** has one holder per machine, and a verb's subject carries the machine (design 33 §4).
 - A **bench** is a seat with several holders. The only one is `mesh-dns-resolver`: the same module,
  one per machine. "Making another one is a decision, recorded" (ADR 0223).
 - A **work queue** is shared by a seat's holders (ADR 0190).
 - A **contribution** is content another module hands to a seat's holder (ADR 0210, ADR 0212).
 The options:
 - **a. Each channel contributes itself to the output seat** (Q1 a, to-be 45 §5).
  - A contribution is content a holder places.
  - A channel is running code: it holds a secret, keeps a connection, reads answers, fails on its own.
  - Making it fit puts every channel's client back in the router. **Rejected.**
 - **b. One seat per channel kind.** The router learns every seat; a new channel is a change to the
  router. **Rejected.**
 - **c. Channel modules found by a manifest field and called by module address.** Callers use seats,
  never modules (ADR 0126). **Rejected.**
 - **d. One monolithic notifier,** every channel built into the router. Shared secrets and failures, a
  release per channel. **Rejected.**
 - **e. A channel module per service, with its own approval or question path** (a "Telegram module"
  that decides things). It locks the conversation to one service, and the next channel repeats it.
  **Rejected.**
 - **f. Kinded benches.** Two mesh seats, **`channel`** (out) and **`intake`** (in). Their holders are
  different modules, each claiming a **kind** (`telegram`, `desktop`, `ntfy`, `matrix`, `mail`, …).
  - One holder per kind; two claiming one kind is refused at registration.
  - A verb's subject carries the kind, as a node seat's carries the machine:
    `mesh.seat.channel.tool.send.<kind>`.
  - A new channel is a new module claiming a new kind, with no change to the router.
  - **Chosen.**
 Option f needs a second bench, of a new sort (different modules, keyed by kind), which ADR 0223 says
 must be decided. It also needs a claim that carries a kind and capabilities.
 ## The channel seat (out)
 **`channel`**, mesh scope, a kinded bench.
 ### Served
 - **`send`:** words, a priority, whether silent, an optional **ask block** (the kind, the options each
  with an opaque token, the ask id) and an optional thread (the conversation handle, or the message
  this replies to). Answers the channel's id for what it sent, or a refusal in words.
 - **`edit`:** replace a sent message by its id, where `edit` is declared.
 - **`standing`:** ready, not configured (naming what is missing, never a value), or failing (since
  when, why); the last delivery; the declared capabilities.
 ### Emitted
 - **`delivered`** and **`failed`**, the latter marked **permanent** or **transient** (defect D6 in
  [04](04-telegram-as-the-first-holder.md)).
 ### Honoured
 - The declared maximum length, by cutting and saying so (D1).
 - Silence where declared (D4).
 - An identical edit is a success (D6).
 - No own secret in any error or event.
 ### The content rule
 The content rule is the router's, applied before anything reaches a holder that does not declare
 `private`.
 ## The intake seat (in)
 **`intake`**, mesh scope, a kinded bench. A service that is read and written by one program (a
 Telegram bot, [04](04-telegram-as-the-first-holder.md)) is held by one module claiming both seats under
 one kind.
 A holder turns what arrives into **one envelope**:
 | Field | What it is |
 |---|---|
 | `id` | Unique, for deduplication. |
 | `kind` | The holder's kind. |
 | `what` | `message` (written first), `choice` (a button or a reaction), `reply` (written in an ask's thread), `mail`, `call` (a webhook), `seen` (activity, for the work context). |
 | `sender` | The identity on that service, and whether the service authenticated it. |
 | `operator` | Whether that identity is on the **controller's** list of the operator's identities. Filled from that list, never from the holder's own. |
 | `conversation` | An opaque handle. Sending on it reaches the same chat, room or mail thread. |
 | `in-reply-to` | The ask or message it answers, if any. |
 | `payload` | The text, or the option's token. **No secrets:** a code for an authorising ask never travels in an envelope ([08](08-asks-that-authorise.md)). |
 | `at` | When. |
 **Answers go to the ask's owner by request and reply:**
 - the router's `answer` for an ordinary ask;
 - the controller's for an authorising one.
 **Everything else is an event on the seat,** which consumers take by `what`:
 - the router takes `seen` for the work context;
 - an agent bridge takes `message` from the operator;
 - a future mail rule takes `mail`.
 **One gap to close:** the shared library cannot yet publish on a seat's event subjects (design 32 §1).
 ## The capability vocabulary
 **Fixed and versioned:** `channel-capabilities/1`. A holder declares capabilities in its claim, and
 the catalogue refuses a word outside the vocabulary. **Each capability has a contract test** the
 holder's build runs and a **drill** its `standing` can run. One that fails its drill is reported and
 withdrawn from routing until it passes.
 The words are in three groups. The first two serve every conversation. The third exists only for
 asks that authorise, and is defined in [08](08-asks-that-authorise.md).
 ### Delivering
 | Capability | Promise | Test / drill |
 |---|---|---|
 | `deliver` | It arrives, or `failed` says why. | Against a test double; a live test message. |
 | `reaches-away` | It reaches a phone away from the operator's machines. | Declared by kind; the operator acknowledges a drill. |
 | `loud` | It can break through the phone's quiet hours. | The service's override is set for urgent. |
 | `silent` | It can arrive without sound. | The service's silent flag is set. |
 | `edit` | A sent message can be replaced in place. | Edit and read back, against a double. |
 | `max-length:N` | Up to N characters arrive whole; longer is cut, and the cut is said. | N+1 characters give a cut message, not a failure. |
 | `reaches-when-mesh-down` | Delivering needs neither the bus nor the control node. | Checked by the holder's placement and its send path. |
 | `private` | The words stay on the operator's machines, or are end-to-end encrypted. | Declared by kind; reviewed. |
 ### Conversing
 | Capability | Promise | Test / drill |
 |---|---|---|
 | `choice` | The operator can pick one offered option in one act, and the pick comes back. | A simulated tap gives a `choice` envelope with the option's token. |
 | `reply` | The operator can answer in free text, and it comes back. | A simulated reply gives a `reply` envelope. |
 | `threads` | An answer is tied to the message it answers. | A reply to message A carries A in `in-reply-to`. |
 | `operator-first` | The operator can write to the mesh unprompted. | A simulated message gives a `message` envelope. |
 ### Trusting
 `verified-sender`, `exact-render`, `code-factor` and `key-factor` are defined in
 [08](08-asks-that-authorise.md). A channel without them still converses fully. It just cannot carry
 an answer that performs an action.
 ## Agents in the conversation
 An agent is a participant. It asks, and it receives.
 - **An agent whose operator is at its own terminal** asks there, in the terminal. The seat is not
  needed.
 - **An agent working unattended** (in the background, on a schedule, or with the operator stepped
  away) asks **through the seat**. The router puts the ask where the operator is now
  ([07](07-the-work-context-and-the-desk.md)): the desk if they are at it, Telegram if they are away
  or talking through Telegram. The agent waits for, or polls, the answer.
 - **An agent the operator talks to through Telegram** receives the operator's messages as intake
  envelopes. It answers on the conversation handle. Its asks carry that handle, so they appear in the
  same chat.
 - **An agent's words reach the operator only as an asker's words,** and the operator's answer reaches
  the agent only as the operator's. An agent relaying "the operator said yes" is not an answer to
  anything. That is why an answer comes from a channel holder, never from the asker
  ([08](08-asks-that-authorise.md)).
 ## The watcher, in this shape
 The watcher's watcher stays **outside** the seats, deliberately:
 - it must speak when the bus and the control node are what failed;
 - the seats live on the bus.
 It is a minimal `deliver` + `reaches-when-mesh-down` sender with its own bot. It never reads, and never
 asks. Its sibling outside the mesh is the dead-man service ([05](05-the-other-holders-on-the-same-axes.md)).
 ## From today to this shape
 1. **Fix the first holder in place:** D1–D4 of [04](04-telegram-as-the-first-holder.md). No change of
   shape.
 2. **The operator configures Telegram** ([09](09-a-proposed-decision.md)). The mesh starts telling.
 3. **The vocabulary and the kinded bench in the catalogue,** and seat events in the shared library.
 4. **Split Telegram out** into its own module holding `channel` and `intake` under `telegram`. The
   router keeps the desktop adapter as `channel/desktop` and `intake/desktop`.
 5. **Asks in the router,** with buttons and replies on Telegram and actions on the desktop
   ([07](07-the-work-context-and-the-desk.md)). Agents can ask from here on.
 6. **The work context** as the router's ordering ([07](07-the-work-context-and-the-desk.md)).
 7. **Authorising asks in the controller** ([08](08-asks-that-authorise.md)).
 8. **Operator-first messages,** and an agent bridge consuming them.
 9. **Further holders as wanted:**
   - Pushover for waking;
   - Matrix once its push is measured;
   - mail out for the digest, mail in as an intake.
 The watcher changes only at step 1.
 ## What this revisits in [03](03-open-questions.md)
 - **Q1:** channels attach as holders of kinded benches (f), not as contributions.
 - **Q3:** the life of a message gains the life of an ask. `edit` and `silent` are declared, and decide
  how a clearing is said (D2, D3).
 - **Q4:** presence becomes the work context ([07](07-the-work-context-and-the-desk.md)).
 - **Q7:** answering back is the conversation itself. Its authorising layer is
  [08](08-asks-that-authorise.md).
 - **Q8:** the content rule stays, applied by the router. Whether a `private` holder may be exempted
  is left to graduation.
@@ -1,117 +0,0 @@
 # 07 — The work context, and the desk
 The operator, 2026-10-06:
 - "If dunst can also show buttons, we could prefer to use desktop notifications instead of Telegram
  for approval actions when working in a session."
 - "The work context is an important factor when deciding the correct output channel."
 [06](06-a-conversation-with-the-operator.md) decides **which channels may carry** a message or an ask:
 those whose declared capabilities satisfy it. This document decides **which of those comes first**,
 from where the operator is working. It also makes the desk a full participant in the conversation.
 ## The rule
 > **A message or ask goes to the most direct channel in the operator's current context, among those
 > whose capabilities already satisfy it. Unanswered in time, it escalates along a fixed chain.
 > Context orders the candidates; it never adds one. Context never lowers the bar.**
 The last sentence matters most for asks that authorise ([08](08-asks-that-authorise.md)). Being at the
 desk never makes a click count as more than it proves.
 ## The signals
 | Signal | Source | Read as |
 |---|---|---|
 | A graphical session unlocked, with input in the last 5 minutes, on machine M | The `node-lock-screen` seat's holder on M (the screen-lock module), whose tools already read the idle time and the lock state. Underneath: logind's `LockedHint` and `IdleSinceHint`. Proposed: an event on each change, not a poll. | **at the desk on M** |
 | That session locked, or idle longer | the same | **not at the desk** |
 | An agent asking from machine M | The ask's asker names its machine. An agent module's own "session active" event, when one exists. | **working with an agent on M**. It strengthens "at the desk on M"; alone it proves nothing. |
 | A verified intake `message`, `reply` or `choice` in the last 15 minutes | The intake seat ([06](06-a-conversation-with-the-operator.md)) | **in a conversation** on that kind |
 | An ask carrying a conversation handle | The ask | **that conversation**, whatever else is true |
 | The hour, against quiet hours | The router's setting | **night**: only urgent wakes |
 ## The contexts, and where things go
 "The away channel" is the operator's setting (Telegram, to begin with). "The loud holder" is an
 optional second away holder for waking (Pushover, [05](05-the-other-holders-on-the-same-axes.md)).
 | Context | An ask goes to | Urgent message | Warning | Unanswered or unacknowledged → |
 |---|---|---|---|---|
 | **In a conversation through Telegram** (the ask carries its handle, or Telegram activity is newer than any desk input) | that chat, in the thread | that chat | that chat, silent | after 10 min (urgent) or 1 h: also the desk, if active |
 | **At the desk on M** (with or without an agent there) | the desk on M, if it can carry the ask; otherwise the away channel, and the desk says where it went | the desk on M, and the away channel silently | the desk on M | after 5 min (urgent) or 30 min: the away channel, with sound |
 | **Away** (no unlocked active session, no recent conversation) | the away channel | the away channel | the away channel, silent | after 15 min (urgent): the loud holder, if configured |
 | **Night, away** | non-urgent asks wait for the morning; urgent as away | the away channel and the loud holder | the morning digest | as away |
 | **The desk locks while an ask is shown there** | moves at once to the away channel | — | — | — |
 - **Every copy of an ask stays valid until one answer wins.** The others are edited to say where it
  was answered.
 - **The context's channel cannot carry the ask** (a free-text ask at a desk without a prompt, or an
  authorising ask the desk cannot prove): the next in the chain carries it, and the context's channel
  says where it went.
 - **Nothing can carry it:** the router says so, as a condition of its own.
 ### Presence stays in the mesh
 - **Presence facts are events on the bus,** consumed by the router.
 - **They are kept as current state only:** a key-value entry per machine and per intake kind,
  overwritten, never a history.
 - **They never appear in a message's words,** so they never reach a channel that is not `private`.
 - **No module keeps them as a timeline of the operator's day.** A consumer that wants one is a
  decision of its own.
 ## The desk as a participant
 Read from the catalogue's main branch and the tools' current documentation, 2026-10-06.
 ### What exists
 - **The `node-notifier` seat** is held on each graphical machine by the dunst module. Its `send` runs
  `notify-send --print-id` with an urgency, an application name and an optional replace id. It
  carries **no actions** today.
 - **libnotify's `notify-send`** (0.8 and later) takes `--action=NAME=Label`, repeatable, and `--wait`.
  It prints the chosen action's name when one is chosen, and nothing when the notification is closed.
  Underneath, the notification server emits `ActionInvoked` with the notification's id and the
  action's key.
 - **dunst shows actions:**
  - `do_action`, which the module binds to the **middle** click, invokes the default or only action;
  - otherwise it opens the **context menu**, which in this mesh is the `node-launcher` seat's
    dmenu-compatible menu;
  - `dunstctl action` and `dunstctl context` do the same from a command line.
 - **The `node-launcher` seat's `menu` verb** shows a list in the operator's session and answers the
  chosen line. A dmenu-compatible menu also accepts typed text that is not a listed line, which makes
  it a free-text prompt.
 - **The graphical session is X11.**
 ### What it takes
 - **`send` gains actions:** a list of (token, label).
 - **It still answers at once.** A notification may be answered minutes later.
 - **The holder listens for `ActionInvoked`** and emits the chosen token as an event on its node seat.
 - **The router's desktop adapter,** which holds `channel/desktop` and `intake/desktop`, turns that
  into a `choice` envelope.
 - **For `text`, `number` and `date` asks,** the notification's single action opens the launcher's
  prompt, and what is typed comes back as a `reply`.
 ### What the desk can declare
 | Group | Capabilities |
 |---|---|
 | Delivering | `deliver`, `silent` (low urgency), `loud` (critical urgency stays until dismissed), `edit` (replace id), `private` |
 | Conversing | `choice` (actions), `reply` (through the launcher's prompt), `threads` (the ask's id is carried) |
 | Trusting | **not** `verified-sender`. `exact-render` yes. `code-factor` (a prompt) yes. `key-factor` yes where a security key is plugged in. See [08](08-asks-that-authorise.md). |
 So the desk carries **every ordinary ask**: yes or no, one of, text, number, date and acknowledge.
 It needs no account anywhere. An agent working unattended on the workstation asks a clarifying question,
 and the operator, at the desk, answers it in the notification.
 It carries an **authorising** ask only with a factor the controller verifies itself, because a click
 on an X11 desk proves that someone was there, not that the operator clicked
 ([08](08-asks-that-authorise.md)).
 ## Sources
 - `notify-send(1)`, `--action` and `--wait`: https://man.archlinux.org/man/notify-send.1.en
 - Desktop notifications and actions: https://wiki.archlinux.org/title/Desktop_notifications
 - dunst documentation (mouse actions, `do_action`, the context menu): https://dunst-project.org/documentation/
 - logind's `LockedHint`, `IdleHint`, `IdleSinceHint`:
  https://freedesktop.org/software/systemd/man/org.freedesktop.login1.html
@@ -1,247 +0,0 @@
 # 08 — Asks that authorise
 Most asks inform their asker and change nothing ([06](06-a-conversation-with-the-operator.md)). Some
 answers **perform an action**: approving a retirement, confirming that a binding moves, deleting data.
 This document is the layer those asks need on top of the conversation. It is the controller's checks,
 the trust a channel must prove, and what a compromise can reach.
 The operator, 2026-10-06:
 - "Make sure I can approve and reject stuff via the Telegram channel."
 - In a terminal session with an agent, having to open Telegram is acceptable.
 - But when talking to an agent **through** Telegram, the operator cannot switch to a desktop session.
 - At the desk, desktop buttons would be preferred ([07](07-the-work-context-and-the-desk.md)).
 ## Where this stands against what was decided
 - To-be 45 §5 says: "No answering back in this form".
 - ADR 0227 kept it open on purpose: "routing by presence, quiet hours, **answering back** and the
  external dead-man service stay open in 028, whose graduation amends to-be 45."
 - So this answers 028's Q7. It does not reverse ADR 0227.
 ## What there is to authorise
 Read from the controller's main branch on 2026-10-06. The condition store marks conditions only a
 person resolves (`resolver: operator`): from the start for retirement, clean-up and binding conditions,
 and once a healer's budget is spent.
 | Action | The verb today | Asked for by | Reversible | Tier |
 |---|---|---|---|---|
 | Approve the retirement set waiting | `retire approve <node> <provider> --why` | `retire-waiting` (urgent) | yes: asking for a consumer again re-enables it | approve |
 | Reject it | `retire reject … --why` | `retire-waiting` | yes | approve |
 | Approve a set rejected before | `retire approve …` | `retire-rejected` (warning) | yes | approve |
 | Confirm that a binding moves, once its data is moved | `pin <node> <provision> <from> <module>` | `binding-kept` (urgent) | the pin, yes. The data, not by the mesh. | approve |
 | End a stuck plan | `plans stop` / `close <id> --why` | `stalled`, `sent-not-reported` once escalated | no, but it destroys nothing | approve |
 | Send a machine its declaration by hand | `push <node> --why` | `sent-not-reported` once escalated | n/a | approve |
 | Reset a bus consumer's position | `broker consumer-reset --why` | `consumer-behind` once escalated | no: messages skipped or redelivered | approve (graduation to confirm) |
 | Try a healer's repair once more | the healer's ordinary path | any escalation (H1–H5), `healers-braked` | as the repair is | approve |
 | Silence a condition | `conditions silence <key> --for --why` | any | yes, it ends by itself (at most 7 days) | acknowledge |
 | Delete one retired consumer's data | `cleanup delete <node> <provider> <consumer> --why` | `cleanup-waiting` (after 30 days) | **no** | destroy |
 | Delete everything retired longer than N days | `cleanup delete --older-than N --confirm --why` | `cleanup-waiting` | **no** | destroy |
 | Change the operator's identities, the away channel, or a factor's enrolment | (new) | — | yes, but it changes who may authorise | destroy |
 The build queue verbs and `replay --register` are not offered as asks: no condition asks for them.
 ## Trust, as capabilities and proofs
 The conversation's vocabulary ([06](06-a-conversation-with-the-operator.md)) gains four words used
 only here:
 | Capability | Promise | Test / drill |
 |---|---|---|
 | `verified-sender` | The holder proves the answer came from the operator's own account on that service, by the service's authentication, through a holder **no agent shares**: not on the operator's account, not on a machine where agents run as the operator. | A choice from an identity not on the list is dropped and reported. The holder's placement is checked. |
 | `exact-render` | The ask is shown as the controller rendered it, by the holder itself. No asker or agent composes the words the operator authorises. | Rendered text equals the controller's, byte for byte, against a double. |
 | `code-factor` | The holder can carry a code the operator types to the controller, by request and reply, and never judges it. | A code is never in an event, and is deleted from the conversation where the service allows. |
 | `key-factor` | The holder can run a security key's assertion over the controller's challenge, and hand the controller the result. | The challenge is the controller's, and the signature is checked by the controller. |
 From these, three **proofs** that the operator is the one answering:
 - **P1, a verified sender:** a Telegram tap, through a holder on a machine no agent runs on.
 - **P2, a code:** from the operator's authenticator, verified by the controller.
 - **P3, a key touch bound to the ask:** the controller's challenge is a hash of the ask's id and the
  state digest. A FIDO2 assertion with user presence (the key waits for a touch) is checked against the
  operator's enrolled credential. It proves a physical touch for **this** ask and no other.
 ## Three tiers
 | Tier | Required |
 |---|---|
 | **acknowledge** | `choice`, `exact-render`. Silencing is open to agents already, and announced; a proof adds nothing. |
 | **approve** | `choice`, `exact-render`, and **one** proof (P1, P2 or P3). Single use, bound to the exact state shown, expiring when that state changes or after 24 h. |
 | **destroy** | `choice`, `exact-render`, and **two** proofs, at least one of them P2 or P3. Valid 10 minutes after it is shown; at most one destroy answered per 10 minutes. |
 | Where the operator answers | Proofs it offers | acknowledge | approve | destroy |
 |---|---|---|---|---|
 | Telegram | P1 (tap), P2 (code as a reply) | tap | tap | tap and code |
 | the desk, with a security key | P3 (touch), P2 (code in a prompt) | click | click and touch | click, touch and code |
 | the desk, without a key | P2 (code in a prompt) | click | click and code | not possible: carried by the away channel |
 | an agent's terminal | none | none | none | none: an agent asks, it never answers |
 | the console (a shell) | P2 (code) | — | break-glass: a code | none |
 ### The rule
 1. **Every authorising verb declares its tier** in the controller's verb table.
 2. **An authorising ask is offered only on a channel whose capabilities satisfy its tier.** An answer
   arriving from any other channel is refused, and the refusal is said there.
 3. **The operator's away channel must satisfy every tier.** The self-check verifies it. A setting
   that would make a tier possible only at a desk is refused, unless the operator chose that for the
   tier explicitly. While working through Telegram, everything can be completed in Telegram.
 4. **The work context chooses among the channels that qualify; it never makes one qualify**
   ([07](07-the-work-context-and-the-desk.md)).
 5. **No agent authorises.** An agent asks. It holds no verb that performs an authorising action. The
   record names the agent that asked.
 ## Why the desk needs a factor
 - **X11 does not isolate the clients of one display.** Any of them can inject input (the XTEST
  extension, as `xdotool` does) and read keystrokes.
 - **`dunstctl action` invokes a notification's action** for any program of the account.
 - **The desktop holder runs as the operator's account,** whose files, the holder's bus credential
  included, every agent on that account can read.
 So a click at the desk, its `ActionInvoked` and the desktop holder's envelope can all be produced by
 an agent. An unlocked session with recent input proves a person was there, not that the person
 clicked. The desk declares no `verified-sender`. A factor the **controller** verifies gets around
 that.
 | Factor at the desk | Can an agent on the account fake it? | Judgement |
 |---|---|---|
 | **A security key's touch, bound to the ask** (P3) | No: the touch is physical, and the signature covers this ask's id and state. | **Preferred.** One click, one touch, no phone. Needs a key and an enrolment. |
 | **A code typed into the launcher's prompt** (P2) | It cannot know the code. On X11 it can read keystrokes and race to use the code first, and each step's code is accepted once. | **Acceptable** without a key. Costs picking up the phone. The race is a residual risk until the session leaves X11. |
 | **The screen's unlock or a fingerprint** | Yes: only the local holder sees the result. | **Rejected.** |
 The desk would earn `verified-sender` only if agents ran under an account of their own, without the
 operator's display, session bus or holders' credentials, on a compositor that isolates clients. That
 is a question for the agent modules' placement. It is noted, not proposed.
 ## The controller holds authorising asks
 Today a grant covers a whole verb (`seat:mesh-controller.retire` allows approving and listing alike).
 A hand-act records `by` from the calling bus principal, which for a channel would be the module, not
 the person. Both call for the controller to hold these asks itself.
 - **The verb table gains a field.** The controller's verb definition (a name, a description, input and
  output schemas) gains **`authorises`**: the tier, and the arguments that make up the exact state a
  person must see (for `retire approve`, the set of consumers).
 ### Three verbs
 - **`authorise request`:** anyone may call it, an agent or the router on a condition's behalf. It
  carries the action (verb and exact arguments), why, and optionally a conversation handle.
  - The controller renders the ask: what is asked, the exact state, who asks, what each option does.
  - It stores it with an opaque id (10 random base32 characters), its expiry and a digest of the
    state shown, and emits `ask-opened` with the controller as owner.
  - The router carries it like any ask. **Nothing is performed.**
 - **`authorise answer`:** only intake holders are granted it. It carries the id, the option, the
  sender's identity, and the code or key assertion where the tier needs them. The controller checks,
  and refuses at the first failure:
  1. the ask is open and not expired;
  2. the caller is the holder of an intake kind, by the controller's own seat records, never by the
     request's claim;
  3. that kind's declared capabilities, from the controller's records, satisfy the tier, and the
     proofs present are enough;
  4. a P1 answer: the sender is on the controller's list of the operator's identities for that kind;
  5. a code: valid for the current or previous 30-second step, and unused;
  6. a key assertion: it verifies against the enrolled credential, over this ask's challenge, with the
     user-presence bit set;
  7. the state **now** has the digest it had when shown. Otherwise the ask is void and a new one is
     requested.
  Then it performs the action as itself, records the hand-act, closes the ask with a compare-and-set
  (so a second answer on another channel loses), and emits `ask-answered`.
 - **`authorisations`:** open and recent authorising asks.
 ### The authorising verbs refuse to be called directly
 `retire approve|reject`, `cleanup delete`, and `pin` while a `binding-kept` names it refuse a caller
 unless the call comes through `authorise answer`, or carries a valid code as **break-glass** at the
 console. Break-glass is recorded as such, and announced on every channel.
 - `retire approve` must accept the set it approves (`expect`). Today it re-reads the set when it
  runs, so "approve what you were shown" (ADR 0230) does not hold end to end.
 - `conditions silence` stays callable. A silence an agent sets is said on the away channel, with its
  why.
 ### The record
 The hand-act gains:
 - **`via`:** the kind and the holder;
 - **`requested-by`:** the agent principal or the condition key;
 - **`ask`:** the id;
 - **`proofs`:** which of P1, P2 and P3 were present.
 `by` reads "the operator, as <kind> identity <id>". Every copy of the ask is edited to the outcome
 ("approved by the operator on telegram at 14:02 UTC"), and its buttons are removed.
 ## Telegram, carrying them
 - **Buttons.** `callback_data` is at most 64 bytes, so a button carries only `a1:<id>:<option>`.
  Everything else is in the controller.
 - **A tap** arrives as a `callback_query` with the tapping user's id and the chat. The holder:
  1. drops it, and reports, unless both are the operator's;
  2. calls `answerCallbackQuery` at once, because the phone shows a spinner until it does;
  3. calls `authorise answer`;
  4. edits the message to the outcome or the refusal.
 - **A destroy ask** answers the tap with a `ForceReply` prompt for the code. The holder reads the
  operator's reply, deletes it from the chat (bots may delete incoming messages in private chats), and
  hands it to the controller by request and reply. It is never put in an event.
 - **Long polling, not a webhook.**
  - `getUpdates` needs no route into the mesh.
  - A stolen token can steal updates, and a second reader shows as HTTP 409, but it cannot inject an
    update.
  - A webhook needs a public route, and a stolen token can redirect it.
  - The offset is kept in the holder's state, and ids are single use anyway.
 - **Placement.** The Telegram holder runs where no agent runs as the operator. Its own declaration of
  `verified-sender` depends on it.
 ## Agents
 - **In a terminal:**
  1. The agent calls `authorise request`.
  2. The router carries the ask to where the operator is ([07](07-the-work-context-and-the-desk.md)):
     the desk, with a factor, or Telegram.
  3. The agent sees `ask-answered`.
  Nothing the agent says counts.
 - **Through Telegram:** the request carries the conversation handle, so the ask appears in the same
  chat, rendered by the holder, and the operator taps in place, destroy included.
 ## If something is compromised
 | What is lost | What the attacker can do | What limits it |
 |---|---|---|
 | The bot token | Read what the bot is sent from then on. Steal taps (visible as 409). Send the operator fake messages. | It cannot call `authorise answer`. Revoke with BotFather's `/token`. |
 | The operator's Telegram account, on a new device | Approve or acknowledge. | Telegram's two-step password. Every authorisation is announced on the other channels. Approve is reversible. Destroy needs a code. |
 | The phone, unlocked | Everything, including destroy, if the authenticator is open on it. | An authenticator behind biometrics. One destroy per 10 minutes, announced. Backups (research 030). A setting turning destroy off for the away channel. |
 | An agent on the operator's account | Click at the desk, read the desk's keystrokes, read the desktop holder's credential. | No tier accepts the desk without a code or a key touch the controller verifies. A code read off X11 is good for one step, and the race is said above. |
 | A channel module, or its bus account | Forge P1 for approve or acknowledge. | It cannot forge P2 or P3. Destroy needs one of them. |
 | Telegram itself | Read the words. In principle, forge a tap. | The content rule. Destroy needs P2 or P3, which Telegram never sees. |
 **The factors' secrets are the controller's own.**
 - The TOTP seed is made by the mesh. It is enrolled by showing its URI once, only to a terminal, and
  never through a channel or an event.
 - A security key is enrolled by registering its credential's public key.
 - Re-enrolling either is a destroy ask.
 ## The other holders, for authorising
 - **Matrix** can declare everything Telegram does: reactions, replies, a sender authenticated by the
  mesh's own homeserver, codes. It is the self-hosted carrier once its push is measured.
 - **ntfy:** an `http` action makes the phone call the mesh, with a credential inside the notification.
  Nobody knows who tapped, and there is no reply. No tier.
 - **Pushover:** acknowledgement, read back by polling a receipt. At most `acknowledge`.
 - **Mail:** a reply can carry a code, but the sender is forgeable. No tier, except as break-glass.
 ## Sources
 As in [04](04-telegram-as-the-first-holder.md) and [07](07-the-work-context-and-the-desk.md), and:
 - Bot API `callback_data` (1–64 bytes), `answerCallbackQuery`, `ForceReply`, `deleteMessage`:
  https://core.telegram.org/bots/api
 - `answerCallbackQuery` is required even with no text: https://gramio.dev/telegram/methods/answercallbackquery
 - X11 and its clients (input injection, keystroke reading):
  https://hackindex.io/services/x11/exploitation/x11-session-hijacking and
  https://www.semicomplete.com/projects/xdotool/
 - `fido2-assert` (user presence, verifying an assertion):
  https://developers.yubico.com/libfido2/Manuals/fido2-assert.html
 - ntfy `http` actions: https://docs.ntfy.sh/publish/
 - Pushover receipts: https://pushover.net/api
@@ -1,238 +0,0 @@
 # 09 — A proposed decision, and what the operator does now
 This is the effort's reading as of 2026-10-06, written so that playbook 02 can turn it into a record
 and amend to-be 45 §5. It is a proposal: nothing here is decided until it graduates.
 ## The recommendation, short
 1. **The mesh holds a conversation with the operator over channels.** It sends messages and asks;
   the operator answers or writes first. A message, an ask and an operator message are the three
   things said ([06](06-a-conversation-with-the-operator.md)).
 2. **Channels and intake are seats.** One kinded bench each, `channel` and `intake`. Each holder is a
   module of its own, claiming a kind and declaring capabilities from a fixed, versioned vocabulary,
   each with a contract test and a drill.
 3. **Asks are general.** Yes or no, one of, text, number, date, acknowledge, each requiring its own
   capabilities. They have timeouts, defaults, cancellation, batching and history. The answer returns
   to the asker as an event, and an asker may wait.
 4. **The output seat's holder is the router.** It chooses among the channels that satisfy a message or
   ask, by **work context**: in a Telegram conversation, Telegram; at the desk, the desk; away, the
   away channel. Unanswered, it escalates. **Context never lowers the bar** ([07](07-the-work-context-and-the-desk.md)).
 5. **The desk is a full participant.** Notification actions and the launcher's prompt carry every
   ordinary ask, with no account anywhere.
 6. **Asks that authorise are a layer on top,** held by the controller. Three tiers (acknowledge,
   approve, destroy), and three proofs the operator is answering (a verified Telegram sender, a code,
   a security key's touch bound to the ask). The controller checks the channel's declared
   capabilities from its own records and verifies codes and key assertions itself
   ([08](08-asks-that-authorise.md)).
 7. **No agent authorises.** An agent asks; the operator answers where they are. On an X11 desk, where
   an agent could click for them, only a code or a key touch counts. In a Telegram conversation, the
   ask appears in that chat and is completed there, destroy included.
 8. **Telegram is the first holder and the away channel.** It is free, on both phone platforms, needs
   no server of the mesh's own, and is the only candidate that carries every tier
   ([04](04-telegram-as-the-first-holder.md), [05](05-the-other-holders-on-the-same-axes.md)).
 9. **The watcher's watcher stays outside the seats,** with its own bot, on a machine that is not the
   control node. A free outside dead-man service covers the rest. Pushover is the optional holder for
   waking. Matrix is the self-hosted carrier once its push is measured.
 10. **The built Telegram code needs D1–D4 fixed before it is configured**
    ([04](04-telegram-as-the-first-holder.md)).
 ## What the operator does
 Minimal, in order. Steps 1–6 are possible today. The desk needs nothing from the operator: no account,
 no bot.
 1. **Make two bots.** In Telegram, open BotFather and run `/newbot` twice: one for the mesh's
   conversation, one for the watcher. Keep each token out of agent sessions.
 2. **Close them to groups:** `/setjoingroups` → Disable, for each bot.
 3. **Press Start** in each bot's chat. A bot cannot write first.
 4. **Turn on Telegram's two-step verification,** if it is not on.
 5. **Find your chat id.** Until the linking verb exists, call `getUpdates` once, reading the token from
   a file, and take `message.chat.id` from your `/start`. It is the same for both bots.
 6. **Give the mesh the values,** through the controller, never on disk:
   - accept the mesh bot's token as the output seat's holder's own secret `telegram-token`, and set
     its `telegram-chat-id`;
   - assign the watcher to a machine that is not the control node, accept the watcher bot's token,
     and set its chat id;
   - push both machines, and run each module's test verb.
 7. **Later, once built:**
   - make a free dead-man check, and give its ping address to the mesh;
   - enrol an authenticator, at a plain terminal;
   - optionally, enrol a security key, to approve at the desk with one touch.
 ## What would change in the code (proposal, not built)
 - **Now, in the output seat's holder and the watcher:** D1 (cut at 4096 characters), D2 (a reopening
  is a new message), D3 (a clearing reaches the newest message), D4 (`disable_notification` for
  warnings and clearings), then D5–D10.
 - **Catalogue:**
  - a claim carries `kind` and `capabilities`;
  - a kinded bench refuses two holders of one kind;
  - the vocabulary `channel-capabilities/1` and its contract tests;
  - the shared library publishes on a seat's event subjects.
 - **Router:**
  - asks (`ask`, `ask cancel`, `asks`, `answer`, and the events `ask-opened`, `ask-answered`,
    `ask-closed`);
  - the work context, from presence events;
  - the escalation chain.
 - **Desktop:** `node-notifier.send` gains actions, and the holder emits the chosen one. The
  screen-lock holder emits lock and idle changes.
 - **Controller:**
  - `authorises` on the verb definition;
  - `authorise request`, `authorise answer`, `authorisations`;
  - `retire approve` takes `expect`;
  - the authorising verbs refuse direct calls without a code;
  - the hand-act gains `via`, `requested-by`, `ask` and `proofs`;
  - the operator's identities, the TOTP seed and enrolled keys as its own;
  - a self-check probe: the away channel satisfies every tier.
 - **Modules:**
  - a `telegram` module holding `channel` and `intake` (long polling, buttons, replies, `ForceReply`
    codes, a linking verb with a one-time deep-link code), placed where no agent runs as the operator;
  - an agent bridge for operator messages;
  - the dead-man ping.
 ## The tables
 ### Ask kinds × what a channel needs
 | Ask | deliver | choice | reply | threads | Trust (only if it authorises) |
 |---|---|---|---|---|---|
 | a message (no answer) | ✓ | | | | |
 | acknowledge | ✓ | ✓ | | | tier acknowledge: `exact-render` |
 | yes-no | ✓ | ✓ or | ✓ | ✓ | tier approve or destroy, if it authorises |
 | one-of | ✓ | ✓ or | ✓ (a number) | ✓ | as above |
 | text, number, date | ✓ | | ✓ | ✓ | never authorises |
 ### Authorising tiers × proofs
 | Tier | Needs | Telegram | Desk with a key | Desk without a key |
 |---|---|---|---|---|
 | acknowledge | `choice`, `exact-render` | tap | click | click |
 | approve | + one proof | tap (P1) | click + touch (P3) | click + code (P2) |
 | destroy | + two proofs, one of them P2 or P3 | tap + code (P1 + P2) | click + touch + code (P3 + P2) | carried by Telegram |
 ### Surfaces × declared capabilities
 ✓ declared, ~ conditional, blank not.
 | Surface | deliver | reaches-away | loud | silent | edit | choice | reply | threads | operator-first | verified-sender | exact-render | code-factor | key-factor | private | reaches-when-mesh-down |
 |---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
 | telegram | ✓ | ✓ | | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ (placed apart from agents) | ✓ | ✓ | | | |
 | desktop (dunst + launcher) | ✓ | | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | | | ✓ | ✓ | ~ (a key plugged in) | ✓ | |
 | matrix (own server) | ✓ | ~ (push unmeasured) | | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | | ~ | |
 | ntfy | ✓ | ✓ | ✓ | ✓ | | ~ (http action) | | | | | ✓ | | | ~ | ~ (ntfy.sh) |
 | pushover | ✓ | ✓ | ✓ | ✓ | | ~ (acknowledge) | | | | ✓ | ✓ | | | | ✓ |
 | mail (outside relay) | ✓ | ✓ | | ✓ | | | ✓ | ✓ | ✓ | | ✓ | ~ | | | ✓ |
 | an agent's terminal | — | | | | | | ~ (relayed) | | | | | | | | |
 | the console | — | | | | | | | | | | ✓ (own output) | ✓ | | | |
 | the watcher's sender | ✓ | ✓ | | | | | | | | | | | | | ✓ |
 ### Where things go, by context
 The full table is in [07](07-the-work-context-and-the-desk.md). In one line each:
 - **in a Telegram conversation:** that chat;
 - **at the desk:** the desk, or the away channel when the desk cannot carry it;
 - **away:** the away channel;
 - **night:** urgent only;
 - **unanswered:** the next in the chain;
 - **the desk locks:** it moves away.
 ## The proposed record
 > **Title.** The mesh holds a conversation with its operator over channels that are seats, chosen by
 > capability and work context, and an answer that performs an action is authorised by the controller.
 >
 > **Context.** The output channel was built in its minimal form (ADR 0227, to-be 45 §5): one holder
 > carrying the router, a Telegram client and a desktop adapter, and no answering back.
 > - The operator expects many channels and many inputs.
 > - The operator wants agents and modules to ask questions, not only for permission.
 > - The operator wants the work context to choose the channel, and every authorisation completable on
 >   the away channel.
 > - Today, actions that need a person are verbs any granted principal can call, agents included, and
 >   a hand-act records the calling principal, not the person.
 >
 > **Considered options.**
 > 1. Channels as contributions to the output seat. A channel is running code with a secret and
 >    answers, not content a holder places.
 > 2. One seat per channel kind. The router learns every seat.
 > 3. Channel modules found by a manifest field. Callers use seats, never modules (ADR 0126).
 > 4. One notifier with every channel built in. Shared failure, shared secrets, a release per channel.
 > 5. A per-service module with its own approval or question path. Locks the conversation to one
 >    service.
 > 6. **Kinded benches for out and in, a capability vocabulary, a router that holds the conversation
 >    and orders channels by work context, and an authorising layer held by the controller. Chosen.**
 >
 > For answers:
 > - a webhook, or **long polling (chosen)**;
 > - authorising actions called directly by the channel module, or **requested and answered through
 >   the controller (chosen)**;
 > - trusting a desktop click, or **requiring a code or a key touch the controller verifies (chosen)**.
 >
 > **Decision.**
 > - **The conversation.**
 >   - Two mesh seats are kinded benches: `channel` (send, edit, standing) and `intake` (one envelope
 >     per input).
 >   - Each holder is its own module, claims one kind, and declares capabilities from
 >     `channel-capabilities/1`, each with a contract test and a drill.
 >   - The output seat's holder routes messages and asks (yes-no, one-of, text, number, date,
 >     acknowledge) by required capability, then by work context, then by severity, escalating when
 >     unanswered. It says when nothing can carry something.
 >   - Asks have timeouts, defaults (never for an authorising ask), cancellation, a per-asker limit,
 >     batching and 30 days of history. Answers return to the asker as events.
 >   - Presence is current state on the bus, never a history, never in a message's words.
 > - **Asks that authorise.**
 >   - The controller holds them: `authorise request` (anyone; never performs), `authorise answer`
 >     (intake holders only), `authorisations`.
 >   - It checks the caller's declared capabilities from its own records, the sender against its own
 >     list of the operator's identities, codes and key assertions itself, and the exact state's digest,
 >     single use and expiry.
 >   - Tiers acknowledge, approve and destroy require none, one and two proofs. The away channel must
 >     satisfy every tier, checked by the self-check, unless the operator chose otherwise for a tier.
 >   - No agent authorises. The authorising verbs refuse direct calls except as break-glass with a
 >     code.
 >   - The hand-act records `via`, `requested-by`, `ask` and `proofs`.
 > - **First holders.**
 >   - Telegram is the first holder of both seats and the away channel, placed where no agent runs as
 >     the operator.
 >   - The desktop holds both for the desk.
 >   - The watcher's watcher stays outside the seats with its own bot, and an outside dead-man service
 >     is pinged by the self-check and the watcher.
 >
 > **Consequences.**
 > - The output seat's holder loses its Telegram client to a module of its own and gains asks and the
 >   work context.
 > - The catalogue gains `kind` and `capabilities` on a claim, and a second kind of bench.
 > - `node-notifier.send` gains actions.
 > - The controller's verb definition gains `authorises`, and `retire approve` takes the set it
 >   approves.
 > - Agents' grants lose authorising verbs.
 > - To-be 45 §5 is amended: the operator answers.
 > - Telegram sees the words, held to the content rule, and never a factor's secret.
 >
 > **How it is checked.**
 > - **Catalogue tests:**
 >   - an unknown capability is refused;
 >   - two holders of one kind are refused;
 >   - each declared capability's contract test runs in its holder's build.
 > - **Router tests:**
 >   - an ask goes only to channels whose capabilities satisfy it;
 >   - context reorders but never adds a channel;
 >   - an authorising ask never defaults;
 >   - a cancelled ask's copies are edited;
 >   - a fourth open ask from one asker is refused.
 > - **Controller tests,** one per refusal of `authorise answer`:
 >   - from a non-intake principal;
 >   - from a kind that does not meet the tier;
 >   - from an identity not on the list;
 >   - with too few proofs;
 >   - with a used code;
 >   - with a key assertion over another ask's challenge;
 >   - with a stale digest;
 >   - a second answer.
 >
 >   Also: a direct `retire approve` without a code.
 > - **Self-check probe:** the away channel meets every tier.
 > - **Live drills:**
 >   - an agent's question answered at the desk;
 >   - the same with the desk locked, answered on the phone;
 >   - an approve and a destroy on a test condition, answered on the phone, with the hand-acts read.
@@ -1,66 +0,0 @@
 ---
 status: graduated
 initiated: 2026-10-06
 touches:
  - 00-META/how-we-build.md
  - 01-RESEARCH/017-a-mesh-that-heals-itself/00-overview.md
  - 01-RESEARCH/028-the-meshs-output-channel/00-overview.md
  - 01-RESEARCH/019-a-warm-twin-of-the-running-mesh/00-overview.md
  - 02-DECISIONS/0141-the-host-delivers-its-own-successor.md
  - 02-DECISIONS/0162-a-merge-produces-a-tiered-plan-the-mesh-keeps.md
  - 02-DECISIONS/0218-a-plan-sends-grants-before-code-rolls-out-one-machine-first-and-a-newer-merge-takes-over-an-older-plan.md
  - 02-DECISIONS/0224-a-provider-that-keeps-failing-a-consumer-is-a-problem-the-controller-reports.md
  - 03-DESIGN/01-to-be/06-the-controller.md
  - 03-DESIGN/01-to-be/09-the-node-lifecycle.md
  - 03-DESIGN/01-to-be/25-the-bus-on-nats.md
  - 03-DESIGN/01-to-be/30-the-mesh-updates-itself-on-a-push.md
  - 04-ISSUES/187-the-mesh-tells-nobody-when-it-stops-working/00-report.md
 became:
  - 02-DECISIONS/0227-the-core-holds-nine-rules-each-checked-and-is-built-to-them-in-six-phases.md
  - 03-DESIGN/01-to-be/45-a-core-that-cannot-fail-silently.md
 ---
 # 031 — A core that cannot fail silently
 **What.** The principles the mesh's core must hold — the controller, the machine host, the bus, the
 console and the path a change takes through them — so that it is fully diagnosable, monitors itself,
 heals what it knows how to heal, and upgrades itself without a person standing by. And the mechanisms
 and the order in which to build them.
 **Why.** The operator, 2026-10-06: *"I still notice a lot of race issues, and commands being ignored, or
 no feedback, no logs, no monitoring. Our mesh core setup must be fully diagnosable, with active
 monitoring, self-healing, self-upgradeable, self-monitoring. The core principles must be very sturdy, no
 ambiguities, clear plan of execution, fail-proof setup."*
 The record bears it out. In the six days to 2026-10-06, 92 issue reports were opened. Of the 48 read here
 as core failures, **every one was noticed because a person or an agent looked**, and **none was raised by
 the mesh unasked**. Four faults came back through a different door after their first fix, because each
 fix closed an instance and left its class open. One merge was skipped by the bus, and twenty-three over three
 days have no matching action; a provider failed for twenty-three hours with only its own
 journal saying so; seven databases were dropped on one unreadable file.
 **What it touches.** The controller (its verbs, `status`, plans, a lease), the host (its apply and
 report), the bus (its advisories and its upgrade), the console, the build path, the output channel of
 research 028, and the self-healing intent of research 017, which this effort extends from the loops that
 converge modules to the core that runs those loops. 017 deferred heartbeats, conditions and advisories
 until the bus was NATS; it is now.
 **Documents.**
 - [01 — The evidence](01-evidence.md): 48 issues classified by class of failure (races, dropped
  commands, no feedback, logs only, two writers, manual repair, self-upgrade, CI-versus-live, third
  party), with time to detect and how each was noticed.
 - [02 — Principles](02-principles.md): nine, each with what exists, what is missing and **how it is
  checked**; and the candidates weighed and not kept.
 - [03 — Mechanisms and roadmap](03-mechanisms-and-roadmap.md): conditions, watchdogs from a signals table,
  a self-check (`doctor`), the output channel, healers with a hand-act log, a controller lease and report
  sequences, staged core upgrades with rollback, a facts snapshot for merge checks, a lab replay of every
  incident; five phases, ordered by risk removed; the five largest risks today.
 **Graduated 2026-10-06.** The operator approved the conclusion the same day (*"do the research and
 implement it"*). The nine principles and the plan became
 [ADR 0227](../../02-DECISIONS/0227-the-core-holds-nine-rules-each-checked-and-is-built-to-them-in-six-phases.md);
 the mechanisms, the tables and the six phases became
 [to-be 45](../../03-DESIGN/01-to-be/45-a-core-that-cannot-fail-silently.md). The two measurements owed
 — the signals table's bounds and a week of the hand-act log — are Phase 0's work there, not
 preconditions of the decision.
@@ -1,202 +0,0 @@
 # 01 — The evidence, classified by class of failure
 Every issue report opened between 2026-09-30 and 2026-10-06 that bears on the mesh's core — the
 controller, the machine host, the bus, the console, the build path — read in full and classified by
 **the class of failure**, not by the component it was found in. A component view says "fix the host";
 a class view says "the same thing is wrong in four places", which is what a principle is for.
 ## The count
 | | |
 |---|---|
 | issue reports opened 2026-10-01 to 2026-10-06 | **92** (about fifteen a day) |
 | of those (and a few from the days before), classified below as core failures | **48** distinct issues |
 | classified in more than one class | 17 of 48 |
 | a fault that **came back** after a fix of the same symptom | 4 chains: 200 → 265, 230 → 264, 257 → 261 → 267, 175 → 184 → 248 |
 | noticed because a person or an agent looked — at a stalled plan, a wrong outcome, a journal, a test run by hand, a review | **48 of 48** |
 | of those, the mesh's own answer carried the fact for whoever asked (a refusal, a `status` line, a push's output) | 4 (233, 244, 259, 263) |
 | raised by the mesh to anyone, unasked | **0 of 48** |
 The recurrences matter most. Each fix was correct for its instance and left the class standing, so the
 same symptom came back through a different door days later. That is the measurement behind the
 operator's mandate: point fixes are converging on the instances, not on the class.
 ## The classes
 Nine classes, as the mandate frames them. The table under each is the evidence; *detected* is the time
 from the fault's start to the moment anyone knew; *noticed by* is how.
 ### (a) Races: concurrent actors without an ordering
 Two actors act on the same thing, and the order of arrival — not an explicit order — decides the outcome.
 | Issue | The two actors | Detected | Noticed by |
 |---|---|---|---|
 | 204 | an outgoing and an incoming controller both sent declarations | 2 min | a person saw a module undone |
 | 201 | a plan's push carried a controller digest older than its successor had written | 10 min crash loop | a person, nothing answered |
 | 214 | the controller rebuilding itself; the outcome reached the old one or neither | 27 min | a person asked the plan twice |
 | 219 | an older build finishing later replaced a newer one | hours | a person reading builds |
 | 234 | seven declarations arrived during an eleven-minute apply; the newest was composed from a stale view and undeclared four modules | 8 min of removals | a person, the modules were gone |
 | 254 | three plans for three merges ran at once, each asking the same builds | hours | a person, one plan stuck "building" |
 | 256 | a first machine's report landed between a module's two sends and read as stale | 7 min | a person |
 | 257, 261 | the machine's five-minute reconcile and a delivery took the apply lock in the wrong order | 5 min (257), 29 s visible undo (261) | a person |
 | 267 | a reconcile's report queued behind a delivery's apply overtook it at the controller | until a hand push | a person |
 | 265 | a push reloaded the bus's permissions while its own answer was still owed | 54 of 103 pushes over two days | a person, "did not answer in time" |
 **What they share.** Every one is a receiver that kept *the last thing written* rather than *the
 newest thing by an explicit order*. Declarations carry a sequence (issue 107); **reports do not**
 (267 says so: "the report does not carry the declaration's sequence number, so the digest decides").
 Plans are ordered by when they were made only since ADR 0218. Builds are ordered since issue 219.
 Controllers have no epoch, so two instances can both act (204). Ordering was added one message kind at
 a time, each after a race in it was seen.
 ### (b) Commands silently ignored, arguments dropped
 | Issue | What was dropped | Effect |
 |---|---|---|
 | 244 | the console removed `node` from every mesh-seat verb's schema and call | `plan` could only refuse; **`push <one machine>` arrived empty and pushed every machine** |
 | 259 | a named push's flush sent every machine a build a policy held back | a fault met on every machine at once, not one |
 | 202 | a module whose setting was unset was *left out* of the machine | the resolver vanished from a declaration, no error |
 | 188 | a refusal inside "who is on the network" dropped a machine | 40 min, every symptom pointed elsewhere |
 | 231 | a misspelled placeholder written to a file as literal text | passes every check |
 | 241 | an unreadable contributions file read as "nobody asks" | **seven databases dropped and recreated empty** |
 | 255 | the journal verb read nothing and said "-- No entries --" | a refusal that reads as a quiet service |
 | 246 | a runtime that answered late was treated as absent | the console said modules "run nowhere" |
 **What they share.** A receiver that could not tell *nothing was asked* from *something was lost on the
 way*, and chose a default. In 241 and 244 the default was the most destructive reading available.
 ### (c) Outcomes not fed back to the caller
 | Issue | What the caller was told | What happened |
 |---|---|---|
 | 200, 265 | "did not answer in time" | the push ran; the answer was refused by the bus |
 | 176 | the console's build tool neither waits nor registers | — |
 | 229 | `plans` answers once in prose; nothing waits for a plan | an agent went round the mesh with `curl` |
 | 230, 264 | a host stood aside for its successor and its report was cancelled | the plan waited for ever, reading `late: false` |
 | 186 | the build machine dropped 26 of 43 asks; nothing counts asks against outcomes | inferred two hours later |
 | 237 | `assign` answered "held" and "does not resolve for lack of it" in one breath | a person or agent would loop |
 Since 2026-10-06 the controller answers within ten seconds and keeps every call's outcome under an id
 (`calls`, issue 265). Read live the same night: **that log holds the last hundred calls in the
 controller's memory**, so a controller restart — which every merge to the controller's own repository
 causes — forgets every outcome it held. And `status`, a read-only verb, took **18 seconds** to answer,
 twice in a row, so even the health question is answered only through the "still running, ask `calls`"
 path.
 ### (d) Failures visible only as log lines
 | Issue | Where it was said | For how long |
 |---|---|---|
 | 179 (recurred) | the identity provider's journal, every five seconds | **23 hours**, about 31 000 refused logins |
 | 184 | the controller's log: slow consumer, heartbeats dropped | 24 min deaf |
 | 187 | five faults in one day, each found by reading a container's log hours later | hours each |
 | 183, 217, 265 | a `Permissions Violation` line from the bus client library | days |
 | 233 | `status` said `refused`, correctly; nothing said it had lasted | 1.5 h |
 | 243 | nothing: machines silently ignored lower licence generations | until a login waited three minutes |
 | 248 | the controller's event loop stopped logging at 15:17 | hours; "status showed every plan done" |
 | 266 | nothing: a merge was skipped by the bus | **23 unmatched merges over three days** |
 | 238 | a ban list of 400 entries | the operator's own address banned for four weeks |
 `status` printed its all-well sentence through 179, 248 and 266. ADR 0224 made the first of those break
 it. The other two have no signal that `status` reads.
 ### (e) State that two writers own
 | Issue | The two writers |
 |---|---|
 | 190, 222 | the runtime's configuration written by modules that are not the runtime, and by the controller |
 | 201 | the controller seat's row written by a successor, read by a predecessor pushed back in |
 | 239 | two definitions, in two repositories, held one module name |
 | 245 | "behind" answered by a commit comparison beside the plan that already knows |
 | 257, 261, 267 | the machine's state written by both the delivery and the five-minute reconcile |
 | 250 | a merge announced by the forge's tool and by its poll |
 | 179 | the identity provider's admin password: the mesh minted one, the database kept another |
 The operator's direction on 245 is the principle in their own words: *"a second answer to the same
 question is how the two came to disagree."*
 ### (f) Manual repair needed
 Counted from the reports' own "what unblocked it" sections:
 | Repair by hand | Issues | Times |
 |---|---|---|
 | a push by hand to unstick a plan waiting on a report | 230, 257, 264, 267 | at least 4 |
 | a controller restart to recreate a missing object or let go of a held message | 208, 248 | 2 |
 | a one-off program run as the controller, outside the service | 201, 248 | 2 |
 | the identity provider's admin reset through its bootstrap command | 179 | 2 |
 | a kept file restored on a machine by hand | 233 | 1 |
 | a stuck plan closed by hand | 214, 254 | 2 |
 | a ban lifted by hand | 238 | 1 |
 | a consumer remade from now | 248 | 1 |
 ADR 0224 (*detected automatically, repaired where safe, loud where not*) is the first rule that turns
 one of these into a mechanism. 248's `broker consumer-reset` and 254's `plans close` turned two into
 verbs a person runs. Every other row is still a hand on a machine.
 ### (g) Self-upgrade fragility
 The core updates itself: the controller rebuilds and replaces itself, the host delivers its own
 successor (ADR 0141), the runtime and the console are modules, and the bus is a module on the control
 node.
 | Issue | What the self-upgrade broke |
 |---|---|
 | 201 | the controller pushed back to an older build than its own successor's row |
 | 204 | two controllers both sending during a handover |
 | 213, 223 | the controller ran as a container, and a new mesh installed it so |
 | 214 | the plan that rebuilds the controller lost track of it |
 | 230, 264 | the host that stands aside loses the report of the apply that delivered it (fixed twice) |
 | 245 | a rebuild of everything replaced the bus's container: **every runtime lost the bus for a minute** |
 | 248, 266 | a controller restart is where merges go missing: most of 266's 23 lie in such windows |
 | 217 | a refused announcement crash-looped nine runtimes, closing the path that would merge the fix |
 A machine's first-in-line rollout (ADR 0218) protects modules. It does not protect the core from itself:
 the health a plan waits for is "reported applied", which a controller that cannot plan, a host that
 cannot report or a bus that drops messages can each satisfy. Nothing rolls back. The recovery in 201
 was the mesh's own binary run by hand from the newer image.
 ### (h) Checks that pass in CI and fail live
 | Issue | The environmental fact the check did not have |
 |---|---|
 | 177 | the store-backed tests are skipped by the quick check, and the mesh runs none of a module's tests |
 | 236 | the host's declaration validation is not run by the catalogue check |
 | 262 | musl takes an NXDOMAIN for IPv6 as final; glibc does not |
 | 263 | the real machine names make a consumer's identity 23–26 characters against a bound of 20 |
 | 202 | the controller's test against the real catalogue, run by nobody until that day |
 | 228 | the host's removal has no case for a `user` — found by a review, not a test |
 Each check was right about the world it was given. None of them was given the mesh's world: its machine
 names, its catalogue, its host's validation, its C libraries.
 ### (i) Third-party bugs
 | Issue | |
 |---|---|
 | 266 | the bus server's 2.10 release skips messages on a consumer with several filter subjects |
 | 265 | a reload of the bus's authorization forgets every reply permission already granted (documented server behaviour, read from its source) |
 | 262 | a resolver answering NXDOMAIN where NODATA is correct, met by musl's stricter reading |
 The lesson of 266 is not "upgrade the bus" — it is that nothing compared *what was announced* with
 *what was acted on*, so a dependency's bug was silent for three days. A defence in depth (watch the
 outcome, not the transport) would have caught it whichever layer was wrong.
 ## What would have prevented or caught each class
 | Class | Would have been prevented by | Would have been caught by |
 |---|---|---|
 | (a) races | every message ordered by its writer, stale refused by every receiver | a lab replay of the interleaving |
 | (b) dropped | refusing an unknown or unreadable input by name | a schema walk over every verb |
 | (c) no feedback | answer at once with an id; outcome kept durably | a watchdog on "asked and never finished" |
 | (d) logs only | — | a condition in `status` and a notification |
 | (e) two writers | one writer per piece of state | a registry of writers checked at composition |
 | (f) manual repair | a healer for every repair done twice | a counter of hand acts |
 | (g) self-upgrade | one machine first, health-gated, rolled back | a lab upgrade with a deliberately broken build |
 | (h) CI vs live | checks fed the real mesh's facts | the same, before merge |
 | (i) third party | pinning and testing the version that runs | an end-to-end count of announced vs acted |
 The two columns are the principles of [02](02-principles.md). Read by count, **the "caught by" column
 is the cheapest and widest**: a watchdog and a condition would have shortened most of the 48 from "a
 person noticed" to minutes, whatever the cause.
@@ -1,247 +0,0 @@
 # 02 — Principles for the core, each with how it is checked
 Nine principles. Each is stated as a rule a reviewer can refuse a change against, carries the classes of
 [01](01-evidence.md) it answers, says what exists already, and says **how it is checked** — the
 repository's own rule ([how-we-build §5](../../00-META/how-we-build.md)): a rule that states no check is
 indistinguishable from a wrong one.
 They extend, not replace, the six of [research 017](../017-a-mesh-that-heals-itself/01-the-intended-behaviour.md)
 (a loop compares with what is; healing is the ordinary path again; a repair never destroys; nothing fails
 silently; what cannot be fixed goes to an agent; correctness, not only liveness). Those are about the
 loops that converge modules. These are about **the core that runs those loops**: the controller, the
 host, the bus, the console and the path a change takes through them. 017 deferred heartbeats, conditions
 and advisories until the bus was NATS. It is now, so that deferral has expired.
 **The core**, for this document: the controller, the machine host and its launcher, the bus server, the
 tool runtime and the console, the build seat, and the forge's announcer of merges. Everything a change
 passes through before a module's own code runs.
 ---
 ## P1 — One writer per piece of state
 Every piece of state the mesh keeps has exactly one writer, named. Anyone else who wants it changed asks
 that writer; nobody writes beside it, and nobody computes a second answer to a question it already
 answers.
 - **Answers:** (e), most of (a). Issues 190, 201, 204, 222, 239, 245, 250, 257/261/267.
 - **Exists:** the controller is the only writer of stream definitions (to-be 25); ADR 0222 §3 (the
  controller writes no file a seat's holder owns); the collision check at composition (no two modules
  declare one path, unit, name or package); the operator's direction on 245.
 - **Missing:** a single writer for a *machine's applied state* (the delivery and the five-minute
  reconcile both apply and both report — three issues in two days); a single *controller* (two instances
  can both act during a handover, 204: nothing holds a lease); a single announcer per event kind (250
  was found by counting duplicates by hand).
 - **How it is checked:**
  1. A **writers table** — state kind, its writer, where it is kept — is part of the to-be design, and a
     test in each core repository asserts that the code paths that write each kind are the one named
     (by a lint over the store's write calls and the bus subjects each component publishes on, the
     latter read from the grants the controller composes: a subject two components may publish on is
     refused at composition unless the table says it is shared).
  2. **Live:** the controller holds a **lease** (a key-value entry with a revision) and every message it
     sends carries the lease's epoch; a host refuses a declaration from an older epoch and says so. A
     probe ([03](03-mechanisms-and-roadmap.md), the self-check) asserts one lease holder and no message
     from a stale epoch in the last interval.
 ## P2 — Everything that changes state carries its writer's order, and every receiver refuses what is older
 Declarations, reports, plans, builds, calls and announcements each carry `(writer, epoch, sequence)`.
 Every receiver keeps the highest it has accepted per writer, and **refuses** — with a line in the mesh's
 own words and a counter — anything older. Arrival order never decides.
 - **Answers:** (a). Issues 201, 204, 214, 219, 234, 256, 257, 261, 264, 267.
 - **Exists:** a declaration carries a sequence and a host keeps the newest (issue 107, to-be 25 §3); a
  newer build wins over an older one finishing later (219); a newer merge's plan supersedes an older
  one (ADR 0218 §3); a report about a declaration the mesh has moved past no longer replaces the stored
  account (267).
 - **Missing:** a **report carries no sequence** — the digest last recorded as sent decides, which is why
  each of 256, 257 and 267 needed its own rule. No epoch on the controller. A plan's state carries no
  revision, so two instances can both advance it (214).
 - **How it is checked:**
  1. A contract test per message kind, in the receiver's repository: deliver `n`, then `n−1`; the state
     names `n` and a refusal is counted. Deliver from epoch `e−1` after `e`: refused. A new message kind
     without such a test fails a check that lists every subject the component consumes against the
     tests that name it.
  2. **Live:** the refusals counter is a signal (P5): zero is normal, a burst is a condition naming the
     writer that sent stale.
 ## P3 — Every command is acknowledged at once, and its outcome is kept where it can be read later
 A call is answered within a bound the caller can rely on — with its result, or with an id. Its outcome is
 kept **durably**, outlives the process that ran it, and can be read by id or waited on. Nothing is fired
 and forgotten, and no answer depends on what the command does to the transport carrying it.
 - **Answers:** (c). Issues 176, 186, 200, 229, 230, 237, 264, 265.
 - **Exists:** since 265, a seat's call answers within ten seconds or says "running" with an id, `push`
  answers before it acts, and `calls` keeps the last hundred calls and their answers; the build path
  says "asked, not waited for" and ADR 0219 §3 makes every cancel/kill leave an outcome.
 - **Missing:** `calls` lives in the controller's memory, so **a controller restart forgets every
  outcome** — and the controller restarts on every merge to its own repository. Nothing waits on a plan
  (229). Observed the night this effort began: the read-only `status` took 18 s, so the health question
  itself is answered through the "still running" path.
 - **How it is checked:**
  1. A test that walks every verb the controller announces: each answers within `AnswerWithin`, with a
     result or an id (already partly built for 265).
  2. A test that restarts the controller between a call and the read of its outcome: the outcome is
     still there.
  3. **Live:** a probe calls `status` and asserts it answers *in full* within the bound; a call
     `running` for longer than its verb's declared bound is a condition (P5).
 ## P4 — Nothing is dropped silently: an input that is unknown, unreadable or unmet is refused by name
 A receiver that cannot read, place or honour an input refuses it and says which, where and why. It never
 substitutes a default — above all never "empty" — for "I could not tell". An unknown argument, key,
 placeholder, seat or subject is refused, naming it.
 - **Answers:** (b). Issues 188, 202, 231, 241, 244, 246, 255, 259.
 - **Exists:** the host's parser refuses unknown keys (ADR 0007, 0045); an undeclared setting or endpoint
  is refused (ADR 0164, 0138); a verb takes only its declared arguments (ADR 0154) and, since 244, the
  controller and the console refuse an undeclared one by name; a seat the mesh does not answer is
  refused by name (ADR 0222 §1); ADR 0219 §3, "nothing dropped is silent".
 - **Missing:** the rule is in a dozen records and in no principle, so each new reader re-meets it. The
  destructive form — **an unreadable input read as "nothing asked", then acted on** (241) — has no
  general guard.
 - **How it is checked:**
  1. Per component, a test that feeds each input reader an unreadable, malformed and foreign input and
     asserts a refusal, never an empty result. A reader whose error path returns an empty value fails a
     lint that the core repositories run (the shape is mechanical: an error branch that returns the
     zero value of a collection).
  2. Schema walks for every verb (244's tests) and every placeholder namespace (231).
  3. **Destructive deltas are braked**: a reconcile that would withdraw more than a bound of what it
     holds (one consumer, one module, a fraction set per provider) stops and raises a condition instead
     (P7). Checked by a test that empties the input and asserts nothing is withdrawn.
 ## P5 — Every expected signal has a watchdog: absence is itself a condition
 Every signal the core expects on a cadence or after an act — a heartbeat, a report after a send, a
 plan's progress, a build's outcome after its ask, the controller's event loop taking something in, a
 provider's standing, an announcement turning into an action — has a declared bound. Silence past the
 bound is raised as a condition, naming what was expected, from whom, since when.
 - **Answers:** (c), (d), (i). Issues 179, 184, 186, 187, 230, 243, 248, 257, 264, 266, 267.
 - **Exists:** a machine's "last heard from — out of touch N m" in `node show`; ADR 0090's stuck machine
  (three identical reports); ADR 0224's provider standing, shown with its silence after thirty minutes;
  266's catch-up of merges not acted on after ten minutes (the first true *announced-versus-acted*
  watchdog); ADR 0162's bound on a plan, which 230 found never fires (`late: false` for ever).
 - **Missing:** a list of the signals, their bounds and their owners; the plan bound working; the event
  loop's last-taken age (187); asks counted against outcomes (186); the bus's own advisories (slow
  consumer, maximum deliveries, permission violations) read as observations instead of log lines.
 - **How it is checked:**
  1. A **signals table** — signal, emitter, cadence or trigger, bound, condition raised — kept in the
     to-be design, and compiled into the controller. A test generated from it suppresses each signal in
     turn and asserts the named condition is raised within its bound and cleared when the signal
     returns.
  2. **Live:** the self-check (P6) reports, for every row, the age of the newest signal, so a row that
     never fires is itself visible.
 ## P6 — The mesh checks itself continuously, against live facts, and says what it found outward
 The invariants the design states are probed **against the running mesh** on a schedule, not only in unit
 tests. A violation is a **condition** — durable, with since-when, evidence and who can resolve it —
 shown in `status` and **sent to the operator** through the output channel. The checker's own heartbeat is
 watched from somewhere it does not run.
 - **Answers:** (d), (h). Issues 177, 187, 238, 245, 253, 262.
 - **Exists:** `status` itself (assembled from reports, as how-we-build §5 requires); 017's *condition*
  shape; 028's output seat, researched only; individual live checks done by hand (262: "the live check
  stays by hand, on each resolver"); 253's measurement before the collector's first run — the one time
  in the window a check ran before the damage.
 - **Missing:** a scheduled runner, a condition store, a channel out, and a watcher's watcher.
 - **How it is checked:**
  1. Every invariant in the to-be design that names a live check is a **probe** in the self-check's
     registry; a check over the design documents counts invariants with a stated live probe against
     those without, and the number may only go down.
  2. The self-check publishes a heartbeat; a second machine's watcher raises "the self-check is silent"
     through a channel that does not depend on the control node.
  3. **Live, once:** a deliberately broken invariant on a lab mesh appears in `status` and as a
     notification within one probe interval.
 ## P7 — A known failure heals itself, under a brake, and every repair is said
 A failure that has been repaired by hand twice is a failure the mesh must repair itself: by running the
 ordinary path again (017 P2), never by destroying (017 P3), with a budget and a back-off, and with one
 line and one event saying what it did and why. When the budget is spent, or the only repair destroys,
 it is a condition and a notification, not a retry.
 - **Answers:** (f). Issues 179, 208, 214, 230, 233, 248, 254, 257, 264, 267.
 - **Exists:** ADR 0224 §5, *detected automatically, repaired where safe, loud where not*, applied to the
  identity provider's admin; the host's launcher rolls back once to known-good and then halts (ADR
  0141); the provisioner's `holds` re-provisions what a backend lost (017/02); `broker consumer-reset`
  and `plans close` as verbs.
 - **Missing:** the general mechanism. The most frequent hand act in the window — **a push by hand to
  unstick a plan waiting on a report** — has no healer: the controller could ask the machine to report
  again (the machine knows what it applied) before waiting longer.
 - **How it is checked:**
  1. Every hand act on the core is done through a verb that records it (who, what, why) — the **hand-act
     log**. Its count per week is a reported number; an act recorded twice for the same cause is a
     condition asking for a healer.
  2. Each healer ships with a test that induces its failure, asserts the repair and the event, and
     asserts the brake after the budget.
 ## P8 — The core upgrades itself one machine at a time, health-gated, and rolls back on its own
 A new controller, host, runtime or bus reaches one machine first; it is **healthy** only when the
 self-check's probes for that component pass there (not merely when it "reported applied"); the rest
 follow only then. A component that does not become healthy within its bound is rolled back to the last
 known good **by something other than itself**, and the rollback is said. The component being replaced is
 never the only witness of its successor's success.
 - **Answers:** (g). Issues 201, 204, 213, 214, 217, 230, 245, 248, 264, 266.
 - **Exists:** ADR 0218's one machine first, for modules, with "applied and current" as the gate; ADR
  0141/0142's side-by-side host versions, known-good and the launcher's single rollback; ADR 0185's
  controller serving what it can when it is behind its seat's row; 264's report kept on disk across the
  hand-over.
 - **Missing:** a health definition per core component; a gate stronger than "reported"; rollback for
  the controller, the runtime and the bus; a lease hand-over between controllers (P1); a planned,
  rehearsed path for the bus, which is still one process on one machine and whose next upgrade (266:
  2.10 → 2.11) is one-way.
 - **How it is checked:**
  1. **Lab:** a deliberately broken build of each core component (one that starts and does nothing; one
     that crashes; one that cannot reach the bus) is merged on a lab mesh. Each is rolled back without a
     hand, the mesh ends on the previous build, and a condition and a notification say so.
  2. **Live:** every core rollout leaves a record — first machine, health verdict, time to verdict,
     rolled back or not — readable through `plans`.
 ## P9 — A check is fed the real mesh's facts before a change is merged
 A check whose verdict depends on the environment — names and their lengths, the machines that exist,
 the catalogue as it is, the host's validation, the C library, the server versions — runs against **the
 mesh's real facts**, exported and anonymised, before merge. A dependency's version that the mesh runs is
 the version its tests run.
 - **Answers:** (h), (i). Issues 177, 202, 228, 236, 262, 263, 266.
 - **Exists:** 266's `TestTheImageIsTheServerTestedHere` (the bus image's release equals the tested
  server's); ADR 0223's composition test that renders the resolver's machine list; 202's test against the real
  catalogue (run by hand).
 - **Missing:** the export of facts; a merge gate that composes every real machine's declaration with the
  change and runs the host's validation over it (which would have refused 236, 263 and 202 in their own
  pull requests); a resolver test under musl as well as glibc.
 - **How it is checked:**
  1. The controller exports a **facts snapshot** (machines, names, assignments, seats, catalogue
     commit — no secrets, no addresses) daily; the core repositories' merge check composes every machine
     from it with the change applied and runs the host's validation; a pull request that makes any
     machine fail to compose or validate fails its check, naming the machine's role and the module.
  2. The snapshot's age is a signal (P5).
 ---
 ## Candidates weighed and not kept as principles
 - **"Every invariant has a live probe, not only a unit test"** — merged into P6; it is how P6 is built.
 - **"Environment-dependent checks run against the real mesh's facts"** — kept as P9; the third-party
  case (i) folded into it, because pinning and testing the version that runs is the same act.
 - **"Self-healing is the default"** — kept as P7 but narrowed to *known* failures, those repaired by
  hand twice. A default of healing everything heals what is not understood, which is how a repair
  destroys (241's reconcile was, in its own terms, healing).
 - **"No loop blocks on long work"** (184, 248, 175) — not a separate principle: a blocked loop is a
  signal gone silent (P5, the loop's last-taken age) and a design defect each owner fixes; stating it
  as a principle adds a rule with no mesh-wide check.
 - **"Clear plan of execution"** from the mandate — not a principle about the mesh; it is the roadmap in
  [03](03-mechanisms-and-roadmap.md), and each phase there states its own verification.
 ## How the principles relate
 P2 and P1 **prevent** the races. P4 **prevents** the silent drops. P3, P5 and P6 **catch** whatever the
 first three miss, at the cost of minutes, not hours. P7 and P8 **repair**. P9 **moves** the catching
 before merge. The order of the roadmap follows from that: catching first, because it is cheapest and
 covers every class, including the ones nobody has met yet.
@@ -1,221 +0,0 @@
 # 03 — Mechanisms and a phased roadmap
 The principles of [02](02-principles.md) need few new things. Most of the parts exist in some form;
 what is missing is the connective tissue that makes a fact the mesh already has reach someone without
 being asked. This document names the mechanisms, then orders them into phases **by risk removed per unit
 of effort**, each phase with deliverables and a verification that says it is done.
 Effort is given in **focused working days** of one agent-and-operator pair, at the pace the record shows
 (a located issue to a merged fix in under a day is common). The figures are for ordering, not promises.
 ## The mechanisms
 ### M1 — Conditions (P5, P6)
 017's *condition*, built: a durable fact about something the mesh owns — what is wrong, since when, the
 evidence, what was tried, who can resolve it, and whether it may clear itself. Kept in a key-value
 bucket the controller writes (one writer, P1), keyed by subject (`plan/<id>`, `machine/<role>`,
 `provider/<module>/<consumer>`, `core/<component>`). Raised and cleared by observation only; a person
 can **silence** one for a stated time, never resolve it. `status` becomes, first, the list of open
 conditions; the all-well sentence is "no open conditions". ADR 0224's provider standing is the first
 condition kind and moves into it unchanged.
 ### M2 — Watchdogs from a signals table (P5)
 One table, compiled into the controller, of every signal the core expects. Its first rows, each from an
 issue in [01](01-evidence.md):
 | Signal | Bound (to be measured, then set) | Condition raised | Issue |
 |---|---|---|---|
 | machine heartbeat | 3 × interval | machine silent (asleep is a declared state, ADR 0211) | 187 |
 | report after a send | the machine's last apply duration × 3, at least 2 min | sent, not reported — then **ask the machine to report again** (M5) | 230, 257, 264, 267 |
 | plan tier progress | per tier, from build and apply durations | plan stalled at tier N, waiting on X | 214, 230, 254 |
 | controller event loop took something | 2 min while the stream has pending | controller deaf | 184, 248 |
 | merge announced → plan made or "nothing reads it" | 10 min (exists, 266) | merge never acted on | 248, 266 |
 | build asked → outcome | build's own declared timeout | ask lost | 186 |
 | call `running` → finished | the verb's declared bound | call hung | 265 |
 | provider standing repeated | 30 min (exists, ADR 0224) | provider silent | 179 |
 | bus advisories: slow consumer, maximum deliveries, permission violation | any | bus refused or dropped X for Y | 183, 187, 217, 265 |
 | self-check heartbeat | 2 × its interval, watched from a second machine | the watcher is silent | — |
 | facts snapshot age | 2 days | merge checks run on stale facts | 263 |
 The bus advisories are the cheapest row: the server already publishes them on its system subjects, and
 the controller only has to subscribe (read-only) and translate each into the mesh's words, naming the
 call or the consumer, as 265 now does for a refused reply.
 ### M3 — The self-check: `doctor` (P6)
 A controller verb, `doctor`, and the same code run every few minutes by the controller itself. Each run
 executes the **probe registry** — the live form of the design's invariants — and raises or clears
 conditions. First probes, each an invariant that a person checked by hand in the window:
 - every machine's declaration composes, and every host would accept it (236, 263);
 - every holder of the mesh's resolver answers a machine name for IPv4 and NODATA for IPv6 (262);
 - every seat on record has a live holder that answers (208, 218);
 - every kept archive is held by a manifest (253 — the controller's collection command already reports it);
 - exactly one controller holds the lease (P1);
 - every durable consumer's position is near its stream's head (248's replay, 266's skip);
 - no address the mesh owns is in a ban list (238);
 - `status` answers in full within its bound (P3).
 `doctor` with no argument answers the last run's verdict at once (P3) and, with `run`, runs now under an
 id. Its own heartbeat is a signal (M2), watched from a second machine.
 ### M4 — The output channel (P6)
 [Research 028](../028-the-meshs-output-channel/00-overview.md)'s seat, built minimally first: **one**
 channel the operator chose (028 records it), plus the desktop notifier where the operator is. A condition
 is sent when raised, once more if it lasts past a bound, and when it clears. Deduplicated by the
 condition's key. The watcher's watcher (028's open question) is the second-machine watchdog of M3,
 sending through a channel that does not pass through the control node.
 ### M5 — Healers (P7)
 A healer is a registered response to one condition kind: its repair (the ordinary path again), its
 budget, its brake, and the event it emits. First healers, all from hand acts in [01](01-evidence.md) §(f):
 | Condition | Repair | Brake |
 |---|---|---|
 | sent, not reported | ask the machine to report what it last applied (it keeps it since 264); if that names another declaration, send again | twice, then condition |
 | plan stalled on a superseded or finished wait | close the plan with its note (`plans close`, done by the mesh) | once |
 | seat holder without its worker | raise the seat's objects again (208) | once per holder |
 | consumer far behind on a history stream | `broker consumer-reset` (248) — **only** for the consumers the table marks resettable | once, then condition |
 | provider admin refuses the mesh's secret | ADR 0224 §5 (exists) | exists |
 And the **hand-act log**: every repair a person makes on the core goes through a verb that records who,
 what and why. Its weekly count is the measure of P7.
 ### M6 — Order and epochs (P1, P2)
 - The controller takes a **lease** in a key-value bucket before it acts and renews it; its revision is
  the **epoch** every declaration and plan write carries. A starting controller waits for the lease;
  the outgoing one stops sending when it loses it. That closes 204 and makes 201/214 detectable.
 - A **report carries the sequence** of the declaration it is about; the controller keeps the highest
  per machine and refuses older accounts by sequence, not by a digest lookup (256, 257, 267 become one
  rule).
 - **The host has one apply queue.** A delivery and the reconcile are two reasons to enqueue the same
  act; the queue applies the newest declaration once, and makes one report (257/261/267 become
  impossible rather than handled).
 - Every receiver's refusal of something stale is a counted line (P2's live check).
 ### M7 — Staged, reversible core upgrades (P8)
 - **A health definition per core component**, written as probes in M3's registry: the controller
  answers `status` in bound and holds the lease; the host has reported its current declaration; the
  runtime has announced and answers a PING; the bus has every stream and every durable consumer and
  passes a request/reply round trip.
 - **The gate:** ADR 0218's first machine is judged by those probes, not by "applied".
 - **Rollback by a witness that is not the new build:** the host's launcher for the host (exists); for
  the controller, the previous controller's process kept installed beside it, re-started by the host
  when the new one does not take the lease in bound; for the runtime, the host's known-good the same
  way. Each rollback is a condition, so it is said.
 - **The bus is planned, not rolled.** A bus upgrade is a declared maintenance step: streams snapshotted,
  the step announced as a condition while it runs, every consumer's position checked after (M3). The
  one-way 2.10 → 2.11 upgrade of 266 is the first. Whether the bus should become a cluster of three so
  that it can be upgraded live is a question for its own effort.
 ### M8 — The facts snapshot and the merge gate (P9)
 The controller exports a facts snapshot (machines by role and name length, assignments, seats, catalogue
 commit) to a place the build seat reads. The core repositories' and the catalogue's merge checks compose
 every machine with the change and run the host's validation. The resolver module's tests run under musl
 and glibc. A bus, store or library version the mesh runs is the one its tests run (266's pattern,
 generalised).
 ### M9 — The lab replay (all)
 [Research 019](../019-a-warm-twin-of-the-running-mesh/00-overview.md)'s warm twin, or a throwaway lab of
 three containers, running **scripted replays of each incident** in the window: a reconcile due during a
 push; a host self-update during its report; a bus reload during a call; a consumer with several filters
 under mixed traffic; a missing consumer made with the server's default; an unreadable contributions
 file; a controller rebuilding itself mid-plan; two controllers at once. Each replay asserts the
 principle's outcome (refused stale, condition raised, healed, rolled back). They run on every merge to a
 core repository.
 ---
 ## The roadmap
 Ordered by **risk removed per day**. Detection comes first because it covers every class at once,
 including the ones not met yet; prevention second; repair and staging third; the pre-merge and lab work
 last because they are larger and pay off over months.
 ### Phase 0 — Finish what is in flight (2–3 days)
 - Land and roll out the located fixes: 244, 264, 265, 266 (including the bus's planned 2.11 upgrade, done
  as M7's first planned bus step), 267, 257/261.
 - Make `calls` durable (a key-value bucket, bounded by count and age), and bring `status` inside its own
  answer bound.
 - Start the **hand-act log** now, before anything else, so every later phase is measured against a
  baseline.
 - **Done when:** the four located core issues resolve with their live checks; a controller restart
  keeps `calls`; `status` answers in full within ten seconds.
 ### Phase 1 — The mesh says when it is wrong (5–8 days)
 - M1 conditions (ADR 0224's standing moved into them); M2 watchdogs for the first eight rows; the bus
  advisories subscribed and translated; M3 `doctor` with the first probes; M4 with one channel and the
  second-machine watcher.
 - **Done when:** on a lab mesh, suppressing each signal in the table raises its condition within its
  bound and sends a notification; clearing it clears both. Live: a week of conditions read back, every
  one either real or a bound corrected.
 - **Risk removed:** every class in [01](01-evidence.md) moves from "noticed by a person, hours later" to
  "said by the mesh, minutes later".
 ### Phase 2 — Order and one writer (5–7 days)
 - M6: the controller's lease and epoch; a report's sequence; the host's single apply queue; stale
  refusals counted.
 - The writers table and the signals table written into a to-be design, with their compile-time checks.
 - P4's lint for empty-on-error readers in the core repositories, and the destructive-delta brake in the
  provisioner harness.
 - **Done when:** the lab replays of 204, 257/261/267 and 241 end with "refused stale", "one report" and
  "withdrawal braked" respectively; the contract test for every consumed subject exists.
 - **Risk removed:** class (a), the largest by count, and the destructive half of (b).
 ### Phase 3 — Healers (3–5 days)
 - M5's first healers and the rule that a repair done by hand twice asks for one (from the hand-act log).
 - **Done when:** a lab mesh recovers from each induced failure in the healers table with no hand, says so,
  and brakes after its budget. Live: a week in which the hand-act log has no repeat.
 ### Phase 4 — Core upgrades that roll back (8–12 days)
 - M7: health definitions; the gate; rollback for the controller and the runtime; the bus as a planned
  step.
 - **Done when:** on a lab mesh, a deliberately broken build of the controller, the host and the runtime
  is each rolled back without a hand, the mesh ends on the previous build, and the rollback is a
  condition and a notification. Live: the next three core rollouts each record a health verdict.
 - **Risk removed:** class (g) — the failures that take the control path itself down.
 ### Phase 5 — Checks before merge, and the replay suite (8–12 days, then ongoing)
 - M8: the facts snapshot and the compose-and-validate merge gate; the libc matrix; versions tested as
  run.
 - M9: every incident in the window as a scripted replay, run on every core merge; each new core issue
  adds its replay as its "how it is checked".
 - **Done when:** the replays of 236, 262, 263 and 266 fail on the commit before their fix and pass after;
  a new core issue cannot resolve without a replay or a stated reason why none is possible.
 **Total, roughly six to eight weeks of focused work**, with the first visible change — the mesh saying
 when it is wrong — inside the first two.
 ## The five largest risks today
 Ranked by likelihood × damage, from the window's evidence and the mesh as read the night this effort
 began:
 1. **A stall nobody is told about.** A plan, a merge or a report that stops is noticed only by someone
   looking (230, 248, 257, 264, 266, 267; issue 187 still open). Every release goes through a plan.
 2. **A destructive act on a misread input.** 241 dropped seven databases on one unreadable file; 234
   undeclared four modules from a stale composition; 245's advice rebuilt everything and cut the bus;
   253's collector would have deleted every archive. There is no general brake on a large withdrawal.
 3. **The core replacing itself with nothing to roll it back.** A controller build that starts but cannot
   plan (201, 214) halts every later change, because the controller is what plans the fix. Only the
   host has a launcher rollback.
 4. **The bus as a single, un-upgradeable process.** It runs a release that skips messages (266), its
   reload drops owed replies (265), replacing it cuts every machine off (245), and its next upgrade is
   one-way and needs a restart.
 5. **Concurrent actors with no lease or report order.** Several agent sessions, plans and reconciles act
   at once; on the night this began, four named pushes, one per machine, started within two seconds. The digests
   catch most of it now, one rule per message kind; the next message kind will not have one.
@@ -1,85 +0,0 @@
 ---
 status: graduated
 initiated: 2026-10-06
 became: [02-DECISIONS/0240-a-module-says-how-it-is-healthy-and-the-node-engine-judges-it.md, 03-DESIGN/01-to-be/48-a-module-says-how-it-is-healthy.md]
 touches:
  - 03-DESIGN/01-to-be/45-a-core-that-cannot-fail-silently.md
  - 03-DESIGN/01-to-be/18-building-a-module.md
  - the module manifest
  - the node-engine
  - the release gate
 ---
 # 032 — A module says how it is healthy
 ## What is investigated
 Whether, and how, every module should declare **how its own health is checked**, as a field of its
 manifest, so the mesh can judge a module the way it already judges its core parts.
 Today the release gate ([ADR 0236](../../02-DECISIONS/0236-a-build-is-judged-on-its-first-machine-and-put-back-by-something-other-than-itself-and-so-it-rolls-out-unattended.md)) judges a
 module on its first machine by what the mesh can see from outside: the declaration applied, no new
 condition about the module or its machine since the send, and its tools answering. It does not see
 whether the module's own service works. A container that applied cleanly and then restarts in a loop,
 a web application whose port is open but whose pages fail, a database that accepts connections and
 refuses queries — each passes the gate and is caught only through what it breaks later, if anything
 notices at all. To-be 45 names this gap ("no container state in the gate").
 The questions:
 1. **What a health declaration says.** The kinds of check a module may declare (a container's own
   health state, an HTTP request and the answer expected, a TCP connect, a command run inside the
   service, a query, a tool of the module's own that answers "healthy"), its interval, its timeout,
   how many failures in a row count, and a start period during which failure does not count.
 2. **Who runs the checks, and where the result goes.** The node-engine on the machine, the node tools,
   or the module itself; how the result reaches the controller (the report, an event, a seat verb); and
   what the release gate, the self-check and the healers do with it.
 3. **What the mesh already has to build on.** Container runtimes' own healthchecks, which many images
   ship and which the mesh neither reads nor sets today; systemd's own state for services; the tools a
   module already serves.
 4. **What "healthy" covers.** Liveness (it runs), readiness (it serves), and whether a module's health
   may depend on what it requires (a provider down makes its consumers unhealthy — said once, at the
   provider, not once per consumer).
 5. **The cost and the noise.** How often checks may run across all modules on a small machine, and how
   a check avoids the single-sample flaw the self-check already met (issue 277).
 6. **Migration.** How every catalogue module gets a declaration, what a module without one is judged
   by, and whether `module check` should require one.
 ## Why
 The mesh now rolls a module out on its own, one machine first, and puts the previous build back when
 the first machine is not healthy. That promise is only as good as "healthy" is, and for a module it is
 today judged from the outside. Making each module say how its health is checked turns "applied" into
 "working", for the gate, for the self-check and for whoever asks.
 ## What it touches
 The module manifest and `module check`; the node-engine, which would run or read the checks; the
 release gate and the doctor probes of to-be 45; the healers, which may restart what stays unhealthy;
 the operator's conversation (ADR 0234), which carries what stays unhealthy; and every catalogue module,
 each of which would gain a declaration.
 ## Where it stands
 Evidence gathered on the live mesh, options weighed and a decision drafted, 2026-10-07:
 - [01 — The evidence](01-evidence.md): 125 catalogue modules, 68 of them running something long-lived
  (49 a container, 19 a service); no manifest can declare a check and nothing reads one; 19 of 73
  long-running catalogue containers carry an image check, two of which were wrong in the mesh's hands;
  every restart count is 0 because a recreate loses it, and the runtime's event history is about a minute
  long. Of seven recent incidents, liveness alone would have caught the crash loop, readiness the
  eleven-hour silent web app, and only a module's own tool the refused identity-provider admin.
 - [02 — Options](02-options.md): who runs the checks, where the result goes, liveness and readiness,
  dependency-aware health, the field's shape and the migration.
 - [03 — Recommendation](03-recommendation.md): liveness judged for every long-running resource at once;
  readiness declared per resource in a field named `health` and run by the node-engine; the state in the
  report, the condition raised by the controller on the second look, so the gate needs no new rule; a
  provider down said once at the provider; a proposed decision text with how each rule is checked, and
  the migration of the 68 modules.
 **Graduated 2026-10-07** on the operator's word (*"yes, turn it into a decision"*), as
 [ADR 0240](../../02-DECISIONS/0240-a-module-says-how-it-is-healthy-and-the-node-engine-judges-it.md) and
 [to-be 48](../../03-DESIGN/01-to-be/48-a-module-says-how-it-is-healthy.md). The record takes the proposed
 decision, adding: a fifth state, `held`, for a resource under a maintenance step; a ceiling of five minutes on
 grace plus failing looks, so a broken start is said inside the gate's bound; and the gate's *own health* reading
 the stated health, so a resource still starting is not yet a pass.
@@ -1,196 +0,0 @@
 # 01 — The evidence
 Measured on 2026-10-07 on the live mesh of four machines (a home server, a control node, a workstation
 and a laptop), read only: the three catalogue repositories at their trunk, the controller's and the
 node-engine's source at their trunk, each machine's container runtime and service manager, and the
 controller's own answers. Counts, not anecdotes. Machines are named by role.
 ## 1. What the catalogue runs
 The three catalogue repositories hold **125 module manifests**: 113 in the main catalogue, 12 in the
 media catalogue. The photos repository holds application code and no manifest; its two instances are
 modules in the main catalogue.
 Each manifest sorted by the **longest-lived thing it runs** (a container that stays up first, then a
 service the manifest says is running, then the mesh's own process that stays up, then a bundle only):
 | What a module runs | Modules |
 |---|---|
 | at least one container that stays up | **49** |
 | no such container, but a service unit stated `running` | **19** |
 | only its bundle — tools and handlers hosted by the node tools | **50** |
 | only files, directories and packages | **7** |
 Underneath:
 | Resource | Count | Of which |
 |---|---|---|
 | container | **85** in 50 modules | 77 stay up, 6 run once (a step), 2 on a schedule; **71 distinct images** |
 | service (an existing unit put in a state) | **31** in 21 modules | 26 stated `running`, 5 stateless (the machine's lifecycle) |
 | process (the mesh's own code in a unit it writes) | **20** in 18 modules | 17 run once, 2 on a schedule, **1** stays up |
 | bundle artifact | **101** in 99 modules | |
 And what a check could be built from:
 - **50** modules declare `listens` (an endpoint, a port, a protocol) — **48 of the 49** container
  modules. A TCP or HTTP check has its target named already.
 - **53** modules declare `tools`. **One** tool in the whole catalogue is a health tool by name
  (`dbus_health`); **18** modules have a tool named `…_status`.
 - **67** modules `require` something; the most-required provisions are `route` (36 consumers),
  `x11-display` (15) and `postgres-database` (12). A database down is, today, potentially twelve
  consumers failing at once.
 - **No manifest declares a health check.** The container resource has no field for one — its fields are
  image, environment, files, ports, volumes, arguments, names, networks, capabilities, logging, the
  restart triggers and the run-once and schedule modes — and the node-engine passes the runtime no
  health option. Whatever check runs is the image's own, run by the runtime by default.
 ## 2. What the images already ship, and what the runtime says today
 Every container on every machine inspected — its state, its health, its restart count, and its
 **image's** healthcheck from the image configuration:
 | | |
 |---|---|
 | containers on the four machines | **115** (94 running) |
 | of those, declared by the catalogue and running | **79 instances** of **73** of the 77 long-running containers (4 are assigned nowhere) |
 | long-running catalogue containers whose **image ships a HEALTHCHECK** | **19 of 73 (26 %)** |
 | …in how many modules | **7 of 45** modules with a running container (mail, the hosted database suite, a spreadsheet app, the chat client, a flow editor, the media server, the certificate authority) |
 | …modules whose every container has one | **4** |
 | running container modules with **no health state at all** | **38 of 45** |
 | catalogue containers reporting `healthy` / `unhealthy` / `starting` | **19 / 0 / 0** |
 | containers reporting `unhealthy` | 5, all exited, all on the workstation, all predating the mesh (none declared) |
 **Two of the nineteen image checks were wrong under the mesh's own configuration** until a catalogue fix:
 - the hosted database suite's studio — the framework binds the address the runtime puts in `HOSTNAME`, so
  it answered only on its network address while its image's check asked `localhost`: *unhealthy for ever
  while working* (fixed 2026-10-05);
 - the flow editor — the image's check reads its settings from a path the module mounted elsewhere: *ran
  fine but reported unhealthy forever* (fixed 2026-09-30).
 So 2 of 19 shipped checks (≈ 10 %) gave a false *unhealthy* in the mesh's hands. Read blindly, they would
 have failed two good builds at the gate.
 The intervals the images chose range from **2 s to 60 s**: a database every 2 s, three web apps every
 5 s, an API gateway every 10 s, the rest 30 s or 60 s. Start periods range from none to 360 s (the
 antivirus). Retries from 3 to 20.
 ### The restart count the runtime keeps is lost
 **All 94 running containers report a restart count of 0** — including the agent server that, per
 [issue 268](../../04-ISSUES/268-letta-printed-its-passwords-into-its-log/00-report.md), had restarted about
 a hundred times in a crash loop days before. The counter belongs to a container, and the node-engine
 recreates a container whenever its declaration or a file it reads changes; the fix recreated it and the
 history went with it. A restart count is only evidence if something outside the container keeps it.
 ### The runtime's event history is about a minute long
 The runtime keeps its most recent ~250 events in memory. On the home server, a query for the last 30
 minutes and for the last minute both answered ~250 events, **every one an `exec_*` event** — the image
 health checks running (84 creates, 85 dies, 84 starts). A 24-hour query for container lifecycle events,
 through the mesh's own `docker_events` tool, answered **zero**. The images' checks crowd every lifecycle
 event out of the history within a minute. A container that died an hour ago leaves no trace there.
 ## 3. What the service manager says today
 - **Failed system units:** 0 on three machines; 2 on the workstation, both mounts that the mesh does not
  declare. One failed user unit on each of two machines, neither the mesh's.
 - The mesh's own units (`mesh-ca-trust`, `mesh-filter`, the power units, the controller, the node tools,
  the node-engine): all `active`, **`NRestarts` 0**.
 - systemd already gives, per unit and for free: `ActiveState`/`SubState`, `is-failed`, `NRestarts`,
  the time it entered its state, and — through a unit's own `ExecStartPost`/`WatchdogSec` where software
  supports it — readiness. None of it is read by the mesh for a module's unit.
 ## 4. What the node-engine reports today
 The node-engine's report (its `Report` message) carries: what applied and what failed per resource,
 refusals, the declaration's digest and order, held and stray containers, reachable sockets on an adopted
 machine, packet filters and the firewall found, windows (a scheduled step holding containers still), the
 machine's profile, the engine's own build, outward links, rollbacks its witnesses decided, and whether it
 reads `witness`. Separately, an `Alive` heartbeat with its interval.
 **It carries no container state, no unit state and no health.** The controller's `node` answer for the
 home server shows the consequence: its assigned modules, its strays, its filters and its capabilities —
 and nothing about whether any of its 45 catalogue containers is running.
 The node-engine has one judging mechanism already: the **witness** (to-be 45 §8) — a process's `witness`
 field, `lease` or `ping` or `none`, judges a new build of the controller or the node tools and restores
 the previous one when it is not healthy in bound. Only the two core processes use it.
 A **run-once step** is already a health gate in practice: a step exiting non-zero fails the apply and
 everything placed after it. **23** steps exist (6 containers, 17 processes); one of them, in the hosted
 database suite, is a loop that waits up to five minutes for its analytics service's `/health` before the
 services that need it start.
 ## 5. What the release gate judges a module by
 The gate on a plan's first machine ([ADR 0236](../../02-DECISIONS/0236-a-build-is-judged-on-its-first-machine-and-put-back-by-something-other-than-itself-and-so-it-rolls-out-unattended.md);
 `judgeHealth` in the controller) passes a module there when, on three judgings at least 40 s apart over at
 least two minutes, within ten minutes of the send:
 1. no witness on the machine put a core build back since the send;
 2. the machine's last report is current and **applied** (failed or refused is broken);
 3. **no condition** raised since the send names the module on that machine, or the machine as a whole
   (issue 281 sorted the latter out);
 4. for the controller, the node-engine and the node tools: their own health definitions (lease held and
   ready; the engine's build reported; the node tools answering the bus);
 5. for any other module **that declares tools**: the machine's node tools serve them.
 That is the whole of it for a catalogue module. For the 49 container modules nothing in 1–5 looks at a
 container: point 5 asks the node tools, which host the module's bundle, not its container. **A container
 that applied and then crash-loops passes all five.** To-be 45's Phase 4 note says so: *"container state in
 the node-engine's report, without which a container that crash-loops after its compose applied is seen
 only through what it breaks"*.
 None of the self-check's probes (D1–D13, the data and delivery probes, H-controller, H-engine, H-tools,
 H-bus, DG) reads a module's container or unit state either.
 ## 6. The incidents, and what a declaration would have done
 Every incident of the last ten days where a module applied and did not work, or looked as if it did not:
 | Incident | What the gate and the self-check saw | Caught by, after | Would a declaration have caught it? |
 |---|---|---|---|
 | The agent server crash-looped: its database lacked the vector extension the provider never created (catalogue fix 2026-10-05) | applied; tools served (its bundle runs in the node tools, not the container); no condition | a person reading its log for another reason ([issue 268](../../04-ISSUES/268-letta-printed-its-passwords-into-its-log/00-report.md)), **about a hundred restarts**; the change readying it for the home server merged 2026-09-30, the provider's fix 2026-10-05 | **Yes, by liveness alone** — *running and not restarting* — inside the gate's ten minutes; an HTTP check on its declared `web` endpoint the same |
 | A web app accepted TCP and answered no HTTP request, its database unreachable after a firewall change ([issue 145](../../04-ISSUES/145-a-machine-reads-healthy-while-its-modules-cannot-reach-each-other/00-report.md)) | *"all doing what they were told"* | a person, **after eleven hours** | **Yes, by an HTTP readiness check** within two looks (a minute at 30 s). **Not** by a TCP check — the port was open — and not by liveness |
 | The identity provider's admin refused the secret the mesh minted; every consumer's client failed ([issue 179](../../04-ISSUES/179-an-adopted-identity-providers-admin-never-took-the-minted-secret/00-report.md)) | the server up and serving; its image ships no check | a person, the module having been broken since it moved to the mesh; **twice** (2026-10-01, again 2026-10-05) | **Only by a module's own check** — *the admin logs in* — which the module now runs itself and announces (ADR 0224). No container check sees it |
 | The studio and the flow editor read unhealthy while working (§2) | nothing: the mesh does not read health | a person reading `docker ps` | The opposite case: **a check read without proving it would have rolled back two good builds.** A declaration must be owned by the module and proved before it is trusted |
 | Two media managers refused a new recycle-bin folder; their settings step exited non-zero ([issue 279](../../04-ISSUES/279-a-folder-cannot-be-owned-by-the-account-a-module-runs-as/00-report.md)) | the apply failed → the gate failed, at once | the gate | Already caught: a step is a gate. A health declaration adds nothing here |
 | The media server's event handler threw on an empty answer and was offered each event five times ([issue 276](../../04-ISSUES/276-a-handler-that-did-its-work-was-offered-it-five-times/00-report.md)) | — | the bus watchdog (S9), `max-deliveries` | **No, and it should not**: the server was healthy; handling an event is the event contract's, not health's |
 | A provisioner runtime restarted several times at start until the overlay was up, then worked ([issue 058](../../04-ISSUES/058-a-provisioner-runtime-crash-loops-until-the-overlay-is-up/00-report.md)) | — | the lab | A warning: **a restart-counting check without a start period reads churn that stops as a crash loop** |
 Of the seven: **two** a declaration catches that nothing catches today (the crash loop, by liveness; the
 silent web app, by readiness), **one** only a module's own tool can catch (the admin), **one** shows what
 an unproved check does wrong, and **three** are not health at all or are already caught.
 ## 7. Cost and noise
 - **Reading every container's state on a machine**, health and restart count included: one `ps` of
  38–49 containers took **17–21 ms**; one inspect of all of them **30–37 ms** (control node and home
  server, five and three runs).
 - **What the images' own checks cost today**, from the runtime's record of each check's start and end
  (95 checks over 19 containers): **median 33 ms, slowest 138 ms**. On the home server they run
  **77 checks a minute** — 8 containers, three of them every 2–5 s — for about **5 s of exec time a
  minute**. On the control node, 11 containers at 30 s: 22 checks a minute, under 1 s.
 - **The smallest machines in this mesh** have 12 cores (the control node) and 31 GB (the laptop); the busiest runs 45 catalogue containers.
  One check per long-running resource at 30 s is **90 checks a minute** on the busiest machine — about
  3 s of exec time a minute for in-container checks, a few hundred milliseconds for HTTP or TCP checks
  the engine makes itself. The cost is not CPU; it is that every in-container check is an `exec` in the
  runtime's event history, which on the home server is already one minute long.
 - **Single-sample noise.** [Issue 277](../../04-ISSUES/277-one-unanswered-question-was-an-urgent-alert-nobody-could-read/00-report.md):
  one DNS question unanswered on a machine starting twenty containers was raised urgent; thirty asked by
  hand a moment later were all answered. Its rule — *a finding one look can be wrong about is raised on
  the second look in a row* — is the runtime's own `retries` under another name; the images use 3 to 20.
  The gate's own three passes 40 s apart are a third form of the same idea.
 ## 8. What this says
 1. **Most of the catalogue has no health anywhere.** 38 of 45 running container modules, all 19
   service-only modules and every bundle module have nothing that says *working* beyond *applied*.
 2. **What exists is not read and not owned.** 19 image checks run, 2 were wrong in the mesh's hands,
   and neither the report nor the gate nor the self-check reads any of them.
 3. **The runtime's memory is too short to rely on.** Restart counts vanish with each recreate; the
   event history is a minute long. Liveness must be observed and kept by the node-engine.
 4. **Liveness alone would have caught the worst incident; readiness the longest; only a module's own
   tool the identity provider's.** All three kinds are needed, and none is enough alone.
 5. **The cost is small and the noise is known.** Tens of milliseconds a look; the two-look rule exists.
@@ -1,141 +0,0 @@
 # 02 — Options
 Each question of the [overview](00-overview.md), the options for it, and what the
 [evidence](01-evidence.md) says about each. The recommendation is [03](03-recommendation.md).
 ## A. Who runs the checks
 ### A1 — The container runtime's own HEALTHCHECK, read by the node-engine
 The image's check, or one the module sets, run by the runtime inside the container; the node-engine reads
 the `health` state it keeps.
 - **For:** 19 images already ship one; it runs inside the container's namespace, so a check of
  `localhost` sees what the program sees; the runtime handles interval, timeout, retries and start period.
 - **Against:** containers only — nothing for the 19 service-only modules, the one long-running process,
  or anything a module's own tool knows. Every check is an `exec`, and on the home server the 77 a minute
  already push every lifecycle event out of the runtime's history (01 §2). Two of 19 shipped checks were
  wrong in the mesh's configuration; an image check the module never stated is a check nobody owns. The
  runtime does nothing when a container turns unhealthy (it restarts only on exit), so the state is only
  useful to whoever reads it.
 ### A2 — The node-engine runs every check itself
 HTTP and TCP from the machine, `exec` through the runtime, a unit's state through the service manager, a
 tool through the node tools.
 - **For:** one runner and one reader per machine, for every hosting form; it keeps what the runtime
  forgets (restarts across recreates, 01 §2); a check from outside the container tests the path a caller
  takes, which issue 145 says matters; HTTP and TCP cost no `exec`.
 - **Against:** the engine grows a scheduler; a check that only makes sense inside the container (a CLI,
  a pid file) still needs an `exec`, which A1 does better.
 ### A3 — The module's own tool answers "healthy"
 The bundle exposes a health tool; something calls it.
 - **For:** the only kind that catches a failure of function — the identity provider's refused admin
  (issue 179) — and the module knows what "working" means for it.
 - **Against:** a bundle is hosted by the node tools, not by the service; a tool that answers proves the
  bundle is up, not the server. One tool in the catalogue is a health tool today. And a module that judges
  itself is the thing ADR 0227 rule 8 refuses for the core: *the component being replaced is never the
  judge*. For readiness of function it is the only option; for liveness it must not be the only one.
 ### A4 — A mix, by kind (the shape the evidence points at)
 The engine owns every check and every verdict. It runs HTTP, TCP and unit checks itself; it delegates an
 in-container command to the runtime by setting the container's HEALTHCHECK from the declaration (so the
 runtime's retries and start period do the timing) and reads the state; it asks a module's health tool
 through the node tools. Liveness — running and not restarting — it observes for every long-running
 resource with no declaration at all.
 ## B. Where the result goes
 | Option | For | Against |
 |---|---|---|
 | **B1 — A field of the report**: per module, per long-running resource, a *state* (healthy, unhealthy, starting, unknown), since when, the failing streak and the restarts the engine counted | the report is how a machine states facts about itself; the gate already reads the last report; one place to read | a report is sent after an apply, not on a change — a container that goes bad at 03:00 waits for the next report |
 | **B2 — An event on each transition** (`module.<m>.<machine>.health` changed) | immediate; the controller can keep the state | events are lost or replayed; an event alone is a sample, not a state |
 | **B3 — A condition, raised by the controller** | the gate already fails a module on a new condition naming it on that machine (01 §5, point 3); the operator's conversation (ADR 0234) and the healers (ADR 0231) already act on conditions; the two-look rule and the content rule already apply | a condition is the controller's word, raised from something — it needs B1 or B2 under it |
 | **B4 — A seat verb the controller calls** (`health <module>`) | always current | a pull per module per judging; a machine that is slow to answer reads as unhealthy |
 B1 + B2 + B3 together is how the core already works: the engine states its state in the report and
 emits the change; the controller keeps the last state per machine, raises the condition on the second
 look, and clears it on the look that no longer sees it. That makes **the gate need no new rule**: an
 unhealthy module raises a condition naming it, and point 3 already holds the gate on it.
 ## C. Liveness and readiness
 - **Liveness** — *it runs*: a container running and not restarted within a window; a unit `active` and
  not `failed`, `NRestarts` not climbing; a process up. Observable for every long-running resource with
  no declaration. It alone catches the worst incident of the window (the crash loop). It needs a **start
  period** and a **settle rule**, or it reads issue 058's churn-that-stops as a crash loop.
 - **Readiness** — *it serves*: the declared check passes. Only the module can say what serving means.
 - **Function** — *it does its job*: the identity provider's admin logs in. A module's own tool, and only
  for what no endpoint shows.
 Options: judge liveness only (cheap, no declarations, misses issue 145 and 179); judge readiness only
 (misses nothing that readiness sees, but every module must declare before anything is judged); **judge
 liveness everywhere at once and readiness where declared**, making the declaration required over a
 migration. The last keeps the gate meaningful from the first day.
 What the mesh **does** with each is a separate choice. Restarting a container that is unhealthy is what
 an orchestrator's liveness probe does; the runtime here does not, and a restart hides the failure the
 gate is meant to see. Options: the healers restart what stays unhealthy (ADR 0231's shape: act on what
 observation raised, say whether it worked), or nothing restarts on health and the condition reaches a
 person. The evidence has no case where a restart would have fixed anything — the crash loop was
 restarting already.
 ## D. Dependency-aware health
 A module requiring a provision fails when its provider fails. With 12 consumers of the database
 provision and 36 of a route, a provider down would be a dozen conditions said once each, and a dozen
 gates failed for something none of them did.
 | Option | What it costs |
 |---|---|
 | D1 — Ignore it | twelve conditions for one fault; the operator learns which one matters by reading all of them; the gate blames the consumers |
 | D2 — A consumer's check names the provision it exercises; when that provider is unhealthy on the record, the consumer's finding is **held under the provider's** — said as *waiting on* the provider, not raised on its own — and its gate waits rather than fails | one condition, at the provider; needs the controller to know which provider answers which consumer — it does: it composes the grants ([issue 181](../../04-ISSUES/181-an-assignment-does-not-record-which-provider-answers-it/00-report.md) is about recording it) |
 | D3 — Order the judging: providers first, consumers only when their providers are healthy | simple, but a consumer broken on its own is not said while a provider is down, which is the moment it is most needed |
 D2 is how issue 281 already treats a machine-level condition: what is about the machine is the
 machine's, and is never pinned on the module the gate is kept on.
 ## E. The manifest field
 Research may sketch a shape; a design doc may only name the field. Where the declaration lives:
 - **E1 — On the resource** (`health` on a container, a process, a service): the check belongs to the
  thing it checks; a module with three containers states three. Matches how `restart-on` and `witness`
  already sit on the resource.
 - **E2 — One per module** (a top-level `health`): one verdict, but a module of eleven containers (the
  mail module) cannot say which one is wrong.
 The sketch for E1 — a field named `health`, holding:
 | Part | Meaning | Default |
 |---|---|---|
 | kind | `runtime` (the image's own check, adopted as is), `http` (an endpoint from `listens`, a path, the status expected), `tcp` (an endpoint from `listens`), `exec` (a command in the container), `unit` (the unit's own readiness), `tool` (one of the module's tools answering) | — |
 | every | interval | 30 s; not under 10 s |
 | timeout | how long one look may take | 5 s; under `every` |
 | after | looks failing in a row before it is unhealthy | 3; **not under 2** (issue 277) |
 | grace | after a start, how long failure does not count | 60 s |
 | needs | the provision whose provider it exercises, for D2 | none |
 An HTTP or TCP check names an endpoint by its `listens` name, never a port or an address, so a check
 follows the machine's ports the way the endpoint does. A `runtime` kind is an explicit adoption of the
 image's check, so a module that ships one *says* it does, and `module check` can prove it on a lab.
 ## F. Migration
 - **F1 — Required at once** — every long-running resource declares, or `module check` refuses. 68
  modules to touch before the next merge; nothing is judged until all are done.
 - **F2 — Liveness at once, declaration required by a date** — every long-running resource is judged by
  liveness from the first build; `module check` warns, then refuses after a stated date; a catalogue-wide
  test counts the modules still without one, and the count only goes down.
 - **F3 — Optional for ever** — modules without one are judged by liveness and tools served. The 38 of 45
  container modules with nothing today would stay at liveness.
 What a module without a declaration is judged by in F2 and F3: liveness of every long-running resource
 plus today's five points (01 §5). A bundle-only module (50) and a files-only module (7) need no
 declaration: they run nothing long-lived of their own, and the node tools serving their tools is their
 liveness.
@@ -1,120 +0,0 @@
 # 03 — Recommendation
 From the [evidence](01-evidence.md) and the [options](02-options.md): the node-engine judges every
 long-running thing a module runs — **liveness for all of them, at once, with no declaration**, and
 **readiness where the module declares how** — states it in its report, and the controller raises it as a
 condition on the second look, so the gate, the self-check and the operator's conversation act on it with
 no new rule of their own. Every catalogue module that runs something long-lived declares its check
 within a stated migration, and `module check` then requires it.
 ## Proposed decision text
 Ready for graduation through playbook 02. The number is assigned then.
 > **A module says how it is healthy, and the node-engine judges it**
 >
 > **Context.** The release gate (ADR 0236) judges a catalogue module on its first machine by what the
 > mesh sees from outside: the declaration applied, no new condition about it or its machine, its tools
 > served. None of that looks at what the module runs. Of 125 catalogue modules, 49 run a container that
 > stays up and 19 a service unit; no manifest can declare a health check, the node-engine reports no
 > container or unit state, and no probe reads one. 19 of 73 long-running catalogue containers have an
 > image check the mesh never reads, two of which were wrong in the mesh's configuration. In ten days a
 > container crash-looped about a hundred times and a web app answered nothing for eleven hours, both
 > while every check passed.
 >
 > **Decision.**
 >
 > 1. **Liveness is judged for every long-running resource, with no declaration.** A container that stays
 >    up, a process that stays up and a service stated `running` are *alive* when running and not
 >    restarted more than once within the settle window after their grace period. The node-engine
 >    observes this itself on each tick and keeps the restarts it counted across recreates; it never
 >    relies on the runtime's restart count or event history. A resource held still by an open window (ADR 0189) is
 >    neither alive nor dead: it is said as held, and judged again when the window closes.
 > 2. **A module declares how each long-running resource is ready**, in a field named `health` on that
 >    resource: one kind — the image's own check adopted by name, an HTTP request to a declared endpoint
 >    and the status expected, a TCP connect to a declared endpoint, a command in the container, the
 >    unit's own readiness, or one of the module's tools — with an interval (default 30 s, not under
 >    10 s), a timeout under the interval, a number of failing looks in a row (default 3, **not under 2**),
 >    and a grace period after a start. An endpoint is named by its `listens` name, never by a port or an
 >    address. A check of function that no endpoint shows is a module's own tool, and only in addition to
 >    a check the module does not run itself.
 > 3. **The node-engine runs every check and owns every verdict.** HTTP, TCP and unit checks it makes
 >    itself; a command in the container it hands to the runtime as that container's healthcheck and reads
 >    the state; a tool it asks through the node tools. Nothing else on the machine judges a module.
 > 4. **The state goes in the report, its change on the bus, and a condition is the controller's.** Each
 >    report carries, per module and long-running resource, a state — healthy, unhealthy, starting,
 >    unknown — since when, the failing streak and the counted restarts; each transition is emitted as an
 >    event. The controller keeps the last state per machine and raises `module.<module>.<machine>`
 >    unhealthy as a condition when two consecutive states say so, and clears it on the first that does
 >    not. The release gate, unchanged, holds a module on a condition naming it; at its bound the build is
 >    put back.
 > 5. **A provider down is said once, at the provider.** A check names the provision it exercises. While
 >    that provision's provider is unhealthy on the record, the consumer's finding is held under the
 >    provider's condition — said as waiting on it — and the consumer's gate waits rather than fails.
 >    What a consumer finds while its provider is healthy is its own.
 > 6. **Nothing is restarted for being unhealthy.** The runtime restarts what exits, as now. A condition
 >    reaches a person or a healer (ADR 0231); a healer that restarts on health is its own decision.
 > 7. **A declaration is proved before it is trusted.** `module check` refuses a `health` field that names
 >    an endpoint the module does not declare, an interval or count below the floor, or a tool the module
 >    does not serve. A lab bed applies every changed declaration and requires it healthy within its grace;
 >    an image check adopted by name is proved the same way, because two of nineteen were wrong.
 > 8. **Every catalogue module that runs something long-lived declares one.** `module check` warns from
 >    the decision and refuses a long-running resource without `health` after the migration's date. A
 >    module running nothing long-lived — its bundle only, or files and packages — declares none: the node
 >    tools serving its tools is its liveness, as the gate judges today.
 >
 > **Consequences.** Liveness alone, from the first build, would have caught the crash loop inside the
 > gate's ten minutes. Readiness would have caught the silent web app in a minute instead of eleven hours.
 > The identity provider's refused admin needs the module's own tool, which it now has. The node-engine
 > grows a small scheduler and a report field; the controller a condition kind; the gate nothing. A
 > machine of 45 containers spends tens of milliseconds a look reading state, and about 3 s a minute on
 > in-container commands at the default interval.
 ## How each rule is checked
 | Rule | Checked by |
 |---|---|
 | 1 Liveness without declaration | node-engine unit tests over a fake runtime and service manager: a container recreated keeps its counted restarts; a restart inside grace is not counted; two restarts within the settle window after grace make it unhealthy. A lab bed that replays the crash loop (a container whose program exits at start) fails the gate within its bound |
 | 2 The field and its floors | `module check` refuses each out-of-range part, with a test per refusal; a catalogue-wide test parses every `health` field |
 | 3 The engine owns the verdict | a test that a declared command becomes the container's healthcheck and nothing else sets one; a test that an HTTP check dials the endpoint's current port after a port change |
 | 4 Report, event, condition | controller tests: one unhealthy state raises nothing and is listed unconfirmed; two raise; a healthy state clears; the gate holds a module on that condition (an existing gate test, extended with this condition's kind). A lab replay of issue 145 — a database made unreachable — raises the consumer's condition within two looks |
 | 5 Said once at the provider | a controller test with one unhealthy database provider and three consumers failing: one condition, at the provider, the consumers listed as waiting; the consumers' gates wait, not fail |
 | 6 No restart on health | a node-engine test that an unhealthy container is not restarted, recreated or stopped |
 | 7 Proved before trusted | the lab bed's run of every changed declaration on every catalogue merge; the replay of the studio's false *unhealthy* (a check that asks `localhost` while the program binds elsewhere) fails the bed, not a machine |
 | 8 Every long-running module declares | a catalogue-wide test that counts the modules with a long-running resource and no `health`: it may only go down, and is zero by the date; after it, `module check` refuses |
 ## The migration
 **Today:** 68 modules run something long-lived (49 with a container, 19 with a running service only);
 57 run nothing long-lived and need no declaration.
 1. **Build first, without declarations.** The node-engine's liveness, the report field, the events, the
   controller's condition and its two-look rule, and the dependency hold. From this step every
   long-running resource is judged by liveness. The catalogue-wide counter starts at 68.
 2. **The seven modules whose images ship checks** adopt them by name — and, for the two that were
   wrong, the fixed configuration is what the lab proves. 19 of their containers are covered at once.
 3. **The other 42 container modules, and the containers without an image check in three of the seven,** declare an HTTP check on their declared endpoint where they serve
   HTTP, TCP where they serve something else, a command where neither shows readiness. 48 of 49
   already declare the endpoint the check needs.
 4. **The 19 service-only modules** declare the unit's own readiness, or a TCP check where the unit
   listens; most are machine software (a resolver, a time daemon, a session manager), where `active` and
   not `failed` is already the honest answer.
 5. **Modules whose function no endpoint shows** add a tool check: the identity provider (its admin logs
   in), the database provider (it can create in a consumer's database), the broker. Identified as they
   are met, not in advance.
 6. **The date:** when the counter reaches zero, or six weeks after step 1, whichever is first. From then
   `module check` refuses a long-running resource without `health`.
 **What a module without a declaration is judged by, until then and for ever if it runs nothing
 long-lived:** liveness of everything it runs that stays up, and the gate's five points as they stand —
 applied, no witness put it back, no new condition naming it or its machine, the core's own definitions,
 its tools served.
 ## What this does not decide
 - Whether a healer restarts what stays unhealthy (rule 6 leaves it to its own record, under ADR 0231).
 - Health for scheduled work — whether the last scheduled run succeeded is data the windows of ADR 0189
  already carry, and belongs to that record.
 - Health of what a module's events do (issue 276) — the event contract's, and the bus watchdog's.
 - The core's own definitions (to-be 45 §8), which stand; a core component may later declare its own
  through the same field.
@@ -1,79 +0,0 @@
 ---
 status: graduated
 initiated: 2026-10-07
 became:
  - 02-DECISIONS/0247-a-machine-with-a-vpn-client-routes-names-by-domain-through-a-resolver-of-its-own.md
  - 03-DESIGN/01-to-be/50-split-dns-on-a-machine-with-a-vpn-client.md
 touches:
  - 02-DECISIONS/0223-the-mesh-has-two-resolvers-and-a-machine-lists-only-them.md
  - 02-DECISIONS/0117-a-machines-uplink-is-a-seat.md
  - 03-DESIGN/01-to-be/08-connectivity.md
  - the node-uplink seat and its holders
  - the node-engine's reconcile of a file another program rewrites
 ---
 # 033 — Split DNS with a VPN client
 ## What is investigated
 How a machine of the mesh resolves three kinds of name at once — the mesh's (`*.internal`), a
 corporate network's reached through a VPN client, and public ones — when the VPN client writes
 `/etc/resolv.conf` itself.
 [ADR 0223](../../02-DECISIONS/0223-the-mesh-has-two-resolvers-and-a-machine-lists-only-them.md) gives
 every machine one resolver file listing the mesh's two resolvers and nothing else, written by the holder
 of the machine's uplink ([ADR 0117](../../02-DECISIONS/0117-a-machines-uplink-is-a-seat.md)). On the
 laptop, a corporate VPN client replaces that file when it connects, with its own servers and eight search
 domains. The node-engine finds the file changed and writes the mesh's back on its next reconcile. From
 then on, for the rest of the session, the corporate names do not resolve; in the minutes before it, the
 mesh's names did not. Neither program knows the other exists.
 The questions:
 1. **How the VPN client sets DNS** on Linux: does it overwrite the file, use `resolvconf`, or talk to
   systemd-resolved or NetworkManager; what it backs up and restores; whether it re-asserts its file.
 2. **What it pushes**: how many servers, which domains, over which link, and what routes.
 3. **How often the two collide** on the live mesh, and what each collision costs.
 4. **The options**: per-link routing in systemd-resolved, adding the VPN's servers to the mesh's file,
   forwarding the corporate domains from the mesh's resolvers, standing back while the VPN is up, and
   any other — and what each means for ADR 0223 and for the machines that run no VPN.
 ## Why
 The operator uses the VPN for work, every working day. While it is up the laptop is either cut off from
 the mesh (agents saw lookups fail) or cut off from the corporate network, depending on which program
 wrote the file last. A rule of the mesh that a machine's own work program silently breaks — or that
 breaks the machine's owner's work — is a rule that cannot be kept as stated.
 A sibling decision proposed alongside this effort, ADR 0241 (machine network health), makes the
 node-engine detect and report an outside writer of the resolver file. That says the fault; this effort
 asks how it stops being one.
 ## What it touches
 ADR 0223's rule that a machine lists only the mesh's resolvers, and its rejection of a local forwarder;
 ADR 0117's list of what an uplink holder declares; the networkmanager module (the uplink holder on the
 laptop); the node-engine's correction of a file changed on the machine; connectivity §2.
 ## Where it stands
 Evidence gathered read-only on the laptop and options weighed, 2026-10-07:
 - [01 — The evidence](01-evidence.md): the VPN client always *moves* the resolver file aside and writes
  its own (two servers, eight search domains), restores its backup on disconnect, and never re-asserts;
  it does not configure systemd-resolved or NetworkManager per link on this machine. In every one of the
  nine sessions since the node-engine's journal begins, the node-engine wrote the mesh's file back within
  1 s to 3.5 min; once the VPN client's restore of a stale backup was itself corrected.
 - [02 — Options](02-options.md): six, from systemd-resolved per-link routing to replacing the VPN
  client.
 - [03 — Recommendation](03-recommendation.md): on a machine that declares a VPN client, the uplink's
  holder runs systemd-resolved as a local router on the machine's private address, and hands it the
  VPN's servers and domains the moment the VPN client writes them; every other machine is unchanged.
  A proposed decision text with how each rule is checked.
 **Graduated 2026-10-07** into [ADR 0247](../../02-DECISIONS/0247-a-machine-with-a-vpn-client-routes-names-by-domain-through-a-resolver-of-its-own.md)
 and [to-be 50](../../03-DESIGN/01-to-be/50-split-dns-on-a-machine-with-a-vpn-client.md). The mechanism is
 the recommendation's: systemd-resolved routing the VPN's domains over its link. Who runs it differs, by
 the operator's decision. The resolver is a module of its own on a node seat, `node-resolver`, rather than
 part of the uplink's holder, which has two forms. The VPN client's module carries the adapter, so no
 setting declares a VPN client. The interim *defer* setting is not adopted. The record says why.
@@ -1,100 +0,0 @@
 # 01 — The evidence
 Gathered read-only on the laptop, 2026-10-07, with the VPN disconnected: the VPN client's installed
 files, its own log (kept since its install, about five weeks), the strings of its binaries, the
 node-engine's journal (kept for eleven days), and the machine's network state. Nothing was changed and
 nothing restarted. The corporate network's domains and addresses are not reproduced here.
 ## The machine
 - **Uplink:** NetworkManager, held by the mesh's `networkmanager` module, which tells it `dns=none` and
  leaves the private network's interface (`mesh0`) unmanaged. The resolver file is the module's own,
  declared from one template: the two mesh resolvers, `options timeout:1 attempts:2 edns0`.
 - **systemd-resolved** is installed, as part of systemd, but disabled and not running. The name service
  order is `files dns … resolve [!UNAVAIL=return]`, so with resolved stopped the resolver file is the
  only DNS path.
 - **The mesh's names are not in `/etc/hosts`** any more (ADR 0148 moved every name to the resolvers):
  with the resolver file replaced, no mesh name resolves on the machine itself, nor in any container.
 - **Five containers**: two on the node-engine network (they read the machine's file as it is, at each lookup),
  three on bridges (they read it, or the runtime's embedded resolver copies its servers, when they start).
 ## The VPN client
 **FortiClient 7.4, the vendor's own Linux client** (not openfortivpn), its scheduler running as a system
 service; the tunnel is set up on demand by its `vpn` process.
 **What it does at connect**, from its log, identical in all eleven sessions recorded:
 1. `Inherit local DNS: No` and `DNS service resetting interval: 0` — settings pushed with the profile.
   The first means the machine's own resolvers are *not* kept beside the corporate ones; the second that
   it never re-asserts its file during a session.
 2. It configures the tunnel device with `ip` ("fall back to using ip command") — so NetworkManager sees
   the tunnel as an external device it does not manage.
 3. **`Moving /etc/resolv.conf to /etc/resolv.conf.forticlient.backup`** — a rename, so the mesh's file,
   inode and all, becomes the backup.
 4. It writes a new `/etc/resolv.conf`: **two nameservers** (in a private RFC 1918 range, reached through
   the tunnel) and **eight search domains** (the corporate network's internal and cloud zones). Its
   binary carries the header it writes: `# Dynamic resolv.conf(5) file for glibc resolver(3) generated
   by forticlient`, and a line saying the original is backed up and restored after the VPN disconnects.
 5. **Split tunnel**: 119 routes through the tunnel — 110 host routes, mostly to a CDN's addresses, and
   nine networks including the whole of `10.0.0.0/8` and `172.16.0.0/12`. The mesh's private /24 sits
   inside the first, and survives only because a more specific route on `mesh0` wins.
 **At disconnect:** `Moving /etc/resolv.conf.forticlient.backup to /etc/resolv.conf` — the backup taken
 at connect is put back as it was then, whatever has happened to the file since. With no backup present
 it logs "No DNS backup file was found. Skip."
 **What it does not do on this machine.** Its binary knows systemd-resolved (if running, it *reads* the
 resolvers from resolved's own file and flushes resolved's cache) and NetworkManager (it can allocate the
 tunnel through `nmcli`, set a connection's DNS search domains, and drop a configuration file into
 NetworkManager's `conf.d`, keeping its own backups beside the resolver file). Here it took neither path.
 In no path found in the binary does it give systemd-resolved a per-link server or routing domain; it
 always writes `/etc/resolv.conf` itself. Public reports agree: with systemd-resolved running, the client
 replaces the stub symlink with its static file.
 ## The collision
 The node-engine corrects a declared file that was "changed on the machine since this host last wrote it"
 on its next apply or reconcile. Matching its journal to the VPN client's log:
 | Session | VPN wrote its file | Node-engine wrote the mesh's back | Gap |
 |---|---|---|---|
 | 1 | 21:20:18 | 21:21:38 | 1 min 20 s |
 | 2 | 11:51:33 | 11:54:48 | 3 min 15 s |
 | 3 | 12:59:48 | 13:00:59 | 1 min 11 s |
 | 4 | 12:26:30 | 12:29:55 | 3 min 25 s |
 | 5 | 12:31:36 | 12:34:54 | 3 min 18 s |
 | 6 | 12:42:58 | 12:44:54 | 1 min 56 s |
 | 7 | 13:53:22 | 13:54:06 | 44 s |
 | 8 | 14:58:37 | 15:00:35 | 1 min 58 s |
 | 9 | 15:46:13 | 15:46:14 | 1 s |
 - **Nine of nine sessions** since the journal begins were overwritten by the mesh, within 1 s to 3.5 min
  (median about 1 min 56 s). Two earlier sessions predate the journal.
 - **Each session then ran on the mesh's file** — sessions lasted from five minutes to fourteen hours —
  so for all but the first minutes **no corporate name resolved**, while the tunnel and its routes stood.
  The VPN client never noticed: its resetting interval is 0.
 - **Sessions 4–6 were three connects within sixteen minutes**, two ended by hand after five and seven
  minutes — the shape of a person reconnecting because something stopped working.
 - **The VPN client's restore is itself an outside write.** On one night the uplink's holder changed (the
  resolver file moved from one module's template to another's) while a session was up; when the session
  ended at 02:43 the client put back its backup — the old module's file — and the node-engine corrected
  it two minutes later. A restore puts back *a* mesh file, not necessarily the current one.
 - **In the minutes before each correction**, the machine had only the corporate servers: no mesh name
  resolved (the agents' lookups failed), and public names depended on the corporate servers. The
  operator reported agents seeing `ENOTFOUND` for the AI API's public name in such a window; it is not in
  any journal kept on the machine, so how often public names failed is not measured.
 ## What the other machines have
 No VPN client runs on the anchor, the home server or the workstation. The two mesh resolvers have no
 route to the corporate network's servers: they sit behind the laptop's tunnel, in ranges the laptop
 routes only to itself.
 ## Two related faults, noted
 - **One mesh resolver briefly slow under load** ([issue 277](../../04-ISSUES/277-one-unanswered-question-was-an-urgent-alert-nobody-could-read/00-report.md)):
  any design that adds a hop must keep the two-resolver answer and its short timeouts.
 - **The self-check asks the resolvers only from the control node** (to-be 45 §4, D2). A machine whose
  own resolver file is wrong is invisible to it — the gap ADR 0241 (proposed) closes from the machine's
  side.
@@ -1,113 +0,0 @@
 # 02 — Options
 What any answer must give, from the [evidence](01-evidence.md) and ADR 0223:
 - **R1** mesh names resolve on the machine and in its containers while the VPN is up;
 - **R2** the corporate domains resolve through the VPN's servers while it is up;
 - **R3** public names resolve, VPN up or down;
 - **R4** no listed set of servers can give two different answers to one name — musl asks every listed
  server at once and takes the first reply, glibc takes the first server's "no such name" as final
  ([issue 262](../../04-ISSUES/262-an-alpine-container-could-not-find-a-machine-by-its-mesh-name/00-report.md),
  ADR 0223);
 - **R5** the VPN client keeps working unmodified — it is the employer's software, configured by the
  employer's gateway; the mesh cannot change what it pushes or how it writes;
 - **R6** no change on a machine that runs no VPN.
 A constraint every option meets: **the VPN client always writes `/etc/resolv.conf` itself**, even with
 systemd-resolved running. No option makes it stop; each decides what happens next.
 ## 1. systemd-resolved with per-link DNS and routing domains
 resolved runs on the machine. The `mesh0` link gets the two mesh resolvers with the routing domain
 `~internal` and the default route (`~.`); the tunnel link gets the VPN's two servers and its eight
 domains as routing domains. resolved sends each question to the link whose domain matches longest, the
 rest to the default route.
 - **R1–R3 met**, by routing rather than by listing: one answer per name.
 - **Containers cannot reach resolved's stub on `127.0.0.53`.** A container on the node-engine network can; one
  on a bridge cannot — it reads the machine's file and gets an address that is its own loopback. resolved
  can listen on further addresses (`DNSStubListenerExtra=`): on the machine's private mesh address, which
  ADR 0223 already relies on being reachable from containers on a holder. The machine's file then lists
  that one address. **R4 met**: one server listed.
 - **Who gives the tunnel link its servers?** Not the VPN client (it never sets per-link DNS) and not
  NetworkManager (the tunnel is not its device). Something must read what the VPN pushed — and the VPN
  client writes exactly that, in its file, within a second of connecting. A path watch on the resolver
  file, declared by the uplink's holder, can read the file's `nameserver` and `search` lines, give them to
  the tunnel link with `resolvectl dns` and `resolvectl domain`, and write the mesh's file back at once —
  not at the next reconcile. When the tunnel goes, resolved forgets its link's configuration by itself.
 - **The VPN client's restore at disconnect** puts back the mesh's file (or an older one: the node-engine
  corrects the content, as today). Nothing points at a link that is gone.
 - **Cost:** a daemon on the machine (already installed; part of systemd), its configuration, the watch.
 - **For ADR 0223:** it is the local forwarder 0223 rejected (its option 2), on fewer machines and with
  its three objections met: not on every machine — only on one that declares a VPN client; reachable
  from containers — on the private address; and it holds no copy of the mesh's names — every `.internal`
  question still goes to the two resolvers, so nothing can disagree with the truth.
 - **R6 met** if it is scoped to machines that declare a VPN client.
 ## 2. The uplink's holder adds the VPN's servers to the mesh's file
 When the tunnel appears, the holder writes the mesh's two resolvers *and* the VPN's two servers, and the
 VPN's search domains.
 - **R4 broken, by construction.** The VPN's servers answer "no such name" for `.internal`; the mesh's
  resolvers forward a corporate name to the public internet, which answers "no such name" or a public
  record. glibc stops at the first listed server's answer, musl takes whichever is fastest. Whatever order
  is chosen, one kind of name fails — the exact fault ADR 0223 removed the public resolver for.
 - Rejected. It only works with something that routes by domain in front — which is option 1 or 5.
 ## 3. The mesh's resolvers forward the corporate domains while the VPN is up
 - **They cannot reach the VPN's servers**: those sit behind the laptop's tunnel, routed only on the
  laptop. Forwarding through the laptop would make the mesh's resolvers depend on one laptop's session.
 - It would also put an employer's zones into the mesh's shared configuration, answered for every machine.
 - Rejected.
 ## 4. Stand back: detect the VPN and defer
 While the resolver file carries the VPN client's marker and its backup holds the mesh's file, the
 node-engine does not correct it, and the machine's health says *deferred to a VPN client* rather than
 *rewritten by another program*. On disconnect the client restores the mesh's file.
 - **R2, R3 met; R1 broken for the whole session**: no mesh name resolves on the laptop, nor in its
  containers. The node-engine reaches the bus by name; agents and tools on the laptop lose the mesh.
 - **Cheap**: no daemon, one rule in the node-engine (and the content check on restore stays).
 - Today's behaviour is the opposite trade — R1 met after a few minutes, R2 broken for the rest of the
  session — and the evidence shows the operator living with it by reconnecting.
 - Acceptable only as a stated, chosen degradation for a machine where the owner's work comes first;
  better than the fight, worse than routing. **Useful as the fallback** of option 1 while it is not
  built, if the operator prefers work names to mesh names.
 ## 5. A local forwarder of the mesh's own (dnsmasq) on the VPN machine
 As option 1, with the catalogue's resolver program in place of resolved: `server=/<corporate domain>/…`
 lines for the VPN's domains, everything else to the two mesh resolvers, listening on the private address.
 - Meets R1–R4 like option 1.
 - **Costs more than option 1**: a package to declare, and a configuration file to rewrite and a
  process to reload on every connect and disconnect, where resolved takes per-link settings live over its
  own interface and drops them with the link. dnsmasq is already the mesh's resolver module, which makes
  "a second copy of the resolver on this machine" easy to misread as a third mesh resolver.
 - Kept as the fallback for a machine without systemd.
 ## 6. Replace the VPN client
 openfortivpn, through NetworkManager's plugin, hands the VPN's DNS to NetworkManager instead of writing
 the file; NetworkManager with `dns=systemd-resolved` then gives resolved per-link servers and domains —
 option 1 with no watch at all.
 - **Not the mesh's to decide** (R5): the employer's gateway may require its own client (posture checks,
  single sign-on through the vendor's flow). It would also hand the file back to NetworkManager, against
  ADR 0117's `dns=none`.
 - Recorded so the option is not rediscovered; not proposed.
 ## Summary
 | | R1 mesh | R2 corporate | R3 public | R4 one answer | R6 others untouched | New on the machine |
 |---|---|---|---|---|---|---|
 | 1 resolved, per link | yes | yes | yes | yes | yes, if scoped | resolved, a path watch |
 | 2 add the VPN's servers | some | some | yes | **no** | yes | nothing |
 | 3 forward from the mesh | yes | **no** | yes | yes | **no** | nothing |
 | 4 defer | **no** | yes | yes | yes | yes | one rule |
 | 5 dnsmasq locally | yes | yes | yes | yes | yes, if scoped | a package, a reload per connect |
 | 6 replace the client | yes | yes | yes | yes | yes | not the mesh's call |
 | today (the fight) | after minutes | **no**, after minutes | mostly | yes | yes | — |
@@ -1,89 +0,0 @@
 # 03 — Recommendation
 From the [evidence](01-evidence.md) and the [options](02-options.md): **route by domain on the one
 machine that runs a VPN client, and leave every other machine as ADR 0223 has it.** On a machine whose
 operator declares a VPN client, the uplink's holder runs systemd-resolved as the machine's resolver,
 listening on the machine's private address; the mesh's link carries the two mesh resolvers for the
 mesh's domain and as the default route; the moment the VPN client writes its own resolver file, the
 holder hands that file's servers and domains to the tunnel link and writes the mesh's file back. The
 fight ends because the two programs no longer want different things: the VPN's servers are used, for the
 VPN's domains only.
 Why not the cheaper ones: adding the VPN's servers to the file breaks the one-answer rule that ADR 0223
 exists for (option 2); the mesh's resolvers cannot reach the VPN's servers (option 3); standing back cuts
 the laptop off from the mesh for whole working days (option 4). Option 4 is kept as what the machine does
 *until* this is built, if the operator prefers it to today's fight — a choice for the operator, stated in
 the proposed text as an interim setting, not as the decision.
 What it asks of the sibling proposal, ADR 0241 (machine network health): on a machine that declares a VPN
 client, the VPN client's file is not an outside writer's fault but an expected handover — it is reported
 as *adopted* once the holder has taken its servers, and as a fault only if it stands longer than the
 watch's bound (a few seconds), which means the watch did not fire.
 ## Proposed decision text
 Ready for graduation through playbook 02. The number is assigned then.
 > **A machine with a VPN client routes names by domain, and the VPN's file is taken, not fought**
 >
 > **Context.** ADR 0223 gives every machine one resolver file listing the mesh's two resolvers and
 > nothing else, written by the uplink's holder (ADR 0117). A corporate VPN client on the laptop moves that
 > file aside when it connects and writes its own — two servers reached through its tunnel, eight search
 > domains — and puts its backup back on disconnect; it never re-asserts its file and never gives
 > systemd-resolved per-link settings, even when resolved runs. The node-engine wrote the mesh's file back
 > in nine of nine sessions, within 1 s to 3.5 min; from then on no corporate name resolved for the rest of
 > sessions lasting up to fourteen hours, and before it no mesh name did. No resolver file can list both
 > sets of servers: musl takes the first reply and glibc the first server's "no such name", so one kind of
 > name would fail (issue 262).
 >
 > **Decision.**
 >
 > 1. **A machine declares that it runs a VPN client**, as a setting of its uplink's holder, naming the
 >    client. Nothing changes on a machine that does not.
 > 2. **On such a machine the uplink's holder runs systemd-resolved** as the machine's only resolver, with
 >    its stub also listening on the machine's private address, so the machine's containers reach it. The
 >    private network's link carries the mesh's resolvers, in ADR 0223's order, as the routing domain of the
 >    mesh's names and as the default route. `/etc/resolv.conf` lists the machine's private address alone,
 >    with ADR 0223's options. resolved holds no copy of any mesh name: every mesh name is asked of the two
 >    resolvers, as on every other machine.
 > 3. **The VPN client's file is taken, not fought.** The holder watches the resolver file; when the
 >    declared client writes it, the holder gives the tunnel link the file's servers and its search domains
 >    as routing domains, and writes the mesh's file back, within seconds — not at the next reconcile. When
 >    the tunnel goes, resolved drops its link's settings; the client's restore of its backup is corrected
 >    by content, as any change to the file is.
 > 4. **The VPN's domains are never the mesh's.** They are not written to the mesh's store, its resolvers
 >    or any other machine; they live in resolved's state for the life of the tunnel.
 > 5. **The machine says it.** The machine's network health (ADR 0241, proposed) states the VPN's file as
 >    *adopted*, with the tunnel link and the count of domains routed, and raises it as an outside writer
 >    only if it stands longer than the watch's bound or the client is not the declared one.
 > 6. **Until rules 2–3 run on a machine, its operator may choose to defer**: the node-engine leaves the
 >    declared client's file in place while the client's backup holds the mesh's file, and the machine's
 >    health says *deferred to the VPN client — mesh names do not resolve* for as long as it lasts.
 >
 > **Consequences.** ADR 0223's rejection of a local forwarder stands for every machine but one that
 > declares a VPN client; there its three objections are answered — one machine, not every machine;
 > reachable from containers on the private address; no copy of the mesh's names. A machine that
 > declares a VPN client and whose resolved is down has no names; its network health says so. The
 > routes the VPN client adds are untouched: its routes include `10.0.0.0/8`, and the
 > mesh's private network keeps working only because its own route is more specific — a fact to keep in
 > mind when choosing a private range, and a check of its own.
 >
 > **How it is checked.**
 >
 > | Rule | Checked by |
 > |---|---|
 > | 1 Declared, nothing changes elsewhere | a controller composition test: a machine without the setting composes exactly as before; with it, the holder declares resolved and the watch |
 > | 2 resolved, on the private address, mesh link and default route | a composition test reading the holder's files; live on the laptop: `resolvectl status` shows the mesh link with `~internal` and `~.`, the stub on the private address, and the machine's file lists that address alone |
 > | 3 Taken within seconds | a lab drill: a container plays the VPN client (writes a file with its own header, servers and search lines, adds a tunnel link); the tunnel link carries the servers and domains and the mesh's file is back within 5 s; removing the link drops them |
 > | 3 Containers | the lab drill: an Alpine container on a bridge resolves a mesh name ten times out of ten while the fake tunnel is up |
 > | 4 Never the mesh's | a test that the store, the controller's renders and the other machines' files carry none of the VPN's domains after the drill |
 > | 5 Said | the machine network health test: the VPN's file read as *adopted*, not raised; raised when it stands past the bound |
 > | 6 Defer, while not built | a node-engine test: with the setting and the client's backup present, the file is not corrected and the health says deferred; without the backup it is corrected |
 > | the routes | the machine network health's check that a mesh address still routes over the private link (ADR 0241, proposed) |
 ## What this does not decide
 - Which VPN client the operator uses (option 6): the employer's.
 - Resolution for a machine with *two* VPN clients — none exists.
 - Whether the operator's corporate names should resolve inside the mesh's containers on the laptop: they
  will, through the same router; restricting them is a later question if it matters.
@@ -1,111 +0,0 @@
 ---
 status: graduated
 initiated: 2026-10-07
 touches:
  - 00-META/glossary.md
  - 00-META/checks/
  - 02-DECISIONS/0006-the-substrate-and-the-control-plane.md
  - 02-DECISIONS/0008-a-context-owns-its-store.md
  - 03-DESIGN/01-to-be/06-the-controller.md
  - the descriptions of every module's tools and every seat's verbs in the catalogue
 became:
  - 02-DECISIONS/0244-the-mesh-is-described-in-domains-and-one-word-names-one-thing.md
  - 03-DESIGN/01-to-be/49-the-mesh-in-domains.md
 ---
 # 034 — The mesh in domains
 ## What is investigated
 The operator, 2026-10-07: *"I wanted to develop our nox-mesh domain driven. Meaning every concept
 should fit into some domain and we try to come up with a common knowledge base/glossary/jargon for our
 application. We kind-of do this already I think, yet sometimes, you return different words for existing
 concepts."*
 Two terms from domain-driven design are used throughout this effort, so they are explained once here.
 A **domain** (in the literature, a *bounded context*) is an area of the system inside which every word
 has exactly one meaning, and which owns the concepts that meaning describes. A **ubiquitous language** is
 the set of words a domain uses the same way in conversation, in documents and in code. The glossary
 ([`00-META/glossary.md`](../../00-META/glossary.md)) is this repository's attempt at a ubiquitous
 language for the whole mesh, without domains.
 The effort asks five questions:
 1. **Which concepts are in use**, in the glossary, the decision records, the designs and the issue
   reports, and in the words the running mesh's tools use to describe themselves?
 2. **Into which domains do they fall?** Each domain gets a purpose, the concepts it owns, the one word
   for each, and its relation to the others. The operator's starting guess — building and delivering
   changes; running modules on machines; health and alerts; data and backups; people, conversation and
   approvals; the network — is tested, not assumed.
 3. **Where do the words clash?** Two or more words for one concept (a *synonym*), or one word for two
   concepts (a *homonym*), each with evidence and a proposed single word.
 4. **How is the glossary rule checked?** [`AGENTS.md`](../../AGENTS.md) says *a rule states how it is
   checked*, and "one name per thing" is checked by nothing today.
 5. **How should the glossary be organised by domain?** Described only; the glossary itself changes when
   this effort graduates, not before.
 ## Why
 Because the drift is measurable, and it costs. The glossary retired *control plane* on 2026-09-16; three
 weeks later 29 occurrences stand in 12 to-be designs — the documents that tell somebody what to do — and
 73 files created after the retirement use it. It retired *host agent*, *the host* and `mesh-host` for the
 **node-engine** on 2026-10-05; the descriptions of four tools the running mesh serves still say *"the host
 will restore"*, and the glossary's own entry for node tools says *"a host-side process the host
 supervises"*. The glossary defines **node**, while the decisions and designs of the last week use
 *machine* twice as often as *node*, and the console's own tools are called `mesh_machine` and list
 "machines". A reader — person or agent — who meets two words assumes two things, and an agent answering
 from these documents repeats whichever word it read last. That is the operator's complaint, observed.
 ## What it touches
 The glossary and how it is kept; the checks in [`00-META/checks/`](../../00-META/checks/); the seven
 contexts of the controller that [ADR 0006](../../02-DECISIONS/0006-the-substrate-and-the-control-plane.md)
 named and [ADR 0008](../../02-DECISIONS/0008-a-context-owns-its-store.md) gave each its own store, which
 are the nearest thing the mesh already has to domains; and the descriptions of the tools and seat verbs
 that the modules in the catalogue serve, which are where an agent meets the mesh's words most often.
 ## The documents
 | | |
 |---|---|
 | [01 — The concepts in use](01-the-concepts-in-use.md) | the inventory: what was read, how it was counted, what the glossary holds and what it lacks, and the words the running tools use |
 | [02 — The domains](02-the-domains.md) | the proposed split into ten domains plus the repository's own, each with purpose, concepts, words and relations; the operator's guess tested |
 | [03 — The clashes](03-the-clashes.md) | twenty clashes with evidence and a proposed word for each, the five most costly first |
 | [04 — How the glossary is checked](04-how-the-glossary-is-checked.md) | a proposed check over hq documents and over the catalogue's tool descriptions; described, not built |
 | [05 — A glossary by domain](05-a-glossary-by-domain.md) | how the glossary would be organised; described, not written |
 ## Findings so far
 - **The mesh already has domains under another name.** ADR 0006 named seven *contexts* of the controller —
  inventory, config, connectivity, provisioning, delivery, observability, identity. Only three of them have
  a store today (`inventory`, `identity`, and `licences`, which is not one of the seven), and the words the
  mesh has grown since (seat, delivery, condition, ask, data class) are not organised by them. The
  proposed split in [02](02-the-domains.md) keeps five of the seven, renames one, and adds four.
 - **The operator's guess survives mostly intact.** Five of its six domains hold up. It lacks a domain for
  *identity and access* (credentials, grants, licences), one for *provisioning* (provider and consumer),
  the *core* the rest runs on (controller, bus, store, lease, genesis), and the *module* itself, whose
  manifest is the language every other domain reads. *Health and alerts* is better called *health and
  repair*: the mesh says *condition*, not *alert*.
 - **The glossary is short of the vocabulary in use, and contradicts itself twice.** It has 33 entries. At
  least 40 words used in more than ten decision records each — *module*, *manifest*, *assignment*,
  *machine*, *provider*, *condition*, *gate*, *tier*, *operator* among them — have no entry. It defines the
  console as a module and, further down, says node tools replaced that name; it says the deprecated broker
  holds no seat and, in the entry for *claim*, that it claims `mesh-broker`.
 - **Most drift is in two places**: governing designs written before a word was retired and never
  revisited, and tool descriptions, which nothing compares with the glossary at all.
 - **Homonyms cost more than synonyms**, and a word list cannot catch them. *Plan*, *push*, *release*,
  *gate*, *tier*, *ask*, *store* and *record* each mean two to four things today, several of them in the
  verbs of the same seat.
 ## Questions for graduation
 - **Machine or node.** One concept, two words, both heavily used; [03](03-the-clashes.md) recommends
  *machine* in prose and keeps `node` only as an identifier (a scope's value and the `node-` prefix of seat
  names). This is the largest rename the effort proposes, and the operator's call.
 - **Domain or context.** The repository already says *context* (ADR 0006, ADR 0008) for an owner of
  records with its own store. Using *domain* for the vocabulary partition beside it would be the effort's
  own synonym. [02](02-the-domains.md) proposes that a domain is the vocabulary and ownership boundary and
  a context is one store inside it, and asks for that to be decided rather than left to usage.
 - **Which documents the check holds to the list**, and from which date ([04](04-how-the-glossary-is-checked.md)).
 - **Where the tool-description check runs**: in the catalogue repository's merge check, or as a probe of the
  running mesh, or both.
@@ -1,148 +0,0 @@
 # 01 — The concepts in use
 What was read, how words were counted, what the glossary holds, what it lacks, and which words the
 running mesh's tools use. The domains in [02](02-the-domains.md) and the clashes in
 [03](03-the-clashes.md) are drawn from this.
 ## What was read
 | Source | Size on 2026-10-07 | How |
 |---|---|---|
 | the glossary | 33 entries | read whole |
 | decision records (`02-DECISIONS/`) | 225 records | counted; the seven-contexts record (0006), its store rule (0008) and the records from 0220 to 0240 read for their words |
 | to-be designs (`03-DESIGN/01-to-be/`) | 49 documents | counted; the controller (06), connectivity (08), and 45 to 48 read for their words |
 | as-is designs (`03-DESIGN/00-as-is/`) | 17 documents | counted |
 | issue reports (`04-ISSUES/`) | 291 issues | counted |
 | research (`01-RESEARCH/`) | 33 efforts | counted; research 005 (*which domains the catalogue groups into*) read whole, as prior art |
 | the running mesh's tools | 88 modules serving 535 tools, plus the verbs of 15 seats every machine holds and 5 seats held once for the mesh | listed through the console's read tools (overview, machine, search, describe); nothing was called that changes anything |
 **How words were counted.** A case-insensitive, whole-word match per file; the number given is the number
 of *files* containing the word, not of occurrences, unless a statement says otherwise. Where a file's age
 matters, its age is the date git first records it. The tool descriptions are the first line each tool
 gives of itself in the console's listing, which is cut at about 160 characters, so a word that occurs only
 late in a long description is undercounted there.
 ## What the glossary holds
 Thirty-three entries, in seven sections: the mesh and its machines; what runs the mesh; what the mesh
 stores and serves; how modules relate to the mesh; the surfaces; how a change reaches the machines; the
 operator's machine. Retired words are marked three ways — struck through (`~~flavor~~`), *"Replaces
 **x**"*, and *"Not x"* — so no program can read the list of retired words from it reliably today.
 **It contradicts itself in two places.**
 - **The console.** The surfaces section defines the console as *"the module (`mesh-console`) that puts the
  mesh's tools in front of whoever is on a machine"*. The operator's machine section, further down, defines
  node tools as the runtime whose *"serving mode on loopback is what was called **the console**"*, and
  says node tools *"replaces 'console' as the module's name; console remains the word for the person's end
  of it."* Both entries are current.
 - **The deprecated broker.** Its entry says it has *"no seat, not foundation"*. The entry for *claim*
  says *"the `mesh-controller`, `postgres` and `lavinmq` modules claim the `mesh-controller`, `mesh-store`
  and `mesh-broker` seats"*, and the entry for *bus* says the bus is held by the `mesh-broker` seat.
 **It uses a word it retired.** The node tools entry says *"a host-side process the host supervises"*,
 eight lines after the node-engine entry retired *the host*.
 ## What the glossary lacks
 Words used in more than ten decision records each, with no entry of their own (files containing each, of
 225 records):
 | Word | Records | Word | Records | Word | Records |
 |---|---|---|---|---|---|
 | machine | 177 | operator | 125 | catalogue | 120 |
 | declaration | 106 | manifest | 102 | reach | 101 |
 | provider | 95 | person | 91 | adopted | 84 |
 | tool | 76 | holder | 75 | grant | 65 |
 | assignment | 60 | secret | 56 | scope | 55 |
 | apply | 54 | resolver | 51 | genesis | 46 |
 | verb | 45 | firewall | 43 | route | 42 |
 | converged | 40 | private network | 37 | connectivity | 34 |
 | the lab | 33 | proxy | 31 | overlay | 30 |
 | upgrade | 27 | gate | 25 | condition | 23 |
 | endpoint | 23 | reconcile | 22 | vault | 20 |
 | hub | 19 | finding | 19 | health | 19 |
 | licence | 16 | probe | 15 | tier | 14 |
 | membership | 14 | anchor | 14 | backup | 11 |
 *Module* itself — the word the whole mesh is built on — has no entry. Nor do the words of the four
 designs written in the last week: *condition*, *healer*, *self-check*, *watchdog*, *hand-act*, *drill*,
 *lease*, *epoch* (to-be 45, *a core that cannot fail silently*); *data class*, *restore point* (to-be 43
 and ADR 0233); *converged* and *adopted* as the two states a machine is in (the controller's `nodes` verb
 answers with them).
 ## The seven contexts, as they stand
 ADR 0006 split the controller into seven **contexts** — areas of record, each owning its own store
 (ADR 0008) — and to-be 06 tabulates them:
 | Context | Owns, in ADR 0006's words | A store of its own today? |
 |---|---|---|
 | inventory | nodes, modules, assignments, versions | yes |
 | config | settings, secrets, and deriving them onto nodes | no |
 | connectivity | overlay, resolution, exposure, filtering, certificates | no |
 | provisioning | resource grants between modules | no |
 | delivery | source to artifact to node | no — deliveries are kept by the `mesh-delivery` module since ADR 0239 |
 | observability | health, logs, metrics, alerts | no |
 | identity | agents, humans, services, authorisation | yes |
 The store has a third database the seven do not name, `licences` (ADR 0183). The seven are the nearest
 thing the mesh has to domains, and they were drawn from one question — *does answering this need more than
 one node?* — which is a test for what the controller owns, not for where a word belongs. Seat, claim,
 bench, delivery group, condition, ask, data class and every word of the operator's conversation arrived
 after them, and none of those records says which context its words belong to.
 Research 005 asked a neighbouring question in August — which *modules* group into domains — measured which
 modules change together, and found that only the reachability modules do. Its conclusion, recorded in ADR
 0009, was that modules are not grouped into packages; it did not touch the vocabulary. This effort groups
 *concepts and words*, not modules: a module may serve several domains, and the domains are not folders in
 the catalogue.
 ## The words the running tools use
 The console's listing gives each tool's first line. Over the 535 module tools (the seat verbs are counted
 separately below):
 | Word | Tools | Modules | Note |
 |---|---|---|---|
 | machine | 39 | 25 | the word most modules use for where they run |
 | node | 27 | 5 | 21 of the 27 in the agent's configuration module; the others the vault, the bus server, the packet filter and a flow editor whose own objects are called nodes |
 | the host / host's | 6 | 2 | the container module's `start` and `stop` tools, meaning the node-engine; the remaining uses are a network's hosts |
 | operator | 28 | 23 | the person; consistent with the glossary |
 | user | 30 | 12 | almost all a wrapped program's own accounts (an identity provider's users, the forge's users, a database's users) |
 | install | 43 | 16 | a package installed on a machine, never the mesh's assignment |
 | condition | 0 | 0 | — while the controller's verb is `conditions` |
 | seat | 0 | 0 | the module tools never name a seat; only the console and the controller do |
 | deploy, rollout, pipeline, control plane | 1, 0, 0, 0 | — | the one *deploy* is a wrapped program's own (a flow editor's) |
 The seat verbs say:
 - `<machine>/node-service-manager.start` and `.stop`: *"the answer says **the host** will restore what its
  declaration says at its next apply"*.
 - the bus server module's `connections` tool: *"a machine's **host** `node.<machine>`, a machine's runtime
  `<machine>.node-tools`"* — three words (host, node, runtime) for two programs, in one line.
 - `mesh-controller.plan`: *"What one machine would run, and why: **the declaration** the mesh would send
  it"*; `mesh-controller.plans`: *"What the last merges produced … the tiers"*;
  `mesh-controller.delivery-plan`: *"The delivery plan of a diffset"*. Three meanings of *plan* on one
  seat.
 - `mesh-controller.queue`, `.cancel`, `.clear`: *"Every **ask** in the build queue"* — while the glossary's
  *ask* is a request for the operator's input.
 - `mesh-delivery.release`: *"A person's word that a held delivery goes on"*; and
  `anthropic-licence-manager.release`: *"Unbind a consumer"*.
 - `mesh-controller.doctor`: *"The **self-check** …"* — the verb and the concept named differently.
 - the nftables module's tool is called `firewall_rules`, and the seat it holds on every machine is
  `node-packet-filter`, whose verb is `rules`.
 - `mesh-controller.nodes`: *"Every **machine** the mesh knows"*; the verb is named for nodes and answers
  in machines.
 - `node-build-agent` is the name of a seat every machine holds, while the glossary avoids *agent*
  *"because the word already means two other things here, the build agent and the operator's coding
  agent"*, and ADR 0237 calls the same role *the build seat*.
 - `operator-channel` is a seat of the mesh, held by the conversation's router (ADR 0234); the glossary
  names the router and the `channel` bench but not the seat.
 **Vendor words are not drift.** A module that wraps a program speaks that program's language where it
 describes the program's own objects: an identity provider has *users* and *realms*, a media manager has
 *releases*, a flow editor *deploys*. That is correct and must stay so; a check that flagged it would be
 wrong ([04](04-how-the-glossary-is-checked.md) scopes the list to the mesh's own words for that reason).
 The drift is where a tool describes **the mesh's** objects — its machines, its engine, its seats — in a
 word the glossary retired or never had.
@@ -1,292 +0,0 @@
 # 02 — The domains
 A proposed split of the mesh's concepts into domains, tested against the operator's starting guess and
 against the seven contexts of ADR 0006.
 ## What a domain is here, and how one was drawn
 A **domain** is an area of the mesh that **owns** a set of concepts: inside it each concept has one
 word, and the domain decides what that word means. Another domain may use the word — that is what makes
 it a shared language — but may not change its meaning. Two relations between domains are named:
 - **upstream / downstream.** Domain A is *upstream* of B when B depends on A's concepts and A does not
  depend on B's. A change of meaning upstream ripples down; never the other way.
 - **shared word.** A word two domains both use. It is safe when both mean the same thing and one of
  them owns it; it is a clash when they mean different things ([03](03-the-clashes.md)).
 Three tests decided where a concept belongs, in this order:
 1. **Who records it.** The context, module or seat that writes the record of it owns it (ADR 0008: *a
   context owns its store*). A condition is the controller's record; a delivery is `mesh-delivery`'s.
 2. **Whose decision records define it.** The records that introduced the word, and the to-be design that
   names those records in its frontmatter.
 3. **Which other words it is never used without.** *Walk* never appears without *delivery*, *tier* and
   *gate*; *healer* never without *condition* and *budget*.
 **Domain and context.** ADR 0006's *context* is narrower than a domain: it is one owner of records, with
 one store, inside the controller. This effort proposes that a domain may hold zero, one or several
 contexts, and that the two words are kept apart: **domain** for the area of vocabulary and ownership,
 **context** for a store-owning part of the controller. Whether to adopt *domain* at all, or to widen
 *context* to mean it, is a question for graduation ([00](00-overview.md)); this document uses *domain*.
 ## The split
 Ten domains of the mesh, and one of this repository. They are ordered from the most upstream to the most
 downstream; each lists its purpose, the concepts it owns with the proposed word for each, and its
 relations.
 ### 1. Module — what a module is and declares
 **Purpose.** To say what one module is, in the one document every other domain reads: its manifest.
 **Owns.** *module*; *manifest* (the file a module is defined by — not *module definition*, not
 *module.yml* in prose); *resource* (what a manifest declares a machine must have: a file, a service, a
 container, a package); *declares* (the verb for what a manifest states); *provides* / *requires* (as
 written in a manifest; their meaning is Provisioning's); *claim* (a manifest's request to hold a seat);
 *setting* (a value a manifest declares and an assignment gives); *kept region*; *bundle* and *tools
 bundle*; *tool* (what a module serves) and *verb* (what a seat carries); *invokes*; *upgrade policy*
 (`roll`, `together`, `record`); the declarations of *data* and *health* (their meaning is Data's and
 Health's).
 **Relations.** The most upstream domain. Every other domain reads the manifest, which makes its words a
 **published language** — a vocabulary fixed in a schema that others conform to. It depends on nothing
 but the Core's notion of a scope.
 **Against the seven contexts.** None; the seven describe the controller, and the manifest is not the
 controller's.
 ### 2. Core — the mesh's own machinery
 **Purpose.** To keep the controller, the bus, the store and every machine's engine running and agreed,
 so that every other domain has something to run on.
 **Owns.** *controller*; *control-node*; *node-engine*; *node tools* (the tool runtime on every machine);
 *foundation*; *store* (the one database server); *bus*; *broker seat*; *genesis* (raising the foundation
 on an empty mesh); *lease* and *epoch* (ADR 0229: which controller may send, and the order of what it
 sent); *context* (a part of the controller that owns a store).
 **Relations.** Upstream of every domain but Module. Every other domain is a **conformist** to it — it
 uses the bus and the store as they are and has no say in their shape.
 **Against the seven contexts.** Not one of them: ADR 0006 described what the controller owns, and the
 Core is the controller itself.
 ### 3. Placement — what runs on which machine
 **Purpose.** To decide, send and apply what each machine runs, and to say why.
 **Owns.** *machine* (or *node* — see clash 1); *operator account*; *assignment* (a module put on a
 machine); *seat*, *scope* (machine, site, mesh), *capacity*, *bench*, *kind*, *holder*, *holding*;
 *depends on a seat*; *declaration* (what the controller sends one machine — see clash 9); *send* (the
 controller giving a machine its declaration; `push` is the verb that asks for it — clash 4); *apply* (the
 node-engine making a machine match its declaration); *reconcile*; *converged* and *adopted* (a machine's
 two states, ADR 0100); *pin* is Provisioning's, not this domain's.
 **Relations.** Downstream of Module and Core. Upstream of Provisioning, Connectivity, Data and Health,
 which all need to know what runs where. Shares *setting* with Module (a manifest declares it, an
 assignment gives it its value) and *declaration* with Module (clash 9).
 **Against the seven contexts.** ADR 0006's *inventory* (nodes, modules, assignments, versions) and the
 derivation half of *config*.
 The operator's guess called this *running modules on machines (seats, benches, claims)*, and it holds.
 *Claim* belongs to Module (a manifest claims) and *holding* to Placement (an assignment holds), which is
 the distinction the glossary already draws in *installed / holding*.
 ### 4. Provisioning — one module serving another
 **Purpose.** To resolve which module serves a provision for which consumer, and to wire the two.
 **Owns.** *provision*; *provider*; *consumer* (the module that requires); *pin* (a person's choice of
 provider); *endpoint* (where a consumer reaches its provider); *pair credential* (the two ends of one
 credential; the credential itself is Identity's); *retire* (a provider stops serving a consumer the mesh
 no longer asks for, ADR 0230).
 **Relations.** Downstream of Module (requires/provides), Placement (what runs where) and Identity (the
 credential). Upstream of Data, which watches what a provider keeps for a consumer. Shares *consumer* with
 Identity's licences (a licence is bound to a consumer) — the same idea, safely shared.
 **Against the seven contexts.** ADR 0006's *provisioning*, unchanged.
 The operator's guess has no such domain; its words are spread across *running modules* and *data*. They
 are a language of their own: 95 decision records say *provider*, and four seat verbs (`pin`, `unpin`,
 `retire`, `cleanup`) are about nothing else.
 ### 5. Identity and access — who may do what
 **Purpose.** To issue, hold, rotate and check the credentials and grants by which modules, machines,
 agents and the operator act.
 **Owns.** *credential* (anything that proves an identity); *secret* (a credential or other value the vault
 keeps sealed); *vault*; *grant* (what an identity may call or reach); *bus account* and *membership*; *rotate*;
 *licence*, *binding* (a consumer bound to a licence), *adopt* (taking in a licence that existed before);
 *proof* (what an authorising answer carries: a verified sender, a one-time code, a key's touch);
 *operator identity* (the list the router checks a sender against).
 **Relations.** Downstream of Core (the bus's accounts) and Placement (what is assigned where). Upstream of
 Provisioning, Operator and conversation, and Change and delivery (whose builds are signed and whose
 merges are approved).
 **Against the seven contexts.** ADR 0006's *identity*, plus the secrets half of *config*, plus the
 `licences` store, which is a context the seven did not name.
 The operator's guess has no such domain. It is not small: *credential* is in 78 decision records, *grant*
 in 65, *secret* in 56, and two of the three context stores that exist today (`identity`, `licences`) are
 its.
 ### 6. Change and delivery — a commit on its way to the machines
 **Purpose.** To take one commit from its pull request to every machine that should run it, and to put it
 back when it fails.
 **Owns.** *pull request*, *commit*, *trunk*; *merge check* (the two statuses a pull request carries, the
 *merge gate* and the *repository check*, ADR 0238); *build*, *build seat*, *build queue* and the entry in
 it (clash 7); *package* and *package-registry*; *artifact* and *artifact store*; *catalogue* (what the mesh
 holds of every module, at which commit); *delivery*, *delivery group*, *delivery plan* (its *build plan*
 and *deploy plan*); *walk*; *tier* in the sense of a step of a walk (clash 8); *first machine* and its
 *gate* (clash 6); *rollback*; *the lab*, *scenario*, *replay*.
 **Relations.** Downstream of Module, Core, Health (the gate reads health) and Data (a module holding
 irreplaceable data is recorded, not rolled out, ADR 0236). Upstream of Placement in time — a walk asks
 the controller to send — and of Operator and conversation, which carries its held deliveries to a person.
 **Against the seven contexts.** ADR 0006's *delivery*, now owned by the `mesh-delivery` module rather than
 by a context of the controller (ADR 0239).
 The operator's guess called this *building and delivering changes*; it holds, with *change* kept for a
 diff (the glossary already says so) and *delivery* for the thing that travels.
 ### 7. Health and repair — what is wrong, and putting it right
 **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.
 **Owns.** *health* (a module's or core component's statement of being well, ADR 0240); *probe*;
 *signal* and *watchdog*; *self-check* (clash 13); *condition* (one open fact about something wrong, with a
 key and a severity); *healer*, its *repair* and *budget*; *drill*; *hand-act*; *observation* (ADR 0231:
 only observation raises or clears a condition).
 **Relations.** Downstream of everything it watches. Upstream of Change and delivery (the gate) and of
 Operator and conversation (a condition becomes a message).
 **Against the seven contexts.** ADR 0006's *observability* — whose row says *"health, logs, metrics,
 alerts"*. The mesh never built *alerts*; it built conditions, and the word *alert* survives only in a
 wrapped dashboard program's tool. The domain is renamed accordingly: *observability* names the watching,
 and half of what this domain owns is repair.
 The operator's guess called this *health and alerts*. It holds as a domain, under the word the mesh
 uses: *condition*, not *alert* (clash 14).
 ### 8. Data — what the mesh keeps, and getting it back
 **Purpose.** To know every item of data a module holds, how precious it is, and to keep it recoverable.
 **Owns.** *data* as a module declares it (ADR 0233); *data class* — *irreplaceable*, *rebuildable*,
 *cache*; *backup*; *restore point*; *restore* (beside the live data, never over it); the bus's *stream
 snapshot* (ADR 0235); *binding* of a consumer to its data moving only by a person (ADR 0232).
 **Relations.** Downstream of Module (the declaration), Placement (where the data is) and Provisioning
 (data a provider keeps for a consumer). Upstream of Change and delivery (irreplaceable data holds a
 module back from rolling out) and of Health (data is watched).
 **Against the seven contexts.** None. Data was not foreseen in ADR 0006; the self-check measures it today
 (`mesh-controller.data`), and every machine's `node-backup` seat keeps it.
 The operator's guess called this *data and backups*, and it holds.
 ### 9. Connectivity — how machines and modules reach one another
 **Purpose.** To make every machine and module reachable by name where it should be, and unreachable
 where it should not.
 **Owns.** *private network* (clash 15); *resolver*; *uplink*; *hostname*; *zone*; *proxy* and *public
 name*; *packet filter* (clash 16); *intrusion prevention* and *ban*; *reach* (how far an
 assignment's endpoint may be reached from, ADR 0138); the roles a machine plays for the network (the anchor, a hub).
 **Relations.** Downstream of Placement (what runs where) and Identity (who may reach). Upstream of
 Provisioning (an endpoint must be reachable) and of Health (an unreachable machine is a condition).
 **Against the seven contexts.** ADR 0006's *connectivity*, unchanged — and the one domain research 005
 found real in the catalogue's history, where its modules are the only ones that change together.
 The operator's guess called this *the network*, and it holds.
 ### 10. Operator and conversation — the person the mesh works for
 **Purpose.** To let the mesh and its operator talk: tell, ask, answer, and act only on an answer it can
 trust.
 **Owns.** *operator* (the person who runs the mesh; clash 17); *person* (any human, as against the mesh
 acting unattended); *console* (the person's or agent's end of node tools, clash 5); *channel* and *intake*
 benches; *router* and the `operator-channel` seat it holds; *responder*; *ask*, *authorising ask*,
 *answer*; *operator message* and *untrusted input*; *reference*; *notification* on a desktop.
 **Relations.** Downstream of Health (conditions become messages), Change and delivery (a held delivery
 waits for a person's word) and Identity (proofs, the operator's identities). An authorising answer acts in
 whichever domain asked, through that domain's own verb; the conversation owns the asking, never the act.
 **Against the seven contexts.** None. ADR 0006 named `api`, *"the one interface every surface speaks
 to"*, as an interface rather than a context; the console and the conversation are what it became.
 The operator's guess called this *people, conversation and approvals*. It holds, with one adjustment:
 an **approval** is not this domain's concept. The approval of a merge is Change and delivery's (a human
 approves the pull request); the release of a held delivery is `mesh-delivery`'s verb; the conversation
 carries both as asks. *Approval* is in five decision records; *ask* in 58.
 ### 11. The record — how this repository works
 Not a domain of the mesh but of the company's way of building it, and listed because its words collide
 with the mesh's. **Owns** *research effort*, *decision record* (and *supersede*, *progressive insight*),
 *design* (*as-is*, *to-be*), *issue*, *playbook*, *check* (one of `00-META/checks/`), *graduation*,
 *hand-off*. Its *record* and *check* collide with the mesh's (clashes 11 and 12).
 ## The operator's guess, scored
 | Guess | Verdict |
 |---|---|
 | building and delivering changes | **holds** as *Change and delivery* |
 | running modules on machines (seats, benches, claims) | **holds** as *Placement*, with *claim* moved to Module |
 | health and alerts | **holds, renamed** *Health and repair*: the mesh's word is condition, and half the domain is repair |
 | data and backups | **holds** as *Data* |
 | people, conversation and approvals | **holds** as *Operator and conversation*, with *approval* owned by the domain whose act is approved |
 | the network | **holds** as *Connectivity* (ADR 0006's word) |
 | — | **added**: *Module* (the published language), *Core* (what the rest runs on), *Provisioning* (ADR 0006 had it), *Identity and access* (ADR 0006 had it) |
 ## A map
 ```
                         Module (published language)
                                   |
                                  Core
                                   |
        +--------------------------+---------------------------+
        |                          |                           |
    Identity  ------------->   Placement                       |
        |                     /    |     \                     |
        |                    /     |      \                    |
        v                   v      v       v                   |
  Provisioning <------- Connectivity   Data                    |
        |                                |                     |
        +------------->  Health and repair  <------------------+
                           |          |
                           v          v
                 Change and delivery  Operator and conversation
                           |                   ^
                           +-------------------+
                     (a held delivery waits for a person's word)
 ```
 Arrows point downstream. Change and delivery appears low because it reads health and data; in time it
 runs first, and asks Placement to send.
 ## What this split does not decide
 - **Module ownership.** A module may serve several domains (the controller serves five). The domains
  are a partition of words and records, not of the catalogue — research 005 already found that grouping
  modules into folders records nothing.
 - **Whether every domain gets a context with its own store.** ADR 0008's rule applies where a domain's
  records live in the controller; *Change and delivery* has moved its records to a module instead, and
  that is equally sound.
 - **The operator's machine.** The desktop seats (display session, launcher, clipboard, notifier) are
  Placement's seats like any other, and their words are each program's own. Research 018 and 026 did not
  introduce a vocabulary that needs a domain.
@@ -1,306 +0,0 @@
 # 03 — The clashes
 Twenty places where the mesh's words disagree with each other. A **synonym clash** is two or more words
 for one concept; a **homonym clash** is one word for two or more concepts. Each entry gives the evidence
 — which documents and which tool descriptions say what — and a proposed single word, with the domain
 ([02](02-the-domains.md)) that would own it. Counts are files containing the word, as in
 [01](01-the-concepts-in-use.md), unless they say *occurrences*.
 The first five are ordered by cost: how often the clash appears where somebody is told what to do (a
 to-be design, `00-META`, a tool description), and how likely it is to make a reader act on the wrong
 thing. The other fifteen follow by domain.
 A decision record keeps the words it was written with (its immutability rule), so a retired word found in
 a decision record is not a fault and is not counted as drift below unless the record was written after
 the word was retired.
 ## The five that cost most
 ### 1. *machine* and *node* — one concept, two words (synonym)
 **Evidence.**
 - The glossary defines **node**: *"a machine in the mesh"*, and has no entry for *machine*.
 - In the decisions and designs of the last week (ADRs 0220 to 0240, to-be 45 to 48), *machine* occurs 706
  times and *node* 349 times. Before ADR 0150, 6 record titles say *machine* and 9 say *node*; from ADR 0150
  on, 17 and 17.
 - In the tool descriptions, *machine* is in 39 tools of 25 modules; *node* in 27 tools of 5 modules, 21 of
  them one module's (the agent's configuration, where *node* is also a scope's value).
 - The console's own tools are `mesh_machine` and an overview that lists *"machines"*. The controller's verb
  is `nodes` and answers *"Every **machine** the mesh knows"*; `node` answers *"What one machine
  reported"*. Every seat a machine holds is named `node-…`.
 - The glossary itself switches inside one entry: *control-node* is *"the one node that also holds…"*, and
  the next sentence says it *"is not a separate kind of machine"*.
 **Proposed word: _machine_** (Placement). It is what the operator, the tools and the newest records already
 say, and it needs no explaining. *Node* survives only as an **identifier**: the value of a scope
 (`scope: node`), the `node-` prefix of seat names, and *control-node* until it is renamed. The glossary
 would map the identifier to the word, as it does for `mesh-host` today. The alternative — *node* everywhere —
 is defensible and cheaper in code, and is what the glossary says; it is listed in
 [00](00-overview.md) as the operator's call because either choice renames something heavily used.
 ### 2. *node-engine*, *mesh-host*, *the host*, *node host*, *host agent* — one program (synonym)
 **Evidence.**
 - The glossary retired *host agent*, *the host* and `mesh-host` for **node-engine** on 2026-10-05, keeping
  `mesh-host` as the name of the repository, binary and service unit until they are renamed.
 - Its own node tools entry still says *"a host-side process **the host** supervises"*.
 - To-be 05 is titled *the node host*; *the host* is in 34 to-be designs and *node-engine* in 7.
 - Of the decision records written since the retirement, ADR 0222 says *the host* six times, ADR 0236 six
  times beside *node-engine* nine times, and ADR 0223 three of each.
 - Tool descriptions: `<machine>/node-service-manager.start` and `.stop`, and the container module's
  `start` and `stop`, say *"the answer says **the host** will restore …"*. The bus server's `connections`
  tool says *"a machine's **host** `node.<machine>`"* — naming the program *host* and its bus account
  *node*.
 - *Host* also keeps its ordinary meanings: a network host (the ssh client module's tools), *hosting* a
  service, and the *host's* network in a container runtime.
 **Proposed word: _node-engine_** (Core), as the glossary already says; *the host* and *host agent* retired
 for the program. Because *host* also has ordinary networking meanings, the check in
 [04](04-how-the-glossary-is-checked.md) can retire only the phrases *the host* and *host agent* and the
 identifier `mesh-host` outside code spans, not the bare word. If clash 1 is decided for *machine*, the
 program's name reads more naturally as **machine engine**; this effort does not propose renaming it again.
 ### 3. *plan* — four things (homonym), and *change plan* / *release plan* / *delivery plan* (synonyms)
 **Evidence.** On one seat, the controller's:
 - `mesh-controller.plan` — *"What one machine would run, and why: the declaration the mesh would send it"*.
  A **machine's declaration**, previewed.
 - `mesh-controller.plans` — *"What the last merges produced and where each stands (ADR 0162): the
  tiers"*. ADR 0162 calls it *a tiered plan*; ADR 0218 and ADR 0236 call it the **release plan** (seven
  times in ADR 0236: *"Every release plan's first machine passes a gate"*).
 - `mesh-controller.delivery-plan` — *"The delivery plan of a diffset"*. The glossary: *"ADR 0238 called it the
  **change plan**; that word is retired"* — and the walk replaces the release plan: *"the controller's
  plan is now the walk of one delivery's trunk commit across machines"*.
 - `mesh-controller.bus` — *"The bus as a **planned step**"*.
 *Release plan* appears in seven files created on or after 2026-10-06, the day ADR 0239 replaced it; *change
 plan* in four, including the title of ADR 0238.
 **Proposed words** (Change and delivery, except the first):
 | Concept | Word | Retire |
 |---|---|---|
 | what the controller would send one machine | **declaration** (Placement); the verb `plan` becomes `declaration` or `preview` | *plan* for this |
 | what a delivery would do to the mesh | **delivery plan** | *change plan*, *release plan* |
 | the controller's sending of one commit's builds across machines | **walk** | *release plan*, *plan* for this |
 | a step a person starts | **planned step**, or simply *step* | — |
 Bare *plan* is then never a mesh concept on its own.
 ### 4. *push*, *send*, *roll out*, *release*, *deploy*, *upgrade* — moving a change (synonyms and homonyms)
 **Evidence.**
 - **push.** `mesh-controller.push`: *"Send one machine everything it should be. With no machine named it
  is a push of the WHOLE mesh"*. ADR 0221's title: *"a push sends no build a policy or a plan holds
  back"*. The same word is a git push (which, per the conventions, starts the build) and a phone
  notification (*"Matrix once its push is measured"*, to-be 46). *Push* is in 84 decision records and
  152 issues.
 - **send.** ADR 0236: *"that machine is sent it, by the ordinary send"*; the gate is judged *"from the
  moment it was sent the build"*. The controller's own description of `push` uses *send*.
 - **roll out.** ADR 0236's title says *rolls out unattended*; its person-facing verb is `upgrade <module>
  roll-out`, and the manifest's policy for the same thing is spelt `roll`. ADR 0218: *"code rolls out one
  machine first"*. *Roll out* is in 30 decision records and 36 issues.
 - **release.** `mesh-delivery.release` — *"A person's word that a held delivery goes on"*;
  `anthropic-licence-manager.release` — *"Unbind a consumer"*; and the retired *release plan* (clash 3).
 - **deploy.** The glossary: a delivery is *"not 'deployment' (one stage of it)"*; its *delivery plan* holds
  a *deploy plan*. The controller has no verb named deploy, and the only tool that says *deploy* is a
  wrapped flow editor's.
 - **upgrade.** `mesh-controller.upgrade` — *"How each module's new builds reach its machines … rolled out
  one machine first"*: a **policy**, not an act.
 **Proposed words:**
 | Concept | Word | Domain |
 |---|---|---|
 | the controller giving one machine its declaration | **send** (the verb `push` asks for one) | Placement |
 | one commit travelling to every machine | **delivery** | Change and delivery |
 | the per-machine part of a delivery plan | **deploy plan** (kept; the only use of *deploy*) | Change and delivery |
 | a build going to its first machine, judged, then the rest | **walk** (the act); **roll** (the policy, one spelling in the manifest and in the verb) | Change and delivery |
 | a person letting a held delivery go on | **release** — this sense only | Change and delivery |
 | unbinding a licence's consumer | **unbind** (rename the licence verb) | Identity |
 | how a module's builds reach its machines | **upgrade policy** | Module |
 *Push* is kept for the controller's verb because it names what the operator does, but prose says *send*;
 *roll out* becomes the policy's value `roll` and is not a noun.
 ### 5. *console*, *node tools*, *mesh-console*, *the MCP server* — the operator's surface (synonym and homonym)
 **Evidence.**
 - The glossary's surfaces section: the console is *"the module (`mesh-console`)"*; not *"the tool bridge",
  "the brain" or "the MCP server"*.
 - The glossary's operator's machine section: node tools *"replaces 'console' as the module's name;
  console remains the word for the person's end of it"*. Both entries are current.
 - The live console introduces itself as *"The tools of a Novox mesh, reached as `<machine>.node-tools`"*,
  under an MCP server named `mesh`; the organisation's instructions to the agent call that server *"the
  console"*.
 - *Console* is in 28 decision records; `mesh-console` in 1; *node tools* in 10. A wrapped chat program's
  tool and the localisation module's tool use *console* in their own senses (a virtual terminal, a web
  console).
 **Proposed words:** **node tools** (Core) for the runtime that serves every module's tools and every seat's
 verbs on a machine; **console** (Operator and conversation) for the end of it a person or agent uses — the
 MCP endpoint and its five tools. `mesh-console` retired. The glossary's surfaces entry is rewritten at
 graduation; the contradiction is removed, not annotated.
 ## Change and delivery
 ### 6. *gate* — three things (homonym)
 ADR 0136 (*a step gates its module, not the machine*): a failing step of a module's apply stops that
 module's later steps. ADR 0236: the **gate** on a delivery's first machine — *"healthy three times"*.
 ADR 0237 and ADR 0238: the **merge gate**, a status a pull request carries (`mesh/merge-gate`). The
 controller's description of `upgrade` says *"judged there at the gate"*; a wrapped forge's tools say
 *branch protection*. **Proposed:** *first-machine gate* for ADR 0236's, *merge gate* for the status, and
 ADR 0136's becomes *a failed step holds its module* (no noun). Bare *the gate* is not used.
 ### 7. *ask* — the operator's question, and an entry in the build queue (homonym)
 The glossary: *"**ask** — a request for the operator's input, of a declared kind"* (ADR 0234).
 `mesh-controller.queue`: *"Every **ask** in the build queue: waiting, in flight … and dead"*;
 `.cancel`: *"Drop one waiting or dead ask"*; `.clear`: *"Cancel every waiting ask"*. ADR 0234's ask is in
 58 decision records' worth of prose shared with the ordinary verb *to ask*. **Proposed:** *ask* stays the
 operator's (Operator and conversation); an entry in the build queue is a **build request** (Change and
 delivery), and the three verbs' descriptions say so.
 ### 8. *tier* — three things (homonym)
 The `topic: the tiers` of 36 decision records, and `repos.md`'s *Tier 0 … 3*: the **layers** of the mesh
 (node-engine, foundation, controller, surfaces). ADR 0162 and to-be 47: the **steps of a walk**, a module
 and the modules built against it (*"its builds are asked and registered tier by tier"*). To-be 46: the
 **levels of authority** of an ask (*"a kind below the tier"*, *"no P2 tier before recovery codes"*).
 **Proposed:** *layer* for the first (Core); *tier* for the walk's steps (Change and delivery), which is how
 the tools use it; *assurance level* for the third (Identity and access).
 ### 9. *declaration* — what a manifest states, and what the controller sends (homonym)
 The glossary: the node-engine *"receives the node's **declaration**"* — the controller's per-machine
 document. The glossary again: a module *"**declares** resources"*, and *depends on a seat* is *"derived from
 the resources it declares"* — the manifest. `mesh-controller.plan` returns *"the declaration the mesh would
 send"*; the container and service-manager tools say *"what its declaration says"*. *Declaration* is in 106
 decision records, in both senses. **Proposed:** a manifest **declares** (Module; the noun is *the
 manifest*), and what the controller sends one machine is that machine's **declaration** (Placement). The
 verb and the noun then never name the same thing, and *declaration* is not used for a manifest.
 ### 10. *control plane* and *controller* (synonym, drift)
 Retired by the glossary on 2026-09-16. Since then: 29 occurrences in 12 to-be designs (`05`, `07`, `08`,
 `18`, `19`, `26`, `28`, `29`, `30`, `32`, `33`, `01`) and one as-is design; 73 files created after the
 retirement use it — 36 issue reports, 29 decision records, 6 designs — among them issue 156, titled *moving a consumer's delivery subject
 stops the control plane*. ADR 0006, the record the word came from, still has it in its
 title. **Proposed:** *controller* (Core), as decided; the to-be designs are corrected at graduation, which
 is a link-and-word fix the README's rules allow.
 ## The record and its checks
 ### 11. *record* — four things (homonym)
 A **decision record** (this repository). **The record** of the mesh — the `records` module that agents
 search first (*"search the record with the literal text"*), and ADR 0006's *"where the record lives is
 deliberately open"*. An **upgrade policy** value: `record` means *register the build, send it nowhere*
 (ADR 0236). **On record**: a seat holder the controller has written down (ADR 0223's *"each on record"*).
 **Proposed:** *decision record* always qualified in hq; *the record* for the mesh's knowledge base (Operator
 and conversation, or a domain of its own if the records module grows one); the policy value renamed
 **hold** — which is also what *held* means for a delivery — and *on record* left as ordinary English.
 ### 12. *check* — at least six things (homonym)
 The checks in `00-META/checks/`; a pull request's **merge check**, made of the **merge gate** and the
 **repository check** (`mesh/repo-check`, ADR 0238); a delivery group's **composed check**
 (`mesh-controller.delivery-check`); the state `checked` of a delivery; the **self-check** (clash 13); a
 module's tool named `…_check` (the ssh client's). *Check* is in 92 decision records. **Proposed:** never
 bare in a governing document; always one of *merge check*, *repository check*, *composed check*,
 *self-check*, *hq check*. The word is too ordinary to retire, so this one is a writing rule, not a list
 entry ([04](04-how-the-glossary-is-checked.md) says why it cannot be checked mechanically).
 ## Health and repair
 ### 13. *self-check* and *doctor* (synonym)
 To-be 45 names the concept **self-check** (8 occurrences) and the verb `doctor` (14); the verb's own
 description begins *"The self-check (to-be 45 §4)"*. **Proposed:** *self-check* (Health and repair); the
 verb renamed `self-check`, or kept as `doctor` with the glossary mapping it — a verb name is an identifier.
 ### 14. *condition*, *alert*, *problem*, *incident*, *finding* (synonyms)
 The controller's verb `conditions`: *"What is wrong with the mesh now: every open condition"*; to-be 45 says
 *condition* 72 times. ADR 0006's observability context owns *"health, logs, metrics, **alerts**"*. ADR
 0224's title: *"a provider that keeps failing a consumer is a **problem** the controller reports"*. The
 container module's tool is `docker_problems`. *Incident* is in 14 decision records, mostly as *the incident
 that earned a rule*. *Finding* is in 19, as what a check or a probe found. **Proposed:** *condition*
 (Health and repair) for an open fact about something wrong; *finding* for what one probe or check returned
 before it becomes a condition; *incident* kept for a past event that taught a rule (The record); *alert* and
 *problem* retired for the mesh's own notion. A wrapped dashboard's *alerts* are its own.
 ## Connectivity
 ### 15. *private network* and *overlay* (synonym)
 The operator, quoted in ADR 0226 (2026-10-06): *"we simply have a private network"*; ADR 0226's title and
 the `mesh-wireguard` module's role: *the private network*, in 37 decision records. To-be 08 (connectivity)
 says *overlay* 24 times; *overlay* is in 30 decision records and 13 to-be designs. No tool says either.
 **Proposed:** *private network* (Connectivity), the operator's word.
 ### 16. *packet filter* and *firewall* (synonym)
 The seat every machine holds is `node-packet-filter`, with the verb `rules` (*"The packet filter as this
 machine enforces it now"*). The nftables module's tool is `firewall_rules`. *Firewall* is in 33 decision
 records and 13 to-be designs; *packet filter* in 22 and 12. **Proposed:** *packet filter* (Connectivity),
 after the seat; the module's tool renamed `packet_filter_rules` or described in the seat's word.
 ## Operator and conversation
 ### 17. *operator*, *the user*, *person* (synonym, partly)
 The glossary's *operator account* entry: *"Not 'the user' (ambiguous with a module's own account)"*. *The
 user* is in 10 to-be designs, several meaning a bus account (*"the user list"*, the bus server's word), and
 in 9 decision records. *Operator* is in 125 decision records and the tools of 23 modules; *person* in 91
 records, meaning a human as against the mesh acting unattended (*"a person's word"*). **Proposed:**
 *operator* for the person who runs the mesh; *person* for any human acting where the mesh could have; *the
 user* retired in the mesh's own prose; a bus account is a *bus account* (Identity). A wrapped program's
 *users* are its own.
 ### 18. *agent* — three things (homonym)
 The glossary avoids *agent* for the node-engine because it *"already means two other things here, the build
 agent and the operator's coding agent"*. The seat every machine holds is `node-build-agent`, held by the
 `build-agent` module; ADR 0237 calls the role *the build seat*, ADR 0236 *the build machine* (14 decision
 records). The licence manager's verbs say *"a node's **agent**"* for the coding agent a licence is bound to.
 A wrapped memory server has *agents* of its own. **Proposed:** *agent* only for a coding agent (the
 operator's, or one the mesh runs); the build role is the **build seat**, its holder on a machine the
 **builder** — and the seat renamed when seats are next renamed. *Build machine* retired: any machine may
 hold the seat.
 ## Core
 ### 19. *store* — four things (homonym)
 The glossary: **store** — *"the one postgres server"*. ADR 0189's title, *"The store keeps what the
 records name"*, is about the **artifact store**. Research 015 is about the **object store**. ADR 0006: *"a
 node reconciles from its own store"* — the machine's local copy of its declaration. **Proposed:** *store*
 alone means only the foundation's database server (Core); the others are always *artifact store*, *object
 store*, and the machine's *last declaration*.
 ### 20. The glossary's own contradictions
 Recorded in [01](01-the-concepts-in-use.md) and listed here because the fix is the same kind: the console
 (clash 5); the deprecated broker, which has no seat in its own entry and claims `mesh-broker` in the entry
 for *claim*; and node tools described with the retired *the host*. **Proposed:** fixed at graduation,
 in the same change that reorganises the glossary ([05](05-a-glossary-by-domain.md)).
 ## Checked and found consistent
 Worth saying, so nobody repeats the search:
 - **catalogue / catalog.** Prose says *catalogue* everywhere (no bare *catalog* in any decision, design or
  `00-META` file); *catalog* appears only inside identifiers (`mesh-catalog`, `catalog_modules`). That is an
  identifier, not a clash.
 - **foundation / substrate.** Of the 10 files created since *substrate* was retired that still use it, 9
  are decision records and research (allowed to keep their words); the tenth is the glossary, naming it
  as retired.
 - **flavor.** Retired; two to-be designs (08, 16) still say it, both predating the retirement.
 - **operator** in the tools is used consistently for the person, in 28 tools of 23 modules.
@@ -1,140 +0,0 @@
 # 04 — How the glossary is checked
 [`AGENTS.md`](../../AGENTS.md): *"If a document states a rule about the mesh, it says how that rule is
 verified. An unenforced rule is indistinguishable from a wrong one."* The glossary states two rules — *one
 name per thing*, and *"a new name for an existing thing lands here first, in the same change that
 introduces it in code"* — and nothing verifies either. [03](03-the-clashes.md) is what that costs. This
 document describes a check; it does not build one. Building it follows graduation.
 ## What a word list can and cannot catch
 A list of retired words catches **synonyms**: a word the glossary replaced, used again. It cannot catch
 **homonyms** — *plan*, *gate*, *tier*, *ask*, *store*, *record*, *check* — because the word is right in one
 sense and wrong in another, and telling them apart is reading, not matching. So the proposal has two
 parts: a mechanical check for synonyms, and a rule for homonyms that turns each one, once decided, into a
 synonym the list can hold (*release plan* → *walk*; *build machine* → *build seat*; `ask` in the build
 queue's verbs → *build request*). A homonym left undecided stays a reviewer's job, and the glossary says
 so next to the word.
 ## Part 1 — the list, kept in the glossary
 The list of retired words lives **in the glossary, in one fixed form**, so there is one source and no
 second file to drift from it. Every entry that retires words ends with one line:
 > *Not:* ~~control plane~~, ~~substrate~~
 and nothing else in the glossary is struck through. Today the glossary marks retired words three ways
 (struck through, *"Replaces x"*, *"Not x"*); graduation moves all of them to this line.
 Each struck word may carry a **scope**, in brackets after it, saying where it is retired:
 - *(hq)* — in this repository's governing documents only;
 - *(tools)* — in the descriptions of the mesh's tools and seat verbs only;
 - no scope — both.
 The scope exists because some words are wrong in one place and right in the other: *the user* is retired
 in hq prose, but a wrapped identity provider's tool must say *user*.
 An entry may also carry an **identifier** line naming code that still has the old name, and the issue that
 tracks its rename:
 > *Identifier until renamed:* `mesh-host` — the repository, binary and service unit (issue NNN)
 An identifier is allowed inside a code span (`` `mesh-host` ``) and nowhere else; when the issue resolves,
 the line goes and so does the allowance.
 ## Part 2 — `00-META/checks/words.py`, over this repository
 **Reads** the glossary's *Not:* lines and *Identifier* lines. **Scans** the documents that tell somebody
 what to do — the same set `records.py` calls *governing*: `00-META/` (the glossary's own *Not:* lines
 excluded), `03-DESIGN/01-to-be/`, `AGENTS.md` and `README.md` — plus `03-DESIGN/00-as-is/`, whose words
 should be today's even where its facts are yesterday's.
 **Fails** on a retired word (of scope *hq* or none) in running prose. It **ignores**:
 - code spans and code blocks, which hold identifiers;
 - block quotes and text in quotation marks, which quote somebody — the operator, a tool, an older
  record — and must quote them faithfully;
 - link targets, which are file names, and file names are immutable when they are a decision record's;
 - `02-DECISIONS/` entirely, and `01-RESEARCH/` and `04-ISSUES/` written before the check's start date
  — records keep their words, and research and issues observe.
 **For research and issues written after the start date** the check applies the same rule. An issue report
 quoting a log or a tool keeps the quotation; its own prose uses today's words. This is a choice for
 graduation, listed in [00](00-overview.md); the reason to include them is that issue reports are the
 largest single source of drift found (36 of the 73 files that say *control plane* since its retirement).
 **The reverse rule.** A to-be design that defines a word in the glossary's form — a bolded word followed by
 a dash at the start of a definition — must find that word as a head word in the glossary. This is how
 *"a new name lands here first"* gets checked, and it would have caught *condition*, *healer* and
 *data class* arriving in to-be 43 and 45 with no entry.
 **The uniqueness rule.** No head word appears in two entries, and no head word is also struck through in
 another entry. This would have caught *release*: today a verb of `mesh-delivery`, and the retired *release
 plan*.
 **What it would fail on today** — the check is proposed because these are real, and per
 [`00-META/checks/README.md`](../../00-META/checks/README.md) a check must fail on something real before
 it passes:
 | Retired word | Where, today |
 |---|---|
 | control plane | 29 occurrences in 12 to-be designs; one as-is design |
 | the host (for the node-engine) | 34 to-be designs, and the glossary's own node tools entry |
 | release plan, change plan | to-be 45, 47 |
 | flavor | to-be 08, 16 |
 | the user | 10 to-be designs (several are a bus account) |
 Each is either fixed at graduation or, where it is a quotation, put in quotation marks — which is the
 check doing its job, making a quotation look like one.
 ## Part 3 — the same list, over the catalogue's tool descriptions
 An agent meets the mesh's words most often in tool descriptions: 535 module tools and the verbs of 20 seats
 today. Nothing compares them with the glossary, and four of them say *the host*.
 **Where it runs.** In the catalogue repository's own repository check (`mesh/repo-check`, ADR 0238), which
 already reads every changed manifest. A changed manifest's tool descriptions and its seat's verb
 descriptions are matched against the *Not:* words of scope *tools* or none. A finding fails the check, as
 everything does on the mesh's repositories (a warning blocks a merge the same as a failure there, [issue
 293](../../04-ISSUES/293-a-warning-on-a-required-check-blocked-the-merge/00-report.md), so a warning-only mode
 is not available and is not proposed).
 **Where the list comes from.** The catalogue cannot read this repository at build time without a new
 dependency. Two options, for graduation:
 1. **A copy, checked.** The catalogue keeps a copy of the list, and `words.py` here fails when the copy in
   the catalogue's trunk differs from the glossary. Simple; two repositories change for one word, which is
   honest about what a retired word costs.
 2. **The list as an artifact.** This repository's merge publishes the list to the artifact store, and the
   catalogue's check reads the newest. One source; one more thing that must be up for a catalogue merge.
 The first is recommended: it fails loudly in the right place, and adds no runtime dependency.
 **Vendor words.** A module wrapping a program describes that program's objects in its own words — an
 identity provider's *users*, a media manager's *releases*, a flow editor's *deploy*. The list holds only
 the mesh's own retired words, and a word that is also a common vendor word (*user*, *release*, *deploy*)
 is never retired with scope *tools*. That keeps the check from crying wolf, which
 `00-META/checks/README.md` names as the way a check gets suppressed.
 **On the running mesh, later.** The descriptions an agent actually sees are the ones served, which may lag
 the catalogue's trunk. A probe in the self-check could compare the controller's `tools` verb with the same
 list and raise a condition. That is a second place for the same rule and is not proposed until the first
 has run.
 ## Part 4 — homonyms, by rule
 For a word the glossary marks *homonym* (*plan*, *gate*, *tier*, *store*, *record*, *check*, *ask*,
 *agent*), the entry lists each sense with its qualified form and its domain, and the writing rule is: **a
 homonym is never bare in a governing document; it is always the qualified form.** This is not
 machine-checked — a word list cannot tell *the gate* that means a first-machine gate from one that means
 the merge gate — and the glossary says so next to the rule, as AGENTS.md requires: *"checked by review;
 the reviewer looks for the bare word in the diff."* Where a homonym is resolved by renaming one sense, the
 old sense moves to the *Not:* line and becomes mechanical.
 ## What it costs
 - One Python file of the size of `cycle.py`, run by `merge-check.sh`.
 - A one-time correction of the governing documents it fails on, made in the graduation change.
 - A copy of the list in the catalogue, and a few lines in its repository check.
 - One rule for writers: a retired word may be quoted, never used.
@@ -1,101 +0,0 @@
 # 05 — A glossary by domain
 How [`00-META/glossary.md`](../../00-META/glossary.md) would be organised once the domains in
 [02](02-the-domains.md) are decided. Described only: the glossary changes in the graduation change, with
 the decision record that adopts the domains, and not before.
 ## What is wrong with its shape today
 - **Its sections are a history, not a map.** *The operator's machine* holds node tools, bundle, kept region
  and installed / holding because they arrived with research 018, not because they belong together; node
  tools is a Core concept and kept region a Module one.
 - **It has no home for a new word.** A writer adding *condition* would not know which section it goes in,
  and so it went in none.
 - **Retired words are marked three ways**, so no program can read them ([04](04-how-the-glossary-is-checked.md)).
 - **It is one page for 33 entries**; with the roughly 50 words [01](01-the-concepts-in-use.md) found
  missing, it is about 85, and one flat list of 85 is read by nobody.
 ## The proposed shape
 One file, as now — it stays the single authority, and a reader searches one page. Its sections are the
 domains, in the order of [02](02-the-domains.md) (most upstream first), preceded by two short sections.
 ### 1. How to read this page
 What a domain is, in two sentences; that a word is defined once, in the domain that owns it; that other
 domains may use it but not change it; and the forms of the *Not:* and *Identifier* lines the check reads.
 ### 2. Words every domain uses
 A short **shared kernel** — the handful of words with one meaning everywhere, owned by no single domain
 and changed only by a decision record: *mesh*, *machine* (or *node*, clash 1), *module*, *seat*, *operator*,
 *person*. Each points to the domain where its detail lives. Kept deliberately short: a word that only one
 domain refines belongs to that domain.
 ### 3. One section per domain
 Each section opens with a fixed header, then its entries:
 - **Purpose** — one sentence, from [02](02-the-domains.md).
 - **Owned by** — the context, module or seat that records its concepts (*the controller's `inventory`
  context*; *the `mesh-delivery` module*; *every machine's `node-backup` seat*).
 - **Upstream of / downstream of** — the domains, by name.
 - **Decided by** — the decision records that define the domain's words, so a reader can go from a word
  to why.
 Each **entry** keeps today's prose form and gains at most three fixed lines:
 - the definition, in plain sentences, with its record cited (as now);
 - *Not:* ~~retired word~~, ~~another~~ *(scope)* — the words it replaced;
 - *Identifier until renamed:* `old-name` — what code still carries the old name, and the issue that
  tracks the rename.
 A word a domain uses but does not own is not repeated there; the domain's section may list it under *Uses*
 with a link, so a reader of one section sees its whole vocabulary without the definition being copied.
 ### 4. Homonyms
 One section at the end for the words that mean different things in different domains — *plan*, *gate*,
 *tier*, *store*, *record*, *check*, *ask*, *agent*, *release*. For each, a small table: the sense, its
 qualified form, the domain that owns it. This is the page a reader lands on from a search for a bare
 word, and it says the rule beside the table: never bare in a governing document; checked by review.
 ### 5. How this page is kept
 Today's section, extended: a new word lands here first, in the domain that owns it; a word moves domain
 only with a decision record; a retired word goes on a *Not:* line and nowhere else; and `words.py`
 checks the three rules it can ([04](04-how-the-glossary-is-checked.md)).
 ## Where today's entries would go
 | Today's entry | Domain |
 |---|---|
 | node, control-node, operator account | shared kernel (machine); Placement (operator account); Core (control-node) |
 | controller, mesh-controller, node-engine, foundation, store, bus, the deprecated broker | Core |
 | package, artifact | Change and delivery |
 | seat, depends on a seat, installed / holding | Placement |
 | claim, provision (as declared), invokes, bundle, kept region | Module |
 | provision (as resolved) | Provisioning |
 | channel / intake, ask, operator message / input, reference, console | Operator and conversation |
 | node tools | Core |
 | delivery, delivery group, delivery plan, mesh-delivery, walk | Change and delivery |
 | ~~master / slave~~, ~~hub / peer~~, ~~flavor~~ | *Not:* lines on *controller* and *setting* |
 And the sections that are empty today and would be filled from the records that already define their
 words: **Identity and access** (credential, secret, vault, grant, bus account, licence, binding, proof —
 ADRs 0143, 0183, 0225, 0234); **Health and repair** (condition, probe, signal, watchdog, self-check, healer,
 drill, hand-act — to-be 45, ADRs 0227, 0231, 0240); **Data** (data class, backup, restore point, stream
 snapshot — to-be 43, ADRs 0233, 0235); **Connectivity** (private network, resolver, uplink, packet
 filter, reach — ADRs 0117, 0138, 0223, 0226).
 ## What derives from it
 - **The decision index.** The records' `topic:` (*the mesh*, *the tiers*, *what runs on it*, *building
  it*, *checking it*, *how we work*) predates the domains and partly overlaps them. Whether a record also
  names its domain — a new frontmatter field, and so a schema change — is left for graduation. It would let
  `words.py` scope a word by domain, and `index.py` print the reading order per domain.
 - **The constitution page.** The mesh injects a page derived from `how-we-build.md` into design sessions
  (playbook 05). A derived glossary page per domain could be injected the same way, so an agent starts
  with the words; that is a separate decision, not proposed here.
 - **Tool descriptions.** Once a domain owns a word, a module describing that concept in a tool uses it; the
  check in [04](04-how-the-glossary-is-checked.md) holds them to the retired half, and review to the rest.
@@ -38,11 +38,6 @@ hand.
 ### What a domain module turns out to be, and why it is not the one refused above
 > **Narrowed, not replaced — 2026-10-06, by [ADR 0226](0226-the-private-network-is-assigned-by-its-own-name-and-the-proxy-names-its-public-issuer.md).** The catalogue no longer
 > holds a domain module: `networking` was retired, and every machine is assigned the private network's
 > own module. A module with requirements and no files stays a thing a module may be; "why it is worth
 > having" below describes what this record decided for `networking`, not what runs.
 *Written 2026-08-29, from building it. The heading above reads as a contradiction of what now
 exists and is not one — but only if the difference is stated, so it is stated here.*
@@ -9,10 +9,6 @@ extends: 0027-a-provision-names-what-the-consumer-is-coupled-to.md
 # 44. A public name is provisioned, not registered by hand
 > **The mechanism changed — 2026-10-06, by [ADR 0226](0226-the-private-network-is-assigned-by-its-own-name-and-the-proxy-names-its-public-issuer.md).** The interface stands; its one provider,
 > `cloudflare-dns`, left the catalogue, assigned nowhere and required by nothing. A mesh that needs a
 > public name made for it adds a provider of `public-dns` again.
 ## Context
 The mesh names and resolves its own machines internally: the overlay generates
@@ -108,14 +108,6 @@ declared slug is a strictly better escape hatch than an opaque hash. **D stays r
 ## Consequences (of E)
 > **The mechanism changed — 2026-10-06, by [ADR 0225](0225-a-consumers-identity-is-bounded-by-the-provision-it-requires.md).**
 > Option C, named above as the later refinement, is taken: each offer states the longest identity its
 > backend keeps, and a consumer is bounded by the provision it requires rather than by 20 everywhere.
 > 20 stays the bound of the object store and of a provider that is told its consumers and does not
 > say. The overflow is refused before merge by the catalogue check, and at composition the consumer
 > is left out of its provider's grants and reported — never the provider's machine refused. What
 > stands: the identity is said once, the slug is the remedy, nothing is hashed or truncated.
 - A module manifest gains an optional `slug`; a node may carry one too. `ConsumerIdentity` prefers
  the slug over the cleaned name for each half. `identityLimit` becomes 20 (the true minimum), and
  `CheckIdentity` refuses at `module add` / assignment — now with a message naming the slug to set.
@@ -51,14 +51,6 @@ the builder) — cost with no new property.
   restarts the runtime when that file changes — the `/etc/hosts` pattern for the content, the
   nftables pattern for the reload. No module author is involved; being on the network is what
   grants the trust, because being on the network is what the trust *is*.
   > **The mechanism changed — 2026-10-05, by [ADR 0222](0222-a-module-is-told-where-a-mesh-seats-holder-is-reached-and-the-controller-writes-no-file-a-seats-holder-owns.md).**
   > What stands: being on the network grants the trust, the overlay is the transport security, no
   > module author chooses it, and the trust is written into the runtime's file rather than over it
   > and reloaded rather than restarted (ADR 0102). What moved: the controller no longer injects the
   > file or the service. The container runtime's own module writes `insecure-registries`, told where
   > this machine reaches the store by `${seat:mesh-artifact-store:reach}`, because the controller
   > writes no file a seat's holder owns ([issue 190](../04-ISSUES/190-the-runtimes-configuration-is-written-by-modules-that-are-not-the-runtime/00-report.md)).
 3. **No accounts (issue 042), recorded as the position it always was.** Reading and pushing
   require presence on the overlay and nothing else. The boundary is enforced, not assumed: the
   registry's `listens` is `from: mesh`, the firewall derives from it, and the overlay admits only
@@ -45,13 +45,6 @@ an operator obligation, and an obligation enforced by nothing is issue 057 resta
 declaration is computed from the whole mesh; delivering a mesh that is knowingly inconsistent and
 merely saying so would make "push succeeded" mean less than it says.
 > **The mechanism changed — 2026-10-05, by [ADR 0221](0221-a-push-sends-no-build-a-policy-or-a-plan-holds-back-except-to-the-machine-it-names.md).**
 > A named push still flushes every other machine that is behind, compared against what each was last
 > sent. A machine whose modules would move to a build their upgrade policy records, or that an open plan
 > has not sent it yet, is no longer flushed: the push names it and leaves it for `push <node>`. "Behind
 > for an unrelated reason" no longer covers a held upgrade
 > ([issue 259](../04-ISSUES/259-a-named-push-sent-every-machine/00-report.md)).
 ## Consequences
 - One push is sufficient for a cross-node consumer: the provider's grants arrive from the same
@@ -64,15 +64,6 @@ node therefore trusts the mesh's registry as soon as it is on the private networ
 networking no longer touches the runtime. The hosts file networking writes is still written whole
 and stays held until networking is taken; a converge preview names it among the files it replaces.
 > **The mechanism changed — 2026-10-05, by [ADR 0222](0222-a-module-is-told-where-a-mesh-seats-holder-is-reached-and-the-controller-writes-no-file-a-seats-holder-owns.md).**
 > Writing into a shared file, adding to a list and reloading rather than restarting all stand. What
 > moved is the writer: the networking module no longer writes the runtime's trust or declares its
 > service. The container runtime's own module writes it into its own file and reloads its own
 > service ([issue 190](../04-ISSUES/190-the-runtimes-configuration-is-written-by-modules-that-are-not-the-runtime/00-report.md)).
 > The controller test named under *How it is checked* below, which held the networking module to
 > declaring the runtime's file, is replaced by one holding the networking module to declaring neither,
 > and by one holding the runtime's module to the trust.
 ## Consequences
 - The runtime's file on a machine in use keeps its data directory, its logging settings and
@@ -293,12 +293,3 @@ travel, which is the other half and was never in question.
 > request/reply over the bus, never through the vault and never as a file the host writes. ADR 0183
 > states that as a bounded exception — one vendor, tokens that live hours, one recipient per message —
 > and a second such channel is a decision of its own.
 > **The mechanism changed — 2026-10-06, by [ADR 0228](0228-a-value-given-by-hand-lives-only-until-its-modules-first-good-start.md).**
 > What stands: a delivered value the vault cannot replace, such as an external API key, is not rotated
 > by the vault, and rotating it means an operator delivering a new one. What moved: the controller had
 > read that as covering **every** value given to it, and refused to rotate any of them. 0228 says what
 > cannot be replaced is a value an outside party issues, which a module's definition now marks
 > (`"issued-by": "outside"`); a given value for a secret the module reads at start is rotated like a
 > made one, and one given through `secret accept` is replaced on its own after the module's first good
 > start under the mesh.
@@ -9,10 +9,6 @@ extends: 0110-a-seat-is-a-module-assignment-from-a-closed-set.md
 # 117. A machine's uplink is a seat: the mesh configures the manager, never the link
 > **The mechanism changed — 2026-10-06, by [ADR 0226](0226-the-private-network-is-assigned-by-its-own-name-and-the-proxy-names-its-public-issuer.md).** The seat stands; the catalogue holds two
 > of its three modules. `dhcpcd`, held by no machine, left it. What this record says of dhcpcd is what
 > a module for it must do, if one is written again.
 ## Context
 The mesh installs on top of a machine's own networking. The private network's generator says
@@ -60,14 +60,6 @@ with the server held still for its duration. Plain collection, not `--delete-unt
 mesh keeps is still a manifest in the store, so it is still referenced, so its blobs stay — the
 dangerous flag is not needed at all once the mesh is the one deciding.
 > **Progressive insight — 2026-10-05.** "What the mesh keeps is still a manifest in the store" was true
 > of images and false of archives: the builder published every archive as a bare blob no manifest names,
 > and the store's collector keeps only what a manifest names. Its first night would have deleted every
 > archive the mesh keeps ([issue 253](../04-ISSUES/253-the-stores-collector-would-delete-every-archive-the-mesh-keeps/00-report.md)).
 > The decision stands — the mesh decides, the store reclaims with plain collection. What changes is how an
 > archive is published: with a manifest that holds it, so the sentence becomes true of archives too. Until
 > every kept archive is held, the collector runs as a dry run.
 **3. What the mesh keeps, stated as three reasons rather than a number.** A digest is kept because:
 - **a definition names it** — every artifact reference in any module's current recorded manifest,
@@ -11,11 +11,6 @@ extends: 0191-the-meshs-resolver-holds-only-the-meshs-own-names.md
 # 194. The mesh has one resolver, and every node asks it for the mesh's names
 > **The mechanism changed — 2026-10-05, by [ADR 0223](0223-the-mesh-has-two-resolvers-and-a-machine-lists-only-them.md).** `mesh-resolver` (named `mesh-dns-resolver` in the
 > set) is no longer of capacity one: it is a replicated seat, held on the anchor and on the home
 > server, each holding every node's internal domain from the same roster. One resolving module, the
 > mesh's names held only by its holders, and the retirement of every per-node copy stand.
 > **Narrowed, not replaced — 2026-10-03.** How a node asks is decided again by
 > [ADR 0196](0196-a-node-asks-the-meshs-resolver-first-and-a-public-one-only-when-it-is-silent.md): every
 > node and container asks `mesh-resolver` first and a public resolver only when it is silent. There is
@@ -10,13 +10,6 @@ supersedes-in-part:
 # 196. A node asks the mesh's resolver first, and a public one only when it is silent
 > **Narrowed, not replaced — 2026-10-05, by [ADR 0223](0223-the-mesh-has-two-resolvers-and-a-machine-lists-only-them.md).** The public resolver listed second goes: musl asks
 > every listed server at once and takes the first reply, so a public "no such name" for a mesh name
 > won it, and every Alpine build on the home server failed. Every machine now lists the mesh's
 > resolvers — two holders of `mesh-dns-resolver`, its own first on a holder — and nothing else. Every
 > node and container asking the mesh's resolver for every name, with no stub and no runtime `dns`,
 > stands. The "fallback" consequence and check below describe what this record decided, not what runs.
 ## Context
 **[ADR 0194](0194-the-mesh-has-one-resolver-and-every-node-asks-it-for-the-meshs-names.md) gave the
@@ -9,10 +9,6 @@ extends: 0194-the-mesh-has-one-resolver-and-every-node-asks-it-for-the-meshs-nam
 # 199. A module that answers names declares its zone, and a node's hosts file is one module's
 > **Decided to change — 2026-10-05, by [ADR 0223](0223-the-mesh-has-two-resolvers-and-a-machine-lists-only-them.md), not yet built.** The `hosts` module is renamed `hostname`
 > and its seat `node-hostname`, and it owns `/etc/hostname` as well as `/etc/hosts`; the operator's
 > lines are kept as this record decides. Until that is built, everything below stands as decided.
 ## Context
 **[ADR 0194](0194-the-mesh-has-one-resolver-and-every-node-asks-it-for-the-meshs-names.md) and
@@ -64,13 +64,6 @@ instead of `_`, which is the whole of the difference between the mesh's identifi
 the one buckets, vhosts and hostnames use. A provider that needs a prefix or a suffix writes it
 around the placeholder, because a served value is a string.
 > **The mechanism changed — 2026-10-06, by [ADR 0225](0225-a-consumers-identity-is-bounded-by-the-provision-it-requires.md).**
 > The identity is no longer capped at twenty characters for every provision: each offer states the
 > bound its backend keeps, and twenty is the bound of the object store and of a provider that does not
 > say. What stands: the identity is still the mesh's, and `dns` is still that name with its separator
 > written `-`. An offer serving `${consumer:as:dns}` now bounds its consumers at 63 or less, so the
 > label still fits.
 The rejected alternative is **the provider returning values from provisioning** — the natural
 channel, since the provider is what derived them. It is rejected for three reasons, in order of
 weight. It inverts the delivery the mesh is built on: a grant would carry data the provider wrote
@@ -46,13 +46,6 @@ filesystem where there is one. Its key is a mesh secret.
 **A night that fails reaches the operator,** and a machine with data and no good backup in 48 hours
 shows in the mesh's status.
 > **The mechanism changed — 2026-10-06, by [ADR 0233](0233-a-module-declares-the-data-it-holds-and-the-mesh-protects-and-watches-it-from-that.md).** The decision stands: backups guard
 > against mistakes and stay on the machine. What moved is the declaration: a module declares its data in
 > its `data` section, with a class and how each item is protected, and the holder's lines are derived
 > from it; a line written by hand is refused. The media library, left out here, is now declared
 > irreplaceable and protected by the redundancy of its array, which the holder watches, because there
 > is no room to copy it.
 ## Consequences
 - Adding a store provider means declaring its dump; the catalogue check can refuse a store provider
@@ -1,107 +0,0 @@
 ---
 topic: the mesh
 status: accepted
 date: 2026-10-05
 deciders: jochen
 reconstructed: false
 extends: 02-DECISIONS/0162-a-merge-produces-a-tiered-plan-the-mesh-keeps.md
 ---
 # 218. A plan sends grants before code, rolls a module out one machine first, and a newer merge takes over an older plan
 ## Context
 On 2026-10-05 the delivery path was watched through a day of merges, by several sessions at once. Three
 things went wrong, each recorded as an issue with its evidence.
 - **Code arrived before the right to use it** ([issue 249](../04-ISSUES/249-a-modules-new-state-is-refused-until-a-push-the-merge-did-not-make/00-report.md)).
  A merge gave a module a new key-value state. The plan sent the new bundle to every machine, and only
  then issued the memberships that grant the state. On three machines the module's new state was refused
  for two minutes, until a push made by hand. The order is written into the code on purpose: memberships
  "after the declaration, because the runtime it is for arrives with it". That reason holds only for a
  first assignment, and even then a membership is kept on the bus for the runtime that connects later
  ([ADR 0160](0160-the-mesh-issues-an-assignments-subjects-and-a-runtime-serves-what-it-is-issued.md)).
 - **No machine went first.** The module's upgrade policy sends one machine at a time, but a plan's rollout
  ignores it and sends every machine running the module at once. One at a time also never waited for the
  first machine to come up healthy: it stopped only if the publish itself failed. A change was therefore
  everywhere before anything had seen it run.
 - **Plans for successive merges ran over each other** ([issue 254](../04-ISSUES/254-plans-for-successive-merges-run-over-each-other-and-one-was-left-open/00-report.md)).
  Three merges to the catalogue within four minutes made three plans. Each sent the build agent to every
  machine and asked for the same builds. One was still "building" hours later, with nothing left for it to
  wait on. [ADR 0162](0162-a-merge-produces-a-tiered-plan-the-mesh-keeps.md) decides one plan per merge
  and says nothing about the next merge arriving while one is open. [Issue 219](../04-ISSUES/219-an-older-build-that-finishes-later-replaces-a-newer-one/00-report.md)
  settled only which build's output wins.
 ## Considered Options
 1. **Debounce merges:** wait a window before planning, so close merges make one plan. Rejected: it only
   delays the overlap, does nothing for merges further apart than the window, and makes every merge slower.
 2. **Queue plans:** a new plan waits until the older one is done. Rejected: the older plan builds what the
   newer merge is about to replace, then the newer one builds it again.
 3. **A newer merge's plan takes over the older plan's unfinished work, a plan rolls a module out one
   machine first, and grants travel before code.** Chosen.
 ## Decision
 **1. Grants before code.** Every send — a plan's rollout and a push alike — issues the memberships for
 the machines it is about to send to before it sends their declarations, after raising the buckets they
 name. When the composed list of bus users changes, the machine that holds the bus is sent first, because
 that list travels in its declaration. A membership that could not be issued fails the send, and the send
 is tried again. It is never reported as done "until the next push".
 **2. One machine first.** A plan rolls a module out according to the module's upgrade policy
 ([ADR 0162](0162-a-merge-produces-a-tiered-plan-the-mesh-keeps.md) §3). Unless the policy says
 *together*:
 - the module is sent to one machine first, the first by name of the machines running it;
 - the rest are sent only once that machine has reported the new declaration applied and current;
 - a first machine that reports a failure, or does not report in time, stops the module's rollout there.
  The plan names the machine and the reason, and the other machines keep what they ran.
 The plan records which machine went first, so a controller replaced mid-rollout resumes from there. A
 policy of *together* keeps today's behaviour.
 > **The mechanism changed — 2026-10-06, by [ADR 0236](0236-a-build-is-judged-on-its-first-machine-and-put-back-by-something-other-than-itself-and-so-it-rolls-out-unattended.md).** What still stands: one machine
 > first, the first by name, the rest only after it, a failed first machine stopping the module and the
 > plan, *together* as it was. What moved: "reported applied and current" is no longer enough — the first
 > machine is judged at a gate by the component's health, three times over at least two minutes within ten,
 > before the rest are sent; and a first machine that fails, by its report or at the gate, is not left on
 > the build that failed it: the previous build is registered again and sent to it, once per build.
 **3. A newer merge takes over an older plan.** When a merge into a repository's branch makes a plan,
 every open plan for the same repository and branch made before it is superseded, ordered by when each
 plan was made, never by commit:
 - the modules the older plan had not yet built join the newer plan's set, before its tiers are computed;
 - the older plan ends in a state of its own, *superseded*, naming the plan that took it over.
 Builds the older plan already asked for still finish and register; issue 219's ordering keeps the newer
 one current. A person can also close a plan that waits on nothing, by its id. The plan is marked closed
 by hand and never resumed.
 ## Consequences
 - A module that gains a state, an event or a tool can use it from its first start on every machine.
 - A change reaches one machine before the rest. A change that breaks its first machine stops there, with
  the reason in the plan.
 - Successive merges build each module once, for the newest commit. The build agent is sent to the
  machines once per run of merges, not once per merge.
 - **What got harder:** a rollout takes one machine's report longer than before. A module that must change
  everywhere at once says *together* in its policy. A plan's record now has a superseded state that
  readers of the plans must know.
 ## How it is checked
 | Rule | Checked by |
 |---|---|
 | grants before code | the controller's test: a send records memberships issued before any declaration; the machine holding the bus is sent first when the user list changes; a failed membership fails the send |
 | one machine first | the controller's test: with a one-at-a-time policy, one machine is sent, the rest only after its applied and current report; a failed first machine stops the module; *together* sends all at once |
 | a newer merge takes over | the controller's test: an older open plan for the same repository and branch is superseded, its unbuilt modules folded in; a plan for another repository is left alone; a superseded plan is not open |
 | live | the next merge to the catalogue that gives a module a new state: no refusal of that state on any machine, the first machine named in the plan, one plan open per repository |
 ## References
 - [Issue 249](../04-ISSUES/249-a-modules-new-state-is-refused-until-a-push-the-merge-did-not-make/00-report.md), [issue 254](../04-ISSUES/254-plans-for-successive-merges-run-over-each-other-and-one-was-left-open/00-report.md)
 - [ADR 0162](0162-a-merge-produces-a-tiered-plan-the-mesh-keeps.md) — plans and tiers, extended here
 - [ADR 0160](0160-the-mesh-issues-an-assignments-subjects-and-a-runtime-serves-what-it-is-issued.md) — memberships, kept on the bus
 - [to-be 30](../03-DESIGN/01-to-be/30-the-mesh-updates-itself-on-a-push.md) — the design this amends
@@ -1,120 +0,0 @@
 ---
 topic: the mesh
 status: accepted
 date: 2026-10-05
 deciders: jochen
 reconstructed: false
 extends: 02-DECISIONS/0190-a-seats-work-is-shared-by-its-holders-and-building-is-the-first-such-role.md
 ---
 # 219. The build queue is controlled through the controller and the build seat
 ## Context
 The operator asked for tools to control the mesh's builds: see what is queued and running, cancel,
 clear, stop a build immediately, pause and continue, restart and replay. On the day of the request none
 existed. The controller could ask for a build and list finished ones. Nothing could see an ask waiting on
 the build seat's work queue, or one being built. Nothing could take an ask back, and a running build
 could only be stopped by restarting the machine's build agent, which hands the ask to another holder.
 How builds run today, read from the code and the bus
 ([ADR 0190](0190-a-seats-work-is-shared-by-its-holders-and-building-is-the-first-such-role.md),
 [ADR 0157](0157-a-build-says-what-it-does-on-the-bus-as-it-happens.md)):
 - an ask is a message on the seat's work-queue stream;
 - every holder pulls one at a time from one shared worker, and acknowledges after it has announced the
  outcome;
 - a build says it started, logs its steps, and announces what it built, all on the bus;
 - an ask delivered five times without an answer stays in the stream for a week, with nothing saying so.
 Three facts constrain any control:
 - **Only the controller may act on the bus's streams and consumers** (design 25 §3, enforced in the bus's
  user list). Holders may only take from their worker and acknowledge.
 - **A plan waits for a build's outcome and has no timeout.** An ask that disappears without one leaves
  its plan waiting, said only as late after half an hour.
 - **The bus server in use cannot pause a consumer**; that arrived in a later version.
 ## Considered Options
 1. **Pause and cancel by remaking the worker consumer.** Rejected: a remade worker delivers from now on,
   so every queued ask would be skipped silently. Issues 206 and 207 are this mistake both ways round.
 2. **Upgrade the bus first and use its consumer pause.** Not now: it gives pause and continue, and
   nothing else on the list, and upgrading the bus is a change of its own.
 3. **Queue actions are the controller's verbs, process actions are the build seat's verbs, and every
   action that drops work leaves a failed outcome.** Chosen.
 ## Decision
 **1. The queue is the controller's.** Its verbs act on the work-queue stream, the one thing only it may
 touch:
 | verb | what it does |
 |---|---|
 | `queue` | lists every ask: waiting, in flight (with the machine building it, from its started event), and dead (delivered as often as allowed, still in the stream) |
 | `cancel <id>` | takes back a waiting or dead ask; an ask in flight is refused, and `kill` is named instead |
 | `clear` | cancels every waiting ask, and with `--dead` every dead one |
 | `rebuild <module or build>` | asks again for a module's current source, or a past build's source and ref, under a new id |
 | `replay <build>` | asks again for a past build at its commit, as a **dry run** unless told to register |
 | `kill <id>`, `pause [node]`, `resume [node]` | pass the request on to the build seat on the right machine, or on every machine |
 **2. The process is the build seat's.** Each holder serves verbs on its own machine:
 - `current`: the build running here, its step and how long, and whether this holder is paused;
 - `kill`: stops a running build at once. The build's whole process group is ended, along with every
  container it started. Its outcome is announced as failed, and the ask is acknowledged, so it is not
  delivered again;
 - `pause` and `resume`: a paused holder takes nothing new, and a running build finishes. The flag
  survives the holder's restart.
 A holder restarted mid-build keeps today's behaviour: the ask is not acknowledged, and another holder
 takes it.
 **3. Nothing dropped is silent.** Cancel, clear and kill each leave a failed outcome for the ask's id,
 taken in like any other. A plan waiting on that build fails, and says why, instead of waiting. A plan keeps
 the id it asked for, so it can match its outcome exactly. A holder checks a cancelled ask before it builds
 it, so an ask taken in the instant it was cancelled is not built.
 **4. A plan says what its builds are waiting on, and a failed plan can go on.**
 - A plan whose build waits on a paused seat says the seat is paused, and on which machines, and is not
  counted late while it waits.
 - `plans retry <id>` asks again for the modules a failed plan could not build, under new ids. The plan
  resumes at that tier and goes on through its later ones. A plan another has superseded, or one
  already done, is refused.
 - `rebuild` of a module that an open or failed plan has not yet built joins that plan, so the plan and
  the build are one thing.
 **5. Replay does not move the mesh backwards unasked.** A replayed build is a dry run: built, its log
 kept, nothing registered. With `--register` it is registered. If a newer build of the module is already
 registered, that is refused unless `--older` is said as well: registering an older commit makes it the
 current one, and the rollout policy sends it to the machines ([issue 207](../04-ISSUES/207-a-re-made-worker-replayed-every-ask-the-stream-kept/00-report.md)).
 ## Consequences
 - Every build in the mesh can be seen, taken back, stopped or asked again from the console. None of it
  needs a shell on a machine.
 - A cancelled or killed build shows in the build records as failed, with who stopped it. Its plan fails
  saying the same.
 - **What got harder:** a holder now serves verbs as well as taking work, and keeps one small flag on
  disk. Pause is per holder, so "pause the mesh" is the controller asking every holder in turn. A holder
  away at the time misses it, and the answer names that holder.
 ## How it is checked
 | Rule | Checked by |
 |---|---|
 | the queue is read and classified right | the controller's test: waiting, in flight and dead asks told apart from the stream and the worker; a live test on a throwaway bus |
 | nothing dropped is silent | the controller's test: cancel and clear delete the ask and record a failed outcome; a plan asked for that id fails |
 | a cancelled ask is not built | the holder's test: an ask taken after its cancel is answered failed without building |
 | kill stops everything it started | the holder's test: the build's process group and its labelled containers are ended; the outcome is failed and the ask acknowledged |
 | pause survives a restart | the holder's test: the flag is read back at start, and nothing is taken while it is set |
 | plans follow the queue | the controller's test: a plan waiting on a paused seat says so and is not late; `plans retry` resumes a failed plan and its later tiers are asked; `rebuild` joins the plan that holds the module |
 | replay is safe | the controller's test: a dry run by default, and `--register` over a newer build refused without `--older` |
 ## References
 - [ADR 0190](0190-a-seats-work-is-shared-by-its-holders-and-building-is-the-first-such-role.md) — holders share the seat's work, one at a time
 - [ADR 0157](0157-a-build-says-what-it-does-on-the-bus-as-it-happens.md) — a build's own events are its record
 - [issue 207](../04-ISSUES/207-a-re-made-worker-replayed-every-ask-the-stream-kept/00-report.md) — a remade worker replayed every ask
 - [to-be 18](../03-DESIGN/01-to-be/18-building-a-module.md) — the design this amends
@@ -1,161 +0,0 @@
 ---
 topic: what runs on it
 status: accepted
 date: 2026-10-05
 deciders: jochen
 reconstructed: false
 extends: 02-DECISIONS/0207-a-module-depends-on-the-node-seats-that-apply-its-resources.md
 ---
 # 220. What a machine asks needs its uplink held, and the retired resolver pieces go
 > **Decided to go — 2026-10-05, by [ADR 0223](0223-the-mesh-has-two-resolvers-and-a-machine-lists-only-them.md), not yet built.** `/etc/resolv.conf` becomes the `node-uplink`
 > holder's file, and `resolv-conf`, `node-resolver-config` and this record's dependency of it on
 > `node-uplink` retire with it. Until that is built, everything below stands as decided.
 ## Context
 **Three things about a machine's resolver were left half done when the mesh moved to one resolver.**
 On the production mesh on 2026-10-05, read from the controller's `seats` verb:
 - **`node-dns-resolver` has no holder on any node, and no module in the catalogue claims it.**
  [ADR 0194](0194-the-mesh-has-one-resolver-and-every-node-asks-it-for-the-meshs-names.md) retired it
  and the controller kept its row deliberately, *"deleted once nothing claims it"*, because removing a
  seat a machine still holds makes that machine unresolvable. That condition now holds. The row still
  stands in the controller's compiled set and in the store's seat table, and the overview still lists
  it, unheld, beside the seats a mesh actually has.
 - **The rule that keeps `/etc/resolv.conf` the mesh's is checked by nothing.**
  [ADR 0117](0117-a-machines-uplink-is-a-seat.md) found that a network manager rewrites the resolver
  file on every connectivity change unless it is told not to, and gave that telling to the module
  holding `node-uplink`. It said the condition *"only if NetworkManager runs"* is expressed by
  assigning the manager's module. Nothing makes anybody do so: `resolv-conf` can be assigned to a
  machine with no uplink holder, and the file is then replaced the first time a laptop changes
  network while every surface of the mesh reads green. Today every node holding
  `node-resolver-config` also holds `node-uplink` — NetworkManager on the home server, the
  workstation and the laptop, systemd-networkd on the anchor — by care, not by check.
 - **The catalogue still carries a systemd-resolved split-DNS module**, `resolved-split-dns`, claiming
  `node-resolver-config`. [ADR 0196](0196-a-node-asks-the-meshs-resolver-first-and-a-public-one-only-when-it-is-silent.md)
  chose against a stub on every node and says *"There is no `systemd-resolved` module."* It is
  assigned nowhere. `resolv-conf`'s own resolver file still tells its reader that systemd-resolved or
  NetworkManager may be assigned *instead* — the opposite of how the roles now divide.
 **A dependency mechanism already exists.** [ADR 0207](0207-a-module-depends-on-the-node-seats-that-apply-its-resources.md)
 made a module depend on the node seats that apply its resources, derived rather than stated, judged
 over the node's whole set of assignments, refused at `assign` naming the seat and its possible holders,
 and refused at composition. [ADR 0210](0210-a-tools-configuration-is-its-seat-holders-and-every-other-module-extends-it-through-the-seat.md)
 derived a second kind from contributions. What is missing is a dependency that belongs to a *role*
 rather than to what a module declares.
 ## Considered Options
 **For the retired seat:**
 1. **Keep the row until the build seat's retired row goes too, and delete both together.** Rejected:
   the two have nothing in common but having been retired; one is unclaimed now and the other is not
   yet known to be.
 2. **Remove it from the compiled set only.** Rejected: seeding adds a seat a release ships and never
   removes one ([ADR 0122](0122-a-seat-is-data-a-rename-is-a-database-update.md)), so the store's
   row, which is the live set, would stay.
 3. **Remove it from the compiled set and delete the store's row in a numbered migration**, as the
   artifact store's rename did for its old row. Chosen.
 **For the resolver file and the uplink:**
 1. **Leave it to the operator.** Rejected: it is the failure ADR 0117 describes — the file silently
   replaced — with the one difference that the operator was told.
 2. **`resolv-conf` declares the manager's settings itself.** Rejected by ADR 0117 already: which
   setting depends on which manager runs, and a resolver module that knew about network managers would
   be the wrong module knowing the wrong thing.
 3. **A manifest field in `resolv-conf` naming `node-uplink`.** Rejected for the reason ADR 0207
   rejected its own option 2: a second module claiming the same seat would have to restate it, and
   one that forgot would pass.
 4. **The seat carries what its holder needs beside it.** `node-resolver-config` names `node-uplink`;
   any module claiming the former depends on the latter, derived from the claim and judged exactly as
   ADR 0207 judges a resource's dependency. Chosen.
 **For the split-DNS module:** keep it for a machine that wants systemd-resolved in charge, or remove it.
 Kept, it is a second answer to a question ADR 0196 settled, and a claimant the catalogue offers
 without a record allowing it. Removed.
 ## Decision
 **1. `node-dns-resolver` is deleted from the mesh's set.** The controller's compiled set no longer
 carries it, and a numbered migration of the controller's store deletes its row and any alias naming
 it. No alias is kept: nothing was renamed, and a manifest still claiming it should be refused at
 registration, naming the seat. This completes ADR 0194's retirement; nothing it decided changes.
 **2. A seat may name the node seats its holder needs held on the same node.** A module claiming such a
 seat depends on each of them. The dependency is a third source beside ADR 0207's resources and ADR
 0210's contributions, and everything ADR 0207 §3 and §4 say of those applies unchanged: met by any
 module assigned to the node, the claimant included; judged over the node's whole set; refused at
 `assign` naming the seat and the catalogue's possible holders; refused at composition; and only said,
 never refused, when no module in the catalogue could hold the needed seat. Unassigning the needed
 seat's last holder beneath a dependent is refused, naming the dependent. What a seat needs is part of
 the mesh's definition of the role: compiled with the set, never stored, as ADR 0212 keeps what a seat
 receives. Adding a need to a seat is a decision, recorded.
 **3. `node-resolver-config` needs `node-uplink`.** The holder that writes the resolver file is right
 only while the network manager is told to leave it alone, and that telling is the uplink holder's
 (ADR 0117). Every manager the catalogue knows — NetworkManager, systemd-networkd, dhcpcd — holds
 `node-uplink`, so the refusal always has a remedy to name.
 **4. `resolved-split-dns` leaves the catalogue.** `resolv-conf` is the only module claiming
 `node-resolver-config`. Its resolver file's comment says the uplink's holder is required beside it,
 rather than naming alternatives to assign instead.
 ## Consequences
 - **The set reads as the mesh is.** Thirty-seven seats in the compiled set; the overview no longer
  lists a role nothing can fill.
 - **A machine cannot be given the mesh's resolver file without its network manager being told to keep
  off it.** A machine with no manager at all — a static configuration — needs the smallest holder,
  `dhcpcd`, or a new module holding `node-uplink` for its way of configuring the link. That is the
  point: such a machine has to say what manages its link before the mesh writes a file the manager
  could overwrite.
 - **Order of assignment on a new machine**: the uplink holder before or with `resolv-conf`, in one
  `assign` when together. On the production mesh nothing changes: every node already holds both.
 - **The uplink becomes harder to take away.** Unassigning a machine's manager module while
  `resolv-conf` stays is refused; replacing one manager with another is one act assigning the new and
  unassigning the old, or the dependent goes first.
 - **A machine wanting systemd-resolved has no module for it.** A future need for one is a new record,
  not a revival of the removed module.
 - **Changing `resolv-conf`'s comment rewrites `/etc/resolv.conf` on every node once**, with the same two
  nameserver lines and options; only the comment differs.
 - **The merge order matters.** The controller's tests read the catalogue beside them, and the two
  changes are judged together: the controller's change and the catalogue's removal merge together,
  the catalogue's first or in the same window, and the controller rolls out only once its test suite
  passes against the merged catalogue.
 ## How it is checked
 | Rule | Checked by |
 |---|---|
 | `node-dns-resolver` is not in the set, and the set has thirty-seven seats | mesh-controller's closed-set unit test on the compiled seats |
 | The store's row goes with it | the migration, and after rollout the controller's `seats` verb listing no `node-dns-resolver` |
 | `node-resolver-config` needs `node-uplink`, and a module claiming it depends on the uplink with nothing in its manifest | mesh-controller's seat-dependency tests on the seat definition and on a synthetic claimant |
 | What a seat needs survives loading the set from the store | a unit test loading the store's rows, which carry no such column |
 | `resolv-conf` without an uplink holder is refused at `assign`, naming `node-uplink` and its possible holders; beside one, or with one in the same act, it passes; a composition without one is refused | the same tests, and `assign` live |
 | Unassigning the uplink's last holder beneath `resolv-conf` is refused | an unassign test |
 | In the catalogue, `resolv-conf` depends on the uplink, dhcpcd, NetworkManager and systemd-networkd each hold it, and `resolv-conf` is the only claimant of `node-resolver-config` | a mesh-controller test reading the catalogue beside it |
 | Two modules deciding what a machine asks are still refused on one node | the resolver test, now with a synthetic second claimant |
 | Every node of the live mesh holding `node-resolver-config` also holds `node-uplink` | the controller's `seats` verb, read before this was decided and after it rolls out; `status` reports no unheld dependency |
 ## References
 - [ADR 0194](0194-the-mesh-has-one-resolver-and-every-node-asks-it-for-the-meshs-names.md) — retired
  `node-dns-resolver`; this record deletes it.
 - [ADR 0196](0196-a-node-asks-the-meshs-resolver-first-and-a-public-one-only-when-it-is-silent.md) — no
  stub, and so no systemd-resolved module.
 - [ADR 0117](0117-a-machines-uplink-is-a-seat.md) — the uplink's holder keeps the manager off the
  resolver file; this record makes that a checked dependency.
 - [ADR 0121](0121-a-system-seat-is-named-for-its-scope-and-modules-define-their-own.md) — serving and
  asking as two seats.
 - [ADR 0207](0207-a-module-depends-on-the-node-seats-that-apply-its-resources.md),
  [ADR 0210](0210-a-tools-configuration-is-its-seat-holders-and-every-other-module-extends-it-through-the-seat.md) — the dependency mechanism
  this extends.
 - [ADR 0122](0122-a-seat-is-data-a-rename-is-a-database-update.md) — the set as data, which is why a
  deletion is a migration.
 - [The seats](../03-DESIGN/01-to-be/26-the-seats.md) and
  [connectivity §2](../03-DESIGN/01-to-be/08-connectivity.md), amended alongside.
 - mesh-controller `internal/catalogue/seats.go`, `internal/catalogue/seat_dependencies.go`, and the
  store migration deleting the row; mesh-catalog `modules/resolv-conf`.
@@ -1,129 +0,0 @@
 ---
 topic: the mesh
 status: accepted
 date: 2026-10-05
 deciders: jochen
 reconstructed: false
 extends: 02-DECISIONS/0083-one-push-leaves-the-mesh-consistent.md
 ---
 # 221. A push sends no build a policy or a plan holds back, except to the machine it names
 ## Context
 [ADR 0083](0083-one-push-leaves-the-mesh-consistent.md) makes a named push finish what it starts. After
 the named machine is sent, every other machine whose declaration differs from what it was last sent is
 sent too. The case it was written for is a grant: assigning a consumer changes the provider's
 declaration on another machine. ADR 0083 accepted that a machine behind *for an unrelated reason* is
 flushed as well, and called that correct rather than a cost.
 On 2026-10-05 that reasoning met an upgrade policy
 ([issue 259](../04-ISSUES/259-a-named-push-sent-every-machine/00-report.md)). A change to the resolver
 modules was merged with the policy `record`, so that each machine would take it only when pushed, one
 at a time: the anchor first, each checked before the next. `push <anchor>` sent all four machines the
 new build, and so did a later `push <laptop>`. A fault in the change
 ([issue 260](../04-ISSUES/260-the-resolver-started-before-its-zones-file-existed/00-report.md)) was met
 on every machine at once.
 The cascade compares one digest per machine, and a digest cannot say why a machine differs. Under
 `record`, every machine running the module differs from the merge on, so every machine is flushed. The
 same holds for a plan's rollout under [ADR 0218](0218-a-plan-sends-grants-before-code-rolls-out-one-machine-first-and-a-newer-merge-takes-over-an-older-plan.md):
 while the plan waits on its first machine, the rest differ, and any named push elsewhere sends them the
 build the plan is holding. [Issue 249](../04-ISSUES/249-a-modules-new-state-is-refused-until-a-push-the-merge-did-not-make/00-report.md)
 met the same confusion for the machine holding the bus, which a send adds when its user list changed.
 It narrowed that check to the user list, but the machine, once added, is still sent its whole
 declaration.
 So `record` held a change back from nothing but the merge, and "one machine first" held it back only
 from the plan's own sends.
 ## Considered Options
 1. **Report instead of cascade:** list every machine that is behind and send none. Rejected: it is the
   option ADR 0083 rejected, and for the same reason. [Issue 057](../04-ISSUES/057-a-cross-node-consumer-is-provisioned-only-when-the-provider-is-pushed-again/00-report.md)'s provider would wait for a second push
   nothing tells anyone to make.
 2. **Send a held machine its consequences and keep its held modules at their last build.** The cascade
   would compose the machine with each held module pinned at the build it was last sent, so a grant
   still reaches it and the upgrade does not. Rejected: the catalogue resolves every machine against
   one manifest per module, the current one. Pinning means resolving a machine's set against a mix of
   current and older manifests, read back from the build records, beside the current settings, seats
   and grants. The result matches neither what the machine runs nor what the mesh would send it, so
   neither `plan` nor `status` could show it. A grant composed for the new build may not fit the old
   one. It is a second composition path to get one edge case right, and the edge case has a one-word
   remedy: name the machine.
 3. **Keep, with every send, which build of each module the machine was sent, and leave a machine any
   of whose modules a policy or a plan holds back.** Chosen.
 ## Decision
 **1. A send records the builds it carried.** With the digest of every declaration it sends, the mesh
 keeps which build of each module the declaration carried: the commit the module's current build was
 made from. A module left out of the declaration keeps the build it was last sent. A declaration sent by
 hand records that what it carried is not known.
 **2. A push does not send a machine it did not name a held build.** A machine reached by a named push's
 cascade, or added because it holds the bus, is not sent when any module it runs would move to a build
 that:
 - its upgrade policy records rather than rolls out, or
 - an open plan has not yet sent it: the plan is still building the module, or has sent it to its first
  machine and this is not that machine.
 A module the machine was never sent counts as a move. A machine whose last send's builds are not known
 counts as held. It was sent before this was kept, or by hand, so a held upgrade cannot be told apart
 from anything else.
 **3. It is named, not hidden.** The push says which machine it left, which module and which builds, why,
 and that `push <node>` sends it. For the machine holding the bus it also says that the bus may refuse
 what this push's machines were newly granted until that machine is sent.
 **4. Everything else stays as it is.** A machine with nothing held is flushed exactly as ADR 0083
 decides: a grant, a peer, a setting. The machine a push names is sent everything, held builds included.
 A push that names no machine sends every machine. `push --behind` still sends every machine that is
 behind, held or not. It is the remedy `record` names when an upgrade is announced ("`push --behind`
 when you want them"), and the one command for taking a recorded upgrade everywhere. Narrowing it would
 leave `record` with no way to say "now".
 > **The mechanism changed — 2026-10-06, by [ADR 0236](0236-a-build-is-judged-on-its-first-machine-and-put-back-by-something-other-than-itself-and-so-it-rolls-out-unattended.md).** What still stands: a send records
 > the builds it carried, a held machine is left and named, the named machine is sent everything, and
 > `push --behind` takes a recorded upgrade everywhere. What moved: `record` is no longer the default — a
 > build rolls out one machine first, gated, unless a person, the module, its irreplaceable data or the bus
 > says otherwise — and one case of "the machine a push names is sent everything" is refused: a machine
 > whose bus would move, which is replaced only as the planned step `bus upgrade`.
 ## Consequences
 - `record` and "one machine first" hold a change back from every push that does not name the machine.
  Walking a change through the mesh is `push <anchor>`, check, `push <next>`.
 - **The cost:** a held machine that is also owed a grant from this push waits for its own push. The
  provider in issue 057's case, if a held upgrade is pending on it, is not sent its new grant, and its
  consumer is refused until the provider is pushed. The push names that machine and the remedy, so the
  wait is announced, not silent. When the holder of the bus is held, a new grant may be refused by the
  bus until it is sent, and the push says so.
 - On the first push after this ships, no machine's last send has its builds recorded yet. Each is held
  from cascades until it is pushed once: by name, in a whole-mesh push, or by `push --behind`.
 - A manifest handed over by hand does not change the commit a module records, so a cascade still sends
  its change. Only builds have a commit to compare.
 - ADR 0083's consequence that a machine behind for an unrelated reason is flushed is narrowed. It still
  holds for every reason except a build held back.
 ## How it is checked
 | Rule | Checked by |
 |---|---|
 | a send records the builds it carried, and "not known" | the controller's test: the builds kept with a send round-trip, an empty send is known and empty, a send by hand reads as not known |
 | a left-out module keeps its last build | the controller's test: a module left out of a declaration records the build it was last sent |
 | a recorded upgrade holds a machine a push did not name | the controller's test: with a module under `record` moved, the cascade of a push naming the anchor leaves the laptop's last send unchanged and names it, the module, both builds and `push laptop` |
 | held and owed something else: not sent, both said | the same test: a newly placed machine changes the laptop's peers while the upgrade is held; the laptop is not sent and the output says why and that what else it is owed waits |
 | a roll-out policy is not held | the same test: with the policy set to roll out, the laptop is sent and its new build recorded |
 | a consequence nothing holds is still sent (issue 057) | the controller's test: a placed machine's peers reach the others by cascade; a machine whose last send is not known is held |
 | a plan waiting on its first machine holds the rest | the controller's test: a machine the plan has not reached is held, the first machine is not; a module sent everywhere, failed, or in a closed plan holds nothing |
 | live | the next change merged under `record`: `push <anchor>` sends the anchor alone and names every other machine running the module |
 ## References
 - [Issue 259](../04-ISSUES/259-a-named-push-sent-every-machine/00-report.md), [issue 260](../04-ISSUES/260-the-resolver-started-before-its-zones-file-existed/00-report.md), [issue 249](../04-ISSUES/249-a-modules-new-state-is-refused-until-a-push-the-merge-did-not-make/00-report.md)
 - [ADR 0083](0083-one-push-leaves-the-mesh-consistent.md): the cascade, narrowed here
 - [ADR 0218](0218-a-plan-sends-grants-before-code-rolls-out-one-machine-first-and-a-newer-merge-takes-over-an-older-plan.md): one machine first, now held from a push as well
 - [ADR 0010](0010-delivery.md): delivery, and what `push --behind` answers
 - [to-be 30](../03-DESIGN/01-to-be/30-the-mesh-updates-itself-on-a-push.md): the design this amends
@@ -1,150 +0,0 @@
 ---
 topic: the mesh
 status: accepted
 date: 2026-10-05
 deciders: jochen
 reconstructed: false
 extends: 02-DECISIONS/0082-the-registry-is-reached-by-name-and-trusted-by-the-overlay.md
 ---
 # 222. A module is told where a mesh seat's holder is reached, and the controller writes no file a seat's holder owns
 ## Context
 [Issue 190](../04-ISSUES/190-the-runtimes-configuration-is-written-by-modules-that-are-not-the-runtime/00-report.md)
 found the container runtime's configuration file written by modules that are not the runtime's. The
 first half is closed: the resolver module no longer writes into that file, and the catalogue's runtime
 module (the holder of `node-container-runtime`) writes `live-restore` and reloads its own service. The
 second half stands. The controller's private network still generates two resources on every machine
 on the network: one writes `insecure-registries`, naming the mesh's artifact store, into the runtime's
 file ([ADR 0082](0082-the-registry-is-reached-by-name-and-trusted-by-the-overlay.md) §2,
 [ADR 0102](0102-the-mesh-writes-into-a-shared-file-never-over-it.md)), and the other declares the
 runtime's service, reloaded on that file. So two parties declare one path and one unit on every
 machine, and nothing refuses it, because the collision check runs over catalogue manifests and the
 private network's resources only exist once its generator has answered for a machine.
 On 2026-10-05 the operator made the rule general: **the controller never writes a file a seat's holder
 owns; it tells the owner.** The hosts file had already moved the same way
 ([ADR 0199](0199-a-module-that-answers-names-declares-its-zone-and-a-nodes-hosts-file-is-one-modules.md)).
 What the runtime's module needs is one fact: the address this machine reaches the mesh's artifact
 store at. The controller already composes that address for every machine at every push. It puts it
 into every image and archive reference the mesh built, and never stores it. Today a module has no way
 to ask for it. A binding gives a consumer the provider's address and a credential. The `${seat:…:<port>}`
 placeholder gives only a port, and only for the store and the broker the controller itself dials.
 Two facts about the move itself, read from the host's code:
 - The private network writes one member into a list. The host adds a list member and records it per
  resource, so between the two writers declaring it and one of them going, the member is owned by
  whichever record added it first.
 - The host removes every resource no longer declared before it applies anything, so in the apply
  where the private network's record goes and the runtime module's member arrives, the member leaves
  and comes back with no reload in between.
 ## Considered Options
 1. **Keep the private network writing the trust.** Rejected: it is the defect issue 190 names. Three
   writers became two, and the second is computed code no check can see.
 2. **An operator setting on the runtime module naming the registry**, as issue 190 first proposed
   under [ADR 0164](0164-a-setting-is-declared-with-its-default-its-meaning-and-what-changing-it-costs.md).
   Rejected: where the store is, is a fact the mesh holds, not a choice an operator makes. A setting
   would be a copy that goes wrong the day the store moves.
 3. **The runtime module requires `artifact-store` and reads the address from its binding
   (`${bound:…}`).** Rejected. A binding makes the module the store's consumer, and that mints a
   credential for every machine's runtime, which needs none: reading from the store needs presence on
   the private network and nothing else (ADR 0082 §3). It also makes a cycle: the store runs as a
   container in the runtime, and the runtime would require the store before it could be assigned.
 4. **A placeholder that answers where a mesh seat's holder is reached, with no binding.** Chosen. It
   is the reasoning of `${seat:…:<port>}` taken one step further: nothing is required, nothing is
   granted, and the answer is an address the mesh already holds in the clear.
 ## Decision
 **1. `${seat:<mesh seat>:reach}` is where this machine reaches the holder of a seat the mesh holds once,
 as host:port.** It is filled where every placeholder is, in a file's content and in an environment
 value, from the address the controller composes for that machine at that push. It requires nothing
 and grants nothing, and no credential comes with it.
 - **Only `mesh-artifact-store` is answered.** Another seat is refused by name, never answered with
  nothing, so a module asking a question the mesh does not answer learns that at composition. A seat
  is added to what is answered by a record saying why its address is needed.
 - **The answer may be empty**: no machine on the private network holds the seat yet, which is how
  genesis begins. In a file written into as JSON, an empty member is dropped from its list, and a list
  left with no members is dropped, so the software is never told an empty name.
 **2. The runtime's module states the registry's trust.** Its `daemon` resource writes
 `insecure-registries`, naming `${seat:mesh-artifact-store:reach}`, beside `live-restore`, and it
 reloads its own service. ADR 0082's decision stands: being on the private network is what grants the
 trust, the private network is the transport security, and no module author chooses it. Only who writes
 it moves, from the private network to the runtime's module.
 **3. The controller writes no file a seat's holder owns.** The private network generates neither the
 runtime's file nor its service.
 **4. What the mesh computes is held to the collision check.** At composition, each computed module's
 resources, as its generator answers for that machine, are checked beside the other modules' resources.
 The check is the same one: no two modules on a machine declare one path, unit, name or package. A
 collision is refused by name. The generator is asked once, and what is checked is exactly what is
 declared.
 **5. A unit still held is not given back when another record of it goes.** When the host removes a
 service resource whose unit another declared resource still gives a state, it forgets that record and
 leaves the unit as it is. What the record going had found is not the machine's to restore while
 another resource holds the unit, and restoring it could stop the runtime only for the remaining
 resource to start it again in the same apply.
 ## Consequences
 - **Rollout has a fixed order, in three steps.**
  1. The controller learns the placeholder. Nothing uses it yet.
  2. The catalogue's runtime module uses it. A controller that does not know the placeholder would
     send it through unfilled, so this waits until step 1 is deployed.
  3. The controller stops generating the private network's two resources and checks generated
     resources for collisions. With step 3 before step 2, machines would lose the trust. The host
     change in Decision 5 is deployed before step 3.
  This replaces issue 190's single push. That was needed when two writers of one scalar key would
  have been refused. A list member written by two records is tolerated by the host.
 - **In the apply of step 3**, the private network's records go first: the member leaves the list and
  the service record is forgotten. Then the runtime module's file is applied, and the member is added
  back, recorded as the runtime module's. The runtime is reloaded once. The address is unchanged, so
  the trust never lapses for a pull.
 - **A machine holding the store, before any network exists**, is answered with the loopback address
  it reaches the store at. A runtime already trusts loopback, so this adds a redundant member, not a
  wrong one.
 - **A second writer cannot return through generated code.** It is refused at composition, naming
  both modules and what they share.
 - **A module can now learn where the artifact store is without being its consumer.** That is a
  capability, and it is bounded: one seat today, and widened only by a record.
 ## How it is checked
 | Rule | Checked by |
 |---|---|
 | `${seat:mesh-artifact-store:reach}` is filled with this machine's address for the store, in a file and in an environment value | mesh-controller `TestASeatsReachIsWhereThisMachineReachesItsHolder`, and through the whole composition `TestTheRuntimesTrustIsComposedFromTheSeatsReach` |
 | An empty answer adds nothing to a list, and other members stay | mesh-controller `TestAnUnansweredReachAddsNothingToAList` |
 | Any other seat is refused by name | mesh-controller `TestAReachTheMeshDoesNotAnswerIsRefused` |
 | The catalogue's runtime module writes `live-restore` and the trust, and writes no trust when no store is reachable | mesh-controller `TestTheRuntimesModuleTrustsTheMeshsRegistry`, which composes the catalogue's manifest beside it |
 | The private network declares neither the runtime's file nor its service | mesh-controller `TestTheNetworkWritesNothingOfTheRuntimes` |
 | A generated resource colliding with a module's is refused by name; disjoint ones compose; the generator is asked once | mesh-controller `TestAGeneratedResourceCollidingWithAModulesIsRefused`, `TestAGeneratedResourceBesideAModulesOwnIsComposed`, `TestAComputedModuleIsAskedAboutTheNodeItIsFor` |
 | The member moves between records in one apply without leaving the list; one reload; a unit still held is forgotten, never stopped or disabled; the plan says so | mesh-host `TestTheRegistryMovesToTheRuntimesModuleWithoutLeavingTheList`, `TestThePlanForgetsARecordOfAUnitStillHeld` |
 | After rollout, every machine's runtime trusts the store's address | the runtime module's `docker_daemon_config` tool on each machine, read before step 3 and after it |
 ## References
 - [Issue 190](../04-ISSUES/190-the-runtimes-configuration-is-written-by-modules-that-are-not-the-runtime/00-report.md),
  steps 2 and 5.
 - [ADR 0082](0082-the-registry-is-reached-by-name-and-trusted-by-the-overlay.md): the trust and why it
  is plain HTTP; its mechanism moves here.
 - [ADR 0102](0102-the-mesh-writes-into-a-shared-file-never-over-it.md): writing into a shared file;
  its writer of the runtime's trust moves here.
 - [ADR 0079](0079-the-foundation-seats-are-named-after-their-servers.md): a mesh seat names the
  server, which is what lets a placeholder ask about it.
 - [ADR 0166](0166-the-container-runtime-is-a-node-seat-and-the-host-creates-containers-through-its-holder.md):
  the runtime module given the registry as a value.
 - [ADR 0199](0199-a-module-that-answers-names-declares-its-zone-and-a-nodes-hosts-file-is-one-modules.md):
  the hosts file left the controller the same way.
 - mesh-controller `internal/catalogue/seat_into.go`, `internal/catalogue/declaration.go`
  (`generatedHere`), `internal/overlay/generator.go`; mesh-catalog `modules/docker`; mesh-host
  `internal/apply/apply.go` (orphan removal).
@@ -1,211 +0,0 @@
 ---
 topic: the tiers
 status: accepted
 date: 2026-10-05
 deciders: jochen
 reconstructed: false
 supersedes-in-part:
  - 0196-a-node-asks-the-meshs-resolver-first-and-a-public-one-only-when-it-is-silent.md
 extends: 02-DECISIONS/0194-the-mesh-has-one-resolver-and-every-node-asks-it-for-the-meshs-names.md
 ---
 # 223. The mesh has two resolvers, and a machine lists only them
 ## Context
 **[ADR 0196](0196-a-node-asks-the-meshs-resolver-first-and-a-public-one-only-when-it-is-silent.md) wrote
 every machine's `/etc/resolv.conf` as the mesh's resolver first and a public resolver second.** Its
 reasoning is the C library's: servers are asked in order, the next only when one does not answer, and
 an answer from the first — "no such name" included — is final. That holds for glibc. It does not hold
 for musl, the C library of every Alpine image: musl sends the query to every listed server at once
 and takes the first reply.
 **On the production mesh on 2026-10-05 that made the anchor's own name unresolvable from the home
 server's builds.** The build agent on the home server runs its steps in Alpine containers on the host
 network, so they read the machine's `resolv.conf` as it is. Asked for `<anchor>.internal`, the public
 resolver — which has no such name and is the nearer of the two — answered NXDOMAIN first, and musl
 took it. Reproduced six times out of six inside the build agent's own container; every build on that
 machine failed fetching from the anchor. The same lookup from glibc on the same machine answered every
 time. [Issue 262](../04-ISSUES/262-an-alpine-container-could-not-find-a-machine-by-its-mesh-name/00-report.md)
 was the same library failing on a different answer (NXDOMAIN for a missing IPv6 record); fixing that
 did not touch this one, because here the wrong answer comes from a server that should never have been
 asked.
 **The public line was there for one case: the mesh's resolver unreachable.** ADR 0196 kept public
 names resolving with the anchor down, the tunnel down, or a laptop behind a captive portal. That case
 is real and rare; the musl case is every lookup of a mesh name from every Alpine container on any
 machine that is not the anchor.
 **A seat's work can already be shared by several holders.** [ADR 0190](0190-a-seats-work-is-shared-by-its-holders-and-building-is-the-first-such-role.md)
 made the build role node-scoped with every holder pulling from one queue. A mesh-scoped seat has
 always had exactly one holder: by derivation, or on record since
 [ADR 0131](0131-everything-on-the-mesh-speaks-to-the-broker-seat.md), where a handover replaces the
 holder in one write and every other eligible assignment stands beside it, silent.
 ## Considered Options
 1. **The mesh's resolver alone.** Every mesh name and every public name answered consistently, by one
   server. Rejected alone: with the anchor down, no machine resolves anything — the reason ADR 0194
   gave against it, and still true.
 2. **A local forwarder on every machine** — a small resolver on loopback that asks the mesh's resolver
   for the mesh's suffix and public resolvers for the rest, with `resolv.conf` naming only it. Rejected:
   it is ADR 0194's per-node stub again, which ADR 0196 removed — a daemon and a module on every node,
   and a container cannot use a loopback resolver, so containers would need a second configuration.
   Every resolution fault found on 2026-10-03 was a per-node copy disagreeing with the truth.
 3. **Split by kind of machine** — servers list the mesh's resolver alone, laptops keep a public
   fallback. Rejected: a laptop runs Alpine containers too, and a rule that differs by machine is a
   rule nobody can state about the mesh.
 4. **Two mesh resolvers, and nothing else listed.** The same module, the same roster and the same zones
   on two machines, and every machine lists both. Whichever answers first gives the same answer, so
   musl's race is harmless; a public name still resolves through either. Chosen.
 ## Decision
 **1. Now: the mesh has two resolvers.** The seat `mesh-dns-resolver` may be held on more than one
 machine — the anchor and the home server — each holder answering the same mesh names: the same
 module, the same machine list, the same zones, rendered by the controller into each.
 - **A seat may be replicated.** It is an attribute of the seat in the mesh's definition, compiled with
  the set and never stored, as what a seat needs ([ADR 0220](0220-what-a-machine-asks-needs-its-uplink-held-and-the-retired-resolver-pieces-go.md))
  and what it receives are. `mesh-dns-resolver` is the only replicated seat. Making another one is a
  decision, recorded. In the glossary's words it is the mesh's first **bench** — a seat whose
  holders coexist — and *replicated* says what kind: every holder answers the same thing.
 - **Every holder is on record, and each is added by an act**: `seat mesh-dns-resolver --add
  <node>/<module>` records one more holder beside those on record. Assigning the module is not enough:
  an assignment not on record stands beside the holders, eligible and silent, exactly as ADR 0131 says,
  and two claimants with nothing on record are refused as for any mesh seat. `--to` still hands the
  seat over, leaving exactly one holder. `--add` on a seat held once is refused, naming `--to`.
 - **One per machine still**: two modules on one machine claiming it are refused. And a seat held once
  stays held once: a second claimant on another machine is refused while nothing is on record, and a
  store recording two holders of such a seat is refused, naming the seat.
 - **Every machine's `/etc/resolv.conf` lists every holder's private address, the holder on the machine
  itself first if it is one, then the rest in name order, and no public resolver.** The controller
  gives a module's roster template the holders of each replicated seat, ordered so; the module holding
  `node-resolver-config` writes the file from it. On a holder, its own private address is first: the
  resolver listens there and on loopback, and the private address is the one a container on that
  machine can reach.
 - **The requirement stays.** What writes the file still requires `wildcard-resolution`, so a machine is
  refused when nothing in the mesh resolves, rather than given a file listing nothing. A holder answers
  its own requirement; any other machine is bound to the first holder by name. Nothing reads that
  binding's address any more — the file lists every holder — and the binding is kept for the refusal
  and the order of delivery.
 **2. Next, decided and not yet built: `/etc/resolv.conf` belongs to the uplink's holder.** The program
 that manages the machine's network already has to be told to keep off the file
 ([ADR 0117](0117-a-machines-uplink-is-a-seat.md)); instead, the `node-uplink` holder writes it, given
 the resolvers by the mesh: NetworkManager through its global DNS configuration, dhcpcd through static
 nameservers, and systemd-networkd's module declaring the file itself. `resolv-conf` and the seat
 `node-resolver-config` then retire, and ADR 0220's dependency of `node-resolver-config` on `node-uplink`
 goes with them. One owner for the file, and it is the program that would otherwise rewrite it.
 > **Progressive insight — 2026-10-05.** Built, the managers' own mechanisms turned out not to write
 > the mesh's file: NetworkManager's global DNS configuration and dhcpcd's resolv.conf hook each write
 > `/etc/resolv.conf` in their own form — their own header, their own options line — and dhcpcd reads
 > its configuration only at its next start, so a change of resolvers would wait for one. The record
 > said NetworkManager and dhcpcd would be given the resolvers "through its global DNS configuration"
 > and "through static nameservers"; instead every one of the three modules declares the file itself,
 > from one template, and keeps its manager off it as before (`dns=none`, `nohook resolv.conf`, and
 > nothing for systemd-networkd). The decision — the uplink's holder owns the file, and `resolv-conf`,
 > `node-resolver-config` and ADR 0220's dependency retire — stands. How parts 2 and 3 are checked is
 > in [connectivity §2](../03-DESIGN/01-to-be/08-connectivity.md).
 > **The mechanism changed — 2026-10-07, by ADR 0247.** On a machine where a module holds the node seat
 > `node-resolver`, which is only where something requires `split-dns` (a VPN client that writes this
 > file itself), that module writes `/etc/resolv.conf` naming the machine's own resolver, and the uplink's
 > holder steps back from the file ([ADR 0247](0247-a-machine-with-a-vpn-client-routes-names-by-domain-through-a-resolver-of-its-own.md)). That resolver asks the
 > mesh's two resolvers for every name but the VPN's own domains. Everywhere else the uplink's holder writes
 > the file as decided here.
 **3. Next, decided and not yet built: a machine's names are one seat's.** `/etc/hosts` and
 `/etc/hostname` belong to one seat for the machine's identity. The `hosts` module, holding
 `node-hosts-file` ([ADR 0199](0199-a-module-that-answers-names-declares-its-zone-and-a-nodes-hosts-file-is-one-modules.md)),
 is renamed **`hostname`** and holds the seat renamed **`node-hostname`**; it writes `/etc/hostname`
 and the machine's own `127.0.1.1` line, and keeps every operator's line as ADR 0199 does today.
 - **Why one seat for both files**: the mesh's only content in `/etc/hosts` is the machine's own name,
  and nothing owns `/etc/hostname` today. Two files saying one fact belong to one owner.
 - **Why `node-hostname`**: a system seat is named `node-` for its scope and then for its role
  ([ADR 0121](0121-a-system-seat-is-named-for-its-scope-and-modules-define-their-own.md)), and the role
  is the machine's name. `node-identity` was considered and rejected: a machine's identity in the mesh
  already means its key and certificate. `node-host` was rejected for the reason the module name
  `host` was: "the host" is what the [node-engine](../00-META/glossary.md) was called until now, and
  its repository and binary still carry `mesh-host`.
 - **Why a module and not part of the node-engine**: the node-engine applies every module's resources
  and owns no file's content; every file it writes belongs to the module that declared it. A file's
  content belongs to a seat's holder, and a seat's holder stays replaceable — another module can hold
  `node-hostname` on a machine that names itself another way, and the node-engine does not change.
 - The rename goes through the seat set's rename (an alias keeps `node-hosts-file` resolving,
  [ADR 0122](0122-a-seat-is-data-a-rename-is-a-database-update.md)), so nothing claiming the old name
  breaks in between.
 ## Consequences
 - **musl and glibc agree.** Every listed server answers a mesh name the same way, so the race musl
  runs has one possible outcome; a public name resolves through either holder's upstreams.
 - **Accepted cost: with no mesh resolver reachable, a machine has no DNS at all** until it can reach
  one. The anchor is the hub of the private network, so with it down the private network is down too,
  and the second resolver is reachable only on its own machine and from machines on its own LAN. The
  mesh assumes the anchor is up about 99.9% of the time. The same holds for a laptop behind a captive
  portal that keeps the tunnel down: it resolves nothing, the portal's own name included, until the
  tunnel is up.
 - **The resolver's options change from one attempt to two**, one second each. With no public resolver
  to fall back to, a single dropped datagram would otherwise fail a lookup on a machine that reaches
  only one resolver.
 - **Holdings are keyed by seat and assignment.** The store's holding table takes a numbered migration;
  every existing row is one per seat and satisfies the new key. A handover replaces every holder in one
  transaction.
 - **Unassigning a holder takes its own row only**: the other resolver keeps holding. Removing the
  second resolver is unassigning it, then `push --behind`.
 - **The rollout order matters.** The controller that knows replicated seats and renders the holders
  rolls out first; the catalogue's `resolv-conf`, which reads the holders, second — a controller without
  them cannot render it; and only then is the second holder added, because an older `resolv-conf`
  reading its one binding would name the first holder by name order, which may be the new one, and
  still list the public resolver.
 - **A container keeps the resolvers it started with.** A container on the default bridge copies its
  machine's `resolv.conf` when it starts; one on a user-defined network is answered by the runtime's
  embedded resolver, which forwards to the servers it read at start. Either keeps the public resolver
  until restarted.
 - **Parts 2 and 3 change who writes two files on every machine**, each a handover between modules on
  the same path; they wait for their own build handoff.
 ## How it is checked
 | Rule | Checked by |
 |---|---|
 | `mesh-dns-resolver` is replicated, and no other seat is; it survives loading the set from the store | mesh-controller unit test over the compiled set and over a store row without the attribute |
 | Two holders on record compose on both, with no refusal, and each lists itself first | mesh-controller resolution and composition test with the catalogue's `dnsmasq` and `resolv-conf` |
 | A machine holding no resolver lists both holders, by name, and no public resolver | the same test on a third machine, asserting no public address appears |
 | A holder answers its own requirement although another holder sorts first | a resolution test on the second holder (issue 258's case kept) |
 | A seat held once still refuses a second claimant, and refuses two holders on record | resolution tests on `mesh-store` |
 | Two claimants of the replicated seat with nothing on record are refused, naming the handover | a resolution test |
 | Every consumer is bound to the same holder whatever order the mesh was resolved in | a unit test on the holder among providers |
 | The store keeps several holders of one seat, once each; a handover leaves one; unassigning takes only its own row | a store test against a live database, through the migration |
 | `seat --add` is refused for a seat held once | the controller's `seat` command |
 | The resolver's machine list has one host record per machine (issue 262's missing check) | a mesh-controller composition test counting host records |
 | `resolv-conf` lists only the seat's holders, with two short attempts | a mesh-controller test reading the catalogue's `resolv-conf` |
 | Live: every machine's `/etc/resolv.conf` lists both holders' private addresses, its own first on a holder, and nothing else; an Alpine container on the host network of the home server resolves `<anchor>.internal` every time | after rollout, read through each machine's tools, and `getent hosts` in an Alpine container repeated ten times |
 | Parts 2 and 3 | not yet built; their checks are written with their handoff |
 ## References
 - [ADR 0194](0194-the-mesh-has-one-resolver-and-every-node-asks-it-for-the-meshs-names.md) — the
  mesh's resolver; now held on two machines, each holding every node's internal domain.
 - [ADR 0196](0196-a-node-asks-the-meshs-resolver-first-and-a-public-one-only-when-it-is-silent.md) —
  replaced in part: its public resolver second goes. Every node and container asking the mesh's
  resolvers for every name, with no stub and no runtime `dns`, stands.
 - [ADR 0190](0190-a-seats-work-is-shared-by-its-holders-and-building-is-the-first-such-role.md) —
  several holders sharing a role, for a node seat.
 - [ADR 0131](0131-everything-on-the-mesh-speaks-to-the-broker-seat.md) — holders on record, handover,
  eligible and silent.
 - [ADR 0220](0220-what-a-machine-asks-needs-its-uplink-held-and-the-retired-resolver-pieces-go.md) — the
  uplink's dependency, which part 2 retires.
 - [ADR 0117](0117-a-machines-uplink-is-a-seat.md), [ADR 0199](0199-a-module-that-answers-names-declares-its-zone-and-a-nodes-hosts-file-is-one-modules.md),
  [ADR 0121](0121-a-system-seat-is-named-for-its-scope-and-modules-define-their-own.md),
  [ADR 0122](0122-a-seat-is-data-a-rename-is-a-database-update.md).
 - [Issue 258](../04-ISSUES/258-every-machine-bound-the-resolver-to-itself/00-report.md),
  [issue 262](../04-ISSUES/262-an-alpine-container-could-not-find-a-machine-by-its-mesh-name/00-report.md).
 - [Connectivity §2](../03-DESIGN/01-to-be/08-connectivity.md) and [the seats](../03-DESIGN/01-to-be/26-the-seats.md),
  amended alongside.
 - mesh-controller `internal/catalogue/seats.go`, `resolve.go`, `roster.go`,
  `cmd/mesh-controller/seats.go`, `holdings.go`, and the store migration keying a holding by seat and
  assignment; mesh-catalog `modules/resolv-conf`, `modules/dnsmasq`.
@@ -1,141 +0,0 @@
 ---
 topic: the mesh
 status: accepted
 date: 2026-10-06
 deciders: jochen
 reconstructed: false
 extends: 02-DECISIONS/0040-what-a-module-is.md
 ---
 # 224. A provider that keeps failing a consumer is a problem the controller reports
 ## Context
 **A provider's provisioner is the only thing in the mesh that knows whether a provision was made.**
 The controller composes a grant, delivers the contributions file and the minted secret, and the node
 reports that it applied every resource. Whether the provider then made the consumer's database, client
 or bucket is known to the provisioner loop alone ([ADR 0040](0040-what-a-module-is.md),
 [ADR 0048](0048-a-provider-creates-the-credential-the-mesh-minted.md)), and until now it
 said so only in its own journal.
 **On 2026-10-05 that cost a day.** The identity provider's database was moved that morning. Its
 realm's administrator kept the password it had before, the module's minted one was inert, and its
 provisioner failed every consumer every five seconds — about 31,000 refused logins from shortly after
 midnight until it was repaired by hand that night. Every surface the mesh has said the mesh was well:
 the machines applied what they were sent, the modules were current, `status` printed its all-well
 sentence. The same fault had been found and repaired by hand four days earlier
 ([issue 179](../04-ISSUES/179-an-adopted-identity-providers-admin-never-took-the-minted-secret/00-report.md)).
 [Issue 145](../04-ISSUES/145-a-machine-reads-healthy-while-its-modules-cannot-reach-each-other/00-report.md)
 already taught that "the mesh and the machines agree" is not "it works", and `status` says so under its
 all-well line. This is the narrower, checkable half of that gap: not whether a consumer can reach its
 provider, which only dialling answers, but whether the provider has told the mesh it cannot do its job.
 ## Considered Options
 1. **Leave it to the journal, and to a person reading it.** Rejected: that is what happened, twice.
 2. **The controller dials every provision.** Rejected for now: it is issue 145's open question, it
   needs the controller to hold or borrow every consumer's credential, and it would still not say
   *why* a provider fails.
 3. **The provider reports its standing through the node's report.** Rejected: the node-engine applies
   resources and knows nothing of what a module's code does after it starts; the provisioner runs in the
   node's tool runtime, which speaks to the bus, not to the host.
 4. **The provider announces, as an event, a consumer it keeps failing; the controller keeps the newest
   word and `status` names it.** Chosen.
 ## Decision
 **1. A provider announces a consumer it keeps failing.** When a provisioner has failed one consumer —
 its create, its periodic check, or reading the consumer's minted secret — for five minutes without a
 single success in between, it emits `provisioner.failing`, naming the consumer, the consumer's
 machine, the provision, the class of error and the error's first words, since when, and how many
 attempts. It says it again every fifteen minutes while it lasts. The first success after that is
 `provisioner.recovered`; so is a consumer the mesh stopped asking for, and so is the first success
 for each consumer after the provider starts, because a provider restarted after announcing a failure
 has forgotten it.
 - **The classes** are `credentials-rejected`, `unreachable`, `secret-unreadable` and `refused` (any
  other refusal), read from the error's words unless the provider's own code classes it better. They are
  what a person reading `status` needs before opening the journal.
 - **No secret travels.** The error is the provider's own text with the consumer's password removed, as
  its log line already is.
 > **The mechanism changed — 2026-10-06, by [ADR 0230](0230-a-consumer-the-mesh-stops-asking-for-is-retired-and-deleted-only-by-a-person.md).**
 > What stands: a consumer the mesh stopped asking for is announced recovered. What moved: a consumer the
 > provider still holds is no longer withdrawn on the first pass that misses it; it is said recovered when
 > it is *retired*, after five passes and ten minutes, or a person's approval. A provider says what it
 > retires, approves, re-enables and deletes on an event of its own, `provisioner.retirement`, permitted
 > the same way as the two events here.
 **2. Every provider may say it, whatever its manifest lists.** The permission to publish the two events
 is derived for every module that receives contributions; no manifest declares them. A provider whose
 manifest forgot them would otherwise have its announcement refused by the bus and fail as silently as
 before.
 **3. The controller follows both events from every module, keeps the newest failing word per provider
 module, its machine and the consumer, and removes it on recovery.** Who said it is read from the subject
 the bus let the provider publish on, never from the body. A recovery that arrives while the store is
 away is held and delivered again, because it is said once. The controller's subscription names the two
 events with a wildcard for the emitter — the one pattern on its list — rather than a list of providers
 somebody would have to extend.
 **4. `status` names every consumer a provider still assigned where it ran says it keeps failing**, and
 such a consumer breaks the all-well sentence. Its JSON carries them as `failing`; `node show` lists those
 whose provider or consumer is on that machine. A provider no longer assigned there has nothing running
 to fail anybody, and is not asked about. A standing not said again for thirty minutes is shown with how
 long it has been silent: the provider stopped saying anything, and its last word is all the mesh has.
 **5. Where a provider's failure has one known cause it can repair safely, it repairs it.** The identity
 provider's administrator refusing the mesh's secret is the first: the module now checks the
 administrator's login on start, every five minutes and whenever its provisioner is refused, and repairs
 a refusal through the server's own bootstrap command — a temporary administrator, the real one's
 password set to the mesh's, the temporary one removed, nothing printed — then checks again and says
 what it did. A repair that fails is braked, from ten minutes doubling to six hours, and announced; while
 the administrator is refused the provisioner stops asking the server, so a lockout policy is not
 provoked, and its consumers are still announced failing. The mechanism is the module's
 ([issue 179](../04-ISSUES/179-an-adopted-identity-providers-admin-never-took-the-minted-secret/00-report.md)),
 the rule is this record's: **detected automatically, repaired where safe, loud where not.**
 ## Consequences
 - **The loop is carried by every Go provider until the Go SDK has one.** The provisioner loop is the
  SDK's ([ADR 0039](0039-what-the-sdk-holds-and-refuses.md)); the Go SDK has none yet, so the two Go
  providers carry identical copies and a test in each fails when they differ. A TypeScript provider
  announces nothing until the TypeScript SDK's loop does the same; until then its consumers fail as
  silently as before, and the next provider to be ported to Go closes that gap for itself.
 - **The controller's event consumer takes one message at a time**, so a standing can wait behind a
  build being acted on for some minutes. Fifteen-minute repetition makes that harmless for a failure;
  a recovery is held, never dropped.
 - **The store keeps one row per provider module, its machine and consumer**, through a numbered
  migration.
 - **The rollout order matters.** The controller that derives the permission and follows the events
  first; the catalogue's providers second — an older controller refuses nothing that matters, but
  every announcement is then refused by the bus and logged by the provider.
 ## How it is checked
 | Rule | Checked by |
 |---|---|
 | A consumer failed for five minutes without a success is announced, again every fifteen, and recovered on the first success | provider loop tests in mesh-catalog, postgres and keycloak (`standing_test.go`) |
 | A failing periodic check and an unreadable secret count, not only a failing create | the same tests |
 | A withdrawn consumer and the first success after a start are announced recovered | the same tests |
 | The two Go providers carry the same loop | `harness_same_test.go` in each, comparing the files |
 | Every module that receives contributions is granted the two events, and no other module is | mesh-controller inventory test over the derived declaration and the bus permissions |
 | The controller may hear the two events from any module, and not every event | the same test over the controller's permissions |
 | The emitter is read from the subject; a failing word is kept, a recovery cleared, and a recovery held while the store is away | mesh-controller link tests with a fake store |
 | One row per provider, machine and consumer; recovered removes only its own | an inventory test against a live database, through the migration |
 | `status` names it and is not all-well; the JSON carries it; `node show` names it on both machines; an unassigned provider's word is not a problem | mesh-controller command tests against a live database |
 | The identity provider repairs a refused administrator, verifies, brakes a failed repair, never puts a secret in a command line, and stops asking the server while refused | keycloak module tests with a fake server and a fake container runtime; a live test against a throwaway server when asked for |
 | Live: after rollout, `status` shows nothing failing on a healthy mesh; a provider made to fail a consumer for five minutes appears, and disappears on its next success | read through the console after rollout |
 ## References
 - [Issue 179](../04-ISSUES/179-an-adopted-identity-providers-admin-never-took-the-minted-secret/00-report.md)
  — the failure, twice, and the repair this record makes automatic.
 - [Issue 145](../04-ISSUES/145-a-machine-reads-healthy-while-its-modules-cannot-reach-each-other/00-report.md)
  — the scope of the all-well sentence, which this narrows and does not close.
 - [ADR 0040](0040-what-a-module-is.md), [ADR 0048](0048-a-provider-creates-the-credential-the-mesh-minted.md),
  [ADR 0039](0039-what-the-sdk-holds-and-refuses.md), [ADR 0042](0042-the-shape-of-an-event-on-the-wire.md).
 - [The module protocol](../03-DESIGN/01-to-be/19-the-module-protocol.md), provisioning, amended alongside.
 - mesh-controller `internal/link/standing.go`, `internal/inventory/standing.go` and its migration,
  `cmd/mesh-controller/standing.go`; mesh-catalog `modules/postgres` and `modules/keycloak`.
@@ -1,148 +0,0 @@
 ---
 topic: what runs on it
 status: accepted
 date: 2026-10-06
 deciders: jochen
 reconstructed: false
 extends: 02-DECISIONS/0049-a-consumers-identity-fits-the-tightest-backend.md
 ---
 # 225. A consumer's identity is bounded by the provision it requires, judged before merge, and never refuses its provider
 ## Context
 [ADR 0049](0049-a-consumers-identity-fits-the-tightest-backend.md) bounds every consumer's identity,
 `mesh_<machine>_<slug-or-module>`, by the tightest backend anywhere in the mesh: an S3 access key's 20
 characters. It chose that over per-interface bounds (its option C) because one constant unblocked the
 object store, and named C as the refinement "if non-S3 consumers are paying for S3's limit often
 enough to mind". [Issue 263](../04-ISSUES/263-every-consumer-pays-for-the-tightest-backends-name-limit/00-report.md)
 is that point. The operator: "the 20 character limit has bitten us multiple times".
 What happened on 2026-10-06, and what it shows:
 - **The bound applied where it meant nothing.** A change made the network-manager modules require the
  mesh's resolver provision. The resolver mints no credential and keeps no name: its provider is not
  even told who its consumers are (it receives nothing). `networkmanager`'s identity, 23 to 26
  characters on real machine names, was refused all the same.
 - **It was found late and far from its cause.** The catalogue's module check and the controller's
  tests passed. ADR 0049 says the refusal comes at assignment; this was a new requirement on modules
  already assigned, so no assignment saw it. It surfaced when the provider composed its grants.
 - **It refused the wrong machine, wholly.** The controller judged the identity while composing the
  *provider's* declaration, and one refusal there fails the whole composition. The anchor holds the
  resolver, so the anchor — every module on it — could not be pushed until a slug was changed
  elsewhere.
 The catalogue's providers keep very different names. Read from each provider's code: the object store
 keeps the identity as an access key (20) and a bucket name; PostgreSQL as a role and a database (63);
 MongoDB as a database (63); SQL Server as a login and a database (128); the identity provider as a
 client id (255); the forge as a user name (40); the mail server as a mailbox's local part (64); the
 public DNS provider as a label (63); the cache, the vault, the message broker and the time-series
 store as names with no limit worth stating. The resolver and both route providers keep no name of
 their consumers at all.
 ## Considered Options
 1. **Keep one bound, raise or lower it.** Any single number is wrong for most provisions: 20 refuses
   a database consumer for an object store's key, 63 lets the object store fail at provision time
   again ([issue 034](../04-ISSUES/034-mesh-login-exceeds-s3-access-key-limit/00-report.md)). Rejected —
   it is the cause.
 2. **Per-interface bounds in a mesh-wide table of provisions.** Puts the fact in the controller, which
   would then know what an S3 key is. The mesh is name-agnostic about what a provider does with an
   identity (`ConsumerIdentity`); a table would make it learn every backend. Rejected.
 3. **Each offer states its own bound; the bound a consumer meets is that of the provision it
   requires** (ADR 0049's option C, placed where [ADR 0202](0202-a-provider-declares-what-it-derives-for-each-consumer.md)
   already places what a provider derives: in its own definition). Chosen.
 4. **Derive a different identity per provision** (C's own "against": one consumer, several names).
   Not needed: the identity stays one name, said once, and must fit every provision the module
   requires. Only the *bound* is per provision. Rejected as unnecessary.
 And for where the refusal lands:
 5. **Keep refusing the provider's composition.** Rejected — it makes one consumer's name a reason
   no push reaches a machine that did nothing wrong.
 6. **Refuse the consumer's whole machine.** Right machine, still too wide, and still late. Not chosen;
   the consumer is named instead, and refused in its own pull request (below).
 ## Decision
 **1. An offer states the longest consumer identity its backend keeps.** In the provider's
 definition, beside the provision: `identity` with a `max` and the words for what keeps it (`in`), so a
 refusal can say "an S3 access key keeps 20"; `in` alone for a backend with no limit worth stating; or
 `false` for a provision that keeps no name derived from its consumer. The bound applied to a consumer
 is that of the provision it requires, from the offer of the module answering it — not the tightest
 backend in the mesh.
 **Unsaid, the bound follows from what the provider is told.** A provider that receives the provision,
 or serves its consumers a value built from their identity, is told who each consumer is and may make
 a name of it in a backend nobody measured: it keeps ADR 0049's 20. A provider told neither keeps
 nothing of its consumers: no bound. A provider whose definition is not at hand is held to 20.
 **2. An overflow is refused before merge.** The catalogue check (`module check`, and the controller's
 test over the real catalogue) judges every module's identity, built on the longest machine name of
 the mesh, against the bound of every provision it wants that a module in the catalogue offers — the
 tightest where several offer it. The pull request that introduces an overflow — a new requirement, a
 lowered bound, a longer module name — is the one that fails, naming the module and the longest slug
 that would fit. The longest machine name is a parameter of the check; its default is the mesh's own
 longest, raised in the same change that names a longer machine.
 **3. One consumer's identity never refuses its provider's machine.** When the provider's declaration
 is composed, a consumer whose identity overflows the bound is left out of the grants and returned
 beside them; every other consumer is granted and the declaration composes. The consumer is named
 where an operator looks: on the push and plan of the provider, on the plan of the consumer's own
 machine, and in `status` (and its document), which does not call the mesh well while one stands.
 **4. An identity served as a DNS label stays inside one.** The mesh writes an identity into a label
 without truncating it ([ADR 0202](0202-a-provider-declares-what-it-derives-for-each-consumer.md)),
 so an offer that serves `${consumer:as:dns}` must bound its consumers at 63 or less.
 What does not change: the identity is still derived once and said to both ends (ADR 0049, issue 023);
 the slug is still the remedy; truncation and hashing are still refused.
 ## Consequences
 - A consumer of a database or the identity provider keeps a legible name on a long machine name; only
  a consumer of the object store still needs a slug of a few characters. Requiring a keyless
  provision costs nothing in name length.
 - The catalogue's providers each state a bound in their offer, and the check reads it there. A new
  provider that is told its consumers and says nothing keeps the old 20: safe, and visible in review.
 - A consumer left out of the grants holds a binding and credential its provider never created. It
  fails to authenticate; that is reported by name in `status` until a slug fixes it, rather than
  hidden behind a machine nobody could push.
 - The check's default machine-name length is a fact about one mesh carried in code. A mesh that
  names a longer machine must raise it, or pass its own to `module check`; nothing reminds it to.
 - Old controllers refuse the new field (manifests are parsed strictly), so the controller ships before
  the catalogue that states bounds.
 - ADR 0049's consequence "`identityLimit` becomes 20 … `CheckIdentity` refuses at `module add` /
  assignment" now holds only for a provision that keeps 20, and is checked before merge and reported
  at composition rather than refused at assignment. ADR 0049 carries a note saying so.
 **How each rule is checked.**
 - *Rule 1:* catalogue unit tests — an offer's stated bound is the one applied; an unstated one is 20
  for a provider told its consumers and none for one told nothing; `false` is none; the field parses
  strictly and a bound without `in`, or shorter than any identity, is refused when the definition is
  parsed. Over the real catalogue: the resolver provision bounds nothing and the object store 20.
 - *Rule 2:* `module check` refuses a module whose identity overflows what it requires, naming the
  slug length, and passes a long name requiring a keyless provision; a test runs the same judgement
  over every manifest in the real catalogue on the default machine-name length, so the catalogue's
  own pull request fails on an overflow.
 - *Rule 3:* a controller test against a real store reproduces the night it was found — the network
  manager, no slug, on a six-character machine, requiring the resolver provision, beside a consumer
  that overflows an object store: the provider's declaration composes, the network manager is granted,
  the overflowing consumer is left out, named by the push, carried by `status` and its document, and
  the mesh is not called well.
 - *Rule 4:* a test that a DNS-label identity under a bound over 63 is refused when the definition is
  parsed.
 ## References
 - [Issue 263](../04-ISSUES/263-every-consumer-pays-for-the-tightest-backends-name-limit/00-report.md) —
  the observation.
 - [ADR 0049](0049-a-consumers-identity-fits-the-tightest-backend.md) — the bound this refines; its
  option C.
 - [ADR 0202](0202-a-provider-declares-what-it-derives-for-each-consumer.md) —
  a provider declares what it derives; the bound is declared beside it.
 - `mesh-controller` `internal/catalogue/identity.go` (`IdentityBound`, `CheckIdentityWithin`,
  `IdentityProblems`, `Resolution.Overflowing`), `manifest.go` (`Offer.Identity`,
  `IdentityBoundOf`), `cmd/mesh-controller/plan.go` (`grantsFor`), `check.go`, `status.go`.
 - `mesh-catalog` — each provider's offer states its bound.
@@ -1,158 +0,0 @@
 ---
 topic: the tiers
 status: accepted
 date: 2026-10-06
 deciders: jochen
 reconstructed: false
 supersedes-in-part:
  - 0009-modules-and-the-graph.md
 extends: 02-DECISIONS/0007-connectivity.md
 ---
 # 226. The private network is assigned by its own name, and the proxy names its public issuer
 ## Context
 **The operator, 2026-10-06: "too many network-related modules … we simply have a private network,
 some docker stuff, a firewall and a public and internal certificate resolver."** Counted on the
 production mesh that day, from the controller's module listing and each machine's plan:
 | module | on | what it is |
 |---|---|---|
 | `networking` | all four machines | requirements only: `private-network`, nothing else. Ships nothing |
 | `mesh-wireguard` | on none directly; on all four through `networking` | the private network; its resources are computed by the controller |
 | `public-acme` | the anchor and the home server | runs nothing; offers `acme-ca`, pointing at Let's Encrypt's production directory |
 | `route-proxy` | the anchor and the home server | the public front door; the only consumer of `acme-ca` |
 | `dhcpcd` | none | a third holder of `node-uplink`, for a machine whose link is dhcpcd's |
 | `cloudflare-dns` | none | the only provider of `public-dns`; nothing in the catalogue requires `public-dns` |
 **`networking` is the domain module [ADR 0009](0009-modules-and-the-graph.md) argued for in its
 "what a domain module turns out to be" section**: a module holding nothing, so `assign networking`
 finds one VPN and takes it, and choosing another is assigning that instead. It has never been more
 than a second name for one module: one VPN exists, every machine runs it, and the name resolution it
 once also required became a fact (ADR 0199). Its cost is real: every machine carries two modules for
 one network, genesis assigns a module that is not the network, and the resolver's hint for a machine
 off the network names the bundle rather than what it installs.
 **`public-acme` is a provision with one consumer and one answer.** It was introduced so a lab without
 a public issuer could answer `acme-ca` from `step-ca` instead (ADR 0066); `step-ca` now offers only
 `internal-acme-ca`, and the mesh itself is the test bed (ADR 0149). What remained was a module
 assigned beside every proxy to say "Let's Encrypt", and a pin when two answers stood on one machine
 (issue 258).
 **The proxy's account directory is named after the issuer as rendered.** `route-proxy` keeps each
 authority's ACME account and certificates under `/var/lib/route-proxy/acme`, in a directory named by
 a digest of the directory URL and of the root bundle its `trust` step copies in (the proxy's
 `forThisAuthority`). The binding rendered the URL as `https://acme-v02.api.letsencrypt.org:443/directory`
 — with the port — and the root as the system bundle of the pinned `trust` image. Spelled any other
 way, the proxy sees a new authority, registers a new account and orders every routed name again. On
 2026-10-06 that is 25 names under one registered domain on the home server, all issued on 2026-10-01,
 and 26 on the anchor: a reissue of the home server's would reach Let's Encrypt's 50-per-week limit for that
 domain inside the week.
 ## Considered Options
 1. **The private network a default of every machine**, with no assignment. Rejected: "a machine is
   on the private network because it was assigned the module" is what made the network a module at
   all (connectivity §1, 2026-08-29); a default is a second path to the same state, and a machine
   that should stay off would need an exception mechanism that does not exist.
 2. **Keep `networking`, document it better.** Rejected: it answers a question — which VPN — that has
   had one answer since it was written, and costs a module on every machine to do so. Choosing
   another VPN is still assigning it; the bundle never added anything to that.
 3. **Assign `mesh-wireguard` directly on every machine and retire the bundle.** Chosen.
 4. **`route-proxy` provides `acme-ca` itself**, keeping the provision. Rejected: nothing else
   consumes it, and a provision whose only consumer is its provider is a field, not an edge.
 5. **The public issuer as a setting of `route-proxy`.** Rejected: a setting has no default (ADR
   0112), so every mesh would need it set before the proxy resolves, and the one value that must not
   change — the URL as rendered, port included — would become a value anybody can change with
   `settings set`. Changing the public issuer of a live proxy is a reissue of every certificate it
   holds; it should take an edit of the module and a decision, not a command.
 6. **`route-proxy` states Let's Encrypt in its own `acme.env`, byte for byte what the binding
   rendered, and `public-acme` retires.** Chosen.
 ## Decision
 **1. The private network is assigned by its own name.** Every machine is assigned `mesh-wireguard`
 directly. The `networking` module is retired: the controller no longer ships it, genesis assigns
 `mesh-wireguard`, and the resolver's refusal for two machines that share no private network names
 `mesh-wireguard`. Another VPN is still chosen by assigning it instead, and the node-scoped claim
 `the-private-network` still refuses two. This supersedes ADR 0009's section *what a domain module
 turns out to be*: the mechanism — a module with requirements and no files — stands, and the
 catalogue no longer holds one.
 **2. A module the controller stops shipping is retired at its next start, never from under a
 machine.** `module forget` refuses a module the controller ships, because the next start would put
 it back; so a retired one could be removed by nothing. At start the controller removes every module
 it recorded as its own and no longer ships — unless a machine is still assigned it, or the mesh still
 holds settings, secrets or ports for it, in which case it is kept and the start says why. This removes
 a module's *definition* from the catalogue, never a consumer's data: what a consumer leaves behind is
 [ADR 0230](0230-a-consumer-the-mesh-stops-asking-for-is-retired-and-deleted-only-by-a-person.md)'s, and
 a module holding anything is never removed here.
 **3. The proxy names its public issuer.** `route-proxy` no longer requires `acme-ca`; its `acme.env`
 states Let's Encrypt's production directory exactly as the binding rendered it. `public-acme` leaves
 the catalogue and the mesh. The internal issuer stays a provision (`internal-acme-ca`, from
 `step-ca`): it is a module that runs, held on one machine and consumed by every proxy and by
 `ca-trust`. The proxy binary's own default stays Let's Encrypt *staging*, for anything that runs it
 without the module.
 **4. `dhcpcd` and `cloudflare-dns` leave the catalogue.** Neither is assigned anywhere; nothing
 requires `public-dns`. `node-uplink` keeps two holders (NetworkManager, systemd-networkd), and the
 `public-dns` interface of [ADR 0044](0044-a-public-name-is-provisioned-like-any-capability.md) has no
 provider until a mesh needs one.
 `avahi` and `netcheck` are not decided here.
 ## Consequences
 - **The rollout changes no machine's network or certificates.** Assigning `mesh-wireguard` beside
  `networking` and then unassigning `networking` leaves every machine's declaration of the private
  network as it was; the proxy's `acme.env` is unchanged, so its `trust` step does not run again and
  its account directory is the one it has. The one file that goes is the proxy's binding to
  `acme-ca`, which nothing reads.
 - **The order is assign, then unassign.** Unassigning `networking` first takes `mesh-wireguard` off
  every machine that does not also run `dnsmasq` (which requires the mesh's addressing) at the next
  push — the private network down. The controller's retirement refuses nothing here; it only keeps
  the bundle while it is assigned.
 - **The public issuer moves only with a plan for the account.** The proxy's account directory depends
  on the URL as spelled and on the pinned `trust` image's root bundle. Moving that image's digest
  reorders every certificate on both proxies; a test holds both values and says so.
 - **The lab's beds that assigned `networking`, or pointed the proxy at `step-ca` for public names,
  need changing before they run again.** A lab proxy now orders public names from Let's Encrypt's
  production directory, so a bed that routes public names must not assign the module as it stands.
 - **Genesis from an older host binary assigns `networking`, which a newer controller refuses.** The
  host's change is merged before the controller's.
 - **A mesh that wants another public issuer edits `route-proxy`**, rather than assigning a different
  provider. That is deliberate (option 5).
 ## How it is checked
 | Rule | Checked by |
 |---|---|
 | The controller ships one network module and no bundle; it resolves on its own | mesh-controller `internal/catalogue/provided_test.go` |
 | A refusal for want of the private network names `mesh-wireguard` | the same file, `TestARefusalForWantOfThePrivateNetworkNamesItsModule` |
 | Another VPN is chosen by assigning it, and WireGuard is not dragged in; two VPNs collide | the same file |
 | A module no longer shipped is retired at start; kept while assigned or holding anything; a registered module is never touched | mesh-controller `internal/inventory/retire_test.go`, against a live database |
 | Genesis assigns `mesh-wireguard`, never `networking` | mesh-host `internal/bootstrap/network_module_test.go` |
 | `route-proxy` requires no `acme-ca`; its `acme.env` is byte for byte what the binding rendered; its `trust` image is the pinned one | mesh-controller `internal/catalogue/public_issuer_test.go` against the sibling catalogue |
 | `public-acme`, `dhcpcd`, `cloudflare-dns` are not in the catalogue; nothing in it requires `acme-ca` or `public-dns` | the same file |
 | Live: every machine still on the private network; every public name's certificate serial and expiry unchanged; no new file in a proxy's account directory | the rollout's checks, before and after each step: the controller's network view, `wg show` through each machine's tools, `openssl s_client` against every routed public name, and a listing of `/var/lib/route-proxy/acme` |
 ## References
 - [ADR 0009](0009-modules-and-the-graph.md) — its section on a domain module is superseded; the rest
  stands.
 - [ADR 0007](0007-connectivity.md), [connectivity](../03-DESIGN/01-to-be/08-connectivity.md) §1 and §5,
  amended alongside.
 - [ADR 0066](0066-public-routing-is-name-agnostic.md) — the proxy requiring an issuer; the public one
  is now its own fact.
 - [ADR 0044](0044-a-public-name-is-provisioned-like-any-capability.md) — `public-dns`, without a
  provider in the catalogue.
 - [ADR 0117](0117-a-machines-uplink-is-a-seat.md) — `node-uplink`, now with two holders.
 - [ADR 0112](0112-a-module-definition-names-no-node-mesh-or-path.md), [ADR 0149](0149-the-live-mesh-is-the-test-bed.md).
 - [Issue 258](../04-ISSUES/258-every-machine-bound-the-resolver-to-itself/00-report.md) — the pin two
  issuers on one machine needed.
 - mesh-controller `internal/overlay/generator.go`, `cmd/mesh-controller/modules.go`, `stores.go`,
  `internal/inventory/catalogue.go`, `internal/catalogue/resolve.go`; mesh-host
  `internal/bootstrap/phase2.go`; mesh-catalog `modules/route-proxy`, and the removal of
  `modules/public-acme`, `modules/dhcpcd`, `modules/cloudflare-dns`.
@@ -1,226 +0,0 @@
 ---
 topic: the mesh
 status: accepted
 date: 2026-10-06
 deciders: jochen
 reconstructed: false
 extends: 02-DECISIONS/0224-a-provider-that-keeps-failing-a-consumer-is-a-problem-the-controller-reports.md
 ---
 # 227. The core holds nine rules, each checked, and is built to them in six phases
 ## Context
 **The core is the controller, the node-engine and its launcher, the bus server, the node tools and the
 console, the build seat, and the forge's announcer of merges** — everything a change passes through
 before a module's own code runs. On 2026-10-06 the operator asked for it to be *"fully diagnosable, with
 active monitoring, self-healing, self-upgradeable, self-monitoring … very sturdy, no ambiguities, clear
 plan of execution, fail-proof setup"*, and approved [research 031](../01-RESEARCH/031-a-core-that-cannot-fail-silently/00-overview.md)'s
 conclusion the same day: *"do the research and implement it"*.
 The evidence is [031/01](../01-RESEARCH/031-a-core-that-cannot-fail-silently/01-evidence.md):
 - **92 issue reports in six days; 48 of them core failures.** Every one of the 48 was noticed because a
  person or an agent looked. **None was raised by the mesh unasked.** In four the mesh's own answer
  carried the fact for whoever asked; in none did it tell anybody.
 - **Four faults came back through a different door after their first fix** (200 → 265, 230 → 264,
  257 → 261 → 267, 175 → 184 → 248): each fix closed an instance and left the class open.
 - **The classes, by count:** races between actors with no explicit order (10 issues); commands or
  arguments dropped with a default chosen in their place (8, two of them destructive —
  [241](../04-ISSUES/241-one-unreadable-grants-file-dropped-every-database-on-the-control-node/00-report.md)
  dropped seven databases on one unreadable file,
  [244](../04-ISSUES/244-a-verb-whose-schema-is-empty-cannot-be-called-through-the-console/00-report.md)
  pushed every machine when one was named); outcomes never fed back (8); failures visible only as log
  lines (9, the longest twenty-three hours); state with two writers (7); repairs by hand (at least
  fifteen acts, the commonest a push by hand to unstick a plan waiting on a report); self-upgrade
  breaking the core (10); checks that pass in CI and fail on the mesh's real facts (6); third-party
  faults nobody compared against outcomes (3, one of them
  [266](../04-ISSUES/266-a-merge-on-the-bus-was-never-handed-to-the-controller/00-report.md):
  23 merges unacted on over three days).
 - **The parts mostly exist, one rule per message kind.** Declarations carry a sequence; reports do not.
  Builds and plans are ordered; controllers have no epoch. `calls` keeps outcomes, in memory, and a
  controller restart — every merge to its own repository — forgets them. ADR 0224 made one failure
  kind a problem `status` reports and repairs where safe; nothing generalises it.
 **Checked against GENESIS.** The mission's core value *failure must be loud — prefer failing to lying*
 is the rule this record enforces on the core. The context says *human agents are few, often one, and
 usually asleep; anything requiring a human to notice it will be noticed late* — the 48-of-48 count is
 that sentence measured. The effect promises that *the mesh notices when something is wrong before you
 do* and asks *with the context, not a log line*. Nothing in 031 conflicts with GENESIS; the effort is
 the gap between the effect and the as-is, counted.
 ## Considered Options
 1. **Keep fixing issues one at a time.** Rejected: that is what the window did, and four classes
   recurred through a different door. Point fixes converge on instances, not classes, and the next
   message kind or the next reader of an unreadable file starts from nothing.
 2. **Monitoring from outside: a metrics stack with alert rules** (an exporter per component, a time
   series store, an alert manager). Rejected: it observes symptoms the core would still keep to itself
   (a report never sent is not a metric), it is a second answer to questions the controller already
   answers (how-we-build §5: a report is read from the system), it adds three services to a mesh with one
   operator, and it repairs nothing. The mesh's facts are in the controller; the watcher belongs there,
   with one watcher of the watcher outside it.
 3. **Prevention first: order and one writer before anything else.** Rejected as the *first* step, kept
   as the second. Prevention covers the classes already met; detection covers every class including
   those not met yet, and is cheaper per day. Phase 1 makes the mesh say when it is wrong; Phase 2
   removes the largest class.
 4. **Heal everything by default.** Rejected: a default of healing heals what is not understood, which is
   how a repair destroys — 241's reconcile was, in its own terms, healing. Healing is narrowed to
   *known* failures, ones repaired by hand twice, under a brake.
 5. **A three-server bus cluster, so the bus can be upgraded live.** Not decided here: it is a change of
   the foundation's shape and needs its own effort. Until then a bus upgrade is a planned, announced
   step (rule 8).
 6. **The lab as the place every core change is proven.** Rejected by [ADR 0149](0149-the-live-mesh-is-the-test-bed.md),
   which stands: the live mesh is the test bed. Lab replays are kept for what must not be done to the
   live mesh on purpose — two controllers at once, a deliberately broken controller build, a suppressed
   signal — and each rule still has a live check.
 7. **Nine principles as stated, the mechanisms M1–M9 and the phased roadmap of 031/03.** Chosen.
 ## Decision
 **The nine rules below hold for the core. A change to a core repository is refused in review if it
 breaks one, and each rule is checked as its row in *How it is checked* says.** They extend, and do not
 replace, [research 017](../01-RESEARCH/017-a-mesh-that-heals-itself/01-the-intended-behaviour.md)'s
 six for the loops that converge modules.
 1. **One writer per piece of state.** Every kind of state the core keeps has exactly one writer, named
   in the writers table of [to-be 45](../03-DESIGN/01-to-be/45-a-core-that-cannot-fail-silently.md).
   Anyone else asks that writer. Nobody computes a second answer to a question it already answers. The
   controller holds a **lease**; only the holder acts.
 2. **Everything that changes state carries its writer's order, and every receiver refuses what is
   older.** Declarations, reports, plans, builds, calls and announcements carry writer, epoch and
   sequence. A receiver keeps the highest it accepted per writer and refuses anything older, with a line
   in the mesh's words and a counter. Arrival order never decides.
 3. **Every command is answered at once, and its outcome is kept where it can be read later.** Within
   the verb's declared bound, with a result or a call id. The outcome is durable: it outlives the process
   that ran it, and is read or waited on by id. No answer depends on what the command does to the
   transport carrying it.
 4. **Nothing is dropped silently.** An input that is unknown, unreadable or unmet is refused by name —
   which input, where, why. A default is never substituted for *I could not tell*, above all never
   "empty". A reconcile that would withdraw more than a bound of what it holds stops and raises a
   condition instead.
 5. **Every expected signal has a watchdog; absence is a condition.** Every signal the core expects on
   a cadence or after an act has a row in the signals table: emitter, trigger, bound, condition raised.
   Silence past the bound is a condition naming what was expected, from whom, since when.
 6. **The mesh checks itself continuously against live facts and says what it found outward.** The
   design's invariants are probes run on a schedule against the running mesh (`doctor`). A violation is
   a **condition** — durable, with since-when, evidence and who can resolve it — shown in `status` and
   sent to the operator through the output channel. The checker's heartbeat is watched from a machine
   that is not the control node, through a channel that does not pass through it.
 7. **A known failure heals itself, under a brake, and every repair is said.** A failure repaired by
   hand twice gets a healer: the ordinary path again, never a destructive act, with a budget and a
   back-off, and one event saying what it did. A spent budget, or a repair that could only destroy, is
   a condition, not a retry. Every repair a person makes on the core goes through a verb that records
   who, what and why (the **hand-act log**).
 8. **The core upgrades itself one machine at a time, health-gated, and rolls back on its own.** A new
   controller, node-engine or node tools build is judged on its first machine by that component's
   health probes, not by "reported applied". One not healthy within its bound is rolled back to the
   last known good **by something other than itself**, and the rollback is a condition. The component
   being replaced is never the only witness of its successor. A bus upgrade is a planned, announced
   maintenance step, never a plain rollout.
 9. **A check is fed the real mesh's facts before a change is merged.** A check whose verdict depends
   on the environment runs against a facts snapshot exported by the controller — every machine
   composed with the change and validated by the node-engine's validator — and a dependency's version
   the mesh runs is the version its tests run.
 **The plan of execution is the six phases of to-be 45**, in that order, each ending at its own *done
 when*:
 | Phase | What it delivers | Rules |
 |---|---|---|
 | 0 — finish what is in flight | the located core fixes rolled out; `calls` durable; `status` inside its bound; the hand-act log; the bus's planned upgrade as the first maintenance step; the durations the bounds are measured from | 3, 7, 8 |
 | 1 — the mesh says when it is wrong | conditions; watchdogs from the signals table; the bus's advisories; `doctor`; the output channel in its minimal form and the second-machine watcher | 5, 6 |
 | 2 — order and one writer | the controller's lease and epoch; a report's sequence; one apply queue on every machine; stale refusals counted; the writers table enforced; the empty-on-error lint; the withdrawal brake | 1, 2, 4 |
 | 3 — healers | the first healers, each braked; a repeated hand act asks for one | 7 |
 | 4 — core upgrades that roll back | a health definition per core component; the gate; rollback by a witness; the bus as a planned step | 8 |
 | 5 — checks before merge, and replays | the facts snapshot and the compose-and-validate merge gate; versions tested as run; every core incident a replay | 9, and all |
 **The output channel is built in the smallest form research 028 allows.** One mesh seat,
 `operator-channel`, accepting `notify` as a work queue and holding its open messages in its own state
 ([028 Q1](../01-RESEARCH/028-the-meshs-output-channel/03-open-questions.md), option a); the controller
 emits condition events and the holder decides what is sent (028 Q5, option a); the Telegram channel the
 operator required and the desktop notifier as the two channels; deduplicated by the condition's key; no
 answering back except through the mesh's own verbs; a message carries roles and words, never an
 address, a path or a secret, refused by the holder otherwise (028 Q8). Routing by presence, quiet hours,
 answering back and the external dead-man service stay open in 028, whose graduation amends to-be 45.
 > **The mechanism changed — 2026-10-06, by [ADR 0234](0234-the-mesh-holds-a-conversation-with-its-operator.md).**
 > What still stands: the output channel is built first in this minimal form, as Phase 1 of to-be 45, and
 > everything above about conditions, deduplication, the content rule and the watcher. What moved, as
 > this paragraph said it would on 028's graduation: "no answering back" no longer holds. The operator
 > answers and is asked over channels that are holders of two kinded benches, `channel` and `intake`,
 > not contributions to `operator-channel`, whose holder becomes the router; an answer that performs an
 > action is checked and performed by the controller. The design is
 > [to-be 46](../03-DESIGN/01-to-be/46-the-conversation-with-the-operator.md).
 **ADR 0224's provider standing becomes the first condition kind**, unchanged in what it says and
 when; its storage moves into the condition store.
 ## Consequences
 - **`status` changes meaning.** It becomes, first, the list of open conditions; the all-well sentence
  is "no open conditions", silenced ones included. A silenced condition is still open; silence stops
  only its messages, for a stated time, with a reason, recorded as a hand act. Nobody resolves a
  condition by hand: it clears when observation says so.
 - **The bounds are measured, not guessed.** The signals table's first bounds are provisional; Phase 0
  records the durations they are set from, and Phase 1's first live week corrects every bound that
  raised a condition that was not real. A corrected bound is a change to the table, reviewed like code.
 - **The controller's restart stops being a forgetting.** Calls, conditions, the hand-act log and the
  lease live in key-value buckets ([ADR 0201](0201-a-module-keeps-its-current-state-in-key-value-buckets-it-declares-and-reaches-through-the-runtime.md));
  a new holder of the lease marks a call the old one left running as abandoned, which is said.
 - **The node-engine gains an order it did not have.** One apply queue replaces the delivery path and
  the five-minute reconcile as two appliers; a report carries the declaration's sequence; a declaration
  from an older controller epoch is refused. Issues 257, 261 and 267 become impossible rather than
  handled. The controller–node-engine wire changes, so the rollout order is the node-engine first
  (it accepts both shapes), the controller second.
 - **More is checked before merge, and merges get slower.** The compose-and-validate gate runs every
  machine through the validator on every core and catalogue merge. That is minutes, against the hours
  each of 202, 236 and 263 cost.
 - **A third party now carries operational words.** Telegram is not end-to-end encrypted for bots, so the
  holder's content rule is the only thing between a condition's evidence and someone else's server. It
  is enforced by the holder and tested there, not trusted to each source.
 - **The watcher outside the control node holds the channel's secret.** That is one more machine with a
  bot token, accepted for the one case nothing else covers: the control node or the bus is what failed.
 - **The roadmap is six to eight weeks of focused work.** The first visible change — the mesh saying
  when it is wrong — is inside the first two. Until Phase 2 lands, races are still caught by watchdogs,
  not prevented.
 - **The rules are not yet in how-we-build.** They are this record's until they are carried into
  how-we-build §2 through playbook 05 (constitution sync), which is a separate change.
 ## How it is checked
 | Rule | Checked by | From |
 |---|---|---|
 | 1. one writer | the writers table in to-be 45; a test per core repository that the code paths writing each kind are the named writer's; the controller refusing, at composition, a bus subject two components may publish on unless the table says it is shared; live, the `doctor` probe *exactly one lease holder, no stale-epoch message in the last interval* | Phase 2 |
 | 2. order | a contract test per consumed message kind in the receiver's repository (deliver *n*, then *n−1*: refused and counted; epoch *e−1* after *e*: refused); a check listing every consumed subject against the tests that name it; live, the stale-refusals signal | Phase 2 |
 | 3. answered, kept | a test walking every verb the controller announces (answers within its bound, with a result or an id); a test restarting the controller between a call and the read of its outcome; live, the `doctor` probe *status answers in full within ten seconds* and the *call hung* signal | Phase 0 |
 | 4. nothing dropped | per component, a test feeding each input reader an unreadable, malformed and foreign input (a refusal, never an empty result); a lint in each core repository refusing an error branch that returns an empty collection; schema walks over every verb and placeholder namespace; a test emptying a provider's input and asserting nothing is withdrawn | Phase 2 |
 | 5. watchdogs | a test generated from the signals table that suppresses each signal in turn and asserts its condition is raised within its bound and cleared when it returns; live, `doctor` reporting the age of the newest signal of every row | Phase 1 |
 | 6. self-check, outward | a check over the to-be designs counting invariants with a live probe against those without, which may only go down; the second-machine watcher raising *self-check silent* when the controller is stopped; once, on a lab mesh, a broken invariant appearing in `status` and as a message within one probe interval | Phase 1 |
 | 7. healers | a test per healer inducing its failure, asserting the repair, the event and the brake after the budget; the hand-act log's weekly count in `status`; a cause recorded twice raising *healer wanted* | Phase 3 |
 | 8. staged upgrades | on a lab mesh, a broken build of the controller, the node-engine and the node tools (one that starts and does nothing, one that crashes, one that cannot reach the bus) each rolled back with no hand, ending on the previous build, said as a condition and a message; live, every core rollout's record (first machine, verdict, time to verdict, rolled back or not) readable through `plans` | Phase 4 |
 | 9. real facts | the merge gate in mesh-controller, mesh-host and mesh-catalog failing a change that makes any machine of the snapshot fail to compose or validate, naming the machine's role and the module; a test that a pinned dependency's version equals the version in the snapshot; the replays of 236, 262, 263 and 266 failing on the commit before their fix | Phase 5 |
 | the plan | each phase's *done when* in to-be 45, recorded in that design when met, with the design's status following | each phase |
 ## References
 - [Research 031](../01-RESEARCH/031-a-core-that-cannot-fail-silently/00-overview.md) — the evidence,
  the principles with the candidates not kept, the mechanisms and the roadmap.
 - [To-be 45](../03-DESIGN/01-to-be/45-a-core-that-cannot-fail-silently.md) — the design this record
  authorises.
 - [Research 017](../01-RESEARCH/017-a-mesh-that-heals-itself/00-overview.md) — the condition, and
  the six principles for the loops; [research 028](../01-RESEARCH/028-the-meshs-output-channel/00-overview.md)
  — the output channel, of which the minimal form is taken here.
 - [ADR 0224](0224-a-provider-that-keeps-failing-a-consumer-is-a-problem-the-controller-reports.md) —
  *detected automatically, repaired where safe, loud where not*, generalised here.
 - [ADR 0141](0141-the-host-delivers-its-own-successor.md), [ADR 0162](0162-a-merge-produces-a-tiered-plan-the-mesh-keeps.md),
  [ADR 0218](0218-a-plan-sends-grants-before-code-rolls-out-one-machine-first-and-a-newer-merge-takes-over-an-older-plan.md),
  [ADR 0149](0149-the-live-mesh-is-the-test-bed.md), [ADR 0201](0201-a-module-keeps-its-current-state-in-key-value-buckets-it-declares-and-reaches-through-the-runtime.md).
 - Issues [187](../04-ISSUES/187-the-mesh-tells-nobody-when-it-stops-working/00-report.md),
  [204](../04-ISSUES/204-a-controller-handover-re-sent-every-node-a-stale-declaration/00-report.md),
  [241](../04-ISSUES/241-one-unreadable-grants-file-dropped-every-database-on-the-control-node/00-report.md),
  [248](../04-ISSUES/248-the-controllers-event-consumer-replayed-a-week-and-held-every-merge-behind-it/00-report.md),
  [264](../04-ISSUES/264-a-self-updating-engine-lost-the-report-of-the-apply-that-delivered-it/00-report.md),
  [265](../04-ISSUES/265-a-push-outlived-its-caller-and-its-answer-was-refused/00-report.md),
  [266](../04-ISSUES/266-a-merge-on-the-bus-was-never-handed-to-the-controller/00-report.md),
  [267](../04-ISSUES/267-a-reconciles-report-overtook-the-apply-that-followed-it/00-report.md).
@@ -1,143 +0,0 @@
 ---
 topic: what runs on it
 status: accepted
 date: 2026-10-06
 deciders: jochen
 reconstructed: false
 extends: 02-DECISIONS/0113-the-vault-makes-every-secret.md
 ---
 # 228. A value given by hand lives only until its module's first good start
 ## Context
 **Two of a module's own secrets leaked into logs on 2026-10-06**, and the operator approved replacing
 both. Each module's definition says it reads the secret when it starts (`taken: at-start`), which is
 the form the mesh rotates by making a new value and starting the module again
 ([ADR 0114](0114-a-shared-credential-rotates-over-two-credentials.md),
 [to-be 13](../03-DESIGN/01-to-be/13-credentials-and-their-rotation.md)). The controller refused both:
 > not rotated: … holds "…" as a value given to the mesh, not made by it, and the mesh will not replace
 > what it cannot read (ADR 0113). Change it where it lives, then `secret accept …` with the new value
 Both values had been given by hand long before, when the modules were moved from an older setup, and
 nothing outside the mesh uses either. The way out the refusal names has a person or an agent make a
 value and feed it to `secret accept` — a secret passing through hands, which is the thing the mesh
 exists to avoid.
 **The refusal reads [ADR 0113](0113-the-vault-makes-every-secret.md) wider than it decides.** 0113 says
 *"A delivered value the vault cannot replace, such as an external API key, is not rotated by the vault:
 rotating it means an operator delivering a new one"*. What the vault cannot replace is a value only an
 outside party can issue — a vendor's key, a bot's token, a licence — because no value of the mesh's
 would work in its place. A secret the module reads at start and nobody else holds is not that: the old
 value is not needed to replace it, because the module is the only reader and it reads the new one when
 it starts. The controller applied the rule to **every** value it had been given, because the store
 records only *made* or *accepted*, and nothing in a module's definition says who issued a value.
 The operator, the same day: *"Our mesh should most definitely be able to rotate 'custom provided'
 passwords — in fact, ideally we immediately rotate them after assigning and running the module for the
 first time so the 'custom pwd' is gone"*, and *"a custom pwd is only useful in case we're adopting an
 existing running container into our mesh."*
 Counted in the catalogue on 2026-10-06: 48 own secrets across 32 modules; 6 say `taken: at-start`, none
 says `applied` and 42 say neither. Of the 6 at-start ones, one is an outside party's key (an OpenAI
 key). Of the rest, at least ten are keys or tokens an outside party issues.
 ## Considered Options
 1. **Keep the refusal; add a separate verb that turns a given value into a made one** (`secret mint`,
   with a reason). Rejected: it keeps a step whose only effect is to say "yes, really" to a rotation
   the definition already permits, and it leaves every given value in force until a person remembers
   to take it. The operator asked for the opposite default.
 2. **Rotate a given at-start value like a made one, and stop there.** Better, and still leaves the
   given value in force indefinitely after an adoption — the value a person handled stays the live one
   until somebody asks.
 3. **Rotate it like a made one, and replace a newly given value on its own once the module has started
   on it**, with the exception said where it belongs: in the module's definition, for a value an
   outside party issues. Chosen.
 4. **Refuse `secret accept` for a secret the mesh may make, except on an adopted machine.** Rejected:
   the mesh cannot tell a fresh install from one carrying data in from elsewhere on a converged machine
   — a restored volume holds the password it was made with — and the replacement after the first good
   start already bounds what a needless given value costs. It is accepted and said.
 ## Decision
 **A module's own secret says who may make its value.** By default the mesh may. An entry says
 `"issued-by": "outside"` when only a party outside the mesh can issue the value — a vendor's API key, a
 bot's token, a licence. The parser refuses any other word.
 **A secret the mesh may make** — read at start, and not issued outside — **is the mesh's to replace,
 whoever gave the value it holds:**
 - **`secret rotate` replaces a given value as it replaces a made one**: made anew, sealed to the
  machine and the operator, recorded as made, and the machine sent so the module starts on it. A
  rotation may say why, and the why is recorded in the hand-act log.
 - **A value given by hand lives only until the module's first good start under the mesh.** Given
  through `secret accept`, it is marked; when the machine's clean report arrives — every resource
  applied, nothing failed or refused — **for the declaration it was last sent, sent after the value
  was given**, the controller replaces the value with one it makes, sends the machine, says so in its
  log and states `secret-replaced` as the controller seat's fact, never the value. On an adopted
  machine the module must also be taken: until then the mesh runs nothing of it. The mark is cleared
  as the value is replaced, so it happens once.
 - **A given value exists to adopt something already running that holds it.** A module the mesh
  installs fresh needs none; `secret accept` for such a secret is accepted, says that the value lives
  until the first good start, and says on a converged machine that a fresh install needs no value.
 **What stays as given, refused with the reason:**
 - a value issued outside the mesh — never replaced; `secret rotate` names the issuer as the one to ask
  and says how old the given value is, and `secret accept` delivers the new one;
 - a value the module **applies** to a backend that takes it once, until the staged rotation of
  [ADR 0114](0114-a-shared-credential-rotates-over-two-credentials.md) exists;
 - a value the mesh's own code accepted — a bus account it issued is its word to a broker, and is never
  marked;
 - a value given **before** this record, which is not marked: the mesh does not decide for a person
  that something given long ago is used nowhere else. `secret rotate` replaces it when asked.
 **What this does not change.** A pair credential an operator delivers is still never replaced by a
 made one ([ADR 0092](0092-an-operator-delivers-a-pair-credential.md)): it is held at both ends of a
 provision, and this record is about a secret one module holds. A secret whose definition says neither
 `at-start` nor `applied` is still not rotated. That the vault makes every shared secret, and its custody,
 stand as 0113 decided.
 ## Consequences
 - Rotating a leaked secret a module reads at start is one call, whoever gave it, with no value in
  anybody's hands.
 - An adoption leaves no hand-given value in force once the module runs under the mesh. A person who
  needs the new value — a password typed at a login page — recovers it with the operator key, as for
  any value the mesh makes.
 - **The catalogue must mark every secret an outside party issues.** An at-start secret left unmarked
  is one the mesh will replace with a random value. The two OpenAI keys in the catalogue are marked
  with this change; the other outside keys say neither `at-start` nor `applied`, so they are not
  rotated either way, and marking them is tidying, not a prerequisite.
 - **The controller ships before the catalogue marks anything.** The parser refuses a field it does not
  know, so a definition saying `issued-by` is refused by a controller older than this record.
 - What got harder: the controller now acts on a machine's report by itself, sending it once more after
  the first good start of a module given a value. A replacement that cannot be sent is kept sealed and
  carried by the next push, and said.
 ## How it is checked
 | Rule | Checked by |
 |---|---|
 | A given value read at start rotates like a made one | Controller inventory test: a value accepted for an at-start secret rotates, and is recorded as made. |
 | A given value is replaced once, after the first good start on it | Controller inventory test: a report of a declaration sent before the value was given replaces nothing; a report of an older declaration replaces nothing; the clean report of the declaration sent after it replaces it; the same report again, and the next declaration's report, replace nothing. |
 | An outside party's value is never replaced | Controller inventory tests: a value accepted for a secret marked `issued-by: outside` is not marked and not replaced after a start; `rotate` refuses it naming the issuer and the value's age; a definition changed to say `outside` after the value was given keeps it. |
 | An applied value, and one the mesh's own code accepted, stay as given | Controller inventory test: neither is marked or replaced after a start; `rotate` of an applied value is refused as not stageable. |
 | An adopted machine waits for the take | Controller inventory test: a module held as found keeps its given value through a clean report; after the take, the next clean report replaces it. A module no longer assigned is never replaced. |
 | A good start is a clean account of a declaration | Controller test: a refusal, a failure, or a bare word that the machine is there is not one. |
 | The definition says who issues a value | Catalogue test: `issued-by` is read, written back as read, and any word but `outside` is refused. |
 | The fact is stated, and permitted | Broker test: the controller's grant and its seat's emits both name `secret-replaced`, and nothing else is added. |
 | A rotation through the console carries why | Controller test: the `rotate` verb passes why and cause to `secret rotate`; why beside a provision is refused as passed over. |
 ## References
 - [ADR 0113](0113-the-vault-makes-every-secret.md): the decision this extends — what the vault cannot
  replace is what an outside party issued
 - [ADR 0114](0114-a-shared-credential-rotates-over-two-credentials.md): read at start and applied, and
  the staged rotation an applied secret waits for
 - [ADR 0092](0092-an-operator-delivers-a-pair-credential.md): a delivered pair credential, unchanged
 - [ADR 0100](0100-a-node-in-use-is-adopted-before-it-is-converged.md): an adopted machine, and the take
 - [To-be 13](../03-DESIGN/01-to-be/13-credentials-and-their-rotation.md): the design this amends
 - [To-be 45](../03-DESIGN/01-to-be/45-a-core-that-cannot-fail-silently.md) §7: the hand-act log a rotation's why is recorded in
@@ -1,177 +0,0 @@
 ---
 topic: the mesh
 status: accepted
 date: 2026-10-06
 deciders: jochen
 reconstructed: false
 extends: 02-DECISIONS/0227-the-core-holds-nine-rules-each-checked-and-is-built-to-them-in-six-phases.md
 ---
 # 229. The core's order is a lease the store remembers, and an epoch a machine is sent once it reads one
 ## Context
 Phase 2 of [to-be 45](../03-DESIGN/01-to-be/45-a-core-that-cannot-fail-silently.md) — *order and one
 writer* — was built on 2026-10-06 in the controller, the node-engine, the providers' loop and the
 SDK's. The design states the lease, the epoch, the report's order and the brake in a paragraph each;
 building them met questions the paragraphs do not answer, and each was answered in code. This record
 is those answers, so the design can say them and the next build does not answer them again.
 Four of them could not be left to taste:
 - **The node-engine decodes a declaration strictly** and refuses a key it does not know, whole. An
  epoch sent to every machine from the first controller that has one is refused by every machine
  not yet updated — and a refused declaration is also the one that would have updated its
  node-engine, so a machine asleep through the rollout could never catch up.
 - **The epoch is a bucket revision, and a bucket can be raised again from nothing.** A bus whose data
  directory was replaced starts its revisions at one, and every machine that heard epoch 57 would
  refuse the next controller for ever.
 - **A command at a shell sends declarations too** — the installer's first pushes, a lab step, a
  person repairing a mesh whose controller is down ([issue 201](../04-ISSUES/201-a-push-recreated-the-controller-behind-the-row-its-successor-wrote/00-report.md)).
  "Only the holder acts" read strictly would stop the installer at its first push.
 - **A controller's grant on the bus is composed by the controller, and the live bus holds the list the
  previous build composed.** A controller that needs a grant for its lease's bucket before it may act
  cannot send the list that grants it.
 ## Considered Options
 1. **Send the epoch to every machine and roll the node-engine out first**, as ADR 0227's consequences
   suggest. Rejected: it relies on every machine being up for the node-engine's rollout, and strands
   one that is not.
 2. **The epoch outside the signed bytes**, where a strict decoder does not look. Rejected: a broker
   could then give an old declaration a new epoch, and the order of declarations is the one property
   their signature does not already protect.
 3. **The epoch inside the signed bytes, sent to a machine only once its node-engine has said it reads
   one.** Chosen.
 4. **A one-off command takes no part in the lease**, and is refused while a controller serves.
   Rejected for the installer above.
 5. **A controller that cannot take the lease refuses to act.** Rejected for the grant above: it could
   never send the user list that grants it.
 ## Decision
 **The lease.** The controller's lease is the key `holder` in the bucket `mesh-controller_lease`, whose
 age is fifteen seconds; the holder renews it every five by compare-and-set at the revision it last
 wrote. Its value names the instance (machine, process, start), its build, its epoch, and when it was
 taken and renewed. **A holder stops acting three seconds before its key could expire unrenewed**, by
 its own clock, whatever its renewing goroutine is doing; a renewal refused or failed is the lease lost,
 said, the instance's epoch recorded as lost, and the process exits to be started again as a candidate.
 A holder that stops gives the key back, so the next takes it at once. The serving controller takes the
 lease before it asserts the bus's objects, and a candidate waits, said once per holder.
 **The epoch never goes backwards.** Every epoch issued is kept in the controller's store with its
 instance, when it was taken and how it ended: given back (`released`), lost by its own renewal
 (`lost`), or found gone by the next holder (`expired`). The highest is a floor: a lease bucket whose
 revisions are at or under it was raised again from nothing, and its stream is compacted past the floor
 before the key is taken — said as a condition, S12.
 **A controller the bus refuses the lease, with nobody holding it, serves without one**, as every
 controller did before: its declarations carry no epoch, which no node-engine refuses; it says so as
 the urgent condition S12 names, and tries again every five seconds. The first push of the machine
 holding the bus sends the user list that grants it. One that finds another took the lease meanwhile
 stops.
 **A command run at a shell** acts under the holder's epoch, read at the moment it acts, while a
 controller holds the lease — it is the same mesh's word, composed under the same hold of each machine —
 and under a lease of its own, given back as it ends, while none does. A process with no bus configured
 claims no epoch.
 **What carries the order on the wire** — the contract, written once on each side (the controller's
 `internal/link/order.go`, the node-engine's `internal/link/messages.go`):
 | Where | Key | Holds |
 |---|---|---|
 | a declaration, inside the signed envelope | `epoch` | the lease epoch it was composed under; absent claims none |
 | | `sequence` | its number for that machine (issue 107); absent claims none |
 | a report | `epoch`, `sequence` | the order of the declaration the report is about |
 | | `report_sequence` | the node-engine's own number for the report, kept on disk, growing across restarts and self-updates; **its presence says the node-engine reads `epoch`** |
 | | `older_than` | on a refusal of a declaration older than one applied: the order of the one held |
 | | `refused_older` | how many declarations the node-engine has refused as older, ever, on every report |
 - **A machine is sent `epoch` only while its latest account carried a `report_sequence`.** One that
  stops carrying it — a node-engine rolled back — is sent none again.
 - **A node-engine refuses by epoch only when both declarations claim one**: an older epoch, or the
  same epoch and a lower sequence. A declaration with no epoch is taken by its sequence, so a
  controller rolled back to a build without the lease is never stranded; that gives up the epoch's
  protection for as long as such a build runs.
 - **The controller keeps the account of each machine by its order**: by epoch where both claim one,
  then by sequence, then by report sequence, and refuses an older account — said, counted, and the
  machine's facts in it kept as before. An account without a report sequence, from an older
  node-engine, is judged by the digest it names (issue 267), and clears the order kept.
 - **What the mesh would send a machine is composed with the epoch it was last sent**, as with its
  sequence: a new holder of the lease is not a change of the machine.
 **Stale refusals name their writer** (S13): a declaration refused as older is counted against the
 controller epoch it claimed, named from the store's record of epochs with how that epoch ended; an
 account the controller refused is counted against the machine's node-engine; and what a machine's
 `refused_older` rose by beyond the refusals heard is counted as refusals whose reports were lost.
 **One writer is enforced where grants are composed.** The writers table is compiled into the
 controller with, for each state the bus carries, the subjects a write of it publishes to and who its
 writer is; a principal whose grant overlaps another writer's subject is refused at composition, naming
 the state and its writer. The controller's own grant loses `mesh.control.>`, which it never published
 and which made it a second writer of every machine's report. The stream-definition row names stream
 creation, update and deletion and durable consumer creation — not every consumer creation, because a
 module watching its own bucket makes an ordered consumer that defines nothing the mesh keeps.
 **A plan is written by compare-and-set** on a revision the store keeps beside it, and carries the epoch
 that wrote it; a write against a plan moved since is refused, and nothing is written by a process that
 may not act.
 **The empty-on-error lint** is a test over the repository's own source: a `return` inside an
 `if err != nil` branch that answers an empty collection and no error fails it, unless a comment
 `empty-on-error: <why>` on the line or above says why empty is the truth there.
 **Every consumed message kind has a contract**: how an older one is refused, with the tests that deliver
 the newer and then the older, or why none is needed. A check fails a kind the controller can be handed
 without one, and one naming a test that does not exist.
 **The withdrawal brake** (the providers' loop, Go and the SDK's alike): a pass that would withdraw more
 than one consumer, or more than half of those held where it holds more than one, withdraws nothing;
 each consumer it keeps is announced `provisioner.failing` with the class `withdrawal-braked`, so the
 controller raises it as a condition (ADR 0224); and while the mesh goes on not asking for them, one is
 let go every hour, said. A consumer asked for again is kept. **The brake stops the bulk, not the
 intention**: an unassignment of many completes without a hand, a mistaken one costs at most one consumer
 an hour while the operator is told — and withdrawal destroys no data since issue 241.
 > **Replaced in part — 2026-10-06, by [ADR 0230](0230-a-consumer-the-mesh-stops-asking-for-is-retired-and-deleted-only-by-a-person.md).**
 > The paragraph above no longer stands; the operator decided against releasing one consumer an hour.
 > A consumer the mesh stops asking for is now *retired* — disabled, reversibly, and marked to delete —
 > once the same result holds for five passes and ten minutes; a set of more than three, or more than
 > half of those held, waits for a person's `retire approve`; and only `cleanup delete` deletes. Every
 > other decision in this record stands. The *how it is checked* row for the brake is replaced by 0230's.
 **What Phase 1 decided while building** — [issue 270](../04-ISSUES/270-phase-1-watches-signals-that-come-later-and-hears-only-the-controllers-faults/00-report.md)'s
 decisions 1 to 6: the condition history as a bucket of its own, the events' shape, a key's last token,
 the probe DW, which deleted consumers are said, and the bounds the design left to the build — is taken
 into to-be 45 as built, and S12 and D5 move to Phase 2, S14 to Phase 5, as that issue asked.
 ## Consequences
 - **The rollout is the node-engine first, then the controller**, as ADR 0227 says — but the order no
  longer has to be exact. A machine on an older node-engine is sent no epoch; one that updates later
  is sent it from its first ordered report.
 - **The first controller with a lease on the live mesh serves without it** until the user list that
  grants its bucket reaches the bus, and S12 says so, urgent. A push of the machine holding the bus
  ends it.
 - **Two controllers at once are now the lease's to settle**, not the consumers' binding (issue 213's
  standing by), which stays as a second guard.
 - **The TypeScript providers' brake is said in their journal only**: the SDK's loop does not announce a
  provider's standing at all (ADR 0224 is in the Go loop), so a braked withdrawal there is not a
  condition until it does.
 - **The lint runs in the controller's repository.** The node-engine's and the node tools' carry their
  own copy when they take it up; until then they are not covered.
 ## How it is checked
 | What | Checked by |
 |---|---|
 | the lease: one holder, a waiting second, a handover at a higher epoch, a loss acting on nothing | `internal/lease` tests and the controller's `TestTwoControllersOneActs`, against a real bus and store |
 | an epoch never issued twice | `TestAnEpochIsNeverIssuedTwiceWhenTheBucketStartsOver`; live, D5 and S12 |
 | the contract | `internal/link/order_test.go`, beside the node-engine's own tests of the same cases |
 | an account kept by its order | the report's contract tests (`heard_order_test.go`); live, S13 |
 | one writer at composition | `internal/broker/writers_test.go`: the table is the design's, a whole mesh composes, a second writer is refused |
 | a plan by compare-and-set | `TestAPlanIsWrittenByCompareAndSetUnderTheLease` |
 | empty on error | `internal/lint`, over the whole repository on every test run |
 | every consumed kind | `TestEveryConsumedKindHasAContract` |
 | the brake | the providers' `brake_test.go` (issue 241 replayed with seven consumers) and the SDK's test |
@@ -1,219 +0,0 @@
 ---
 topic: the mesh
 status: accepted
 date: 2026-10-06
 deciders: jochen
 reconstructed: false
 extends: 02-DECISIONS/0229-the-cores-order-is-a-lease-the-store-remembers-and-an-epoch-a-machine-is-sent-once-it-reads-one.md
 ---
 # 230. A consumer the mesh stops asking for is retired, and deleted only by a person
 ## Context
 **This is the operator's decision, taken on 2026-10-06**, the day the withdrawal brake of
 [ADR 0229](0229-the-cores-order-is-a-lease-the-store-remembers-and-an-epoch-a-machine-is-sent-once-it-reads-one.md)
 was built. The model below — the three states, the stable result, the threshold that hands the act to a
 person, the cleanup verbs, the thirty-day reminder — is the operator's direction, recorded here as given.
 What the record adds is the evidence it rests on and the facts the build had to settle.
 **What the brake did.** A provider's loop ([ADR 0224](0224-a-provider-that-keeps-failing-a-consumer-is-a-problem-the-controller-reports.md),
 in the Go providers and the SDK's) that would withdraw more than one consumer in a pass, or more than
 half of those it held, withdrew nothing and announced each kept consumer as failing; then, while the mesh
 went on not asking, it let one go every hour, with no person involved. So a mistaken unassignment of
 seven consumers still completed by itself in seven hours, and a person who did not read `status` in that
 time lost all seven.
 **What withdrawal does today**, since [issue 241](../04-ISSUES/241-one-unreadable-grants-file-dropped-every-database-on-the-control-node/00-report.md):
 nothing a provider withdraws is destroyed in the providers that issue names — the relational database
 locks the role and keeps the database; the SQL Server provider disables the login; the document store
 strips the user's roles; the object store revokes the key and keeps the bucket; the mail server disables
 the mailbox; the forge prohibits the login; the analytics site is kept. But three things were still
 wrong:
 - **The identity provider deleted the client.** Its withdrawal was a `DELETE` of the consumer's client,
  outside issue 241's list; the secret, redirects and mappers went with it.
 - **Nothing recorded that a withdrawal happened, or when.** A locked role is indistinguishable from one
  an operator locked by hand. On the home server one consumer's login has been locked by an earlier
  withdrawal, its database kept, with no record of when or why; on the control node six databases set
  aside during issue 241's recovery sit under a dated name, which is the only record of them.
 - **A restart forgot.** The loop withdrew only what *this process* had made. A consumer unassigned while
  its provider was down was never withdrawn at all — its login stayed open, indefinitely.
 **And nothing ever deleted anything**, so withdrawn data accumulates with no surface that says it is
 there.
 ## Considered Options
 1. **Keep the hourly release.** Rejected by the operator: it lets the mesh finish, unattended, an act the
   bound exists to question. Many changes at once means a person is at work, and that person can confirm
   once.
 2. **Delete after a grace period.** Rejected: a timer is the mesh acting alone again, only later; the
   loss in issue 241 was data nobody had decided to lose.
 3. **Withdraw at once, below the bound, as before.** Rejected: one pass is one read of one file, and
   issue 241 was one bad read. A result has to hold before it is acted on.
 4. **Three states — active, retired, deleted — where retiring is reversible and automatic only when
   stable and small, and deleting is always a person's act through the controller, executed by the
   provider.** Chosen.
 ## Decision
 **1. A consumer is ACTIVE, RETIRED or DELETED.**
 - **Retired**: the mesh stopped asking for it. The provider **disables its access** — reversibly — and
  **marks its login and data "to delete", with when and why**. Nothing is deleted. Asked for again, the
  provider's ordinary create re-enables it at once, as it was, and clears the mark. A provider that
  has no non-destructive way to disable does **not** fall back on its removal: it is **mark-only** —
  the consumer keeps its access, is marked retired and needing deletion, and is said and announced (§2).
 - **Deleted**: only through `cleanup delete`, after a person approved it.
 **2. What "disable" means, per provider kind** — each the smallest reversible switch that stops the
 consumer reaching its data, keeping everything else; or, where a provider has none, nothing at all:
 | Provider | Retired is | Kept | Mark |
 |---|---|---|---|
 | postgres | the role set `NOLOGIN`, its open sessions ended | the database, its owner and grants, every byte; `CONNECT` is not revoked and the database still accepts connections, so the nightly dump still backs it up | the role's comment, a JSON object naming the consumer's machine, when and why |
 | keycloak, the identity provider | the client `enabled: false` — the server refuses its authorization and token requests | its secret, redirects, mappers and every other setting | the client's attributes `mesh.retired` and `mesh.retired-why` |
 | a TypeScript provider whose adapter has `retire` (and, if its create does not undo it, `reenable`) | what its `retire` disables | what its `retire` keeps | what its `retire` writes |
 | a TypeScript provider without `retire` — **mark-only** | **nothing changes in the backend: the consumer keeps its access** | everything | the loop's own record, "retired, access kept, needs deletion", said loudly, announced, shown by `cleanup list` |
 **`remove` is never called to retire.** A TypeScript adapter's `remove` is what it did on withdrawal, and
 several destroy something a person has not decided to lose — the secrets vault unlinks the ledger file
 holding the secret, the public DNS provider deletes the record, the message brokers delete the user. So
 an adapter without a non-destructive `retire` is mark-only, and `remove` is reached only as the delete of
 a provider without one of its own, through a person's `cleanup delete`. Today **every TypeScript provider
 is mark-only**, because none has a `retire` yet: redis, mosquitto, minio, umami, mssql, mongodb,
 influxdb, the secrets vault (mesh-vault), mailu, gitea and cloudflare-dns. Each leaves mark-only by
 adding a `retire` that disables — the SQL Server, document-store, object-store, mail and forge providers
 already have such a switch in their `remove` (disable the login, strip the roles, revoke the key,
 disable the mailbox, prohibit the login), moved into `retire`.
 A mark-only retirement is kept in the provider's process, not its backend: a restart forgets it, and the
 consumer, still reachable, is no longer listed. That is the cost of a provider that cannot disable, and
 the reason to give each a `retire`.
 A database renamed aside — by postgres's `postgres_retire_database` tool or by hand, the
 `<name>_deleted_<date>` form — is listed beside the retired consumers, retired since that date, so a
 person sees it and can delete it.
 **3. Stable removals.** A provider retires a consumer only after it has seen **the same set** of
 consumers no longer asked for **both** in **five consecutive passes** that read the contributions file
 **and** for at least **ten minutes** since the first of them (the constant `StableFor` in the Go loop,
 `STABLE_FOR_MS` in the SDK's). At the loop's pass interval of five seconds, five passes alone are
 twenty-five seconds — shorter than a controller restart, a store reconnecting or a file half written —
 so the ten minutes are what a real hiccup has to outlast, and the five passes keep one slow pass from
 counting as agreement. A pass that could not read the file is not a result and starts both again; so does
 a different set. **Additions and changes to an existing consumer — create, rotate — act on the first pass
 and are never delayed.**
 **4. Too many is a person.** A stable set of **more than three consumers, or of more than half of those
 the provider holds where it holds more than one**, retires nothing. The provider **waits**: it says so in
 its journal and announces it, the controller raises an **urgent** condition listing what would be
 retired, and it waits for `retire approve <node> <provider-module>` or `retire reject <node>
 <provider-module>`. **An unassignment the controller itself made goes through the same threshold** — the
 operator's words: *too many changes means a human is actively working on it*, so one confirmation. The
 bound is the old brake's half, with three in place of one: one, two or three consumers of a larger
 provider go without a hand; two of two do not.
 - **Approve** retires exactly the set waiting — the provider refuses any other set, so a person approves
  what they were shown.
 - **Reject** keeps the set active; the provider does not ask about it again while the set stays the same.
  The rejection is held by the provider's process: a restart asks again, loudly. A rejected set can still
  be approved later.
 - **Settled**: a waiting or rejected set ends without retiring when the mesh asks for any of it again or
  the set changes; a new stable set starts the count over.
 **5. The backend remembers, not the process.** Each provider lists from its own backend what the mesh
 made, active and retired, with the mark. So a restart forgets nothing; a consumer the backend holds
 active and the mesh no longer asks for is retired by the same rules after a restart as before one; and a
 consumer **found disabled without the mark** — withdrawn before this record — is **adopted** as retired:
 marked, said, announced, its clock starting then. What the mesh made is known by the mark, or, before
 the mark existed, by its shape (postgres: a role valid until *infinity*, which only the
 mesh's role statement sets, owning a database of its own name; keycloak: the
 `mesh.provisioned` attribute it already had). Anything else is somebody else's and is never listed,
 retired or deleted.
 **6. Cleanup is the controller's verbs, executed by the provider.**
 - `cleanup list` — every retired consumer per provider: its age, its size where the backend can say,
  and why.
 - `cleanup delete <node> <provider-module> <consumer> --why` — one.
 - `cleanup delete --older-than <days> --why` — lists what it would delete; deletes only with the
  operator's explicit `--confirm`.
 - **The provider deletes**, because it owns its backend: the controller asks the provider's tool on that
  machine through the mesh, as any module's tool is asked, and never touches a backend itself. A provider
  refuses to delete anything active or asked for, and anything not retired.
 - **Every deletion is written to the hand-act log**, as is every approval and rejection — including one
  made by asking a provider's tool directly rather than through the controller. They are a person's decision
  by design, not a repair, so they never count toward the hand-act log's *healer wanted* (to-be 45 S15):
  a healer may not withdraw or delete data.
 **7. Every provider serves the same four tools**, the protocol between the verbs and the providers:
 `provisioner_retirement` (what is held, waiting, rejected and retired), `provisioner_retire_approve`,
 `provisioner_retire_reject` and `provisioner_delete`, each act requiring a why. And says one event,
 `provisioner.retirement`, whose `change` is `waiting`, `settled`, `approved`, `rejected`, `retired`,
 `reenabled`, `deleted` or `adopted`; the controller derives the permission to publish it for every module
 that receives contributions, as ADR 0224 does the standing events.
 **8. Nothing is silent.** Retire, approve, reject, re-enable and delete are each announced and said in the
 provider's journal; waiting is an urgent condition and a rejection a warning one, both naming the
 provider and its machine; and a self-check probe raises a **low-severity `cleanup-waiting` condition**
 for any provider holding something retired **more than thirty days**.
 **9. The withdrawal brake paragraph of ADR 0229 is replaced by this record.** The rest of 0229 — the
 lease, the epoch, the report's order, one writer at composition, the plan by compare-and-set, the lint,
 every consumed kind's contract — stands unchanged.
 ## Consequences
 - **The first rollout surfaces what is already there.** On the home server the consumer locked by an
  earlier withdrawal is adopted as retired; the control node's six set-aside databases are listed, and
  raise `cleanup-waiting` thirty days after their date; any consumer a backend holds open that the mesh no
  longer asks for becomes a retirement — waiting for a person if there are more than three. Nothing is
  deleted by the rollout.
 - **Retired data is still backed up and still takes space** until a person deletes it. That is the
  point; the thirty-day condition is what keeps it from being forgotten.
 - **A person who rejects must come back.** A rejected set is kept active and said as a warning until the
  mesh asks for it again or someone approves it.
 - **The TypeScript providers get the stable count, the ten minutes, the threshold and mark-only** from
  the SDK's loop on their next build (every catalogue provider's range accepts it). Mark-only is safe —
  nothing is destroyed — and weak: the consumer keeps its access, and a restart forgets the mark. A set
  over the bound there waits with no way to approve it until each provider passes its module name and an
  announcer to the loop. Until each adds a `retire` and that wiring, they are covered for safety and not
  for disabling or cleanup, and the record says so rather than claiming otherwise.
 - **The Go loop is still two identical copies**, in postgres and keycloak,
  held together by a test — now over three files. Its home is the Go SDK ([ADR 0039](0039-what-the-sdk-holds-and-refuses.md));
  moving it there means a tagged SDK release before the catalogue can use it, a separate change.
 - **The rollout order**: the controller first (it derives the permission to publish the new event and
  hears it; an older controller makes the provider's announcement a refusal the provider logs), then the
  catalogue's two Go providers, then the SDK's release and each TypeScript provider as it is rebuilt.
 ## How it is checked
 | What | Checked by |
 |---|---|
 | a transient empty list for four passes retires nothing; five passes in twenty-five seconds retire nothing, the same set held ten minutes does; ten minutes in fewer than five passes do not; an unreadable pass and a changed set restart the count; additions and changes are not delayed | the catalogue's shared `retirement_test.go` (identical in both Go providers) and the SDK's `retire.test.ts` |
 | over the bound waits, is announced and said, again every fifteen minutes; approve takes only the exact set; reject keeps it and is not asked again; a set asked for again settles | the same tests |
 | retired is disabled with data intact; asked for again it is enabled as it was | postgres's `live_test.go` and keycloak's `live_retire_test.go`, against throwaway servers |
 | delete removes only that consumer, never an active or asked one | the same live tests, and `retirement_test.go` |
 | a restart retires what the backend holds unasked and adopts what it finds disabled | `retirement_test.go`, the provider's inventory tests |
 | the conditions, verbs, hand acts and the thirty-day probe | the controller's tests of the event, the verbs against a fake provider on a real bus, and the probe |
 | an adapter without `retire` is mark-only: `remove` is not called on retirement, the consumer is marked with its access kept and said loudly, and `remove` runs only on a person's delete; `reenable` runs before create for a retired consumer asked for again | the SDK's `retire.test.ts` and `sdk.test.ts` |
 | the two Go copies agree | `harness_same_test.go` in each provider, over the three files |
 | live, after rollout | `cleanup list` names the adopted and set-aside entries; `conditions` shows no `retire-waiting` on a mesh nobody is changing |
 ## References
 - [ADR 0229](0229-the-cores-order-is-a-lease-the-store-remembers-and-an-epoch-a-machine-is-sent-once-it-reads-one.md)
  — replaced in part: its withdrawal brake paragraph. Everything else in it stands.
 - [ADR 0227](0227-the-core-holds-nine-rules-each-checked-and-is-built-to-them-in-six-phases.md) rule 4,
  *nothing dropped silently* — which this keeps: a stable result over the bound stops and raises a
  condition.
 - [ADR 0224](0224-a-provider-that-keeps-failing-a-consumer-is-a-problem-the-controller-reports.md)
  — the provider's events and their derived permission, which the retirement event follows.
 - [Issue 241](../04-ISSUES/241-one-unreadable-grants-file-dropped-every-database-on-the-control-node/00-report.md)
  — what withdrawal destroyed, and what it stopped destroying.
 - [To-be 45](../03-DESIGN/01-to-be/45-a-core-that-cannot-fail-silently.md) §2, §4, §7 and Phase 2, and
  [the module protocol](../03-DESIGN/01-to-be/19-the-module-protocol.md), amended alongside.
 - mesh-catalog `modules/postgres` and `modules/keycloak` (`retirement.go`, `retire_pg.go`, `oidc.go`);
  mesh-sdk `src/provisioner` 0.1.12; mesh-controller's `retire` and `cleanup` verbs and its probe.
@@ -1,158 +0,0 @@
 ---
 topic: the mesh
 status: accepted
 date: 2026-10-06
 deciders: jochen
 reconstructed: false
 extends: 02-DECISIONS/0227-the-core-holds-nine-rules-each-checked-and-is-built-to-them-in-six-phases.md
 ---
 # 231. A healer acts on what observation raised, and only observation says it worked
 ## Context
 Phase 3 of [to-be 45](../03-DESIGN/01-to-be/45-a-core-that-cannot-fail-silently.md) — *healers* — was
 built on 2026-10-06 in the controller and the node-engine. §7 of the design gives each healer a row:
 the condition, the repair, the budget and what happens then. Building them met questions the rows do
 not answer, and each was answered in code. This record is those answers.
 Five could not be left to taste:
 - **Where a budget is counted.** A budget kept in the controller's memory is reset by every restart,
  and a controller restarting in a loop is exactly when a healer must not start counting again. A
  budget kept in the condition is lost when the condition clears and reopens — which a repair that
  half-works makes happen every few minutes.
 - **When an act has failed.** A repair is made in a moment; whether it worked is known only when the
  watchdog or the probe that raised the condition looks again — thirty seconds for a watchdog, five
  minutes for a probe.
 - **What a healer may send.** H1's repair is "send the current declaration again", which is what a
  named push does — and a named push sends a machine the builds a policy or a plan is holding back
  ([ADR 0221](0221-a-push-sends-no-build-a-policy-or-a-plan-holds-back-except-to-the-machine-it-names.md)).
  A person naming a machine means it; a healer does not.
 - **What triggers H4.** The design names S9's `slow-consumer`. The controller hears a slow consumer for
  its own connection only until the bus has a system account
  ([issue 270](../04-ISSUES/270-phase-1-watches-signals-that-come-later-and-hears-only-the-controllers-faults/00-report.md)),
  and a slow *connection* is not a consumer a reset repairs. What 248 met — a durable consumer a week
  behind its stream — is what D6 finds.
 - **How the machine is asked to report.** The design gives the node-engine a `report` verb. A machine's
  bus user may not answer anybody's inbox, and granting it that is a second channel out of every
  machine.
 ## Considered Options
 1. **Budgets in memory, success when the repair returns.** Rejected: a restart resets every budget, and
   "the act returned" is the healer's opinion of its own work — the second answer to a question
   rule 1 says has one.
 2. **Budgets in a bucket on the bus.** Rejected: the bus's user list must grant a new bucket before the
   first heal could be counted, so the first controller with healers would heal uncounted on the live
   mesh until the bus's machine was pushed.
 3. **Budgets in the controller's store, each act begun before it is made; success only as the
   condition's clearing; H4 on D6's own kind; the machine answering through its ordinary report.**
   Chosen.
 ## Decision
 **A healer is a row of the healer registry**, compiled into the controller: the condition kinds it
 answers, its repair, its budget (acts against one *budget key* within a window), its **settle** (how long
 after an act the observation is given before the next act or the escalation), what happens when the
 budget is spent, where the repair runs, and the event each act is said as. A test generated from the
 registry holds every row to a kind the mesh raises — a row of the signals table, a probe of the
 self-check, a provider's event — a budget, a settle inside its window, and its event, and every healer
 the controller runs to an induced failure that sees it act and brake.
 **The healers of Phase 3:**
 | Healer | Answers | Repair | Budget, settle |
 |---|---|---|---|
 | H1 | `sent-not-reported` (S2) | ask the machine's node-engine to report again; if it does not then report the declaration it was sent, or says nothing within 45 s, send it again — never moving a build a policy or a plan holds back | 2 per condition in 6 h; 3 min |
 | H2 | `stalled` (S3) on a wait that is **superseded** (a newer plan of the same repository and branch exists) or **finished** (every module of every tier built or failed, every one that rolls out sent) | close the plan with its note — `superseded`, naming the newer plan, or `done`; what it asked still builds | 1 per plan in 24 h; 2 min |
 | H3 | `holder-silent` (D3), `consumer-lost` (D6, S9) | assert the bus's streams, consumers and seat workers — the assertion every send makes (issue 208) | 1 per object in 1 h; 6 min |
 | H4 | `consumer-behind` (D6) on a consumer the stream table marks resettable | `broker consumer-reset` | 1 per consumer in 24 h; 6 min |
 | H5 | `provider-failing`, the identity provider's administrator refusing the mesh's secret | the provider's own repair (ADR 0224 §5), registered and not run by the controller | the provider's |
 - **A condition a healer does not apply to is left alone.** H2 passes over a plan waiting on something
  still to come; H4 over any consumer not marked resettable. Passing over is not an attempt: no budget,
  no escalation, said once in the controller's journal. **Only the controller's own events consumer is
  marked resettable**, with why in the table: what a reset drops is caught up — a merge by the catch-up
  pass that reads the forge (issue 266), a build's outcome from the build records (issue 214), a
  provider's failing word said again within a quarter of an hour (ADR 0224). A module's consumer is
  never: nothing would catch up for it.
 - **A send by a healer is a push that did not name the machine** (ADR 0221): a machine whose
  composition would move a held build is not sent again, and the attempt says so and why.
 - **D6's far-behind finding has its own kind, `consumer-behind`**, so H4 answers it and nothing a reset
  cannot repair; a probe's registry row names the kinds its findings carry besides its own.
 **Every act is begun in the controller's store before it is made**, under the lease and carrying its
 epoch, and finished after it: `acted`, `failed`, or `escalated`. The budgets and the brake are counted
 from there, so a controller dying mid-act has still spent it, and one restarting in a loop resets
 nothing. Only the controller holding the lease heals; one serving without it (S12) heals nothing — a
 repair is the one act that can always wait.
 **Success is never a healer's to say.** An act is kept in its condition's `tried` as `healer Hn`, the
 resolver becomes `healer:Hn`, and the condition stays open until the watchdog or probe that raised it
 no longer observes it. A condition cleared and reopened within ten minutes carries what was tried. **A
 spent budget** — the budget's acts made, the last one's settle past, the condition still open — hands
 the condition to the operator: resolver `operator`, severity `urgent`, an attempt saying what was tried.
 An observation does not lower an escalated condition's severity again, and no healer touches it until it
 clears.
 **Every act is said** as the controller seat's event `healer-acted`: the healer, the condition and its
 kind, the act, the outcome, where the budget stands, the epoch, and the verb that shows more. A heal is
 never written to the hand-act log, which is how S15 tells a repair the mesh made from one a person had
 to. `healers` lists the registry, the acts lately and the brake; `status` counts the week's heals.
 **The mesh-wide brake.** Twelve acts in an hour, all healers together, and every healer stops: the
 urgent condition `mesh.healers.braked` names which healer acted on what, and the brake holds until an
 hour after the last act. A healer looping is then at most a dozen acts, said, never the incident.
 Escalations are sayings, not acts, and are not counted.
 **The `report` verb, as built.** The controller asks on `mesh.node.<machine>.ask.report`, on core NATS,
 which each machine's bus user may subscribe to for its own name only. The node-engine enqueues a
 reconcile — the one apply queue's ordinary act — whose account of the declaration it keeps is said
 whether or not it is news; a delivery waiting meanwhile is applied and reported instead. **The answer is
 the machine's ordinary report** on its own report subject: nothing new is published and nobody's inbox
 is answered. A node-engine older than the verb hears nothing, and H1 then sends again, as a person did.
 **S15, as built.** The watchdog reads the hand-act log's fortnight every half minute; a cause recorded
 twice within fourteen days raises `mesh.hand-acts.<cause>.healer-wanted`, naming the acts, who and why —
 and, where a healer answers that cause, that it was not enough. It clears when fewer than two acts of
 that cause remain within the fortnight.
 ## Consequences
 - **The controller, the bus's user list and the node-engines roll out in any order**: a machine whose node-engine cannot hear the question is sent again instead, and a
  bus whose user list does not yet grant `healer-acted` refuses only the event — the act and `tried` still
  say it. A push of the machine holding the bus ends that.
 - **H1 sends what a push of the machine would, minus what is held back.** A send that went unreported
  because the machine holds a held build is not repaired by a healer: its two attempts say why, and the
  operator's `push <machine>` is still the way, recorded as a hand act.
 - **Twelve an hour is a guess**, like Phase 1's first bounds: corrected from the live week, in the
  registry, reviewed like code.
 - **A heal that half-works costs a few acts, then a person.** The settle and the budget make the
  slowest probe the pace: H3 and H4 act at most once per object an hour and a day.
 - **Not built:** the induced failures on a lab mesh (mesh-lab); a healer for the commonest remaining hand
  acts that have none — a ban lifted, a kept file restored — which S15 will now ask for by name.
 ## References
 - [To-be 45 §7](../03-DESIGN/01-to-be/45-a-core-that-cannot-fail-silently.md) — the design this record
  details.
 - [Research 031, evidence §(f)](../01-RESEARCH/031-a-core-that-cannot-fail-silently/01-evidence.md) — the
  hand acts the healers replace.
 - [Issue 208](../04-ISSUES/208-a-seats-worker-is-made-only-when-the-controller-starts/00-report.md) — H3 as
  the send's own assertion, for D3 and D6 alike.
 - mesh-controller and mesh-host, branch `feat/a-core-that-cannot-fail-silently-phase-3`.
 ## How it is checked
 | What | Checked by |
 |---|---|
 | every healer answers a raised kind, with a budget, a brake, an event and an induced failure | `TestEveryHealerAnswersAKindTheMeshRaisesWithABudgetABrakeAndItsEvent` |
 | H1 asks, sends again, keeps `tried`, says `healer-acted`, escalates and stops | `TestH1AsksAMachineToReportAndSendsItAgain` |
 | H2 closes a superseded plan and leaves one still waiting | `TestH2ClosesAPlanAnotherHasTakenOver` |
 | H3 against a real bus: repaired, cleared by the probe, escalated after its budget | `TestNatsH3AssertsAMissingConsumerAgainAndBrakesAfterItsBudget` |
 | H4 against a real bus: reset, cleared by the probe, and the controller still hears | `TestNatsH4ResetsTheControllersEventsConsumerAndItStillDelivers`, `TestH4ResetsOnlyWhatTheTableMarksResettable` |
 | the brake, and no heal without the lease | `TestTheBrakeStopsEveryHealerAndSaysSo`, `TestNoHealerActsWithoutTheLease` |
 | the `report` verb | mesh-host `internal/link/asked_test.go`, against a real bus; the grant in `TestNatsAskToReportReachesTheMachine` |
 | S15 | the signals table's generated test, and `TestARepeatedHandActNamesItsCauseAndItsHealer` |
 | live | `healers`, each condition's `tried`, and the hand-act log's weekly count in `status` |
@@ -1,143 +0,0 @@
 ---
 topic: what runs on it
 status: accepted
 date: 2026-10-06
 deciders: jochen
 reconstructed: false
 extends: 02-DECISIONS/0110-a-seat-is-a-module-assignment-from-a-closed-set.md
 ---
 # 232. A binding to a consumer's data moves only by a person
 ## Context
 **A rule written for the resolver moved a machine's databases.** [Issue 258](../04-ISSUES/258-every-machine-bound-the-resolver-to-itself/00-report.md)
 found that a machine running its own provider of a mesh-wide provision bound its consumers to that
 provider, even when the mesh's seat for the provision was held elsewhere. Its fix made the seat's
 holder, or a pin naming another machine, win over the local provider. That is right for the mesh's
 resolver: every resolver gives the same answer, so a consumer moved between two loses nothing.
 The fix applied to every seat that delivers a provision. The store's seat delivers the relational
 database. On the home server, which runs its own store with five applications' databases in it, the
 fix's first push re-bound all five to the store on the control node, which holds the seat. That store
 did what a provider does for a new consumer: it made each one an empty database. The applications
 started, ran their first migrations, and served empty data for about twenty hours. Nothing warned
 ([issue 273](../04-ISSUES/273-a-rule-for-the-resolver-moved-a-machines-databases/00-report.md)).
 Nothing was lost, only because the old store kept everything.
 The incident has two parts:
 1. **Issue 258's rule applies to two kinds of provision as if they were one.** It does not say which
   kind it is for.
 2. **Nothing in the mesh knows where a consumer's data is.** A resolution answers one question:
   *which provider would I choose now?* Every input to that answer can change under a consumer without
   anybody meaning to move it: the seat's holder (a handover, ADR 0131), a pin added or removed, a
   provider assigned or unassigned. Only the pair secrets in the store held a trace of the old
   binding, and only because a new pair was minted beside it.
 ## Considered Options
 1. **Revert issue 258's fix.** Rejected. It was correct for the resolver, and the resolver would
   break again.
 2. **Make the store's seat not deliver its provision.** Rejected. That fixes one seat, and the next
   seat that delivers a provision which keeps data repeats the incident.
 3. **Refuse any resolution that changes a binding.** Rejected. It would refuse the resolver's moves,
   which are the point of 258, and a person moving a database on purpose would have no way to do it.
 4. **Know which provisions keep their consumers' data. For those, keep each consumer where it was
   last sent, say every move the mesh would have made, and let only a pin move it.** Chosen.
 ## Decision
 **1. An offer says whether it keeps its consumers' data.** The field is `keeps-consumer-data` on
 `provides`.
 - If unsaid, a provider that **grants** each consumer a credential of its own keeps that consumer's
  data. The grant makes an account (a role and its database, a key and its bucket, a client), and
  what the consumer writes under it stays with that provider.
 - A provider that grants nothing keeps nothing of anybody's. Examples: the resolver, a CA, the
  artifact store, a route.
 - The property belongs to the provision's name, as brokering does (ADR 0009): if any provider says
  the provision keeps data, it keeps data.
 **2. Issue 258's rule is for provisions that keep nothing.** For a provision that keeps data, the
 seat's holder on another machine does **not** overrule a provider beside the consumer. A pin naming
 another machine still does, because a pin is a person.
 **3. Where each such consumer was sent is recorded, and a resolution keeps it there.** One row per
 consumer and provision is written when a declaration carrying the binding is sent. The provider is
 recorded by name, so a provider's machine leaving the mesh does not erase where the data is.
 - **Recorded binding, different provider chosen, no pin naming the new one:** the recorded provider
  keeps answering. The move is said.
 - **Recorded provider no longer provides the provision:** the machine's set is **refused**, naming the
  pin that would confirm the move. It is never answered by the provider chosen instead. This is ADR
  0009's stance, already applied to a pin naming a provider that is gone.
 - **New consumer with no record:** it binds as resolved, and is recorded when first sent.
 **4. Only a pin moves it.** The pin names the provider, for that machine and provision. The send
 that carries the move records the new provider and keeps where it was. The data is moved by a person
 before the push; the mesh does not move data.
 **5. Nothing is silent.** A kept move is printed by the push that composed it and raised at once as
 an **urgent** condition:
 > would move X's P from A to B — its data is on A; kept there. `pin …` to confirm a move (and move
 > the data first)
 A self-check probe ([to-be 45](../03-DESIGN/01-to-be/45-a-core-that-cannot-fail-silently.md) §4)
 checks every machine every run. It raises:
 - a kept move, as urgent;
 - a pinned move not yet sent, as a **warning**, so the data goes first;
 - any consumer about to be sent another provider than the one on record with no pin naming it, as
  **urgent**. The resolver makes this impossible; the probe exists for the day it is not.
 > **The mechanism changed — 2026-10-06, by [ADR 0233](0233-a-module-declares-the-data-it-holds-and-the-mesh-protects-and-watches-it-from-that.md).** The decision stands: a binding to
 > a consumer's data moves only by a person. What moved is how a provision is known to keep data: a
 > provider now says it in its `data` section, as a class for its consumers — irreplaceable, valuable or
 > rebuildable keep data, cache and none do not — and `module check` refuses a provider that grants
 > without saying it. `keeps-consumer-data` on the offer and the inference from `grants` are read only
 > from a definition already on the shelf.
 ## Consequences
 - **The first push after rollout records what each machine is bound to then.** A consumer moved
  silently before the rollout and never moved back would be recorded where it was moved to. The
  rollout therefore starts by checking that every binding to data points where the data is. On
  2026-10-06 every one did: the five moved consumers had already been pinned back.
 - **A pin is per machine and provision, not per consumer.** Pinning one consumer of a machine
  elsewhere pins all its consumers of that provision. That is how pins have always worked, and the
  warning names every consumer that would move.
 - **Unassigning a store beside its consumers now refuses their machine** until a person pins them
  elsewhere. Before this, they moved silently to whichever store answered.
 - **A retired consumer's binding stays on record** ([ADR 0230](0230-a-consumer-the-mesh-stops-asking-for-is-retired-and-deleted-only-by-a-person.md)).
  Assigned again, the consumer returns to the provider that kept its retired data.
 - **No module definition changes.** Every provider in the catalogue that keeps data already grants
  credentials, and none that keeps nothing does. A definition states the field only when the default
  is wrong for it.
 ## How it is checked
 | What | Checked by |
 |---|---|
 | the incident: a machine running its own store and its consumers, the store's seat held elsewhere — the consumers stay on their own store, and the resolver beside them still follows its seat | mesh-controller `internal/catalogue/bound_test.go`, and `cmd/mesh-controller/bindings_test.go` through the real stores; both fail without the fix |
 | a recorded consumer is kept when the seat's holder changes, and the move is said with its pin | `bound_test.go` |
 | a pin moves it; a gone provider, or a store beside it unassigned, is refused and never answered elsewhere | `bound_test.go`, `bindings_test.go` |
 | an offer's `keeps-consumer-data` is read and written, and unsaid follows the grant | `bound_test.go` |
 | a binding is recorded on send, a move keeps where it was, and a provider's machine leaving keeps the record | `internal/inventory/bindings_test.go` |
 | a push raises a kept move at once; the probe says kept (urgent), pinned and not yet sent (warning), and unasked (urgent) | `bindings_test.go` |
 | live, after rollout | the self-check passes its binding probe on every run, and `conditions` holds no `binding-kept` on a mesh nobody is changing |
 ## References
 - [Issue 273](../04-ISSUES/273-a-rule-for-the-resolver-moved-a-machines-databases/00-report.md):
  the incident.
 - [Issue 258](../04-ISSUES/258-every-machine-bound-the-resolver-to-itself/00-report.md): the rule
  this record limits.
 - [ADR 0110](0110-a-seat-is-a-module-assignment-from-a-closed-set.md): a seat's holder answers. This
  record extends it, because the holder now answers only where nothing is kept.
 - [ADR 0009](0009-modules-and-the-graph.md): refuse rather than guess.
 - [ADR 0230](0230-a-consumer-the-mesh-stops-asking-for-is-retired-and-deleted-only-by-a-person.md):
  the provider keeps a consumer's data until a person deletes it.
 - mesh-controller PR #86: `catalogue/bound.go`, the `binding` table (migration 0071), and the
  self-check's binding probe.
@@ -1,281 +0,0 @@
 ---
 topic: what runs on it
 status: accepted
 date: 2026-10-06
 deciders: jochen
 reconstructed: false
 extends: 02-DECISIONS/0232-a-binding-to-a-consumers-data-moves-only-by-a-person.md
 ---
 # 233. A module declares the data it holds, and the mesh protects and watches it from that declaration
 ## Context
 **This is the operator's decision, taken on 2026-10-06**, the day after five applications ran for
 twenty hours on empty databases ([issue 273](../04-ISSUES/273-a-rule-for-the-resolver-moved-a-machines-databases/00-report.md)).
 In the operator's words: modules must indicate the "data storage which should be monitored/protected",
 "in the module's manifest", "in a generic, configurable way". The ranking of what is precious is also the
 operator's, given the same day and recorded as given:
 > "data loss would be painful but not the end of the world. Only my plex storage is sacred and the photo
 > sites as well (I'm not sure everyone has a good backup themselves but it's their own responsibility)."
 > "we can't backup the plex storage, we don't have any storage for it, it's on a RAID5 which should be
 > safe as far as we can afford it. The plex metadata storage is not important" — and the metadata
 > "should be part of the standard backup plan of course".
 What the mesh knew about data before this record, measured on the code and the catalogue that day:
 - **Where a consumer's data is** was inferred, not said. [ADR 0232](0232-a-binding-to-a-consumers-data-moves-only-by-a-person.md)
  made a binding sticky when the provider *grants* a credential; no manifest in the catalogue stated
  `keeps-consumer-data`. A provider whose grants hold nothing — a cache — was sticky all the same.
 - **Backups were a second list.** [ADR 0214](0214-backups-guard-against-mistakes-and-stay-on-the-machine.md)
  had a module write `run` and `path` lines to the `node-backup` seat by hand; thirteen modules did,
  across two catalogues. The rule that "the catalogue check refuses a store provider that declares none"
  was never in `module check`: one controller test applied it to the catalogue checked out beside it,
  against a list of six provisions kept by hand.
 - **Unassigning a module kept its data only by accident of the host's rule.** The node-engine removes an
  orphaned directory only when it is empty; a directory with anything in it is **kept and forgotten** —
  its record dropped from the machine's store, the report saying "kept … remove it by hand once you know
  what it is". Nothing anywhere then knew the data was there, and the one instruction given was the one
  that destroys it.
 - **Nothing was measured.** No size, no last write, no check that a backup covered what mattered, and
  nothing that could tell an empty copy of a database from the full one beside it — exactly the shape
  of issue 273.
 - **The media library was out of every design** (ADR 0214 named it as not backed up), and the photo
  sites' storage lives in two providers, the object store and the document store, as consumer data
  whose preciousness only the photo application knows.
 ## Considered Options
 1. **Keep ADR 0232's inference and add a list of protected paths in the backup module.** Rejected: a
   second list is the failure ADR 0214 rejected ("whatever is not listed is unprotected, silently"), and
   an inference cannot say that a grant holds a cache.
 2. **Keep `keeps-consumer-data` on the offer, required, and add a separate `backups` field.** Rejected:
   two places for one fact, and a yes/no cannot carry the operator's ranking — a cache's consumers and a
   photo library's both "keep data".
 3. **Every declared item backed up, irreplaceable or not; the media library copied too.** Rejected by
   the operator: there is no storage for a copy of the media library. A class that forces a backup would
   make the most precious data undeclarable.
 4. **A class per item decides everything, including the protection.** Rejected for the same reason:
   how precious data is and how it is protected are two facts. The media library is the most precious
   thing on the mesh and the one thing that cannot be copied.
 5. **A per-module check in code ("postgres is a store").** Rejected: never per-module code; a new
   module would be unprotected until someone remembered it.
 6. **Array health watched by a new `node-storage` seat.** Deferred, not adopted: the only thing needed
   today is to *read* an array's health under declared data, and the backup holder already reads that
   data on every machine that keeps any. A seat for storage is right the day the mesh *acts* on disks
   (scrubs, replacing a member); that is not decided here.
 7. **One `data` section, a class for how precious, a protection for how it is kept, and everything
   derived from them.** Chosen.
 ## Decision
 **1. One section, `data`, says every kind of data a module keeps.**
 - `own`: a list of items, each `id`, `path`, `class`, and how it is protected. `path` names one of the
  module's directories, `${dir:<id>}`, or an operator's path it was given, `${access:<id>}`, or a path
  beneath either — never a machine path (ADR 0112).
 - `consumers`: per provision the module grants, the `class` of what it keeps for each consumer and
  `in` — the own item that holds it, or a provision the module itself requires (an identity provider
  keeps its clients in its database). **Any provider that `grants` must say this; `module check`
  refuses it otherwise.** The offer's `keeps-consumer-data` (ADR 0232) is still read from a definition
  already on the shelf, and refused by `module check` in a new one: it is said once, here.
 - `kept-by`: per provision the module requires, the `class` of what of its own lives with that
  provider. The photo sites' application says its objects and its database are irreplaceable; the
  object store and the document store are then held to that class for the machine and consumer
  concerned.
 - Each entry may carry `why`, a line for the reviewer.
 **2. Four classes, ranked by the operator.** A fixed vocabulary; a fifth is a decision.
 | Class | Is | Backed up | On unassign | Alerts |
 |---|---|---|---|---|
 | `irreplaceable` | what must never be lost: the media library, the photo sites' storage | a protection is **required**: a backup, or a declared redundancy | retired, never removed | **urgent** |
 | `valuable` | anybody's work, painful to lose: every store, mailboxes, repositories, the vault, the agent's home | **yes, by default** — the standard nightly plan, where the machine has a backup holder | retired, never removed | warning |
 | `rebuildable` | made again from elsewhere: a dump, a clone, thumbnails, Plex's metadata | **yes, by default**; may say `none` (the artifact store, downloaded models) | forgotten | none |
 | `cache` | disposable | never | forgotten | none |
 For consumers, `none` also exists: the provision keeps nothing of anybody's (a resolver). A binding to
 a consumer's data is sticky (ADR 0232) when the class is irreplaceable, valuable or rebuildable — not
 for a cache or none. **Redis is `cache`**: no module in this catalogue requires its provision, its name
 says what it is for, and a consumer keeping data in a cache would be the consumer's mistake, not the
 mesh's to make sticky.
 **3. Protection is its own field.** `backup` is `copy` (the holder reads the path as it stands),
 `none`, or `{dump, into}` — a command that writes a consistent copy into another item, which is copied
 (a running store's files are not a consistent copy). Unsaid, anything but a cache is copied. Or
 `redundancy: "<why that is enough>"`: the item is protected by the redundancy of the storage it is on,
 and the mesh watches that storage instead. **An irreplaceable item has a backup or a redundancy;
 `module check` refuses it with neither.** `within` bounds the age of its last good backup (48 hours
 unsaid, ADR 0214); `active` says it is written all the time and how long quiet is a fault.
 **4. The backup holder's lines are derived from the section.** The controller composes, from every
 module on a machine, the `backup` lines it always did and a second kind, `data`: every item with its
 class, its path, the path that covers it and its protection. **A backup line written by hand is
 refused by `module check`** and, beside a data section, not placed: one list. A module keeping
 anything irreplaceable depends on the machine's `node-backup` holder (ADR 0207) — the holder backs it
 up or watches its array — so it cannot be assigned where nothing would. Valuable and rebuildable data
 is backed up where a holder is and refuses no machine for want of one.
 **5. The holder measures; the controller judges — and nothing large is ever walked.** The holder
 measures every item that is not a cache by the item's own `measure`:
 - `walk` (the default, for small items): every file summed and the newest change found, in one walk as
  root — **at most once a day**, after the night, and **stopped after ten minutes or two million
  files**, said as "measured partially": a partial size is a lower bound, shown and never compared;
 - `dataset`: the ZFS dataset holding the path — its size from the filesystem's own counters — and the
  newest change among the path's top-level entries; hourly, nothing walked. Items on one dataset share
  its size, so a shrink of it is one condition naming them all;
 - `shallow`: the newest change among the top-level entries only, and no size; hourly.
 A large item never says `walk`: the media library is `dataset`, Plex's metadata and previews, the
 artifact store and the models are `shallow`. A file walk over a pool of that size every hour is load on
 the array that protects the library, and competes with the server reading it. The holder also reads the
 redundant storage each item is on: a ZFS pool's health and its own verdict, an md array's members, a
 btrfs filesystem's error counters. It answers this, with each item's newest good backup, in
 `node-backup.backed-up`; it decides nothing. **The holder is the measurer**, not the node-engine: it
 already reads every declared path as root, it is a module that can be replaced, and the core gains no
 work. The controller's self-check asks every holder on every run.
 **6. Unassigning keeps the data, and the mesh remembers it.** An irreplaceable or valuable item in a
 module's own directory that its machine no longer declares is **retired** (ADR 0230's meaning): kept,
 recorded with when and why, listed by `cleanup list`, said by `unassign` when it is done, and a warning
 after thirty days. Assigned again, it is no longer retired. It is deleted only by `cleanup delete
 <machine> <module> <item> --why`, a hand act, which the machine's backup holder executes **only after
 taking a last restore point of it**, tagged as retired, so the deletion can be undone until a person
 forgets that restore point; the holder refuses any path declared now. An item on an operator's path —
 the media library — is **never** retired and never deleted: the mesh does not own it. The node-engine's
 rule stays (a directory with anything in it is never removed); its report no longer says "remove it by
 hand".
 **7. What is watched, and how loud.** Each condition is **urgent for irreplaceable data and a warning
 for valuable data**; rebuildable data and caches raise none. A consumer's data is as precious as the
 stricter of its provider's class and its own `kept-by`; a provider's item is held to the strictest
 class kept in it.
 | Condition | Raised when |
 |---|---|
 | `data-shrank` | an item holds less than half of its largest size in seven days, and at least 16 MiB less; one condition per dataset for items measured from a dataset's counters; never from a partial size |
 | `data-missing` | an item's path is gone |
 | `empty-replacement` | a copy in use is less than half the size (and 16 MiB less) of a copy of the same thing kept elsewhere: an item retired on another machine, or a consumer's data at another provider — issue 273's shape |
 | `data-held-twice` (warning) | a consumer has active data at two providers whose sizes cannot be compared |
 | `data-quiet` | an item that says `active` has not been written within it |
 | `backup-stale` | an item's newest good backup is older than its bound, or there is none — for valuable data, only where a holder measured it |
 | `array-degraded` | the redundant storage under watched data is not healthy, or cannot be read; one per array |
 | `protection-missing` | an item says `redundancy` and is on storage the holder cannot read as redundant |
 | `data-unmeasured` (warning) | a machine's holder did not answer |
 | `cleanup-waiting` (warning) | an item retired more than thirty days |
 **8. A verb reads it.** `data` lists every item on every machine with its class, protection, path,
 size, newest write, newest good backup and its bound, the array under it, and what is retired.
 **9. Every catalogue module that holds data declares it** (the table below), and the catalogue check
 refuses a container that writes one of its directories, mounted whole, without a data item covering
 it — a directory the mesh does not know about is data the mesh cannot protect.
 ### The classes, per module
 The operator's ranking applied to every module that holds data, **for the operator to correct**: only
 the media library and the photo sites' storage are irreplaceable; everything people wrote is valuable.
 | Module | Own data | Its consumers' | Kept with a provider |
 |---|---|---|---|
 | plex | the media library, eight operator paths: **irreplaceable**, by **redundancy**, measured from its dataset; metadata: rebuildable, backed up, measured shallow; **previews: rebuildable, not backed up** (Plex makes them again; too large to copy nightly); working data: rebuildable; transcode: cache | | |
 | photos | | | object store and document store: **irreplaceable** |
 | postgres, mssql, mongodb | the store: valuable, by dump; the dumps: rebuildable | valuable | |
 | minio, influxdb | data (and influx's config): valuable | valuable | |
 | mesh-vault | state, ledger, root: valuable | valuable | |
 | mailu | mail, signing keys, data, calendars, webmail, the queue: valuable; filter, certificates, autoconfiguration, fetch state: rebuildable; virus signatures, its redis: cache | valuable | |
 | gitea | data: valuable | the package registry: rebuildable | |
 | keycloak | | clients: rebuildable, in its database | |
 | umami | | page views: valuable, in its database | |
 | mosquitto | retained messages: rebuildable | rebuildable | |
 | redis | its snapshot: cache | **cache** | |
 | nextcloud, baserow, grafana, matrix, nodered, unifi, step-ca, audit-logger | their data: valuable | | |
 | home-assistant | its configuration and history: valuable, written all the time (a day) | | |
 | nats | the bus's streams and buckets: valuable, written all the time (a day) | | |
 | n8n | data: valuable; scratch: cache | | |
 | supabase | database: valuable, **by `pg_dumpall`** inside its container; storage, functions: valuable; the dump and its seeded configuration: rebuildable | | |
 | claude-code | the operator's agent's home: valuable | | |
 | ssh-client | the operator's keys: valuable | | |
 | radarr, sonarr, lidarr, bazarr | the database: valuable, by sqlite's own backup; settings: valuable; covers and the night's copy: rebuildable; lidarr's start-up scripts: cache | | |
 | bookshelf, jackett, kometa, nzbget, ombi, qbittorrent, tautulli | configuration: valuable | | |
 | distribution, ollama | the artifact store, the models: rebuildable, **not backed up** (too large; made again), measured shallow | | |
 | only-office | its working data, database, fonts: rebuildable; logs, queue, cache: cache | | |
 | records, route-proxy | the record's clone, issued certificates: rebuildable; the authority's roots: cache | | |
 | restic | the repository: rebuildable, not backed up — it is the copy, never the only copy of anything; its state: cache | | |
 | build-agent, icecast, lab, model-usage, searxng | cache | | |
 **Uncertain, for the operator:** the bus's streams are copied as live files — the bus's image carries
 no tool to snapshot a stream safely, so a consistent copy needs the bus's own backup command run from
 somewhere that has it, which is not built; mailu's queue is valuable though transient; the agent's home
 and the operator's keys are valuable, and are backed up only on machines that hold `node-backup`
 (today, neither workstation does).
 > **Progressive insight — 2026-10-06.** The first of these items is resolved, and was a fact about what
 > was built rather than part of the decision. The record said the bus's streams "are copied as live
 > files" and that a consistent copy "is not built". It now is: the nats module's streams item is
 > protected by a dump — `backup: {dump, into}`, this record's own mechanism — that runs a snapshot
 > program built into the bus's image, through the server's snapshot API, under the bus module's own
 > account granted that API and nothing else; the live store is no longer copied, and a restore builds
 > a new store beside the live one ([ADR 0235](0235-the-bus-is-backed-up-by-its-own-snapshot-of-each-stream.md)).
 > The bus's row in the table above stands: its streams and buckets are valuable, written all the time.
 ## Consequences
 - **The first run of the self-check records what every machine holds**, and the first night backs up
  what was not backed up before: on the home server, every application's own data and Plex's metadata;
  on the control node, the bus's streams and the certificate authority. Measured read-only on
  2026-10-06, the home server's new nightly data is about 11 GB of application data (the chat server's
  database 5.6 GB, the database platform's 2.1 GB before its dump, the network controller 1.1 GB, the
  viewing history 0.9 GB, dashboards 0.5 GB, the rest under 0.2 GB each) and Plex's metadata, at most
  the 136 GB its disk holds — under 150 GB against 33.6 TB free where the repository is: under half a
  percent. The previews, on the media pool, are left out. Later nights cost what changed.
 - **The media library is watched, not copied.** Its array is read every hour; a degraded pool is
  urgent. A pool that loses a vdev still loses the library — the operator's accepted risk, now said
  rather than silent. SMART pre-failure warnings are not read: the pool's own device error counters are,
  and reading SMART is the work of a storage seat when one is decided.
 - **A provider that grants and a container that writes a directory must declare their data** before
  `module check` passes; a module outside the catalogue meets this in its own repository, and a module
  already on the shelf is read as it is.
 - **Retired data takes space until a person deletes it**, as ADR 0230's retired consumers do.
 - **An empty replacement of a store's consumers is a warning**, not urgent: the stores' data is
  valuable by the operator's ranking. A consumer that says `kept-by` irreplaceable — the photo sites —
  makes it urgent.
 - **Rollout order**: the controller first (it reads the new section and composes the holder's new file;
  an older holder ignores what it is not given), then the catalogues and the photo application, then a
  push of every machine. The controller's grant gains `node-backup.backed-up`, and the installer's first
  user list with it.
 ## How it is checked
 | What | Checked by |
 |---|---|
 | the section parses and refuses what it must: unknown class, a machine path, an undeclared directory or access, irreplaceable with no protection, a cache backed up, a dump into nothing | mesh-controller `internal/catalogue/data_test.go` |
 | a granting provider says its consumers' class; nobody says it on the offer; no backup line by hand; a written directory is declared; data kept with a provider as irreplaceable is protected there | `data_test.go`, and `module check` over the whole catalogue (`TestModuleCheckPassesTheCatalogue`, `TestEveryCatalogueModuleDeclaresItsData`) |
 | stickiness follows the class; an older definition still follows its grant | `data_test.go` (`TestKeepingConsumerDataFollowsTheClass`) |
 | the holder's lines are derived — dumps, copies, redundancy, a home directory, an operator's path — and only irreplaceable data needs a holder | `data_test.go` (`TestTheBackupHoldersLinesAreDerivedFromTheData`) |
 | unassigning keeps irreplaceable and valuable data retired, says so, and lists it; an empty replacement of it elsewhere is said — through the real stores and a real bus | `cmd/mesh-controller/data_test.go` (`TestNatsUnassigningIrreplaceableDataRetiresItAndAnEmptyReplacementIsUrgent`), `internal/inventory/data_test.go` |
 | **issue 273 replayed**: five consumers' real databases at one provider, empty ones at another — each an empty replacement, urgent where the consumer keeps irreplaceable data there; a deliberate move is silent | `data_test.go` (`TestAnEmptyReplacementOfAConsumersDataIsSaid`, `TestADeliberateMoveIsNoEmptyReplacement`) |
 | shrink, missing, quiet, backup age, array health and missing protection, by class | `data_test.go` |
 | the holder reads the data file, measures, reads ZFS and md, and deletes only after a last restore point, never a declared path | mesh-catalog `modules/restic/cmd/restic-backups/data_test.go` |
 | the node-engine keeps a directory with anything in it and says so without "by hand" | mesh-host `internal/apply/apply_test.go` |
 | the controller's grant names `node-backup.backed-up`, and the installer's carries it | mesh-controller `internal/broker` (`TestTheInstallersFirstUserListIsWhatTheControllerWouldCompose`, the golden) |
 | live, after rollout | `data` lists every declared item with a measurement and a recent backup; `doctor` passes D13; `conditions` holds no `array-degraded` while the pool is healthy |
 ## References
 - [Issue 273](../04-ISSUES/273-a-rule-for-the-resolver-moved-a-machines-databases/00-report.md) — the incident.
 - [ADR 0232](0232-a-binding-to-a-consumers-data-moves-only-by-a-person.md) — extended: stickiness now
  follows the class, and `keeps-consumer-data` moved into the data section.
 - [ADR 0230](0230-a-consumer-the-mesh-stops-asking-for-is-retired-and-deleted-only-by-a-person.md) — the
  meaning of retired, applied to a module's own data.
 - [ADR 0214](0214-backups-guard-against-mistakes-and-stay-on-the-machine.md) — its backup lines are now
  derived; its exclusion of the media library is replaced by redundancy watched.
 - [ADR 0051](0051-shared-data-is-the-operators.md) — an operator's path is the operator's: never retired
  or deleted.
 - [To-be 32](../03-DESIGN/01-to-be/32-what-a-module-declares.md), [to-be 43](../03-DESIGN/01-to-be/43-backups-against-mistakes.md),
  [to-be 45](../03-DESIGN/01-to-be/45-a-core-that-cannot-fail-silently.md) — amended alongside.
 - mesh-controller `internal/catalogue/data.go`, `internal/inventory/data.go` (migration 0072),
  `cmd/mesh-controller/data.go`; mesh-catalog `modules/restic`; mesh-host `internal/apply/apply.go`.
@@ -1,462 +0,0 @@
 ---
 topic: the mesh
 status: accepted
 date: 2026-10-06
 deciders: jochen
 reconstructed: false
 extends: 02-DECISIONS/0227-the-core-holds-nine-rules-each-checked-and-is-built-to-them-in-six-phases.md
 ---
 # 234. The mesh holds a conversation with its operator, over channels that are seats, and an answer that performs an action is authorised by the controller
 ## Context
 **The output channel was built in its smallest form** ([ADR 0227](0227-the-core-holds-nine-rules-each-checked-and-is-built-to-them-in-six-phases.md),
 [to-be 45](../03-DESIGN/01-to-be/45-a-core-that-cannot-fail-silently.md) §5): one mesh seat,
 `operator-channel`, whose single holder carries the router, a Telegram client and a desktop adapter in
 one process, and **no answering back**. ADR 0227 left routing by presence, quiet hours, answering back
 and the outside dead-man service open in [research 028](../01-RESEARCH/028-the-meshs-output-channel/00-overview.md),
 "whose graduation amends to-be 45". This record is that graduation.
 The evidence, from 028:
 - **The mesh tells nobody.** 15 of the 236 issue reports say the fault was found because a person
  happened to look; 74 describe something failing silently. On the day 028 opened the mesh knew of a
  machine refusing every declaration for ninety minutes, a machine out of touch for ten minutes, and a
  failure repeated thirteen times, and told nobody ([028/01](../01-RESEARCH/028-the-meshs-output-channel/01-what-the-mesh-already-knows.md)).
 - **The built Telegram code has ten defects**, two of which silence exactly what the operator most
  needs to hear: nothing bounds a message to Telegram's 4096 characters, so one long message wedges the
  channel (D1); and a reopened urgent condition is said by an edit, which on Telegram rings nothing (D2)
  ([028/04](../01-RESEARCH/028-the-meshs-output-channel/04-telegram-as-the-first-holder.md)).
 - **Actions that need a person are ordinary verbs.** `retire approve`, `cleanup delete` and `pin` while
  a binding is kept are callable by any principal granted the verb, agents included, and a hand-act
  records the calling bus principal, not the person ([028/08](../01-RESEARCH/028-the-meshs-output-channel/08-asks-that-authorise.md)).
  `retire approve` re-reads the set when it runs, so "approve what you were shown"
  ([ADR 0230](0230-a-consumer-the-mesh-stops-asking-for-is-retired-and-deleted-only-by-a-person.md))
  does not hold end to end.
 - **The desk cannot prove who clicked.** The graphical session is X11: any client of the display can
  inject input and read keystrokes, `dunstctl action` invokes a notification's action for any program
  of the account, and the desktop holder's bus credential is readable by every agent running as the
  operator ([028/08](../01-RESEARCH/028-the-meshs-output-channel/08-asks-that-authorise.md)).
 The operator's directions, 2026-10-06:
 - Telegram is one channel among many to come; it simply fills a seat. Input (a mail, a message from the
  operator) has the same shape.
 - Each channel has capabilities, and they decide what may travel on it.
 - Agents and modules must be able to **ask** the operator anything, not only for permission.
 - The **work context** chooses the channel: in a Telegram conversation, Telegram; at the desk, the desk.
 - Approving and rejecting must be possible through Telegram, and while talking to an agent through
  Telegram, everything must be completable there.
 - **There is no hardware security key.** The proof the operator gives is a code from the authenticator
  app on the phone. A key may be added later and must never be required.
 Reviewing the proposed record, the operator found four questions it left open, and on 2026-10-06
 asked for each to be decided here rather than left as a gap:
 - **A lost phone locks the operator out for good.** Re-enrolling a factor is a destroy ask, and a destroy
  ask needs a code from the factor that was lost.
 - **Nothing says who answers an operator message.** "An agent bridge takes `message`" names no
  addressee, and a message nobody takes is silence.
 - **The content rule refuses what an ask sometimes needs.** "Which of these two paths should be kept?"
  cannot be asked in roles and words.
 - **"The operator" was the holder's flag.** The research's envelope carried an `operator` field filled
  "from the controller's list", but nothing said who fills it or what an envelope from anyone else may
  do.
 ### Against GENESIS
 - **Mission — intake, process, deliver; agents, some of whom are human.** A human agent "acts through a
  shell, a desktop, a message from a phone". The conversation is that modality made a first-class part
  of the mesh, for asking as well as telling. The distinction this record draws is **not** human versus
  non-human as a category: it is which **identity** can present which **proof**. A spawned agent holds
  no enrolled factor, so it cannot authorise; nor can a person without one.
 - **Core value — failure must be loud.** A conversation that cannot carry something says so, and the
  away channel is checked to carry every tier.
 - **Core value — sovereignty.** Telegram is an outside dependency, taken deliberately: free, on both
  phone platforms, no server of the mesh's own, and the only candidate that carries every tier today.
  It holds a seat, so it is replaceable by a holder of the mesh's own (Matrix, once its push is
  measured) without changing anything that speaks to the seat. It never sees a factor's secret.
 - **Context — one human, usually asleep; nodes are personal and mobile.** Hence routing by where the
  operator is, escalation when unanswered, quiet hours, and a watcher's watcher that does not depend on
  the control node.
 - **Effect — "when something genuinely needs a decision, you are asked, with the context, not a log
  line".** That sentence is this record's purpose.
 Nothing in 028 conflicts with GENESIS.
 ## Considered Options
 ### Where a channel attaches
 1. **Each channel contributes itself to the output seat** (to-be 45 §5 as written). Rejected: a
   contribution is content a holder places ([ADR 0210](0210-a-tools-configuration-is-its-seat-holders-and-every-other-module-extends-it-through-the-seat.md));
   a channel is running code with a secret, a connection and answers of its own. Making it fit puts
   every channel's client back in the router.
 2. **One seat per channel kind** (`telegram-channel`, `desktop-channel`, …). Rejected: the router must
   learn every seat, and every new channel is a change to the router.
 3. **Channel modules found by a manifest field and called by module address.** Rejected: callers use
   seats, never modules ([ADR 0126](0126-a-module-declares-its-own-seats.md)).
 4. **One notifier with every channel built in.** Rejected: shared secrets, shared failure, a release
   of the router per channel.
 5. **A per-service module with its own question or approval path** (a "Telegram module" that decides).
   Rejected: it locks the conversation to one service, and the next channel repeats it.
 6. **Two kinded benches, `channel` (out) and `intake` (in); a fixed capability vocabulary; the output
   seat's holder as the router that orders by work context; an authorising layer held by the
   controller.** Chosen.
 ### How answers come in
 - **A webhook.** Rejected: it needs a public route into the mesh, and a stolen token can redirect it.
 - **Long polling.** Chosen: outbound only; a stolen token can steal updates (visible as a conflict) but
  cannot inject one.
 ### Who performs an authorised action
 - **The channel module calls the authorising verb itself.** Rejected: the hand-act would name the
  module, a compromised channel could act, and every channel would repeat the checks.
 - **The asker performs it on hearing "yes".** Rejected: an agent relaying "the operator said yes" is
  not an answer to anything.
 - **The controller holds the ask, checks the answer and performs.** Chosen.
 ### What proves the operator answered
 - **A click at the desk.** Rejected: on X11 an agent on the operator's account can produce it.
 - **The screen's unlock or a fingerprint reader.** Rejected: only the local holder sees the result,
  and an agent can forge what it reports.
 - **A security key's touch (FIDO2), required.** Rejected: the operator has no key. Kept as an
  optional proof for whoever enrols one; never required for any tier.
 - **A TOTP code from the operator's authenticator, verified by the controller.** Chosen as the proof
  every tier above acknowledge can rest on.
 - **A verified Telegram sender**, through a holder no agent shares. Chosen as a proof for approve, never
  enough alone for destroy.
 ### Whether context may lower the bar
 - **Being at the desk, or in a recent conversation, counts as presence and so as proof.** Rejected:
  presence proves someone was there, not who answered.
 - **Context orders the channels that already qualify, and never makes one qualify.** Chosen.
 ### The seat shape, against ADR 0223
 [ADR 0223](0223-the-mesh-has-two-resolvers-and-a-machine-lists-only-them.md) made `mesh-dns-resolver`
 the first bench, of the **replicated** sort (the same module, one holder per machine, every holder
 answering the same), and said making another bench is a decision, recorded.
 - **Model channels as a replicated bench.** Rejected: the holders are different modules that answer
  differently, and a send must reach one chosen holder, not any.
 - **Model each holder as a node seat keyed by machine.** Rejected: a channel's identity is its service,
  not where it runs.
 - **A second sort of bench, kinded.** Chosen, decided here (below).
 ### Recovering the operator's factor
 - **Re-enrolling only through a destroy ask.** Rejected: losing the phone loses the code the ask needs;
  a permanent lockout of the mesh's only person.
 - **Recovery through the away channel** (a Telegram tap re-enrols). Rejected: the phone that was lost
  is the away channel, and a stolen phone would recover itself.
 - **A verb on the bus that re-enrols for the operator's principal, without a code.** Rejected: any
  holder of that principal, an agent on the operator's account included, could take the factor over.
 - **Recovery codes kept in clear in the controller's state.** Rejected: whoever reads the state holds
  ten proofs.
 - **Ten one-time recovery codes made at enrolment, kept only as hashes, each one P2 proof; a last resort
  that needs root on the control node, run there and refused over the bus.** Chosen.
 ### Who answers an operator message
 - **Every operator message to every agent.** Rejected: each agent would act on words meant for
  another.
 - **To whichever agent spoke last.** Rejected: a guess, wrong exactly when two agents are working.
 - **Drop what nobody is addressed by.** Rejected: silence, the failure this effort exists to end.
 - **Addressed by `@name` or by the thread it is written in; otherwise to the mesh's own responder,
  which answers from the controller's read verbs or says it did not understand.** Chosen.
 ### Asks that need specifics the content rule refuses
 - **Lift the content rule for `private` holders, or for Telegram.** Rejected: Telegram reads every
  word, and a holder's declaration is not a reason to let a path leave the machines.
 - **Refuse silently, as before.** Rejected: the asker cannot tell what to change.
 - **Machine names allowed in words; anything else concrete carried as a reference only a private
  surface opens; a refusal names the offending part to the sender.** Chosen.
 ### Who counts as the operator
 - **The holder's own allow-list.** Rejected: a channel module, or its bus account, would decide who
  the operator is.
 - **The service's own verification alone** (a Telegram account is authenticated). Rejected: it proves
  an account, not that the account is the operator's.
 - **Drop everything not from the operator.** Rejected: mail and webhooks are inputs the mesh wants, as
  data.
 - **The controller's list decides; everything else is marked untrusted and may be data for consumers
  that accept it, never the operator's words.** Chosen.
 ## Decision
 ### 1. The conversation
 **The mesh holds a conversation with its operator.** Three things are said: a **message** (the mesh
 tells; no answer expected), an **ask** (someone wants the operator's input, of a declared kind), and an
 **operator message** (the operator writes first). An input from outside that is not the operator (a
 mail, a webhook) is the same envelope with another sender; this record decides its shape only, and its
 consumers are later work.
 ### 2. Channels and intake are kinded benches
 - **A kinded bench is the mesh's second sort of bench**: a mesh seat whose holders are **different
  modules, each claiming one kind**. Two claims of one kind are refused at registration. A verb's
  subject carries the kind, as a node seat's carries the machine.
 - **`channel`** (out) and **`intake`** (in) are kinded benches, and the only ones. Making another is a
  decision, recorded, as ADR 0223 requires of every bench.
 - `channel` serves `send`, `edit` and `standing`, and emits `delivered` and `failed` (permanent or
  transient). `intake` emits one envelope per input. A service read and written by one program is held
  by one module claiming both seats under one kind.
 - **A claim on a kinded bench carries `kind` and `capabilities`.** Capabilities come from the fixed,
  versioned vocabulary **`channel-capabilities/1`**; a word outside it is refused. Each capability has
  a contract test the holder's build runs and a drill its `standing` can run; one that fails its drill
  is withdrawn from routing and reported until it passes.
 - The vocabulary has three groups: delivering (`deliver`, `reaches-away`, `loud`, `silent`, `edit`,
  `max-length:N`, `reaches-when-mesh-down`, `private`), conversing (`choice`, `reply`, `threads`,
  `operator-first`) and trusting (`verified-sender`, `exact-render`, `code-factor`, `key-factor`).
 ### 3. Who counts as the operator
 - **Only a sender on the controller's list of the operator's identities is the operator.** The list
  is kept per intake kind, in the controller's own state. While no factor exists, an identity is
  enrolled only at a terminal; once one does, adding or removing an identity is a destroy ask.
 - **Every envelope is marked `trusted: true` or `trusted: false` by a check against that list, made on
  the controller's side** — the router asks the controller, never reads a holder's word for it. A raw
  intake event is untrusted by construction; only the router's re-emitted operator message is trusted.
 - **An untrusted envelope** may start work for consumers that declare they accept untrusted input (a
  mail rule). It can **never** answer an ask, authorise, or reach an agent as the operator's words.
 - **The rule for agents and consumers: untrusted input is data, not instructions.** An agent that is
  handed one may read it, quote it and report on it, and never follows what it says.
 ### 4. Who answers an operator message
 - **An operator message is addressed:** to an agent by `@name` at its start, or by being written in an
  agent's thread (its conversation handle); otherwise to **the responder**, the mesh's own participant,
  addressed as `@mesh`.
 - **The responder is part of the router.** It answers questions about the mesh from the controller's
  read verbs only — status, conditions, asks, and the bindings and data on record — and lists what it
  can answer when asked or when it does not understand. It performs nothing.
 - **Nothing is answered with silence.** A message that is unaddressed and not understood gets a reply
  saying so, and how to address someone.
 - **An agent registers as addressable** with the router: its name (unique, bound to its bus
  principal), its owner, and what it handles. `@` names come only from that register.
 - **A message to a registered agent that is not running is kept**, bounded per agent, and the operator
  is told it will be read when the agent next runs. **A message to a name not registered is refused**,
  with the names that are.
 ### 5. The router
 - **The holder of `operator-channel` is the conversation's router.** It loses its Telegram client to a
  module of its own and keeps no channel's client in its process.
 - **It routes by required capability, then by work context, then by severity**, and escalates along a
  fixed chain when unanswered. When nothing can carry something, it says so as a condition of its own.
 - **Context orders, never qualifies.** The work context chooses among channels whose capabilities
  already satisfy the message or ask. It never adds one, and never lowers what an ask requires.
 - **The content rule stays the router's**, applied before anything reaches any holder (§6). A holder
  declaring `private` is not exempted.
 - **Presence is current state on the bus**: a value per machine and per intake kind, overwritten, never
  a history, and never in a message's words.
 ### 6. What a message may name, and references
 - **The mesh's own machine names may appear in a message's words.** Domains, addresses, paths and
  anything shaped like a secret may not.
 - **A message or ask may carry references.** A sender attaches a detail (a path, an address, a log
  excerpt) with a label; the router keeps it and puts only an opaque reference and its label in the
  words. A secret is refused even as a reference.
 - **A dereferenced detail is shown only on a channel declaring `private`, and at the console.** Today
  that is the desk and the console. On Telegram, and on any channel not declaring `private`, only the
  reference's label is shown. The router's verb `detail <ref>` answers only the console and the intake
  holders of `private` kinds, and its answer travels only back to them.
 - **A refusal by the content rule is said to the sender, naming the offending part**, so the asker can
  rephrase or move the specific into a reference. The offending part is never sent to a channel.
 ### 7. Asks
 - **Kinds:** `yes-no`, `one-of` (at most eight options), `text`, `number`, `date`, `acknowledge`, each
  requiring its capabilities (`choice` or `reply`).
 - **Life:** open → answered | defaulted | expired | cancelled. The first answer wins; every other copy is
  edited to say where it was answered. A default is delivered marked as a default, never as the
  operator's answer.
 - **An authorising ask never defaults.** It expires.
 - An asker holds **at most three open asks**; a fourth is refused in words. Asks count against the
  router's hourly cap. Asks burst-batched to one channel go out together under one heading, each its
  own message. **History is kept 30 days.**
 - **The answer returns to the asker as an event**; an asker may also wait a bounded time, or poll.
 ### 8. Asks that authorise
 **An ask whose answer performs an action is held by the controller.** The router carries it like any
 other ask; only the controller performs.
 - **Every authorising verb declares its tier** in the controller's verb table (`authorises`: the tier,
  and the arguments that make up the exact state the operator must see).
 - **The controller's verbs:** `authorise request` (anyone may call it; it renders the ask, stores it
  with a digest of the state shown, and performs nothing); `authorise answer` (granted to intake holders
  only); `authorisations` (open and recent).
 - **The proofs** that the operator, and not someone else, answered:
  - **P1, a verified sender:** a tap from the operator's own Telegram account, through a holder placed
    where no agent runs as the operator;
  - **P2, a TOTP code** from the operator's authenticator app, verified by the controller — valid for
    the current or previous 30-second step, and accepted once;
  - **P3, a security key's touch bound to the ask** — **optional**. It counts where a key is enrolled,
    and no tier ever requires it.
 - **The tiers:**
  | Tier | Required | On the away channel (Telegram) | At the desk |
  |---|---|---|---|
  | acknowledge | `choice`, `exact-render` | tap | click |
  | approve | the above and **one** proof | tap (P1) | click **and a code** (P2) |
  | destroy | the above and **two** proofs, at least one of them P2 | tap and a code (P1 + P2) | click, code and key touch (P2 + P3) where a key is enrolled; otherwise carried by the away channel |
  Acknowledge performs only what any granted principal may already do (silencing, announced); it is
  not an authorisation, and needs no proof.
 - **A desk click alone never authorises.** The desk declares no `verified-sender`; at the desk, approve
  and destroy rest on a code the controller verifies (or a key touch, where enrolled).
 - **Every tier is completable on the away channel.** The self-check verifies it every run; a setting
  that would make a tier possible only at a desk is refused unless the operator chose it for that tier
  explicitly.
 - **The controller checks from its own records, never the request's claims:** the ask is open and
  unexpired; the caller holds an intake kind; that kind's declared capabilities meet the tier; a P1
  sender is on the controller's list of the operator's identities; a code is valid and unused; a key
  assertion verifies over this ask's challenge; and the state now has the digest it had when shown.
  It refuses at the first failure, then performs as itself, closes the ask with a compare-and-set (a
  second answer loses), and emits `ask-answered`.
 - **No agent authorises.** An agent asks; the operator answers where they are. Agents' grants lose the
  authorising verbs. Those verbs refuse direct calls except through `authorise answer`, or as
  **break-glass** at the console with a code, recorded and announced as such.
 - **`retire approve` takes `expect`**, the set it approves, and refuses if the set differs.
 - **The hand-act records** `via` (kind and holder), `requested-by` (agent principal or condition key),
  `ask` (its id) and `proofs` (which were present). `by` names the operator as that kind's identity.
 - **The factors' secrets are the controller's own.** The TOTP seed is made by the mesh and shown once,
  to a terminal, never through a channel or an event. Re-enrolling a factor, or changing the operator's
  identities or the away channel, is a destroy ask — except recovery, below, which exists because a lost
  factor cannot answer one.
 - **A code travels by request and reply only**, from the holder to the controller; never in an
  envelope or an event, and deleted from the conversation where the service allows.
 **Recovering the factor.**
 - **At TOTP enrolment the controller makes ten one-time recovery codes**, shown once to the terminal
  together with the seed, never through a channel or an event, and stored only as hashes.
 - **Each recovery code counts as one P2 proof, once.**
 - **`factor recover`**, given a recovery code at a terminal, re-enrols the TOTP factor (a new seed,
  and ten new recovery codes replacing the rest). It is recorded as a hand-act and **announced loudly on
  every channel**.
 - **The count of recovery codes left is visible**, and the self-check warns when three or fewer remain.
 - **The last resort:** root on the control node (at it, or by its SSH key) runs `factor enrol
  --break-glass` there, locally. The controller refuses it over the bus. It is recorded and announced as
  break-glass.
 - **The controller refuses to enable any tier that requires P2 until recovery codes exist.**
 ### 9. First holders
 - **Telegram** is the first holder of both seats and the away channel: its own module, kind
  `telegram`, long polling, buttons, replies, codes by a forced reply, a linking verb; placed where no
  agent runs as the operator, on which its `verified-sender` depends.
 - **The desk** holds both seats as kind `desktop`, through the machine's `node-notifier` (gaining
  actions) and `node-launcher` (a prompt for text, numbers, dates and codes). It carries every ordinary
  ask with no account anywhere.
 - **The watcher's watcher stays outside the seats**, with its own bot, on a machine that is not the
  control node. An outside dead-man service is pinged by the self-check and by the watcher.
 ### 10. The order of work
 **Fix D1–D4 of the built Telegram code first**, before the channel is configured; then the desk's
 actions; then the seats and the router, with the operator's identities, untrusted marking and
 references; then asks, the responder and addressing; then authorising with TOTP and its recovery; then
 Telegram live. The
 phases and their owners are in [to-be 46](../03-DESIGN/01-to-be/46-the-conversation-with-the-operator.md).
 ## Consequences
 - **To-be 45 §5 is amended**: the operator answers. ADR 0227's minimal form is the first step of this
  design, not reversed; ADR 0227 left this to 028's graduation and carries a dated note pointing here.
 - **The catalogue gains a second sort of bench**, `kind` and `capabilities` on a claim, two seats in
  the closed set ([ADR 0110](0110-a-seat-is-a-module-assignment-from-a-closed-set.md)), and the
  vocabulary with its contract tests.
 - **The shared library must publish on a seat's event subjects** (to-be 32 §1's open gap), and the
  permission model must grant it; until then the seats' events cannot be emitted as designed.
 - **`node-notifier.send` gains actions**, and the screen-lock holder emits lock and idle changes.
 - **The controller grows**: the `authorises` field, three verbs, refusals on direct calls, the
  hand-act fields, the operator's identities, the TOTP seed and enrolled keys as its own state, and a
  self-check probe for the away channel.
 - **The operator's identities, the factor and its recovery codes are the controller's state**, and the
  controller gains `factor enrol`, `factor recover` and a local-only break-glass enrolment.
 - **The router gains a register of addressable agents, the responder, kept messages for agents not
  running, and references with `detail`.** A message may now name a machine; it still may not name a
  domain, an address or a path.
 - **Every agent and consumer of input carries a rule:** untrusted input is data, not instructions.
 - **Harder:** approving at the desk now costs picking up the phone for a code. That is the price of an
  X11 desk shared with agents; it falls if agents run under an account of their own on a display that
  isolates clients, which is noted, not decided.
 - **A residual risk is accepted:** on X11 an agent can read a code as it is typed at the desk and race
  to use it. Each code is accepted once and only within its step; the session leaving X11 closes it.
 - **Telegram sees the words**, held to the content rule, and never a factor's secret. If the operator's
  Telegram account is taken, approve is reachable (announced, reversible), destroy is not without the
  code.
 - **The predecessor wording in to-be 45** ("each a module contributing itself to the seat") is replaced
  there, not here; this record's option 1 says why.
 ## How it is checked
 | Rule | Checked by |
 |---|---|
 | A capability outside `channel-capabilities/1` is refused | catalogue registration test |
 | Two holders claiming one kind on a kinded bench are refused; only `channel` and `intake` are kinded | catalogue registration test over the compiled seat set |
 | Each declared capability has a contract test that runs in its holder's build | catalogue lint: a declared capability without its test fails the build |
 | A capability failing its drill is withdrawn from routing and reported | router test with a holder whose drill fails |
 | An ask goes only to channels whose capabilities satisfy it | router test |
 | Context reorders but never adds a channel, and never lowers what an ask requires | router test: the same ask in every context yields subsets of the same qualified set |
 | An authorising ask never defaults | router test |
 | A cancelled or answered ask's other copies are edited | router test against channel doubles |
 | A fourth open ask from one asker is refused | router test |
 | Presence is never written as history and never in a message's words | router test over its state buckets; the content rule's test |
 | A desk click alone never authorises | controller test: `authorise answer` from kind `desktop` with no code is refused for approve and destroy |
 | A TOTP code is verified by the controller, once, within its step | controller tests: wrong code, used code, code from two steps back, all refused |
 | Destroy needs two proofs, one of them a code; a key is never required | controller tests: P1 alone refused; P1 + P2 accepted; P2 + P3 accepted; no tier's requirement names P3 |
 | `authorise answer` refuses a non-intake caller, a kind below the tier, an identity not on the list, a key assertion over another ask's challenge, a stale digest, a second answer | one controller test per refusal |
 | No agent authorises; authorising verbs refuse direct calls | controller test: direct `retire approve`, `cleanup delete`, `pin` (while kept) refused without a code; catalogue check that no agent module's grant names an authorising verb |
 | `retire approve` approves only the set shown | controller test with `expect` differing from the current set |
 | The hand-act records `via`, `requested-by`, `ask`, `proofs` | controller test reading the hand-act after an authorised action |
 | Every tier is completable on the away channel | self-check probe, every run; raises a condition when not |
 | A code never appears in an event | intake holder contract test (`code-factor`) |
 | D1–D4 are fixed before Telegram is configured | holder tests: 4097 characters arrive cut and said; a reopening is a new message; clearing edits the newest; warnings and clearings are silent |
 | Only a sender on the controller's list is the operator; `trusted` is set from the controller, never the holder | router test: an envelope a holder marks as the operator's, from an identity not on the list, is re-emitted `trusted: false` |
 | An untrusted envelope never answers an ask, authorises, or reaches an agent as the operator's words | router test (`answer` refused); controller test (`authorise answer` refused); router test (no addressed operator message emitted for it) |
 | Adding or removing an operator identity is a destroy ask | controller test: a change without two proofs is refused |
 | Untrusted input is data, not instructions | the rule stated in every agent module's instructions and every intake consumer's definition; review, and a live drill: a mail saying "approve the retirement" changes nothing |
 | An operator message reaches the addressed agent, by `@name` or thread; otherwise the responder | router test per route |
 | Never silence: an unaddressed message not understood gets a reply saying how to address | router test |
 | The responder only reads | catalogue check: its grant names only read verbs |
 | A message to a registered agent not running is kept (bounded) and said; to an unknown name, refused with the known names | router tests |
 | Machine names pass the content rule; domains, addresses, paths and secrets do not | content-rule test table |
 | A dereferenced detail reaches only a `private` channel or the console; elsewhere only the label | router test: `detail` from a non-`private` holder refused; a message to Telegram carries the label only |
 | A content-rule refusal names the offending part to the sender, and to no channel | router test |
 | Ten recovery codes made at enrolment, shown once, stored only as hashes; each one P2, once | controller tests over enrolment and the store (no clear code in state); a used recovery code refused |
 | `factor recover` re-enrols, is recorded and announced on every channel | controller test reading the hand-act and the announcement |
 | The self-check warns at three or fewer recovery codes | self-check probe test |
 | Break-glass enrolment runs only locally on the control node | controller test: `factor enrol --break-glass` over the bus is refused |
 | No tier requiring P2 is enabled before recovery codes exist | controller test |
 | End to end | live drills: an agent's question answered at the desk; the same with the desk locked, answered on the phone; an approve and a destroy on a test condition, answered on the phone with a code, hand-acts read |
 ## References
 - [Research 028](../01-RESEARCH/028-the-meshs-output-channel/00-overview.md), above all
  [06](../01-RESEARCH/028-the-meshs-output-channel/06-a-conversation-with-the-operator.md),
  [07](../01-RESEARCH/028-the-meshs-output-channel/07-the-work-context-and-the-desk.md),
  [08](../01-RESEARCH/028-the-meshs-output-channel/08-asks-that-authorise.md) and the proposed record in
  [09](../01-RESEARCH/028-the-meshs-output-channel/09-a-proposed-decision.md).
 - [ADR 0227](0227-the-core-holds-nine-rules-each-checked-and-is-built-to-them-in-six-phases.md): the
  minimal output channel this record grows, and the place it left answering back.
 - [ADR 0223](0223-the-mesh-has-two-resolvers-and-a-machine-lists-only-them.md): the first bench, and
  the rule that another is a recorded decision.
 - [ADR 0230](0230-a-consumer-the-mesh-stops-asking-for-is-retired-and-deleted-only-by-a-person.md):
  approve what you were shown; a timer is the mesh acting alone again.
 - [ADR 0208](0208-the-graphical-session-is-one-module-per-piece-on-the-meshs-seats.md): the desktop
  notifier as a node seat.
 - [Issue 187](../04-ISSUES/187-the-mesh-tells-nobody-when-it-stops-working/00-report.md): the class.
 - [To-be 46](../03-DESIGN/01-to-be/46-the-conversation-with-the-operator.md): the design.
@@ -1,163 +0,0 @@
 ---
 topic: what runs on it
 status: accepted
 date: 2026-10-06
 deciders: jochen
 reconstructed: false
 extends: 02-DECISIONS/0233-a-module-declares-the-data-it-holds-and-the-mesh-protects-and-watches-it-from-that.md
 ---
 # 235. The bus is backed up by its own snapshot of each stream, taken under the bus module's account
 ## Context
 [ADR 0233](0233-a-module-declares-the-data-it-holds-and-the-mesh-protects-and-watches-it-from-that.md)
 made every module declare its data and derived the night's backup from it. It left one item flagged
 for the operator: **the bus's streams were copied as live files.** The bus keeps everything it holds in
 JetStream — every stream, and every key-value bucket, which is a stream too: conditions and their
 history, calls, the hand-act log, the controller's lease, assignments, events, every module's state.
 The backup holder read the store's directory as it stood while the server wrote it. A copy taken that
 way can hold a block half-written, or an index from before the block it indexes, and may not restore;
 nothing would say so until the day it was needed. The operator asked for a safe snapshot the same day.
 What was true when this was decided, read from the bus on the control node without changing it:
 - 19 streams, 141,703 messages, 117 MB: the events stream 97 MB (139,322 messages), the calls
  bucket 17.6 MB, the machines' declarations 1.6 MB, the rest under 200 KB each. All on disk; none in
  memory.
 - The server's own way to hand a stream out whole is the **snapshot API**: a request names a subject
  to deliver to; the server answers with the stream's configuration and its state, then sends an
  archive in chunks, each carrying a reply subject the server waits on past an 8 MiB window, and ends
  with an empty message. The server goes on taking writes throughout; nothing is paused or
  reconfigured; only a second snapshot of the same stream at once is refused. The client library the
  mesh uses offers no helper for it; the operator's command-line tool and the server implement it.
 - **Only the controller could reach the JetStream API** ([design 25](../03-DESIGN/01-to-be/25-the-bus-on-nats.md)
  §3–§4): it is the one writer of stream definitions, and its grant is the whole API.
 - The bus's image is the upstream server and an entrypoint; nothing in it could take a snapshot. Its
  module declared no account on the bus.
 - A dump is a shell command the backup holder runs as root before it copies the item the dump writes
  into ([to-be 43](../03-DESIGN/01-to-be/43-backups-against-mistakes.md)); the stores' dumps run
  `docker exec` into their own container. A dump can name the module's directories and nothing else —
  no machine path (ADR 0112), and no reference to where a bundle is unpacked.
 ## Considered Options
 1. **Keep copying the live files.** Rejected: it is the thing that may not restore, and a backup that
   may not restore is worse than none, because it is believed.
 2. **Stop the bus for a cold copy each night.** Rejected: every machine, every tool call and every
   hand act depends on the one server; an outage a night to make a copy the server can give while
   running is a cost with nothing bought.
 3. **The controller takes the snapshots** — it already holds the whole JetStream API — on a schedule
   before the night, into its own state directory. Rejected: it puts backup work in the core, whose
   rule is that it does as little as it can and fails loudly (ADR 0227); the bus's protection would
   depend on the controller's machine and schedule, and a dump of one module would be a file of
   another; and the reading would be done under the widest authority on the bus.
 4. **A dedicated snapshot principal with an issuance path of its own.** Rejected: a second way to mint
   and seal a bus credential, when `module issue` already mints a module's account and seals it to the
   machine.
 5. **The program in the nats module's tools bundle**, run by the node's runtime. Rejected: a dump
   cannot name where a bundle is unpacked, and a restore needs the server itself, which the bundle does
   not carry.
 6. **The program in the bus's own image, run by the backup holder's dump under the bus module's own
   account, granted the snapshot API and nothing else.** Chosen.
 ## Decision
 **1. The bus's streams are protected by a dump, and the live store is no longer copied.** The nats
 module's `jetstream` item says `backup: {dump, into: snapshots}`. The dump runs, in the bus's own
 container, a program built into the bus's image, `mesh-nats-snapshot`, with the module's credential on
 its standard input; it writes one archive to standard output into the module's `snapshots` directory
 (rebuildable), renamed into place only when whole. The holder backs up that directory. **No transition
 period copies both**: the restore points of the live files taken before stay in the repository for
 the rotation's two weeks, two months and half a year, so the old copies are at hand until they age
 out, while the snapshot protects the bus from its first night.
 **2. The module holding `mesh-broker` is the bus, and its account may snapshot the bus and do nothing
 else.** When it declares an own secret named `broker`, the controller composes its user
 `<machine>.<module>` with exactly: the stream names, one stream's information, the snapshot request for
 any stream, the acknowledgement subjects the server puts on the chunks, and its own inbox. Nothing that
 defines, changes, purges or writes a stream — the writers table (to-be 45 §1) holds that at
 composition, the same check that refuses any second writer. It answers nothing. A bus module that
 declares anything else to say or hear on the bus is refused by `module check`, because it would be
 granted nothing. Its tools stay the node runtime's to serve. **The controller's own grant, and so the
 installer's first user list, are unchanged.**
 **3. A snapshot is the server's, taken gently.** One stream at a time, in name order, with a pause
 between two; each chunk acknowledged as it arrives so the server's window keeps moving; a bound per
 stream (ten minutes) and for the whole (thirty). A memory stream holds nothing across a restart and
 cannot be snapshotted; it is listed as skipped with why. Any stream failing fails the whole night for
 the bus: a partial copy where a whole one is expected is the silent failure this exists to prevent.
 The archive is a tar: first a **manifest** — when it was taken and how long it took, the server's
 version, and per stream its subjects, messages, bytes, first and last sequence, consumers, and the size
 and SHA-256 of each file beside it — then, per stream, the server's configuration and state and the
 server's own archive of it, consumers included, in the layout the operator's command-line tool also
 reads.
 **What a snapshot promises, as measured, not assumed:** every message up to the last sequence the
 manifest gives for a stream, exactly. The server states a stream when the snapshot starts and reads its
 blocks a moment later, so a stream written during its snapshot carries some of what arrived in that
 moment as well — the first test against a server being written every two milliseconds restored to
 sequence 6025 where the manifest said 6024, and at a hundred megabytes to 90075 where it said 90024,
 with some messages of that tail present and some not. A restore ends at or after the manifest's
 sequence, and one that ends before it is refused.
 **4. Restoring never touches the live bus.** A stream is restored only where it does not exist, and on
 the live bus every stream exists. So the same program builds a **new store beside the live one**: it
 starts the bus's own server binary, from the bus's own image, on loopback, with the bus's one account,
 restores every stream, holds each to the manifest, and stops it. Swapping the new store in for the
 live one, with the bus stopped, is a person's act and a planned bus step (to-be 45). The steps are in
 to-be 43 and the module's README.
 **5. Nothing new watches it.** A failed snapshot is a failed night for the bus, and its item's last good
 backup ages into the existing `backup-stale` condition, read by D13; the holder measures the snapshots
 directory like any item. Each night's runtime and size are in the manifest, and the archive's size is
 the holder's measurement of the item.
 ## Consequences
 - **The bus's image changes, so the bus restarts once**: the image now carries the program (built
  from a Go toolchain declared beside the server's base). That restart is a planned bus step, done by a
  person, not a side effect of a push.
 - **Rollout order**: the controller first (it composes the new user once the module declares an
  account; until then nothing changes); then the catalogue; then `module issue nats --node <the bus's
  machine>` **before** that machine's next push — a push refuses a module whose declared account was
  never issued, and says so; then the push, as the planned bus step. The first night after it is the
  first snapshot.
 - **The size of a night**: at most the streams' bytes — 117 MB today, less once compressed. A local run
  of the program at that size (105 MiB, 90,000 messages, written to throughout) took half a second for
  the snapshot and a third of a second to restore the largest stream. The archive's compression is
  per block, so a night's restore point shares what did not move with the night before; the events
  stream ages out a week at a time, so most of it moves within the week.
 - A restore is a person's work of four steps, not a verb. A verb that swaps a store would stop the bus
  from a tool call; that stays a hand act until the planned bus step (to-be 45) is a verb itself.
 - A stream's messages written during its snapshot may be partly there; nothing the mesh keeps depends
  on the last few milliseconds of a night.
 ## How it is checked
 | What | Checked by |
 |---|---|
 | a snapshot of every stream and bucket of a server being written to, restored into a fresh server and into a new store served by a third: every message to the manifest's sequence identical, deletes still deleted, buckets and an object store working, consumers where they were; writes during the snapshot all accepted | mesh-catalog `modules/nats/snapshot/live_test.go` (`TestASnapshotOfALiveBusRestoresToTheSameContent`, throwaway `nats:2.11`) |
 | nothing restored over a live stream; a damaged archive refused | the same test |
 | the manifest's dump, exactly, in the module's image with the module's configuration; a refused night fails and keeps the last snapshot | `modules/nats/snapshot/image_test.go` |
 | the composed grant is the snapshot API and an inbox; it writes nothing (the writers table); only the broker seat's holder gets it | mesh-controller `internal/broker/snapshot_test.go`, `internal/inventory/busrecords_test.go`, the composition golden |
 | that grant, composed, against a real server: a whole snapshot taken; every write and every wider subscription refused | `internal/broker/snapshot_live_test.go` (`TestTheComposedSnapshotUserCanSnapshotAndCannotWrite`) |
 | a bus module declaring more on the bus is refused; the catalogue's bus is protected by the snapshot | `internal/catalogue/bus_snapshot_test.go` |
 | the installer's first user list still matches the controller's | `TestTheInstallersFirstUserListIsWhatTheControllerWouldCompose` |
 | live, after rollout | `node-backup.backed-up` shows the bus's item with a recent good backup; `doctor` passes D13; `nats_users` shows the bus module's user with four grants |
 ## References
 - [ADR 0233](0233-a-module-declares-the-data-it-holds-and-the-mesh-protects-and-watches-it-from-that.md)
  — its uncertain item, resolved here.
 - [ADR 0214](0214-backups-guard-against-mistakes-and-stay-on-the-machine.md),
  [to-be 43](../03-DESIGN/01-to-be/43-backups-against-mistakes.md) — the night, the dump, restoring
  beside.
 - [Design 25](../03-DESIGN/01-to-be/25-the-bus-on-nats.md) §3–§4 — the controller remains the one
  writer of stream definitions.
 - [To-be 45](../03-DESIGN/01-to-be/45-a-core-that-cannot-fail-silently.md) — the writers table; the bus
  as a planned step.
 - mesh-catalog `modules/nats` (`snapshot/`, `Dockerfile`, `module.json`, `README.md`); mesh-controller
  `internal/broker` (`BusSnapshotGrants`), `internal/inventory/busrecords.go`,
  `internal/catalogue/manifest.go`.
@@ -1,314 +0,0 @@
 ---
 topic: the mesh
 status: accepted
 date: 2026-10-06
 deciders: jochen
 reconstructed: false
 extends: 02-DECISIONS/0227-the-core-holds-nine-rules-each-checked-and-is-built-to-them-in-six-phases.md
 ---
 # 236. A build is judged on its first machine and put back by something other than itself, and so it rolls out unattended
 > **The mechanism changed — 2026-10-06, by [ADR 0239](0239-a-delivery-is-owned-by-the-mesh-delivery-module-and-runs-from-commit-to-delivered.md).** The gate, the rollback, the
 > witness, the policy and the bus step stand as decided here. What moved: a **release plan** is no longer an
 > object of its own. A plan is the *walk* of one delivery's trunk commit, and the backlog walk of §4a credits
 > each build it carries to the delivery that published it. While `mesh-delivery` is held, a walk that moves
 > no core module starts on that module's word, and *held* is a delivery's state, released by a person through
 > `mesh-delivery`'s `release`. These are the gate rules ADR 0239 applies when a member of a delivery group fails.
 ## Context
 **The operator said "start phase 4"** of [to-be 45](../03-DESIGN/01-to-be/45-a-core-that-cannot-fail-silently.md)
 on 2026-10-06: a health definition per core component, the gate on a plan's first machine, rollback by
 a witness that is not the new build, the bus as a planned step ([ADR 0227](0227-the-core-holds-nine-rules-each-checked-and-is-built-to-them-in-six-phases.md)
 rule 8). The same day's hand-act log says what the missing phase costs:
 - **47 pushes by hand in one day**, the cause the log records most and the one that raised
  `healer-wanted` (S15). By what they did: **21 walked a new node-engine build through the four machines
  one at a time**, each pushed only after the one before was looked at; **8 carried a new controller's
  grant into the bus's user list**, which the controller's own rollout does not send; **2 were `push
  --behind`** to deliver catalogue builds that their policy held back; 16 were steps of other work a person
  was walking through.
 - **Every module but five had the upgrade policy `record`** — built on a merge, sent to no machine
  until a person pushed. `record` was the column's default since [ADR 0162](0162-a-merge-produces-a-tiered-plan-the-mesh-keeps.md)
  §3, and nothing told a `record` somebody chose from the default it always was. The five that rolled out
  were set by hand: the controller, the catalogue, the build agent, the intrusion filter and the records
  module.
 - **The one-machine-first rollout ([ADR 0218](0218-a-plan-sends-grants-before-code-rolls-out-one-machine-first-and-a-newer-merge-takes-over-an-older-plan.md)
  §2) judged the first machine by "reported applied".** A build that applies and then serves no tools,
  crashes after the report, or makes the machine's own conditions fire passes that test. Nothing put a
  failed build back: a first machine that failed stopped the plan, and the machine stayed on the build
  that failed it.
 - **The witness for the core is being built beside this.** mesh-host's node-engine keeps the previous
  controller and node tools bundles beside the new ones, judges the new controller by the lease and the
  node tools by their answer to the services protocol's ping, puts the previous build back when either is
  not healthy in its bound, and says so in every report while it stands (mesh-host PR #40). The controller
  must grant it what it reads, raise what it says, and never send what it put back again.
 - **A merge that deleted a module's directory made the controller ask the build seat to build it.**
  The merge of 2026-10-06 that folded `public-acme` into the proxy failed its plan: "has no module.json at
  modules/public-acme"; the four other modules of its tier were built and never sent.
 - **The bus's planned step had a snapshot to take since [ADR 0235](0235-the-bus-is-backed-up-by-its-own-snapshot-of-each-stream.md)**:
  the bus machine's backup holder snapshots every stream through the bus module's dump.
 **Checked against GENESIS.** *Anything requiring a human to notice it will be noticed late*: a person
 walking a build through four machines is that sentence, every day. *Failure must be loud*: a build put
 back without saying it, or never put back, is the silent failure the core exists to end. Nothing here
 conflicts with GENESIS.
 ## Considered Options
 1. **Keep `record` as the default and heal the pushes** — a healer that pushes what is behind. Rejected:
   it is a push with no judgement, the cascade of [ADR 0221](0221-a-push-sends-no-build-a-policy-or-a-plan-holds-back-except-to-the-machine-it-names.md)
   with the hand taken out; a broken build would reach every machine as fast as before, and nothing would
   put it back.
 2. **Roll everything out, gate nothing, and rely on the conditions to say what broke.** Rejected: rule 8
   says the core is judged by health, not by "applied"; a condition after a build is everywhere says what
   broke after it broke everywhere.
 3. **Gate only the core, and leave modules to `record`.** Rejected: the pushes are mostly the core's, but
   the catalogue's are the ones that stay behind the longest, and a module has health the controller can
   read as well as the core has.
 4. **A health definition per core component, a gate on every plan's first machine that judges a module by
   its own health, a rollback there by the ordinary path once per build, a witness on the machine for what
   cannot put itself back, and then rolling out as the default.** Chosen.
 ## Decision
 **1. A core component's health is a definition, written as probes.** In the self-check's registry
 (to-be 45 §4), run every five minutes on every machine and by the gate on a first machine:
 | Probe | Component | Healthy when |
 |---|---|---|
 | H-controller | controller | the lease is held, renewed within its age, by a controller that says it is ready: its self-check ran, and `status` answered in full within ten seconds in that run (D9) |
 | H-engine | node-engine | every machine heard from has reported its current declaration, under a node-engine build it names; on its first machine, under the new build |
 | H-tools | node tools | every machine heard from that runs them has them answering the bus's discovery |
 | H-bus | bus | every stream and durable consumer the mesh defines is on the bus, and a request crosses it to the machines' node tools and back |
 **2. Every release plan's first machine passes a gate before the rest are sent.** ADR 0218's first
 machine is judged from the moment it was sent the build: it reported the build applied; no witness on it
 put the build back; no condition was raised since about the machine, or about the module on it; and the
 component's health holds — a core component's definition above, or a module's own: its tools are served
 on that machine where it has tools and the machine runs the node tools that serve them. **Healthy three
 times, at least forty seconds apart and two minutes after the send, within ten minutes of it.** A module
 on one machine is judged the same way; only then does the plan go on. A policy of *together* is not
 gated: it is the module saying it must change everywhere at once.
 > **The mechanism changed — 2026-10-07, by [ADR 0240](0240-a-module-says-how-it-is-healthy-and-the-node-engine-judges-it.md).**
 > What stands: the three judgings, their spacing and bound, and the points above. What moved: *a module's own
 > health* is no longer only its tools served — every long-running resource of the module on that machine must
 > also be stated healthy by the node-engine, a resource still starting is not yet a pass, and an unhealthy one
 > is the condition `module.<module>.<machine>.unhealthy` that *no condition raised since the send* already
 > holds the module on. Designed in [to-be 48](../03-DESIGN/01-to-be/48-a-module-says-how-it-is-healthy.md).
 **3. A build that fails its gate is put back there, once, and never sent again on its own.** The plan
 stops; the build is marked failed at its gate; the module's registered build goes back to the build the
 first machine ran before — the newest successful build of that commit still kept ([ADR 0189](0189-the-store-keeps-what-the-records-name.md)
 keeps five) — and that machine is sent it, by the ordinary send. The verdict is written before the send
 and is never written over, so a controller replaced between the two does not send it twice. A build
 marked failed is refused registration if its outcome is heard again, and `plans retry` refuses the plan;
 a newer merge or a `rebuild` makes a new build, judged again. It is said as the condition
 `build.<module>.<machine>.rolled-back` (a warning: the machine runs what it ran before) or
 `core.<component>.<machine>.rolled-back` (urgent), `rollback-failed` (urgent, the operator's) when
 nothing could be put back — no earlier build kept, the machine had never had the module, the send refused
 — and as the event `rolled-back`. The probe DG keeps each until a newer build of the module passes.
 **4. A build rolls out unattended by default.** With the gate and the rollback in place, a module's
 build is sent one machine first, judged, then the rest, unless something says otherwise:
 - **a person**, through `upgrade <module> roll-out|record|default`, `record` with why; kept, said with
  who and why, and taken back by `default`;
 - **the module**, in its manifest: `upgrade` with policy `roll`, `together` or `record`, the last two
  with why;
 - **its data**: a module that declares irreplaceable data ([ADR 0233](0233-a-module-declares-the-data-it-holds-and-the-mesh-protects-and-watches-it-from-that.md)),
  its own or kept with a provider, records — a rollback cannot undo what a new build does to data that
  cannot be had again;
 - **the bus** records whatever anyone says (rule 6 below).
 The store's `record` rows were the old default and become no choice; a person's `roll-out` is kept.
 The catalogue keeps `record` where a module says why — the network path a rollback could not cross, and
 the providers every consumer on a machine drops with, among them the two holding the photos. The
 resulting policy of every module the mesh held on 2026-10-06:
 | Policy | Modules | Why |
 |---|---|---|
 | record — the bus | nats | a planned step a person starts (rule 6) |
 | record — irreplaceable data | plex, photos | the media library; the photos and their albums (the operator's ranking, ADR 0233) |
 | record — the network path | dnsmasq, nftables, networkmanager, systemd-networkd, sshd | a build that cuts a machine off from the bus cannot be put back from outside it; sshd is the way in when the mesh cannot reach it, which no gate sees |
 | record — a provider whose restart costs | postgres, mssql, mongodb, minio, keycloak | every consumer on the machine drops with it, a new version may change its data's format in place, and minio and mongodb hold the photos |
 | roll — a person's choice, kept | mesh-controller, mesh-catalog, build-agent, fail2ban, records | — |
 | roll — the default | every other module: 111 of the 129, ten of them on no machine, the node-engine and the node tools among them | gated on the first machine; the node-engine and node tools also witnessed on the machine |
 The private network itself is provided by the controller and moves only with it; the modules that run on
 no machine move nothing.
 **4a. No build reaches a machine without a gate — the backlog included.** A send carries a machine's
 whole declaration, so a plan sending one module, a cascade, a healer's resend or a whole-mesh push would
 carry every other build waiting there. Under the old default builds were registered and sent nowhere;
 on the day the default becomes `roll`, the next send of anything would restart them all at once, on every
 machine. So:
 - **a gated send carries everything waiting on its machine, and its gate judges all of it** — a plan's
  first machine, a release plan's machine; a pass is each build's verdict, a failure puts back what was
  found wanting, on the machines that were sent it;
 - a module a send exists for may move where it goes — a policy of *together*, a rollback; a build that
  passed a gate on one machine may go to the others;
 - a person's send naming a machine (`push <node>`, the bus step) carries what it carries;
 - **every other send is refused, or leaves the machine, while a build no gate has seen waits there** —
  a plan's "rest", a cascade, a healer's, a whole-mesh push, the bus's user list carried — said with what
  waits and the remedy;
 - **a rebuild that made the same artifacts from the same manifest is no move.**
  > **Progressive insight — 2026-10-06.** This rule assumed that a rebuild changing nothing makes the same
  > artifacts. That holds for an archive or a bundle, which the builder packs deterministically. It does
  > not hold for an image: every build of an unchanged source makes a new image digest. So a catalogue
  > merge that never touched the bus rebuilt it, the new digest read as a new bus build, and every send
  > to the control node was refused until a planned bus upgrade
  > ([issue 280](../04-ISSUES/280-a-rebuild-of-an-unchanged-source-was-read-as-a-new-bus/00-report.md)).
  > The rule said "a rebuild that made the same artifacts from the same manifest". It now also covers
  > **a rebuild made from the same source**: the module's tree at the commit, the trees of the contexts
  > it read, and its bases and toolchains by digest, hashed by the builder as the build's source
  > fingerprint. Such a rebuild is registered with the artifacts of the build it repeats, so no machine
  > is sent a new digest. Identical artifacts remain the second way to be no move, and the only way for
  > a build the registry decides. The decision stands: a rebuild that changes nothing is no move. Only
  > the test for "changes nothing" was wrong.
 **The release plan walks what waits.** Whenever builds no gate has seen wait on machines and no plan that
 has started walks them, the mesh opens a release plan: every such machine heard from, **one at a time,
 the control node last**, each sent everything waiting there and judged by the gate before the next is
 sent. A machine not heard from when its turn comes is left. A build asked outside a plan (a `rebuild`)
 waits for it too, instead of being sent one machine after another unjudged. **A release plan that fails
 puts back what failed and stops; the next one opens only when a person says `upgrade release-backlog
 --why`**, and until then `release-held` says what waits. `upgrade backlog` lists it, read-only.
 Chosen over holding the whole backlog for a person's release (safer by one human glance, but every
 merge after the switch would then stall behind it) and over waves of a few modules (a send cannot carry
 part of a declaration — ADR 0221's second option — so the bound that can be kept is one machine at a
 time, which is the one kept). Measured on 2026-10-06 at the switch: the catalogue merge that rebuilt
 103 modules for a change to the build agent made **88 of them byte-identical** to the builds before
 (no move) and 15 different; every machine had already been sent all of them by hand that evening, so
 **no build waited on any of the four machines** when this was decided.
 **5. The controller's rollback is the node-engine's on its machine; the contract is written once on
 each side.** mesh-controller `internal/lease/witness.go` and mesh-host `internal/witness/contract.go`,
 held field for field:
 - **What the host reads.** A direct get of the lease bucket's one key, `holder`: the lease's holder as
  the controller writes it (instance, host, epoch, taken, renewed; anything else ignored). The node
  principal of a machine assigned the controller is granted that one subject; every machine's node
  principal is granted the ping of its own node tools. Reads only: the writers table still refuses any
  write.
 - **When it is healthy.** The holder's host is the machine, it took the key at or after the moment the
  host started the new build (two seconds of skew), and renewed it within the key's fifteen seconds:
  asked every five seconds, within sixty of the start. The node tools: they answer the ping within five
  seconds, within sixty of the start.
 - **What it starts.** The previous bundle it kept, as the previous declaration ran it.
 - **What it says.** `rollbacks` on every report while the verdict stands — component, from, to, outcome,
  why, when — and `witness` with the contract's version. The controller raises
  `core.<component>.<machine>.<outcome>`: urgent for rolled-back, not-reversible, restore-failed and
  halted; a warning for nothing-to-restore and unwitnessed; cleared by the first report without it. On a
  first machine, a verdict made since the send fails the gate, so the build is marked and the registered
  build put back.
 - **What the controller adds.** It writes in the lease's value whether it is ready (rule 1), which the
  host does not read and the gate does: the host rolls back a controller that never holds the lease, the
  gate one that holds it and never becomes ready, by sending the previous build, which the host applies
  as any declaration. A process's `witness` and `not-reversible` are the host's to read; the controller
  sends neither yet — the host's defaults by name are the two witnesses above — and sends them only to a
  machine whose report carries `witness`.
 - **And the grant that follows the controller.** Once a new controller passes its gate, it sends the
  machine holding the bus the user list it composes, when that differs from the one last sent and nothing
  held back would go with it: the eight pushes of the day that carried a controller's grant by hand.
 **6. The bus is never rolled out; its upgrade is a step a person starts.** Its policy is `record`
 whatever is said, `upgrade` refuses it a roll-out, a plan builds it and sends nothing, a cascade holds its
 machine (ADR 0221), and **no send reaches its machine while a new bus build waits for it** — a push naming
 it, a plan's send for another module there, a healer's, a rollback's — each refused with the remedy. On
 2026-10-06 a plan's send of the catalogue to the control node carried the bus's rebuilt image with it,
 and the bus restarted under every machine with nobody having asked (`record` held a cascade, not the
 machine a send was for). A rebuild that made the same artifacts from the same manifest is no move. A
 change of the bus's **user list** is not a restart: the bus's image reloads its server in place when the
 list it is written changes, and that stays the ordinary path. The step is `bus upgrade --why …`: refused unless the person says whether the new version can
 be reverted (`--reversible`, or `--irreversible` as their explicit word that it runs anyway); the bus
 machine's backup holder snapshots the streams first (ADR 0235) — a person who took one by hand says where
 — and only then is the machine sent; recorded as a hand act; `bus-maintenance` (the probe DB) is open
 while it runs, and the step ends done when the machine reported the new bus applied and H-bus passes, or
 failed after fifteen minutes, said urgent with its snapshot as the way back while the bus is not healthy.
 **7. A module deleted at its source is not built.** The forge's announcer says which of a merge's files
 it deleted; a module whose manifest is among them is forgotten where nothing holds it and said otherwise
 — never asked to build. A build that finds no manifest at a module's path, from an announcer that does
 not say which files went, marks the module deleted in its plan, which goes on.
 ## Consequences
 - **A merge reaches every machine with no hand**, one machine first, judged for at least two minutes —
  and a build that breaks its first machine is put back there and goes nowhere else. The 21 pushes that
  walked a node-engine build, and the 2 that delivered held catalogue builds, are the plan's.
 - **A rollout is slower by the gate**: two minutes at the least per tier that rolls out, ten at the most
  before a verdict. A plan with a module on one machine waits on that machine's gate before its next
  tier.
 - **The controller's grant gains one verb that acts**, `node-backup now`, used only by the bus step, and
  an event, `rolled-back`; the installer's first user list carries both (mesh-host).
 - **A new bus build stalls every send to the bus's machine until a person runs the step.** A plan whose
  first machine is that machine waits, said in the plan and, past its bound, as `stalled`. That is the
  point: the bus is replaced when a person is there, not as a side effect.
 - **A change to the build agent rebuilds most of the catalogue** (its modules are built on what it
  builds), which is how the bus came to be rebuilt by a merge that did not touch it. Whether that tiering
  is right is left open here; a rebuild that changes nothing is at least no longer a move of the bus.
  > **Progressive insight — 2026-10-06.** The open question rested on a wrong cause. This consequence
  > said "a change to the build agent rebuilds most of the catalogue", and the measurement in decision 4
  > said "the catalogue merge that rebuilt 103 modules for a change to the build agent". That merge did
  > not change the build agent. It changed a file of the catalogue's reference module, which no machine
  > runs. Its definition was not in the merge, so the controller read the file as shared code and
  > rebuilt everything built from the repository
  > ([issue 278](../04-ISSUES/278-a-module-held-by-no-machine-was-read-as-shared-code/00-report.md)).
  > The build agent stood in tier 0 only because everything else is built by it. A built-by edge
  > orders a plan and never widens it, so a change to the build agent rebuilds the build agent alone.
  > The controller's test checks this over the real dependency relation. The open question is answered:
  > the tiering was right. What was wrong is now fixed: the forge's announcer says which directories
  > hold a module at the merge commit, and only a file in none of them is shared. The measurement
  > stands as a count; only its cause was wrong. Everything this record decided stands.
 - **Thirteen modules still wait for a person**, each saying why in the catalogue or by its data; `status`
  lists the machines behind them and `push <machine>` walks them, as before. A person who wants another
  held says `upgrade <module> record --why …`.
 - **What the gate cannot see.** A container that crash-loops after its compose applied is seen only
  through what it breaks — its tools, a provider's failing word, the machine's own conditions — until the
  node-engine reports container state, which is mesh-host's to add. A build whose migration cannot be
  undone is put back all the same; marking such a build `not-reversible` for the witness is not composed
  yet.
 - **A merge after a release plan failed may stall** on a machine where a build waits for the person's
  release: its first send carries and judges what waits there, but its "rest" waits. Said in the plan
  and by `release-held`.
 - **Rollout order**: mesh-host first (its genesis user list, and the witness, which reads nothing the
  controller does not yet grant until then); the controller second, whose migration turns the store's
  default `record` rows into no choice; the catalogue third — its manifests carry `upgrade`, which a
  builder older than the controller refuses.
 ## How it is checked
 | Rule | Checked by |
 |---|---|
 | the gate holds back the rest | the controller's test against a real store: a build that fails its gate on the first machine is put back there, registered at the previous build, marked, said as a condition and an event, never sent to the second machine, never registered or rolled back again, and `plans retry` refuses it |
 | a passing build rolls everywhere | the controller's test: three healthy judgings, then the rest sent and the plan done, its verdict kept, no condition |
 | the bound | the controller's test: a first machine never healthy fails at the bound and is put back |
 | the health definitions | the controller's test per component: tools not served, a condition since the send, a witness's verdict, node tools not answering, a lease held by an older controller or one not ready |
 | the policy | the catalogue's test: default roll, a module's word, irreplaceable data, the bus whatever it says; a record without why refused; the store's test: the current builds read the derived policy |
 | the bus is never rolled out | the controller's test: the bus records whatever it says, a person's roll-out is refused, a plan sends nothing, no send may reach its machine while a new bus build waits — a rebuild with the same artifacts and manifest excepted — the step refuses without its word on reversibility and without its snapshot, and starts with both |
 | no build without a gate | the controller's test: the backlog released one machine at a time, the first judged before the second is sent, each pass kept, a rebuild with the same bytes no move, a send that judges nothing refused; a release that fails puts back what it carried on its first machine, goes no further, holds the next until a person releases it with why; a cascade does not carry a build no gate has seen, and does once one passed |
 | a deleted module is not built | the controller's test: a merge deleting a module's manifest asks no build and forgets it; a build finding no manifest leaves the plan going |
 | the witness's contract | the lease package's test of the host's rule; the broker's test of the grants (the ping on every machine, the lease's key where the controller runs, no write); the controller's test that a witness's verdict is its condition while reports carry it and cleared after |
 | live | the next merge to the catalogue sends one machine first and the rest after its gate, with no push; `plans <id>` shows the gate's record; the next week's hand-act log has no push for a build that rolled out |
 ## References
 - [To-be 45](../03-DESIGN/01-to-be/45-a-core-that-cannot-fail-silently.md) §8 and Phase 4 — the design
  this builds and amends.
 - [ADR 0218](0218-a-plan-sends-grants-before-code-rolls-out-one-machine-first-and-a-newer-merge-takes-over-an-older-plan.md),
  [ADR 0221](0221-a-push-sends-no-build-a-policy-or-a-plan-holds-back-except-to-the-machine-it-names.md),
  [ADR 0162](0162-a-merge-produces-a-tiered-plan-the-mesh-keeps.md) — the rollout, the hold, the policy,
  whose mechanisms move here.
 - [ADR 0233](0233-a-module-declares-the-data-it-holds-and-the-mesh-protects-and-watches-it-from-that.md),
  [ADR 0232](0232-a-binding-to-a-consumers-data-moves-only-by-a-person.md) — the data a rollout never
  moves; [ADR 0235](0235-the-bus-is-backed-up-by-its-own-snapshot-of-each-stream.md) — the snapshot the
  bus step takes.
 - mesh-controller, mesh-host, mesh-catalog: the branches `feat/core-upgrades-that-roll-back`;
  mesh-host's witness `feat/core-upgrades-roll-back`.
@@ -1,170 +0,0 @@
 ---
 topic: the mesh
 status: accepted
 date: 2026-10-06
 deciders: jochen
 reconstructed: false
 extends: 02-DECISIONS/0227-the-core-holds-nine-rules-each-checked-and-is-built-to-them-in-six-phases.md
 ---
 # 237. A change is judged against the mesh that runs, before it merges, on the build seat
 > **Narrowed, not replaced — 2026-10-06, by [ADR 0238](0238-a-commit-is-the-build-at-hand-one-commit-one-change-plan-checked-off-the-trunk-and-published-only-on-it.md).**
 > Decision 4's *which* and *what* moved: a pull request is checked when the mesh's module graph says it
 > reaches a module — the planner's own answer, not *a repository it builds a module from into that
 > branch* — and every repository of the mesh runs its own `merge-check.sh` as a second status,
 > `mesh/repo-check`, a warning when it has none, instead of *the gate alone*. The gate itself is the
 > build seat's, no longer each repository's script. The facts, the gate's rules, the replays, where a
 > check runs and what it is given stand as decided here.
 ## Context
 **The operator approved starting Phase 5** of [to-be 45](../03-DESIGN/01-to-be/45-a-core-that-cannot-fail-silently.md)
 on 2026-10-06: the facts snapshot, the merge gate, versions tested as run, and the replays of
 [ADR 0227](0227-the-core-holds-nine-rules-each-checked-and-is-built-to-them-in-six-phases.md) rule 9. The
 design says what they are; building them left decisions it does not make — where a check runs on a mesh
 that has no CI, what a snapshot must hold for a check to compose a machine faithfully, where a replay lives
 when its incident is in one repository's logic and when it is in what the mesh runs, and how a test suite
 that failed in parallel can be one a gate is allowed to read.
 The evidence is research 031's class (h), *checks that pass in CI and fail live*, and the incidents of the
 window since:
 - **236**: a manifest passed `module check` and was refused whole by the node-engine on the first machine
  it was assigned to. **263**: a real machine's name made a consumer's identity 26 characters against a
  bound of 20, and the provider's whole machine could not be pushed. **262**: an answer glibc forgave was
  final to musl. Each check was right about the world it was given; none was given the mesh's.
 - **278**: a file of a module no machine held read as shared code, and a merge rebuilt 103 modules. Its
  width could have been read before the merge; nobody was shown it.
 - **The controller's suite failed when its packages ran in parallel** against one shared bus, and one test
  hung under the race detector: the live tests assert, read and remove the mesh's own objects by their
  fixed names, so two packages at once were one deleting what the other read. A red suite read as noise.
 - **The bus tests ran a release the mesh did not run** (2.10's instructions in the tests' own comments
  after the bus had moved to 2.11), and the 2.10 release that skipped messages (266) had been tested by
  nobody's tests.
 ## Options weighed
 **Where a check runs.**
 1. *An outside CI.* Rejected: a second system to run, watch and keep in step, with no access to the mesh's
   facts, its artifact store or its toolchains — the very things a check must be fed.
 2. *The live controller composes the change.* Rejected as the gate: a change to the controller is judged by
   the controller it changes, so the running one cannot judge it; and a composition run inside the serving
   controller is load and risk on the control node for every pull request.
 3. **The build seat, as one more kind of work on its queue** — chosen. The build machine already holds the
   repositories, a container runtime, the artifact store and the mesh's Go toolchain; the controller already
   asks it for work and watches every ask (S6).
 **Where the facts are kept.** A key-value bucket on the bus would need a grant for every reader and a bus
 that carries a document of a megabyte. **The artifact store, under `facts:latest`** — the design's choice —
 is read by any machine of the mesh over plain HTTP, keeps one version, and is where the build seat already
 reads and writes.
 **Where a replay lives.** All in mesh-lab would put a test of the controller's planning in a repository that
 cannot import it. All in their own repositories would leave the bus's release and the resolver's answers —
 what the mesh *runs*, not what it wrote — with no home. **Both, by kind** — chosen.
 **What the tests' bus is.** A shared bus per run needs serialised packages and still leaks between tests.
 **A server per test, linked in at the release the mesh runs** — chosen.
 ## Decision
 1. **The facts snapshot.** The controller (lease holder) composes it every ten minutes and keeps it in the
   artifact store as `facts:latest` when its content moved or the one kept is a day old; the manifest it
   replaced is deleted by digest, so the nightly collector takes it and the store keeps one. It holds every
   machine — under a stable pseudonym of the same length as its name — with its roles in words, system,
   C library, architecture, builds, reported capabilities, assignments, pins, settings and the names (never
   the values) of secrets a person gave; every seat and holder; every module the mesh holds, as its manifest,
   with its source and build edges; the bus's, store's and node-engine's versions as they run; and how each
   machine's declaration composes today. No secret, no address: a key or value reading as a secret is
   withheld, an address becomes one from a documentation range, and machine, site, account and domain
   names are replaced wherever they appear. `facts`, `facts compose`, `facts export` read and write it by
   hand. **S14** raises `facts-stale` past two days.
 2. **The merge gate is the controller's `merge-gate`.** It raises two throwaway stores from the snapshot
   through the controller's own records — the mesh as it is, and with the change's manifests in place of the
   mesh's — composes every machine twice in each (the first time making the credentials a push makes), and
   runs the node-engine's validator over each body. **What composes in the first and not in the second is
   the change's**, named by the machine's roles and the module; what was already broken is said and fails
   nothing. It also fails: a manifest the judging controller cannot read; a consumer the change leaves out
   of a grant or a credential it leaves bound elsewhere; a module a machine runs removed from its source;
   two definitions of one module name; a stored setting the changed definition cannot keep; and a module no
   machine runs yet that the node-engine would refuse on the first machine that could run it (tried there
   and taken back). It **warns** when a merge would rebuild more than twelve modules, and says when shared
   code is why — the width read with the same rule the merge handler uses, the changed directories that
   hold a definition read from the tree as the forge's announcer reads them.
 3. **A catalogue change is judged by the controller the mesh runs** (version skew caught: a field only a
   newer controller reads fails the pull request, not the registration after it); while the running one
   predates the gate, by the controller's main, said. A controller change is judged by itself. A node-engine
   change is judged by the running controller built with the change's validator in place of the one it
   vendors.
 4. **The check runs on the build seat.** The forge's announcer — the one that announces merges — announces
   each new head of an open pull request (`pull.updated`) and marks it pending; the controller, for a
   repository it builds a module from into that branch, asks the build seat a check: the head, and beside it
   the controller the mesh runs and its main, the catalogue, the node-engine it runs, and mesh-lab. The
   builder reads the snapshot, raises a throwaway store and bus **of the versions the snapshot says run**,
   builds the judge, and runs the repository's own `merge-check.sh` — or the gate alone for a repository
   with none — **in the mesh's Go toolchain, in a container of its own with no container runtime socket**:
   a pull request is code nobody has approved yet. Then mesh-lab's replays from its main — reviewed code —
   with the socket, against that bus and the change's own catalogue. The verdict is pass, warning, fail, or
   **error, never read as a pass**, said by the controller as `checked`; the forge's holder sets it as the
   head commit's status `mesh/merge-gate` and, when it is not a pass, comments with the check's own account.
   Nothing a check does is recorded or registered. Whether the status is required to merge is the
   operator's setting on the forge.
 5. **A replay lives where its incident is.** One of a component's logic is a test in that repository,
   named `TestReplay<issue>`, written only with what the component had before the fix, so it can be laid
   over the older commit. One of what the mesh runs — the bus server's release, the resolver the catalogue
   configures under musl and glibc — is in mesh-lab's `replays/`. mesh-lab's `register.go` names every
   replay with its issue and fix, and `replays/cmd/prove` runs each on the commit before its fix (it must
   fail, or, for a check that did not exist, not build) and on its fix (it must pass).
 6. **A core issue resolves with its replay or a stated reason.** An issue opened from 2026-10-07 whose
   `located-in` names a core repository — mesh-controller, mesh-host, mesh-tools, mesh-sdk, or the
   catalogue's bus, forge or build-agent module — cannot be `resolved` without `replay:` (a register id) or
   `replay-none:` (why none is possible). The issues the replays were written from carry theirs.
 7. **The tests' bus is a server of their own, of the release the mesh runs.** The controller's suite links
   the bus server in at the version go.mod pins and starts one per test; a test holds that pin to the
   catalogue's bus image and, given a snapshot, to the release the mesh runs. The suite runs its packages in
   parallel and under the race detector; a test reading timing, not state, is rewritten to read state. A
   person may still point a run at a bus of their own with `MESH_TEST_NATS_EXTERNAL=1`.
 ## Consequences
 - **A pull request to the core or the catalogue waits minutes for its verdict**, and the controller's
  merge check runs the whole suite. That is the cost ADR 0227 accepted against the hours each of 202, 236
  and 263 cost.
 - **The gate is as faithful as the snapshot.** What the snapshot does not carry — a machine's adopted
  state's detail, its tunnels, ports chosen by hand — a machine may compose differently in the gate than on
  the mesh; then the gate says the machine composes on the mesh and not as raised, and judges it by what the
  change adds. A gap that hides a real failure is found by the live probe D1, which stays.
 - **The build agent pulls the toolchain, store and bus images for every check**, and mesh-lab's replays
  pull the resolver and two C libraries' images from the public registry.
 - **A bus upgrade is a pin moved in two places**: the catalogue's image and the controller's go.mod, which
  a test holds equal. That is the rule, not a cost of it.
 - **The forge's holder stays TypeScript** for this change; porting it to Go is its own piece of work.
 ## How it is checked
 | Rule | Checked by |
 |---|---|
 | the snapshot carries no secret, address or name, and every machine's length | the controller's test raising a mesh with secrets, settings holding a password, an address and a machine's name, a credential made, and asserting none is in the snapshot; the scrubber's own tests |
 | the snapshot is kept, one version, and said when stale | the artifact store's live test against the store's registry (put, read back by tag, the replaced one collected); S14's suppression in the generated signals test |
 | the gate fails 236, 263, version skew, a removal, and says 278's width | the controller's gate tests, one per incident, against a raised mesh |
 | a check runs the repository's script beside the mesh's versions, leaves nothing, and is never a pass when it cannot run | the builder's live tests against a container runtime and a registry |
 | the verdict reaches the pull request, an error never as a success | the forge module's tests |
 | 236, 262, 263, 266 (and 273) fail before their fix and pass after | `replays/cmd/prove` in mesh-lab |
 | a core issue resolves only with a replay or a reason | `00-META/checks/cycle.py` |
 | the tests' bus is the mesh's release, and the suite is deterministic | `internal/testbus`'s tests; the suite run three times in parallel under the race detector |
 ## References
 - [ADR 0227](0227-the-core-holds-nine-rules-each-checked-and-is-built-to-them-in-six-phases.md) rule 9,
  [to-be 45](../03-DESIGN/01-to-be/45-a-core-that-cannot-fail-silently.md) §9 and Phase 5.
 - [ADR 0225](0225-a-consumers-identity-is-bounded-by-the-provision-it-requires.md),
  [ADR 0232](0232-a-binding-to-a-consumers-data-moves-only-by-a-person.md),
  [ADR 0236](0236-a-build-is-judged-on-its-first-machine-and-put-back-by-something-other-than-itself-and-so-it-rolls-out-unattended.md).
 - Issues [236](../04-ISSUES/236-the-catalogue-check-passes-a-manifest-the-host-refuses/00-report.md),
  [262](../04-ISSUES/262-an-alpine-container-could-not-find-a-machine-by-its-mesh-name/00-report.md),
  [263](../04-ISSUES/263-every-consumer-pays-for-the-tightest-backends-name-limit/00-report.md),
  [266](../04-ISSUES/266-a-merge-on-the-bus-was-never-handed-to-the-controller/00-report.md),
  [273](../04-ISSUES/273-a-rule-for-the-resolver-moved-a-machines-databases/00-report.md),
  [278](../04-ISSUES/278-a-module-held-by-no-machine-was-read-as-shared-code/00-report.md).
@@ -1,193 +0,0 @@
 ---
 topic: the mesh
 status: accepted
 date: 2026-10-06
 deciders: jochen
 reconstructed: false
 supersedes-in-part:
  - 0237-a-change-is-judged-against-the-mesh-that-runs-before-it-merges-on-the-build-seat.md
 extends: 02-DECISIONS/0237-a-change-is-judged-against-the-mesh-that-runs-before-it-merges-on-the-build-seat.md
 ---
 # 238. A commit is the build at hand: one commit, one change plan, checked off the trunk and published only on it
 > **Superseded in part — 2026-10-06, by [ADR 0239](0239-a-delivery-is-owned-by-the-mesh-delivery-module-and-runs-from-commit-to-delivered.md).** Decision 6's state machine is
 > built as a **delivery**'s, owned by the module `mesh-delivery` rather than by the controller. Its states are
 > renamed (`releasing` → `delivering`, `done` → `delivered`) and a delivery group sits above it. Decision 7's
 > note and status link are written by the forge's holder when it hears a delivery's transition, and the link
 > leads to the delivery's view on the pull request. The *change plan* is called the **delivery plan**. Decisions
 > 1 to 5 stand as decided here.
 ## Context
 [ADR 0237](0237-a-change-is-judged-against-the-mesh-that-runs-before-it-merges-on-the-build-seat.md) put a
 check before every merge and ran it on the build seat. Turning it on for every repository of the mesh, the
 same day, showed four places where it asked the wrong question.
 - **Which pull requests are checked was the repository's choice, not the mesh's.** The controller checked a
  pull request when the mesh built a module from that repository into that branch, and ran the
  repository's `merge-check.sh`, or the gate alone. A repository nothing is built from (the decision
  records, the lab) was not checked at all, and its pull request kept the forge's *pending* forever. A
  repository with no script ran only the gate, and nobody was told its own tests never ran.
 - **The gate had its own idea of what a change touches.** The merge handler, the release planner's
  what-if, the gate's *rebuild width* and the gate's composition each read a change's files in their own
  way. Two of them agreed with each other; none of them was guaranteed to agree with the plan a merge
  then made.
 - **The rule they shared was wrong.** A file in no module's directory was read as *shared code*, and
  everything built from the repository was rebuilt for it. The builder never reads such a file: it clones
  the repository and builds within the module's own directory (the whole repository for a module built
  from its root), plus any other repository an artifact's recipe names. Adding `merge-check.sh` at the
  catalogue's root planned 103 rebuilds ([issue 280](../04-ISSUES/280-a-rebuild-of-an-unchanged-source-was-read-as-a-new-bus/00-report.md),
  *Left open*). [Issue 278](../04-ISSUES/278-a-module-held-by-no-machine-was-read-as-shared-code/00-report.md)
  and [issue 252](../04-ISSUES/252-a-merges-changed-modules-were-read-wrong/00-report.md) had each patched
  an exception into the same rule.
 - **Nothing stopped a commit off the trunk becoming a module's version.** `build --ref <branch>` of a
  feature branch registered what it built, and the next push could send it. A pull request's head was
  only kept out of the catalogue by the check never asking to register it — a convention.
 ## Considered Options
 **What decides whether a pull request is checked.**
 1. *The repository opts in*, with a script or a registration. Rejected: a repository that has not opted in
   is exactly the one nobody is watching, and the forge said *pending* for it forever.
 2. **The mesh's module graph** — chosen. The controller holds every module, the repository and directory
   it is built from, and the build records' other repositories. Every pull request the forge holds is
   announced, and the graph says what it reaches.
 **Where what a change touches is computed.**
 1. *In the gate, beside the planner.* Rejected: two computations of one fact drift, and the drift is found
   when a merge does something its check did not say.
 2. **In the planner, once** — chosen. One function maps a changed file onto modules, one function answers
   what a merge would move and build; the merge handler, the what-if, the gate and the check all ask them.
 **What a file outside every module's directory touches.**
 1. *Everything built from the repository* (the shared-code rule). Rejected: no build reads it — the cost
   was 103 rebuilds for a script at the root.
 2. **Nothing** — chosen. A build reads its module's directory and the repositories its recipes name;
   a repository a recipe names is the build record's, already followed.
 **How a commit off the trunk is kept from being published.**
 1. *By convention*: checks do not ask to register. Rejected: a person building a branch by hand registered
   it, and a definition nobody had reviewed reached a machine ([issue 240](../04-ISSUES/240-a-dry-run-build-is-recorded-and-rolled-out/00-report.md)'s class).
 2. **By refusal in code**: the build seat says which branches hold the commit it built; the controller
   records and never registers a build off its module's trunk — chosen.
 ## Decision
 1. **The commit is the build at hand, and where it sits decides what may happen.** A commit **not on the
   trunk** — a pull request's head, any branch — is only *checked*: its change plan computed, the gate run
   (composed machines validated, replays), its own tests run, the verdict posted. Nothing of it is
   registered or sent to any machine; anything built to check it is never registrable. A commit **on the
   trunk** is *published* — its builds registered as the module's version — and *pushed*, by the gated
   release. **The trunk** is the branch the module follows; for a module new to the catalogue, its
   repository's default branch as the forge names it. Enforced in code: the build seat reads, from its own
   fresh clone, the default branch and every branch holding the commit, and says them with the outcome;
   the controller records a build off its module's trunk and refuses to register it, naming the trunk —
   which covers `build --ref`, `rebuild` and `replay --register` alike. A check's or a dry run's outcome
   is never registered. A build seat older than this rule says nothing, and its build is registered as
   before and said, so the rule can reach the mesh through the build seat it is built into.
 2. **One commit, one change plan.** A change plan is computed from a diffset — a repository, the branch it
   merges into, the commit at hand — by the planner: the **build plan** (the modules the merge moves
   itself, their dependents in tiers; whether each is a move is its build's source fingerprint, issue
   280), the **deploy plan** (per machine, what it is sent in the build plan's order; what waits there
   for a person; steps that are not an ordinary send flagged: a planned bus step, a provider whose
   consumers are sent again, a module keeping data per ADR 0232/0233), and the **verdict** (the composed
   machines, the replays). It is one object: a pull request's check posts it as its result, the release
   after the merge follows the same planner and says what differs when another merge landed meanwhile,
   and `plans` answers it for any base and head. It is kept — its id, its inputs, its result — so the
   pull request, the release and the operator refer to the same thing.
 3. **The planner maps a change onto the modules, once.** A changed file touches exactly the modules whose
   build reads it: a module's own directory, the whole repository for a module built from its root, and
   a repository a recipe names (the build record's `read`). A file read by no build — at the root, in a
   directory no module is in — touches nothing and is said as such. A directory the change adds a
   `module.json` in, which the graph does not hold, is a new module: checked, never built by the merge.
   One function does the mapping and one answers the whole reach; the merge handler, the release
   planner's what-if, the merge gate and a pull request's check call them, and nothing else maps a path.
 4. **The graph decides what is checked, in two layers** (replacing ADR 0237 decision 4's *for a
   repository it builds a module from into that branch* and *or the gate alone*). The forge's holder
   announces every pull request it holds, with the directories holding a module at its head, the files
   it deletes and whether its head has a `merge-check.sh`. The controller answers every one:
   - a change that reaches a module, or adds one: the build seat runs **the gate**, status
     `mesh/merge-gate` — the touched manifests through `module check` (a problem the base branch already
     had is said and fails nothing), every machine composed with the definitions of the modules the plan
     moves or adds (not every definition in the tree), the replays — judged by the controller the mesh
     runs, a controller change by itself, a node-engine change by the running controller with its
     validator;
   - every repository of the mesh — one a module is built from on some branch, one of the core's owner,
     one the change adds a module to — gets **its own check**, status `mesh/repo-check`: its
     `merge-check.sh`, in the toolchain it declares (`# mesh-check-toolchain: go|typescript`); a
     repository with none is a **warning**, never a pass and never silent;
   - a change that reaches nothing is a pass that says so — a fact, not a missing check — and a
     repository outside the mesh is told nothing more.
 5. **Required statuses are the operator's setting, applied by the forge's holder.** `mesh/merge-gate` is
   required on the trunk of every repository a module is built from, the list derived from the graph;
   `mesh/repo-check` as well on the core repositories. The forge module's
   `gitea_branch_protection_get` / `gitea_branch_protection_set` read and set it; a new rule refuses direct
   pushes.
 6. **A change plan is a state machine, one table.** States and the transitions allowed between them,
   each with its guard, compiled once; any other transition is refused. `proposed` (a head) → `checked`
   → `rejected` | `ready`; `ready` → `published` (guard: the commit on the trunk, its builds registered)
   → `releasing` (per machine: sent → judging → passed | failed → rolled-back) → `done` | `failed` |
   `superseded` (a newer plan for the same repository and trunk) | `stopped` (a person, with why) |
   `held` (waits for a person: the release backlog, a bus step, a module whose policy records) →
   `releasing` (guard: a person's decision, with why). It replaces the release plans' implicit states
   (open, building, judging, done, failed, superseded, stopped, held), so there is one machine, not two.
   Every transition is kept with the plan and the commit, said on the bus, and appended to the commit's
   note; the plan resumes from its recorded state under the lease after a restart; a state held past its
   bound raises a condition, and healer H2 works from the table.
 7. **The plan is attached to its commit.** The `mesh/merge-gate` status links to the kept plan and
   describes it in a line ("builds gitea → the control node; no bus step; 4/4 compose"). A git note under
   `refs/notes/mesh-plan` on the pull request's head carries the plan's id and the predicted summary; on
   the merge commit on the trunk, the executed plan — what was built, sent where, the gates' verdicts,
   rollbacks, timings — written by the mesh's own forge account after the release, never by a person's
   or an agent's hand. The note writer appends: running twice adds nothing, and an outcome amends the note,
   never history. `git log --notes=mesh-plan` shows each commit's plan.
 ## Consequences
 - **A module built from a branch other than its repository's default keeps that branch as its trunk.**
  Three applications are built from such a branch; a module new to the catalogue from one is refused until
  the branch is the default or merged into it.
 - **The build seat must be updated before the trunk rule bites.** Until the build seat built from this
  change is held, it says nothing and its builds register as before, said in the controller's log.
 - **The repository's own check runs code nobody has approved, and is given nothing to leak**: no container
  runtime socket, no package-registry credential. A suite that needs the mesh's own packages from the
  registry says those tests did not run; the Go toolchain gains a C compiler (the race detector) and Python
  (the decision records' checks), and the TypeScript toolchain git.
 - **A rebuild is narrower**: a file at a repository's root rebuilds nothing; the release planner and the
  gate say the files no build reads.
 - **What is decided here and not yet built** is listed in to-be 45's Phase 5 and stays there until it is:
  the kept change plan and its comparison at release, the state machine replacing the release plans'
  states, the notes, the status's link.
 ## How it is checked
 | Rule | Checked by |
 |---|---|
 | a commit off its module's trunk is recorded and never registered; a check or a dry run never is | the controller's test of the publish rule (on the trunk, off it, a module following another branch, a feature branch named by hand, a check, a dry run, a build seat that says nothing); the builder's test reading the trunk and the branches holding a commit from a fresh clone |
 | one function maps a changed file onto modules, and every reader asks the planner | the controller's tests that a pull request's reach is the merge's (moved, dependents, width, unread) for a root file, a module's directory and both; the merge handler's and the gate's width tests on the same rule; a review of the callers, listed in the pull request |
 | a file no build reads touches nothing; a repository a recipe names reaches its packager | the merge-handler tests (a root file, a directory with no manifest, a file among the modules), the gate's width test (a root file and a README rebuild nothing), the check's test of a packaged repository |
 | every pull request is answered: a gate when it reaches a module, a repository check for the mesh's repositories (a warning without a script), a pass that says so otherwise | the controller's scope tests; the builder's test of a check with nothing to run; the builder's live tests (a script run beside the mesh's versions, failing, in a toolchain the mesh does not hold, past its bound, the gate with a stand-in judge) |
 | a manifest problem the base already had fails nothing | the builder's live gate test with a manifest broken on the base branch |
 | the statuses and the plan reach the pull request; an error is never a success | the forge module's tests of both statuses, the plan's line and comment |
 | the change plan says what each machine receives and what is not an ordinary send | the controller's change-plan test (a module's own change, the bus with its dependents and a module that waits, a root file) |
 | a branch protection rule is set as asked and a new one refuses pushes | the forge module's protection tests |
 | the state machine refuses a transition not in its table; notes are append-only | not yet built: a test walking the table, as the signals and healers tables are walked; the note writer's idempotence test |
 ## References
 - [ADR 0237](0237-a-change-is-judged-against-the-mesh-that-runs-before-it-merges-on-the-build-seat.md),
  [ADR 0236](0236-a-build-is-judged-on-its-first-machine-and-put-back-by-something-other-than-itself-and-so-it-rolls-out-unattended.md),
  [ADR 0162](0162-a-merge-produces-a-tiered-plan-the-mesh-keeps.md),
  [ADR 0132](0132-a-seat-carries-the-tools-its-holder-must-serve.md).
 - [to-be 45](../03-DESIGN/01-to-be/45-a-core-that-cannot-fail-silently.md) §9 and Phase 5;
  [to-be 30](../03-DESIGN/01-to-be/30-the-mesh-updates-itself-on-a-push.md).
 - Issues [252](../04-ISSUES/252-a-merges-changed-modules-were-read-wrong/00-report.md),
  [278](../04-ISSUES/278-a-module-held-by-no-machine-was-read-as-shared-code/00-report.md),
  [280](../04-ISSUES/280-a-rebuild-of-an-unchanged-source-was-read-as-a-new-bus/00-report.md).
 - mesh-controller #101, mesh-catalog #98, mesh-host #43, mesh-tools #18, mesh-tools-go #1, mesh-sdk #11,
  mesh-lab #53, mesh-media-catalog #12, and the applications' own checks.
@@ -1,376 +0,0 @@
 ---
 topic: the mesh
 status: accepted
 date: 2026-10-06
 deciders: jochen
 reconstructed: false
 supersedes-in-part:
  - 0238-a-commit-is-the-build-at-hand-one-commit-one-change-plan-checked-off-the-trunk-and-published-only-on-it.md
 extends: 02-DECISIONS/0238-a-commit-is-the-build-at-hand-one-commit-one-change-plan-checked-off-the-trunk-and-published-only-on-it.md
 ---
 # 239. A delivery is owned by the mesh-delivery module and runs from commit to delivered
 ## Context
 [ADR 0238](0238-a-commit-is-the-build-at-hand-one-commit-one-change-plan-checked-off-the-trunk-and-published-only-on-it.md)
 made the commit the build at hand and gave it one change plan, and decided (its decision 6) that the plan is a
 state machine in one table. It did not say who owns that machine, and nothing built it. On 2026-10-06 the
 operator decided that a new module owns it, named it `mesh-delivery`, and anchored it in
 [to-be 10](../03-DESIGN/01-to-be/10-delivery.md), whose title is *Modules and delivery*.
 What the day showed:
 - **"Did my change go out?" had no owner.** The forge's holder knew the pull request, the controller knew the
  merge's plan, the build seat knew the builds, the gate knew the first machine, and the hand-act log knew
  the 47 pushes made by hand. A person joined those five records by hand to answer for one commit.
 - **The release plan's lifecycle was implicit.** `building`, `rolling`, `done`, `failed`, `superseded`, and
  the release backlog's `held` were strings in `inventory.Plan.State` and in the note beside it. No table said
  which state may follow which. A plan could be closed by hand, by healer H2, by a newer merge, or by a gate.
  Each did it in its own code, and none said so on the forge.
 - **Nearly every change crossed repositories, in an order that was not written down.** A catalogue manifest
  used a field only a newer controller parses, so the controller had to go first. The node-engine's genesis
  lock had to mirror the controller's grants. A toolchain image had to be built before the builds that use it.
  Each order was known to the person merging and to nothing in the mesh. A wrong order failed at
  registration (version skew) or on a machine.
 - **The controller is the one component that cannot be judged by itself.** Every orchestration put in it
  adds to what has to be right before anything can be repaired. The witness ([ADR 0236](0236-a-build-is-judged-on-its-first-machine-and-put-back-by-something-other-than-itself-and-so-it-rolls-out-unattended.md)
  §5) exists because of that.
 To-be 10 says *"There is no pipeline as a state machine. No stage list something can be omitted from, and
 no run to lose."* That was written against a pipeline that decides what to build. It still holds: what is
 built is decided by comparing source with artifacts, and nothing here changes that. What it lacked is a
 record of one commit's journey through the mesh that has an owner. That record must stay durable when the
 controller is replaced, and it must refuse an impossible step instead of drifting into one.
 **Checked against GENESIS.** *Anything requiring a human to notice it will be noticed late*: a person joining
 five records is that sentence. *Failure must be loud*: a delivery stopped half-way, with nothing saying where,
 is the silent failure the core exists to end. Nothing here conflicts with GENESIS.
 ## Considered Options
 **Who owns a delivery.**
 1. *The controller, as ADR 0238 decision 6 left it implicitly.* Rejected. The controller would own the
   delivery of the controller. Its states would sit in the store the controller migrates. Every new rule about
   order, holds and groups would be one more thing the component that cannot be judged by itself must get
   right first.
 2. **A module, `mesh-delivery`, holding a mesh-scoped seat of the same name.** Chosen. One owner per thing.
   The controller stays the owner of what it already owns: machine declarations, bus objects, grants,
   registration and the gate's primitives. The delivery is the new module's.
 **What it is called.** *Change* was rejected: it is the forge's and git's word for a diff, and it names the
 input, not the journey. *Upgrade-planner* was rejected: `upgrade` already names a module's policy (ADR 0236
 §4), and the thing is more than a planner. *Release* was rejected: a release plan is one stage of the journey,
 the stage this decision folds in, and keeping the word would keep two concepts. *Pipeline* was rejected
 because to-be 10 retires it. **Delivery** is to-be 10's word for the whole of it.
 **What a delivery is.**
 1. *A merge.* Rejected: a pull request is checked long before it merges, and a merge's commit is not the one
   the forge shows the verdict on.
 2. *A group of commits across repositories, as the unit.* Considered on the day and replaced. A group as the
   only object has no one commit status, no one note and no one pull request. Everything the forge shows is
   per commit.
 3. **One commit in one repository, and a delivery group of deliveries one level above it (the composite).**
   Chosen. A delivery is 1:1 with git and the forge: one pull request, one head commit, one status, one note.
   A group holds deliveries and never groups. A lone delivery needs no group.
 **How a delivery joins a group.**
 1. *By timing* (merged close together). Rejected: guessing is the fault being removed.
 2. *By a trailer, a field in the pull request, or a verb.* Rejected as the mechanism. Each is a second thing a
   person must keep in step with the branch they already named, and a verb is a hand act on every
   cross-repository change.
 3. **By the pull request's head branch name, across the mesh's repositories.** Chosen.
   [Playbook 07](../00-META/process/07-feature-branches.md) already requires one feature to be one branch
   name in every repository it touches. The mesh reads the name the person already gave. Two or more open
   pull requests with the same head branch form one group. A pull request whose branch name is used in no
   other repository is a lone delivery. To keep a change out of a group, rename its branch.
 **Dependencies between separately planned deliveries (`needs:`).** Dropped. A delivery that depends on another
 is in the same feature and belongs in its group. A dependency on a delivery already delivered needs nothing.
 A second linking mechanism would be a second graph to keep acyclic and to show.
 **Where the walk across machines runs.**
 1. *Ported into mesh-delivery*: the module asks for each tier's build, picks the first machine, asks for one
   gated send, polls the judgement and asks for the rest. Rejected for now. The walk holds the fixes of issues
   214, 219, 249, 254, 256, 280 and 281. The bootstrap rule below requires the controller to keep a walk for
   its own updates and for mesh-delivery's. Porting it means two walks, and one of them would be less tested.
 2. **The walk of one trunk commit across machines stays the controller's primitive, and mesh-delivery decides
   when it may start, records each step, and stops it.** Chosen. Sending, the gate and the rollback are the
   primitives the controller keeps. The walk is their sequence for one commit, as `push <machine>` is a
   person's sequence of one. Everything above that sequence moves to mesh-delivery: whether and when, in what
   order, waiting for whom, superseded by what, stopped by whom, and the record.
 **Where a commit's check is triggered.**
 1. *mesh-delivery hears every pull request and asks the controller to check it.* Rejected. A mesh-delivery
   that is down would check nothing, including the pull request that fixes mesh-delivery, and that is a mesh
   that cannot be fixed.
 2. **The controller keeps answering every pull request's head itself (ADR 0238 decision 4), and mesh-delivery
   records the verdict as the delivery's `checked` and asks only for what the controller cannot know: the
   group's composed check.** Chosen.
 **When a published delivery's builds are registered.**
 1. *At the merge, as before, and the walk held back until its turn.* Rejected. A send carries a machine's
   whole declaration, and a gated send carries every registered build that waits on its machine
   ([ADR 0236](0236-a-build-is-judged-on-its-first-machine-and-put-back-by-something-other-than-itself-and-so-it-rolls-out-unattended.md)
   §4a). A build registered before its turn would reach the machines with the next send of anything else
   there. The group's order would be broken by a send nobody made for it, and a catalogue member registered
   ahead of its controller is the version skew the order exists to prevent.
 2. **When its walk starts.** Chosen. The merge opens the walk and asks nothing. Its first tier is asked when
   the delivery's word comes, and a later tier is asked once the earlier one runs, as before. `published` is
   the trunk commit accepted with its walk opened and waiting. Its builds are registered in `delivering`.
 **Where a delivery is kept.**
 1. *A database from the store's provider.* Rejected. It would make mesh-delivery depend on a provider whose
   policy is `record` (ADR 0236 §4) and whose restart drops every consumer, adding a second dependency to the
   bus mesh-delivery cannot work without anyway. Its queries are a few dozen keys a day.
 2. **Key-value state the module declares, on the bus ([ADR 0201](0201-a-module-keeps-its-current-state-in-key-value-buckets-it-declares-and-reaches-through-the-runtime.md)).**
   Chosen. Current state per delivery and per group. History is the events, the git notes and a bounded list
   of transitions in each delivery. The seat has one holder, so the state has one writer.
 ## Decision
 **1. Three things, one owner.**
 - **A delivery** is one commit in one repository: a pull request's head, or a commit that reached the trunk
  without one. Its id is `<owner>/<repository>@<commit, twelve characters>`. It carries its **delivery plan**,
  the ADR 0238 change plan under its new name: the **build plan** (the modules it moves, their dependents in
  tiers, a move or not by source fingerprint), the **deploy plan** (per machine, what it receives in that
  order, what waits there for a person, the steps that are not an ordinary send), and the **verdict** (the
  composed machines and the replays). It also carries its transitions, its per-machine steps and, once
  merged, the commit it landed on the trunk as.
 - **A delivery group** is two or more deliveries with the same head branch name in the mesh's repositories.
  It has one level, an order among its members, and a state derived from theirs, never set on its own.
 - **mesh-delivery** is the module that owns both. It holds the mesh-scoped seat `mesh-delivery`, one holder,
  in the controller's compiled seat set, and serves the seat's verbs: `deliveries`, `show`, `groups`,
  `what-if`, `stop`, `release`, `recheck`, `stalled`, `close`, `table`.
 **2. A delivery is a state machine, one compiled table.** Each row of the table is a transition: a from-state,
 an event, a to-state and a guard. Any transition not in the table is refused and the refusal is said. A test
 walks the table. Each state carries its bound and what healer H2 may do once the bound has passed.
 | From | Event | To | Guard |
 |---|---|---|---|
 | (none) | announced | proposed | a pull request's head the forge announced |
 | (none) | appeared | held | a trunk commit whose walk waits, with no pull request known: merged before the seat was held, or pushed to the trunk |
 | (none) | adopted | delivering | a walk already running: at the switch, or on the controller's own path |
 | proposed | checked | checked | the verdict names this commit |
 | checked | accepted | ready | the gate passed or warned; the repository's own check did not fail |
 | checked | refused | rejected | the gate failed or could not run |
 | rejected | recheck | proposed | a person asked, or the head was announced again |
 | ready | recheck | proposed | a person asked, or its group changed |
 | proposed, checked, ready, rejected | new head | superseded | a newer head of the same pull request |
 | proposed, checked, ready, rejected | closed | stopped | the pull request closed unmerged |
 | ready | merged | published | merged on the trunk its modules follow, and its walk opened; or nothing for a walk to move |
 | proposed, checked, rejected | merged unchecked | held | merged without a passing check; a verdict known with it is taken first |
 | published | done | delivered | nothing for a walk to move |
 | published, ready | hold | held | merged, and its group's composed check did not pass for the heads that merged, or no walk was opened for it within ten minutes |
 | published | go | delivering | its walk started: let go by this owner in its group's order, by a person, or on the controller's own path |
 | held | go | delivering | its walk started on a word that was not this owner's: the controller's own path, or a person's `plans go` |
 | held | release | delivering | a person's decision, with why |
 | delivering | done | delivered | every machine of its deploy plan passed or was left as its policy says |
 | delivering | failed | failed | its walk failed: a first machine's gate (what it carried put back, ADR 0236 §3), a build, a machine |
 | delivering | stop | stopped | its walk was stopped through this owner |
 | published, delivering | superseded | superseded | a newer delivery to the same trunk took over its walk (ADR 0218) |
 | any state not final | stop | stopped | a person, with why, or its group stopped by a member before it |
 `delivered`, `failed`, `superseded` and `stopped` are final. A delivery never goes back to a state before
 `published` once it has left one. A row is either *observed*, taken whenever its guard holds, or an *act*,
 taken only when a person or healer H2 asks (recheck, release, stop). The observed rows are taken in the
 table's order until none holds. A delivery therefore stands where its facts put it, whatever order the facts
 arrived in. Inside `delivering`, each machine has its own row in a second table: `sent` → `judging` →
 `passed` | `failed`, `failed` → `rolled-back`. A step may pass through states between two readings of the
 walk. A move the table does not reach, such as `passed` → `failed`, is refused. Steps are read from the
 walk's own record (rule 7), never guessed.
 **3. The trunk rule ([ADR 0238](0238-a-commit-is-the-build-at-hand-one-commit-one-change-plan-checked-off-the-trunk-and-published-only-on-it.md)
 decision 1) is the guard on `published`.** A commit off the trunk can reach `ready` and no further, and the
 walk that publishes it exists only for a merge into a branch a module follows. Only a commit on the trunk is
 published, and only a published delivery is delivered. A check builds nothing today. When one does, what it
 builds goes under a scratch namespace of the artifact store that registration refuses.
 **4. A delivery group.**
 - **Membership** is the head branch name (above). A group that has started delivering is closed: a new pull
  request with the same branch name is a lone delivery, and the reason is given.
 - **Order** is declared and inferred. It is declared by a line `after: <repository>` in a member's pull
  request description. It is inferred by the controller's planner, which holds the graph, through the verb
  `delivery-order`, from four rules:
  - a member that moves a module goes before a member whose modules are built by it or stand on it
    (toolchains and the build agent before their dependents);
  - a member that moves the controller goes before a member that changes any module's manifest (version skew:
    the newer controller parses what the newer manifest says);
  - a member that moves the node-engine goes before the controller's member, because the witness reads
    nothing the controller does not yet grant and a controller sends nothing an older engine refuses (ADR 0236
    *Rollout order*);
  - otherwise, the order of the repositories' names, so the order is the same on every reading.
  A declared order that contradicts an inferred one is a cycle. The group is rejected, naming the cycle.
 - **Checked** means all members' heads are composed together as one future state of the mesh: one gate over
  every machine with every member's definitions, judged by the group's own controller when a member moves it.
  The verdict is posted on every member's head as `mesh/delivery-group`. The group is `ready` only when that
  verdict passed and every member is `ready`.
 - **Delivering** follows the order, member by member. The next member starts only when the one before is
  `delivered`.
 - **A failed member stops the group cleanly.** The members after it are `stopped`, and the reason names the
  member and why. **What was already delivered stays.** Each earlier member passed its own gate on its first
  machine and its own judgement on every machine. A later member's failure says nothing about it, and putting
  back a build that passed would be a rollback with no verdict behind it. **The failed member's own builds are
  put back at its gate, once (ADR 0236 §3)**, by the controller as today. A person releases what was stopped
  once the fix is merged, which makes a new delivery.
 - The group's state is derived: `checking` while any member is `proposed` or the composed check is
  outstanding; `rejected` when any member or the composed check is; `ready`; `delivering`; `delivered` when
  all are; `failed` or `stopped` when a member is. Nothing writes a group's state except this derivation.
 **5. Every transition is said four ways, and the owner of each says it.** mesh-delivery keeps the transition
 in its state before anything else, and does nothing else for it until it is kept. What it owes outside is
 kept with the delivery and retried until done:
 - the event `mesh-delivery.transition` (a group's change of state: `mesh-delivery.group`), with no secret and
  no address;
 - a line on the commit's note under `refs/notes/mesh-plan`, asked of the forge's holder (`gitea_note_append`).
  The line goes on the head while the delivery is off the trunk, on the commit it landed as once it is on it,
  and at its end with what was executed. The forge's holder appends it in its own repository as the forge's
  own account. A line the note already holds is not appended again;
 - the delivery's view, one comment on the pull request kept current (`gitea_delivery_view`);
 - the status `mesh/delivery` on the head, and `mesh/delivery-group` on each member's head
  (`gitea_commit_status`).
 Every status links to the pull request where the view is, `mesh/merge-gate` among them. The forge's holder
 also says when a pull request closes unmerged (`pull.closed`), and says the head and its statuses with a
 merge.
 **6. The boundary.** mesh-delivery never sends to a machine, never writes a declaration, a bus object or a
 grant, and never registers a build. It asks:
 - **the controller**, through the seat's verbs: `delivery-plan` (the planner's one answer for a diffset),
  `delivery-order`, `delivery-check` (compose a group's heads, or check one head again), `deliver` (let one
  published trunk commit's walk start), `delivery-stop` (end a walk, with why), `delivery-walks` (the walks
  and their steps);
 - **the build seat**, through the controller's `delivery-check`. A group's check is a check ask like any
  other;
 - **the forge's holder**, through its tools: the notes, the view and the statuses.
 The controller keeps composition, registration, the trunk rule, sending, the gate, the rollback and the walk
 of one commit's tiers across machines, and says each step of a walk as the event `plan-moved`.
 **7. The walk's record is the controller's, and the delivery's state is mesh-delivery's.** A plan the
 controller keeps is from now on the walk of one delivery, read by the repository and commit it walks. Its
 `building` and `rolling` are the walk's progress, and its end is reported to the delivery, which decides the
 delivery's state from it. **A release plan stops being a concept of its own.** The backlog walk of ADR 0236
 §4a is the walk of every build that waits on its machines, and each build it carries is credited to the
 delivery that published it. `plans` stays as the walk's record. `deliveries` is what a person reads.
 **8. The bootstrap rule.** mesh-delivery cannot gate or deliver itself, and the mesh must never depend on it to
 be repaired:
 - A walk that moves **the controller, the node-engine, the node tools, the bus or mesh-delivery** runs on the
  controller's built-in path: started by the merge, judged at the gate, witnessed on the machine (ADR 0236
  §5), the previous build kept and switched back to. mesh-delivery records it and does not start it.
 - Any other walk, **while the seat `mesh-delivery` has a holder on record**, is built and published by the
  merge and then waits for mesh-delivery's `deliver` before its first send. With no holder on record, the
  controller starts it itself, exactly as before this record.
 - **If mesh-delivery is down**, a walk waiting for it waits. Past its bound, the stall is said as the condition
  `stalled` with the remedy.
  > **Progressive insight — 2026-10-07.** The first build did not do what this said. It took waiting walks out
  > of the stall watchdog (S3), on the reasoning that a silent mesh-delivery is D3's `holder-silent`. That
  > covers a holder that is down. It does not cover one that is up and never says go: a bug, or a delivery
  > stuck in its own table. Such a walk would have waited for ever with no condition open, the silent failure
  > this record exists to end. The wait is now said by the controller itself, whatever mesh-delivery says of
  > itself. A new row of the signals table, **S16**, raises `plan.<walk>.waiting` once a walk has waited 30
  > minutes, urgent after 4 hours, naming `plans go` as the way on. The condition's name is `waiting`, not
  > `stalled`: a waiting walk is no tier late, and H2's `stalled` repairs would not fit it. The decision
  > stands; only its first build was wrong. A person delivers by hand: `push <machine>`, which carries what waits there
  (ADR 0236 §4a), or `plans go <plan> --why`, which gives the walk a person's word in place of
  mesh-delivery's. Nothing in the controller waits for mesh-delivery to repair the controller or
  mesh-delivery.
 - A pull request's own check is triggered by the controller, not by mesh-delivery (above). The fix for a
  broken mesh-delivery is checked, merged and delivered without it.
 **9. Durable across restarts.** The state is mesh-delivery's key-value state. A restarted holder reads it back
 before it takes an event. It then reads the controller's `delivery-walks`, and again every half minute, so a
 walk's move it missed while it was down, or one a command made that says nothing, is found by comparison and
 never lost. A pull request merged while it was down is made a delivery from the forge's word: its head and
 the statuses the forge holds on it. A state held past its
 bound is listed by `stalled`. The controller's self-check reads that list and raises
 `delivery.<delivery>.stalled`. **Healer H2 works from the table**: it closes a stalled delivery only by a
 transition the table allows for that state (`superseded` when a newer delivery took over, `delivered` when
 the walk's record says done), through mesh-delivery's `close`.
 **10. The switch, without a gap.** Before mesh-delivery is assigned, the controller walks every merge as it
 does today. Once the seat has a holder on record, a walk that starts after that waits for its word. Walks
 already open finish where they are: the holder adopts each open plan as a delivery in `delivering`, and an open
 release plan's carried builds are credited to their deliveries, or listed as carried with no delivery. Only a
 walk's start reads whether a holder is on record, so no walk is ever both started by the controller and
 waiting for mesh-delivery. Unassigning mesh-delivery returns the mesh to the controller's own path.
 ## Consequences
 - **"Did my change go out?" is one verb.** `deliveries` and `show <delivery>` answer it from the pull request
  to the last machine. The pull request's statuses link to the same answer, and the commit's note keeps it
  after the state is pruned.
 - **A cross-repository change merges in an order the mesh enforces.** A member that would cause version skew
  waits for the member it depends on. A group that cannot be ordered is rejected before anything merges.
 - **A merge no longer sends anything until mesh-delivery says so** while it is held, except the core and
  mesh-delivery itself. A down mesh-delivery means walks wait, said as a condition. A person can still deliver
  by hand.
 - **The controller gains six verbs, one event (`plan-moved`, in the installer's first user list too) and a
  `go` for `plans`, and loses no primitive.** Its release planner's lifecycle,
  supersession and hold decisions remain its code until mesh-delivery is held. After that they run only on the
  built-in path. Removing them is a later decision, once mesh-delivery has delivered for a while.
 - **The forge's holder gains the notes, the view and two statuses.** A note is written inside the forge's own
  container, in the bare repository, as the forge's user. The forge's API reads notes and writes none, and a
  push from anywhere else would need a credential to the forge that nothing else should hold.
 - **A module named as its seat says its events as itself.** A consumed `<seat>.<event>` names the seat's event
  only when the seat emits it. Otherwise it names the event of the module of that name (`mesh-delivery.transition`).
  The controller derives subscriptions by that rule.
 - **What is not built by this record**: porting the walk itself into mesh-delivery (option 1 of *where the walk
  runs*); a web view
  of deliveries beyond the pull request's comment; requiring `mesh/delivery-group` on the trunks, which is the
  operator's setting through the forge module's protection tool; the scratch namespace, until a check builds
  something.
 > **Progressive insight — 2026-10-07.** *What is not built* named the self-check reading `stalled` and H2
 > calling `close` (to-be 47 Phase B). Both are now built: probe D14 raises `delivery.<delivery>.stalled`, and
 > H2 asks mesh-delivery's `close` for a state the table gives it, never for one that is the operator's.
 > Decision 9 is unchanged.
 ## How it is checked
 | Rule | Checked by |
 |---|---|
 | a waiting walk is said whatever mesh-delivery says | the signals table's generated test for S16 (inside 30 minutes nothing, past it `plan.<walk>.waiting`, cleared when the walk starts) and the test that it is urgent past four hours and names `plans go` |
 | a stalled delivery is the controller's condition, healed by the table | the controller's D14 test (nothing with no holder on record, one condition per stalled delivery, the operator's where the table gives H2 nothing, nothing when the holder is down, which D3 says); its H2 test (`close` asked only for the delivery H2 may move, a refusal is no repair); the test asking a stand-in owner over a real bus, and that the controller's grant names `stalled` and `close` and nothing else of the seat |
 | a transition not in the table is refused; the table is walked | mesh-delivery's test that walks every row and every pair not in the table; the machine-step table walked the same way |
 | a pull request's head goes proposed → checked → ready, or rejected | mesh-delivery's test from a `pull.updated` and a `checked` |
 | a merge publishes, delivers and is delivered; a failed gate fails it; a newer commit supersedes it | mesh-delivery's tests driven by the controller's `plan-moved` snapshots: done, gate failed with rollback, superseded |
 | the trunk rule | mesh-delivery's test that an off-trunk commit never reaches published; the controller's publish-rule test (ADR 0238) |
 | a group's membership, order, composed check and clean stop | mesh-delivery's group tests: by branch name, declared and inferred order, a cycle rejected, ready only when all are, a failed member stopping those after it and leaving those before it delivered |
 | a restart resumes | mesh-delivery's test that a holder restarted over the same state resumes each delivery and reconciles a walk it missed |
 | the bootstrap rule | the controller's tests: a walk moving a core module or mesh-delivery never waits; another waits only while the seat has a holder on record and asks no build while it waits, so a push carries nothing of it; `plans go` starts it with mesh-delivery down, with why, recorded as a hand act; unassigned, the mesh is back on the controller's own path |
 | the inferred order | the controller's `delivery-order` test: built by, version skew, engine before controller, declared, by name the same on every reading, and a contradiction named as a cycle |
 | a group is checked as one future state | the controller's gate test: a catalogue change needing a provision only another repository's change adds fails alone and passes composed with it; the builder's check test, on a container runtime, clones a group's other head and hands it to the gate, and runs no member's own script |
 | a walk moved by a verb is said | the controller's test that `delivery go`, run as a command of its own, says `plan-moved` on the bus |
 | every transition is persisted, said, noted and reflected | mesh-delivery's test that each transition is put before it is emitted; the forge module's note test (append-only, idempotent) and view test (statuses carry its link) |
 | the seat is in the set and its holder is one | the controller's seat test; the catalogue's manifest test of mesh-delivery |
 | live | the next merge with mesh-delivery held waits for `deliver`, and `deliveries` shows it from head to delivered; `git log --notes=mesh-plan` shows the note on its merge commit |
 ## References
 - [ADR 0238](0238-a-commit-is-the-build-at-hand-one-commit-one-change-plan-checked-off-the-trunk-and-published-only-on-it.md)
  decision 6, which this record gives an owner and builds;
  [ADR 0236](0236-a-build-is-judged-on-its-first-machine-and-put-back-by-something-other-than-itself-and-so-it-rolls-out-unattended.md)
  §3, §4a and §5, whose release plan becomes the delivering stage and whose gate rules decide what stays;
  [ADR 0218](0218-a-plan-sends-grants-before-code-rolls-out-one-machine-first-and-a-newer-merge-takes-over-an-older-plan.md),
  [ADR 0201](0201-a-module-keeps-its-current-state-in-key-value-buckets-it-declares-and-reaches-through-the-runtime.md),
  [ADR 0231](0231-a-healer-acts-on-what-observation-raised-and-only-observation-says-it-worked.md).
 - [To-be 47](../03-DESIGN/01-to-be/47-delivery-from-commit-to-delivered.md), the design;
  [to-be 10](../03-DESIGN/01-to-be/10-delivery.md), the delivery it carries out;
  [playbook 07](../00-META/process/07-feature-branches.md), whose branch name is a group's membership.
 - mesh-controller, mesh-catalog and mesh-host: the branches `feat/mesh-delivery`.
@@ -1,263 +0,0 @@
 ---
 topic: what runs on it
 status: accepted
 date: 2026-10-07
 deciders: jochen
 reconstructed: false
 extends: 02-DECISIONS/0236-a-build-is-judged-on-its-first-machine-and-put-back-by-something-other-than-itself-and-so-it-rolls-out-unattended.md
 ---
 # 240. A module says how it is healthy, and the node-engine judges it
 ## Context
 The release gate ([ADR 0236](0236-a-build-is-judged-on-its-first-machine-and-put-back-by-something-other-than-itself-and-so-it-rolls-out-unattended.md)
 §2) judges a catalogue module on its first machine by what the mesh sees from outside: the build reported
 applied, no witness put it back, no condition raised since the send about the machine or the module there,
 and its tools served. None of that looks at what the module *runs*. To-be 45 names the gap in its Phase 4:
 *container state in the node-engine's report, without which a container that crash-loops after its compose
 applied is seen only through what it breaks.*
 Measured on the live mesh for [research 032](../01-RESEARCH/032-a-module-says-how-it-is-healthy/00-overview.md)
 ([evidence](../01-RESEARCH/032-a-module-says-how-it-is-healthy/01-evidence.md)), 2026-10-07:
 - **125 catalogue modules; 68 run something long-lived** — 49 a container that stays up, 19 a service
  unit stated `running` and no such container. 50 run only their bundle in the node tools, 7 only files,
  directories and packages.
 - **No manifest can declare a health check, and nothing reads one.** The node-engine's report carries no
  container or unit state; no probe of the self-check reads one.
 - **19 of 73 long-running catalogue containers have an image that ships a check** (7 of 45 container
  modules). The mesh never reads it. **Two of those were wrong in the mesh's hands**: the studio and the
  flow editor read *unhealthy* while working, because their checks ask an address the program does not
  bind in the mesh's configuration. Read without proof, they would have rolled back two good builds.
 - **Every restart count is 0**, because a recreate loses it; the runtime's event history on the home
  server is about a minute long, pushed out by its own check executions.
 - **Of seven recent incidents**, liveness alone would have caught the agent server's crash loop (about a
  hundred restarts, found by a person reading its log for something else); an HTTP readiness check the
  web application that accepted TCP and answered nothing for eleven hours
  ([issue 145](../04-ISSUES/145-a-machine-reads-healthy-while-its-modules-cannot-reach-each-other/00-report.md));
  only the module's own check the identity provider's refused administrator
  ([issue 179](../04-ISSUES/179-an-adopted-identity-providers-admin-never-took-the-minted-secret/00-report.md)).
  A provisioner runtime that restarted until the overlay was up and then worked
  ([issue 058](../04-ISSUES/058-a-provisioner-runtime-crash-loops-until-the-overlay-is-up/00-report.md))
  is the warning: a restart count without a start period reads churn that stops as a crash loop.
 - **One sample is not a finding.** A single unanswered question raised an urgent alert nobody could read
  ([issue 277](../04-ISSUES/277-one-unanswered-question-was-an-urgent-alert-nobody-could-read/00-report.md));
  the self-check now raises such a finding on the second look (to-be 45 §4).
 The mesh now rolls a module out on its own and puts the previous build back when the first machine is not
 healthy. That promise is only as good as "healthy" is, and for a module it is judged today from the outside.
 **Checked against GENESIS.** *Failure must be loud* — a crash loop behind every passing check is work that
 reported success and did nothing. *Anything requiring a human to notice it will be noticed late* — eleven
 hours, and a hundred restarts, each found by a person. *Evidence over assertion* — "applied" is an
 assertion about a declaration; "it answers" is a measurement. *The mesh notices when something is wrong
 before you do* ([effect](../00-META/effect.md)). *Long-lived user services rather than an orchestrator*
 ([context](../00-META/context.md)) is why this record judges and reports, and restarts nothing on health:
 an orchestrator's liveness restart is the part it does not take. *The mesh is a guest on a personal node*
 bounds the cost: the checks' floors below. Nothing here conflicts with GENESIS.
 ## Considered Options
 **Who runs the checks.**
 1. *The container runtime's own check, read by the node-engine.* Rejected as the whole answer: containers
   only — nothing for the 19 service-only modules or anything only a module's tool knows; every look is an
   execution inside the container, which on the home server already pushes every lifecycle event out of
   the runtime's history; an image check the module never stated is a check nobody owns, and two of 19 were
   wrong. Kept as one *kind*, adopted by name and proved.
 2. *The module's own tool answers "healthy", and that is the judgement.* Rejected as the judge: a bundle is
   hosted by the node tools, so a tool that answers proves the bundle up, not the server; and a component
   that judges itself is what [ADR 0227](0227-the-core-holds-nine-rules-each-checked-and-is-built-to-them-in-six-phases.md)
   rule 8 refuses for the core. Kept as one kind, for function no endpoint shows, and only beside a check
   the module does not run itself.
 3. *The node-engine runs everything itself, including commands, on its own schedule.* Rejected in part: a
   command that only makes sense inside the container is better timed by the runtime's own retries and
   start period than by an execution per look from outside.
 4. **The node-engine owns every check and every verdict, and runs each kind where it is cheapest.**
   Chosen: HTTP, TCP and unit checks it makes itself; a command it hands to the runtime as that
   container's check and reads; a tool it asks through the node tools. One runner and one reader per
   machine, for every hosting form, and it keeps what the runtime forgets.
 **Where the result goes.**
 1. *Only a field of the report.* Rejected alone: a report follows an apply, so a container that goes bad at
   03:00 waits for the next one.
 2. *Only an event on each change.* Rejected alone: events are lost or replayed; an event is a sample, not
   a state.
 3. *A verb the controller calls per module when it judges.* Rejected: a pull per module per judging, and a
   machine slow to answer reads as unhealthy.
 4. **State in the report, its change on the bus, and a condition the controller raises on the second
   look.** Chosen. It is how the core already says its own state; the gate, the self-check, the healers
   ([ADR 0231](0231-a-healer-acts-on-what-observation-raised-and-only-observation-says-it-worked.md)) and
   the operator's conversation ([ADR 0234](0234-the-mesh-holds-a-conversation-with-its-operator.md)) all
   already act on conditions.
 **What is judged.**
 1. *Liveness only.* Rejected: no declarations needed, but it misses issue 145 (the port was open and the
   program running) and issue 179.
 2. *Readiness only, where declared.* Rejected: nothing is judged until every module has declared, and
   liveness alone would have caught the worst incident of the window.
 3. **Liveness for every long-running resource at once, readiness where declared, the declaration required
   over a migration.** Chosen: the gate means something from the first build.
 **What is done with an unhealthy module.**
 1. *Restart it, as an orchestrator's liveness probe does.* Rejected for this record: the evidence holds no
   case where a restart would have fixed anything — the crash loop was restarting already — and a restart
   hides the failure the gate is meant to see. Whether a healer restarts what stays unhealthy is left to a
   record of its own under ADR 0231.
 2. **Nothing restarts on health; the condition reaches a person or a healer.** Chosen.
 **A provider down.** With 12 consumers of the database provision and 36 of a route:
 1. *Ignore it.* Rejected: twelve conditions for one fault, and twelve gates failed for something none of
   them did.
 2. *Judge providers first, consumers only once their providers are healthy.* Rejected: a consumer broken on
   its own is not said while its provider is down, which is when it is most needed.
 3. **A consumer's check names the provision it exercises; while that provision's provider is unhealthy on
   the record, the consumer's finding is held under the provider's condition and its gate waits.** Chosen.
   It is how [issue 281](../04-ISSUES/281-a-tier-sent-one-module-at-a-time-blamed-a-module-for-its-machine/00-report.md)
   already treats a machine-level fault: what is the machine's is never pinned on a module.
 **Where the declaration sits.**
 1. *One per module.* Rejected: a module of eleven containers (the mail module) could not say which is wrong.
 2. **On each long-running resource**, beside the resource's other fields. Chosen.
 **The migration.**
 1. *Required at once.* Rejected: 68 modules to change before the next merge, and nothing judged until all
   are.
 2. *Optional for ever.* Rejected: 38 of 45 container modules would stay at liveness, and a field that is
   optional for ever is a field half the catalogue never gets.
 3. **Liveness at once; the declaration required by a date, counted down.** Chosen.
 ## Decision
 **1. Liveness is judged for every long-running resource, with no declaration.** A container that stays up,
 a process that stays up and a service stated `running` are *alive* when running and not restarted more than
 once within the settle window after their grace period. The node-engine observes this itself on each tick
 and keeps the restarts it counted across recreates and across its own restarts; it never relies on the
 runtime's restart count or event history. A resource held still by an open maintenance step
 ([ADR 0189](0189-the-store-keeps-what-the-records-name.md)) is neither alive nor dead: it is said as held,
 and judged again when the step ends.
 **2. A module declares how each long-running resource is ready**, in a field named `health` on that
 resource: one kind — the image's own check adopted by name, an HTTP request to a declared endpoint and the
 status expected, a TCP connect to a declared endpoint, a command in the container, the unit's own
 readiness, or one of the module's tools — with an interval (default 30 s, **not under 10 s**), a timeout
 under the interval, a number of failing looks in a row before it is unhealthy (default 3, **not under 2**),
 and a grace period after a start (default 60 s), in which failure does not count. The grace and the failing
 looks together are at most five minutes, so a resource broken from its start is said within the gate's
 bound. An endpoint is named by its `listens` name, never by a port or an address, so a check follows the
 machine's ports as the endpoint does. A check of function that no endpoint shows is a module's own tool, and
 only in addition to a check the module does not run itself.
 **3. The node-engine runs every check and owns every verdict.** HTTP, TCP and unit checks it makes itself;
 a command in the container it hands to the runtime as that container's check and reads the state; an
 adopted image check it reads the same way; a tool it asks through the node tools. Nothing else on the machine
 judges a module, and nothing else sets a container's check.
 **4. The state goes in the report, its change on the bus, and a condition is the controller's.** Each
 report carries, per module and long-running resource, a state — healthy, unhealthy, starting, held,
 unknown — since when, the failing streak and the restarts counted; each change is emitted as an event, and a
 state that is not healthy is said again while it lasts. The controller keeps the last state per machine,
 raises `module.<module>.<machine>.unhealthy` when two consecutive statements say so, and clears it on the
 first that does not. **The gate needs no new rule:** ADR 0236 §2's *a module's own health holds* now reads
 the module's stated health — a judging is healthy only when every long-running resource of the module on that
 machine is healthy, so a resource still starting is not yet a pass — and its *no condition raised since the
 send* holds the module on this condition. Every start begins in `starting`, so a condition from before the
 send clears at the new build's start and anything after it is the new build's. At the gate's bound the
 build is put back, as ADR 0236 §3 says.
 **5. A provider down is said once, at the provider.** A check names the provision it exercises. While
 that provision's provider for this consumer is unhealthy on the record, the consumer's finding is held under
 the provider's condition — listed there as waiting on it, raised as nothing of its own — and the consumer's
 gate waits rather than fails. What a consumer finds while its provider is healthy is its own.
 **6. Nothing is restarted for being unhealthy.** The runtime restarts what exits, as now. A condition
 reaches a person through the operator's conversation, or a healer; a healer that restarts on health is its
 own decision.
 **7. A declaration is proved before it is trusted.** `module check` refuses a `health` field that names an
 endpoint the module does not declare, an interval, timeout or count outside its bounds, or a tool the module
 does not serve. A bed from mesh-lab, run by the catalogue's check on the build seat, starts every resource
 whose declaration or image changed and requires its check to say healthy within its grace; an image check
 adopted by name is proved the same way, because two of nineteen were wrong. This proves the check's
 wiring — that it can see the program working — not the change, which the live mesh and the first machine's
 gate still judge ([ADR 0149](0149-the-live-mesh-is-the-test-bed.md) stands).
 **8. Every catalogue module that runs something long-lived declares one.** A catalogue-wide count of the
 long-running resources without `health` may only go down. `module check` warns from this decision, and
 refuses a long-running resource without `health` once the count reaches zero, or six weeks after liveness is
 first judged live, whichever is first. A module running nothing long-lived — its bundle only, or files and
 packages — declares none: the node tools serving its tools is its liveness, as the gate judges today.
 ## Consequences
 - **Liveness alone, from the first build, would have caught the crash loop inside the gate's ten minutes.**
  Readiness would have caught the silent web application in about a minute instead of eleven hours. The
  identity provider's refused administrator needs the module's own tool, which it already has (ADR 0224 §5).
 - **The node-engine grows a small scheduler, a field of its report and an event; the controller a condition
  kind and its two-look rule; the gate a reading of state it already had a place for.** A machine of 45
  containers spends tens of milliseconds a look reading state, and about 3 s a minute on in-container
  commands at the default interval.
 - **A module whose first machine was unhealthy before the send no longer passes the gate for being
  unchanged in its unhealthiness** — the start resets it to `starting`, and the new build is judged on its
  own.
 - **What a check names becomes load-bearing.** A check naming the wrong provision hides a consumer's own
  fault under its provider; the bed and the first machine's gate are what catch that.
 - **Harder:** a slow starter — a module that needs more than five minutes to be ready — cannot say so
  within these bounds and fails its gate. That is accepted until one exists; it would be a change to the
  bound, recorded.
 - **A provider's health and its consumers' failures meet in two places**: this record's condition (the
  provider's resource is unhealthy) and ADR 0224's standing (the provider keeps failing a consumer). They
  are different facts, both kept; the hold of rule 5 reads only this record's.
 - **Data is not health.** Whether a module's data is there, measured and backed up stays
  [ADR 0233](0233-a-module-declares-the-data-it-holds-and-the-mesh-protects-and-watches-it-from-that.md)'s,
  watched by the self-check's D13.
 ## What this does not decide
 - Whether a healer restarts what stays unhealthy (rule 6 leaves it to its own record, under ADR 0231).
 - Health for scheduled work — whether the last scheduled run succeeded belongs to the record of the
  scheduled step.
 - Health of what a module's events do ([issue 276](../04-ISSUES/276-a-handler-that-did-its-work-was-offered-it-five-times/00-report.md))
  — the event contract's, and the bus watchdog's.
 - The core's own definitions (ADR 0236 §1, to-be 45 §8), which stand; a core component may later declare its
  own through the same field.
 ## How it is checked
 | Rule | Checked by |
 |---|---|
 | 1 Liveness without declaration | node-engine tests over a fake runtime and service manager: a container recreated keeps its counted restarts, and so does the engine restarted; a restart inside grace is not counted; two restarts within the settle window after grace make it unhealthy; a resource under a maintenance step is held. A mesh-lab replay of the crash loop (a container whose program exits at start) fails its gate within the bound |
 | 2 The field and its bounds | `module check` refuses each out-of-range part and each endpoint named by port or address, a test per refusal; a catalogue-wide test parses every `health` field |
 | 3 The engine owns the verdict | a node-engine test that a declared command becomes the container's check and nothing else sets one; a test that an HTTP check dials the endpoint's current port after a port change |
 | 4 Report, event, condition, gate | controller tests: one unhealthy statement raises nothing and is listed unconfirmed; two raise; a healthy one clears; the gate fails a judging while a resource is starting or unhealthy and holds a module on this condition (the existing gate test, extended); a condition from before the send clears at the new build's start. A replay of issue 145 — a database made unreachable — raises the consumer's condition within two looks |
 | 5 Said once at the provider | a controller test with one unhealthy database provider and three consumers failing: one condition, at the provider, the consumers listed as waiting; their gates wait, not fail; a consumer failing while its provider is healthy is raised on its own |
 | 6 No restart on health | a node-engine test that an unhealthy container is not restarted, recreated or stopped |
 | 7 Proved before trusted | the bed's run of every changed declaration in the catalogue's check; the replay of the studio's false *unhealthy* (a check that asks an address the program does not bind) fails the bed, not a machine |
 | 8 Every long-running module declares | the catalogue-wide count of long-running resources without `health`, compared with the number kept in the catalogue: a merge may lower it and never raise it; after the date, `module check` refuses |
 | live | every machine's report carries a state for every long-running resource; `conditions` raises `module.<module>.<machine>.unhealthy` for a module stopped on purpose and clears it when it runs |
 ## References
 - [Research 032](../01-RESEARCH/032-a-module-says-how-it-is-healthy/00-overview.md) — the evidence, the
  options and the recommendation this record takes.
 - [To-be 48](../03-DESIGN/01-to-be/48-a-module-says-how-it-is-healthy.md), the design.
 - [ADR 0236](0236-a-build-is-judged-on-its-first-machine-and-put-back-by-something-other-than-itself-and-so-it-rolls-out-unattended.md)
  §2, whose module health this gives a content;
  [ADR 0227](0227-the-core-holds-nine-rules-each-checked-and-is-built-to-them-in-six-phases.md) rules 5, 6
  and 8 and [to-be 45](../03-DESIGN/01-to-be/45-a-core-that-cannot-fail-silently.md) §2, §4 and §8 — the
  condition, the second look, the witness that is never the component;
  [ADR 0224](0224-a-provider-that-keeps-failing-a-consumer-is-a-problem-the-controller-reports.md),
  [ADR 0231](0231-a-healer-acts-on-what-observation-raised-and-only-observation-says-it-worked.md),
  [ADR 0233](0233-a-module-declares-the-data-it-holds-and-the-mesh-protects-and-watches-it-from-that.md),
  [ADR 0234](0234-the-mesh-holds-a-conversation-with-its-operator.md),
  [ADR 0189](0189-the-store-keeps-what-the-records-name.md),
  [ADR 0149](0149-the-live-mesh-is-the-test-bed.md),
  [ADR 0237](0237-a-change-is-judged-against-the-mesh-that-runs-before-it-merges-on-the-build-seat.md).
 - Issues 058, 145, 179, 181, 276, 277, 281.
@@ -1,217 +0,0 @@
 ---
 topic: what runs on it
 status: accepted
 date: 2026-10-07
 deciders: jochen
 reconstructed: false
 extends: 02-DECISIONS/0240-a-module-says-how-it-is-healthy-and-the-node-engine-judges-it.md
 ---
 # 241. A machine says how its network is, and an outside writer of a mesh file is a finding
 ## Context
 [ADR 0240](0240-a-module-says-how-it-is-healthy-and-the-node-engine-judges-it.md) has the node-engine
 judge everything a module runs. It judges nothing *under* the modules: the machine's own networking, which
 every module on it uses and none of them owns.
 **On the laptop, a corporate VPN client rewrites `/etc/resolv.conf` when it connects.** It moves the file
 the uplink's holder wrote ([ADR 0117](0117-a-machines-uplink-is-a-seat.md),
 [ADR 0223](0223-the-mesh-has-two-resolvers-and-a-machine-lists-only-them.md)) aside and writes its own, naming
 its own resolvers. Mesh names then fail on the machine and in its containers, and agents saw "no such host"
 for a public service they call. The node-engine writes the mesh's file back at its next reconcile, which ends
 the VPN's names for the rest of the session; measured for
 [research 033](../01-RESEARCH/033-split-dns-with-a-vpn-client/00-overview.md), in nine of nine VPN sessions
 since the node-engine's journal begins, one second to three and a half minutes after each connect. **Nothing
 said any of it.** Every module's check was green, because no check asked the machine.
 Two more facts of the same kind: one mesh resolver answered slowly under load
 ([issue 277](../04-ISSUES/277-one-unanswered-question-was-an-urgent-alert-nobody-could-read/00-report.md)),
 and the self-check's resolver probe asks the resolvers only from the control node, so a machine that cannot
 reach them is not seen. An Alpine container failed a mesh name because a resolver answered "no such name"
 for its IPv6 address
 ([issue 262](../04-ISSUES/262-an-alpine-container-could-not-find-a-machine-by-its-mesh-name/00-report.md)).
 The operator's direction, 2026-10-07: *the health check should, from now on, also catch DNS issues or other
 networking issues.*
 **Checked against GENESIS.** *Failure must be loud*: a machine whose names stop resolving while every
 module reads healthy is quiet failure. *The mesh notices when something is wrong before you do*: the
 operator found this by reconnecting the VPN three times in sixteen minutes. *The mesh is a guest on a
 personal node*: on the laptop the VPN client is the employer's, so the mesh says what it finds and repairs
 nothing it does not own. Nothing here conflicts with GENESIS.
 ## Considered Options
 **Who looks.**
 1. *The controller's self-check probes each machine's resolvers from the control node.* Rejected: this is
   what exists, and it is blind to the machine that cannot reach them. A machine's names are a fact on that
   machine.
 2. **The node-engine on each machine looks at its own networking, beside its liveness looks.** Chosen. It
   already reads the machine for ADR 0240, and it applied the file it compares.
 **What is looked at.** Rejected: a full network test (throughput, latency to every machine), which costs
 more than it tells. Chosen: five cheap parts, each a fact some incident needed (Decision §1).
 **What an outside writer is.**
 1. *A cause of the names failing, said only in the names' finding.* Rejected: it hides the actionable fact.
   The operator can do something about another program owning a mesh file, and cannot do anything about
   names failing.
 2. **Its own finding, naming the writer where it can.** Chosen. The names that fail through the rewritten
   file are listed as what it costs, not raised a second time.
 **What the gate does with a network condition.** Under
 [issue 281](../04-ISSUES/281-a-tier-sent-one-module-at-a-time-blamed-a-module-for-its-machine/00-report.md),
 a machine-level condition raised since the send holds the machine as a whole, and it fails at the bound.
 1. *Leave it so.* Rejected for the outside writer: a VPN connecting during a send would put back a good build.
 2. *Ignore network conditions in the gate.* Rejected: a send that breaks the machine's network is exactly
   what the gate exists to catch.
 3. **What is shown to be another's waits; what is the machine's own stays the machine's.** Chosen.
 ## Decision
 **1. The node-engine judges its machine's networking every 30 s, in five parts:**
 - **resolv-conf**: `/etc/resolv.conf` is, byte for byte apart from surrounding whitespace, the file the
  uplink's holder declared and the engine last applied. A file nothing declares whole is not judged.
 - **names**: every resolver the file lists (up to three, as the C library reads them) answers the mesh's
  name with an address, its IPv6 question with "none" and never "no such name" (issue 262), and a public
  name with an address. Each answer must come within the time the file tells the C library to wait. The
  mesh's name is the bus's own, the name the machine needs most. The public name is one reserved for
  documentation, which belongs to no installation.
 - **tunnel**: the mesh's interface has handshaken with the hub within five minutes. On the hub, any peer has.
 - **bus**: the link to the bus is open.
 - **route**: the machine has a default route.
 The resolvers are asked concurrently, so a look costs one wait however many are silent. A part that cannot be
 judged on the machine, such as a machine with no tunnel tool, is left out, not failed.
 **2. The two-look rule is the engine's.** A part is unhealthy on its second failing look in a row, and
 healthy on its first passing one. One unanswered datagram is not a finding (issue 277). Each part says
 its reason in words that hold no address, path or domain. The detail, with addresses, is evidence and stays
 inside the mesh ([ADR 0234](0234-the-mesh-holds-a-conversation-with-its-operator.md) §6).
 **3. An outside writer is named where the machine shows it, and said as a guess when it is one.** In order:
 1. the file's own header, since every writer puts its name there;
 2. a backup beside the file named for its writer, or one changed when the file was;
 3. a program known to write the file, running now, said with a question mark.
 A link put in place of the file names what it points at. Nothing found is said as nothing found.
 **4. The statement carries it.** The engine's health statement (ADR 0240 §4) gains the machine's network:
 its worst state, since when, and each part with its reason, evidence, writer, the module whose file it is,
 and what a failure points at (the hub, or each resolver's address). It travels in every report and with the
 health event, on the same subject, under the same grant. An engine older than this says no network, and
 the controller reads that as not known: never healthy, never raised.
 **5. The controller raises three kinds, from every machine's newest statement together:**
 - **`machine.<m>.<owner>.rewritten`**: the file the module `<owner>` writes on `<m>` was rewritten by
  another program, naming it, and what it costs (names that do not resolve) "until the node-engine writes it
  back at its next reconcile, or that program gives it back". The names failing through the rewritten file
  are this finding's, not raised again.
 - **`machine.<m>.network`**: what is the machine's own, meaning its route, its tunnel, its bus, or a
  resolver that is no mesh machine's.
 - **`machine.<x>.unreachable`**: what points at another machine is said once, there, as ADR 0240 rule 5
  says a provider. A failure toward the hub or toward a mesh resolver is held under that machine when it is
  down on the record: its silence is open, its own network is unhealthy, or a second machine finds the same.
  The waiting machines are listed there and raise nothing of their own. When that machine's own network
  condition is open, they are listed on it. One machine alone failing toward a healthy one is its own.
 Each is a warning. It is urgent on the control node or the hub, when the bus cannot be reached, or when other
 machines wait on it. It clears on the first statement that no longer says it. `node show` lists each part.
 **6. The gate waits on what is shown to be another's.** A send whose machine raises
 `…rewritten` for a file the send did not move, or `…unreachable` for another machine, waits: no pass, and
 no failure at the bound. A `…rewritten` naming a module the send moved is that module's, under issue 281's
 rule. A machine's own `…network` holds the machine as a whole, as before.
 **7. The engine reads and never acts** (ADR 0240 rule 6). It does not write the file back sooner, restart a
 link, or ask for a reconcile. The reconcile holds the file as it always has. How the laptop should share
 its names with a VPN client is [research 033](../01-RESEARCH/033-split-dns-with-a-vpn-client/00-overview.md)'s
 question, and is not decided here.
 > **The mechanism changed — 2026-10-07, by ADR 0247.** Research 033's question is decided in
 > [ADR 0247](0247-a-machine-with-a-vpn-client-routes-names-by-domain-through-a-resolver-of-its-own.md): a machine with such a VPN client runs a resolver of its
 > own, whose module writes the resolver file there. The file this rule 1 judges on that machine is
 > therefore that module's, and a rewrite is raised as `machine.<m>.systemd-resolved.rewritten`. Nothing in
 > the judge changed. The module's guard puts its file back sooner (rule 7 binds the engine, not the
 > module): at once for a write the VPN client's module took, after 90 s for one nobody took, which is long
 > enough to be raised first.
 **8. The uplink seat answers what the machine resolves through.** `node-uplink` serves two read-only verbs,
 the same from every holder whatever manages the network. `resolvers` gives the resolver file as it is: its
 resolvers, search domains and options, whether it is the mesh's, and who wrote it as far as the machine
 shows. `links` gives every link with its addresses, whether the default route leaves through it, and the
 resolvers and search domains the manager knows for it. A finding of rule 5 is followed up with these verbs.
 Nobody opens a terminal on the machine. The verbs are *staged*: promised and routed, but not yet a condition
 of holding the seat, and never stored in the seat's row. A controller older than them reads the row and
 would refuse every holder of its time. A later change requires them once both holders serve them.
 > **Progressive insight — 2026-10-07.** The verbs did not ship *staged*. This rule said they were
 > "promised and routed, but not yet a condition of holding the seat, and never stored in the seat's row",
 > and the check for rule 8 in the table below said "a staged verb is never seeded into the row and comes
 > back from the binary". The controller that merged (mesh-controller #116) has no staged seat. It marks
 > both verbs optional (`Verb.Optional`). An optional verb is promised, so a claim serving it is accepted,
 > but it is not required, so a holder serving neither still holds the seat. It is seeded into the seat's
 > row like any verb, and it stays optional when read back, because the mark is taken from the seat as
 > compiled. Mesh-controller's `TestTheUplinkVerbsReadBackFromTheRowStayOptional` holds that. The
 > decision is unchanged: promised now, required once both holders serve them. The general rule for a verb
 > added to a held seat is [ADR 0246](0246-a-seats-new-verb-is-promised-before-it-is-required.md), from
 > [issue 298](../04-ISSUES/298-a-new-seat-verb-deadlocks-across-two-repositories/00-report.md).
 ## Consequences
 - **The VPN rewriting the laptop's file is said within about a minute,** naming FortiClient from its
  header. It clears when the reconcile writes the file back. While research 033 is open it is raised on every
  connect. That is the point: the fight between the two writers is now visible, not silent.
 - **A resolver failing from one machine is that machine's; from two, the resolver's.** The control node's
  probe stays, and the machines' own looks now cover the paths it cannot see.
 - **About six datagrams per resolver and three small reads, every 30 s, on every machine.** A silent
  resolver costs one wait per look (the file's timeout, one second on the mesh's own file).
 - **Harder:** a writer the engine cannot name is said as "another program". The mesh cannot see who wrote a
  file after the fact, only what the machine shows.
 - **Harder:** a machine whose file nothing declares whole (an adopted machine, one whose uplink holder does
  not write it) has its names judged but not its file.
 - **The gate's waiting has no bound,** as it already has none for a provider down. A rewrite that never
  ends keeps the laptop's sends waiting, and the condition says why.
 ## What this does not decide
 - How the laptop resolves both the mesh's names and the VPN's (research 033).
 - Whether a healer writes the file back sooner, under [ADR 0231](0231-a-healer-acts-on-what-observation-raised-and-only-observation-says-it-worked.md).
 - A judging of other mesh-owned files for outside writers. This record judges the one that broke. Another
  is its own decision, made the same way when one breaks.
 ## How it is checked
 | Rule | Checked by |
 |---|---|
 | 1 The five parts | mesh-host `internal/network` tests: a healthy machine is healthy on its first look; the file rewritten is a finding; a resolver answering NXDOMAIN for a mesh name's IPv6 address is a finding naming that resolver; a stale handshake with the hub, the bus unlinked and no default route are each said; on the hub, one fresh peer is a healthy tunnel; a file nothing declares and a machine without the tunnel tool are not judged; a real UDP resolver raised by the test is read for an address, for none and for no such name |
 | 2 Two looks | the same tests: one failing look is not a finding, a pass between two failures resets it, and recovery is healthy on the first passing look; the reason never holds an address the evidence holds |
 | 3 The writer named | tests naming FortiClient from its header, from its backup beside the file (kept with the old file's time, as its rename leaves it), a running VPN client as a guess, and systemd-resolved from a link put in place of the file |
 | 4 The statement | mesh-host `cmd/mesh-host` tests: the file judged is the one a module declares whole (not a seed); the mesh name asked is the bus's; the statement carries the network and an engine with no network judge says none. The controller keeps it in `node_health.network` (migration 0077) |
 | 5 Three kinds, said once | mesh-controller `machine_network_test.go`: the rewrite is one finding naming its writer and its cost, with no address in its summary; one machine failing toward a healthy hub is its own; two are one condition at the hub, urgent, listing both; a silent hub holds it; a hub whose own network is unhealthy lists who cannot reach it; a mesh resolver failing from one machine is that machine's and from two is the resolver's machine's; the control node and the bus are urgent; an engine that says no network raises nothing; raised from the statement through the store and cleared when the file is written back |
 | 6 The gate | the same file: a rewrite the send did not make waits; one of the file a moved module owns is that module's; the machine's own network holds the machine as a whole; a machine that cannot reach a down hub waits |
 | 7 Reads only | the network package holds no write, restart or reconcile, and its tests run against files and fakes alone |
 | 8 The uplink seat's verbs | mesh-controller: the seat promises both and requires neither yet; a holder serving none, or both, holds it, and one naming a verb the seat does not promise is refused; a staged verb is never seeded into the row and comes back from the binary. mesh-catalog: each holder's bundle reads the mesh's file, a VPN client's file naming its writer, a backup beside it, a writer running, a link in its place, and the links with their default route and the manager's resolvers; both holders carry one copy of the reading, held by a test |
 | drill | mesh-host's `TestDrill…`, run in a throwaway container: declared, rewritten as the VPN client rewrites it, written back: healthy, healthy after one failing look, unhealthy naming FortiClient and the names it costs, healthy. Its statements are replayed by mesh-controller's `TestTheDrillsStatementsRaiseAndClearTheRewrite`, which raises the rewrite on the fourth statement alone and clears it on the fifth |
 | live | after rollout, the node-engine first and then the controller: every machine's `node show` lists its network's five parts (four where there is no tunnel tool); the laptop's next VPN connect raises `machine.<laptop>.<uplink holder>.rewritten` naming FortiClient, and the reconcile that writes it back clears it |
 ## References
 - [ADR 0240](0240-a-module-says-how-it-is-healthy-and-the-node-engine-judges-it.md), which this extends from
  modules to their machine. Its rules 2, 4, 5 and 6 are the shape here.
 - [ADR 0223](0223-the-mesh-has-two-resolvers-and-a-machine-lists-only-them.md) and
  [ADR 0117](0117-a-machines-uplink-is-a-seat.md): whose file it is, and what it lists.
 - [Research 033](../01-RESEARCH/033-split-dns-with-a-vpn-client/00-overview.md): the VPN client's behaviour,
  measured, and how the laptop could share names with it.
 - [To-be 48](../03-DESIGN/01-to-be/48-a-module-says-how-it-is-healthy.md) §10, the design.
 - Issues 262, 277 and 281.
 - mesh-host `internal/network`, `cmd/mesh-host`; mesh-controller `cmd/mesh-controller/machine_network.go`,
  `gate.go`, migration 0077, `internal/catalogue/seats.go` (the uplink seat's verbs); mesh-catalog
  `modules/networkmanager` and `modules/systemd-networkd`, `cmd/uplink-tools`.
@@ -1,131 +0,0 @@
 ---
 topic: what runs on it
 status: proposed
 date: 2026-10-07
 deciders: jochen
 reconstructed: false
 extends: 02-DECISIONS/0236-a-build-is-judged-on-its-first-machine-and-put-back-by-something-other-than-itself-and-so-it-rolls-out-unattended.md
 ---
 # 242. A recorded build moves only by a person's push, and a send says what it recreates
 ## Context
 [ADR 0236](0236-a-build-is-judged-on-its-first-machine-and-put-back-by-something-other-than-itself-and-so-it-rolls-out-unattended.md)
 §4 keeps `record` for three kinds of module: those whose new build a rollback could not undo, the
 network path, and the providers whose restart costs. A person takes each of their builds. Its §4a
 says that "a gated send carries everything waiting on its machine, and its gate judges all of it".
 A send carries the machine's whole declaration
 ([ADR 0221](0221-a-push-sends-no-build-a-policy-or-a-plan-holds-back-except-to-the-machine-it-names.md)),
 and that declaration is composed from the builds the mesh holds. A recorded module's build is
 registered at its merge, so every send to its machine composes the new build. "Waiting" and
 "judged" were only ever computed for modules that roll out.
 On 2026-10-07 ([issue 295](../04-ISSUES/295-a-recorded-build-was-carried-by-a-plans-send/00-report.md)),
 a catalogue merge adopted the images' own health checks in twelve modules. Its plan's gated sends to
 its two first machines carried the new builds of the database (on both machines) and of the
 document store (on the control node). Both modules are `record`. No gate judged them, and nobody
 pushed. The same send recreated nine of mail's eleven containers at once for a change that brought
 no new image, and the operator's mail was down until they were up again. The change plan had said
 only that mail "receives" a build.
 Measured that evening:
 - Fourteen modules record: the bus, two holding irreplaceable data, five on the network path, five
  providers and keycloak.
 - Each of them, waiting on a machine, was carried by the next send there for any other module that
  rolled out. That happened twice that evening.
 - One was still waiting afterwards: the media library, rebuilt at 19:01.
 ## Considered Options
 1. **Refuse every send but a person's to a machine where a recorded build waits**, as the bus is
   held today. Rejected. One recorded build would stop every plan on its machine until a person
   pushed it. On the control node that is the controller's own path, and [issue 280](../04-ISSUES/280-a-rebuild-of-an-unchanged-source-was-read-as-a-new-bus/00-report.md)
   is the evening it cost.
 2. **Do not register a recorded build until a person pushes.** Rejected. The mesh would no longer
   hold what was built. `status` could not say a machine is behind, and a person's push would have
   nothing to send.
 3. **Leave the recorded module out of the declaration** ([ADR 0163](0163-taking-a-module-over-is-a-comparison.md) rule 6: its containers
   untouched). Rejected. A left-out module contributes nothing, so its consumers on the machine would
   lose what it provides to them in the same send.
 4. **Compose the recorded module at the build its machine runs.** Chosen. The machine runs what it
   ran, everything else in the send moves, and the person's push remains the one way the new build
   arrives.
 For the interruption:
 5. **The node-engine recreates a module's containers one at a time where the module allows it.**
   Not decided here. It is the node-engine's apply order, and mail cannot tolerate even one of its
   front, smtp and imap containers going down unseen. It stays open as the better answer for
   modules with replicas.
 6. **Schedule a recreation-only change into a quiet window a module declares.** Not decided here.
   It needs a window per module and a clock in the walk, and a person's choice of moment does the
   same today.
 7. **A module that people use directly declares `record` and says why, and every send says what it
   recreates.** Chosen. It uses the policy that exists, which 1–4 make hold, and it marks the
   interruption where people read the send.
 ## Decision
 1. **A recorded build moves only by a person's push.** A person's push names a machine. Every other
   send composes each recorded module at the build that machine was last sent: the manifest of that
   build, from the build records, standing for the one the mesh holds. It also records that it still
   carries that build. This covers a plan's send to its first machine and to the rest, a release
   plan's, a rollback's, a healer's and a rotation's.
   - `status` still says the machine is behind, and `push <node>` sends the new build.
   - **The bus step is a person's word for the bus alone.** It moves the bus, and every other
     recorded module on that machine stays.
   - A module the machine was never sent is composed as the mesh holds it, since there is nothing
     running to keep.
   - If the build to keep is no longer in the records, the send is refused and the refusal names
     `push <node>`. Composing the new build there would be the very move this rule stops.
   §4a's "a gated send carries everything waiting on its machine" now reads: everything *that rolls
   out*.
 2. **A send says what it recreates.** For every module a gated send moves, it compares the build
   the machine ran with the build it is sent, container by container. It says how many containers
   it recreates and of how many, which ones, and whether any image is new or only the declaration
   changed. It warns when it recreates more than one container at once, because the module's service
   is interrupted until they are up again. This goes in the walk's record (`plans <id>`, the
   delivery's walk), the plan's note and the controller's log.
 3. **A module people use directly declares `record` and says why.** Mail is the first. A change to
   how its containers are declared recreates them together, so a person chooses the moment. Its
   image updates wait for a person too. A module that can be interrupted unseen keeps rolling.
 ## Consequences
 - **Plans no longer restart providers behind a person's back.** In exchange, a recorded module's
  machines stay behind until somebody pushes, as `record` always promised. `status` and `upgrade
  backlog` already say so.
 - **A declaration can now hold a build older than the one the mesh holds.** The resolution sees the
  kept manifest for that machine only. Other machines' consumers still resolve against the
  provider's registered manifest.
 - **Pruning the build records can make a kept build disappear.** [ADR 0189](0189-the-store-keeps-what-the-records-name.md)
  keeps five builds per module. If a recorded module falls more than five builds behind, sends to its
  machine are refused, said with the remedy, until a person pushes. That is loud rather than silent.
 - **The marking comes from the build, not before it.** The change plan at merge time cannot yet
  know which containers a build changes. The walk says it at the send. Saying it before the merge
  needs the planner to read the merged manifests, which is a later step.
 - **The time interrupted is not yet a number.** The mesh measures a send-to-report time per
  machine (`durations`), not how long one container takes to restart. The send says
  "interrupted until they are up again". A per-container start time in the node-engine's report
  would let it name a number.
 How it is checked: the controller's `TestARecordedBuildIsCarriedOnlyByAPersonsPush` replays
 issue 295 (a recorded provider and a rolled module on one machine, both rebuilt, the gated send). It
 fails on the commit before the fix. A mesh-lab replay is owed with the issue.
 ## References
 - [Issue 295](../04-ISSUES/295-a-recorded-build-was-carried-by-a-plans-send/00-report.md), the
  evidence.
 - mesh-controller PR #115: `recordedKept`, `keepRecorded`, `sendKeeps`, `inventory.ManifestAt`,
  `catalogue.Recreates`.
 - mesh-catalog PR #106: mail's policy.
 - [ADR 0236](0236-a-build-is-judged-on-its-first-machine-and-put-back-by-something-other-than-itself-and-so-it-rolls-out-unattended.md)
  §4, §4a; [ADR 0221](0221-a-push-sends-no-build-a-policy-or-a-plan-holds-back-except-to-the-machine-it-names.md);
  [ADR 0240](0240-a-module-says-how-it-is-healthy-and-the-node-engine-judges-it.md), whose first
  declarations were the change that recreated mail.
@@ -1,63 +0,0 @@
 ---
 topic: what runs on it
 status: accepted
 date: 2026-10-07
 deciders: jochen
 reconstructed: false
 extends: 02-DECISIONS/0216-the-agents-configuration-is-registered-through-its-module-at-three-scopes-and-served-as-one-plugin.md
 ---
 # 243. The agent module removes a home item it did not place only on the person's word, and keeps a copy
 ## Context
 [ADR 0216](0216-the-agents-configuration-is-registered-through-its-module-at-three-scopes-and-served-as-one-plugin.md)
 gave the agent module the home scope: the coding agent's own folder under the operator account. In
 its rule 5 the module "writes, changes and removes only" what it placed there. Rule 6 says it
 reports and can import what it did not place, and "removing the original stays the person's act".
 That left the person's act with no channel. Rule files written by hand under a predecessor system
 sat in the home of every machine. They told every session to use tools that no longer exist and
 contradicted the mesh's own instructions. The operator asked for them to be folded into mesh-wide
 instructions and removed. Removing a file on four machines without a tool means a remote shell on
 each, which is the work-around the mesh refuses: a missing tool is built in the module that owns
 the area, never worked around.
 ## Options
 1. **Leave removal outside the mesh.** The person deletes by hand on each machine. This keeps rule 5
   as written, but the mesh's most-used surface then has a task it cannot do, and the deletion
   leaves no trace and no way back.
 2. **Import, then unregister.** Importing at home scope puts the item under the mesh's care, and
   unregistering it removes it. This works today, but it is a trick: the record would say the
   mesh placed something it never placed.
 3. **A removal tool for what the module did not place, called only on the person's word.** It
   keeps a copy and logs the reason, with a restore tool beside it.
 ## Decision
 Option 3.
 - The module serves, per machine, a tool that reads one home item it did not place, the
  account's own instruction file included. It also serves a tool that removes one such item and
  a tool that puts a removed item back.
 - The removal tool requires a reason, and it is called only when the person asks for that item to
  go, never on an agent's own judgement. That is rule 6's "person's act", made through a tool.
 - Before removing, the module copies the item into its own state and checks the copy. If the
  copy fails, nothing is removed. The removal is logged with its reason, both in the module's
  state and in the journal.
 - The tool refuses an item the mesh placed, because unregistering owns those. It also refuses a
  symbolic link and a name that leads outside the item's own folder.
 - Restore refuses when something already exists at the original path.
 This extends rule 5 of ADR 0216: the module removes what it placed, and also, on the person's
 word, what it did not place. Rule 6 stands as written.
 ## Consequences
 - An item the mesh did not place can now leave a machine with its reason recorded and its content
  kept, and it can come back.
 - Whether the person asked is checked by nobody but the caller. The tool's description says so,
  and the logged reason is what an audit reads. A tool cannot tell an operator's request from an
  agent's initiative, so this rule is checked after the fact, by reading the removal log.
 - The kept copies stay in the module's state until removed. Clearing them is not decided here.
@@ -1,236 +0,0 @@
 ---
 topic: how we work
 status: accepted
 date: 2026-10-07
 deciders: jochen
 reconstructed: false
 extends: 02-DECISIONS/0006-the-substrate-and-the-control-plane.md
 ---
 # 244. The mesh is described in domains, and one word names one thing
 ## Context
 The operator, 2026-10-07: *"I wanted to develop our nox-mesh domain driven. Meaning every concept should
 fit into some domain and we try to come up with a common knowledge base/glossary/jargon for our
 application. We kind-of do this already I think, yet sometimes, you return different words for existing
 concepts."*
 Two terms from domain-driven design are used below. A **domain** (in the literature, a *bounded
 context*) is an area of the system inside which every word has exactly one meaning, and which owns the
 concepts that meaning describes. A **ubiquitous language** is the set of words a domain uses the same way
 in conversation, in documents and in code.
 [Research 034](../01-RESEARCH/034-the-mesh-in-domains/00-overview.md) measured the drift on 2026-10-07:
 - **The glossary's rule was checked by nothing.** It had 33 entries and said *one name per thing*. It
  retired "control plane" on 2026-09-16; three weeks later 29 occurrences stood in 12 to-be designs, the
  documents that tell somebody what to do. It retired "the host" for the node-engine on 2026-10-05; 34
  to-be designs and four tool descriptions the running mesh serves still said it, and so did the
  glossary's own entry for node tools.
 - **The glossary contradicted itself twice.** It defined the console as a module and, further down, said
  node tools had replaced that name; it said the deprecated broker holds no seat and, in the entry for
  *claim*, that it claims `mesh-broker` (the `nats` module claims it, ADR 0116).
 - **It lacked the words in use.** At least 40 words used in more than ten decision records each —
  *module*, *manifest*, *machine*, *provider*, *condition*, *gate*, *tier*, *operator* among them — had no
  entry.
 - **Twenty clashes**: two words for one thing (a *synonym*), or one word for several things (a
  *homonym*). *Plan* meant four things, three of them on one seat's verbs.
 - **The mesh already had domains under another name.** [ADR 0006](0006-the-substrate-and-the-control-plane.md)
  named seven *contexts* of the controller — inventory, config, connectivity, provisioning, delivery,
  observability, identity — and [ADR 0008](0008-a-context-owns-its-store.md) gave each its own store. The
  words the mesh grew since (seat, delivery, condition, ask, data class) were never sorted into them.
 This serves the mission directly: an agent states an intent and the mesh carries it out
 ([`mission.md`](../00-META/mission.md)). An agent answering from these documents repeats whichever word it
 read last, and one that meets two words for one thing assumes two things.
 The operator answered the research's questions on 2026-10-07, and those answers are decisions 2, 3 and 5
 below.
 ## Decision
 ### 1. The mesh is described in ten domains, and a domain replaces ADR 0006's context
 Every concept of the mesh belongs to exactly one domain, which owns its word and its meaning. Another
 domain may use the word as defined and never changes its meaning. The ten, most upstream first (a domain
 is *upstream* of another when the other depends on its concepts and not the other way round):
 | Domain | Owns | From ADR 0006 |
 |---|---|---|
 | **Module** | what a module is and declares: manifest, resource, claim, setting, kept region, bundle, tool, verb, invokes, upgrade policy | — |
 | **Core** | the mesh's own machinery: controller, control-node, node-engine, tool runner, foundation, store, bus, genesis, layer, lease and epoch | — |
 | **Placement** | what runs on which node: assignment, scope, capacity, bench, holder, declaration, send, apply | inventory, half of config |
 | **Provisioning** | one module serving another: provision, provider, consumer, pin, endpoint, retire | provisioning |
 | **Identity and access** | who may do what: credential, secret, vault, grant, bus account, licence, proof | identity, half of config |
 | **Change and delivery** | a commit on its way to the nodes: merge check, build seat, package, artifact, catalogue, delivery, delivery plan, walk, first-node gate, release | delivery |
 | **Health and repair** | what is wrong, and putting it right: health, probe, condition, self-check, healer, drill, hand-act | observability, renamed |
 | **Data** | what the mesh keeps: data class, backup, restore point, stream snapshot | — |
 | **Connectivity** | how nodes reach one another: private network, resolver, uplink, proxy, packet filter, reach | connectivity |
 | **Operator and conversation** | the person the mesh works for: the mesh MCP server, channel and intake, router, ask, operator message | — |
 Beside them, **the record** holds this repository's own words (research effort, decision record, design,
 issue, playbook, hq check), because they meet the mesh's.
 **"Domain" replaces ADR 0006's "context"** for this sense. ADR 0006's seven contexts carry over as
 domains under their names, except *observability*, which becomes **Health and repair**: the mesh never
 built alerts, it built conditions, and half of what the domain owns is repair. ADR 0008's rule now reads
 with *domain*: where a domain's records live in the controller, it owns that store alone. ADR 0006 and
 0008 are not rewritten; they keep their word, and the glossary says how to read it. A domain is a
 partition of words and records, not of the catalogue: one module may serve several domains, as research
 005 and ADR 0009 already found for modules.
 ### 2. A machine is any computer; a node is a machine the mesh has adopted and owns
 The operator: *"a node is a mesh-adopted/owned machine"*. Both words stay, with distinct meanings. A
 **machine** is any computer. A **node** is a machine the mesh has adopted and owns; a machine becomes a
 node when it joins (ADR 0004), and is then adopted or converged (ADR 0100). Prose about members of the
 mesh says node; prose about the hardware, or about the computer before or outside its adoption, says
 machine.
 This reverses the research's proposal to make *machine* the one word. The code that now misfits is listed
 in §6 for a later rename and is not renamed here.
 ### 3. One word per thing; the glossary is the authority; a retired word is listed in its entry with its scope
 [`00-META/glossary.md`](../00-META/glossary.md) is organised by domain and defines every word once, in the
 domain that owns it. A word another word replaced is named **in that word's entry**, on one fixed line —
 *Not:* followed by the struck-through word — with its **scope**: none (retired everywhere), *(hq)*
 (retired in this repository's prose only) or *(tools)* (retired in the descriptions of the mesh's tools
 only). Code that still carries an old name is named on an *Identifier until renamed* line and may stand
 only in a code span. Nothing else in the glossary is struck through.
 Scopes exist because vendor words are not drift. A module wrapping a program describes that program's
 objects in its own words — an identity provider's *users*, a media manager's *releases*, a router's
 *firewall* — so a word that is also a common vendor word is never retired in the tools' scope.
 A **homonym** is listed in the glossary's homonym table with the qualified form each domain uses, and is
 never bare in a governing document. A word list cannot tell one sense from another, so homonyms are
 **checked by review**; where one sense is settled by renaming, the old sense moves to a *Not:* line and
 becomes mechanical.
 ### 4. The words this record settles
 | Clash | Decided | Retired |
 |---|---|---|
 | the program on every node | **node-engine** | "the host" (hq: in the tools it is also an SSH server's and a container runtime's word), "host agent", "node host"; `mesh-host` an identifier until the code rename |
 | the program that serves every module's tools on a node | **tool runner** (ADR 0175's "node tools") | "node tools", "tool runtime" (hq); `node-tools` an identifier until renamed |
 | the loopback endpoint every agent and person on a node reaches the mesh through | **the mesh MCP server** — the MCP server named `mesh` and its five tools | "console" (hq: it suggests a terminal or shell, and the module `mesh-console` no longer exists), "mesh-console", "tool bridge" |
 | the module library | **mesh-sdk**; its tool-serving harness is part of it | "tools-sdk" |
 | plan | **declaration** (what the controller sends one node), **delivery plan** (what a delivery does), **walk** (one commit sent across nodes); the bus's **planned step** stays | "change plan", "release plan" |
 | moving a change | **send** (the controller giving a node its declaration; the verb `push` asks for one), **delivery**, **walk**, the policy **`roll`**, **release** (a person letting a held delivery go on, this sense only), **unbind** (a licence), **upgrade policy**; *deploy* only in **deploy plan** | "rollout" as a noun (hq), "deployment" (hq) |
 | the controller | **controller** | "control plane", "master" and "slave" (hq), "mesh-control" (hq) |
 | the foundation | **foundation** | "substrate" |
 | the build role | **build seat**, held on a node by the **builder** | "build machine" |
 | an open fact about something wrong | **condition**; a probe's result before it is one is a **finding** | "alert" (hq) |
 | the controller's examination of the mesh | **self-check** (the verb `doctor` is an identifier) | "doctor" in prose (hq) |
 | the mesh's own network | **private network** | "overlay" (hq) |
 | a manifest | **manifest** | "module definition" (hq) |
 | the catalogue | **catalogue**; `mesh-catalog` is an identifier | "catalog" (hq) |
 | a setting's predecessor | **setting** or a separate module | "flavor" |
 Decided as the research proposed, and checked by review because the word is ordinary or has vendor
 senses: **packet filter** for what the mesh enforces and **found firewall** for a program found on a
 machine; **operator** or **person** for a human, never *the user*, which is a wrapped program's or the
 bus server's account; **first-node gate** and **merge gate**, never *the gate*; **layer** for a level of
 the mesh, **tier** for a step of a walk, **assurance level** for how much proof an ask needs; **build
 request** for an entry in the build queue, *ask* staying the operator's; **store** for the database
 server only, **artifact store** and **last declaration** for the others; **decision record** always
 qualified in this repository; **agent** for a coding agent only. *Pipeline* is not retired: it names the
 predecessor's mechanism, which the as-is designs describe, and is never a word for a delivery.
 ### 5. The rule is checked, in this repository and in the catalogue
 - **`00-META/checks/words.py`**, run by `merge-check.sh` beside `records.py`, `index.py` and `cycle.py`,
  reads the glossary's *Not:* and *Identifier* lines and fails on a retired word of scope *hq* or none,
  or an identifier, in **running prose**: what is left once code blocks and spans, block quotes, text in
  quotation marks, struck-through text, link targets, comments and frontmatter are taken out. A quotation
  keeps the words it quotes; a link target is a file name. It also fails when a head word heads two
  entries or is also retired (**uniqueness**).
 - **It covers** `00-META/`, both layers of `03-DESIGN/`, `AGENTS.md` and `README.md` from now on, and
  research efforts initiated and issues opened on or after 2026-10-07. Decision records are never
  checked: they keep their words.
 - **A document it fails on** that cannot be reworded in the change that found it is named in
  `00-META/checks/words-allowed.md` with a date by which it is reworded; an entry past its date, or for a
  document that no longer needs it, fails. A graduated research effort may instead be **kept**, because it
  records what was said; research 034 is, since every clash it found names the words that clashed.
 - **The catalogue keeps a copy** of the words retired with scope none or *(tools)*, as `retired-words`,
  and its own repository check (`mesh/repo-check`, its `merge-check.sh`) fails when the text a module's
  tools show an agent — their descriptions, and the notes and errors they answer with — uses one. A
  copy rather than an artifact the catalogue reads: it fails loudly in the right place and adds no
  dependency to a catalogue merge. `words.py` compares the copy with the glossary when a checkout of the
  catalogue is named to it (`MESH_CATALOG_DIR`); a change that retires a tools word changes both.
 Every part failed on something real before it passed: `words.py` on 581 uses in 63 documents, and the
 catalogue's check on the forge module's pull request comment still headed "Change plan". Its first run
 also flagged an SSH client's "the host", which is that program's own word — so "the host" is retired in
 this repository's prose only, and the tools that meant the node-engine by it were reworded by hand.
 ### 6. What is not renamed here
 Code is renamed by the repositories that own it, each with its own change. The misfits, for that later
 work:
 - the mesh MCP server's tools: `mesh_machine`, and an overview listing *machines*, where the
  members of the mesh are nodes; the controller's `nodes` verb answering *"Every machine the mesh
  knows"*;
 - `mesh-host` (the node-engine's repository, binary and unit), `node-tools` (the tool runner's module,
  unit and bus account), `mesh-console` wherever code still names it, and the `--console` flag of the
  person's client;
 - `node-build-agent` (the build seat), the licence manager's verb `release` (unbind), the controller's
  verbs `plan` (a declaration), `doctor` (the self-check), and `queue`, `cancel` and `clear`, whose
  descriptions call a build request an *ask*;
 - the nftables module's tool `firewall_rules`, which serves the packet filter.
 ## Options rejected
 - **Machine as the one word, node only as an identifier** — the research's proposal, and what the newest
  records already said. Rejected by the operator: a machine and a node are different things, and the
  difference (adopted and owned by the mesh, or not) is one the mesh acts on.
 - **Node everywhere** — cheaper in code, but it leaves no word for the computer before it joins, which the
  joining, adoption and lab designs all need.
 - **Widening "context" to mean a domain** — keeps ADR 0006's word, but *context* is ordinary English in
  every other sentence, and the research found it used for a store-owning part of the controller. Two
  meanings for the word that is supposed to hold one meaning per word.
 - **Keeping both "context" and "domain"**, the research's tentative proposal (a domain holds contexts) —
  rejected as the effort's own synonym: only three contexts have a store, and the domain owns it anyway.
 - **A list of retired words in a file of its own in this repository** — a second source that drifts from
  the glossary. The *Not:* lines are the list.
 - **The list as an artifact the catalogue reads at check time** — one source, but one more thing that must
  be up for a catalogue merge. The checked copy is preferred.
 - **A probe in the self-check comparing the served descriptions with the list** — the descriptions an
  agent sees are the served ones, which may lag the catalogue's trunk; worth having once the first check
  has run, not before. A second place for the same rule.
 - **A warning-only mode** — a warning blocks a merge on the mesh's repositories the same as a failure
  (issue 293), so none is available.
 - **Retiring homonyms by list** (*plan*, *gate*, *tier*, *ask*, *store*, *record*, *check*) — the word is
  right in one sense and wrong in another; a list would cry wolf, and a check that cries wolf gets
  suppressed (`00-META/checks/README.md`).
 - **Retiring "the user", "firewall" and "pipeline" mechanically** — each has a correct use the check
  cannot tell apart (a bus server's users and an SSH user CA; a found firewall; the predecessor's
  pipeline). They are homonyms, reviewed.
 - **Rewriting research 034 in today's words** — it is the record of the words as they stood; it is kept.
 - **The reverse rule** (a to-be design defining a word in the glossary's form must find it in the
  glossary) — proposed by the research; not built here, because a bolded word followed by a dash is also
  how designs emphasise a term they do not define, and the first run would need its own measuring.
 ## Consequences
 - **The glossary is rewritten by domain**, with the missing words added, the two contradictions removed
  and every retired word on a *Not:* line. The domains are drawn in
  [to-be 49](../03-DESIGN/01-to-be/49-the-mesh-in-domains.md).
 - **The governing documents are reworded in the same change**: the node-engine, the tool runner, the
  mesh MCP server, the controller, the private network and the build seat by their words, in 63 documents.
  These are wording fixes, not changes of meaning; where a sentence quoted an older record, it is now in
  quotation marks.
 - **To-be 34 and as-is 13 describe a module, `mesh-console`, that no longer exists.** Their wording is
  fixed here; their substance is an as-is fact to update when the tool runner's serving mode is written
  up, not a word.
 - **A change that retires a word** edits the glossary's entry, rewords what `words.py` then finds, and —
  for a word in the tools' scope — changes the catalogue's copy and the descriptions it then finds.
 - **Tool descriptions are not yet held to *node* and *machine*.** Both words are correct, in different
  senses; which one a description needs is a reviewer's call. The catalogue's check holds them only to the
  retired words.
 - **The controller's, the node-engine's and the tool runner's own verb descriptions** are not in the
  catalogue, so its check does not see them; a check in those repositories is the same few lines and is
  left to them.
@@ -1,98 +0,0 @@
 ---
 topic: what runs on it
 status: accepted
 date: 2026-10-07
 deciders: jochen
 reconstructed: false
 extends: 02-DECISIONS/0216-the-agents-configuration-is-registered-through-its-module-at-three-scopes-and-served-as-one-plugin.md
 ---
 # 245. A verb says what it replaces, and the agent is guarded from working round the mesh
 ## Context
 The agent on the mesh's machines kept reading a service's log with `ssh <machine> journalctl …` and a
 container's with `ssh <machine> docker logs …`, while the service manager's seat served `journal` and the
 container module `docker_logs` on every machine. It was not refusing the tools; it never found them. The
 mesh MCP server offers five tools and finds everything else by `mesh_search` with the agent's own words
 ([ADR 0195](0195-the-meshs-tools-are-found-by-address-not-announced-whole.md)), and those words were the commands it would have
 typed — `journalctl`, `logs`, `systemctl status`, `docker ps`. Search matched names and descriptions: the
 journal verb's description says *journal*, never *logs* or *journalctl*, so the search answered nothing
 and ssh worked. The managed instructions said "the console is the only way to the mesh" and nothing
 stopped a session that did not believe it.
 Each work-around also hid the gap it went round: a machine reached by ssh is a tool nobody learns is
 missing.
 ## Considered Options
 1. **Write the guidance by hand** in the agent's instructions — "use the journal verb, not journalctl".
   Rejected: a hand-written list of tools drifts from the tools the mesh has, which is why the managed
   instructions already name no machine and no module.
 2. **Deny ssh in the agent's permission settings** (a `deny` rule on `Bash(ssh:*)`). Rejected: a prefix
   rule cannot tell a mesh machine from the forge — git over ssh to the forge is legitimate — nor see a
   command inside `bash -c` or `$(…)`, and its refusal names no tool.
 3. **Teach search synonyms only.** Rejected alone: it helps the agent that searches, and the habit at
   fault is not searching.
 4. **The verb says what it replaces, and three things are built from that one statement** — chosen.
 ## Decision
 1. **A verb or tool says which shell commands it replaces.** A seat's verb carries `replaces` in its
   definition — what a role replaces is the role's, so a module never says it for a verb it serves under a
   claim; a module says it for its own tools in its manifest, keyed by tool. Each entry is the command as
   typed (`journalctl`, `systemctl restart`, `docker logs`), one short line; `edit /etc/hosts` and
   `HOSTALIASES` name the two local work-arounds for a mesh name. The controller answers both — the
   seats' `tools` verb and `module list --json` — and is the only source.
 2. **The agent's instructions carry an "instead of" table generated from it**, on every render of the agent
   module: one row per seat or module, each verb with the commands it replaces, the rows the guard on that
   machine refused most first. Never written by hand: a verb that gains `replaces` is in the next render.
 3. **Search finds a tool by the command it replaces.** `mesh_search` matches a query that is a command line
   against every replaced command — its words in order — and ranks: a replaced command first (the most
   specific wins), then words in a name or a replaced command, then words in a description, with a short
   table of the words agents use for the mesh's (*logs* finds the journal). Seats before modules on a tie.
 4. **A guard on the agent's shell refuses working round the mesh.** The agent module delivers, in its plugin
   on every machine, a hook run before every shell command and file edit. It refuses `ssh` (and `scp`,
   `sftp`, `rsync`, `mosh`, `autossh`) to a mesh machine — by name, by a name under its domains, by any name
   in the mesh's internal domain, by address, read as ssh itself reads the destination, a jump through one
   included — and writing the hosts or resolver file, and `HOSTALIASES`. The refusal names the tool that does
   the job on that machine when one says it replaces the command, and otherwise says that **a missing tool is
   created in the module that owns it, on its seat, never worked around.** An ssh login as the forge's git
   account passes, **stated here rather than silently**: that account runs git and nothing else. Nothing else
   is allowed by exception.
 5. **The operator alone overrides the guard, and every override is recorded.** An override is a variable
   with the reason as its value, set in the operator's own shell before a session starts, read from the
   session's environment as it was started — so nothing a session does can set it, and a command naming it is
   refused outright. Every override and every refusal is a line in the agent module's record on that machine,
   readable through the module's tool; an override that cannot be recorded is not honoured.
 ## Consequences
 - **How each rule is checked.** Rule 1: the controller refuses a manifest whose `replaces` names a tool it
  does not declare, or an entry that is empty, longer than a line or repeated — the module check every pull
  request's gate runs; the controller's tests hold that the worked-around verbs say what they replace.
  Rule 2: the agent module's tests generate the table from records and hold its rows, order and cut; the
  rendered file is the module's managed instruction file, never edited. Rule 3: the tool runner's tests hold
  that `journalctl`, `logs`, `systemctl status` and `docker ps` find the right verb first, and that a
  controller older than the field searches as before. Rules 4 and 5: the agent module's tests hold the
  guard's refusals and what passes — git to the forge, ssh beyond the mesh, a command merely mentioning
  ssh — the override read only from the session's start, and recorded; the module's guard tool shows the
  rules, the data and the record, which is how a refusal that should not have happened, or a habit that
  found a way round, is seen.
 - **It is a guard against a habit, not a sandbox.** A command built to hide what it runs can hide it. The
  record is the check on that, not the matcher.
 - **A tool the mesh lacks now surfaces as a refusal** instead of disappearing into an ssh session. The
  answer to one is a tool in the owning module, which is more work than an ssh line, and is the point.
 - **A module's `replaces` waits for the controller that reads it.** The manifest is read strictly, so a
  module may say what its tools replace only once that controller runs; until then its tools are found by
  name and description as before, and the seats' verbs carry the mesh's own statement.
 - The agent module now asks the controller for its tools and machines every few minutes, and renders when
  the answer changes.
 ## References
 - The controller: verbs say what they replace, the manifest field, both answers (`mesh-controller`).
 - The mesh MCP server's search (`mesh-tools`, the tool runner's loopback mode).
 - The agent module's table, guard and record (`mesh-catalog`, the claude-code module).
 - [ADR 0195](0195-the-meshs-tools-are-found-by-address-not-announced-whole.md) — the mesh's tools are found by address.
 - [ADR 0216](0216-the-agents-configuration-is-registered-through-its-module-at-three-scopes-and-served-as-one-plugin.md) — the agent's plugin, which carries the guard.
@@ -1,83 +0,0 @@
 ---
 topic: the mesh
 status: accepted
 date: 2026-10-07
 deciders: jochen
 reconstructed: false
 extends: 02-DECISIONS/0132-a-seat-carries-the-tools-its-holder-must-serve.md
 ---
 # 246. A seat's new verb is promised before it is required
 ## Context
 [ADR 0132](0132-a-seat-carries-the-tools-its-holder-must-serve.md) made serving a seat's verbs a
 condition of holding it. [Design 33](../03-DESIGN/01-to-be/33-the-tools-the-mesh-answers.md) §7 says
 those verbs change "additively within a version". The controller's claim check enforces two things: a
 holder serves every verb the seat promises, and a claim names no verb the seat does not promise.
 A mesh seat is defined in the controller, and its holders live in the catalogue. On 2026-10-07 three
 verbs were added this way: `checks` on `mesh-delivery`, `failed` on `node-service-manager`, and
 `resolvers` and `links` on `node-uplink`. Each time, neither repository could merge first
 ([issue 298](../04-ISSUES/298-a-new-seat-verb-deadlocks-across-two-repositories/00-report.md)). The new
 controller refused the old holder for not serving the verb. The old controller refused the new holder for
 claiming a verb it did not promise. Every catalogue check between the two failed on a module nobody had
 touched. The controller was unblocked by marking the added verb optional (mesh-controller #117, kept
 optional in a stored seat row by #114).
 ## Options
 1. **Drop the check that refuses an unpromised verb.** The catalogue could then land first. But the check
   catches a misspelt verb that would otherwise be served to nobody. The controller's change would still
   refuse every holder not yet rebuilt, so only one order opens.
 2. **A new seat version for every added verb.** §7 already allows a version for a change that would
   break a caller. Running two versions side by side to add one verb costs a set of subjects, grants and
   a retirement for nothing a caller would notice.
 3. **Land both repositories at once.** Nothing joins two checked pull requests into one merge, and the
   mesh would have to run both builds at the same moment on every machine.
 4. **Promise first, require later.** The controller promises the verb as optional. Then the holder
   serves it. Then the controller makes it required.
 ## Decision
 Option 4. **A verb added to a seat whose holder lives in another repository lands in three steps, each
 in its own pull request:**
 1. **The controller promises it, optional.** A claim that serves it is accepted, and a holder that does
   not serve it still holds the seat. The mark comes from the seat as compiled and survives a seat row
   read back from the store.
 2. **Every holder serves it.** Each holder is checked against a controller that already promises the
   verb.
 3. **The controller requires it.** The mark is removed, and serving the verb becomes a condition of
   holding like every other verb of the seat.
 A verb on a new seat, or on a seat that nothing holds yet, is required from the start. Removing a verb
 or changing its arguments in a way that breaks a caller is still a new version (§7).
 ## Consequences
 - Adding a verb to a held seat takes two controller changes and one in each holder's repository, where
  design 33 implied one change. That is the price of §3 holding at every moment in between.
 - Between steps 1 and 3, a caller can be told that a holder does not answer the verb. The caller finds
  this out from the holder, not from the seat's protocol. Discovery lists the verb, because it is
  promised.
 - Nothing yet checks that step 3 happens. A verb left optional is a promise that no future holder has to
  keep. Issue 298 is not resolved until a check covers it.
 ## How it is checked
 - The controller's claim check refuses a claim that serves an unpromised verb, and a holder that misses a
  required verb. It runs at registration, at handover, and in `module check`, which the catalogue's merge
  check runs over every manifest with the controller the mesh runs.
 - Tests in mesh-controller:
  - `TestTheDeliverySeatPromisesChecks` (#117);
  - `TestFailedIsAnOptionalVerbOfTheServiceManager`, `TestAnOptionalVerbStaysOptionalInASetReadFromTheStore`
    and `TestASeatsVerbGainsTheArgumentsTheBinaryNames` (#114);
  - `TestTheUplinkSeatPromisesItsVerbsAndRequiresNoneYet` and
    `TestTheUplinkVerbsReadBackFromTheRowStayOptional` (#116).
 ## References
 - [Issue 298](../04-ISSUES/298-a-new-seat-verb-deadlocks-across-two-repositories/00-report.md)
 - [Design 33](../03-DESIGN/01-to-be/33-the-tools-the-mesh-answers.md) §3 and §7
 - mesh-controller #114, #116 and #117; mesh-catalog #105, #107 and #109
@@ -1,244 +0,0 @@
 ---
 topic: the tiers
 status: accepted
 date: 2026-10-07
 deciders: jochen
 reconstructed: false
 extends: 02-DECISIONS/0223-the-mesh-has-two-resolvers-and-a-machine-lists-only-them.md
 ---
 # 247. A machine with a VPN client routes names by domain, through a resolver of its own
 ## Context
 **Every machine lists the mesh's two resolvers in `/etc/resolv.conf`, and nothing else**
 ([ADR 0223](0223-the-mesh-has-two-resolvers-and-a-machine-lists-only-them.md)). The module holding the
 machine's uplink writes that file ([ADR 0117](0117-a-machines-uplink-is-a-seat.md)). The *uplink* is the
 program that manages the machine's own network connection, NetworkManager or systemd-networkd. A
 *resolver* is a server that answers questions about names.
 **On the laptop, a VPN client writes the same file.** The operator's employer supplies the VPN client,
 FortiClient's Linux client. When it connects, it moves the mesh's file aside and writes its own: two
 servers reached through its tunnel, and eight search domains of the company's network. It never tells
 systemd-resolved or NetworkManager which servers belong to which link, and it never writes the file again
 during a session. [Research 033](../01-RESEARCH/033-split-dns-with-a-vpn-client/00-overview.md) measured
 what followed, from the client's log and the node-engine's journal:
 - In **nine of nine** sessions the node-engine wrote the mesh's file back at its next reconcile, 1 s to
  3.5 min after the connect. From then on **no company name resolved** for the rest of the session, and
  sessions lasted up to fourteen hours.
 - In the minutes before that, **no mesh name resolved**. On 2026-10-07 a delivery to the laptop failed on
  37 resources, because the artifact store's name was asked of the VPN's servers, which answered "no such
  host".
 - **One file cannot list both sets of servers.** musl, the C library of every Alpine container, asks every
  listed server at once and takes the first reply. glibc takes the first server's "no such name" as final
  ([issue 262](../04-ISSUES/262-an-alpine-container-could-not-find-a-machine-by-its-mesh-name/00-report.md)).
  Whatever the order, one kind of name fails.
 [ADR 0241](0241-a-machine-says-how-its-network-is-and-an-outside-writer-of-a-mesh-file-is-a-finding.md),
 merged today, makes this visible: the node-engine raises `machine.<m>.<owner>.rewritten`, naming
 FortiClient from the file's header. It said how the laptop should share names with the VPN was research
 033's question. This record answers it.
 **Research 033 recommended** routing by domain with systemd-resolved, run by the uplink's holder on a
 machine that declares a VPN client, with a path watch in the same holder taking the VPN's file. **The
 operator approved a different split of the same mechanism on 2026-10-07**: the resolver is its own module
 on a seat of its own, the VPN client's module carries the adapter, and nothing declares a VPN client.
 The options below say why.
 **Checked against GENESIS.** *Failure must be loud*: a write nothing handles is still raised. *The mesh is
 a guest on a personal node*: the VPN client is the employer's and is not changed, and its domains never
 leave the machine. *Do one thing in one place*: the resolver is written once, not once per uplink holder.
 Nothing conflicts.
 ## Considered Options
 **What routes names by domain.**
 1. *Add the VPN's servers to the mesh's file.* Rejected (research 033 option 2): it breaks the one-answer
   rule above.
 2. *Forward the company's domains from the mesh's resolvers.* Rejected (option 3): they cannot reach
   servers that sit behind one laptop's tunnel, and the company's zones would become every machine's.
 3. *Leave the VPN's file in place for the session.* Rejected (option 4): the laptop loses the mesh, the bus
   included, for whole working days. Research 033 also offered this as an interim setting until routing was
   built. It is not adopted: the routing is built with this record.
 4. **systemd-resolved on the machine**, which sends each name to the servers of the link whose domain
   matches it, and every other name to the mesh's resolvers. Chosen. dnsmasq on the machine would also work
   (option 5). It costs a configuration rewrite and a reload on every connect, where resolved takes a
   link's servers live and forgets them when the link goes. resolved ships with systemd, so it needs no
   new package.
 **Who runs it.**
 1. *The uplink's holder*, as research 033 recommended. Rejected: there are two uplink holders,
   NetworkManager's and systemd-networkd's, so the resolver would be written twice, and kept the same by
   a test. And each would have to know which VPN clients exist.
 2. *The node-engine.* Rejected for ADR 0223 part 3's reason: the node-engine applies every module's
   resources and owns no file's content.
 3. **A module of its own, holding a new node seat, `node-resolver`.** Chosen. A *node seat* is a role that
   one module holds per machine. Another module could hold it on a machine without systemd.
 **Who knows about the VPN client.**
 1. *The resolver, given a setting that names the client* (research 033 rule 1). Rejected: it would grow a
   branch for every VPN client.
 2. **The module that wraps the client.** Chosen. The mesh's default pattern is that the module wrapping a
   program owns that program's quirks. The resolver offers a generic verb: route these domains to these
   servers over this link. A VPN that tells systemd-resolved its link's DNS itself needs no adapter.
   NetworkManager's VPN plugins, WireGuard under systemd-networkd and Tailscale all do this.
 **How the adapter reaches the resolver.**
 1. *Through the bus, as `<node>/node-resolver.route`.* Rejected for this caller: the VPN's servers and
   domains would cross the broker on another machine.
 2. **On the machine, over a socket only root can open, with the same verbs.** Chosen. The socket's path is
   the seat's, so a caller does not need to know which module holds it. The same verbs are also served on
   the bus, for the operator to read and correct routes.
 **What happens to the VPN client's write.**
 1. *Put the resolver's file back at once, whatever wrote it.* Rejected: a write nothing handles would end
   before the node-engine looks twice, and so would never be said.
 2. *Leave it to the node-engine's reconcile*, as today. Rejected: a handled write would then still cut
   off the mesh's names for minutes.
 3. **Keep it, put the module's file back at once when a module took it, and otherwise after 90 s.**
   Chosen. 90 s is longer than two of the node-engine's 30 s looks.
 ## Decision
 **1. A machine's own resolver is a node seat, `node-resolver`, held only where something requires it.**
 Its first holder is the catalogue module `systemd-resolved`, which provides the provision `split-dns` at
 the machine's reach. A *provision* is something one module offers another. *The machine's reach* means a
 requirement is answered only by a provider on the same machine, and the provider is never pulled in by
 the requirement ([ADR 0208](0208-the-graphical-session-is-one-module-per-piece-on-the-meshs-seats.md) §3).
 A machine where nothing requires `split-dns` is unchanged: its uplink's holder writes the file listing the
 mesh's two resolvers.
 **2. Where it is held, the resolver writes `/etc/resolv.conf`, and the uplink's holder steps back from that
 file.** The rule is the controller's. On a machine where a module holds `node-resolver` and renders the
 resolver file, the uplink holder's rendering of the same path is not composed. Everything else the uplink
 holder declares stays. Only the uplink holder steps back: any other module writing the file beside the
 resolver is still two owners of one path, and is refused as before.
 **3. The file names the machine's own private address alone, with ADR 0223's options.** resolved listens
 there and on loopback. ADR 0223 rejected a local forwarder (its option 2) for three reasons, and each is
 answered here:
 - *A daemon on every machine*: only on a machine that requires `split-dns`.
 - *A container cannot use a loopback resolver*: the file names the private address, which a container
  can reach. The packet filter admits the machine's own guests and nobody else, so no other machine can
  ask this resolver.
 - *A per-node copy disagreeing with the truth*: resolved keeps no cache and reads no hosts file, and every
  name not routed elsewhere goes to the mesh's two resolvers. They are its default route, with no public
  fallback.
 **4. The resolver's verbs route by link, and know nothing of a VPN.**
 | verb | what it does |
 |---|---|
 | `routes` | what is routed where, and the resolver file's outside writes |
 | `route {link, domains, servers}` | send those domains, and every name under them, to those servers over that link, and only them |
 | `unroute {link}` | send that link's domains back to the mesh's resolvers |
 `route` refuses the mesh's own domain and the root. A link with servers of its own is never a default
 route for names, whether this verb set it or a network manager did. resolved forgets a link's route when
 the link goes. The seat is new and nothing holds it, so its verbs are required from the start
 (ADR 0246).
 **5. The resolver keeps its file, and keeps an outside write for whoever handles it.** Its guard runs as
 root and compares the file with the module's copy twice a second. When another program has written the
 file, the guard does three things:
 - It **keeps** what was written, readable by root alone and gone at the next boot, and names the writer
  from the file's header.
 - If a module on the machine **takes** the write (it routed what it needed and says so), the guard puts
  the module's file back at once.
 - Otherwise it puts the module's file back **after 90 s**.
 Of an outside write, the resolver says nothing beyond the machine except when it happened, the writer's
 name and what became of it. It never says a server or a domain from the write.
 **6. The VPN client's module carries its own adapter.** The `forticlient` module requires `split-dns` and
 runs an adapter, as root, that does four things:
 - It reads the client's servers and search domains from the kept write.
 - It waits up to 15 s for the client's tunnel link, then routes those domains to those servers over it
  and takes the write in the same call.
 - It takes the route away when the tunnel goes.
 - It gives the route again if the resolver restarted and forgot it.
 The client's search domains become routing domains. A short name is not completed with them.
 **7. ADR 0241's network check agrees without a change to it.** The node-engine already judges the file
 that a module declares whole at that path, so on a machine with the resolver it judges the resolver's
 file. A write the adapter took is undone within seconds, before the node-engine's second look, so it is
 no finding. A write nothing took stands for 90 s, so the node-engine sees it twice and raises
 `machine.<m>.systemd-resolved.rewritten`, naming the writer. This covers an undeclared writer, the
 adapter not running, no tunnel within its wait, and a route refused. The guard then puts the file back,
 and the finding clears.
 **8. The VPN's domains stay on the machine.** They are never in the mesh's store, the controller's
 renders, the mesh's resolvers, an event or another machine's files. The adapter hands them over on the
 machine, never over the bus. They live in resolved's per-link state for the life of the tunnel, and in the
 kept write until the next boot. They cross the bus only as the answer to `routes` when the operator asks
 it, and nothing keeps that answer.
 ## Consequences
 - **The laptop resolves both kinds of name while the VPN is up**, and public names through the mesh's
  resolvers, as before. The fight between the two writers ends: the VPN client's servers are used, for
  the VPN's domains only.
 - **A machine with the resolver has one more thing that can stop its names**: resolved, or its guard,
  down. Both declare `unit` health, so the node-engine judges them (ADR 0240). The node-engine's names
  check asks the address the file lists, which is resolved's, so a resolved that does not answer is said
  there too.
 - **The client's search domains do not expand short names**, because the machine's file is the mesh's
  and lists no search domain. A full company name resolves.
 - **Every machine that runs the `forticlient` module needs the resolver.** The module requires
  `split-dns` wherever it runs, and the workstation runs it too. Either `systemd-resolved` is assigned
  there as well, or the client is unassigned from the workstation, before the module's change is
  delivered. Otherwise the controller refuses the workstation's composition, naming who could provide
  `split-dns`.
 - **The rollout has an order.** First the controller that knows the seat, which must be running, since
  the catalogue's check reads manifests with the controller the mesh runs. Then the resolver module,
  assigned to the machines that need it. Then the `forticlient` change.
 - **Containers keep the resolvers they started with** (ADR 0223's consequence, unchanged). On the laptop a
  container started before the resolver is assigned keeps the mesh's two resolvers until it restarts. That
  is correct for mesh names, but it means the company's names do not reach that container.
 - **To confirm live:** resolved takes no servers from `/etc/resolv.conf` once its own are configured
  (`DNS=` in its drop-in). So neither a VPN client's write, nor the file's own address, should become one
  of its servers. The live test reads `routes` while a write stands to confirm it.
 - **Unassigning the resolver** brings the uplink holder's rendering back. The node-engine hands a whole
  file from one owner to the next at the same path, so the file is not removed in between.
 ## How it is checked
 | Rule | Checked by |
 |---|---|
 | 1 The seat, its verbs required, its holder providing `split-dns` at the machine's reach | mesh-controller `TestTheMachinesOwnResolverIsANodeSeatWithItsVerbs`, `TestTheCataloguesResolverHoldersWriteTheFileAndProvideSplitDNS`, `TestTheSeatsAreAClosedSetAndEachNamesItsDecision`; mesh-catalog systemd-resolved `TestTheManifestSaysWhatTheGuardKeeps` |
 | 1 Nothing changes where it is not held | `TestWithoutTheResolverTheUplinkWritesTheFileAsBefore` |
 | 2 The uplink steps back, and only the uplink | `TestWhereTheResolverIsHeldItWritesTheFileAndTheUplinkStepsBack`, `TestOnlyTheUplinkStepsBackForTheResolver`, `TestTheCataloguesUplinksWriteTheResolverFileAndNothingElseDoes` |
 | 3 One address, the mesh's resolvers as default route, no fallback, no cache | `TestTheCataloguesResolverComposesOnAMachine` (the catalogue's module rendered by the controller); `TestTheManifestSaysWhatTheGuardKeeps` |
 | 4 Routes by link; the mesh's domain and the root refused; no default route for a link's servers | mesh-catalog systemd-resolved `TestARouteSendsOnlyItsDomainsOverItsLink`, `TestARouteThatWouldTakeTheMeshsNamesIsRefused`, `TestOnlyTheMeshsResolversAnswerEveryName`, `TestUnrouteRevertsTheLink`, `TestRoutesReadWhatResolvedSendsWhere` |
 | 5 Kept, taken, held, said without servers or domains | `TestATakenWriteIsPutBackAtOnce`, `TestAWriteNobodyTakesStandsUntilItIsSaidThenGoes`, `TestWritesUndoneAndWrittenOverAreSaid`, `TestTheVerbsOnTheMachine` (the socket root's alone) |
 | 6 The adapter | mesh-catalog forticlient `TestTheClientsDomainsAreRoutedOverItsTunnelAndGoWithIt`, `TestAWriteWithNoTunnelOrNotTheClientsIsLeftToTheResolver`, `TestARouteIsKeptAcrossARestartOfEither`, `TestTheClientsFileIsReadForItsServersAndDomains`, `TestItDeclaresTheServiceAndNothingOfTheConfiguration` |
 | 7 Agrees with ADR 0241 | by construction: the node-engine's `declaredResolvConf` judges the file declared whole at the path, which rule 2 makes the resolver's; the 90 s hold is held above two looks by `TestAWriteNobodyTakesStandsUntilItIsSaidThenGoes`. Live: below |
 | 8 Never leaves the machine | the socket's mode in `TestTheVerbsOnTheMachine`; no server or domain in the history (`TestATakenWriteIsPutBackAtOnce`) or the adapter's journal (`TestTheClientsDomainsAreRoutedOverItsTunnelAndGoWithIt`) |
 | live | on the laptop, connected: a company name and a mesh name both resolve, on the machine and in an Alpine container on a bridge; `node-resolver.routes` shows the tunnel with its domains and the write taken by `forticlient`; no `machine.<laptop>.….rewritten` stays raised. Disconnected: the route is gone and the file is the resolver's |
 ## References
 - [Research 033](../01-RESEARCH/033-split-dns-with-a-vpn-client/00-overview.md): the evidence and the
  options, and the recommendation this record changes.
 - [ADR 0223](0223-the-mesh-has-two-resolvers-and-a-machine-lists-only-them.md), which this extends: its
  rule that a machine lists only the mesh's resolvers holds everywhere but on a machine with its own
  resolver, which lists itself and asks only them.
 - [ADR 0241](0241-a-machine-says-how-its-network-is-and-an-outside-writer-of-a-mesh-file-is-a-finding.md):
  the finding, unchanged.
 - [ADR 0117](0117-a-machines-uplink-is-a-seat.md), [ADR 0207](0207-a-module-depends-on-the-node-seats-that-apply-its-resources.md)
  (resolved's package is the service manager's holder's), [ADR 0240](0240-a-module-says-how-it-is-healthy-and-the-node-engine-judges-it.md),
  ADR 0246.
 - [To-be 50](../03-DESIGN/01-to-be/50-split-dns-on-a-machine-with-a-vpn-client.md), the design; to-be 48
  §10 and connectivity §2, amended alongside.
 - mesh-controller `internal/catalogue/node_resolver.go`, `seats.go`, `declaration.go`, `resolve.go`;
  mesh-catalog `modules/systemd-resolved`, `modules/forticlient`.
@@ -194,21 +194,6 @@ python3 00-META/checks/index.py            fail if stale
 - **0207** — [A module depends on the node seats that apply its resources](0207-a-module-depends-on-the-node-seats-that-apply-its-resources.md)
 - **0210** — [A tool's configuration is its seat holder's, and every other module extends it through the seat](0210-a-tools-configuration-is-its-seat-holders-and-every-other-module-extends-it-through-the-seat.md)
 - **0212** — [A seat says what it receives, and the machine's hotkeys are a seat](0212-a-seat-says-what-it-receives-and-the-machines-hotkeys-are-a-seat.md)
 - **0218** — [A plan sends grants before code, rolls a module out one machine first, and a newer merge takes over an older plan](0218-a-plan-sends-grants-before-code-rolls-out-one-machine-first-and-a-newer-merge-takes-over-an-older-plan.md)
 - **0219** — [The build queue is controlled through the controller and the build seat](0219-the-build-queue-is-controlled-through-the-controller-and-the-build-seat.md)
 - **0221** — [A push sends no build a policy or a plan holds back, except to the machine it names](0221-a-push-sends-no-build-a-policy-or-a-plan-holds-back-except-to-the-machine-it-names.md)
 - **0222** — [A module is told where a mesh seat's holder is reached, and the controller writes no file a seat's holder owns](0222-a-module-is-told-where-a-mesh-seats-holder-is-reached-and-the-controller-writes-no-file-a-seats-holder-owns.md)
 - **0224** — [A provider that keeps failing a consumer is a problem the controller reports](0224-a-provider-that-keeps-failing-a-consumer-is-a-problem-the-controller-reports.md)
 - **0227** — [The core holds nine rules, each checked, and is built to them in six phases](0227-the-core-holds-nine-rules-each-checked-and-is-built-to-them-in-six-phases.md)
 - **0229** — [The core's order is a lease the store remembers, and an epoch a machine is sent once it reads one](0229-the-cores-order-is-a-lease-the-store-remembers-and-an-epoch-a-machine-is-sent-once-it-reads-one.md)
 - **0230** — [A consumer the mesh stops asking for is retired, and deleted only by a person](0230-a-consumer-the-mesh-stops-asking-for-is-retired-and-deleted-only-by-a-person.md)
 - **0231** — [A healer acts on what observation raised, and only observation says it worked](0231-a-healer-acts-on-what-observation-raised-and-only-observation-says-it-worked.md)
 - **0234** — [The mesh holds a conversation with its operator, over channels that are seats, and an answer that performs an action is authorised by the controller](0234-the-mesh-holds-a-conversation-with-its-operator.md)
 - **0236** — [A build is judged on its first machine and put back by something other than itself, and so it rolls out unattended](0236-a-build-is-judged-on-its-first-machine-and-put-back-by-something-other-than-itself-and-so-it-rolls-out-unattended.md)
 - **0237** — [A change is judged against the mesh that runs, before it merges, on the build seat](0237-a-change-is-judged-against-the-mesh-that-runs-before-it-merges-on-the-build-seat.md)
 - **0238** — [A commit is the build at hand: one commit, one change plan, checked off the trunk and published only on it](0238-a-commit-is-the-build-at-hand-one-commit-one-change-plan-checked-off-the-trunk-and-published-only-on-it.md)
 - **0239** — [A delivery is owned by the mesh-delivery module and runs from commit to delivered](0239-a-delivery-is-owned-by-the-mesh-delivery-module-and-runs-from-commit-to-delivered.md)
 - **0246** — [A seat's new verb is promised before it is required](0246-a-seats-new-verb-is-promised-before-it-is-required.md)
 ### Its tiers, from the bottom up
@@ -246,9 +231,6 @@ python3 00-META/checks/index.py            fail if stale
 - **0194** — [The mesh has one resolver, and every node asks it for the mesh's names](0194-the-mesh-has-one-resolver-and-every-node-asks-it-for-the-meshs-names.md)
 - **0196** — [A node asks the mesh's resolver first, and a public one only when it is silent](0196-a-node-asks-the-meshs-resolver-first-and-a-public-one-only-when-it-is-silent.md)
 - **0199** — [A module that answers names declares its zone, and a node's hosts file is one module's](0199-a-module-that-answers-names-declares-its-zone-and-a-nodes-hosts-file-is-one-modules.md)
 - **0223** — [The mesh has two resolvers, and a machine lists only them](0223-the-mesh-has-two-resolvers-and-a-machine-lists-only-them.md)
 - **0226** — [The private network is assigned by its own name, and the proxy names its public issuer](0226-the-private-network-is-assigned-by-its-own-name-and-the-proxy-names-its-public-issuer.md)
 - **0247** — [A machine with a VPN client routes names by domain, through a resolver of its own](0247-a-machine-with-a-vpn-client-routes-names-by-domain-through-a-resolver-of-its-own.md)
 ### What runs on them, and how it gets there
@@ -334,17 +316,6 @@ python3 00-META/checks/index.py            fail if stale
 - **0214** — [Backups guard against mistakes, stay on the machine, and are declared by the module that owns the data](0214-backups-guard-against-mistakes-and-stay-on-the-machine.md)
 - **0215** — [The machine's message bus is a node seat, and it is never restarted live](0215-the-machines-message-bus-is-a-node-seat-and-is-never-restarted-live.md)
 - **0216** — [The agent's configuration is registered through its module, at three scopes, and served as one plugin](0216-the-agents-configuration-is-registered-through-its-module-at-three-scopes-and-served-as-one-plugin.md)
 - **0220** — [What a machine asks needs its uplink held, and the retired resolver pieces go](0220-what-a-machine-asks-needs-its-uplink-held-and-the-retired-resolver-pieces-go.md)
 - **0225** — [A consumer's identity is bounded by the provision it requires, judged before merge, and never refuses its provider](0225-a-consumers-identity-is-bounded-by-the-provision-it-requires.md)
 - **0228** — [A value given by hand lives only until its module's first good start](0228-a-value-given-by-hand-lives-only-until-its-modules-first-good-start.md)
 - **0232** — [A binding to a consumer's data moves only by a person](0232-a-binding-to-a-consumers-data-moves-only-by-a-person.md)
 - **0233** — [A module declares the data it holds, and the mesh protects and watches it from that declaration](0233-a-module-declares-the-data-it-holds-and-the-mesh-protects-and-watches-it-from-that.md)
 - **0235** — [The bus is backed up by its own snapshot of each stream, taken under the bus module's account](0235-the-bus-is-backed-up-by-its-own-snapshot-of-each-stream.md)
 - **0240** — [A module says how it is healthy, and the node-engine judges it](0240-a-module-says-how-it-is-healthy-and-the-node-engine-judges-it.md)
 - **0241** — [A machine says how its network is, and an outside writer of a mesh file is a finding](0241-a-machine-says-how-its-network-is-and-an-outside-writer-of-a-mesh-file-is-a-finding.md)
 - **0242** — [A recorded build moves only by a person's push, and a send says what it recreates](0242-a-recorded-build-moves-only-by-a-persons-push-and-a-send-says-what-it-recreates.md)  *(proposed)*
 - **0243** — [The agent module removes a home item it did not place only on the person's word, and keeps a copy](0243-the-agent-module-removes-a-home-item-it-did-not-place-only-on-the-persons-word-and-keeps-a-copy.md)
 - **0245** — [A verb says what it replaces, and the agent is guarded from working round the mesh](0245-a-verb-says-what-it-replaces-and-the-agent-is-guarded-from-working-round-the-mesh.md)
 ### How it is built
@@ -389,6 +360,5 @@ python3 00-META/checks/index.py            fail if stale
 - **0080** — [The development cycle is checked, not trusted](0080-the-development-cycle-is-checked.md)
 - **0081** — [A decision nothing cites is not yet in the chain](0081-a-decision-nothing-cites-is-not-yet-in-the-chain.md)
 - **0153** — [The record is read by a module the mesh assigns, and the console lists it](0153-the-record-is-read-by-a-module-and-the-console-lists-it.md)
 - **0244** — [The mesh is described in domains, and one word names one thing](0244-the-mesh-is-described-in-domains-and-one-word-names-one-thing.md)
 <!-- index:end -->
@@ -20,7 +20,7 @@ One relational database holds the bindings. Its content divides cleanly:
 | Holds | Describes |
 |---|---|
 | Node records | Which nodes exist, and each node's own properties — its name in the mesh, whether it carries a public name, its identity text |
-| Assignments | Which node runs which module, at which selection, and whether it starts automatically |
+| Assignments | Which node hosts which module, at which selection, and whether it starts automatically |
 | Overrides | Per-node, per-module values that take precedence over anything the manifest generates |
 | Mesh settings | Values every node reads — where the broker is, where the forge is, where the registry is |
 | Grants | Which consumer holds which resource from which provider, with the credential |
@@ -87,7 +87,7 @@ down.
 ## Reaching a capability on another node
-A node holds some capabilities and can reach the rest.
+A node hosts some capabilities and can reach the rest.
 At startup, a node asks every peer what it hosts. For anything hosted elsewhere it creates a
 local stand-in that forwards over the broker. For anything hosted both locally and elsewhere
@@ -103,8 +103,8 @@ restarts. Nothing re-discovers on a schedule.
 ## Names and reachability
-Nodes address each other by names that resolve on the mesh's own private network, not on whatever the
+Nodes address each other by names that resolve on the mesh's own overlay, not on whatever the
-underlying network provides. A node's mesh name is its private network address; its public name, if it
+underlying network provides. A node's mesh name is its overlay address; its public name, if it
 has one, is a separate fact used by things outside the mesh.
 Two lessons are embedded in that separation, both learned the expensive way. A name resolved
@@ -69,7 +69,7 @@ is what runs today.
 ## Supervision
-Services run under the machine's init system via a templated unit, one instance per module. It is
+Services run under the host's init system via a templated unit, one instance per module. It is
 a thin layer: the unit starts and stops a container group.
 Whether the mesh keeps this, drops the per-module layer, containerises the daemons, or writes
@@ -12,8 +12,8 @@ decisions:
 # Knowledge
 **The mesh keeps no knowledge store.** What it knows is what its modules answer, and the way a person
-or an agent asks is the mesh MCP server's tool list on the machine they sit at
+or an agent asks is the console's tool list on the machine they sit at
-([13 — The mesh MCP server](13-the-console.md)). This document used to describe two stores; it is rewritten
+([13 — The console](13-the-console.md)). This document used to describe two stores; it is rewritten
 because neither exists from the mesh's side, and an as-is document that describes what is gone is a
 brochure.
@@ -36,7 +36,7 @@ merge the forge announces and every ten minutes — and answers over the bus: wh
 written, one document whole, what a folder holds, and where the checkout stands, each naming the
 commit it read. Which repository it reads is a setting on its assignment; the module names no mesh.
-It is listed by the mesh MCP server beside every other tool, with a description that says to search the
+It is listed by the console beside every other tool, with a description that says to search the
 literal words of a symptom before forming a hypothesis. That is what
 [ADR 0025](../../02-DECISIONS/0025-the-design-record-is-read-not-copied.md) meant by *beside
 everything else*, in a mesh with no store to be beside
@@ -14,7 +14,7 @@ How the mesh is reached, and how anyone can tell what it is doing.
 ## Capabilities are the primary interface
-The mesh's primary interface is not a web dashboard. It is a set of **capabilities**, exposed to
+The mesh's primary interface is not a web console. It is a set of **capabilities**, exposed to
 a session and callable in language.
 A capability is contributed by a module and is available on any node, wherever it actually
@@ -56,7 +56,7 @@ the unit of one piece of software, because that is the only granularity the modu
 offers.
 This is the same failure [ADR 0001](../../02-DECISIONS/0001-mesh-brokers-nodes-host-agents-think.md)
-names for the platform core — "boundaries drawn by deployment accident rather than by domain" —
+names for the platform core — *boundaries drawn by deployment accident rather than by domain* —
 appearing outside it, at four times the scale. The core is being recomposed; the flat level is
 addressed in principle by
 [ADR 0009](../../02-DECISIONS/0009-modules-and-the-graph.md), which
@@ -46,7 +46,7 @@ scenario as one state.
 ## What it does not do, and why that matters
-**`place:` is refused.** A scenario can declare that a node-engine is placed on a machine; the
+**`place:` is refused.** A scenario can declare that a node host is placed on a machine; the
 lab names the gap and refuses rather than raising a scenario that silently lacks what it
 declared. Nothing can be placed because tier 0 does not exist yet.
@@ -25,7 +25,7 @@ have; nothing else can add to it.
 Five seats deliver a provision: the mesh's store delivers the relational database, the mesh's broker
 the message transport, the artifact-store seat the registry, and two more the package registry for
 one ecosystem and the git service. The remaining nine — the controller and catalogue seats, and the
-node-scope ones for the builder, the DNS port, the packet filter, intrusion prevention, the
+node-scope ones for the build machine, the DNS port, the packet filter, intrusion prevention, the
 private network, the resolver's configuration and the showcase — mark a role without answering for
 anything a consumer requires.
@@ -74,7 +74,7 @@ mesh carrying one from before the set existed says so.
 A module's repository is either a URL, recorded and cloned exactly as given, or a path on the forge
 holding the git seat, recorded as that path plus the seat. The clone URL is composed from wherever
-the holder runs at the moment of building, so the builder is never told an address that could
+the holder runs at the moment of building, so the build machine is never told an address that could
 go stale. Before this, a self-hosted forge's scheme, host and port were written into every module
 built from it, and moving the forge made every record stale at once — noticed when a rebuild failed
 to clone.
@@ -10,7 +10,7 @@ decisions:
  - 02-DECISIONS/0154-the-meshs-own-verbs-are-the-controller-seats-tools.md
 ---
-# The mesh MCP server, as it runs
+# The console, as it runs
 **The mesh's tools reach a person through a module the mesh assigned to their machine.** Since
 2026-09-30 a workstation that is a node can be assigned `mesh-console`; the mesh mints a bus account
@@ -22,36 +22,36 @@ endpoint. Nothing on the machine holds a credential a person had to carry.
 ## What it answers
 `initialize`, `tools/list`, `tools/call`, over HTTP, one JSON body per request, no session and no event
-stream. `tools/list` is what the running modules answered: every tool runner built on or after that day
+stream. `tools/list` is what the running modules answered: every tool runtime built on or after that day
-serves a `tools` verb for its module, and the mesh MCP server asks the catalogue for the roster and each module
+serves a `tools` verb for its module, and the console asks the catalogue for the roster and each module
 for its tools. A module that did not answer is named in the list's `_meta.notAnswering`. On the day it
 shipped that was 36 of 51 modules — those that serve no tools at all, and those whose rebuilt runtime the
 mesh records rather than rolls out — and 62 tools from the rest.
-`tools/call` reaches any tool by `<module>.<tool>`, listed or not. The mesh MCP server's grant is `*`, so what it
+`tools/call` reaches any tool by `<module>.<tool>`, listed or not. The console's grant is `*`, so what it
 may call is every tool on the mesh; its account may publish nothing else and subscribes nothing.
 ## The mesh's own verbs
 *Since 2026-09-30 evening ([ADR 0154](../../02-DECISIONS/0154-the-meshs-own-verbs-are-the-controller-seats-tools.md)).*
-The mesh MCP server asks the `mesh-controller` seat's `tools` verb beside the modules and lists every role's
+The console asks the `mesh-controller` seat's `tools` verb beside the modules and lists every role's
 tools as `<seat>.<verb>` — `mesh-controller.status`, `mesh-controller.push` and the other ten. A call
 to `<prefix>.<name>` reaches the seat when the prefix is a seat declaring that verb, and the module
-otherwise; `seat:<seat>.<verb>` says so outright. When the controller does not answer, the list
+otherwise; `seat:<seat>.<verb>` says so outright. When the control plane does not answer, the list
 names `mesh-controller (seat)` as not answering and carries the modules' tools regardless. The
 `mesh-controller` *module* is always named as not answering: it serves no module tools, only its seat's.
 ## Around it
 - **`invokes`** in a manifest is the grant. It is composed into the bus's user list exactly as a
-  person's account is; the mesh MCP server is the only module that declares it.
+  person's account is; the console is the only module that declares it.
 - **`module check <file|dir>…`** on the controller's binary judges a manifest with no mesh: the strict
  parse, every per-manifest problem, and the rules between the manifests given. It prints what it cannot
-  judge without a store rather than refusing. The mesh MCP server's own manifest was the first thing checked
+  judge without a store rather than refusing. The console's own manifest was the first thing checked
  with it, and the whole catalogue passes.
 - **The person's client remains.** `operator issue` and `mesh tools|call|mcp` with a credential file
  still work, for a machine that is not a node and for a mesh not yet able to assign anything.
-  `mesh tools --console <url>` goes through a running mesh MCP server with no credential; it is covered by the
+  `mesh tools --console <url>` goes through a running console with no credential; it is covered by the
  runtime repository's tests and was not exercised on the live mesh.
 ## What shipped bent
@@ -61,4 +61,4 @@ names `mesh-controller (seat)` as not answering and carries the modules' tools r
  operator did not pass. The rebuild-on-merge matched the URL anyway.
 - Modules whose upgrade policy is *record* — the forge among them — answered `tools` only once
  something pushed their rebuilt runtime; until then they are listed as not answering while still
-  callable. That is the policy doing what it says, not a fault of the mesh MCP server.
+  callable. That is the policy doing what it says, not a fault of the console.
@@ -17,7 +17,7 @@ a port or a bus credential of its own. Live since 2026-10-04, on all four machin
 ## The agent module on each machine
- **Writes the agent's managed directory**: the tool servers — the mesh MCP server as `mesh`, plus servers
+- **Writes the agent's managed directory**: the tool servers — the console as `mesh`, plus servers
  registered through the module — the mesh's settings, and the instruction file. The tool-server list
  is exclusive by the vendor's rule: a server not in it does not load on that machine.
 - **Keeps registered tool servers in its state**, one key per registration for every machine or for one;
@@ -46,7 +46,7 @@ a port or a bus credential of its own. Live since 2026-10-04, on all four machin
 One subscription account was adopted from the control node's own login on its first start; the other
 three machines, logged in to the same account with older logins, were bound to it without their logins
 being exchanged. A forced rotation reached all four machines within seconds. Two faults were found and
-fixed while it rolled out: a machine reporting an already-adopted account later was never bound, and a
+fixed during the rollout: a machine reporting an already-adopted account later was never bound, and a
 seat verb named with an underscore was refused by the builder.
 ## How it is checked
@@ -95,7 +95,7 @@ anyway, because a dependency can restart long after everything was applied.
 shape widens what a compromised controller can express, so
 [ADR 0029](../../02-DECISIONS/0029-a-network-is-a-shape-because-an-action-cannot-be-undone.md)
 records why this one is worth it: an `action` could create a network and **nothing could ever
-remove it**, because an action leaves no footprint the node-engine can undo. The vocabulary is nine.
+remove it**, because an action leaves no footprint the host can undo. The vocabulary is nine.
 **Three tasks in a row that were already possible.** Both were written from the design rather than
 from the code, which is the review's finding arriving in the plan: *a claim here is counted, not
@@ -128,7 +128,7 @@ does not say.**
 survive every step**. A data folder may move; it may never be lost.
 **One thing was found by asking this and is fixed**
-([ADR 0030](../../02-DECISIONS/0030-data-outlives-the-mesh-that-declared-it.md)): the node-engine deleted
+([ADR 0030](../../02-DECISIONS/0030-data-outlives-the-mesh-that-declared-it.md)): the host deleted
 a directory and everything under it when the directory stopped being declared, which happens when
 a module is unassigned or a manifest is edited to move a data folder — the exact operation this
 plan needs. A directory holding anything the mesh did not put there is now kept and reported.
@@ -340,7 +340,7 @@ once, and maintain for a year. The modules are the input; a person reads what on
 writes what it declares tomorrow.
 **It also changes what "safe" means for the system being retired.** A fix to it has to be safe on
-its own, because there is no careful walk to sequence it into: the thing is being switched off
+its own, because there is no careful rollout to sequence it into: the thing is being switched off
 by hand, not managed into retirement. A change needing three steps in the right order is a change
 that will be half-applied.
@@ -42,9 +42,9 @@ not the first one built** ([ADR 0016](../../02-DECISIONS/0016-the-lab.md)).
 | | **Bootstrap scenario** | **Full scenario** |
 |---|---|---|
-| Contains | virtual machines, the node-engine binary, a pinned foundation bundle | a complete mesh: forge, coordinator, delivery, modules |
+| Contains | virtual machines, the host binary, a pinned foundation bundle | a complete mesh: forge, coordinator, delivery, modules |
-| Verdict from | what the node-engine reports about the state it reconciled | a pipeline result ending in verify |
+| Verdict from | what the host reports about the state it reconciled | a pipeline result ending in verify |
-| Exercises | the node-engine and the foundation | the controller and everything above it |
+| Exercises | the node host and the foundation | the controller and everything above it |
 | Exists to | **develop the mesh** | **test what runs on it** |
 The bootstrap scenario is a **strict subset**: same virtualisation, same networking, same
@@ -350,7 +350,7 @@ from the existing system has run against any of it yet.
 ### A node is a system container
 An OS userspace with its own init, its own network interface, its own filesystem, sharing
-the lab machine's kernel.
+the host kernel.
 **A node's job is to run containers**, so modelling a node *as* an application container
 inverts the thing being modelled: it forces nested containers through a privileged daemon or
@@ -369,14 +369,14 @@ test file — when a question needs a kernel to answer it, or when the point is
 ### The network
-Two segments and a private network, because some module behaviour is only visible across a real
+Two segments and an overlay, because some module behaviour is only visible across a real
 network boundary:
 - **wan** — a published node holds an address here, and an authoritative resolver maps its
  name to it, so a public touchpoint is real enough to exercise routing, virtual hosts and
  certificates
 - **local** — behind translation, as a home network is
- **the private network** — the mechanism production uses; the mesh addresses peers by mesh name and
+- **the overlay** — the mechanism production uses; the mesh addresses peers by mesh name and
  never learns which segment anyone is on
 A node can be moved between segments or detached entirely, mid-test.
@@ -420,14 +420,14 @@ receipt written before it recorded a given fact, which claims nothing rather tha
 **The run rebuilds what it tests.** The suite consumes artifacts from other repositories, and an
 artifact rebuilt from memory is one rebuilt sometimes. A stale binary reporting success against
 rules that have since changed is the same fault wearing different clothes. This covers the module
-runtimes a bed's scenario stocks as well as the node-engine and the controller
+runtimes a bed's scenario stocks as well as the host and the control plane
 ([issue 075](../../04-ISSUES/075-a-stocked-runtime-image-is-never-rebuilt-by-the-run/00-report.md)):
 each is compared against the module's source and what it is built on, and rebuilt where older,
 missing or uncommitted. *How it is checked:* unit tests on what a bed stocks and when it is stale;
 a run with an image removed rebuilds it before the bed passes.
 **The general rule, which outlives this suite:** *silence and success must never look alike.*
-It is the same rule the node-engine follows about a service that does not exist
+It is the same rule the host follows about a service that does not exist
 ([ADR 0004](../../02-DECISIONS/0004-a-node-and-how-it-joins.md)) — absence must be distinguishable
 from a failure to answer — applied to coverage instead of to a machine.
@@ -472,7 +472,7 @@ runner needs is the one the mesh should keep.
 **Module verification becomes worth writing**, because it is the thing that gives a
 developer a verdict, not just a stricter deploy.
-**Host-borrowing ends.** Today's tooling starts providers on the machine's own init system and
+**Host-borrowing ends.** Today's tooling starts providers on the host's own init system and
 reads credentials from host paths, because there is nowhere else to put a mesh. Once there
 is, a workstation stops being collateral.
@@ -244,7 +244,7 @@ too thin. It carries three facts, and all three are load-bearing:
  carrier NAT; omitting it means mappings never expire, which no real gateway does.
 **`segments[].mtu`** — the largest packet the segment carries, defaulting to 1500. Lower values
-reproduce tunnelled and PPPoE paths. This matters because a private network adds its own header: a
+reproduce tunnelled and PPPoE paths. This matters because an overlay adds its own header: a
 tunnel over a 1400-byte path establishes a connection and then silently drops large packets,
 which is the shape of fault this whole effort exists to stop shipping.
@@ -297,7 +297,7 @@ The same machine, the same identity, three positions in one run: at home where i
 reach it directly, on a foreign network where it can only dial out and its apparent address
 belongs to a router it does not control, and asleep.
-Whether the private network survives that, re-forms, and is noticed to have changed endpoint is
+Whether the overlay survives that, re-forms, and is noticed to have changed endpoint is
 **observed**, never arranged
 ([ADR 0016](../../02-DECISIONS/0016-the-lab.md)).
@@ -347,13 +347,13 @@ assert:
 ```
 `module:` and `assert:` are meaningless in a bootstrap scenario and absent from one. A
-bootstrap scenario's verdict comes from what the node-engine reports about the state it reconciled,
+bootstrap scenario's verdict comes from what the host reports about the state it reconciled,
 not from an assertion runner — which is why assertion execution is second in the build order,
 not first.
 ## What a scenario deliberately cannot say
- **Private network addresses, the hub, peer configuration.** Outcomes, not inputs
+- **Overlay addresses, the hub, peer configuration.** Outcomes, not inputs
  ([ADR 0016](../../02-DECISIONS/0016-the-lab.md)).
 - **What a machine is in mesh terms** — server or workstation, its site, its names. Mesh
  configuration, established by the mesh.
@@ -541,7 +541,7 @@ cannot yet express.
 ### What is deliberately absent
-Nothing here mentions private network addresses, which node is the hub, who peers with whom, any name,
+Nothing here mentions overlay addresses, which node is the hub, who peers with whom, any name,
 or any certificate. Research 004 recorded all of those for this topology, and **a scenario must
 not state them** ([ADR 0016](../../02-DECISIONS/0016-the-lab.md)): they
 are what the mesh does, and a scenario that supplied them would be certifying its own work.
@@ -634,7 +634,7 @@ is the one real absence, and it is exactly the double-NAT case.
 - **`user` and `edge` profiles have no scenario.** A lab machine is always privileged, so the
  two profiles that exist for unprivileged and phone-like participation cannot be exercised.
-  Either the lab grows a way to run the node-engine unprivileged, or those profiles are developed
+  Either the lab grows a way to run the host unprivileged, or those profiles are developed
  against something that is not a virtual machine. This is the largest gap.
 - **Where `place:` gets its artifacts from.** Before the mesh is self-hosting these come from
  outside; afterwards from the mesh itself. The declaration should not have to care, which
@@ -81,7 +81,7 @@ was done* is not evidence.
 Worth stating, because it looks like an exception and is not.
-The node-engine is the one thing installed by hand on a machine
+The node host is the one thing installed by hand on a machine
 ([research 006](../../01-RESEARCH/006-mesh-from-scratch/code-skeleton.md)): everything else
 arrives through it. The lab is the same shape on a workstation — installed once, by hand, and
 then everything about the mesh is developed inside it.
@@ -24,7 +24,7 @@ decisions:
  - 02-DECISIONS/0005-the-node-host.md
 ---
-# The node-engine
+# The node host
 Tier 0. The one thing ever installed by hand, and the only thing that changes a machine.
@@ -33,10 +33,10 @@ Tier 0. The one thing ever installed by hand, and the only thing that changes a
 A **statically linked binary that requires nothing to be present** — copy it onto a machine and
 run it, and that is the whole installation
 ([ADR 0005](../../02-DECISIONS/0005-the-node-host.md)). Written in Go, because the
-job is system-level and because the node-engine shares no code with any other tier.
+job is system-level and because the host shares no code with any other tier.
 A single binary with one job: **apply declared state on this machine**
-([ADR 0005](../../02-DECISIONS/0005-the-node-host.md)). Private network
+([ADR 0005](../../02-DECISIONS/0005-the-node-host.md)). Overlay
 membership, packet filtering, packages, services, containers and filesystems are not six
 concerns it carries; they are six instances of the one.
@@ -130,7 +130,7 @@ the link; never asked downward.
 - It has no listening surface.
 - **It does not manage its own unit.** It manages `service` resources and its own unit is one —
  the temptation is obvious and it ends with a host stopping itself half way through an apply,
-  leaving a machine with nothing running to fix it. The installation owns the node-engine; the node-engine owns
+  leaving a machine with nothing running to fix it. The installation owns the host; the host owns
  everything else.
 **How it is installed, enrolled, run, upgraded and retired is
@@ -141,36 +141,36 @@ is the component; that one is what happens to it.
 *2026-09-22, [ADR 0100](../../02-DECISIONS/0100-a-node-in-use-is-adopted-before-it-is-converged.md).* A declaration says whether the node is adopted, and which of its
 modules have been **taken**. *Found* is a file at a declared path, or a container at a declared
-name, that the node-engine's store has no record of writing. On an adopted node the node-engine keeps what it
+name, that the host's store has no record of writing. On an adopted node the host keeps what it
 found for any module not yet taken: it records a found file's original content before anything
 else, and it reports the file or container as held — a report that says what it holds, so an
 adopted node never reads as converged. Once the module is taken, its resources converge like any
 other. What is held is never removed, even when its module is unassigned, and a held file or
 container that changes while held is reported as changed by something else, not reverted or
-restarted. The node-engine also
+restarted. The host also
 converges a new resource, the **opening** — a port made reachable through the firewall it found
 ([08-connectivity](08-connectivity.md)) — and reports which firewall it found. This is the
-companion the node-engine's ownership rule needed: *never touch what you did not create, unless adoption
+companion the host's ownership rule needed: *never touch what you did not create, unless adoption
 made it yours — and while the node is adopted, not until its module is taken.* *How it is
-checked:* unit tests hold the node-engine to keeping a found file and container, converging them once
+checked:* unit tests hold the host to keeping a found file and container, converging them once
 taken, never removing a held file and reporting one that changed; the adoption bed asserts a found
 file byte for byte unchanged until its module is taken.
-**What the node-engine says of a found container, and what it removes** — revision, 2026-10-01
+**What the host says of a found container, and what it removes** — revision, 2026-10-01
 ([ADR 0163](../../02-DECISIONS/0163-taking-a-module-over-is-a-comparison.md)). Its report of a held
 container carries the image and the image's creation date, the networks it is on and the other
-containers on each, its mounts and its published ports — the facts a take compares. The node-engine compares
+containers on each, its mounts and its published ports — the facts a take compares. The host compares
 every field it writes before calling a container current, volumes and paths included; its record keeps
 a resource's former targets, removes a container or file it wrote under a name the declaration no
 longer names, never removes what was found, and reports what runs on the machine that it neither
 wrote nor holds. *How it is checked:* ADR 0163's table.
-**What the node-engine joins, keeps and raises for a take** — revision, 2026-10-02
+**What the host joins, keeps and raises for a take** — revision, 2026-10-02
 ([ADR 0163](../../02-DECISIONS/0163-taking-a-module-over-is-a-comparison.md), rules 4, 6 and 7). A
 container may name networks it also joins once it runs — the found network a per-machine setting keeps
 for a taken container while a neighbour still resolves it there; joined after the run, part of the
 container's spec, refused when it cannot be joined. A declaration may name the modules the mesh left
-out of it because a stored setting cannot compose with the module's definition: the node-engine keeps what it
+out of it because a stored setting cannot compose with the module's definition: the host keeps what it
 wrote and holds for a left-out module and says so, where absence used to read as removal. And genesis
 raises the bootstrap forge under the forge module's container name, with the module's image digest and
 its data directory, so the module holds it by the found rule; the network is the one difference a take
@@ -179,7 +179,7 @@ host test keeps a left-out module's record and hold and removes an absent module
 holds the installer's constants to the module's manifest where the catalogue is checked out beside it.
 **What filters the machine, and the found firewall kept retired** — revision, 2026-10-02
-([ADR 0168](../../02-DECISIONS/0168-a-converged-machine-is-filtered-by-the-mesh-alone.md)). The node-engine
+([ADR 0168](../../02-DECISIONS/0168-a-converged-machine-is-filtered-by-the-mesh-alone.md)). The host
 reports, with every apply, every table and legacy chain that refuses traffic and whose it reads it as —
 the mesh's, the found firewall's, the container runtime's own, a ban, or other — and, converged, whether
 the firewall it was found with is in force and who retired it. It retires that firewall on every
@@ -191,14 +191,14 @@ step was skipped. *How it is checked:* ADR 0168's table.
 keeps its mode and owner, a unit present with no record keeps its state and boot setting, a
 container that would mount found data is not created, and an action run in a held container
 waits for the cutover. **A file the machine shares is written into, never over**
-([ADR 0102](../../02-DECISIONS/0102-the-mesh-writes-into-a-shared-file-never-over-it.md)): the node-engine sets the mesh's keys in the object already there,
+([ADR 0102](../../02-DECISIONS/0102-the-mesh-writes-into-a-shared-file-never-over-it.md)): the host sets the mesh's keys in the object already there,
 keeps every other key, adds its members to a list already there rather than replacing it,
 records what each of its keys held and which members it added, and gives them back when the
 file is undeclared. Such a file replaces nothing, so it is never held. And on any node, before
-the node-engine writes over a file it has no record of making, it keeps the original once and names
+the host writes over a file it has no record of making, it keeps the original once and names
 where; if it cannot keep it, it does not write. A service that re-reads
 its configuration is **reloaded** for what it names in `reload-on`, never restarted. *How it is
-checked:* unit tests hold the node-engine to each of these, and the adoption bed asserts the runtime's
+checked:* unit tests hold the host to each of these, and the adoption bed asserts the runtime's
 own settings survive adoption and a container without a restart policy keeps running.
 ## Where a declaration comes from
@@ -208,7 +208,7 @@ One behaviour, two sources
 | Situation | Source |
 |---|---|
-| no mesh reachable | `foundation.lock` — the pinned bundle the node-engine carries |
+| no mesh reachable | `foundation.lock` — the pinned bundle the host carries |
 | mesh reachable | the controller, over the link |
 **The first node is not a different kind of node.** It is a node whose mesh is not up yet. It
@@ -216,23 +216,23 @@ applies the bundle it carries, the controller comes up on top of it, and from th
 takes declarations like every other node. Its specialness is temporary and self-erasing.
 **A joining node does the minimum to be reachable and nothing else** — an identity, an address,
-one peer — and then stops deciding. It does not compute the private network; it needs one peer to reach
+one peer — and then stops deciding. It does not compute the overlay; it needs one peer to reach
 the mesh, and the full peer set arrives derived.
 ## What a declaration is
 Settled by [ADR 0005](../../02-DECISIONS/0005-the-node-host.md).
-**JSON**, because the node-engine has no dependencies to spend and the standard library carries no
+**JSON**, because the host has no dependencies to spend and the standard library carries no
 YAML. **An ordered list of typed resources**, each with a stable identity — the order is stated
-rather than derived, because deriving it would be the node-engine deciding the thing most likely to
+rather than derived, because deriving it would be the host deciding the thing most likely to
 differ from what the controller intended.
 **Unknown is refused, never skipped.** An unknown version, type or field refuses the whole
 declaration. A host that skipped what it did not understand would apply most of it and report
 success.
-**Complete for what the node-engine owns, and only that.** It removes what it previously applied and
+**Complete for what the host owns, and only that.** It removes what it previously applied and
 is no longer declared — a fact it holds, from the store, rather than an inference — and never
 removes anything it did not create.
@@ -243,11 +243,11 @@ without one, applying the bundle it carries, has nothing to check against.
 Staged so each stage is verifiable in the lab before the next exists.
-**1 — profile and inventory.** The node-engine runs on a machine, detects what it can do, and reports
+**1 — profile and inventory.** The host runs on a machine, detects what it can do, and reports
 what it is. No controller, no declarations, no network. Verifiable immediately: the lab's
 `place:` gains its first implementation, and a raised scenario finally contains something.
-**2 — apply, from the bundle.** The node-engine applies `foundation.lock` with no mesh present. This is
+**2 — apply, from the bundle.** The host applies `foundation.lock` with no mesh present. This is
 the first node's path, and it is the claim the skeleton's Move 1 rests on and has never proved:
 that one host can raise the foundation alone.
@@ -260,7 +260,7 @@ ready; the current bundle simply does not. **All of them are built:**
 |---|---|---|
 | `directory`, `file` | **built** | no machine dependency at all |
 | `service` | **built** | running/stopped **and** enabled/disabled at boot — a unit started but not enabled stops being true at the next reboot |
-| `package` | **built** | present, never upgraded, and **never uninstalled** — the node-engine cannot know what else needs it, so dropping one is *forgotten*, not *removed* |
+| `package` | **built** | present, never upgraded, and **never uninstalled** — the host cannot know what else needs it, so dropping one is *forgotten*, not *removed* |
 | `container` | **built** | pinned by digest ([ADR 0006](../../02-DECISIONS/0006-the-substrate-and-the-control-plane.md)); identified by a label carrying a digest of the declaration that made it, because a runtime normalises what it is given and that is indistinguishable from drift |
 | `action` | **built** | bundle-only ([ADR 0005](../../02-DECISIONS/0005-the-node-host.md)); verify is mandatory and is the idempotency check as well as the read-back |
@@ -285,7 +285,7 @@ unqualified name still means *my own*, so the common case reads as it always did
 **An action's verify is the definition of what the action is for**, and the action's own idea of
 being finished must be the same one. *Written 2026-08-31, after this went wrong.* If an action
 waits on one test and its verify reads back another, the two can disagree — and then the action
-succeeds into a state its own verify rejects. The node-engine says so accurately and uselessly: *the
+succeeds into a state its own verify rejects. The host says so accurately and uselessly: *the
 action ran without error and its own verify still fails.* It is intermittent, it reads as a slow
 machine, and the remedy people reach for is a longer timeout, which cannot help.
 [04-ISSUES/017](../../04-ISSUES/017-an-action-succeeded-into-a-state-its-verify-rejects/00-report.md)
@@ -323,7 +323,7 @@ Each decision above owes a test:
 | Decision | What asserts it |
 |---|---|
-| 0037 — the node-engine never queries the mesh database | no database client in the dependency tree; a dependency-direction lint failing on an upward import |
+| 0037 — the host never queries the mesh database | no database client in the dependency tree; a dependency-direction lint failing on an upward import |
 | 0038 — one behaviour, two sources | the same code path raises a first node and joins a second |
 | 0039 — a node holds no shared credential | a raised node's store contains no credential to any service |
 | 0036 — disconnection is a situation | a node cut off and returned reconciles without being re-adopted |
@@ -366,7 +366,7 @@ nobody can write against without reading the code.*
 | `overlay` | the private network can be joined |
 | `graphical-session` | a display server **is running** — state |
 | `seat` | hardware where one **could** run — and assignment needs this one, not the row above |
-| `privileged` | the node-engine can change the machine |
+| `privileged` | the host can change the machine |
 **`seat` and `graphical-session` are the pair worth reading twice**, because collapsing them is
 the obvious economy and it is wrong in both directions: a machine with a seat and no session can
@@ -379,7 +379,7 @@ A version string proves a binary is on disk, which
 records as false in the way that matters: the package was installed and the daemon was not
 running.
-**Never reported and reported nothing stay different.** One machine has not run the node-engine yet; the
+**Never reported and reported nothing stay different.** One machine has not run the host yet; the
 other ran it and can do nothing. Both refuse everything that requires a capability, and the
 remedies are not remotely alike.
@@ -391,10 +391,10 @@ reported to be distinguishable from one that reported an empty list.*
 - **Whether one host can raise the foundation alone.** Move 1 assumes it. Stage 2 tests it, and
  if it is false the tier boundary moves.
- **What the node-engine carries versus what it finds.** It manages `wg`, `nft`, `pacman`, `docker`;
+- **What the host carries versus what it finds.** It manages `wg`, `nft`, `pacman`, `docker`;
  it does not contain them, and how it obtains one it lacks is undecided —
  [04-ISSUES/007](../../04-ISSUES/007-an-installed-package-is-not-a-capability/00-report.md).
- **Six vocabularies.** Zero dependencies, but the node-engine must still know what a peer, a rule, a
+- **Six vocabularies.** Zero dependencies, but the host must still know what a peer, a rule, a
  package, a unit, a container and a dataset *are*. Nothing has measured that surface, and it is
  the residue of the question [`host-size.md`](../../01-RESEARCH/006-mesh-from-scratch/host-size.md)
  answered.
@@ -433,7 +433,7 @@ of the reason to manage a machine.
  otherwise, which would silently remove every group that makes a login able to use the machine.
  A machine's own groups are not the mesh's to know about.
 - **An archive is pinned by digest, checked before a single file is written.** This is the one
-  place the node-engine reaches out on its own — everywhere else it holds one outbound connection and
+  place the host reaches out on its own — everywhere else it holds one outbound connection and
  fetches nothing — so the only thing making those bytes safe to unpack is that they hash to what
  was declared.
 - **An entry naming a path outside the archive is refused, not sanitised.** Rewriting it to land
@@ -443,31 +443,31 @@ of the reason to manage a machine.
  silently incomplete.
 **A partial host does archives and refuses users**: an archive needs a filesystem and a way to
-fetch; a user needs a user database the node-engine is allowed to write.
+fetch; a user needs a user database the host is allowed to write.
 ## A machine becomes the last thing it was told
 Every declaration is complete, so applying an old one is never wrong, only wasted — and under a
 flurry of pushes a machine spent minutes becoming things the mesh had moved past
 ([issue 031](../../04-ISSUES/031-a-machine-becomes-each-thing-it-was-told-in-turn/00-report.md)).
-So the node-engine looks at what is already waiting before it applies anything: it holds a small window
+So the host looks at what is already waiting before it applies anything: it holds a small window
 of unacknowledged declarations, applies the newest, and sets the rest aside — each **reported as
 superseded**, naming the one applied instead, because silence would read as a machine that
 ignored an instruction and "applied" would be a lie. Applying stays one at a time; only seeing
 is not. **Checked** by the link's unit tests on the drain, and by the genesis bed's settle wait,
 which counts on a node catching up to the newest declaration rather than the oldest.
-## The node-engine delivers its own successor
+## The host delivers its own successor
-*2026-09-29, from a change to the node-engine that could reach no machine —
+*2026-09-29, from a change to the host that could reach no machine —
 [issue 142](../../04-ISSUES/142-the-host-is-the-one-thing-the-mesh-does-not-deliver/00-report.md),
 settled by [ADR 0141](../../02-DECISIONS/0141-the-host-delivers-its-own-successor.md).*
-A merge builds every changed module and the controller, and the result reaches the machines running
+A merge builds every changed module and the control plane, and the result reaches the machines running
-it with nobody asking. The node-engine was the exception: not a build target, named by no declaration, and
+it with nobody asking. The host was the exception: not a build target, named by no declaration, and
 identical on every machine because somebody had copied it there.
-The supervision needed for this was already right. A clean exit from the node-engine means it has stood aside,
+The supervision needed for this was already right. A clean exit from the host means it has stood aside,
 and the launcher's next turn runs whatever is on disk. Consecutive failed starts are counted, a
 rollback happens at the limit, and a second failure halts with the machine named rather than the binary.
 What was missing was smaller than it looked: nothing told the running host a successor was waiting, and
@@ -503,13 +503,13 @@ that runs.
 ## A service is still running a moment later, 2026-10-02
 [ADR 0184](../../02-DECISIONS/0184-a-service-the-mesh-asked-to-run-is-still-running-a-moment-later.md).
-The node-engine has always read a unit back after acting on it, because a service manager accepting a
+The host has always read a unit back after acting on it, because a service manager accepting a
 command says the transaction was accepted and nothing about the process. The read raced the failure:
 a daemon that refuses the configuration the mesh just wrote exits a fraction of a second after the
-manager returns, and one look sees it alive. So the node-engine looks twice, with a pause between, and a
+manager returns, and one look sees it alive. So the host looks twice, with a pause between, and a
 unit that was running and is not any more fails its resource by name. A unit still coming up reads
 as running at both looks and is accepted; a service asked to stop is not waited on.
 No command for this reaches a machine. A module declaring *how to test my configuration* was weighed
-and refused: the link carries no actions, and a verification command is one. The node-engine is checking
+and refused: the link carries no actions, and a verification command is one. The host is checking
 the state it was told to establish, which is what it is for. *How it is checked:* ADR 0184's table.
@@ -26,7 +26,7 @@ This document defines it. It does **not** design the contexts inside it; those a
 > **The controller is everything that needs to know about more than one node.**
 That is the whole test, and it is not arbitrary — it follows from
-[ADR 0005](../../02-DECISIONS/0005-the-node-host.md). The node-engine applies and
+[ADR 0005](../../02-DECISIONS/0005-the-node-host.md). The host applies and
 does not decide *because deciding needs knowledge the machine does not have*. So the line falls
 exactly there:
@@ -35,11 +35,12 @@ exactly there:
 | write this file, with this content, with this mode | the **host** — one machine |
 | which nodes should run the store | the **controller** — needs every node |
 | is this unit running | the **host** — one machine |
-| which peers belong in this node's private network | the **controller** — needs every node |
+| which peers belong in this node's overlay | the **controller** — needs every node |
 | what does this machine have installed | the **host** reports; the controller **records** |
 | has this node been unreachable for a week | the **controller** — nobody else is watching |
-A useful consequence: **anything a single machine could answer alone is not the controller's.** If it needs no second node, putting it here is a mistake, and the tier rule will not
+A useful consequence: **anything a single machine could answer alone is not the control
 plane's.** If it needs no second node, putting it here is a mistake, and the tier rule will not
 catch it because the dependency direction is still correct.
 ## What is inside it
@@ -52,10 +53,10 @@ each one earning its place by the test above rather than by being ours:
 |---|---|---|
 | **inventory** | nodes, modules, assignments, versions | that *is* the mesh-wide fact |
 | **config** | settings, secrets, and deriving them onto nodes | it derives **onto nodes** |
-| **connectivity** | private network, resolution, exposure, filtering, certificates — **specified in full in [`08-connectivity.md`](08-connectivity.md)** | who peers with whom; which node is reachable |
+| **connectivity** | overlay, resolution, exposure, filtering, certificates — **specified in full in [`08-connectivity.md`](08-connectivity.md)** | who peers with whom; which node is reachable |
 | **provisioning** | resource grants between modules | consumer and provider may be on different nodes |
 | **delivery** | source to artifact to node | it targets nodes |
-| **observability** | health, logs, metrics, conditions | *unreachable for a week* is nobody else's to notice |
+| **observability** | health, logs, metrics, alerts | *unreachable for a week* is nobody else's to notice |
 | **identity** | agents, humans, services, authorisation | credentials follow an agent's node bindings and modality |
 | **api** | the one interface every surface speaks to | — it is an interface, not a context |
@@ -96,7 +97,7 @@ because each one alone reads like a detail:
 | | |
 |---|---|
-| [ADR 0005](../../02-DECISIONS/0005-the-node-host.md) | the node-engine never queries the mesh database |
+| [ADR 0005](../../02-DECISIONS/0005-the-node-host.md) | the host never queries the mesh database |
 | [ADR 0004](../../02-DECISIONS/0004-a-node-and-how-it-joins.md) | a node holds its own identity **and nothing else** — the shared database credential every node carries today is the exposure this exists to remove |
 | [ADR 0008](../../02-DECISIONS/0008-a-context-owns-its-store.md) | a context is granted only what it **exclusively** owns: no shared writes, no read-only roles |
 | [ADR 0006](../../02-DECISIONS/0006-the-substrate-and-the-control-plane.md) | there is no single mesh database, and nothing reads one |
@@ -173,8 +174,8 @@ volume genuinely argues against a relational store.
 ## What it is not
- **Not the thing that changes machines.** It decides; the node-engine applies. It never reaches into a
+- **Not the thing that changes machines.** It decides; the host applies. It never reaches into a
-  node except through the node-engine.
+  node except through the host.
 - **Not a surface.** Tier 3 is how people and agents reach it. It has one interface; the
  surfaces are what speak to that interface.
 - **Not the foundation.** It *runs on* tier 1 — PostgreSQL, LavinMQ, an OCI registry
@@ -191,7 +192,7 @@ module needs, granted the same way.
 That is the circularity the tiers exist to resolve rather than hide: the controller cannot
 provision its own database, because it is not running yet. So its **store** is raised from the
-bundle the node-engine carries, before there is a controller to ask
+bundle the host carries, before there is a controller to ask
 ([ADR 0004](../../02-DECISIONS/0004-a-node-and-how-it-joins.md),
 [research 011](../../01-RESEARCH/011-the-module-graph/worked-provider.md)).
@@ -42,9 +42,10 @@ gap applied: the word was load-bearing and unpinned.
 > **The foundation is what the controller consumes and cannot grant itself.**
-Every module that needs a database asks the controller's provisioning for one. The controller needs a database too — and it cannot ask itself, because it is not running yet. That
+Every module that needs a database asks the controller's provisioning for one. The control
 plane needs a database too — and it cannot ask itself, because it is not running yet. That
 circularity is not an awkwardness to work around; it *is* the definition. Anything on the wrong
-side of it must be raised some other way, and the other way is the bundle the node-engine carries
+side of it must be raised some other way, and the other way is the bundle the host carries
 ([ADR 0004](../../02-DECISIONS/0004-a-node-and-how-it-joins.md)).
 The test, applied:
@@ -102,7 +103,7 @@ cannot obtain it* is.
 ## What the foundation is not
- **Not tier 0.** The node-engine raises the foundation; it is not part of it. The node-engine carries the
+- **Not tier 0.** The host raises the foundation; it is not part of it. The host carries the
  declaration that brings the foundation up, and depends on nothing.
 - **Not the controller.** These are services with no knowledge of the mesh. A store does not
  know what a node is.
@@ -150,9 +151,9 @@ foundation exists to start, and it is in the bundle for the same reason they are
 to fetch it with yet. It also carries seven actions, a package and a service.
 **Why pinned:** the bundle is applied when no mesh exists, so nothing can resolve a version, ask
-a registry, or check a constraint. What the node-engine carries must already be exact.
+a registry, or check a constraint. What the host carries must already be exact.
-**Why references and not payload:** the bundle names images by **digest** and the node-engine fetches
+**Why references and not payload:** the bundle names images by **digest** and the host fetches
 them ([ADR 0006](../../02-DECISIONS/0006-the-substrate-and-the-control-plane.md)). A first node is
 a real machine with a network; the sealed case is the lab, and the lab places images itself.
@@ -166,7 +167,7 @@ up ([ADR 0088](../../02-DECISIONS/0088-the-foundation-filters-before-anything-li
 default, keep loopback, replies, ping, ssh, the bus and the registry, and the container runtime's
 networks through the forward chain. It is written into the same table the filter module derives,
 so that module replaces it wholesale once it can. Until it does, the machine admits nothing else —
-not the private network hub's port, which is derived from the hub's endpoint — so the filter module is
+not the overlay hub's port, which is derived from the hub's endpoint — so the filter module is
 assigned to the control-node before a hub is placed there, as genesis does; a lab bed that raises
 the foundation without genesis must do the same, and says so by waiting for the hub's port in the
 ruleset the machine loaded. **Checked** by the installer's bundle test (order and rules) and by
@@ -226,7 +227,7 @@ is a *package*, not a container.
 already has one keeps it. On a machine with none, the controller names the package, because
 what it is called differs per system. It is:
- what the node-engine's capability detection already reports, and the first use of that report by
+- what the host's capability detection already reports, and the first use of that report by
  something other than a person;
 - **adopted rather than installed** when the machine already has one with configuration somebody
  chose ([research 012](../../01-RESEARCH/012-the-minimum-viable-node/00-overview.md));
@@ -237,19 +238,21 @@ So the bootstrap uses four shapes: **package**, **container**, **service** and *
 *counted from `foundation-first-node.lock`, which is the only bundle there is*. It had said six,
 adding `file` and `directory`, which this bootstrap never asks for.
-All four are built, as are the node-engine's other five
+All four are built, as are the host's other five
 ([`05-the-node-host.md`](05-the-node-host.md) stage 2), so nothing in this bootstrap is blocked
-on the node-engine any longer — which is the claim that mattered, and it was true either way.
+on the host any longer — which is the claim that mattered, and it was true either way.
 **Steps 2 and 3 happen before there is a mesh to do them**, which is why provisioning is part of
 the bootstrap rather than a service consumers use later. They are **actions** the bundle
-declares and the node-engine runs
+declares and the host runs
-([ADR 0005](../../02-DECISIONS/0005-the-node-host.md)) — so the node-engine's vocabulary grows by one shape rather than by one resource type per foundation service.
+([ADR 0005](../../02-DECISIONS/0005-the-node-host.md)) — so the
 host's vocabulary grows by one shape rather than by one resource type per foundation service.
 ## Open
 - ~~**Whether identity is the fifth.**~~ **Closed 2026-08-31** by
-  [ADR 0031](../../02-DECISIONS/0031-the-control-plane-authenticates-nobody.md): the controller delegates authentication to nothing, so identity is an ordinary module. With the object
+  [ADR 0031](../../02-DECISIONS/0031-the-control-plane-authenticates-nobody.md): the control
  plane delegates authentication to nothing, so identity is an ordinary module. With the object
  store gone ([ADR 0028](../../02-DECISIONS/0028-the-substrate-supplies-the-control-plane-and-nothing-else.md))
  the foundation is three, and no member is conditional.
 - ~~**Whether the bus must precede the controller.**~~ **Resolved** by
@@ -270,11 +273,11 @@ declares and the node-engine runs
 - ~~**Whether the host can do step 2.**~~ **Resolved** by
  [ADR 0005](../../02-DECISIONS/0005-the-node-host.md). A service
  running on this machine is part of this machine, so the scope was never in question — the real
-  question was whether the node-engine must learn what a database is, and it must not. The bundle
+  question was whether the host must learn what a database is, and it must not. The bundle
-  declares an **action**; the node-engine runs it and verifies it, and what a database means stays with
+  declares an **action**; the host runs it and verifies it, and what a database means stays with
  the module that provides one.
 - **Whether one host can raise all three.** The claim under stage 2 of
-  [the node-engine](05-the-node-host.md), never proved. If it is false, the tier boundary moves.
+  [the node host](05-the-node-host.md), never proved. If it is false, the tier boundary moves.
 - ~~**The vault as the fourth piece.**~~ **Closed 2026-09-21** by
  [ADR 0085](../../02-DECISIONS/0085-a-secret-is-a-provision.md) as amended: genesis makes the
  operator key before anything is minted, raises the store and broker with credentials it made
@@ -322,11 +325,11 @@ username. Recorded in ADR 0004 as the fifth thing a token carries.
 The bundle carries three images and one of them is the controller, *because there is nothing to fetch
 it with yet*. That reasoning holds and its conclusion changes: the controller is carried as a **binary**
 reference rather than an image reference, pinned by digest exactly as before. Nothing about the bundle's
-shape moves — it names a thing and the node-engine fetches it — and the container runtime stops being something
+shape moves — it names a thing and the host fetches it — and the container runtime stops being something
-genesis must raise before the controller can exist. It still raises one, for the store and the broker,
+genesis must raise before the control plane can exist. It still raises one, for the store and the broker,
 which is where somebody else's software belongs.
-The mesh's own components — the node-engine, the controller, the catalogue, the builder, the vault — are
+The mesh's own components — the host, the controller, the catalogue, the builder, the vault — are
 delivered as binaries into directories named for their versions, by the mechanism
 [ADR 0141](../../02-DECISIONS/0141-the-host-delivers-its-own-successor.md) describes. Third-party
 software stays a container. The split is not about isolation; it is about who built the thing.
@@ -7,25 +7,14 @@ code:
  - mesh-controller internal/identity/authority.go
  - mesh-controller cmd/mesh-controller/plan.go (the names the roster publishes)
  - mesh-controller internal/catalogue/zones.go (the zones a module answers, ADR 0199)
-  - mesh-controller internal/catalogue/seats.go (mesh-dns-resolver, node-hostname, node-uplink)
+  - mesh-controller internal/catalogue/seats.go (mesh-dns-resolver, node-hosts-file)
-  - mesh-controller internal/catalogue/resolve.go (one owner per path, a rendered fact's included, ADR 0223)
+  - mesh-catalog modules/dnsmasq (the mesh's one resolver)
-  - mesh-controller cmd/mesh-controller/holdings.go (the holders of a replicated seat, ADR 0223)
+  - mesh-catalog modules/resolv-conf (what a node asks)
-  - mesh-controller internal/catalogue/roster.go (each replicated seat's holders, for a template)
+  - mesh-catalog modules/hosts (a node's /etc/hosts)
  - mesh-catalog modules/dnsmasq (the mesh's resolvers)
  - mesh-catalog modules/networkmanager, modules/systemd-networkd (what a node asks, written by its uplink's holder)
  - mesh-catalog modules/route-proxy (the public issuer named by the proxy, ADR 0226)
  - mesh-controller internal/overlay/generator.go (the private network's module, assigned by its own name, ADR 0226)
  - mesh-catalog modules/hostname (a node's /etc/hostname and /etc/hosts)
  - mesh-controller internal/catalogue/node_resolver.go (a machine's own resolver, ADR 0247)
  - mesh-catalog modules/systemd-resolved (a machine's own resolver, ADR 0247)
  - mesh-host internal/identity/serving.go
-  - mesh-host internal/apply (the service that reflects a rule set; a whole file handed to its new owner)
+  - mesh-host internal/apply (the service that reflects a rule set)
-updated: 2026-10-07
+updated: 2026-10-03
 decisions:
  - 02-DECISIONS/0247-a-machine-with-a-vpn-client-routes-names-by-domain-through-a-resolver-of-its-own.md
  - 02-DECISIONS/0226-the-private-network-is-assigned-by-its-own-name-and-the-proxy-names-its-public-issuer.md
  - 02-DECISIONS/0223-the-mesh-has-two-resolvers-and-a-machine-lists-only-them.md
  - 02-DECISIONS/0220-what-a-machine-asks-needs-its-uplink-held-and-the-retired-resolver-pieces-go.md
  - 02-DECISIONS/0199-a-module-that-answers-names-declares-its-zone-and-a-nodes-hosts-file-is-one-modules.md
  - 02-DECISIONS/0196-a-node-asks-the-meshs-resolver-first-and-a-public-one-only-when-it-is-silent.md
  - 02-DECISIONS/0194-the-mesh-has-one-resolver-and-every-node-asks-it-for-the-meshs-names.md
@@ -65,7 +54,7 @@ decisions:
 # Connectivity
 One of [the controller's](06-the-controller.md) ten contexts, and the one with the most
-moving parts: **private network, resolution, exposure, filtering, certificates.**
+moving parts: **overlay, resolution, exposure, filtering, certificates.**
 It is written as a whole because the five are one design. They share inputs, they must agree, and
 every one of them today is computed in a different place by a different module from a different
@@ -78,10 +67,10 @@ node* — to each responsibility:
 | | needs to know | whose |
 |---|---|---|
-| **private network** — who peers with whom, at what address | **every node**, and which of them can be dialled | controller |
+| **overlay** — who peers with whom, at what address | **every node**, and which of them can be dialled | controller |
 | **resolution** — which name is which node | **every node** | controller |
 | **exposure** — which public name reaches which container | **which node is publicly reachable** ([ADR 0007](../../02-DECISIONS/0007-connectivity.md)) | controller |
-| **filtering** — which port is open, to whom | what is assigned here, and the private network's shape | controller decides, host applies |
+| **filtering** — which port is open, to whom | what is assigned here, and the overlay's shape | controller decides, host applies |
 | **certificates** — who may present which name | which name belongs to which node | controller |
 **Not one of the five can be answered by a machine on its own.** That is the whole reason this is
@@ -127,18 +116,10 @@ settings, and absent from a machine nobody gave it to.
 |---|---|---|---|
 | the WireGuard one | a private network, **and the mesh's own addressing** | | *the* private network, one per node |
 | the names one | name resolution | the mesh's own addressing | |
-| ~~`networking`~~ | | both of the above | |
+| `networking` | | both of the above | |
 > **Amended 2026-10-06, by [ADR 0226](../../02-DECISIONS/0226-the-private-network-is-assigned-by-its-own-name-and-the-proxy-names-its-public-issuer.md).** The names
 > became a fact (ADR 0199), leaving `networking` a module that required one other and nothing else,
 > assigned on every machine. It is retired: every machine is assigned the WireGuard module —
 > `mesh-wireguard` — by its own name, and genesis does the same. Choosing another VPN is still
 > assigning it instead; the claim still refuses two. A module the controller stops shipping is
 > retired at its next start, and kept while any machine is assigned it. The paragraphs below record
 > why the bundle was built.
 **Three rather than one, because WireGuard is one VPN of several.** Naming the module after the
-job — `networking` — and putting WireGuard inside it is the retired "flavor" idea wearing a
+job — `networking` — and putting WireGuard inside it is the retired *flavor* idea wearing a
 generic name: the second VPN has nowhere to go. So a module is named for what it *is* and declares
 what it *does*, and `networking` is the third row — requirements and no files
 ([ADR 0009](../../02-DECISIONS/0009-modules-and-the-graph.md)).
@@ -168,7 +149,7 @@ into whatever it runs, which is why swapping Traefik for something else touches
 publishes through it. See [ADR 0009](../../02-DECISIONS/0009-modules-and-the-graph.md) for the
 other direction — handing a credential *back* — which is the larger half and is not built.
-**What is still not a module, and why that is correct.** The node-engine needs none of this. It has an
+**What is still not a module, and why that is correct.** The host needs none of this. It has an
 address and a route before the mesh exists — that is the machine's own networking — and the
 broker's address is carried in the token rather than resolved
 ([ADR 0004](../../02-DECISIONS/0004-a-node-and-how-it-joins.md)). **The one connection that
@@ -189,10 +170,10 @@ The one thing to get right, because everything else depends on it:
 7  routes and certificates              once this node has something to expose
 ```
-**Step 1 runs on the underlay and never on the private network.** This is the circularity that must not
+**Step 1 runs on the underlay and never on the overlay.** This is the circularity that must not
-be created: the private network is configured by the mesh, so a link that required the private network could
+be created: the overlay is configured by the mesh, so a link that required the overlay could
 never be established on a new node. The link stays on the underlay permanently — it is
-outbound-only and carries its own identity, so it needs nothing the private network provides.
+outbound-only and carries its own identity, so it needs nothing the overlay provides.
 **Nothing before step 3 can resolve a mesh name**, which is why the token carries an *address*
 ([ADR 0004](../../02-DECISIONS/0004-a-node-and-how-it-joins.md)). Today this is
@@ -207,7 +188,7 @@ a broker node whose address moves invalidates every token issued for it.
 *2026-10-02.* **The order changes at step 1: the tunnel comes first, from the token**
 ([ADR 0169](../../02-DECISIONS/0169-a-machine-joins-through-the-tunnel-and-the-bus-is-never-public.md)).
-The circularity above is real, and it is broken differently. The private network is configured by the mesh,
+The circularity above is real, and it is broken differently. The overlay is configured by the mesh,
 except for the one peer a joining machine needs, and the token carries that peer. So the sequence
 becomes:
@@ -227,14 +208,14 @@ including one that is joining, so it is never opened to the internet. The precon
 hub's tunnel must be dialable by every node, at a stable address.** That port answers nothing to a
 key it does not know.
-**Whether the link should later move onto the private network, with the underlay as fallback, is
+**Whether the link should later move onto the overlay, with the underlay as fallback, is
 [open](../../02-DECISIONS/0007-connectivity.md).** It is a decision rather than a derivation: the
 gain is which network carries bytes, not what an attacker can reach, since the link is already
 encrypted against a pinned fingerprint.
-## 1 — The private network
+## 1 — The overlay
-**What is decided:** the peer graph. For every node: its private network address, which peers it holds,
+**What is decided:** the peer graph. For every node: its overlay address, which peers it holds,
 which of those it may dial, and which must dial it.
 **Inputs, all declared:**
@@ -250,7 +231,7 @@ which of those it may dial, and which must dial it.
 **Keys.** Each node generates its own keypair. **The private key never leaves the machine**; the
 public key is published to the mesh. This is already true and it is already right — it is
 [ADR 0004](../../02-DECISIONS/0004-a-node-and-how-it-joins.md)'s *a node holds its own
-identity* applied to the private network, and it means the controller computes a graph it cannot
+identity* applied to the overlay, and it means the controller computes a graph it cannot
 itself impersonate.
 **Shape: a hub, with direct peering between co-located nodes.**
@@ -266,7 +247,7 @@ preference: there is no failover.** A more specific route to a dead endpoint bla
 not fall back to the general one. So a node whose location changes gets exactly one path, because
 two paths would mean one of them silently swallowing traffic.
-**What the node-engine receives:** an interface configuration and a peer list, as files. It does not
+**What the host receives:** an interface configuration and a peer list, as files. It does not
 compute them, and after this it holds no credential to the mesh's database.
 ### Four things the lab found, none of them visible from the mesh's own state
@@ -289,7 +270,7 @@ files were right, the services were up, and every node reported success.
  path, and the direct route is more specific than the hub's, so it wins and blackholes. This
  document's own warning, arriving in its implementation: *a more specific route to a dead
  endpoint blackholes; it does not fall back to the general one.*
- **The container runtime closes the door the private network needs.** Docker sets the FORWARD policy to
+- **The container runtime closes the door the overlay needs.** Docker sets the FORWARD policy to
  DROP, so a hub with `ip_forward` enabled still carries nothing between its spokes. The foundation
  at tier 1 silently breaks the network at tier 2, and nothing in either tier's state says so. The
  hub inserts its own rule above those chains and removes it on the way down.
@@ -304,10 +285,10 @@ each was found within minutes of a real machine trying it.
 | | resolves to | certified by |
 |---|---|---|
-| **internal names** | private network addresses | the **mesh CA** |
+| **internal names** | overlay addresses | the **mesh CA** |
 | **public names** | whatever the outside world must reach | a **public authority** |
-A node's mesh name is its private network address. Its public name, if it has one, is a separate fact
+A node's mesh name is its overlay address. Its public name, if it has one, is a separate fact
 used by things outside the mesh — and the separation carries two lessons that were learned
 expensively enough to be worth restating:
@@ -317,18 +298,10 @@ expensively enough to be worth restating:
 - **A node must not pin its own public name locally.** The duplicate record breaks resolution of
  that name for everything else that needs it.
-**What the node-engine receives:** what to ask, not what to answer. The mesh has **two resolvers**, each
+**What the host receives:** what to ask, not what to answer. The mesh has **one resolver**, holding
-holding every node's internal domain; a node lists both and nothing else
+every node's internal domain; a node asks it first and a public resolver only when it is silent
 ([ADR 0194](../../02-DECISIONS/0194-the-mesh-has-one-resolver-and-every-node-asks-it-for-the-meshs-names.md),
-[ADR 0223](../../02-DECISIONS/0223-the-mesh-has-two-resolvers-and-a-machine-lists-only-them.md)).
+[ADR 0196](../../02-DECISIONS/0196-a-node-asks-the-meshs-resolver-first-and-a-public-one-only-when-it-is-silent.md)).
 **A machine with a VPN client that writes the resolver file itself runs a resolver of its own**
 ([ADR 0247](../../02-DECISIONS/0247-a-machine-with-a-vpn-client-routes-names-by-domain-through-a-resolver-of-its-own.md),
 [to-be 50](50-split-dns-on-a-machine-with-a-vpn-client.md)). Its file names that resolver, on the
 machine's private address so its containers reach it, and the resolver asks the mesh's two resolvers for
 every name except the VPN's own domains, which it sends to the VPN's servers over the VPN's link. One
 server is listed, so there is still one answer per name. It is installed only where something requires
 `split-dns`; everywhere else the file is as above.
 **What goes away:** the `/etc/hosts` floor. It exists because a node had to reach the mesh
 database before its own DNS existed; with [ADR 0004](../../02-DECISIONS/0004-a-node-and-how-it-joins.md)
@@ -375,7 +348,8 @@ nothing is copied.** The resolver is a machine-level process rather than a conta
 circular is being asked for. It was gated on a container being able to reach the resolver from any of
 the runtime's networks
 ([issue 110](../../04-ISSUES/110-a-container-on-the-runtimes-own-network-cannot-reach-the-resolver/00-report.md)),
-and landed the day that did, 2026-09-30: the controller writes no mesh name into a container and the node-engine's digest carries only what the module declared for itself.
+and landed the day that did, 2026-09-30: the controller writes no mesh name into a container and the
 host's digest carries only what the module declared for itself.
 The paragraph below states the old boundary, and 0148 deliberately gives it up: a container somebody
 started by hand resolves the same names as everything else, because the resolver answers the machine,
@@ -385,87 +359,39 @@ not a list of containers.
 somebody starts by hand is not the mesh's to configure, and reaching into every container on a
 machine — declared or not — is what a nameserver in `resolv.conf` would be for.
-### The mesh's resolvers
+### One resolver for the mesh
-*2026-10-03, revised 2026-10-05.* **The mesh's names live in one module, held on two machines: the
+*2026-10-03.* **The mesh's names live in one place: the module holding `mesh-resolver`**, a mesh-scoped
-holders of `mesh-dns-resolver`**, a mesh-scoped seat that is *replicated* — held on the anchor and on
+seat of capacity one, placed on the node every tunnel converges on. It holds one wildcard per node —
-the home server, each running the same module with the same machine list and the same zones, rendered
+`<node>.internal` and everything under it — and listens on the private network only. It answers the
-by the controller into each. Each holds one wildcard per node — `<node>.internal` and everything
+mesh's names from what it holds and forwards every other name, giving the public answer.
 under it — and one host record per node, listens on its private address and loopback only, answers
 the mesh's names from what it holds and forwards every other name, giving the public answer
 ([ADR 0194](../../02-DECISIONS/0194-the-mesh-has-one-resolver-and-every-node-asks-it-for-the-meshs-names.md),
 [ADR 0223](../../02-DECISIONS/0223-the-mesh-has-two-resolvers-and-a-machine-lists-only-them.md)).
 Each holder is on record, added by `seat mesh-dns-resolver --add <node>/<module>`; an assignment of
 the module not on record stands beside them, eligible and silent, and a seat held once stays held
 once. *Checked by the controller's resolution tests with two holders on record, with two claimants
 and nothing on record, and on a seat held once.*
-**Every node asks them for everything, and nothing else.** `/etc/resolv.conf` lists every holder's
+**Every node asks it for everything, and a public resolver only when it is silent.** The module
-private address — the holder on the machine itself first if it is one, then the rest by name — with a
+holding `node-resolver-config` writes `/etc/resolv.conf` naming `mesh-resolver` first and a public
-short timeout and two attempts, and **no public resolver**. ADR 0196 listed a public resolver second,
+resolver second, with a short timeout and one attempt: the C library moves to the second only when the
-for the anchor being unreachable; a C library that asks every listed server at once and takes the
+first does not answer — the anchor or the tunnel down, a captive portal holding the tunnel back — so
-first reply — musl, so every Alpine container — took the public resolver's "no such name" for a mesh
+public names keep resolving then, and `.internal` is never asked of a public resolver while the mesh's
-name, and every build on the home server failed. With only the mesh's resolvers listed, whichever
+answers. Containers take the same two from their machine, the runtime copying non-loopback resolvers
-answers first gives the one answer. The cost is stated: a machine that reaches no mesh resolver has no
+into every container, so the runtime is given no `dns` of its own
 names until it does, and with the anchor down the second resolver is reachable only on its own machine
 and its own LAN. Containers take the same lines from their machine, the runtime copying non-loopback
 resolvers into every container, so the runtime is given no `dns` of its own
 ([ADR 0196](../../02-DECISIONS/0196-a-node-asks-the-meshs-resolver-first-and-a-public-one-only-when-it-is-silent.md),
-replacing ADR 0194's per-node `systemd-resolved` stub). *Checked by the controller's composition tests
+replacing ADR 0194's per-node `systemd-resolved` stub).
 on both holders and on a third machine, for every uplink module, and live by each machine's
 `/etc/resolv.conf` and an Alpine container on the home server resolving the anchor's name every
 time.*
-**The file is the uplink's holder's** ([ADR 0223](../../02-DECISIONS/0223-the-mesh-has-two-resolvers-and-a-machine-lists-only-them.md)).
+**No node holds a copy.** The per-node resolver, its zones file and the mesh's region of `/etc/hosts`
-A network manager rewrites `/etc/resolv.conf` on every connectivity change unless it is told not to
+go: every resolution fault found on 2026-10-03 was a copy disagreeing with the truth — a hosts file
 ([ADR 0117](../../02-DECISIONS/0117-a-machines-uplink-is-a-seat.md)), so the module holding
 `node-uplink` — the one telling it — writes the file itself, and there is one owner for it, the one
 whose program would otherwise overwrite it. Each of the catalogue's managers' modules
 (NetworkManager, systemd-networkd; dhcpcd's left the catalogue with
 [ADR 0226](../../02-DECISIONS/0226-the-private-network-is-assigned-by-its-own-name-and-the-proxy-names-its-public-issuer.md), held by no machine) renders the same template from the resolver's holders and
 requires the mesh's resolver, so a machine is refused when nothing in the mesh resolves rather than
 given a file listing nothing. The managers' own mechanisms were weighed and not used: NetworkManager's
 global DNS and dhcpcd's static nameservers each write the file in their own form — their own header,
 their own options line — so neither can write the mesh's file byte for byte, and dhcpcd reads its
 configuration only at its next start; each manager is told to keep off the file and the module
 declares it. No other module may write that path, as a file or as a rendered fact: two modules on one
 node declaring one path are refused. The module that wrote the file before, its seat
 `node-resolver-config` and that seat's need of the uplink beside it
 ([ADR 0220](../../02-DECISIONS/0220-what-a-machine-asks-needs-its-uplink-held-and-the-retired-resolver-pieces-go.md))
 retire. The file changes owner in one apply on each machine: the node-engine hands a whole file to the
 resource declaring its path now rather than removing it first, so a machine is never without it.
 *Checked by the controller's tests that the uplink modules carry one identical template and that
 nothing else in the catalogue writes the path, a resolution test refusing a second writer, and the
 node-engine's handover test, in which the file is present at every step of the apply.*
 **A machine's names are one seat's** ([ADR 0223](../../02-DECISIONS/0223-the-mesh-has-two-resolvers-and-a-machine-lists-only-them.md)).
 The `hosts` module is renamed `hostname` and holds `node-hostname`, the seat once named
 `node-hosts-file`, whose former name resolves to it. It writes `/etc/hostname` from its `hostname`
 setting — with no default: what a machine calls itself is the operator's, and the mesh's name for a
 machine and its own need not agree — and the machine's `127.0.1.1` line, keeping the operator's lines.
 A new name takes effect at the next boot; nothing sets it live, because a graphical session's X
 authority is keyed by the name the session started under. *Checked by a resolution test that a
 module claiming the old name and one claiming the new are one seat on one machine, and a composition
 test that `/etc/hostname` is the setting, left out naming the key when nothing sets it.*
 **No node holds a copy of its own.** The two holders hold the same rendering of one roster, never a
 list anyone edits. The per-node resolver, its zones file and the mesh's region of `/etc/hosts`
 go, and the per-node resolver's seat with them, deleted from the set once nothing claimed it
 ([ADR 0220](../../02-DECISIONS/0220-what-a-machine-asks-needs-its-uplink-held-and-the-retired-resolver-pieces-go.md)): every resolution fault found on 2026-10-03 was a copy disagreeing with the truth — a hosts file
 read once at start, an operator's old line beside the mesh's, a node's resolver lent to a LAN. No
 member's resolver answers a LAN; a router pointing at one is moved first. *Checked by each node's
-`/etc/resolv.conf` listing the resolver's holders and nothing else, by no node but a holder answering
+`/etc/resolv.conf` naming `mesh-resolver` then a public resolver, by no node but the holder answering
 DNS on any address, and by the router's DHCP DNS option naming the router.*
 **Names that are neither a node nor a route.** A module that answers names declares a zone (a
 setting) and the listen that answers it; the controller hands the `mesh-dns-resolver` holder every
-zone with its module's node address and published port, and each holder forwards that zone there and
+zone with its module's node address and published port, and the holder forwards that zone there and
 answers nothing in it itself — the lab answers `<machine>.incus` for its running scenarios this way.
 An operator's own names, unrelated to the mesh, live in `/etc/hosts`'s kept region, held per node by
-the `node-hostname` seat's holder and changed through its tools; the controller holds none of them
+the `node-hosts-file` seat's holder and changed through its tools; the controller holds none of them
 ([ADR 0199](../../02-DECISIONS/0199-a-module-that-answers-names-declares-its-zone-and-a-nodes-hosts-file-is-one-modules.md)).
 *Checked by the holder's configuration carrying one forwarding rule per declared zone, and by a push
-leaving the `hosts` file's operator region byte for byte.*
+leaving the hosts file's operator region byte for byte.*
 *What follows describes the per-node resolver this replaces — how it was built and why the roles were
 split. The split stands; the serving role's scope is what moved.*
@@ -485,7 +411,7 @@ composed from the serving node, the rule above holds without exception. The publ
 module's node's, which is where the operator put it.
 **The mesh writes the data and runs no daemon.** One wildcard per machine, from the same set that
-writes the `hosts` file. A resolver is third-party software and runs *on* the mesh rather than being
+writes the hosts file. A resolver is third-party software and runs *on* the mesh rather than being
 *of* it: the mesh has no business shipping one, choosing which one, or knowing its configuration
 language. Swapping dnsmasq for unbound changes that module and nothing in the controller.
@@ -600,7 +526,7 @@ it and hands back the public name. Ordinary
 vocabulary — the mirror of a database grant, where the consumer supplies a target and receives a
 name rather than supplying nothing and receiving credentials.
-**A workload on an unreachable node is proxied by a reachable one, across the private network.** Which is
+**A workload on an unreachable node is proxied by a reachable one, across the overlay.** Which is
 the case is a mesh-level fact, which is the fourth reason exposure is controller work.
 ### What was built
@@ -691,7 +617,7 @@ program that reads it, and another proxy may implement the same file.
 ## 4 — Filtering
-**Derived from what is assigned here, and from the private network's shape** — a node's open ports are a
+**Derived from what is assigned here, and from the overlay's shape** — a node's open ports are a
 consequence of what runs on it and who must reach it, not an independent declaration to keep in
 step by hand. That is true of a converged node; an adopted one keeps the firewall it was found
 with until it converges (below).
@@ -702,7 +628,7 @@ is removed rather than implemented: five manifests carry it today, it is referen
 and it is the clearest instance in the repository of *an unenforced rule is indistinguishable
 from a wrong one, and costs more, because people believe it.*
-**Unknown keys are refused** — the discipline the node-engine's declaration parser already has
+**Unknown keys are refused** — the discipline the host's declaration parser already has
 ([ADR 0005](../../02-DECISIONS/0005-the-node-host.md)), and
 the one manifests lack. `scope:` survived because nothing rejected it.
@@ -756,7 +682,7 @@ tmpfiles — is shaped that way. Until there is one, a module ships a unit that
 the better shape: how a machine enforces rules is a fact about the machine, and the mesh has no
 business depending on what a distribution happens to package.
-**One rule is derived from the private network's shape rather than from what is assigned: a hub's own
+**One rule is derived from the overlay's shape rather than from what is assigned: a hub's own
 listening port.** A hub accepts inbound connections from every node at other sites; a machine that
 is not a hub dials out and needs nothing open, because a reply to a flow it started is already
 accepted. The two want different rules on an *identical module*, so `listens` — a static field —
@@ -809,7 +735,7 @@ declares as **openings**: a port, from where, on the incoming path or the forwar
 published container port is forwarded, and a firewall that filters only incoming traffic never
 sees it. The controller derives them from what the filter would be derived from, each from where
 the filter would admit it: the assigned modules' `listens`, the hub's port, the bus and the registry
-from anywhere; the store's port and the broker's management port from the private network. The node-engine converges each opening through
+from anywhere; the store's port and the broker's management port from the private network. The host converges each opening through
 the found firewall in that firewall's own terms, marks it as the mesh's, removes only what it
 marked, and re-checks every opening on each reconcile so a reload or a reboot does not lose it for
 longer than one reconcile. An opening is state, not a command, so it travels over the link like any
@@ -879,9 +805,9 @@ named in any setting, and each reaches outward afterwards — which fails agains
 where the same flip cut them off, and is how it was written; a network made *after* the last declaration
 needs no new filter; a declared port is reachable from off the private network and an undeclared one is
 not; no address of a machine's own networks appears in a rendered filter, asserted on the text; and a
-machine reporting no outward link is refused in the controller with its existing filter left alone.
+machine reporting no outward link is refused in the control plane with its existing filter left alone.
-### A converged machine is filtered by the mesh alone, and the node-engine says what else refuses
+### A converged machine is filtered by the mesh alone, and the host says what else refuses
 *2026-10-02, [ADR 0168](../../02-DECISIONS/0168-a-converged-machine-is-filtered-by-the-mesh-alone.md),
 from [issues 143](../../04-ISSUES/143-converging-does-not-retire-the-firewall-it-found/00-report.md) and
@@ -894,9 +820,9 @@ runtime's user hook — legacy iptables on one machine, invisible to a reader of
 forwarded path, refused ports the mesh declared open, and carried an allowance every module reaching
 another by the machine's own name relied on.
-**Convergence is a state the node-engine keeps.** Every converged apply reads whether the found firewall is in
+**Convergence is a state the host keeps.** Every converged apply reads whether the found firewall is in
 force; enabled again, it is retired again and said; the record says whether the mesh disabled it or
-found it inactive, and a skipped step is said. **The node-engine reports what filters the machine**, every
+found it inactive, and a skipped step is said. **The host reports what filters the machine**, every
 apply, adopted or converged: every table and legacy chain that refuses, with an owner — the mesh's,
 the found firewall's, the runtime's own plumbing, a ban, or *other*, which is where the runtime's user
 chain's refusals go. **The mesh says which:** `node show` lists them; `status` names a converged machine
@@ -914,7 +840,7 @@ predicate. Live: the home server's record names the predecessor's chain as *othe
 names the machine until the chain is removed by hand.
 *2026-10-02, [ADR 0170](../../02-DECISIONS/0170-the-firewall-seat-serves-its-verbs.md):* removing what
-the node-engine reports as *other* is reached through the packet filter seat's `remove` verb, an operator's act
+the host reports as *other* is reached through the packet filter seat's `remove` verb, an operator's act
 by name on the bus; the seat also serves `rules` and `reload`, and its holder's runtime declares the
 `NET_ADMIN` capability on the machine's network. See design 33.
@@ -930,7 +856,7 @@ adopted then enables nothing. The rollback path ADR 0100 kept on disk is given u
 | | issued by | for |
 |---|---|---|
 | **public names** | a public ACME authority | anything outside the mesh reaches |
-| **internal names** | the **mesh CA** | node-to-node, over the private network |
+| **internal names** | the **mesh CA** | node-to-node, over the overlay |
 **The split is not collapsed, including in the lab.** A single-CA lab would hide any bug living
 in the split, so the lab runs its own ACME issuer on its public segment and keeps the mesh CA
@@ -945,17 +871,6 @@ defaults to the public authority's *production* endpoint. Two consequences, and
 worse than the lab problem that found it — every certificate experiment on a real node consumes
 production issuance quota, and a retry loop can exhaust it for a week.
 > **Amended 2026-10-06, by [ADR 0226](../../02-DECISIONS/0226-the-private-network-is-assigned-by-its-own-name-and-the-proxy-names-its-public-issuer.md).** Configurable in the
 > proxy binary, which defaults to the authority's *staging* endpoint; fixed in the mesh. The public
 > issuer was a provision, `acme-ca`, answered by a module that ran nothing and was assigned beside
 > every proxy; it is the proxy module's own `acme.env` now, Let's Encrypt's production directory
 > spelled exactly as the binding rendered it. The proxy names each authority's account directory after
 > that spelling and the root it trusts, so changing either is a new account and every certificate
 > ordered again: moving the public issuer is an edit of the module with a plan for the account, never
 > an assignment. The internal issuer stays a provision, `internal-acme-ca`.
 > *How it is checked:* mesh-controller `internal/catalogue/public_issuer_test.go` holds the rendered
 > file byte for byte and the `trust` image's digest, against the catalogue.
 **The mesh CA is not a bootstrap concern.** A joining node verifies the controller against the
 fingerprint in its token ([ADR 0004](../../02-DECISIONS/0004-a-node-and-how-it-joins.md)),
 so nothing needs the CA before membership. It certifies internal names afterwards, and that is
@@ -983,7 +898,7 @@ extracted bundles — and stopping it, which is what being unassigned does, take
 and refreshes them again. Not the controller's business, because being on the private network is
 what makes the authority *reachable* and is not the same fact as having a reason to *verify* a
 mesh name; and because where anchors live and which command refreshes them is one operating
-system's difference, which is the node-engine's half of the mesh
+system's difference, which is the host's half of the mesh
 ([ADR 0005](../../02-DECISIONS/0005-the-node-host.md)).
 *How it is checked:* on a machine holding the module a plain client verifies an internal HTTPS
 name with no bundle argument, and on one without it the same fetch fails to find an issuer — both
@@ -1007,7 +922,7 @@ valid certificate and there is nothing to keep in step.
 **A machine with no name inside the mesh is refused**, not given a certificate for nothing. A
 certificate for a name nothing resolves is a certificate nothing can check.
-**And the key is stored in the format a server reads** — PKCS#8 PEM, not the node-engine's own encoding.
+**And the key is stored in the format a server reads** — PKCS#8 PEM, not the host's own encoding.
 That is not an implementation detail of whoever writes the file: the file exists *because
 something else reads it*, so the format is the interface
 ([04-ISSUES/014](../../04-ISSUES/014-a-key-that-is-present-and-unusable/00-report.md)).
@@ -1120,14 +1035,10 @@ The list is worth having in one place, because it is most of the argument:
 ## Open
- **One resolver ([ADR 0194](../../02-DECISIONS/0194-the-mesh-has-one-resolver-and-every-node-asks-it-for-the-meshs-names.md)).** *Correction of fact,
+- **One resolver ([ADR 0194](../../02-DECISIONS/0194-the-mesh-has-one-resolver-and-every-node-asks-it-for-the-meshs-names.md)).** Not built: every node still runs
-  2026-10-05:* no node holds `node-dns-resolver` any more, and
+  `node-dns-resolver`. The migration's four steps are in the record, in order.
-  [ADR 0220](../../02-DECISIONS/0220-what-a-machine-asks-needs-its-uplink-held-and-the-retired-resolver-pieces-go.md) deletes the seat. What stood here before: *"Not built: every node still runs
+  Nor are zones or the hosts file's holder ([ADR 0199](../../02-DECISIONS/0199-a-module-that-answers-names-declares-its-zone-and-a-nodes-hosts-file-is-one-modules.md)): the
-  `node-dns-resolver`. The migration's four steps are in the record, in order."* Nor did it
+  workstation moves to the one resolver only once both exist, its lab and operator names depending on them.
  stay true that *"the workstation moves to the one resolver only once"* zones and the `hosts` file's
  holder ([ADR 0199](../../02-DECISIONS/0199-a-module-that-answers-names-declares-its-zone-and-a-nodes-hosts-file-is-one-modules.md))
  exist: every node, the workstation included, asks the one resolver, and every node holds
  `node-hosts-file`.
 - ~~**What happens when the hub is down.**~~ **Resolved** by
  [ADR 0006](../../02-DECISIONS/0006-the-substrate-and-the-control-plane.md), together with `06`'s
@@ -1135,14 +1046,14 @@ The list is worth having in one place, because it is most of the argument:
  hub is declared rather than elected, and non-co-located paths stop while co-located direct peers
  and every already-assigned workload keep running. The recovery path is restore, and its deadline
  is certificate renewal.
- **Renumbering the private network.** Made *possible* by declaring the hub rather than inferring it from
+- **Renumbering the overlay.** Made *possible* by declaring the hub rather than inferring it from
  an address, but no procedure exists, and a graph delivered node by node has an ordering problem
  while it is half-applied.
 - ~~**Revoking a route** when a module is unassigned.~~ **Resolved** 2026-08-31 — see §3. The file
  a proxy is given is the whole truth about who has a route, so a route does not outlive the module
  that asked for it.
 - **IPv6.** [ADR 0007](../../02-DECISIONS/0007-connectivity.md) makes
-  it expressible; nothing here says the private network or the resolver handle it.
+  it expressible; nothing here says the overlay or the resolver handle it.
 - **Reporting declared-versus-observed.** ADR 0007 makes the disagreement detectable and does not
  say who looks or what they are told.
 - **Composing a route name from a label and a node's domain.**
@@ -1179,7 +1090,7 @@ anything but a person restoring it by hand. Undeclaring the private network does
 before code; this section names the shape only.*
 Every link the mesh has rides NATS subjects; durability is JetStream's; a module's account is a
-NATS account with permissions derived from `emits`/`consumes`, declared as configuration the node-engine
+NATS account with permissions derived from `emits`/`consumes`, declared as configuration the host
 writes and the server reloads. The sdk's contract is unchanged. The adopted AMQP broker stays as
 the predecessor's compatibility broker until its last client is gone. Built in the lab beside the
-migration; cut over in one switch-over after the core; the person's client is designed on it.
+migration; cut over in one rollout after the core; the person's client is designed on it.
@@ -29,7 +29,7 @@ decisions:
 How a Linux machine becomes a node, stays one, and stops being one.
-[`05-the-node-host.md`](05-the-node-host.md) describes the node-engine as a component. This describes
+[`05-the-node-host.md`](05-the-node-host.md) describes the host as a component. This describes
 it as something that runs for years on a machine somebody else also uses — which is where the
 questions that were not being asked live.
@@ -44,7 +44,7 @@ questions that were not being asked live.
 | State | Has | Can |
 |---|---|---|
 | **unmanaged** | nothing of ours | — it is a Linux machine |
-| **hosted** | the node-engine, no identity | apply a local file, apply its bundle |
+| **hosted** | the host, no identity | apply a local file, apply its bundle |
 | **enrolled** | identity, link, store | everything; this is *a node* |
 | **disconnected** | identity, store, no link | hold its machine in the last state it was told |
@@ -116,7 +116,7 @@ asked to *start this at boot* and *start it again if it exits*, and nothing else
 expressible in OpenRC, runit, s6 and an Android `init.rc`, so porting this file is transcription
 rather than design.
-**`Restart=always` and not `on-failure`**: the node-engine restarts onto a new binary by exiting
+**`Restart=always` and not `on-failure`**: the host restarts onto a new binary by exiting
 *cleanly*, so a supervisor that only restarts on failure would leave every upgraded node stopped,
 having successfully upgraded.
@@ -124,13 +124,14 @@ having successfully upgraded.
 lives in the launcher, where it can be tested — `OnFailure=` in a unit file can only be read and
 hoped for, and it is the one thing that has to work on a machine where nothing else does.
-**The package owns this file. The node-engine never does.** It manages `service` resources, and its own
+**The package owns this file. The host never does.** It manages `service` resources, and its own
 unit is a service — the temptation is obvious and it ends with a host stopping itself half way
-through an apply, leaving a machine with nothing running to fix it. A declaration naming the node-engine's own unit is **refused**, and that refusal is a test rather than a convention.
+through an apply, leaving a machine with nothing running to fix it. A declaration naming the
 host's own unit is **refused**, and that refusal is a test rather than a convention.
-The line to hold: **the installation owns the node-engine; the node-engine owns everything else.**
+The line to hold: **the installation owns the host; the host owns everything else.**
-At this point the node-engine is running and **doing nothing**. It has no identity, so there is nobody
+At this point the host is running and **doing nothing**. It has no identity, so there is nobody
 to link to and nothing to apply. It answers `profile`, `inventory` and `version`, and waits.
 ---
@@ -149,29 +150,29 @@ join once.
 **The fourth is the one this document listed three of.** A node connects to the broker and takes
 instruction from the controller behind it, and those are two different identities. Pinning only
 the broker would make the controller's authority *transitive* — a compromised broker could then
-forge declarations, which, since the node-engine applies whatever the link delivers, is the whole machine.
+forge declarations, which, since the host applies whatever the link delivers, is the whole machine.
 So the transport is verified once at connect, and **each declaration is verified by its signature,
 every time**.
 What happens, in order:
-1. the node-engine dials the broker at the address in the token, **over the underlay**;
+1. the host dials the broker at the address in the token, **over the underlay**;
 2. it checks the broker's certificate against the pinned fingerprint — *before* sending anything;
 3. it presents the one-time secret **and its own public key**, which the mesh records;
 4. it reports its `profile` and `inventory` upward;
 5. the controller decides what this machine should be, and sends a declaration;
-6. the node-engine applies it, reads back, and reports.
+6. the host applies it, reads back, and reports.
 **Step 4 is the one that is easy to miss and is what makes step 5 possible.** The controller
 cannot decide what a machine should run without knowing what it *can* run — a graphical session,
 a container runtime, an architecture. The profile is not a diagnostic; it is the input.
-**The node computes nothing about the mesh.** It needs one peer to reach; the whole private network is
+**The node computes nothing about the mesh.** It needs one peer to reach; the whole overlay is
 derived centrally and pushed down
 ([ADR 0004](../../02-DECISIONS/0004-a-node-and-how-it-joins.md),
 [`08-connectivity.md`](08-connectivity.md)).
-### The first declaration is the private network, and nothing else
+### The first declaration is the overlay, and nothing else
 **The mesh makes a node reachable before it makes it useful.** Step 5 is not one declaration
 carrying everything the node will ever run. It is two, in order:
@@ -183,13 +184,13 @@ then     everything else — packages, containers, services, files
 Three reasons, and the third is the one that matters when something goes wrong:
- **It is forced.** A node cannot join the private network before contacting the mesh, because its
+- **It is forced.** A node cannot join the overlay before contacting the mesh, because its
  address and peer set are *assigned* — it generates a keypair, publishes the public half, and
-  receives the rest ([`08-connectivity.md`](08-connectivity.md)). So the private network is the first
+  receives the rest ([`08-connectivity.md`](08-connectivity.md)). So the overlay is the first
  thing the mesh can give it, and it should be.
 - **It is what [ADR 0004](../../02-DECISIONS/0004-a-node-and-how-it-joins.md) already
  says:** *a joining node does the minimum to be reachable, and nothing else.*
- **It is the way back in.** Once the private network is up, the node is reachable over it — by SSH, by
+- **It is the way back in.** Once the overlay is up, the node is reachable over it — by SSH, by
  anything. If a later declaration breaks the machine, there is a route to it that does not
  depend on the mesh's control path working. **Sending a large first declaration risks a node
  that is broken and unreachable at the same time**, and those two failures are much worse
@@ -201,14 +202,14 @@ Worth stating plainly, because the two rules read as a contradiction and are not
 | | |
 |---|---|
-| **every node reaches every other node** | over the private network — SSH, services, ordinary traffic. This is the point of having one |
+| **every node reaches every other node** | over the overlay — SSH, services, ordinary traffic. This is the point of having one |
 | **every node consumes from the broker** | its own queue, over its own outbound connection ([ADR 0002](../../02-DECISIONS/0002-nodes-communicate-over-a-broker.md)) |
-| **nothing dials a node to control it** | the node-engine has no inbound control surface ([ADR 0004](../../02-DECISIONS/0004-a-node-and-how-it-joins.md)) |
+| **nothing dials a node to control it** | the host has no inbound control surface ([ADR 0004](../../02-DECISIONS/0004-a-node-and-how-it-joins.md)) |
 **[ADR 0004](../../02-DECISIONS/0004-a-node-and-how-it-joins.md) is about the control
 channel, not about network reachability.** What it forbids is a listening thing that accepts
-instructions and changes the machine. A node being reachable on the private network — the whole purpose
+instructions and changes the machine. A node being reachable on the overlay — the whole purpose
-of the private network — is untouched by it, and so is a person opening a shell on it.
+of the overlay — is untouched by it, and so is a person opening a shell on it.
 The distinction is *who can tell this machine what to be*: only the controller, only over the
 link the node opened, only in declarations of known shape.
@@ -232,7 +233,7 @@ nox-mesh-host enrol --token <token>
 Step 1 is the bootstrap from [`07-the-foundation.md`](07-the-foundation.md): a container runtime,
 then PostgreSQL, then the database, then the schema, then the controller. It needs no identity
-because nothing is being asked of anyone — the node-engine is applying a declaration it already
+because nothing is being asked of anyone — the host is applying a declaration it already
 carries, to the machine it is already on.
 **After step 3 the first node is not special in any way**, which is the property `adopt.sh` and
@@ -246,7 +247,7 @@ used months later on node two.
 ## Two kinds of host
-Everything above assumes a machine with an init that runs the node-engine at boot. Not every machine
+Everything above assumes a machine with an init that runs the host at boot. Not every machine
 has one ([ADR 0005](../../02-DECISIONS/0005-the-node-host.md)).
 | | **resident** | **episodic** |
@@ -295,7 +296,7 @@ converged, as before
 The operator says a node is adopted — at genesis for the control-node, in the enrolment token for
 the others — and the controller records it and says so in every declaration, with the modules
 **taken** on that node. On an adopted node what is found is held until its module is taken
-([05-the node-engine](05-the-node-host.md)): assigning a module prepares it, taking it is its
+([05-the-node-host](05-the-node-host.md)): assigning a module prepares it, taking it is its
 cutover. The firewall found there stays in force and the mesh opens what it needs through it
 ([08-connectivity](08-connectivity.md)). **Converging is one act per node, previewed**: it refuses
 while an assigned module still holds a found container; otherwise it lists what is reachable on the
@@ -339,7 +340,7 @@ over a take's digest, staleness and secrets.
 A candidate machine is not empty. It has a package manager, probably a container runtime,
 configuration somebody chose. [ADR 0005](../../02-DECISIONS/0005-the-node-host.md)
-says the node-engine never touches what it did not create — adoption is the deliberate act of taking
+says the host never touches what it did not create — adoption is the deliberate act of taking
 ownership of exactly that, so it is a companion to that rule rather than an exception:
 > *never, unless adoption made it the host's* — with adoption **explicit, recorded, and visible
@@ -360,13 +361,14 @@ bind is not adopted but broken.
 **Adoption produces a briefing**, not just a result: what it found, what it took over, and what
 it could not resolve — with each line marked `ok`, `kept`, `unknown` or `failed`, and the overall
-outcome **derived** from the worst line rather than stated alongside it. A file or container the node-engine is holding on an adopted node is a `kept` line for as long as it is held.
+outcome **derived** from the worst line rather than stated alongside it. A file or container the
 host is holding on an adopted node is a `kept` line for as long as it is held.
 ---
 ## enrolled: what running actually looks like
-**Changes are pushed, not polled.** A declaration arrives as a message on the link and the node-engine
+**Changes are pushed, not polled.** A declaration arrives as a message on the link and the host
 applies it then. The link is already open and outbound
 ([ADR 0002](../../02-DECISIONS/0002-nodes-communicate-over-a-broker.md),
 [ADR 0004](../../02-DECISIONS/0004-a-node-and-how-it-joins.md)) — asking it
@@ -402,28 +404,28 @@ because a stuck node cannot send.
 **Rebooting mid-apply is safe by construction.** The store records each resource *after* it
 worked ([ADR 0018](../../02-DECISIONS/0018-a-picture-is-read-from-what-runs.md)), so a host that
 dies half way through comes back, finds the completed ones already matching, and applies the
-rest. The rule that exists to stop the node-engine lying about what it did also makes it crash-safe.
+rest. The rule that exists to stop the host lying about what it did also makes it crash-safe.
 ## Updating what the node holds
 An ordinary declaration. Someone assigns a module; the controller recomputes what that node
-should be and sends it; the node-engine applies the difference and removes what is no longer declared.
+should be and sends it; the host applies the difference and removes what is no longer declared.
 **Removal is not symmetric, and the asymmetry is the design:**
 | | on being undeclared |
 |---|---|
 | file, directory | **removed** |
-| container | **removed** — the node-engine created it |
+| container | **removed** — the host created it |
-| service | **stopped**; the unit file is not the node-engine's to delete |
+| service | **stopped**; the unit file is not the host's to delete |
 | package | **left installed** — *forgotten*, not removed |
-| action | **forgotten** — it left nothing the node-engine owns |
+| action | **forgotten** — it left nothing the host owns |
-The node-engine removes what it *made* and leaves what it merely *configured*. Uninstalling a container
+The host removes what it *made* and leaves what it merely *configured*. Uninstalling a container
 runtime because a declaration changed would stop every container on the node.
 *On an adopted node* ([ADR 0100](../../02-DECISIONS/0100-a-node-in-use-is-adopted-before-it-is-converged.md)),
-what the node-engine is holding was found, not made, so nothing held is ever removed: a held file or
+what the host is holding was found, not made, so nothing held is ever removed: a held file or
 container whose module is unassigned stays where it is.
 ---
@@ -448,7 +450,7 @@ Without it, a node running last month's assignments looks exactly like one that
 ## Rescue
-The node-engine is still a command-line tool, and that is what rescue is:
+The host is still a command-line tool, and that is what rescue is:
 ```
 nox-mesh-host owned                     # what do you think you own?
@@ -465,7 +467,7 @@ root can already do anything it can. The bound in
 [issue 104](../../04-ISSUES/104-reconcile-applies-a-stale-declaration-and-refuses-nothing/00-report.md):
 once a controller declaration has been kept on the node, `apply FILE` is refused, whatever the
 file — a hand-applied file is recorded as *carried*, which the mesh can never remove and reports
-as the machine's own, and a declaration carries no order, so the node-engine cannot tell a newer file
+as the machine's own, and a declaration carries no order, so the host cannot tell a newer file
 from an older one ([issue 107](../../04-ISSUES/107-a-declaration-carries-no-order/00-report.md)).
 Rescue on an enrolled node is `reconcile`, which re-applies what the mesh last said, previewed;
 `apply FILE` is for a machine before enrolment. A `--rescue` that applies a hand-written file to an
@@ -480,8 +482,8 @@ one binary that has always been the same binary.
 Two cases, and they are genuinely different.
-**Graceful.** The controller sends a final declaration that names nothing. The node-engine removes
+**Graceful.** The controller sends a final declaration that names nothing. The host removes
-what it owns by the table above, reports, and drops its identity. The machine keeps the node-engine
+what it owns by the table above, reports, and drops its identity. The machine keeps the host
 installed and is back to `hosted`. Nothing is left behind that anybody has to remember.
 **The node is gone.** Stolen, dead, or simply unreachable. The mesh cannot tell it anything, and
@@ -489,7 +491,7 @@ by [ADR 0004](../../02-DECISIONS/0004-a-node-and-how-it-joins.md) it will go on
 its last declaration **forever**.
 That is the honest consequence of making disconnection ordinary, and the answer is not to make
-the node-engine expire. It is that **the node holds nothing that outlives revocation**: its identity is
+the host expire. It is that **the node holds nothing that outlives revocation**: its identity is
 its own, and every grant it holds is a per-node credential at the provider
 ([ADR 0004](../../02-DECISIONS/0004-a-node-and-how-it-joins.md),
 [ADR 0008](../../02-DECISIONS/0008-a-context-owns-its-store.md)). Revoking is done at the
@@ -505,12 +507,12 @@ switch a machine off, which it cannot and should not be able to.
 Worth its own section because the failure is quiet.
-If `/var/lib/mesh-host/state.json` is lost — a reinstall, a replaced disk — the node-engine loses
+If `/var/lib/mesh-host/state.json` is lost — a reinstall, a replaced disk — the host loses
 **its record of what it owns**, not its ability to work. It re-enrols, receives the declaration
 again, and re-applies it.
 **Without help, what does not come back is removal.** Resources applied under an older
-declaration, whose record is gone, become unowned: the node-engine will not touch them, because it
+declaration, whose record is gone, become unowned: the host will not touch them, because it
 never touches what it did not create. They would sit there, unmanaged, indefinitely.
 **So the mesh keeps a copy of what each node reports it owns**, refreshed on every apply report,
@@ -519,9 +521,9 @@ remains locally authoritative for *operating*; the copy exists only for this.
 ---
-## Upgrading the node-engine
+## Upgrading the host
-The node-engine is delivered like anything else
+The host is delivered like anything else
 ([ADR 0010](../../02-DECISIONS/0010-delivery.md)), and this is worth
 walking through because tier 0 looks like it should be special and is not.
@@ -539,7 +541,7 @@ push to mesh-host
 **Compared with today.** The current pipeline's third silo runs *once per node* and sends each
 one a command to install and start. That is where the as-is records a package install that
 404ed while the job went green. Here deploy is **one write** — the declaration changes — and the
-installing is the node-engine's ordinary work, which reads back before it records anything.
+installing is the host's ordinary work, which reads back before it records anything.
 **The repository is reachable because a declaration made it so.** A `file` resource writes the
 package manager's configuration pointing at the mesh's repository; a `package` resource names
@@ -563,9 +565,9 @@ the test of whether this is really uniform.
 **Step 2 is the one to insist on.** A package can install a binary that does not execute here —
 wrong architecture, a libc that is not present. Running it once before committing to a restart
 turns "the node never came back" into "the apply failed and said why". It is the same read-back
-rule the rest of the node-engine already follows, applied to the one resource that is the node-engine.
+rule the rest of the host already follows, applied to the one resource that is the host.
-**The node-engine never asks the service manager to restart it.** That is the node-engine stopping itself
+**The host never asks the service manager to restart it.** That is the host stopping itself
 part-way through an apply. It stops by finishing.
 **A fleet upgrades over an interval, not at an instant**, because each node restarts when its
@@ -575,7 +577,7 @@ installed — otherwise the mesh believes an upgrade landed at step 1.
 **A version that crashes on start rolls itself back**
 ([ADR 0005](../../02-DECISIONS/0005-the-node-host.md)).
-What the init starts is not the node-engine but a **launcher**, and the launcher is where the policy
+What the init starts is not the host but a **launcher**, and the launcher is where the policy
 lives:
 ```
@@ -587,8 +589,8 @@ init ──► nox-mesh-host-launch ──► nox-mesh-host
              └─ otherwise                        start the host
 ```
-It reinstalls the version recorded in `known-good`, which the node-engine wrote the last time it
+It reinstalls the version recorded in `known-good`, which the host wrote the last time it
-completed a reconcile — and the node-engine clears the attempt counter at the same moment, for the same
+completed a reconcile — and the host clears the attempt counter at the same moment, for the same
 reason.
 **The launcher rather than the init's own features**, because this is the one thing that must
@@ -622,7 +624,7 @@ mesh-controller token issue --node workstation   # this machine is that node aga
 mesh-controller token issue --new                # a machine the mesh has not seen
 ```
-The node-engine does not need to know which it is. It presents a token and receives an identity; what
+The host does not need to know which it is. It presents a token and receives an identity; what
 that identity is bound to was decided when the token was made.
 **Issuing a re-enrolment token revokes the previous identity for that node**, and that is not
@@ -632,7 +634,7 @@ credentials still valid — the case
 ### Protecting the store
-**The node-engine reports what it owns, and the mesh keeps the last report.**
+**The host reports what it owns, and the mesh keeps the last report.**
 The store stays locally authoritative — a node operates from its own copy and needs nothing to
 do so ([ADR 0004](../../02-DECISIONS/0004-a-node-and-how-it-joins.md)). What changes is that
@@ -642,7 +644,7 @@ So a node that loses its state file re-enrols, receives both the declaration *an
 what it previously owned, and can then remove what is no longer declared. The orphans that used
 to be permanently stranded are recoverable.
-**This is a backup, never a source.** The node-engine never reads it to decide anything; it is handed
+**This is a backup, never a source.** The host never reads it to decide anything; it is handed
 back only on a store rebuild, and a node that disagrees with it wins, because the node is the
 one that can see the machine.
@@ -654,7 +656,7 @@ because they answer different questions — the mesh's is *have I heard from it*
 noticed at all.
 **No threshold and no alarm.** A laptop switched off for three weeks is doing nothing wrong, and
-a mesh that raised a condition for it would train people to ignore the condition. It is a **reported fact** —
+a mesh that alerted on it would train people to ignore the alert. It is a **reported fact** —
 `last seen 4 days ago` beside every node — and what counts as too long is a judgement for
 whoever is looking, not a constant in the design.
@@ -717,7 +719,7 @@ the same command against a mesh that is one machine old.
 - ~~**Automatic rollback of a bad host version.**~~ **Resolved** by
  [ADR 0005](../../02-DECISIONS/0005-the-node-host.md): a launcher
-  counts failed starts and rolls back — shipped by the package, not the node-engine binary, because a
+  counts failed starts and rolls back — shipped by the package, not the host binary, because a
  binary that will not start cannot recover itself. It rolls back once; a second failure means
  the machine is the problem, not the binary.
 - **How a previous declaration is retained and chosen**, which is what rollback of anything else
@@ -750,7 +752,7 @@ must never be indistinguishable from a failure to answer* is the rule this whole
 on. It recovered on its own, which is why this was a quality gap rather than a fault. It was still
 the machine waiting to be told something it already knew.
-**So the machine says so.** Waking, and changing network, both rouse the node-engine.
+**So the machine says so.** Waking, and changing network, both rouse the host.
 | | |
 |---|---|
@@ -5,9 +5,8 @@ code:
  - mesh-controller internal/builder
  - mesh-controller cmd/mesh-controller (build, build --behind, push, status)
  - mesh-controller internal/inventory/builds.go
-updated: 2026-10-06
+updated: 2026-09-29
 decisions:
  - 02-DECISIONS/0239-a-delivery-is-owned-by-the-mesh-delivery-module-and-runs-from-commit-to-delivered.md
  - 02-DECISIONS/0090-a-failure-that-repeats-is-said-to-be-stuck.md
  - 02-DECISIONS/0082-the-registry-is-reached-by-name-and-trusted-by-the-overlay.md
  - 02-DECISIONS/0010-delivery.md
@@ -36,7 +35,7 @@ them, and only edges can be queried or kept true automatically.
 **When several modules always change together**, that means they share an *authority* — one place
 that decides for all of them. It does not mean they should be one artifact. Connectivity is the
-worked example: one context decides the private network, names, routes, filtering and certificates, and
+worked example: one context decides the overlay, names, routes, filtering and certificates, and
 `wireguard`, the resolver, the proxy and the firewall remain four modules, because they are
 deployed to different sets of nodes.
@@ -93,17 +92,15 @@ what has been built from it ─┘
 An event makes it fast; nothing makes it necessary — so a missed webhook costs latency and cannot
 cost correctness.
-That is the same shape the node-engine uses on a machine, one layer up:
+That is the same shape the host uses on a machine, one layer up:
 | | reconciles | against |
 |---|---|---|
 | the controller | artifacts | source |
-| the node-engine | machine state | declarations |
+| the host | machine state | declarations |
 **There is no pipeline as a state machine.** No stage list something can be omitted from, and no
-run to lose. *What* is built stays decided by this comparison. *One commit's journey* through the mesh is a
+run to lose.
 delivery with a state table of its own: it records and orders that journey and never decides what to build
 (below, *A delivery has an owner*).
 ### An artifact is current, or it is not
@@ -183,8 +180,9 @@ Not aspirations — things without which the above does not work:
  same digest, a cascade would stop at the first module whose output did not move. Without them,
  one core-library commit redeploys the fleet with no behavioural change.
 - **How a module publishes its own types**, which differs per language.
- **How the controller upgrades itself.** It declares its own new version and the node-engine applies
+- **How the controller upgrades itself.** It declares its own new version and the host applies
-  it — but if the new one is broken, the thing that would fix it is the thing that is broken. The node-engine has a launcher for exactly this; the controller has nothing.
+  it — but if the new one is broken, the thing that would fix it is the thing that is broken. The
  host has a launcher for exactly this; the controller has nothing.
 ## What "behind" means, and what it used to mean
@@ -225,7 +223,7 @@ knows something the person reading the status does not.
 re-applies on its interval and reports each time, so a resource nothing can ever apply arrives as
 the same failure over and over, at a fresh time each time. The mesh keeps, beside the last report,
 when the current failure began and how many reports in a row have said it — the same resources by
-id, whatever the words; three make the machine stuck, and `status` says so beside the failure. The node-engine keeps trying — stuck is what the mesh
+id, whatever the words; three make the machine stuck, and `status` says so beside the failure. The host keeps trying — stuck is what the mesh
 knows, not what the machine is told. *How it is checked:* an inventory test counts three identical
 reports, a different one, and a clean apply; the status test asserts the word appears.
@@ -259,26 +257,3 @@ A verification mechanism was drafted for this and withdrawn. It would have repor
 would not have prevented it, and the part of it that was hard — deciding which network position to check
 from — existed only because the rule was wrong. Whether the mesh should check that a grant works is still
 open, in issue 145; it is not the remedy for a configuration error.
 ## A delivery has an owner
 *2026-10-06, by [ADR 0239](../../02-DECISIONS/0239-a-delivery-is-owned-by-the-mesh-delivery-module-and-runs-from-commit-to-delivered.md);
 designed in full in [to-be 47](47-delivery-from-commit-to-delivered.md).*
 The comparison above decides what is built, and that does not change. What it never had is an owner for
 **did my change go out?** for one commit: from its pull request's head through its check, the merge, its
 builds and every machine's gate. Five records answered it in parts, and a person joined them.
 **A delivery is one commit in one repository, and the module `mesh-delivery` owns it.** Its states are one
 compiled table: proposed, checked, ready or rejected, published, delivering, held, and four final states.
 A transition the table does not hold is refused. Two or more deliveries that share a head branch name are a
 **delivery group**, delivered in an order the planner infers and the pull requests may declare, and checked
 together as one future state of the mesh.
 **This answers the first open question above.** A fit artifact does not declare itself. Off the trunk it is
 only checked. On the trunk it is published, and its walk across the machines starts when its delivery says
 so: by itself for the core, which cannot wait for anything to be repaired, and by `mesh-delivery` for
 everything else while that module is held. A person can always deliver by hand.
 The controller keeps the comparison, the planner, the gate, sending and rollback. `mesh-delivery` keeps the
 record and the order, and asks.
--- a/Show More
+++ b/Show More