Glossary: the build seat, the build queue and the build capacity as asks on a language's streams, and the build module (issue 1788)

00-META/glossary.md

@@ -403,11 +403,11 @@ and the operator act. **Recorded by** the controller's `identity` and `licences`
 back when it fails. The domain is continuous integration and delivery, named **delivery**, and its parts live in
 the repository `mesh-delivery` (ADR 0429 §2). **Recorded by** the `mesh-delivery` module (deliveries) and the
 controller (the planner, the rollout) until release 6 of ADR 0429; from each release on, by the parts it builds. **Downstream of** Module, Core, Health and repair and Data.
-**Decided by** ADR 0162, 0218, 0236, 0237, 0238, 0239, 0250, 0267, 0270, 0276, 0323, 0401–0408, 0428, 0429, 0444–0447.
+**Decided by** ADR 0162, 0218, 0236, 0237, 0238, 0239, 0250, 0267, 0270, 0276, 0323, 0401–0408, 0428, 0429, 0444–0447, 0524–0530.
 **Uses:** module, node, declaration and send (Placement), health (Health and repair), person.
 
 - **merge check** — what a pull request carries before it may merge, judging the merge of its head into a
-  named **trunk commit**, made in the builder's own clone and never pushed (ADR 0323). One status,
+  named **trunk commit**, made in a clone of its own on a build node and never pushed (ADR 0323). One status,
   `mesh/check`, written by the checker: the change's tests, run by the language's build module, and the
   **composition check**; for a delivery group, one verdict on every member's head (ADR 0445, ADR 0447). Before
   release 4 of ADR 0429 a pull request carried two statuses, one for the modules the change touches and one
@@ -421,20 +421,27 @@ controller (the planner, the rollout) until release 6 of ADR 0429; from each rel
   everything its tests read, written once and read-only; a check takes it instead of running an unchanged
   package (ADR 0444).
 - **trunk commit** — the commit of the trunk a merge check's verdict was judged against: the trunk's head when
-  the build seat cloned it. The verdict holds for that commit only, and goes out of date when the trunk moves
+  the build module cloned it. The verdict holds for that commit only, and goes out of date when the trunk moves
   (ADR 0323).
-- **build seat** — the seat whose holder builds modules, `node-build-agent`; its holder on a node is the
-  **builder**. Any node may hold the seat, so there is no build node by nature
-  (ADR 0237).
+- **build seat** — a language's node seat, held on a node by that language's build module: `node-build-go`,
+  `node-build-node` and `node-build-image` (ADR 0525 §2). Its accepted kinds are the **build streams**, and its
+  verbs `current`, `pause` and `resume` serve that node's pulls. It replaces the seat `node-build-agent`, retired
+  in R4g (ADR 0525 §10). Any node may hold it, and a node whose **build capacity** is above zero builds, so there is
+  no build node by nature (ADR 0237).
   *Not:* ~~build machine~~
