Designs 08 and 33: the reviews by domain (H-A-314, H-A-315, H-A-316)

This commit is contained in:
2026-11-21 20:43:11 +01:00
parent 654a08b5a0
commit 8fc4f09d8f
5 changed files with 181 additions and 138 deletions
+4 -4
View File
@@ -1164,9 +1164,9 @@ 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 the packet filter keeps open by hand 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 expiry, and rendered by the node-engine into a converged node's input chain
- **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
@@ -1587,7 +1587,7 @@ 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 the packet filter keeps open by hand | **allowance** | 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 |
+3 -3
View File
@@ -700,10 +700,10 @@ program that reads it, and another proxy may implement the same file.
**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 hand 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 expired allowance is removed at the next render and said (ADR 0683,
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). That is true of a converged node; an adopted one keeps the firewall it was found
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).
**A rule names its source** (ADR 0007).
@@ -3,7 +3,7 @@ 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]
code: [mesh-host internal/compose (the filter's compose), mesh-catalog modules/nftables, mesh-networking modules/mesh-connectivity-contracts]
decisions:
- "ADR 0683"
- "ADR 0170"
@@ -15,72 +15,84 @@ decisions:
# 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 hand through the seat's verbs, with who
set it, when, why and an optional expiry. 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 is gone at the first render
after its expiry, said by the holder. 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 and H-A-308. The seat's verbs, its event and
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, H-A-315 and H-A-316. 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: 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 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.
**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, bound 10 s, and renders the answer's allowances beside the derived ports. 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.
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 an allowance with no interface (the default set, resolved here at
compose, H-A-308 (1)) every input interface but the private network's, rendered as a negated match on that one interface (so an interface that comes up later is
covered and the tunnel never is); its source when it has one, for the family of its CIDR, and no source match when
it has none (both families). Each rule carries the comment `allowance <key>`, the allowance's key in its state
(design 33 control-verbs §7), which is how `rules` tells a loaded allowance (design 33 control-verbs §5). 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.
and destination port; its interface by name, or for the default set (resolved here at compose, H-A-308 (1)) every
input interface but the private network's, rendered as a negated match on that one interface, so an interface that
comes up later is covered and the tunnel never is; 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)).
Each rule carries the comment `allowance <key> <at>`, the allowance's key in the holder's state 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` whose node is its own (design 33 control-verbs §6), 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.
4. **An unanswered `allowed` refuses the compose and keeps the loaded filter** (H-A-307 (1); the rule for a generator
that cannot say what it opens, §4). When `allowed` does not answer within its bound or answers an error (the holder
not running yet, its tool runner away, no holder on the node), the node-engine composes no filter file, keeps the
one loaded, and says it once in the outcome of its compose of the filter, read with `<node>/node-engine.composition`
for the holder's module: the refusal and the reason, never "nothing opened". It says it again only after a compose
with an answer in between. The next `allowances-changed` (the holder says one when it starts serving, design 33
control-verbs §6) or the next compose tries again.
`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 holder asked
`node-packet-filter.allowed`: said once in the journal and in `<node>/node-engine.composition`, never "nothing
opened". 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 §9), so the node-engine
renders none. After the node converges, allowances are set with `allow` like on any converged node.
6. **An expired allowance is gone at the next render, and said by the holder** (H-A-308 (2)). At its `until` the
holder deletes its key, says `allowances-changed` with change `expired` and writes a journal line (design 33
control-verbs §4, §6); the event composes the filter again (line 3), so the port closes when the expiry passes, not
at an unrelated compose. No expired entry is kept, and `allowed` never answers one. While the holder is away, the
loaded filter is kept (line 4), so a port whose allowance expires then stays open until the holder is back and
removes it at its start (design 33 control-verbs §10); that is accepted and said (H-A-312 (2), ADR 0683), rather
than closing every port of the filter.
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.
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 no interface, a rule with the negated match on
the private network's interface and no positive match on it; 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. A fake `allowed` that
never answers leaves the loaded file untouched and one refusal in the outcome; an `allowances-changed` for the
node composes again and one for another node does not; an allowance past its `until` is absent from the render; an
adopted node renders none. Live, read in packets as §4 reads them: after `allow` of tcp 8000 on the workstation's
home-network interfaces, a machine on the home network reaches the port and a machine reaching the workstation
over the private network does not; after `disallow` neither does; a node-engine restart between the two keeps it
open.
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 the negated match on the
private network's interface and no positive match on it; 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 withheld part in the composition read; 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 (today's render accepts every link that is neither outward nor the tunnel, so the
test proves the drop first and fails there until it holds, H-A-314 (8)); 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.
+103 -74
View File
@@ -3,10 +3,12 @@ layer: to-be
design: 33
milestone: control-verbs
updated: 2026-11-21
code: [mesh-networking modules/mesh-connectivity-contracts, mesh-catalog modules/nftables, mesh-sdk (TypeScript state)]
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"
@@ -18,88 +20,115 @@ decisions:
**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`.
An **allowance** is a port opened by hand 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 and H-A-308; P7 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".
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, H-A-315 and H-A-316; 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: the networking
repository (the seat's whole definition in its contracts module), the catalog repository (the nftables module, the
holder) and, where line 7 finds the gap, mesh-sdk's TypeScript side.
**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>`.
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 every input interface but the private network's (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; 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. It refuses,
naming the argument and writing nothing: 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`, and a write that would
make more than 100 allowances on the node (the bound keeps the rendered chain readable and `allowed` in one
answer). It answers with each allowance as kept, with its key and what it replaced, and that `allowances-changed` (line 6)
was said (H-A-308 (3)); whether the loaded chain carries it is read with `rules` (line 5).
3. **`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
deletes every key named, or, when one does not exist, refuses naming it and deletes none. It answers with each
allowance as removed and that `allowances-changed` was said with change `disallowed`, its who and its why.
4. **`allowed` reads every allowance.** No arguments. It answers every allowance kept on the node, each with its key,
`port`, `protocol`, `interface` (absent for every input interface but the private network's), `source` (absent for
any), `until` (absent for none), `why`, `by` (who) and `at` (when). At an allowance's `until` the holder removes its key
from its own state, by a timer on that state, says `allowances-changed` with change `expired` and writes a journal
line naming the allowance (H-A-308 (2)); the expired entry is not kept, so `allowed` never answers one, and the
filter closes the port then (design 08 control-verbs §6). The node-engine is its caller at every compose of the filter, bound 10 s.
5. **`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` when a rule of the mesh's table carries its
comment `allowance <key>` (design 08 control-verbs §2) and not loaded otherwise, so a kept allowance the loaded
filter does not carry is visible in one call.
6. **The event `node-packet-filter.allowances-changed`.** The holder says it after every write or delete of its
state, as a family of the seat on the shared events stream, its subject carrying the node. Its body: `node`;
`change`, one of `allowed`, `disallowed`, `expired` and `started`; `allowances`, the ones concerned (all of them for
`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`; a port that a derived rule of the loaded mesh table
admits from the private network only (the store's port, the broker's management port), unless a `source` is given
(H-A-315 (7), ADR 0683 §3); 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.** `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.
7. **The holder keeps the allowances in its own state on the bus.** A state `allowances` asked for in the holder's
manifest's `requires` by the template `state` (ADR 0595 §1, §2), reached only by its owner. One key per allowance:
`allow.<protocol>.<port>` for the default set (every input interface but the private network's), `allow.<protocol>.<port>.<interface>`
for a named one (the interface is every token after the third, since a name may hold a dot). 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 an expiry (line 4) delete a key;
no render, restart or delivery does. The bus module's own tools read the state's fill against its cap. When
mesh-sdk's TypeScript side gives a module no state yet, that is built there first and the holder uses it, never a
file or a store of its own (H-A-305).
8. **The seat's definition becomes whole** (H-A-307 (3); 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 arguments and its answer form as lines 2 to 5 say, the event of line 6 with its family on the shared events
stream, the state's value of line 7 as a layout, and the generated Go and TypeScript packages, as the private
network's seat has them. 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.
9. **On an adopted node the holder keeps no allowance** (H-A-312 (1); ADR 0683). `allow` and `disallow` are refused
there, naming the adoption (the mesh speaks the found firewall's terms, design 08 adoption §2, §3), and `allowed`
answers none, so no answer says a port is open that is not. Whether its node is adopted is the node's convergence
state, which the node-engine keeps (ADR 0168); the verb that answers it to the holder is not yet named (a design
question for the lead).
10. **At every start the holder removes every expired allowance first** (H-A-312 (2)). Before it answers `allowed`,
it deletes every key whose `until` has passed, writes a journal line for each, and says `allowances-changed` with
change `expired` for them, then `started` (line 6).
11. **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; port 0, 65536 and `80a` are refused, as are protocol `icmp`,
an `until` in the past, an empty `why`, an unknown argument and a 101st allowance; `allow` with no `interfaces`
stores no interface, so the private network's interface is never in the defaults; an allowance whose `until` passes is
deleted from the state at that time, says `expired` and writes its journal line, and `allowed` then answers
without it; a second `allow` of one key answers what it replaced; `allow` with two interfaces keeps two keys; `rules` marks an allowance with no rule in a fixture
ruleset as not loaded; a start says `started`, and a start with a key past its `until` deletes it and says
`expired` before its first `allowed` answers; on a node reported adopted, `allow` and `disallow` are refused naming
the adoption and `allowed` answers none. The seat's contract test holds every holder to the six verbs, and
the generated packages to the definition.
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)). One key per allowance: `allow.<protocol>.<port>` for the default set (every input
interface but the private network's), `allow.<protocol>.<port>.<interface>` for a named one (the interface is every
token after the third, since a name may hold a dot). 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, emits the event and requires the state (H-A-314
(3)).
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; and
for an adopted node `found`, the found firewall's kind. 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: it never
assumes converged.
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 (accepted with one); `allow` with no `interfaces` stores no interface, so the private network's
interface is never in the defaults; `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; an allowance kept on one node
is absent from another node's `allowed`; `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.
@@ -220,12 +220,14 @@ through the seat, recorded on the bus, instead of a shell on the machine. *How i
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, 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
expiry); `rules` lists the allowances beside the ruleset. The holder keeps them in its own state on the bus and says
`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 and H-A-308; *how it is checked* is its line 9.
[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