diff --git a/03-DESIGN/01-to-be/08-milestones/control-verbs.md b/03-DESIGN/01-to-be/08-milestones/control-verbs.md index 33b1aa6c..bd5fcc21 100644 --- a/03-DESIGN/01-to-be/08-milestones/control-verbs.md +++ b/03-DESIGN/01-to-be/08-milestones/control-verbs.md @@ -21,7 +21,7 @@ input chain, at every compose of the filter; an allowance survives every render 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 +answers H-A-304, H-A-305, H-A-307, H-A-308, H-A-312, H-A-314 to H-A-316 and H-A-321. 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: @@ -48,8 +48,8 @@ on the workstation's home-network interfaces. 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 `, 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 + Each rule carries the comment `allowance `, 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 @@ -61,9 +61,12 @@ on the workstation's home-network interfaces. (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-engine.composition`, never "nothing - opened". The next `allowances-changed` (the holder says `started` when it starts serving, design 33 control-verbs + 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-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 @@ -87,7 +90,8 @@ on the workstation's home-network interfaces. 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 `; 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 + 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 diff --git a/03-DESIGN/01-to-be/33-milestones/control-verbs.md b/03-DESIGN/01-to-be/33-milestones/control-verbs.md index 97eecedb..71dfe661 100644 --- a/03-DESIGN/01-to-be/33-milestones/control-verbs.md +++ b/03-DESIGN/01-to-be/33-milestones/control-verbs.md @@ -23,7 +23,7 @@ the ruleset; and the seat says every change of its allowances as the event `node 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 +H-A-305, H-A-307, H-A-308, H-A-310, H-A-312 and H-A-314 to H-A-321; 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". @@ -54,9 +54,11 @@ does (H-A-314 (4)). 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 + 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.** `allow` answers each @@ -89,19 +91,25 @@ does (H-A-314 (4)). 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..` for the default set (every input - interface but the private network's), `allow...` 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`, + allowances only (H-A-315 (1)). The per-machine option is one bucket whose keys carry the node, `` and + `.>` 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: `.allow..` for the default set (every input interface but + the private network's), `.allow...` 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..[.]`. 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)). + 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; and - for an adopted node `found`, the found firewall's kind. Class `read`, built in the group's node-engine part, added + for an adopted node `found`, the found firewall's kind (H-A-321). 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. + 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 @@ -123,12 +131,12 @@ does (H-A-314 (4)). 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 + 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 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 + 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.