-- **build queue** — the builds waiting to run, kept by the bus as three work queues a builder takes in order:
-  delivery builds, then checks of pull requests whose Approve is asked or given (ADR 0421 §10), then every other check; each check queue keeps one
-  request per pull request, the newest (ADR 0406); one entry in it is a
-  **build request**.
-  The queue's verbs still say *ask* for an entry; the conversation's ask is another thing
-  (see [Homonyms](#homonyms)).
+- **build queue** — the build requests waiting to run, kept by the bus alone: per language, the work-queue streams
+  `delivery`, `check` and `recheck`, which a build module pulls from, deliveries first, while its node has a free
+  slot of the build capacity (ADR 0525 §1, §4; ADR 0536 §4). No part keeps a list of them: the controller's queue
+  and its verbs are gone, and a stream's backlog and the age of its oldest request are read from its consumers
+  (ADR 0525 §9). One entry in it is a **build request**, an ask on a build stream for one whole job on one node;
+  the conversation's ask is another thing (see [Homonyms](#homonyms)).
+- **build capacity** — how many build requests a node's build modules hold at once: a setting of the node that the
+  build modules read, and 0 pulls nothing (ADR 0525 §5). Not a seat's capacity (**capacity**, Module).
+- **build module** — the module of one language that does the build steps for it on a node (fetch, build, digest,
+  test), claiming that language's build seat: `mesh-build-go`, `mesh-build-node` and `mesh-build-image`. It pulls the
+  build requests of its language and writes each step's end on its own key (ADR 0525 §3, §6). Not the **builder**.
 - **package** — what code resolves when it is **compiled**: an npm/cargo/pypi dependency, by **version**.
-  Served by the **package-registry** (gitea). Only a builder talks to it.
+  Served by the **package-registry** (gitea). Only a build module talks to it.
 - **artifact** — anything a build produces and the mesh delivers to a node by **digest**: an `image`, a
   mirrored `upstream` image, a `bundle` of the module's own code, an `archive`. Served by the
   **artifact store**, an OCI registry that holds every kind as content-addressed blobs
@@ -478,7 +485,7 @@ controller (the planner, the rollout) until release 6 of ADR 0429; from each rel
   lone delivery (ADR 0401). Work is never held back on a branch other than a trunk: the trunk is what runs.
   *Not:* ~~release branch~~ (hq)
 - **toolchain** — a language's compiler and tools, installed by that language's build module on every node holding
-  the build seat, pinned to one version that is the same on every builder; its version is part of a build's reuse
+  its build seat, pinned to one version that is the same on every build node; its version is part of a build's reuse
   key (ADR 0405). No longer an image.
 - **delivery plan** — what a delivery does to the mesh: its **build plan** (the modules it moves and
   their dependents, in tiers), its **deploy plan** (per node, what it receives and what waits for a
@@ -502,7 +509,7 @@ controller (the planner, the rollout) until release 6 of ADR 0429; from each rel
   and writes keys and never calls another part (ADR 0429 §1). Each key has one writer; the operator's
   credential may also write a want, the one manual escape. The parts: the **forge bridge** (forge events in,
   the only caller of the forge), the **indexer** (fingerprints, the candidates of a group, the modules of the
-  trunk), the **builder** (claims and builds one fingerprint once), the **checker** (the merge check on built
+  trunk), the **builder** (claims one fingerprint once and orders its build), the **checker** (the merge check on built
   artifacts), the **gate** (merges a group and moves the source revision; *gate part* where it could be read
   as another gate, see [Homonyms](#homonyms)), the **teller** (the operator's phone, and the only writer of an
   ask's answer), the **assigner** (writes each node's wants by its six rules), the **node agent** (the
@@ -512,7 +519,7 @@ controller (the planner, the rollout) until release 6 of ADR 0429; from each rel
 - **fingerprint** — what identifies a module's build by its content: a hash over its source files, its
   manifest and the fingerprints of its build-time inputs, so equal content gives an equal fingerprint whatever
   the commit (ADR 0429 §5). It is today's source fingerprint with a base entering by its module's
-  fingerprint, the builder by its own module's fingerprint, and a build resolving packages by its lock. From
+  fingerprint, and a build resolving packages by its lock; from R4g the builder is no input of any fingerprint (ADR 0530). From
   release 4 a build's key, so one source is never built twice.
 - **source revision** — one revision of the key `source.main`, written only by the gate: every repository's
   merged head and the group that moved it. A group reaches the mesh as one source revision (ADR 0429 §11); a
@@ -712,8 +719,8 @@ asking, never the act. **Decided by** ADR 0152, 0175, 0234, 0259, 0272, 0383, 03
 - **reference** — an opaque token in a message's words standing for a detail the content rule keeps out
   of them (a path, an address); opened with `detail` only on a `private` channel or through the mesh MCP server.
 - **agent** — a coding agent: the operator's, or one the mesh runs; to the mesh, an identity of kind agent
-  (ADR 0386). Not the node-engine, and not the
-  build seat's holder, whose seat name `node-build-agent` is an identifier to rename.
+  (ADR 0386). Not the node-engine, and not a
+  build module.
 - **thread** — one line of agent work, owned by the mesh: its turns, tool calls and results, its workspace
   and usage, kept whole for good on the bus by the thread seat; it outlives any session, node or front end
   (ADR 0383, ADR 0384).
@@ -942,7 +949,7 @@ renaming one sense, the old sense moves to a *Not:* line and becomes mechanical.
 | role | what a seat names, at a scope | **seat**; the bare word in older designs is tracked by issue 872 | Module |
 | | what an identity may call | **role** | Identity and access |
 | ask | a request for the operator's input | **ask** | Operator and conversation |
-| | an entry in the build queue | **build request** | Delivery |
+| | an entry in the build queue | **build request** (an ask on a build stream) | Delivery |
 | store | the one database server | **store** | Core |
 | | the OCI registry | **artifact store** | Delivery |
 | | a node's own copy of its last declaration | **last declaration** | Placement |
@@ -960,7 +967,7 @@ renaming one sense, the old sense moves to a *Not:* line and becomes mechanical.
 | | the controller's own examination | **self-check** | Health and repair |
 | | a file in `00-META/checks/` | **hq check** | The record |
 | agent | a coding agent | **agent** | Operator and conversation |
-| | the build seat's holder; from release 4 of ADR 0429 the part `mesh-delivery-builder` | **builder** | Delivery |
+| | the holder of the seat `node-build-agent` until R4g; from release 4 of ADR 0429 the part `mesh-delivery-builder` | **builder** (the part); **build module** (what builds) | Delivery |
 | the user | an account of a wrapped program, or of the bus server | **its account**, **bus account** | Identity and access |
 | | a human | **operator** or **person** | words every domain uses |
 | firewall | what the mesh enforces | **packet filter** | Connectivity |