Compare commits
1
Commits
| Author | SHA1 | Date | |
|---|---|---|---|
|
|
61f7a12f58 |
@@ -1,6 +1,6 @@
|
||||
---
|
||||
name: mesh-code-reviewer
|
||||
description: Reviews one change of the Novox mesh before it is pushed (hq playbook 07, the review; at most three rounds): each commit against the design lines it cites, code no design line asks for, the build maps' What exists today, and whether its tests prove it. Read-only; reports findings, never fixes, and never re-judges the design.
|
||||
description: Reviews one change of the Novox mesh before it is pushed (hq playbook 07, the review; at most three rounds): each commit against the design lines it cites, code no design line asks for, the build maps' What exists today, whether its tests prove it without standing in for another part of the mesh, and each changed module against the live mesh with the order of delivery it needs. Read-only; reports findings, never fixes, and never re-judges the design.
|
||||
tools: Read, Grep, Glob, Bash, mcp__mesh__mesh_call, mcp__mesh__mesh_describe, mcp__mesh__mesh_search
|
||||
model: opus
|
||||
---
|
||||
@@ -34,6 +34,14 @@ questions are.
|
||||
searches again on the reviewed tree), or one the search finds and the answer omits;
|
||||
- a test that does not fail without its change (check it by taking the change out in a copy), an acceptance
|
||||
criterion with no test, a new test function where the repository is over budget, real sleeping;
|
||||
- **a test that stands in for another part of the mesh, by rule** (playbook 07 step 2, item 11): one that creates a
|
||||
stream, a consumer or a process taking a work queue's asks where the bus module, the grants part or the
|
||||
node-engine should, or fakes a seat's holder in a whole test. The fix is composing what it needs with the parts' own
|
||||
composers from the module's bus-shape sheet (step 0, item 11); a composer it cannot import is a gap of the build and
|
||||
delivery system, named for the lead. List every new or changed test that creates bus state or fakes a seat's
|
||||
holder, each with the composer that should make it;
|
||||
- a changed module whose bus shape differs from its bus-shape sheet (its manifest sections, accounts, streams and
|
||||
subjects, work queues and who takes their asks, who creates each);
|
||||
- vet or tests that fail: run `go vet ./...`, `go vet -tags integration ./...` and `go test ./...` in every
|
||||
touched module, with the siblings placed as the build map's one placement says;
|
||||
- a change to any `module.json` reported without the manifest validator's verdicts (every manifest whose verdict
|
||||
@@ -44,6 +52,16 @@ questions are.
|
||||
principle you know of, name the line and why in a note; the lead brings it to the operator. The code follows the
|
||||
line until the design changes.
|
||||
|
||||
**Read each changed module against the live mesh, and name the order of delivery** (playbook 07 step 2, item 12;
|
||||
the operator, 2026-11-22). Through the mesh MCP server's tools, read what runs on the nodes now: each node's haves of
|
||||
every module the change touches or relies on, and which parts still carry the form the change replaces (the tool
|
||||
runner, the build modules, the node-engine, the indexer and its manifest validator, the grants part). For each, ask
|
||||
whether its running version can take in, judge, build, compose or page the new form. Write a section `Live mesh`:
|
||||
each such part with the build read on each node and the time read, then the order of delivery the change needs (the
|
||||
parts that judge, build, compose or page first, then the modules that use them), each step an ordering edge the
|
||||
delivery plan derives, or a gap of the build and delivery system for the lead. A part on the old form that no step of
|
||||
the order brings over is a finding.
|
||||
|
||||
**Prove it against the live mesh, never a re-creation.** When the change answers a fault seen on the machines,
|
||||
check what it claims against the state the mesh itself uses, read through its tools (the manifest validator's own verdicts in the indexer,
|
||||
the packages state, the store, a node's haves), never against a copy you rebuilt: a manifest validator run without the seat list,
|
||||
@@ -53,5 +71,6 @@ such in the report.
|
||||
Anything else (hardening, a further case, a nicer form) is a note, never a round. Read only: no edits, no git
|
||||
write, no verb that writes, never ssh. Use a temporary directory under `/var/tmp`.
|
||||
|
||||
Answer playbook 07 step 2 item 10's two questions, one line each. Answer **APPROVED at** the full commit ids, or numbered findings each with file:line, the design line it concerns,
|
||||
what is wrong, and the fix; design questions and notes apart. Under 25 lines, glossary words only.
|
||||
Answer playbook 07 step 2 item 10's two questions, one line each; then the list of tests of item 11 and the section
|
||||
`Live mesh` of item 12 (a report without them is not an approval). Answer **APPROVED at** the full commit ids, or numbered findings each with file:line, the design line it concerns,
|
||||
what is wrong, and the fix; design questions and notes apart. Under 40 lines, glossary words only.
|
||||
|
||||
@@ -35,7 +35,11 @@ A fact the build map got wrong (a file moved, a function renamed) you say to the
|
||||
**How you work.** Worktrees from `origin/main` on the branch the handover names, subtasks in the build map's order:
|
||||
one that uses a contract, type, verb or package another subtask adds starts from that subtask's commit. Commit per
|
||||
subtask, its label in the subject and a line `Builds: design NN M §n, …` in the body, locally only: never push, never open a pull request, never call a verb that writes on the mesh (reads are fine). Never
|
||||
ssh, never a shell helper for the mesh. Tests: every change carries a test that fails without it (check it);
|
||||
ssh, never a shell helper for the mesh. Tests: every change carries a test that fails without it (check it), and no test stands in for another part of the
|
||||
mesh (playbook 07 step 2, item 11): none creates a stream, a consumer or a process taking a work queue's asks that the
|
||||
bus module, the grants part or the node-engine should, and none fakes a seat's holder in a whole test; compose what a
|
||||
test needs with the parts' own composers from the module's bus-shape sheet, and a composer you cannot import is a
|
||||
question for the lead;
|
||||
rows or subtests in existing tests where the repository is over the test budget the instructions set; no real
|
||||
sleeping. Run `go vet ./...`, `go vet -tags integration ./...` and `go test ./...` in every touched module as
|
||||
the running checker places siblings (playbook 07). Once per head you report, not per commit, also run the integration tests of
|
||||
|
||||
@@ -1,13 +1,14 @@
|
||||
---
|
||||
name: mesh-preparer
|
||||
description: Prepares one milestone or small fix of the Novox mesh before any code is written (hq playbook 07, the prepare step; playbook 08), from the milestone's part of its design and the design's main file, read whole, then the code each design line lands in - one build map per repository (where each design line lands in code, what exists there today and what relies on it, the subtasks and their order), the list of design questions the design does not answer, and the list of places where a design line and the code disagree. Decides nothing; writes only its build maps and the milestone file's two lists.
|
||||
description: Prepares one milestone or small fix of the Novox mesh before any code is written (hq playbook 07, the prepare step; playbook 08), from the milestone's part of its design and the design's main file, read whole, then the code each design line lands in - one build map per repository (where each design line lands in code, what exists there today and what relies on it, the subtasks and their order), the list of design questions the design does not answer, and the list of places where a design line and the code disagree. Decides nothing; writes only its build maps, the milestone file's two lists and a bus-shape sheet per module.
|
||||
tools: Read, Grep, Glob, Bash, Write, mcp__mesh__mesh_call, mcp__mesh__mesh_describe, mcp__mesh__mesh_search, SendMessage
|
||||
model: opus
|
||||
---
|
||||
|
||||
You prepare one change of the Novox mesh for the lead who started you. The caller's handover names the issue, the
|
||||
design and its milestone part at an hq commit, and where your files go (playbook 07, step 0). You write the build
|
||||
maps and the milestone file's sections `Design questions` and `Design meets code`, nothing else; you call no verb that writes and make no git
|
||||
maps, the milestone file's sections `Design questions` and `Design meets code`, and a bus-shape sheet per module with
|
||||
the test that composes it, in your own worktree, nothing else; you call no verb that writes and make no git
|
||||
write.
|
||||
|
||||
**The design is your only input for what is built.** Read the milestone part and the design's main file whole, at the commit the
|
||||
@@ -38,6 +39,17 @@ code`: the design line, the code (file:line at the commit read, each repository'
|
||||
which of the three it is, and your recommendation, said as one. The lead answers these against the principles before
|
||||
develop starts, as it does the design questions; you answer none.
|
||||
|
||||
**End with a bus-shape sheet per module, composed in a test** (playbook 07 step 0, item 11; the operator,
|
||||
2026-11-22). For each module the milestone adds or changes, write `.work/<slug>/<module>.bus.md`: its manifest
|
||||
sections (each process, its `bus`, `serves` and `requires`), its bus accounts, its streams and their subjects, its
|
||||
work queues and the process that takes each queue's asks, its durable consumers, and who creates each (the bus module
|
||||
from `requires`, the grants part, the module's own process), every row citing its design line. Then judge it in a
|
||||
test in a worktree of your own under `/var/tmp`: the manifest validator with the live seat list, and the grants part's
|
||||
composer and the node-engine's composer (the composition of `mesh-delivery-sdk`) composing the manifests the sheet
|
||||
describes. A refusal is an entry under `Design meets code`; a row no design line gives is a design question; a composer
|
||||
the test cannot import you report to the lead as a gap of the build and delivery system. Name the test and its result
|
||||
at the top of the sheet.
|
||||
|
||||
**Everything the design does not say is a design question, never your answer.** A reader or an effect with no fate,
|
||||
a field's form, a key and who deletes it, a bound, a caller, an owner, a tool for a new state, an interaction whose
|
||||
seat, verb, event or provision the design does not name, a live state that contradicts a design line: list
|
||||
@@ -47,6 +59,7 @@ anything should be, no finding of your own and no ruling; where you think a desi
|
||||
principles, it is a design question too, and you map the line as written.
|
||||
|
||||
Report to the caller in under 30 lines: the build maps' paths, the count of design lines mapped per repository and
|
||||
any line not mapped, the subtasks' order, the design questions and the entries of `Design meets code`, one line each with your
|
||||
recommendation. Glossary
|
||||
any line not mapped, the subtasks' order, the bus-shape sheets' paths and their tests' results, the design questions and the entries of
|
||||
`Design meets code`, one line each with your recommendation, and their count: more than ten together send the
|
||||
milestone back to its design (step 0b, item 5). Glossary
|
||||
words only; a guess is said as one.
|
||||
|
||||
+9
-10
@@ -746,10 +746,16 @@ controller (the planner, the rollout) until release 6 of ADR 0429; from each rel
|
||||
word goes to that entry's *Not:* line with the as-is update after that delivery.
|
||||
- **dry run** — a session's run, before a release is pushed, of the parts that will take it in, build it and merge it,
|
||||
as they run live, on the revision as the merge will make it: in process on the session's machine, reading the mesh
|
||||
and writing nothing there. It holds four items: the live take-in run whole with the seat list it will read, every
|
||||
build against the packages as published, the gate's merge path read for the group, and no item left open (hq
|
||||
playbook 07, step 2b). Not a **try** nor a **run on request**, which the mesh runs and which deliver a verdict; a dry
|
||||
and writing nothing there. It holds five items: the live take-in run whole with the seat list it will read, every
|
||||
build against the packages as published, the gate's merge path read for the group, the reviewed heads delivered once
|
||||
in the lab of one machine from take-in to `delivered`, and no item left open (hq playbook 07, step 2b). A change
|
||||
of a delivery module, the node-engine, the tool runner, the bus module or the SDK's bus packages never skips it. Not a **try** nor a **run on request**, which the mesh runs and which deliver a verdict; a dry
|
||||
run owes the forge nothing and is not a check.
|
||||
- **bus-shape sheet** — the prepare's list, per module a milestone adds or changes, of what the module will be on the
|
||||
bus: its manifest sections, bus accounts, streams and their subjects, work queues and the process that takes each
|
||||
queue's asks, durable consumers, and which part creates each; judged by the manifest validator and composed by the
|
||||
grants part's composer and the node-engine's composer in a test before any code (hq playbook 07, step 0, item 11).
|
||||
Not a **build map**, which says where each design line lands in code.
|
||||
- **trunk commit** — the commit of the trunk a merge check's verdict was judged against: the trunk's head when
|
||||
the build module cloned it. The verdict holds for that commit only, goes out of date when the trunk moves, and
|
||||
is then carried to the new commit (ADR 0323, ADR 0548). Goes at milestone G's delivery with the merge check: a pipeline
|
||||
@@ -1164,11 +1170,6 @@ it should not. **Recorded by** the controller. **Upstream of** Provisioning and
|
||||
- **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.
|
||||
- **allowance** — a port of the packet filter opened by the operator, through the seat, beside the ports derived from
|
||||
the modules' `listens`: set with the `node-packet-filter` seat's verb `allow`, taken back with `disallow`, read with `allowed`, each with
|
||||
who set it, when, why and an optional `until`, at which it is removed, and rendered by the node-engine into a converged node's input chain
|
||||
(design 08 §4, design 33). It is not an `opening`, the resource the node-engine converges through a found firewall.
|
||||
*Not:* ~~pinhole~~ (hq), ~~hand rule~~ (hq)
|
||||
- **intrusion prevention** and **ban** — refusing a source that misbehaved, and the refusal itself; the node seat
|
||||
`node-intrusion-prevention` is of this domain.
|
||||
- **reach** — how far an assignment's endpoint may be reached from: the node, the private network, or
|
||||
@@ -1587,8 +1588,6 @@ renaming one sense, the old sense moves to a *Not:* line and becomes mechanical.
|
||||
| | 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 |
|
||||
| allowance | a port of the packet filter opened by the operator, through the seat | **allowance** | Connectivity |
|
||||
| | the share of model use every session draws on in a week (playbook 07's report) | **weekly allowance** | — |
|
||||
| ticket | an answer's one-time token (ADR 0258) | **answer ticket** | Operator and conversation |
|
||||
| | a question someone must answer | **issue** | The record |
|
||||
| deploy | the per-node part of a delivery plan | **deploy plan** | Delivery |
|
||||
|
||||
@@ -67,22 +67,34 @@ A small fix (one repository, one issue, about an hour of work) follows
|
||||
own indexer and five more modules with the live seat list, and its trunk builds waited on renamed packages only the
|
||||
take-in would publish. The dry run (step 2b) now runs the live take-in, the builds against what is published and the
|
||||
gate's merge path, and holds the push while any item is open.
|
||||
- **A change of the delivery system proven only on the live mesh.** On 2026-11-21 and 2026-11-22 milestone H2 of
|
||||
design 47 was delivered after a review that approved it, and about 25 faults showed only on the machines: the
|
||||
node-engine's composer stripped one manifest section of a process and kept another, so the declaration read refused
|
||||
the milestone's own manifests; a stream's subject was not widened, so an approved registration was never written; a
|
||||
work queue had no process taking its asks; and a durable consumer left behind for each old form set off the grants
|
||||
part's alarm. The tests had passed because they created the streams, consumers and takers of asks the broker should
|
||||
have, or a stand-in for a seat's holder, and the review read the code against the design, not against what the nodes
|
||||
ran: the tool runner, the build modules and the node-engine still carried the old form, and the parts that judge,
|
||||
build and compose had to reach the machines first. The prepare now ends with a bus-shape sheet composed in a test
|
||||
(step 0, item 11), a test that stands in for a part of the mesh is a finding (step 2, item 11), the review reads the
|
||||
live mesh and names the order of delivery (step 2, item 12), and the dry run delivers the reviewed heads once in the
|
||||
lab before any pull request opens (step 2b, item 4; the operator, 2026-11-22).
|
||||
- **A module proven only after it reached the machines.** The mail modules were delivered with unit tests
|
||||
only, then failed live three times (issues 859, 865, 868) and took five more hours of fixes.
|
||||
|
||||
## The shape
|
||||
|
||||
One feature is **one branch name**, **one worktree per repository**, **one pull request per repository**,
|
||||
opened **once**, after the review, and **one check** (ADR 0548). It runs in five steps, with the design completed between the first two (step 0b) and, for a change of what judges, builds or merges it, a dry run between the review and the check (step 2b), and its time is bounded. A milestone has no phases
|
||||
opened **once**, after the review, and **one check** (ADR 0548). It runs in five steps, with the design completed between the first two (step 0b) and, for a change of what judges, builds, composes or delivers it, a dry run between the review and the check (step 2b), and its time is bounded. A milestone has no phases
|
||||
(the operator, 2026-10-17): these are its steps, and a report names the step it is in:
|
||||
|
||||
| Step | What happens | Bound |
|
||||
|---|---|---|
|
||||
| 0. Prepare | from the milestone part and the design's main file, read whole, then the code each design line lands in: where each line lands, what exists there today and what relies on it, as one build map per repository; every design question, the design's silences, listed; and every place where a design line and the code disagree, listed | 15 minutes, longer when what exists is large: code never starts on an incomplete answer |
|
||||
| 0b. Design complete | every design question and every place where design and code disagree is answered: by the lead in one line against the principles, or, where no principle settles it, by the operator or `hq-design-writer` (step 0); each answer is written down (the lead's in the milestone's lead-answers file, the others into the milestone part, playbook 02) and its build map rows added | until the list is empty: develop never starts before |
|
||||
| 0. Prepare | from the milestone part and the design's main file, read whole, then the code each design line lands in: where each line lands, what exists there today and what relies on it, as one build map per repository; every design question, the design's silences, listed; every place where a design line and the code disagree, listed; and a bus-shape sheet per module, composed in a test | 15 minutes, longer when what exists is large: code never starts on an incomplete answer |
|
||||
| 0b. Design complete | every design question and every place where design and code disagree is answered: by the lead in one line against the principles, or, where no principle settles it, by the operator or `hq-design-writer` (step 0); each answer is written down (the lead's in the milestone's lead-answers file, the others into the milestone part, playbook 02) and its build map rows added; more than ten questions send the milestone back to its design | until the list is empty: develop never starts before |
|
||||
| 1. Develop | one fixing agent per repository builds every design line of its build map locally, each commit citing the lines it builds, the whole unit suite before every commit, the integration tests compiled, and once per head it reports those of the packages it touched and their importers run against an embedded bus (below); nothing is pushed | the milestone's issues, 30 minutes each |
|
||||
| 2. Review | one reviewer reads all of it, the local commits, judging the integration tests by reading them against the code; reports go both ways; at most 3 rounds | 15 minutes |
|
||||
| 2b. Dry run | for a release that changes a part judging a change, or a module path, a package or a manifest form the take-in reads: the live take-in run whole with the seat list it will read, every build against the packages as published, the gate's merge path read for the group, and no item left open | until no item is open: nothing is pushed before |
|
||||
| 2. Review | one reviewer reads all of it, the local commits, judging the integration tests by reading them against the code, a test that stands in for a part of the mesh a finding, each changed module read against the live mesh and the order of delivery named; reports go both ways; at most 3 rounds | 15 minutes |
|
||||
| 2b. Dry run | for a release that changes a part judging a change, or a module path, a package or a manifest form the take-in reads, and always for one that changes a delivery module, the node-engine, the tool runner, the bus module or the SDK's bus packages: the live take-in run whole with the seat list it will read, every build against the packages as published, the gate's merge path read for the group, the reviewed heads delivered once in the lab from take-in to `delivered`, and no item left open | until no item is open: nothing is pushed before |
|
||||
| 3. Check | push the reviewed heads once and open the pull requests together; the checker's one check runs the integration tests; no further review unless the check fails | one check run |
|
||||
| 4. Deliver | merge; the source revision moves, each module is built once and wanted on its nodes, its canary first | until the view says the source revision `delivered` |
|
||||
|
||||
@@ -314,7 +326,24 @@ of the prepare the lead names at the next report.
|
||||
Then, under `Design meets code`, every place item 3 found where a design line and the code disagree, each with
|
||||
the design line, the code (file:line at the `origin/main` commit read), which of the three it is (a form the code
|
||||
cannot take, a part the line assumes built that is not, a rule in code the line would break), and the preparer's
|
||||
recommendation, said as a recommendation. The two lists are the prepare's last output and step 0b's input.
|
||||
recommendation, said as a recommendation. The two lists and the bus-shape sheets (item 11) are the prepare's last
|
||||
output and step 0b's input.
|
||||
11. **Write a bus-shape sheet per module, and compose it in a test, before any code** (the operator, 2026-11-22). For
|
||||
each module the milestone adds or changes, `.work/<slug>/<module>.bus.md` lists what the module will be on the bus
|
||||
once the change runs: its manifest sections (each process, its `bus`, `serves` and `requires`), its bus accounts,
|
||||
its streams with their subjects, its work queues with the process that takes each queue's asks, its durable
|
||||
consumers, and for each of these who creates it (the bus module from the module's `requires`, the grants part, the
|
||||
module's own process at its start). Each row cites the design line that gives it; a row no design line gives is a
|
||||
design question (item 10). The sheet is judged as the mesh will judge it, in a test in the preparer's worktree: the
|
||||
manifest validator judges the manifests the sheet describes, with the live seat list, and the grants part's
|
||||
composer and the node-engine's composer (the composition of `mesh-delivery-sdk`) compose them; each must take the
|
||||
sheet as written. A refusal is an entry under `Design meets code`. A composer a test cannot import is a gap of the
|
||||
build and delivery system, said to the lead and built there before develop (the grants part's composer belongs in
|
||||
the SDK, beside the composition of `mesh-delivery-sdk`); never a sheet left unjudged. The sheet is what the
|
||||
developers' tests and the reviewer's reading of the live mesh (step 2, items 11 and 12) hold the change to.
|
||||
How it is checked: every module a build map changes has its sheet, with the test that composed it and its result
|
||||
(`ls .work/<slug>/*.bus.md`); a fault of the bus's shape met after the push that the sheet omits is a miss of the
|
||||
prepare, named at the next report.
|
||||
|
||||
## Step 0b — Design complete
|
||||
|
||||
@@ -339,6 +368,13 @@ answer is written down before the code; 2026-11-11: the lead answers it against
|
||||
answers it.
|
||||
4. **The design is complete** when every entry of both lists names its answering commit. Then step 1 starts, from the milestone
|
||||
part at that commit.
|
||||
5. **More than ten design questions send the milestone back to its design** (the operator, 2026-11-22). When the
|
||||
prepare leaves more than ten entries in `Design questions` and `Design meets code` together, the milestone part is
|
||||
not ready to be built: the lead answers none of them one by one, hands them all to `hq-design-writer` as one
|
||||
amendment of the milestone part (playbook [02](02-graduation.md)), read by the four reviewers by architectural
|
||||
domain, and the prepare runs again on the amended part. Develop starts only from a prepare that left ten or fewer.
|
||||
How it is checked: the milestone file's two lists, counted at the prepare's end (`grep -c`), and the hq commit of
|
||||
the amendment when they held more than ten.
|
||||
|
||||
**A question met later stops only its part.** A developer or the reviewer who meets a question the milestone part
|
||||
does not answer stops the subtasks that need the answer, says the question to the lead with the design line and
|
||||
@@ -371,7 +407,10 @@ an answer no hq commit holds, is a finding of the review (step 2, item 2a).
|
||||
the test calls what the change adds, the agent takes out the change's effect (the line that does it, not the new
|
||||
function), sees the test fail, and puts it back (2026-10-19: a check request's new field was proven by a test of
|
||||
its helper alone, and dropping the field from the request passed every test); `gofmt`, `go vet` and the whole unit suite stay green. **The tests are written from the issue's
|
||||
acceptance criteria**: one test or more per criterion at the level it names, each test's comment citing
|
||||
acceptance criteria**, and **a test never stands in for another part of the mesh** (step 2, item 11): it creates no
|
||||
stream, consumer or taker of a work queue's asks that the bus module or the grants part should create, and fakes no
|
||||
seat's holder in a whole test; it composes what it needs with the parts' own composers, from the bus-shape sheet
|
||||
(step 0, item 11). One test or more per criterion at the level it names, each test's comment citing
|
||||
the criterion it proves by its label (`// 1118/AC2`), and no criterion left without its test; an integration criterion is a test
|
||||
that compiles and is run by the pull request's one check. The integration tests (those that start a store, a bus
|
||||
or a process) are compiled with `go vet -tags integration ./...` while developing and run by that check. **Once per head it
|
||||
@@ -510,15 +549,41 @@ an answer no hq commit holds, is a finding of the review (step 2, item 2a).
|
||||
the record behind it, the lead brings it to the operator as a design question, and the code waits for the answer
|
||||
in the design. How it is checked: the review report has a line for each question with its answer, and the lead reads both before the
|
||||
push; a report without them is not an approval.
|
||||
11. **A test that stands in for another part of the mesh is a finding, by rule** (the operator, 2026-11-22). A test
|
||||
that creates a stream, a consumer or a process taking a work queue's asks where the bus module, the grants part
|
||||
or the node-engine should, or that fakes a seat's holder in a whole test, proves what the test made, not what the
|
||||
mesh will make: on 2026-11-21 milestone H2's tests passed on streams and takers they created themselves, and the
|
||||
live broker made neither. The fix is the test composing what it needs with the parts' own composers (the grants
|
||||
part's and the composition of `mesh-delivery-sdk`), from the module's bus-shape sheet (step 0, item 11); a
|
||||
composer it cannot import is a gap of the build and delivery system, built there in the milestone, never a stand-in
|
||||
kept. A unit test's fake of a function's own collaborator is not this; a stand-in for a part another module
|
||||
holds is. How it is checked: the review report lists every new or changed test that creates bus state or fakes a
|
||||
seat's holder, each with the composer that should make it, and a report without that list is not an approval.
|
||||
12. **Each changed module is read against the live mesh, not only the design** (the operator, 2026-11-22). The
|
||||
reviewer reads, through the mesh MCP server's tools, what runs on the nodes today: each node's haves of every
|
||||
module the change touches or relies on, and which parts still carry the form the change replaces (the tool runner,
|
||||
the build modules, the node-engine, the indexer and its manifest validator, the grants part). For each, it asks
|
||||
whether the running version can take in, judge, build, compose or page the change's new form. Then it names, in
|
||||
its report, **the order of delivery the change needs**: the parts that judge, build, compose or page the new form
|
||||
first, then the modules that use it, each step an ordering edge of the module graph the delivery plan derives
|
||||
(instruction design-it-as-it-should-be), or, where no edge carries it, a gap of the build and delivery system for
|
||||
the lead to bring to the operator. A part still on the old form that no step of the order brings over makes the
|
||||
change wrong. How it is checked: the review report holds a section `Live mesh` naming each node's build read for
|
||||
each such part, with its time, and the order of delivery; the lead copies the order into the milestone file and
|
||||
the dry run (step 2b, item 4) delivers in it. A fault met after the merge from a part on the old form is named at
|
||||
the next report.
|
||||
|
||||
## Step 2b — Dry run (a change of the delivery system, or of what the take-in reads)
|
||||
|
||||
**When it runs.** After the review approves the heads and before the push of step 3, for every release that changes a
|
||||
part judging a change (step 3, item 3: the indexer and its manifest validator, the gate, the builder, a build module,
|
||||
the checker or the pipeline runner, the node-engine, a seat definition), and for every release that adds or renames a
|
||||
module path or a package other modules take, or changes the form of manifests the take-in reads. The prepare step's
|
||||
milestone file says per release whether it runs and why (`Dry run: yes` or `no`, with the reason); the review refuses a
|
||||
group that lists a judging part with no such line. The operator, 2026-11-13: "remember the mistake and make sure our
|
||||
module path or a package other modules take, or changes the form of manifests the take-in reads. **A release that
|
||||
changes a delivery module, the node-engine, the tool runner, the bus module or the SDK's bus packages never skips it**,
|
||||
and no rule is weighed against that (the operator, 2026-11-22: milestone H2's faults would each have shown in one
|
||||
delivery off the machines). The prepare step's milestone file says per release whether it runs and why (`Dry run: yes`
|
||||
or `no`, with the reason); the review refuses a group that lists a judging part with no such line, and a `no` for a
|
||||
release that changes one of the parts just named. The operator, 2026-11-13: "remember the mistake and make sure our
|
||||
pipeline catches this".
|
||||
|
||||
**What it is.** A dry run runs the parts that will take the change in, build it and merge it, as they run live, on the
|
||||
@@ -526,7 +591,7 @@ revision as the merge will make it: in process on the session's machine, reading
|
||||
asking no try and no check. An agent of hq's definitions runs it, read-only on the mesh and on every working copy; the
|
||||
lead writes only the handover. Everything live it uses (the builds the nodes run, the seat list, the published
|
||||
versions, the trunks) is read in the same hour as the push, and read again, with the dry run run again, when a head,
|
||||
a main or a live build moves before the push. Four items, each held before any push:
|
||||
a main or a live build moves before the push. Five items, each held before any push:
|
||||
|
||||
1. **The live take-in, run whole.** The indexer that will take the revision in (the running one, read from the view's
|
||||
reach of its module; for a revision that names another build of the indexer, the running one, which keeps it
|
||||
@@ -554,7 +619,18 @@ a main or a live build moves before the push. Four items, each held before any p
|
||||
another base is moved to the gate's branch or left out of the group, a group the gate holds closed is pushed under a
|
||||
new branch name, and an Approve ask that names fewer members than the group is ended and said to the operator,
|
||||
never answered.
|
||||
4. **No item open.** The dry run's report says of each item what ran, at which heads and on which live builds, and its
|
||||
4. **The reviewed heads delivered once in the lab, from take-in to delivery** (the operator, 2026-11-22). The lab of
|
||||
one machine raises the mesh's four node roles on the session's machine (the control-node's parts, a build node's,
|
||||
the bus module and a node-engine with its tool runner), with an embedded bus and store, from the builds the nodes
|
||||
run now (item 1's reading). The reviewed heads are merged there and run the whole way once: the take-in, the
|
||||
pipeline and its steps, the builds, the grants part's memberships, the compositions, the wants, the node-engine's
|
||||
apply and the tool runner's start, in the order of delivery the review named (step 2, item 12), until the lab's
|
||||
view says the source revision `delivered` and every changed module runs healthy and answers its tools. A step that
|
||||
refuses, holds or stands still is a fault of the release, fixed and reviewed before the push. Where the lab cannot
|
||||
yet raise a part (no bed for it), that is a gap of the build and delivery system, built in the lab in the same
|
||||
milestone or before it and said to the operator; the item is never closed as "not run". The pull requests open
|
||||
only after this item passed.
|
||||
5. **No item open.** The dry run's report says of each item what ran, at which heads and on which live builds, and its
|
||||
counts ("ran: 193 manifests, 0 refused, seat list read at 13:05"). An item said "not run", "not known" or "read, not
|
||||
run" is closed, by running it or by showing why it does not apply, or the push is held: **a dry run with an open
|
||||
item is not a pass**, and no rule is weighed against it. Before the push the lead says to the operator, in one line
|
||||
@@ -568,7 +644,8 @@ take-in publishes; no dry run had built a trunk module against the published pac
|
||||
merged a group one member at a time with no undo, stopped at a member whose base was not main, and asked an Approve
|
||||
while a group was still forming and per member of a closed group.
|
||||
|
||||
**How it is checked.** The milestone file holds a section `Dry run` with each item's result, the reviewed heads it ran
|
||||
**How it is checked.** The milestone file holds a section `Dry run` with each of the five items' result, the lab
|
||||
run's source revision and its `delivered` time among them, the reviewed heads it ran
|
||||
on and its time (`grep -n -A6 '^## Dry run' .work/<slug>/milestone.md`), older than the push (the forge branch's
|
||||
first push of the heads) and with no item open; the pull requests' description names it in one line. A push of a
|
||||
release whose milestone file lists a judging part with no such section, or with an item open, is this step skipped;
|
||||
@@ -676,7 +753,8 @@ a fault met after the merge that an item would have shown is named at the next r
|
||||
4. **The milestone's acceptance is proven by its check.** A milestone that adds or changes a module
|
||||
carries an integration test that starts the module whole, its process against the real bus and store, and
|
||||
shows the milestone's acceptance sentence; the forge's checks run it (ADR 0391 §1, §6). Unit tests alone are not
|
||||
that proof; the mesh has no end-to-end tests yet, and the lab is not used (the operator, 2026-10-16).
|
||||
that proof; the mesh has no end-to-end tests yet, and the lab is used only for the dry run's delivery (step 2b,
|
||||
item 4; the operator, 2026-10-16 and 2026-11-22).
|
||||
**A new manifest word's test goes through the first composition that meets it, not only the verb that fills it.**
|
||||
On 2026-10-19 release 1 of feature mail-sender tested a process's own bus account through `module issue`
|
||||
alone; the first push after mesh-mail declared the process composed a random 40-character stand-in for the
|
||||
@@ -943,8 +1021,15 @@ issues in `fixing` that nobody works on reads to the operator as stuck work.
|
||||
item 6b). A fixing agent started on a file without the section, or an effect of a removed or moved part met only
|
||||
after the delivery, is the prepare step skipped, named in the next detailed report and written into the playbook's
|
||||
lessons here.
|
||||
- A release whose milestone file lists a part judging a change holds a `Dry run` section with all four items closed,
|
||||
older than its push (step 2b); one pushed without it, or with an item open, is that step skipped.
|
||||
- A release whose milestone file lists a part judging a change, or that changes a delivery module, the node-engine,
|
||||
the tool runner, the bus module or the SDK's bus packages, holds a `Dry run` section with all five items closed, the
|
||||
lab's delivery among them, older than its push (step 2b); one pushed without it, or with an item open, is that step
|
||||
skipped.
|
||||
- Every module a build map changes has its bus-shape sheet with the test that composed it (step 0, item 11); a
|
||||
milestone developed from a prepare that left more than ten design questions, with no amendment of its part between,
|
||||
is step 0b item 5 skipped.
|
||||
- Every review report holds the list of tests that create bus state or fake a seat's holder (step 2, item 11) and the
|
||||
section `Live mesh` with the order of delivery (step 2, item 12); a report without either is not an approval.
|
||||
- No issue of a running milestone is sized over an hour in its prepare note; an issue whose fixing agent passes
|
||||
twice its bound was not split.
|
||||
- Every issue of a running milestone has a note from the prepare step naming its files and tests (file:line), how
|
||||
|
||||
@@ -476,11 +476,11 @@ const P = [
|
||||
{n:"07",name:"Features",kind:"build",c:"--build",
|
||||
trig:"Work that changes code across issues or repositories, too large for a small fix.",
|
||||
who:"A lead (larger model), one fixing agent per repository (smaller), one reviewer (larger).",
|
||||
steps:["Prepare: name the branch, make the worktrees, read the milestone part and the design's main file whole, then the code each design line lands in. (new)","List every place where a design line and the code disagree, beside the design questions. (new)","Every agent is one of hq's definitions (mesh-preparer, mesh-developer, mesh-code-reviewer, mesh-watcher); the lead writes only the handover. (new)","The prepare's only output: a build map per repository, each row a design line and where it lands, and the design questions. No rulings. (new)","Design complete: the lead answers every question against the principles; one no principle settles goes to the operator or the design writer; then develop. (new)","Read what exists today from the code and the live mesh: every effect of what is removed or moved, every reader of each, what happens to each and its test. No code before it is complete; the review refuses work without it. (new)","The build map opens with what exists today; subtasks ordered contract first, one writer per file.","Write the findings and acceptance criteria into each issue.","Survey every other reader and writer of each changed value. (new)","Answer three questions in the milestone file: who deletes each new key and stream, how the switch-over is tried on one node first, what the one check does not cover. The review checks them. (new)","List every part the change reaches; copy fixtures from the real writer.","Develop: one agent per repository, one commit per subtask, each citing its design lines; a question stops only its subtask. (new)","A test fails first on behaviour, not on compiling. (new)","Bring each branch up to the trunk; nothing is pushed, no try runs. (new)","Review all of it against the design lines, code no line asks for a finding, reading the integration tests against the code; at most 3 rounds; the report answers the state-and-seams and mesh-agnostic questions. (new)","Dry run, for a change of what judges, builds or merges it: the live take-in run whole with the seat list it will read, every build against the packages as published, the gate's merge path read for the group; an item left open holds the push. (new)","A group pins the group's own mesh-sdk head in every member. (new)","Push the reviewed heads once and read each forge head against the reviewed commit; no draft pull request, no fix round on an open one. (new)","Open one pull request per repository, together, with Reviewed-by and Pushed-by; the one check runs. A failed check is read, fixed, reviewed, pushed once more. (new)","The operator's Approve on Telegram; the group merges in one pass.","Follow the delivery in the status view (moving, settled, stuck, delivered) to done; resolve the issues; clean up. (new)","When the builder cannot deliver its own fix: revert, a build by a session's call, a registration at the terminal, copies kept outside the store; a broken controller is put back by a want the operator writes, a hand build by mesh-hand-compose and a want. (new)"],
|
||||
steps:["Prepare: name the branch, make the worktrees, read the milestone part and the design's main file whole, then the code each design line lands in. (new)","List every place where a design line and the code disagree, beside the design questions. (new)","Every agent is one of hq's definitions (mesh-preparer, mesh-developer, mesh-code-reviewer, mesh-watcher); the lead writes only the handover. (new)","The prepare's only output: a build map per repository, each row a design line and where it lands, and the design questions. No rulings. (new)","Design complete: the lead answers every question against the principles; one no principle settles goes to the operator or the design writer; then develop. (new)","Read what exists today from the code and the live mesh: every effect of what is removed or moved, every reader of each, what happens to each and its test. No code before it is complete; the review refuses work without it. (new)","The build map opens with what exists today; subtasks ordered contract first, one writer per file.","Write the findings and acceptance criteria into each issue.","Survey every other reader and writer of each changed value. (new)","Answer three questions in the milestone file: who deletes each new key and stream, how the switch-over is tried on one node first, what the one check does not cover. The review checks them. (new)","List every part the change reaches; copy fixtures from the real writer.","End the prepare with a bus-shape sheet per module (manifest sections, accounts, streams and subjects, work queues and who takes their asks, who creates each), judged by the manifest validator and composed by the grants part's and the node-engine's composers in a test; more than ten design questions send the milestone back to its design. (new)","Develop: one agent per repository, one commit per subtask, each citing its design lines; a question stops only its subtask. (new)","A test fails first on behaviour, not on compiling. (new)","Bring each branch up to the trunk; nothing is pushed, no try runs. (new)","Review all of it against the design lines, code no line asks for a finding, reading the integration tests against the code; at most 3 rounds; the report answers the state-and-seams and mesh-agnostic questions. (new)","A test that stands in for another part of the mesh (a stream, consumer or taker of asks it creates, a faked seat's holder) is a finding; the review reads each changed module against the live mesh and names the order of delivery: the parts that judge, build, compose or page first. (new)","Dry run, for a change of what judges, builds or merges it: the live take-in run whole with the seat list it will read, every build against the packages as published, the gate's merge path read for the group, the reviewed heads delivered once in the lab of one machine from take-in to delivered; an item left open holds the push, and a change of a delivery module, the node-engine, the tool runner, the bus module or the SDK's bus packages never skips it. (new)","A group pins the group's own mesh-sdk head in every member. (new)","Push the reviewed heads once and read each forge head against the reviewed commit; no draft pull request, no fix round on an open one. (new)","Open one pull request per repository, together, with Reviewed-by and Pushed-by; the one check runs. A failed check is read, fixed, reviewed, pushed once more. (new)","The operator's Approve on Telegram; the group merges in one pass.","Follow the delivery in the status view (moving, settled, stuck, delivered) to done; resolve the issues; clean up. (new)","When the builder cannot deliver its own fix: revert, a build by a session's call, a registration at the terminal, copies kept outside the store; a broken controller is put back by a want the operator writes, a hand build by mesh-hand-compose and a want. (new)"],
|
||||
prod:"One pull request per repository, one source revision delivered, resolved issues, no branch or worktree left.",
|
||||
next:"02 (when it ships)",bounds:"Prepare 15 min · 30 min per issue · review 15 min, ≤ 3 rounds · one check, pushed once",
|
||||
prev:["Pull requests as scratchpads","Context bought again and again","A change built on what was remembered, not on what runs","Review rounds spent on what a run would show","A node agent's bus reads, proven only by review","A dry run with an open item, taken as a pass"],
|
||||
check:"The checker's one status, mesh/check; the review record; the dry run's section in the milestone file; the tracker's move."},
|
||||
next:"02 (when it ships)",bounds:"Prepare 15 min, at most ten design questions · 30 min per issue · review 15 min, ≤ 3 rounds · one check, pushed once",
|
||||
prev:["Pull requests as scratchpads","Context bought again and again","A change built on what was remembered, not on what runs","Review rounds spent on what a run would show","A node agent's bus reads, proven only by review","A dry run with an open item, taken as a pass","A change of the delivery system proven only on the live mesh"],
|
||||
check:"The checker's one status, mesh/check; the review record; the dry run's section in the milestone file, the lab's delivery among its items; the bus-shape sheets; the review's Live mesh section; the tracker's move."},
|
||||
{n:"08",name:"Small fixes",kind:"build",c:"--build",
|
||||
trig:"One issue in one repository, about an hour of work.",
|
||||
who:"The session, with one reviewer on the larger model.",
|
||||
|
||||
@@ -22,7 +22,7 @@ code:
|
||||
- mesh-host internal/apply (the service that reflects a rule set; a whole file handed to its new owner)
|
||||
- mesh-controller cmd/mesh-controller/nodes.go (a token issued for a machine's tunnel key, ADR 0169)
|
||||
- mesh-host cmd/mesh-host/join_tunnel.go (a machine joins through the tunnel, ADR 0169)
|
||||
updated: 2026-11-21
|
||||
updated: 2026-10-14
|
||||
decisions:
|
||||
- "ADR 0241"
|
||||
- "ADR 0117"
|
||||
@@ -36,7 +36,6 @@ decisions:
|
||||
- "ADR 0194"
|
||||
- "ADR 0191"
|
||||
- "ADR 0180"
|
||||
- "ADR 0683"
|
||||
- "ADR 0170"
|
||||
- "ADR 0169"
|
||||
- "ADR 0168"
|
||||
@@ -697,14 +696,10 @@ 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, with allowances set by hand beside
|
||||
them.** The automatic part of a node's open ports is a consequence of what runs on it and who must reach it, not a
|
||||
declaration to keep in step by hand. Beside it, the holder of `node-packet-filter` keeps **allowances**: ports opened
|
||||
by the operator, through the seat's verbs, each with who set it, when, why and an optional expiry, rendered into the same input
|
||||
chain and surviving every render and restart; an allowance is removed at its `until` and said (ADR 0683,
|
||||
the firewall's control verbs, amending ADR 0170; the operator, 2026-11-21; design 47 H's lead
|
||||
answers H-A-304, H-A-305, H-A-307, H-A-308, H-A-310, H-A-312 and H-A-314 to H-A-316). That is true of a converged node; an adopted one keeps the firewall it was found
|
||||
with until it converges, and takes no allowance (design 08 adoption §2 to §6).
|
||||
**Derived from what is assigned here, and from the private network'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).
|
||||
|
||||
**A rule names its source** (ADR 0007).
|
||||
A rule with no source is open, and must say so rather than appear to restrict something. `scope:`
|
||||
@@ -795,25 +790,57 @@ undeclared one does not — then the module is removed and the port closes with
|
||||
rule. *A rule set that is written but never loaded passes every check that reads the file, which
|
||||
is why the check reads packets.*
|
||||
|
||||
### By hand, beside the derived ports
|
||||
### While a predecessor still serves the same thing
|
||||
|
||||
*2026-11-21, ADR 0683.* Deriving every open port from the modules' `listens` left no way to open a port no manifest
|
||||
names (a program the operator runs by hand on the workstation, for a while). One renderer stays: the node-engine
|
||||
composes the filter file, and nothing else writes the input chain.
|
||||
*2026-09-22, ADR 0104.*
|
||||
The mesh's proxy owns the two public ports and derives its routes from what modules contributed, so
|
||||
it cannot stand beside a predecessor's proxy and cannot serve the predecessor's names. During a
|
||||
migration a provision of this shape — one provider, a scarce machine-wide resource — may instead be
|
||||
answered by an **adapter**: a module that provides `route` and writes each contribution into the
|
||||
predecessor's own configuration, pointing at the machine port the contributing module publishes.
|
||||
The predecessor's proxy goes on serving every name and renewing every certificate; the mesh's proxy
|
||||
is taken last, when every route is one the mesh contributed. The adapter is refused on a converged
|
||||
node, and removed when the predecessor's proxy retires. *How it is checked:* the adoption bed takes
|
||||
a module behind the adapter and asserts the name answers and the predecessor's own names still do.
|
||||
|
||||
```
|
||||
caller ── allow / disallow ──▶ node-packet-filter (holder) state allowances, one key per allowance
|
||||
│ event node-packet-filter.allowances-changed (node)
|
||||
▼
|
||||
node-engine ── allowed ──▶ holder composes the filter: derived ports + allowances, input chain only
|
||||
│ writes the filter file; the holder's unit loads it (reload)
|
||||
```
|
||||
### On an adopted node
|
||||
|
||||
The holder keeps each allowance in its own state on the bus and says every change as an event; the node-engine of
|
||||
that node hears it, asks `allowed` and composes the filter again. An unanswered `allowed` refuses the compose and
|
||||
keeps the loaded filter, said once, never read as "nothing opened" (the rule for a generator above). Allowances are
|
||||
rendered only into a converged node's own table. The seat's verbs and event are design 33's (*The firewall seat's
|
||||
verbs*); every line the milestone builds is in [design 08 control-verbs](08-milestones/control-verbs.md).
|
||||
*2026-09-22, ADR 0100.* **The firewall found on the machine stays in force**, and the mesh
|
||||
loads no table there that drops by default or holds an accept — neither genesis's base ruleset nor
|
||||
the derived one. Every base chain at a hook runs and a drop in any is final, whatever the other
|
||||
firewall is written in, so a second, stricter table would close every port the machine serves, and
|
||||
an accept in one would open nothing the found firewall drops. What the mesh needs reachable it
|
||||
declares as **openings**: a port, from where, on the incoming path or the forwarded path — a
|
||||
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
|
||||
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
|
||||
other resource. **The mesh guards its own ports in a table of its own that only refuses** —
|
||||
passing everything by default and holding nothing but refusals, and the found firewall's reload
|
||||
does not touch it. Its ports are derived (ADR 0103): every machine port a
|
||||
*taken* module publishes that the filter admits from the private network only, with the store's
|
||||
port and the broker's management port. A port of a module not yet taken may still be the
|
||||
predecessor's, so it is not guarded; and only packets addressed to this machine are matched, so
|
||||
traffic it routes for others passes. An opening a found rule already answers is not added, so
|
||||
removing it never removes the operator's rule. It refuses those ports except from
|
||||
the private network and the machine itself — loopback and the container runtime's networks, known by the interface a packet arrives on, never by
|
||||
its source address alone — at
|
||||
the prerouting hook, before the container runtime redirects the packet, so it matches the port the
|
||||
packet was sent to, for both address families; the
|
||||
bus, the registry and the hub's port stay reachable from anywhere, as a node enrols and pulls
|
||||
before it has a private-network address. One kind of found firewall is spoken; a machine with none
|
||||
needs no openings, and a machine with another kind is refused adoption. Converging the node refuses
|
||||
while a found container is still held; otherwise it previews what is reachable now — listening
|
||||
sockets and published ports — what will close and which modules it will take, then loads the
|
||||
derived filter in place of the refusal-only table and disables the found firewall without flushing
|
||||
it. *How it is checked:* the adoption bed asserts the found firewall's rules differ only by the
|
||||
mesh's marked rules, that the store is unreachable from off the private network before and after
|
||||
the found firewall reloads and reachable from a container on the node, that a machine not yet enrolled reaches the bus, that a second machine
|
||||
enrols through the openings before and after a reload and a reboot, and that after the flip the
|
||||
declared port is open and the undeclared one closed.
|
||||
|
||||
### It filters what arrives from outside, and not what the machine's own guests send
|
||||
|
||||
@@ -1218,15 +1245,27 @@ The list is worth having in one place, because it is most of the argument:
|
||||
|
||||
## Open
|
||||
|
||||
- **One resolver (ADR 0194), settled** (2026-10-05): ADR 0220 deletes the seat `node-dns-resolver`; every node, the
|
||||
workstation included, asks the one resolver and holds `node-hosts-file` (ADR 0199).
|
||||
|
||||
- **When the hub is down nothing takes over** (ADR 0006): non-co-located paths stop, co-located direct peers and
|
||||
every assigned workload keep running; recovery is restore, before certificate renewal.
|
||||
- **One resolver (ADR 0194).** *Correction of fact,
|
||||
2026-10-05:* no node holds `node-dns-resolver` any more, and
|
||||
ADR 0220 deletes the seat. What stood here before: *"Not built: every node still runs
|
||||
`node-dns-resolver`. The migration's four steps are in the record, in order."* Nor did it
|
||||
stay true that *"the workstation moves to the one resolver only once"* zones and the `hosts` file's
|
||||
holder (ADR 0199)
|
||||
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, together with `06`'s
|
||||
matching question — they were one question. Nothing takes over. WireGuard has no failover, the
|
||||
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
|
||||
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 makes
|
||||
it expressible; nothing here says the private network or the resolver handle it.
|
||||
- **Reporting declared-versus-observed.** ADR 0007 makes the disagreement detectable and does not
|
||||
@@ -1237,6 +1276,28 @@ The list is worth having in one place, because it is most of the argument:
|
||||
the composition is a per-node override rather than the design. The interpolation that would let a
|
||||
module carry a label and a node carry the domain, and the mesh join them, does not yet exist.
|
||||
|
||||
## The hub adopts the predecessor's tunnel
|
||||
|
||||
*2026-09-23, ADR 0105.*
|
||||
|
||||
On an adopted node that is the hub, the private network is not raised beside the tunnel it finds;
|
||||
it **takes it over**: the found interface's private key, its port, its address and range, and every
|
||||
peer it had, carried as peers not yet enrolled. The found interface is stopped, its configuration
|
||||
kept on disk. A predecessor machine sees the same server key at the same endpoint and cannot tell
|
||||
the tunnel changed hands; when it enrols, it keeps the address the tunnel already held for its key.
|
||||
|
||||
The mesh's own addresses are the adopted range's — every binding, hosts entry and endpoint the
|
||||
controller composes follows it, as readers of a setting. ADR 0100's non-overlap rule applies only
|
||||
where a found tunnel is left running beside the mesh's; where it is adopted there is one tunnel.
|
||||
The guard admits the mesh's ports from that one interface, and the predecessor's peers arrive on
|
||||
it.
|
||||
|
||||
*2026-09-27, ADR 0119.* The
|
||||
found configuration is kept only until the take is proven — the found unit down, the mesh's
|
||||
interface up and handshaking with a peer. Then it is removed from where the found unit reads it
|
||||
(its original stays kept), the hold ends, and the predecessor's tunnel cannot be raised again by
|
||||
anything but a person restoring it by hand. Undeclaring the private network does not bring it back.
|
||||
|
||||
## The bus is NATS
|
||||
|
||||
*2026-09-23, ADR 0106. Architecture to be written
|
||||
@@ -1247,13 +1308,3 @@ NATS account with permissions derived from `emits`/`consumes`, declared as confi
|
||||
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.
|
||||
|
||||
## Milestones
|
||||
|
||||
Each milestone's lines are in its part, cited as "design 08 <milestone> §n"; the rest of this file records what was
|
||||
built before milestone parts existed.
|
||||
|
||||
| Milestone | Part | State |
|
||||
|---|---|---|
|
||||
| adoption: a node the mesh adopted, before it converges (ADR 0100, 0103, 0104, 0105, 0119) | [adoption](08-milestones/adoption.md) | delivered |
|
||||
| control-verbs: allowances set by hand beside the derived ports, built in design 47's milestone H (ADR 0683) | [control-verbs](08-milestones/control-verbs.md) | to build |
|
||||
|
||||
@@ -1,79 +0,0 @@
|
||||
---
|
||||
layer: to-be
|
||||
design: 08
|
||||
milestone: adoption (delivered)
|
||||
updated: 2026-11-21
|
||||
decisions:
|
||||
- "ADR 0100"
|
||||
- "ADR 0103"
|
||||
- "ADR 0104"
|
||||
- "ADR 0105"
|
||||
- "ADR 0119"
|
||||
---
|
||||
|
||||
# Design 08, milestone adoption — a node the mesh adopted, before it converges
|
||||
|
||||
**What it built.** How the mesh stands beside what it found on an adopted node: a predecessor's proxy, the found
|
||||
firewall and the predecessor's tunnel, each until the node converges. This part is delivered: it records what was
|
||||
intended, moved whole from the main file when design 08 was put in the shape of playbook 02 (2026-11-21), and no
|
||||
builder reads it again. Cited as "design 08 adoption §n".
|
||||
|
||||
## Lines
|
||||
|
||||
1. **While a predecessor still serves the same thing, an adapter answers the provision** (2026-09-22, ADR 0104).
|
||||
The mesh's proxy owns the two public ports and derives its routes from what modules contributed, so it cannot
|
||||
stand beside a predecessor's proxy and cannot serve the predecessor's names. During a migration a provision of
|
||||
this shape (one provider, a scarce machine-wide resource) may instead be answered by an **adapter**: a module
|
||||
that provides `route` and writes each contribution into the predecessor's own configuration, pointing at the
|
||||
machine port the contributing module publishes. The predecessor's proxy goes on serving every name and renewing
|
||||
every certificate; the mesh's proxy is taken last, when every route is one the mesh contributed. The adapter is
|
||||
refused on a converged node, and removed when the predecessor's proxy retires. *How it is checked:* the adoption
|
||||
bed takes a module behind the adapter and asserts the name answers and the predecessor's own names still do.
|
||||
2. **On an adopted node the found firewall stays in force** (2026-09-22, ADR 0100), and the mesh loads no table
|
||||
there that drops by default or holds an accept: neither genesis's base ruleset nor the derived one. Every base
|
||||
chain at a hook runs and a drop in any is final, whatever the other firewall is written in, so a second, stricter
|
||||
table would close every port the machine serves, and an accept in one would open nothing the found firewall
|
||||
drops.
|
||||
3. **What the mesh needs reachable it declares as openings**: a port, from where, on the incoming path or the
|
||||
forwarded path (a 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 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 other resource. An opening a
|
||||
found rule already answers is not added, so removing it never removes the operator's rule.
|
||||
4. **The mesh guards its own ports in a table of its own that only refuses**: passing everything by default and
|
||||
holding nothing but refusals, and the found firewall's reload does not touch it. Its ports are derived (ADR
|
||||
0103): every machine port a *taken* module publishes that the filter admits from the private network only, with
|
||||
the store's port and the broker's management port. A port of a module not yet taken may still be the
|
||||
predecessor's, so it is not guarded; and only packets addressed to this machine are matched, so traffic it routes
|
||||
for others passes. It refuses those ports except from the private network and the machine itself (loopback and
|
||||
the container runtime's networks, known by the interface a packet arrives on, never by its source address alone)
|
||||
at the prerouting hook, before the container runtime redirects the packet, so it matches the port the packet was
|
||||
sent to, for both address families; the bus, the registry and the hub's port stay reachable from anywhere, as a
|
||||
node enrols and pulls before it has a private-network address.
|
||||
5. **One kind of found firewall is spoken**; a machine with none needs no openings, and a machine with another kind
|
||||
is refused adoption.
|
||||
6. **Converging the node refuses while a found container is still held**; otherwise it previews what is reachable
|
||||
now (listening sockets and published ports), what will close and which modules it will take, then loads the
|
||||
derived filter in place of the refusal-only table and disables the found firewall without flushing it. *How
|
||||
lines 2 to 6 are checked:* the adoption bed asserts the found firewall's rules differ only by the mesh's marked
|
||||
rules, that the store is unreachable from off the private network before and after the found firewall reloads
|
||||
and reachable from a container on the node, that a machine not yet enrolled reaches the bus, that a second
|
||||
machine enrols through the openings before and after a reload and a reboot, and that after the flip the declared
|
||||
port is open and the undeclared one closed.
|
||||
7. **The hub adopts the predecessor's tunnel** (2026-09-23, ADR 0105). On an adopted node that is the hub, the
|
||||
private network is not raised beside the tunnel it finds; it **takes it over**: the found interface's private
|
||||
key, its port, its address and range, and every peer it had, carried as peers not yet enrolled. The found
|
||||
interface is stopped, its configuration kept on disk. A predecessor machine sees the same server key at the same
|
||||
endpoint and cannot tell the tunnel changed hands; when it enrols, it keeps the address the tunnel already held
|
||||
for its key.
|
||||
8. **The mesh's own addresses are the adopted range's**: every binding, hosts entry and endpoint the controller
|
||||
composes follows it, as readers of a setting. ADR 0100's non-overlap rule applies only where a found tunnel is
|
||||
left running beside the mesh's; where it is adopted there is one tunnel. The guard admits the mesh's ports from
|
||||
that one interface, and the predecessor's peers arrive on it.
|
||||
9. **The found tunnel's configuration is kept only until the take is proven** (2026-09-27, ADR 0119): the found
|
||||
unit down, the mesh's interface up and handshaking with a peer. Then it is removed from where the found unit
|
||||
reads it (its original stays kept), the hold ends, and the predecessor's tunnel cannot be raised again by
|
||||
anything but a person restoring it by hand. Undeclaring the private network does not bring it back.
|
||||
@@ -1,107 +0,0 @@
|
||||
---
|
||||
layer: to-be
|
||||
design: 08
|
||||
milestone: control-verbs
|
||||
updated: 2026-11-21
|
||||
code: [mesh-host internal/compose (the filter's compose), mesh-catalog modules/nftables, mesh-networking modules/mesh-connectivity-contracts]
|
||||
decisions:
|
||||
- "ADR 0683"
|
||||
- "ADR 0170"
|
||||
- "ADR 0168"
|
||||
- "ADR 0595"
|
||||
- "ADR 0100"
|
||||
---
|
||||
|
||||
# Design 08, milestone control-verbs — allowances set by hand, rendered beside the derived ports
|
||||
|
||||
**What it builds.** The packet filter of a converged node opens, beside the ports derived from the modules' `listens`,
|
||||
every **allowance** the holder of `node-packet-filter` keeps: a port opened by the operator, through the seat, with
|
||||
who set it, when, why and an optional `until`. The node-engine renders both into the mesh's own table, in the same
|
||||
input chain, at every compose of the filter; an allowance survives every render and restart, and one with an `until`
|
||||
is removed at its `until`, by the kernel in the loaded filter and by the holder in its state. This follows ADR 0683
|
||||
(the firewall's control verbs, amending ADR 0170) and the operator's word of 2026-11-21 20:35 CET (the packet filter's
|
||||
module has tools to control it beside the automatic provisioning from declarations), written from design 47 H's lead
|
||||
answers H-A-304, H-A-305, H-A-307, H-A-308, H-A-312, H-A-314 to H-A-316, H-A-321, H-A-324 and H-A-325. The seat's verbs, its event and
|
||||
its state are design 33 control-verbs; this part holds the render. Cited as "design 08 control-verbs §n".
|
||||
|
||||
**Where.** Built in design 47's milestone H, in one delivery group with design 33 control-verbs, three repositories:
|
||||
the networking repository (the seat's contracts module), the catalog repository (the nftables module, the holder)
|
||||
and the node-engine's repository (the compose of the filter, the verb `converged`). The ordering edge is the served
|
||||
verb: the node-engine asks `allowed`, so the holder serving it comes first in the delivery plan. First use: tcp 8000
|
||||
on the workstation's home-network interfaces.
|
||||
|
||||
## Lines
|
||||
|
||||
1. **The node-engine is the one renderer of the filter file** (H-A-305; P7). At every compose of the packet filter
|
||||
(each compose it makes today, and each one line 3 starts) it asks `<node>/node-packet-filter.allowed` of its own
|
||||
node, within its compose-ask bound, the node-engine's setting `compose-ask-bound`, default 10 s (H-A-314 (5)), and
|
||||
renders the answer's allowances beside the derived ports. The node-engine's manifest invokes
|
||||
`seat:node-packet-filter.allowed` and consumes `node-packet-filter.allowances-changed` (H-A-314 (3), H-A-315 (2)).
|
||||
Nothing else writes the input chain: the holder writes no rule and loads the file as today (`reload`, ADR 0170
|
||||
§3). The derived part is unchanged: the modules' `listens`, the hub's port, the foundation's ports and their
|
||||
sources stay as §4 *What was built* says.
|
||||
2. **Where an allowance is rendered.** In the mesh's own table (family `inet`, name `mesh`), its input chain, after
|
||||
the derived ports' rules and before the chain's drop policy: one accept rule per allowance, matching its protocol
|
||||
and destination port; its interface by name, or for the default set (resolved here at compose, H-A-308 (1)) every
|
||||
input interface that is neither the private network's tunnel nor an outward link (a hub's internet-facing link
|
||||
included; H-A-324), rendered as a negated match on the tunnel and on each outward link the node reports (§4, *It
|
||||
filters what arrives from outside*), so an interface that comes up later is covered and neither the tunnel nor an
|
||||
outward link ever is; the node-engine serves the same classification, the tunnel and the outward links, in its
|
||||
verb `converged` (design 33 control-verbs §10; H-A-325), so one classifier of links serves the render and the holder; an outward link is opened only by an allowance that names it; its source when it has one, for the family of its CIDR, and no
|
||||
source match when it has none (both families). An allowance with an `until` matches its port as the one element of
|
||||
a set of the mesh's table with the `timeout` flag, the element's timeout the time left to its `until` at the
|
||||
compose, at least 1 s, so the kernel closes the port at its `until` even while the holder is away (H-A-315 (4)); a re-render reloads the
|
||||
filter and re-arms the time left, which is the right time (H-A-324).
|
||||
Each rule carries the comment `allowance <key> <at>`, the allowance's key as its answers give it (without the node) and
|
||||
the time it was set (design 33 control-verbs §7, §9). An allowance opens the input path only: a container's published port is
|
||||
forwarded traffic and stays its module's `listens`' (§4, *It filters what arrives from outside*). An allowance and
|
||||
a derived rule on the same port are both rendered; neither removes or narrows the other.
|
||||
3. **The node-engine composes the filter again on every change of the allowances.** It hears the event
|
||||
`node-packet-filter.allowances-changed` on the subject of its own node (design 33 control-verbs §8), asks `allowed`
|
||||
and composes the filter; no timer and no poll. The event's body is not rendered: `allowed`'s answer is the one
|
||||
input, so an event missed is made good at the next compose. The node-engine drops nothing past an `until` on its
|
||||
own clock: the holder's answer is the truth (H-A-314 (6)).
|
||||
4. **An unanswered `allowed` refuses the compose and keeps the loaded filter** (H-A-307 (1), H-A-314 (7), H-A-315
|
||||
(6); the rule for a generator that cannot say what it opens, §4). When `allowed` does not answer within the
|
||||
compose-ask bound or answers an error (the holder not running yet, its tool runner away, no holder on the node, a
|
||||
rolled-back holder that does not serve the verb, a laptop asleep), the node-engine composes no filter file and
|
||||
keeps the one loaded. The refusal is a withheld part in H-A-306's form: the node-engine seat's composition answer
|
||||
gains the field `withheld-parts`, a list of `{part, why}`, set when a compose kept a part because its read did not
|
||||
answer, here `part` `node-packet-filter.allowed`; it is added in the same contracts commit as the verb `converged`
|
||||
(H-A-321). It is said once in the journal and in `<node>/node-engine.composition`, never "nothing opened". The
|
||||
holder's module is not held for it, since an old holder that does not serve `allowed` must still be replaceable;
|
||||
only the filter file resource is kept as it runs. The next `allowances-changed` (the holder says `started` when it starts serving, design 33 control-verbs
|
||||
§8) or the next compose tries again; by hand it is recovered with the node-engine's compose verb, and the composed
|
||||
file is loaded with `reload`.
|
||||
5. **Allowances are rendered only into a converged node's own table** (H-A-307 (2), H-A-312 (1)). On an adopted node
|
||||
the mesh loads no table that holds an accept (design 08 adoption §2) and speaks the found firewall's terms through
|
||||
openings derived from what the filter would be derived from (adoption §3); an allowance is none of them. The holder
|
||||
refuses `allow` and `disallow` there and `allowed` answers none (design 33 control-verbs §3, §6), so the
|
||||
node-engine renders none. After the node converges, allowances are set with `allow` as on any converged node.
|
||||
6. **An allowance is removed at its `until`** (H-A-308 (2), H-A-312 (2), H-A-315 (4)). In the loaded filter the
|
||||
kernel removes its set's element at its `until` (line 2). In the holder's state the holder removes its key at its
|
||||
`until`, says `allowances-changed` with change `expired` and writes a journal line (design 33 control-verbs §11);
|
||||
the event composes the filter again (line 3), which leaves its rule out. A holder away at the `until` removes the
|
||||
key at its next start, before it answers `allowed`; meanwhile the loaded filter is kept (line 4) and the port is
|
||||
already closed by the kernel.
|
||||
7. **An allowance survives every render and restart because it lives in one place.** The holder's state on the bus is
|
||||
the only copy; the rendered file is output, rewritten whole at each compose and never read back. A restart of the
|
||||
node-engine, of the holder or of the machine renders the allowances again from `allowed`; a delivery of either
|
||||
module removes none. A running holder keeps the seat while the seat's definition grows (design 33 control-verbs
|
||||
§13).
|
||||
8. **How it is checked.** The node-engine's compose tests assert on the input chain's text: with no allowance the file
|
||||
is byte for byte today's derived file; with one allowance of the default set, a rule with negated matches on the
|
||||
private network's interface and on each outward link and no positive match on either; with three (one interface named, one with an IPv4 source,
|
||||
one udp), three rules in that form after the derived ones, each with its comment `allowance <key> <at>`; one with an
|
||||
`until` renders a timeout set whose element's timeout is the time left. A fake `allowed` that never answers within
|
||||
the bound leaves the loaded file untouched and one entry in `withheld-parts` of the composition answer, `node-packet-filter.allowed` with its why, and the
|
||||
holder's module still replaceable; an
|
||||
`allowances-changed` for the node composes again and one for another node does not; an allowance the fake answers
|
||||
with an `until` already past is rendered as answered, the node-engine dropping none on its own clock; an adopted
|
||||
node renders none. Live, read in packets as §4 reads them: before `allow`, a machine on the home network is refused
|
||||
on tcp 8000 at the workstation (this holds where the home-network links are outward in the node's render, as the
|
||||
workstation reports them; H-A-314 (8), H-A-324); after `allow` of tcp 8000 with no interface the home-network
|
||||
machine is still refused, since an outward link is not in the default set; after `allow` of tcp 8000 on the workstation's home-network interfaces it
|
||||
reaches the port and a machine reaching the workstation over the private network does not; a node-engine restart
|
||||
keeps it open; after `disallow` neither reaches it; an `allow` with an `until` a minute ahead closes at its `until`
|
||||
with the holder stopped.
|
||||
@@ -1,147 +0,0 @@
|
||||
---
|
||||
layer: to-be
|
||||
design: 33
|
||||
milestone: control-verbs
|
||||
updated: 2026-11-21
|
||||
code: [mesh-networking modules/mesh-connectivity-contracts, mesh-catalog modules/nftables, mesh-host (the node-engine seat's verb converged)]
|
||||
decisions:
|
||||
- "ADR 0683"
|
||||
- "ADR 0170"
|
||||
- "ADR 0168"
|
||||
- "ADR 0565"
|
||||
- "ADR 0595"
|
||||
- "ADR 0625"
|
||||
- "ADR 0636"
|
||||
- "ADR 0246"
|
||||
---
|
||||
|
||||
# Design 33, milestone control-verbs — the packet filter seat's allow, disallow and allowed
|
||||
|
||||
**What it builds.** The node seat `node-packet-filter` serves, beside `rules`, `reload` and `remove` (ADR 0170), three
|
||||
verbs that control the packet filter by hand: `allow`, `disallow` and `allowed`; `rules` lists the allowances beside
|
||||
the ruleset; and the seat says every change of its allowances as the event `node-packet-filter.allowances-changed`.
|
||||
The node seat `node-engine` gains the read verb `converged`. An **allowance** is a port opened by the operator, through
|
||||
the seat, beside the ports derived from the modules' `listens`. This follows ADR 0683 (the firewall's control verbs,
|
||||
amending ADR 0170) and the operator's word of 2026-11-21 20:35 CET, written from design 47 H's lead answers H-A-304,
|
||||
H-A-305, H-A-307, H-A-308, H-A-310, H-A-312, H-A-314 to H-A-321, H-A-324 and H-A-325; P7, P11 and the instruction that tools are
|
||||
how a module is spoken to (every act by hand has its verb, every kept thing its read). How the node-engine renders
|
||||
allowances is design 08 control-verbs. Cited as "design 33 control-verbs §n".
|
||||
|
||||
**Where.** Built in design 47's milestone H, one delivery group with design 08 control-verbs, three repositories: the
|
||||
networking repository (the seat's whole definition in its contracts module), the catalog repository (the nftables
|
||||
module, the holder) and the node-engine's repository (the verb `converged`, and the render of design 08
|
||||
control-verbs). mesh-sdk is not in the group: its TypeScript `state()` asks the runtime's state methods as a Go bundle
|
||||
does (H-A-314 (4)).
|
||||
|
||||
## Lines
|
||||
|
||||
1. **The seat serves six verbs, and every holder serves all six** (§3). `rules`, `reload` and `remove` as ADR 0170
|
||||
§1 to §7 say, with `rules`' answer widened by line 5; `allow`, `disallow` and `allowed` as lines 2 to 4 say. The
|
||||
three are required from the start, in the one delivery group that adds them: §7's three steps (ADR 0246) end for a
|
||||
seat defined in a contracts module (ADR 0683; H-A-310), since the group's check builds the definition and its
|
||||
holder together. Each is a node verb, called `<node>/node-packet-filter.<verb>`. Their classes: `allow` and
|
||||
`disallow` are class `act`, by-caller; `allowed` is class `read` (H-A-315 (2)).
|
||||
2. **`allow` opens a port by hand.** Arguments: `port`, an integer 1 to 65535, required; `protocol`, `tcp` or `udp`,
|
||||
default `tcp`; `interfaces`, a list of interface names, each 1 to 15 characters of letters, digits, `_`, `.` and
|
||||
`-`, default none, which means the default set: every input interface that is neither the private network's tunnel nor an outward link (a hub's internet-facing link
|
||||
included), so an outward link is opened only when named here (H-A-324; design 08 control-verbs §2);
|
||||
`source`, one IPv4 or IPv6 CIDR, default none, which means any; `until`, an RFC 3339 time in the future, optional;
|
||||
`why`, 1 to 500 characters, required. Any other argument is refused. Who set it is the caller as the bus names it on
|
||||
the request, never an argument; for a session's call that is the tool runner's account (H-A-315 (3)). When is the
|
||||
holder's clock at the write. It keeps one allowance per protocol, port and interface (H-A-308 (1)): one key per
|
||||
named interface, each with the same source, who, when, why and `until`, or for none the one key of the default set
|
||||
(line 7), resolved by the node-engine at compose. An `allow` for a key that exists replaces it whole and answers
|
||||
what it replaced.
|
||||
3. **What `allow` refuses**, naming the argument and writing nothing: a caller whose proof is `unproven` (H-A-315
|
||||
(3)); a node that `converged` (line 10) says is adopted, naming the adoption, or a `converged` that does not answer
|
||||
(line 10); a port out of range or not an integer, another protocol, a bad interface name, a source that is not a
|
||||
CIDR, an `until` not in the future, an empty or longer `why`; unless a `source` is given, a port that the loaded
|
||||
input chain accepts only with a source match (`ip saddr` or `ip6 saddr`) and never from any source, read from the
|
||||
chain as `rules` shows it, which covers the store's port, the broker's management port and a port opened to the
|
||||
local network only (H-A-315 (7), H-A-319, ADR 0683 §3; a comment naming each derived rule's scope, so the
|
||||
holder reads scope and not shape, is owed to milestone H2 and not built here); and a write that would make more than `allowances-max` allowances on the node, the
|
||||
holder's setting, default 100 (H-A-314 (5); the bound keeps the rendered chain readable and `allowed` in one
|
||||
answer).
|
||||
4. **`allow` and `disallow` answer what they did, and are written in the hand-act log.** When a named interface is
|
||||
an outward link, as the `outward` list of the `converged` answer it asked for this call names them (line 10),
|
||||
`allow`'s answer sets on that kept allowance the optional field `outward`, the outward link it opens (H-A-324,
|
||||
H-A-325). The holder reads no shape of the loaded table to tell an outward link from the tunnel. `allow` answers each
|
||||
allowance as kept, with its key and what it replaced, and that `allowances-changed` (line 6) was said; `disallow`
|
||||
answers each allowance as removed and that the event was said (H-A-308 (3)). Whether the loaded chain carries an
|
||||
allowance is read with `rules` (line 5). Each call of either is written in the hand-act log (ADR 0565 §10; H-A-315).
|
||||
5. **`disallow` takes back an allowance.** Arguments: `port`, `protocol` and `interfaces` with `allow`'s forms and
|
||||
defaults, which name the same keys (no `interfaces`: the default set's key), and `why`, required as for `allow`;
|
||||
any other argument is refused, the source among them, since it is a property and not part of an allowance's
|
||||
identity. It refuses as `allow` does an `unproven` caller, an adopted node and an unanswered `converged`. It deletes
|
||||
every key named, or, when one does not exist, refuses naming it and deletes none, and says `allowances-changed` with
|
||||
change `disallowed`, its who and its why.
|
||||
6. **`allowed` reads every allowance.** No arguments. It answers every allowance kept for its own node only (line 7),
|
||||
each with its key, `port`, `protocol`, `interface` (absent for the default set), `source` (absent for any), `until`
|
||||
(absent for none), `why`, `by` (who) and `at` (when). The node-engine is its caller at every compose of the filter,
|
||||
within its compose-ask bound (design 08 control-verbs §1). On an adopted node it answers none (H-A-312 (1)), so no
|
||||
answer says a port is open that is not.
|
||||
7. **`rules` lists the allowances beside the ruleset.** Its answer keeps the filter as the machine enforces it (ADR
|
||||
0170 §2) and adds `allowances`: `allowed`'s answer, each marked `loaded` only when a rule of the mesh's table carries
|
||||
its comment `allowance <key> <at>` with an equal `at` (design 08 control-verbs §2), and not loaded otherwise; and
|
||||
every loaded allowance comment whose key is not kept, listed as "loaded, not kept" (H-A-315 (5)). So a kept
|
||||
allowance the loaded filter does not carry, and a loaded one nobody keeps, are both visible in one call.
|
||||
8. **The event `node-packet-filter.allowances-changed`.** The holder says it after every write or delete of its
|
||||
state, in the seat's family `node-packet-filter.events` on the shared events stream, `max-age-days` 7, its subject
|
||||
`allowances-changed.<node>` (as the node-engine seat's `composed.<node>`; H-A-314 (2)). Its body: `node`; `change`,
|
||||
one of `allowed`, `disallowed`, `expired` and `started`; `allowances`, the ones concerned (all of them for
|
||||
`started`); `by` and `why` for `allowed` and `disallowed`; `at`. The holder says `started` once each time it starts
|
||||
serving the seat, so a node-engine that refused a compose for want of an answer composes again. The node-engine
|
||||
of that node hears it (design 08 control-verbs §3); nothing else needs to.
|
||||
9. **The holder keeps the allowances in its own state on the bus, one bucket per machine.** A state `allowances`
|
||||
asked for in the holder's manifest's `requires` by the template `state` (ADR 0595 §1, §2) with the template's
|
||||
option of one bucket per machine, `history` 1, reached only by its owner; a node's holder answers its own node's
|
||||
allowances only (H-A-315 (1)). The per-machine option is one bucket whose keys carry the node, `<node>` and
|
||||
`<node>.>` reached only by that machine's holder, so each holder reads and writes its own node's prefix only
|
||||
(H-A-317). One key per allowance: `<node>.allow.<protocol>.<port>` for the default set (line 2), `<node>.allow.<protocol>.<port>.<interface>` for a named one (the interface is every token
|
||||
after the fourth, since a name may hold a dot). The allowance's key in every answer, in the event and in the rule's
|
||||
comment is the same key without the node, `allow.<protocol>.<port>[.<interface>]`. Its value: `port`, `protocol`, `interface`, `source`, `until`,
|
||||
`why`, `by`, `at`; the source is a property of the value, never part of the key. Only `disallow` and the removal at
|
||||
its `until` (line 11) delete a key; no render, restart or delivery does. The bus module's own tools read the state's
|
||||
fill against its cap. The holder's manifest serves the six verbs and requires the state; it does not list the event in
|
||||
`emits`, which the manifest check refuses for a claimed seat's event: the claim of `node-packet-filter` says the
|
||||
event, and the holder says it with the seat's publish (H-A-314 (3), H-A-317).
|
||||
10. **The node seat `node-engine` gains the read verb `converged`** (H-A-316). It answers the node's convergence
|
||||
state, which the node-engine keeps (ADR 0168): `state`, `adopted` or `converged`; `since`, when it became so, optional and absent for a record written before this change (H-A-324); for an adopted node `found`, the found firewall's kind (H-A-321); and the node's links as the node-engine
|
||||
classifies them for its render: `tunnel`, the private network's interface name, and `outward`, the list of the
|
||||
node's outward links (H-A-325; design 08 control-verbs §2). Class `read`, built in the group's node-engine part, added
|
||||
to the node-engine seat's whole definition. The holder asks it at its start and at every `allow` and `disallow`,
|
||||
bound 10 s (the default of the node-engine's compose-ask bound), and refuses when it does not answer. When it
|
||||
holds no answer (its start's ask did not answer and no `allow` or `disallow` asked since), `allowed` asks
|
||||
`converged` again, bounded by the same 10 s, and refuses when that does not answer, so the node-engine keeps the
|
||||
loaded filter (H-A-318). It never assumes either state and recovers without a restart.
|
||||
11. **An allowance is removed at its `until`, by the holder.** The holder keeps an in-process timer per allowance with
|
||||
an `until`, armed from the watch of its own state at every start (H-A-314 (6)). At an allowance's `until` it
|
||||
deletes the key, says `allowances-changed` with change `expired` and writes a journal line naming the
|
||||
allowance (H-A-308 (2)); no removed entry is kept, so `allowed` never answers one. At its start it first deletes
|
||||
every key whose `until` has passed, with the same event and journal line, then says `started`, then answers
|
||||
`allowed` (H-A-312 (2)). The kernel closes the port at its `until` even while the holder is away (design 08
|
||||
control-verbs §2).
|
||||
12. **The seat's definition becomes whole** (H-A-307 (3), H-A-314 (2); ADR 0625 §1, ADR 0636 §5, §6). It lives in the
|
||||
Connectivity domain's contracts module, `mesh-connectivity-contracts`, in the networking repository: every one of
|
||||
the six verbs with its class, its arguments and its answer form as lines 1 to 7 say, the family and event of line
|
||||
8, the state's value of line 9 as a layout, and the generated Go and TypeScript packages. Its model is the
|
||||
`node-engine` and `git` seats' whole definitions. The node-engine calls `allowed` and hears the event
|
||||
through the Go package; the holder serves the verbs and says the event through the TypeScript one.
|
||||
13. **A running holder keeps the seat while its definition grows** (H-A-315 (6)). A holder running before this group
|
||||
is not withdrawn when the seat's definition gains the three verbs; it holds the seat until it is replaced. While a
|
||||
node's holder does not serve `allowed` (a rollback, a laptop asleep), the node-engine refuses the filter's
|
||||
composes and keeps the loaded filter (design 08 control-verbs §4).
|
||||
14. **How it is checked.** The holder's tests, against a state in memory: `allow` then `disallow` writes the key, then
|
||||
deletes it, with an `allowed` and a `disallowed` event, both answers saying the event was said, and two hand-act
|
||||
log lines; port 0, 65536 and `80a` are refused, as are protocol `icmp`, an `until` in the past, an empty `why`, an
|
||||
unknown argument, an `unproven` caller, the 101st allowance at the default `allowances-max`, and the store's port
|
||||
with no source when the fixture chain accepts it only with a source match (accepted with one); `allow` with no `interfaces` stores no interface, so neither the private network's
|
||||
interface nor an outward link is ever in the defaults; with a fake `converged` whose `outward` lists `eth1`, `allow` naming `eth1` answers that kept allowance with
|
||||
`outward` `eth1`, and one naming another interface answers it without the field; `allow` with two interfaces keeps two keys; a second `allow` of one key answers
|
||||
what it replaced; an allowance is removed at its `until`, says `expired`, writes its journal line, and
|
||||
`allowed` then answers without it; a start with a key past its `until` deletes it and says so before `started` and
|
||||
before its first `allowed`; with a fake `converged` saying adopted, `allow` and `disallow` are refused naming the
|
||||
adoption and `allowed` answers none; with one that never answers, both are refused and `allowed`, holding no answer, asks again and refuses; an allowance kept on one node
|
||||
is absent from another node's `allowed`, and its key in the bucket carries its node while its answer's key does not; `rules` over a fixture ruleset marks an allowance loaded only on an equal
|
||||
`at` and lists a comment with no kept key as "loaded, not kept". The node-engine's test of `converged` answers both
|
||||
states. The seat's contract test holds every holder to the six verbs, and the generated packages to the definition.
|
||||
@@ -1,10 +1,9 @@
|
||||
---
|
||||
layer: to-be
|
||||
status: in-progress
|
||||
status: implemented
|
||||
code: [mesh-controller, mesh-tools]
|
||||
updated: 2026-11-21
|
||||
updated: 2026-10-07
|
||||
decisions:
|
||||
- "ADR 0683"
|
||||
- "ADR 0246"
|
||||
- "ADR 0170"
|
||||
- "ADR 0179"
|
||||
@@ -215,20 +214,6 @@ container to declare a capability. Removing a predecessor's rule set is an opera
|
||||
through the seat, recorded on the bus, instead of a shell on the machine. *How it is checked:* ADR
|
||||
0169's table.
|
||||
|
||||
*2026-11-21, ADR 0683 (the firewall's control verbs, amending ADR 0170); the operator,
|
||||
2026-11-21: the packet filter's module has tools to control it beside the automatic provisioning from declarations.*
|
||||
The seat serves three more verbs: `allow` (a port 1 to 65535, protocol `tcp` by default or `udp`, interfaces by
|
||||
default every input interface but the private network's tunnel and the outward links, a source CIDR by default any, an optional `until`, a
|
||||
required `why`), `disallow` (the same keys) and `allowed` (every **allowance** with who set it, when, why and its
|
||||
`until`, at which it is removed); `rules` lists the allowances beside the ruleset. The node seat `node-engine` gains
|
||||
the read verb `converged` (adopted or converged, since when, the found firewall's kind), which the holder asks before
|
||||
it keeps an allowance. The holder keeps them in its own state on the bus and says
|
||||
every change as the event `node-packet-filter.allowances-changed`, which the node-engine hears to compose the filter
|
||||
again; the node-engine stays the one renderer (design 08 §4, *By hand, beside the derived ports*). The seat's
|
||||
definition becomes whole in its domain's contracts module. Every holder serves the six verbs. Every line is in
|
||||
[design 33 control-verbs](33-milestones/control-verbs.md), from design 47 H's lead answers
|
||||
H-A-304, H-A-305, H-A-307, H-A-308, H-A-310, H-A-312 and H-A-314 to H-A-316; *how it is checked* is its line 14.
|
||||
|
||||
## The intrusion seat's verbs, 2026-10-02
|
||||
|
||||
ADR 0179.
|
||||
@@ -241,15 +226,6 @@ per-module container ADR 0175
|
||||
retires; the verbs and the client are the same code once the node's own runtime loads them as a bundle.
|
||||
The module's own tool beside them reads one jail's effective settings. *How it is checked:* ADR 0179's table.
|
||||
|
||||
## Milestones
|
||||
|
||||
Each milestone not yet delivered has its part, cited as "design 33 <milestone> §n"; what is above was built before
|
||||
milestone parts existed.
|
||||
|
||||
| Milestone | Part | State |
|
||||
|---|---|---|
|
||||
| control-verbs: the packet filter seat's `allow`, `disallow` and `allowed`, built in design 47's milestone H (ADR 0683) | [control-verbs](33-milestones/control-verbs.md) | to build |
|
||||
|
||||
## What this does not settle
|
||||
|
||||
- Which verbs each seat should serve. That is a decision per seat, and the reason to do it slowly: a
|
||||
|
||||
Reference in New Issue
Block a user