Glossary: placement, mesh-placement, placement proposal, candidate and hand-back replace the placement file

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 `<group>.<node>` 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 `<proposal>.<node>` 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).