diff --git a/03-DESIGN/01-to-be/32-what-a-module-declares.md b/03-DESIGN/01-to-be/32-what-a-module-declares.md index c55a817e..f91004cd 100644 --- a/03-DESIGN/01-to-be/32-what-a-module-declares.md +++ b/03-DESIGN/01-to-be/32-what-a-module-declares.md @@ -18,6 +18,7 @@ decisions: - "ADR 0609" - "ADR 0612" - "ADR 0613" + - "ADR 0618" - "ADR 0606" - "ADR 0595" - "ADR 0596" @@ -516,10 +517,14 @@ value it holds under the old name to the new name in its own state, without the module reports applied a build of it that reads the new name. mesh-config hears the status view's `delivered` events and, at its start and on each, asks its `node_haves` for every node, away ones included, since `delivered` counts only the nodes present (design 47); until then mesh-config answers both names. A node away when the last - `delivered` was said should close its window when it returns, with no other delivery: what wakes mesh-config then - is to be decided in ADR 0618 (reserved), the node-engine seat's event for a node's stated manifest-reads, said also - on its return, as for the old seat name (design 51), never a watch of the node-engine's have state (ADR 0596). - **Until ADR 0618 is accepted**, such a node closes the window on the next `delivered`, whichever delivery says it. A node holding a window open + `delivered` was said should close its window when it returns, with no other delivery: mesh-config also wakes on + the node-engine seat's event `mesh.seat.node-engine.event.manifest-reads-changed`, said when a node's stated + capabilities change and when it returns after being away (ADR 0618 §4), as for the old seat name (design 51), and + on it reads that node's stated capabilities through the seat's verb `manifest-reads` (ADR 0618 §3) and its applied + builds through `node_haves`, never a watch of the node-engine's have state (ADR 0596). ADR 0618 does not cover a + returned node that applies the module's new build only after its return event, since that build changes what the + module reads, not what the node-engine states: such a node closes the window on the next `delivered`, whichever + delivery says it. A node holding a window open for seven days is mesh-config's finding naming the node, cleared when the window closes; `config_rename_close` drops a node from a window by hand, recorded as a hand act. - **The checker asks the seat, never the module.** The seat `mesh-config` gains the optional verb `renames` (the @@ -572,8 +577,8 @@ holder that does not serve it refuses `renamed-from` naming the verb, one meetin `renamed-from` naming the nodes, and a check that cannot ask fails saying so; `retire` with the warrant removes the secret and emits `retired` and `own-retired`, without it, with a warrant for another name, or from a caller not on the list it is refused; a waiter on the vault's `rotated` or `own-replaced` does not wake on `own-retired`; a node that was away, -returning with a build that reads the new name, closes the rename window on the next `delivered` (until ADR 0618 is -accepted); `config_rename_close` drops a node from a window and records the hand act; a window held seven days and a +returning with a build that reads the new name, closes the rename window on its `manifest-reads-changed` event when +it applied that build before the event (ADR 0618 §4), and on the next `delivered` when it applies it after; `config_rename_close` drops a node from a window and records the hand act; a window held seven days and a retirement held seven days each write their finding naming the node, cleared when it closes. ### The mesh delivery cases this design carries diff --git a/03-DESIGN/01-to-be/51-the-registries-keep-what-is-named.md b/03-DESIGN/01-to-be/51-the-registries-keep-what-is-named.md index 2fd24210..f140f711 100644 --- a/03-DESIGN/01-to-be/51-the-registries-keep-what-is-named.md +++ b/03-DESIGN/01-to-be/51-the-registries-keep-what-is-named.md @@ -18,6 +18,7 @@ decisions: - "ADR 0614" - "ADR 0613" - "ADR 0617" + - "ADR 0618" - "ADR 0606" - "ADR 0607" - "ADR 0610" @@ -79,11 +80,13 @@ it open for seven days is a finding naming the node, cleared when the window clo `distribution`'s own family `distribution.events`, kept seven days and capped at 16 MiB, dropping its oldest when full (it carries a handful of events per window), never on a seat's `.events`: it is one module's window, not the seats' contract. A node away when the last `delivered` was said should close the window when it returns and -applies the new build, with no other delivery: what wakes `distribution` then is to be decided in ADR 0618 -(reserved), the node-engine seat's event for a change of a node's stated manifest-reads and the delivery view's read -of them, never a watch of the node-engine's have state (ADR 0596). **Until ADR 0618 is accepted**, such a node closes -the window on the next `delivered`, whichever delivery says it: `distribution` asks `node_haves` then, finds the -returned node's new build, and closes. `cargo-package-registry` stays +applies the new build, with no other delivery: `distribution` also wakes on the node-engine seat's event +`mesh.seat.node-engine.event.manifest-reads-changed`, which each node-engine says when the capabilities it states +change and when its node returns after being away (ADR 0618 §4), and on it reads that node's stated capabilities +through the seat's verb `manifest-reads` (ADR 0618 §3), and its applied build through `node_haves`, never a watch of +the node-engine's have state (ADR 0596). A returned node that then applies the build whose node-engine reads the new +names says the event again, as its stated capabilities change, so ADR 0618 covers every node of this window and no +`delivered` is waited for. `cargo-package-registry` stays named, without a holder, until a build module publishes cargo packages. **One contract, a seat definition** (design 26, *A seat's definition*). Verbs: `publish`, `publish-part` (ADR 0611), `versions`, `remove` (a @@ -373,14 +376,16 @@ publish of mesh-sdk or `mesh-contracts` triggers their users (ADR 0614 §6). The build and adds none (ADR 0613 §1). ADR 0614 bounds nothing here; a bound, such as a settle before building a fingerprint whose inputs still move, is a question for a record, put to the operator, and is not designed here. -**The node-engine's own build keeps the old reference form** until every node-engine states the capability to read -the new one: a node-engine away across the milestone must be able to read the build it wakes to, or it could never -update itself (ADR 0603 §7, §9). The builder writes the node-engine's done key in the old form until the stated -capabilities show it on every node; this is a window like the old seat name's. What should wake the builder for a -node that returns is to be decided in ADR 0618 (reserved): the node-engine seat's event for a change of a node's stated -manifest-reads and the delivery view's read of them, never a watch of the node-engine's have state (ADR 0596). **Until -ADR 0618 is accepted**, the builder hears the status view's `delivered` events, asks `node_haves` at its start and on -each, and a node that was away closes the window on the next `delivered`. Its tool `builder_old_form` lists whether the +**The node-engine's own build keeps the old reference form** until every present node-engine states the capability +to read the new one (ADR 0618 §2): the builder writes a new reference form, in the node-engine's done key as in every +other build's, only once every node-engine on a node present states it, so no build, the node-engine's own included, +needs a form no running node-engine reads (ADR 0603 §7, §9). Each build names with it the reader capabilities its +forms need, and the assigner holds a node's want while that node's engine does not state one (ADR 0618 §1), so a node +that was away is held, never handed a form it cannot read. This is a window like the old seat name's. The builder +reads each node's stated capabilities through the node-engine seat's verb `manifest-reads` (ADR 0618 §3) at its start, +and wakes on the seat's event `mesh.seat.node-engine.event.manifest-reads-changed`, said when a node's stated +capabilities change and when the node returns after being away (ADR 0618 §4), never on a watch of the node-engine's +have state (ADR 0596) and never on a timer. Its tool `builder_old_form` lists whether the window is open and the nodes whose node-engine does not yet state the capability, and drops a retired node from it by hand, recorded as a hand act; a node holding it open for seven days is the builder's finding naming the node, cleared when the window closes. Closing it says so in the build log and emits `old-form-closed` (the time, the nodes that held @@ -415,8 +420,8 @@ reports (ADR 0610 §4). The revert's order is the module graph's, as the move's is delivered before a build module's reverted build only where that build module's reverted manifest requires or invokes something only `distribution`'s reverted build offers; the milestone's prepare step checks the build modules' manifests for such an edge. The done keys written in the new form stay in the builder's state after a -revert and are not built again for their form; whether an older reader can read them is to be decided in ADR 0618 -(reserved). **On a fresh mesh** the foundation's bootstrap (research 075) pushes the holders' own images +revert and are not built again for their form; each names the forms it needs, so a node whose node-engine does not +state them is held by the assigner, never handed them (ADR 0618 §1). **On a fresh mesh** the foundation's bootstrap (research 075) pushes the holders' own images with a one-off credential of the bootstrap, discarded once the holders serve `publish`. ### Acceptance tests @@ -466,7 +471,7 @@ test). module publishing through the seats, and refused after, naming `publish`, with `direct-writes-closed` emitted and its log line written; `registry_direct_writes` names the node still running an old build module, and drops it by hand with a hand act; a node that was away, returning with the new build, closes the old seat name's window on - the next `delivered` (until ADR 0618 is accepted); a waiter on a build's `published` does not wake on `held`, + its `manifest-reads-changed` event with no `delivered` said (ADR 0618 §4); a waiter on a build's `published` does not wake on `held`, `released`, `old-name-closed` or `direct-writes-closed`. - **Builder, added for the milestone, integration** (cases of the builder's whole-module test): with the seat's holder down at a first claim, a bundle's trunk build is built unnumbered and published by its digest, the holder's @@ -477,8 +482,9 @@ test). clears (no timer runs), and is then numbered and published by version; `builder_floor_again` asks the three sources at once and records the hand act; the node-engine's done key stays in the old form while one node's node-engine lacks the capability and is written in the new form once every node states it, `builder_old_form` - naming that node meanwhile and dropping it by hand with a hand act; a node that was away, returning with the - capability, closes that window on the next `delivered` (until ADR 0618 is accepted), with `old-form-closed` emitted + naming that node meanwhile and dropping it by hand with a hand act; a present node gaining the capability closes + that window on its `manifest-reads-changed` event with no `delivered` and no timer (ADR 0618 §2, §4), while a node + away is held by the assigner from builds in the new form (ADR 0618 §1), with `old-form-closed` emitted and its build-log line written, and a waiter on a build's end does not wake on it; with the image's own seat silent at the claim of `distribution`'s own image, the image is still built, published by its digest, and numbered once its new build answers (ADR 0617 *How it is checked*).