From 1aa887dd2898108e98c1d0fca1a2c3a8ae801e64 Mon Sep 17 00:00:00 2001 From: jochen Date: Wed, 28 Oct 2026 18:25:31 +0100 Subject: [PATCH] Glossary: placement, mesh-placement, placement proposal, candidate and hand-back replace the placement file --- 00-META/glossary.md | 37 ++++++++++++++++++++++--------------- 1 file changed, 22 insertions(+), 15 deletions(-) diff --git a/00-META/glossary.md b/00-META/glossary.md index 7a3ee222..09d432ee 100644 --- a/00-META/glossary.md +++ b/00-META/glossary.md @@ -240,24 +240,31 @@ every other domain has something to run on. **Recorded by** the controller and t ## Placement — what runs on which node **Purpose.** To decide, send and apply what each node runs, and to say why. -**Recorded by** the controller's `inventory` database; from ADR 0549, by the catalog's placement files, which -the indexer reads onto the bus. **Upstream of** Provisioning, Connectivity, Data -and Health and repair. **Decided by** ADR 0100, 0126, 0176, 0181, 0207, 0221, 0252, 0261, 0411, 0539, 0549, 0559. -**Uses:** node, machine, module, seat, manifest (Module), config value (Config). +**Recorded by** the controller's `inventory` database; from ADR 0567, by the seat `mesh-placement`, in its states on +the bus. **Upstream of** Provisioning, Connectivity, Data +and Health and repair. **Decided by** ADR 0100, 0126, 0176, 0181, 0207, 0221, 0252, 0261, 0411, 0539, 0549, 0559, 0567. +**Uses:** node, machine, module, seat, manifest (Module), config value (Config), proposal (Operator and conversation). - **assignment** — a module put on a node. Its config values on that node (module-assignment config, Config) are `mesh-config`'s, never part of what the controller records (ADR 0348 §9). -- **placement file** — the catalog's file for one node: the modules placed on it and, for each, its pins, its - host ports and its bindings to the providers it requires. It changes only by a pull request on the catalog, - and the indexer reads it at each trunk merge into its state `placement`, one key per node, which every reader - of placement watches (ADR 0549 §1 to §3). Until ADR 0547's third milestone the controller's assignments are - kept equal to it. -- **placement candidate** — a placement file of one node as an open catalog pull request has it at its head, - kept by the indexer in its state `placement-candidates` under `.` while the pull request is open. - Every node composes it in **shadow** (composed and compared, never applied) and answers in its own have whether - what it would run is the same; the composition check passes only when every placed node has answered the same - or differs only where the change intends (ADR 0559). Not the indexer's candidates of a group, which are - fingerprints (Delivery). +- **placement** — which module runs on which node, with its pins, host ports and bindings, and what a person + decided of the node, as one key per node in the state `placement` of the seat `mesh-placement`. It changes only by + a placement proposal the operator approves, and no repository holds it or names a node (ADR 0567). Until ADR + 0547's third milestone the controller's assignments are kept equal to it by the holder. + *Not:* ~~placement file~~ (hq) +- **mesh-placement** — the seat, held once for the mesh by the assigner, that keeps placement: its states + `placement`, `proposals` and `candidates`, and its seven verbs `placement`, `proposals`, `propose`, `withdraw`, + `again`, `adopt` and `hand-back`. Only the holder writes its states (ADR 0567). +- **placement proposal** — a change to placement put forward through the verb `propose`: the changes, the revision + of each key they were laid over, the nodes' answers, the verdict and the ask. It takes effect only on the operator's + Approve, and is discarded if declined, expired or withdrawn. A kind of *proposal* (Operator and conversation). +- **placement candidate** — one node's placement as a placement proposal lays it, kept in the state `candidates` + of the seat `mesh-placement` under `.` while the proposal is open. The node composes it in + **shadow** (composed and compared, never applied) and answers in its own have whether what it would run is the + same; the verdict fails only on a refusal or a node that has not answered (ADR 0567). Not the indexer's candidates of + a group, which are fingerprints (Delivery). +- **hand-back** — the operator's verb `hand-back` of the seat `mesh-placement`, answered until the lease write: it + deletes every placement key, and every node returns to the compositions the controller sends. A hand act (ADR 0567). - **pending assignment** — an assignment of a module whose build is still running, kept, and made by the controller when that build registers the module, or ended with why when it does not (ADR 0261).