Drop SeatViewPrefix again: G's form removed it and nothing calls it (review-g-again r1 finding)

Claude-Session: https://claude.ai/code/session_01NcbgfGKaxw984XyAPfLm4h

README.md

@@ -9,6 +9,15 @@ does not belong.* Per-module code (a service's API client, its tool implementati
 create-a-resource adapter) lives **in the module**, never here — that coupling is exactly what
 turned the old SDK into constant maintenance and made every edit rebuild every module.
 
+**A seat's code is not here** (novox/hq ADR 0625, ADR 0627). mesh-sdk is the runtime every module uses (the bus
+connection, the tools bundle's runtime, state and its helpers) and a seat-neutral part two or more seats' clients or
+holders share (sending a file in parts, `go/parts`). A seat defined whole has its generated contract, and its client
+where callers share logic over it, in mesh-contracts (`go/seats/<seat>`, `go/clients/<seat>client`); the seat list is
+mesh-contracts' `go/seats`, which `catalogue` alone imports. The value layouts of seats not yet defined whole stay
+here until their domain moves, and no new seat-specific type is added. `packages_list_test.go` holds all of it:
+mesh-sdk imports no contracts module but the seat set in `catalogue`, names none of the seats with a client outside
+`catalogue`, and holds none of the packages that moved (`asks`, `asker`, `publish`).
+
 ## What is in it
 
 Five small areas, each a thing a module's `tools/` or `provisioner/` imports:
@@ -106,21 +115,31 @@ runtime's (`node-tools/internal/launch`, mesh-tools).
 values and then every change. Through the runtime that launched the bundle, which refuses what the
 module did not declare. Current values, never history and never a secret (novox/hq ADR 0201).
 
-### `seats` and `asks` — asking a person, answering on a channel (Go)
+### `runtime`, `callers` and `views` — holding a seat from TypeScript
+The TypeScript side of what the Go side's `stdio` and `views` give a seat's holder, with the same rules (design 47
+*The forge module's tools come from mesh-sdk's TypeScript side*): `runtime.seatPublish` says an event or submits an
+accept on a seat (`mesh/seat.publish`) and `runtime.config` reads a config value; `callers.callerOf(args)` is the
+caller the runtime proved in the call's `_meta`, never an argument, and `callers.refusal` judges it against a
+holder's list per verb (`parseVerbCallers`, `configuredVerbCallers`: `*` any proved caller, `operator` any person);
+`views.Follower` keeps a first view of an owner's state from its pages and its events, asking again only on a gap,
+and `views.statusTools` serves its read and ask-again tools (`<module>_first_views`, `<module>_first_view_again`)
+over the reader's state `first-views`. `waitFor(view)` and `holds(view)` say the revision view a part waits for and
+holds; past five minutes `raiseWaits` is told and `viewWaitsFinding` says the part's `view-waits` finding. Checked by `test/stdio.test.ts` and `test/sdk.test.ts`.
+
+### `seats` and `channel` — publishing on a seat, the channel's benches (Go)
 A seat may name its caller or its kind (novox/hq ADR 0259): `stdio.SeatPublish` submits an accept or says
 an event under the module's own name or kind, `stdio.SeatTake` takes a held seat's work, `stdio.SeatProve`
 and `stdio.SeatAnswer` carry a proof (a code typed by a person, by request and reply, never kept),
 `stdio.SeatRecord` reads a record kept for the module, and `State(...).Create` and `.Update` write by
-compare-and-set. The runtime does each only as far as the module's membership lists. `go/asks` is the
-contract on top: the `Ask` an asker publishes and the checks it is held to (its `Whole` is what a channel that proves
-who answers shows in place of its `Explanation`, and its `Details` what the Details answer shows, hq issue 383), the `Warrant` it acts on
-(`For`, `Says`), and the `Message`, `Choice`, `LinkAsked` and `Code` a channel takes and says, with the
-subjects each travels on.
-`go/asker` is an asking module's client (ADR 0259 §10): `Ask` keeps an ask in the module's own state and then
-publishes it under the module's name; `Cancel`; `Where` reads its state from the router's record; `Listen` and
-`Take` hand the module each warrant once — marked acted on by compare-and-set before the module acts, and only
-for an ask it made, an option it offered, at that option's level, before it expired. A lost compare-and-set is
-`stdio.ErrChanged`, told by the runtime's error code.
+compare-and-set. The runtime does each only as far as the module's membership lists. `go/channel` holds the
+shapes of the two benches a channel holds, `channel` and `intake` (the `Message` a channel takes, the `Choice`,
+`LinkAsked`, `Failed`, `Standing` and `Code` it says, with the subjects each travels on): those benches are not
+defined whole, so their layouts stay here (ADR 0625 §9).
+Asking a person is the `operator-channel` seat's, defined whole in mesh-contracts: its `Ask` and `Warrant` are its
+generated contract (`go/seats/operatorchannel`), and the checks an ask is held to, the warrant's (`For`, `Says`,
+`Performs`) and an asking module's client (`Ask`, `Cancel`, `Where`, `Listen`, `Take`, each warrant handed once,
+marked acted on by compare-and-set) are its client, `go/clients/operatorchannelclient` (ADR 0627 §1). A lost
+compare-and-set is `stdio.ErrChanged`, told by the runtime's error code.
 `State(...).Increment(key, attempts)` is a counter on top of the two (for numbers handed out once, such as an
 issue's): it reads the key, writes one more at the revision read, and on a lost write reads and tries again, at
 most `attempts` times; past that it is `stdio.ErrChanged` and nothing was counted.

c/.gitignore

@@ -1 +0,0 @@
-example

c/Makefile

@@ -1,8 +0,0 @@
-CFLAGS ?= -O2 -Wall -Wextra
-JANSSON := $(shell pkg-config --cflags --libs jansson)
-
-example: example.c mesh_sdk.c mesh_sdk.h
-	$(CC) $(CFLAGS) -o $@ example.c mesh_sdk.c $(JANSSON)
-
-clean:
-	rm -f example

c/README.md

@@ -1,9 +0,0 @@
-# mesh-sdk for C
-
-The skeleton (novox/hq ADR 0188): `mesh_serve(name, tools, count)` speaks MCP over stdio to the
-node's tool runtime. A `mesh_tool` is a name, a description, an argument schema and a function
-returning JSON. A tool named `<seat>.<verb>` is the seat's implementation. JSON is jansson's, the
-one dependency.
-
-What it holds, under ADR 0039's test: the stdio loop and the tool type. Nothing else — no bus, no
-client, nothing of any module's. `make` and pipe a `tools/list` request into `./example`.

c/example.c

@@ -1,27 +0,0 @@
-/* A tools bundle in C: one tool of its own and one seat verb, served over stdio. */
-#include "mesh_sdk.h"
-#include <stdio.h>
-
-static json_t *greet(json_t *args, char **error) {
-    (void)error;
-    const char *who = json_string_value(json_object_get(args, "who"));
-    char greeting[128];
-    snprintf(greeting, sizeof greeting, "hello %s", who ? who : "world");
-    return json_pack("{s:s,s:s}", "greeting", greeting, "language", "c");
-}
-
-static json_t *on(json_t *args, char **error) {
-    (void)args; (void)error;
-    return json_pack("{s:b,s:s}", "on", 1, "language", "c");
-}
-
-int main(void) {
-    json_t *who = json_pack("{s:{s:s,s:s}}", "who", "type", "string", "description", "whom");
-    const mesh_tool tools[] = {
-        {"greet", "say hello", who, greet},
-        {"node-lamp.on", "the seat's verb", NULL, on},
-    };
-    int rc = mesh_serve("c-example", tools, 2);
-    json_decref(who);
-    return rc;
-}

c/mesh_sdk.c

@@ -1,83 +0,0 @@
-#include "mesh_sdk.h"
-#include <stdio.h>
-#include <stdlib.h>
-#include <string.h>
-
-static void say(json_t *m) {
-    json_object_set_new(m, "jsonrpc", json_string("2.0"));
-    char *text = json_dumps(m, JSON_COMPACT);
-    fprintf(stdout, "%s\n", text);
-    fflush(stdout);
-    free(text);
-    json_decref(m);
-}
-
-static json_t *as_schema(json_t *given) {
-    if (!given || !json_is_object(given) || json_object_size(given) == 0)
-        return json_pack("{s:s,s:{}}", "type", "object", "properties");
-    if (json_object_get(given, "type") || json_object_get(given, "properties"))
-        return json_incref(given);
-    return json_pack("{s:s,s:O}", "type", "object", "properties", given);
-}
-
-int mesh_serve(const char *name, const mesh_tool *tools, size_t count) {
-    char *line = NULL;
-    size_t cap = 0;
-    ssize_t got;
-    while ((got = getline(&line, &cap, stdin)) >= 0) {
-        json_error_t err;
-        json_t *req = json_loads(line, 0, &err);
-        if (!req) continue;
-        json_t *id = json_object_get(req, "id");
-        const char *method = json_string_value(json_object_get(req, "method"));
-        json_t *params = json_object_get(req, "params");
-        if (!method) { json_decref(req); continue; }
-        if (strcmp(method, "initialize") == 0) {
-            say(json_pack("{s:O,s:{s:s,s:{s:{}},s:{s:s,s:s}}}", "id", id ? id : json_null(), "result",
-                "protocolVersion", MESH_SDK_PROTOCOL, "capabilities", "tools",
-                "serverInfo", "name", name, "version", "1"));
-        } else if (strcmp(method, "notifications/initialized") == 0) {
-        } else if (strcmp(method, "ping") == 0) {
-            if (id) say(json_pack("{s:O,s:{}}", "id", id, "result"));
-        } else if (strcmp(method, "tools/list") == 0) {
-            json_t *listed = json_array();
-            for (size_t i = 0; i < count; i++)
-                json_array_append_new(listed, json_pack("{s:s,s:s,s:o}", "name", tools[i].name,
-                    "description", tools[i].description, "inputSchema", as_schema(tools[i].input)));
-            say(json_pack("{s:O,s:{s:o}}", "id", id ? id : json_null(), "result", "tools", listed));
-        } else if (strcmp(method, "tools/call") == 0) {
-            const char *wanted = params ? json_string_value(json_object_get(params, "name")) : NULL;
-            const mesh_tool *tool = NULL;
-            for (size_t i = 0; wanted && i < count; i++)
-                if (strcmp(tools[i].name, wanted) == 0) tool = &tools[i];
-            if (!tool) {
-                char message[256];
-                snprintf(message, sizeof message, "%s has no tool %s", name, wanted ? wanted : "");
-                say(json_pack("{s:O,s:{s:i,s:s}}", "id", id ? id : json_null(), "error", "code", -32602, "message", message));
-            } else {
-                json_t *args = params ? json_object_get(params, "arguments") : NULL;
-                json_t *empty = args ? NULL : json_object();
-                char *error = NULL;
-                json_t *result = tool->run(args ? args : empty, &error);
-                if (empty) json_decref(empty);
-                if (result) {
-                    char *text = json_dumps(result, JSON_COMPACT);
-                    say(json_pack("{s:O,s:{s:[{s:s,s:s}]}}", "id", id ? id : json_null(), "result", "content", "type", "text", "text", text));
-                    free(text);
-                    json_decref(result);
-                } else {
-                    say(json_pack("{s:O,s:{s:[{s:s,s:s}],s:b}}", "id", id ? id : json_null(), "result", "content",
-                        "type", "text", "text", error ? error : "the tool failed", "isError", 1));
-                    free(error);
-                }
-            }
-        } else if (id) {
-            char message[256];
-            snprintf(message, sizeof message, "no %s", method);
-            say(json_pack("{s:O,s:{s:i,s:s}}", "id", id, "error", "code", -32601, "message", message));
-        }
-        json_decref(req);
-    }
-    free(line);
-    return ferror(stdin) ? -1 : 0;
-}

c/mesh_sdk.h

@@ -1,29 +0,0 @@
-/* The Novox Mesh SDK for C — the skeleton (novox/hq ADR 0188).
- *
- * A tools bundle is a process the node's runtime launches and speaks MCP over stdio to:
- * `initialize`, `tools/list` once, `tools/call` per call, newline-framed JSON-RPC on stdin and
- * stdout. This is the loop, so a bundle writes its tools and nothing else. A tool named
- * `<seat>.<verb>` is the module's implementation of that seat's verb; any other name is the
- * module's own. JSON is jansson's.
- *
- * No transport here: the bus, the subjects and the memberships are the runtime's (ADR 0039, 0175).
- * stdout is the protocol; log to stderr. */
-#ifndef MESH_SDK_H
-#define MESH_SDK_H
-#include <jansson.h>
-
-#define MESH_SDK_PROTOCOL "2025-03-26"
-
-/* One tool. `run` returns a new JSON value (the answer) or NULL with *error set to a message the
- * caller frees. `input` is the schema of the arguments, or NULL for a tool that takes nothing. */
-typedef struct {
-    const char *name;
-    const char *description;
-    json_t *input;
-    json_t *(*run)(json_t *args, char **error);
-} mesh_tool;
-
-/* Serve these tools on stdin/stdout until stdin closes. Returns 0, or -1 on an I/O fault. */
-int mesh_serve(const char *name, const mesh_tool *tools, size_t count);
-
-#endif

go/README.md

@@ -16,6 +16,6 @@ at the same version as the TypeScript package.
 
 What it holds, under ADR 0039's test: the stdio loop and the tool type, and `cli`, the local protocol
 `mesh-cli` speaks to the node-engine on its machine (novox/hq ADR 0272): the socket's path and one request and one
-answer; and `seal`, the mesh's sealed box (novox/hq ADR 0206: X25519, HKDF-SHA256, AES-256-GCM, `{v, eph, iv, tag, ct}`), byte for byte the box the licence manager made before it lived here and the TypeScript `@novox/mesh-sdk/seal` makes. Nothing else — no bus, no client, nothing of any module's. `go build ./example` and pipe a `tools/list` request into it.
+answer; and `seal`, the mesh's sealed box (novox/hq ADR 0206: X25519, HKDF-SHA256, AES-256-GCM, `{v, eph, iv, tag, ct}`), byte for byte the box the licence manager made before it lived here. Nothing else — no bus, no client, nothing of any module's.
 
 From release 4a of design 47 (novox/hq ADR 0453 clause 3, ADR 0446 clause 4) it also holds the composition of a machine's declaration, over a plain input and with nothing behind it: `declaration` and `validate`, the node-engine's parser and its validator, copied from mesh-host; `catalogue`, the manifests, their resolution and rendering, and `overlay`, the private network's generator, copied from mesh-controller; `compose`, the controller's planFor, renderingFor and declarationWith as functions of an `Input` (the composition never allocates, makes, keeps or writes: what a send would do it names as foreseen or returns); `sdkversion`, which mesh-sdk version a program was built with; and, in `delivery`, the layouts of the keys the builder, the checker and the indexer write (the source fingerprint's new form, the builds, the verdicts and kept verdicts, the manifests by digest). None of them holds a bus, a store or a vault client, which `go list -deps` of `compose` shows.

go/announce/announce.go

@@ -24,16 +24,13 @@ const Event = "states"
 // account may already publish to and the events stream keeps.
 func Subject(module string) string { return "mesh.mod." + module + ".event." + Event }
 
-// SubjectAll is every module's announcement, what the controller consumes.
+// SubjectAll is every module's announcement.
 const SubjectAll = "mesh.mod.*.event." + Event
 
-// KeptBucket is the controller's bucket of the last announcement of each module, by Key.
-const KeptBucket = "mesh-controller_states-announced"
-
 var name = regexp.MustCompile(`^[a-z0-9][a-z0-9-]*$`)
 
-// Key is module's key in KeptBucket: the module itself, which must be one plain name, since a module's name is part of
-// its buckets' names (catalogue.StateProblems).
+// Key is module's key where the last announcement of each module is kept: the module itself, which must be one plain name, since a module's name is part of
+// its buckets' names (the indexer's judge, novox/hq ADR 0578 §1).
 func Key(module string) (string, error) {
 	if !name.MatchString(module) {
 		return "", fmt.Errorf("announce: %q is not a module that keeps state: lower-case letters, digits and hyphens", module)

go/announce/announce_test.go

@@ -42,9 +42,6 @@ func TestAnAnnouncementRoundTripsSortedAndSaysWhatIsReadable(t *testing.T) {
 	if Subject("mesh-controller") != "mesh.mod.mesh-controller.event.states" || SubjectAll != "mesh.mod.*.event.states" {
 		t.Fatalf("the subjects are %q and %q", Subject("mesh-controller"), SubjectAll)
 	}
-	if KeptBucket != "mesh-controller_states-announced" {
-		t.Fatalf("the kept bucket is %q", KeptBucket)
-	}
 	if k, err := Key("mesh-delivery-builder"); err != nil || k != "mesh-delivery-builder" {
 		t.Fatalf("Key = %q, %v", k, err)
 	}

go/approval/act.go

@@ -0,0 +1,296 @@
+package approval
+
+import (
+	"bytes"
+	"encoding/json"
+	"fmt"
+	"math"
+	"sort"
+	"strconv"
+	"strings"
+	"unicode/utf8"
+
+	"git.novox.be/novox/mesh-sdk/go/operatorask"
+	"git.novox.be/novox/mesh-sdk/go/outward"
+)
+
+// Call is one call the runner serves, as the gate judges it: a module's tool, or a seat verb its module serves.
+type Call struct {
+	// Address is the address as called: `<module>.<tool>` or `<seat>.<verb>`.
+	Address string
+	// Module is the module whose bundle serves it; Seat the seat of a verb, empty for a tool; Name the tool or the verb.
+	Module, Seat, Name string
+	// Fingerprint is the build the bundle serves, from its composed environment (§5).
+	Fingerprint string
+	// Caller is the caller the bus proved.
+	Caller string
+	// Args are the call's arguments, a JSON object.
+	Args json.RawMessage
+	// Description is the tool's or verb's own description, whose first line the ask explains it by.
+	Description string
+	// Own says it is one of the runner's own tools served under the module's name (its ledger repairs), not its bundle's.
+	Own bool
+}
+
+// MostArguments is the most a marked call's arguments may hold: more is refused, asking nothing (§9).
+const MostArguments = 16 * 1024
+
+// arguments are a call's arguments by name; a body that is not an object is refused.
+func arguments(raw json.RawMessage) (map[string]json.RawMessage, error) {
+	args := map[string]json.RawMessage{}
+	if len(bytes.TrimSpace(raw)) == 0 || string(bytes.TrimSpace(raw)) == "null" {
+		return args, nil
+	}
+	if err := json.Unmarshal(raw, &args); err != nil {
+		return nil, fmt.Errorf("its arguments are not a JSON object: %v", err)
+	}
+	return args, nil
+}
+
+// refusedUnasked says why a marked call is refused at once, asking nothing (§9): its arguments hold a secret's shape, or are
+// more than MostArguments.
+func refusedUnasked(raw json.RawMessage) string {
+	if len(raw) > MostArguments {
+		return fmt.Sprintf("its arguments are %d bytes, more than the %d a call that needs the operator's approval may carry", len(raw), MostArguments)
+	}
+	if r, ok := outward.CheckSecret(string(raw)); !ok {
+		return fmt.Sprintf("its arguments hold %s, which no ask may carry", r.What)
+	}
+	return ""
+}
+
+// ActOf is the act a marked call binds (§8): `address`, `node` (none given for a process holder, lead answer A-255), `module` and `tool` or `seat` and `verb`, `build`, and
+// `arg.<name>` for each argument given, a string as itself and any other value as its JSON in RFC 8785's canonical form.
+func ActOf(c Call, node string) (operatorask.Act, error) {
+	act := operatorask.Act{"address": c.Address, "build": c.Fingerprint}
+	if node != "" { // a process holder's act names none (lead answer A-255)
+		act["node"] = node
+	}
+	if c.Seat == "" {
+		act["module"], act["tool"] = c.Module, c.Name
+	} else {
+		act["seat"], act["verb"] = c.Seat, c.Name
+	}
+	args, err := arguments(c.Args)
+	if err != nil {
+		return nil, err
+	}
+	for name, raw := range args {
+		var s string
+		if json.Unmarshal(raw, &s) == nil {
+			act["arg."+name] = s
+			continue
+		}
+		canon, err := Canonical(raw)
+		if err != nil {
+			return nil, fmt.Errorf("the argument %s cannot be put in canonical form: %v", name, err)
+		}
+		act["arg."+name] = canon
+	}
+	return act, nil
+}
+
+// Canonical is a JSON value in RFC 8785's canonical form: no white space, an object's members sorted by their names' UTF-16
+// code units, a number as ECMAScript writes a double, a string with only the escapes the RFC names.
+func Canonical(raw json.RawMessage) (string, error) {
+	dec := json.NewDecoder(bytes.NewReader(raw))
+	dec.UseNumber()
+	var v any
+	if err := dec.Decode(&v); err != nil {
+		return "", err
+	}
+	var b strings.Builder
+	if err := canonicalValue(&b, v); err != nil {
+		return "", err
+	}
+	return b.String(), nil
+}
+
+func canonicalValue(b *strings.Builder, v any) error {
+	switch x := v.(type) {
+	case nil:
+		b.WriteString("null")
+	case bool:
+		b.WriteString(strconv.FormatBool(x))
+	case json.Number:
+		f, err := strconv.ParseFloat(string(x), 64)
+		if err != nil || math.IsInf(f, 0) || math.IsNaN(f) {
+			return fmt.Errorf("the number %s is not a double", x)
+		}
+		b.WriteString(es6Number(f))
+	case string:
+		canonicalString(b, x)
+	case []any:
+		b.WriteByte('[')
+		for i, e := range x {
+			if i > 0 {
+				b.WriteByte(',')
+			}
+			if err := canonicalValue(b, e); err != nil {
+				return err
+			}
+		}
+		b.WriteByte(']')
+	case map[string]any:
+		names := make([]string, 0, len(x))
+		for k := range x {
+			names = append(names, k)
+		}
+		sort.Slice(names, func(i, j int) bool { return utf16Less(names[i], names[j]) })
+		b.WriteByte('{')
+		for i, k := range names {
+			if i > 0 {
+				b.WriteByte(',')
+			}
+			canonicalString(b, k)
+			b.WriteByte(':')
+			if err := canonicalValue(b, x[k]); err != nil {
+				return err
+			}
+		}
+		b.WriteByte('}')
+	default:
+		return fmt.Errorf("a value of type %T", v)
+	}
+	return nil
+}
+
+// es6Number is a double as ECMAScript's Number.prototype.toString writes it (RFC 8785 §3.2.2.3).
+func es6Number(f float64) string {
+	if f == 0 {
+		return "0"
+	}
+	abs := math.Abs(f)
+	if abs >= 1e-6 && abs < 1e21 {
+		return strconv.FormatFloat(f, 'f', -1, 64)
+	}
+	s := strconv.FormatFloat(f, 'e', -1, 64) // 1e+21, 1.5e-07
+	mant, exp, _ := strings.Cut(s, "e")
+	sign, digits := exp[:1], strings.TrimLeft(exp[1:], "0")
+	return mant + "e" + sign + digits
+}
+
+func canonicalString(b *strings.Builder, s string) {
+	b.WriteByte('"')
+	for _, r := range s {
+		switch {
+		case r == '"':
+			b.WriteString(`\"`)
+		case r == '\\':
+			b.WriteString(`\\`)
+		case r == '\b':
+			b.WriteString(`\b`)
+		case r == '\f':
+			b.WriteString(`\f`)
+		case r == '\n':
+			b.WriteString(`\n`)
+		case r == '\r':
+			b.WriteString(`\r`)
+		case r == '\t':
+			b.WriteString(`\t`)
+		case r < 0x20:
+			fmt.Fprintf(b, `\u%04x`, r)
+		default:
+			b.WriteRune(r)
+		}
+	}
+	b.WriteByte('"')
+}
+
+func utf16Less(a, b string) bool {
+	ua, ub := utf16Of(a), utf16Of(b)
+	for i := 0; i < len(ua) && i < len(ub); i++ {
+		if ua[i] != ub[i] {
+			return ua[i] < ub[i]
+		}
+	}
+	return len(ua) < len(ub)
+}
+
+func utf16Of(s string) []uint16 {
+	out := make([]uint16, 0, utf8.RuneCountInString(s))
+	for _, r := range s {
+		if r >= 0x10000 {
+			r -= 0x10000
+			out = append(out, uint16(0xD800+(r>>10)), uint16(0xDC00+(r&0x3FF)))
+		} else {
+			out = append(out, uint16(r))
+		}
+	}
+	return out
+}
+
+// Fingerprint is how an act is shown: its digest's first 24 hexadecimal digits in groups of four (§10).
+func Fingerprint(digest string) string {
+	hex := strings.TrimPrefix(digest, "sha256:")
+	if len(hex) > 24 {
+		hex = hex[:24]
+	}
+	var groups []string
+	for len(hex) > 4 {
+		groups, hex = append(groups, hex[:4]), hex[4:]
+	}
+	return strings.Join(append(groups, hex), " ")
+}
+
+// The bounds of the arguments shown in an ask (§11).
+const (
+	ShownBytes, ShownLines = 2000, 40
+	PartBytes, PartLines   = 1200, 20
+)
+
+// shown is a call's arguments as an ask shows them (§11), one per line as "name: value", and whether all were shown whole:
+// an argument whole where outward.Check passes it, else its shape, ‹path›, ‹address› or ‹withheld›; the whole when it is at
+// most ShownBytes and ShownLines, else its first PartLines lines and PartBytes bytes, marked NOT SHOWN IN FULL.
+func shown(raw json.RawMessage) (string, bool) {
+	args, _ := arguments(raw)
+	names := make([]string, 0, len(args))
+	for n := range args {
+		names = append(names, n)
+	}
+	sort.Strings(names)
+	whole := true
+	var lines []string
+	for _, n := range names {
+		var value string
+		if json.Unmarshal(args[n], &value) != nil {
+			value = string(args[n])
+		}
+		if r, ok := outward.Check(value); !ok {
+			value, whole = shapeOf(r), false
+		}
+		lines = append(lines, n+": "+value)
+	}
+	text := strings.Join(lines, "\n")
+	if all := strings.Split(text, "\n"); len(text) > ShownBytes || len(all) > ShownLines {
+		if len(all) > PartLines {
+			all = all[:PartLines]
+		}
+		text = strings.Join(all, "\n")
+		if len(text) > PartBytes {
+			text = cutBytes(text, PartBytes)
+		}
+		text += "\nNOT SHOWN IN FULL"
+		whole = false
+	}
+	return text, whole
+}
+
+// shapeOf is what an argument outward.Check refuses is shown as.
+func shapeOf(r outward.Refusal) string {
+	switch r.Class {
+	case "path":
+		return "‹path›"
+	case "address":
+		return "‹address›"
+	}
+	return "‹withheld›"
+}
+
+// cutBytes is s at most n bytes, cut at a character's end.
+func cutBytes(s string, n int) string {
+	for n > 0 && !utf8.RuneStart(s[n]) {
+		n--
+	}
+	return s[:n]
+}

go/approval/approval_test.go

@@ -0,0 +1,80 @@
+package approval
+
+import (
+	"encoding/json"
+	"strings"
+	"testing"
+
+	"git.novox.be/novox/mesh-sdk/go/operatorask"
+)
+
+// call is a fixture call of the marked tool wipe.
+func call(name, args string) Call {
+	return Call{Address: "shell." + name, Module: "shell", Name: name, Fingerprint: "src2:1", Caller: "agent", Args: json.RawMessage(args),
+		Description: "Wipes a scratch directory.\nMore words."}
+}
+
+// Design 46 7-approval-mark §8, §10, §11: the act's fields give each call its digest, and the ask shows a call's arguments
+// in their shape and its headline cut (the gate's other cases run on the tool runner's fixture mesh, node-tools
+// internal/approval).
+func TestTheActAndItsAsk(t *testing.T) {
+	base := call("wipe", `{"dir":"scratch","n":1}`)
+	digest := func(c Call) string {
+		act, err := ActOf(c, "n1")
+		if err != nil {
+			t.Fatal(err)
+		}
+		d, _ := operatorask.ActDigest(act)
+		return d
+	}
+	act, _ := ActOf(base, "n1")
+	want := operatorask.Act{"address": "shell.wipe", "node": "n1", "module": "shell", "tool": "wipe", "build": "src2:1",
+		"arg.dir": "scratch", "arg.n": "1"}
+	if len(act) != len(want) {
+		t.Fatalf("act %v", act)
+	}
+	for k, v := range want {
+		if act[k] != v {
+			t.Errorf("act[%s] = %q, want %q", k, act[k], v)
+		}
+	}
+	seen := map[string]string{digest(base): "the call"}
+	for name, c := range map[string]Call{
+		"an omitted argument": call("wipe", `{"dir":"scratch"}`),
+		"another number":      call("wipe", `{"dir":"scratch","n":2}`),
+		"an object":           call("wipe", `{"dir":{"name":"scratch"},"n":1}`),
+		"a changed build":     func() Call { c := base; c.Fingerprint = "src2:2"; return c }(),
+		"another node's seat": {Address: "node-login-shell.execute", Module: "shell", Seat: "node-login-shell", Name: "execute", Fingerprint: "src2:1"},
+	} {
+		d := digest(c)
+		if other, dup := seen[d]; dup {
+			t.Errorf("%s gives the digest of %s", name, other)
+		}
+		seen[d] = name
+	}
+	if got, _ := Canonical(json.RawMessage(`{"b":[1.0,2.5e-7,1e21],"a":"é<"}`)); got != `{"a":"é<","b":[1,2.5e-7,1e+21]}` {
+		t.Errorf("canonical form %s", got)
+	}
+	// §11: a path, an address and a long argument are shown in their shape and cut.
+	text, whole := shown(json.RawMessage(`{"dir":"/home/someone/scratch","host":"10.0.0.7","ok":"yes"}`))
+	if whole || text != "dir: ‹path›\nhost: ‹address›\nok: yes" {
+		t.Errorf("shown %q whole %v", text, whole)
+	}
+	long, _ := json.Marshal(map[string]string{"text": strings.Repeat("word ", 500)})
+	if text, whole := shown(long); whole || !strings.HasSuffix(text, "NOT SHOWN IN FULL") || len(text) > PartBytes+len("\nNOT SHOWN IN FULL") {
+		t.Errorf("a long argument shown whole %v, %d bytes", whole, len(text))
+	}
+	// §10: the headline, cut with … to 60 characters, ending Part shown.
+	for _, tc := range []struct{ name, node, want string }{
+		{"wipe", "n1", "Run wipe on n1?"},
+		{strings.Repeat("x", 50), "n1", "Run " + strings.Repeat("x", 50) + "?"},
+		{strings.Repeat("y", 80), "n1", "Run " + strings.Repeat("y", 54) + "…?"},
+	} {
+		if got := headlineOf("Run", tc.name, tc.node, true); got != tc.want || len([]rune(got)) > 60 {
+			t.Errorf("headline %q, want %q", got, tc.want)
+		}
+	}
+	if got := headlineOf("Run", "wipe", "n1", false); got != "Run wipe on n1? Part shown" {
+		t.Errorf("headline %q", got)
+	}
+}

go/approval/ask.go

@@ -0,0 +1,239 @@
+package approval
+
+import (
+	"crypto/rand"
+	"encoding/hex"
+	"encoding/json"
+	"fmt"
+	"strings"
+	"time"
+
+	stdio "git.novox.be/novox/mesh-sdk/go"
+	"git.novox.be/novox/mesh-sdk/go/keys"
+	"git.novox.be/novox/mesh-sdk/go/operatorask"
+)
+
+// StateName is the runner's own state its asks and claims are kept in, per machine (§13).
+const StateName = "approvals"
+
+// Store is the runner's state `approvals` (§13): a key's value, a create that refuses a key that exists and an update by
+// compare-and-set, each failing with stdio.ErrChanged when another write came first; a put, and its keys.
+type Store interface {
+	Get(key string) (*stdio.StateEntry, error)
+	Create(key string, value any) (uint64, error)
+	Update(key string, value any, revision uint64) (uint64, error)
+	Put(key string, value any) (uint64, error)
+	Keys() ([]string, error)
+}
+
+// The bounds of an ask (§10, §12, §13, §14, §17).
+const (
+	AskLasts      = 60 * time.Minute
+	RecordWithin  = 5 * time.Second
+	RunWithin     = 30 * time.Minute
+	DeclinedFor   = 10 * time.Minute
+	MostKeptValue = 256 * 1024
+	OnExpiry      = "nothing runs; call again to ask anew"
+)
+
+// The options every ask offers (§10), both at level approve, both binding the act's digest.
+const (
+	OptionApprove = "approve"
+	OptionDecline = "decline"
+)
+
+// actKey is the key naming the newest ask of an act (§13), its digest escaped as a key's name is, since the bus holds no `:` in a key (lead answer A-209).
+func (g *Gate) actKey(digest string) string { return g.prefix() + "act." + keys.EscapeName(digest) }
+
+// prefix is what the gate's keys begin with: the tool runner's machine, `<node>.`, since its state is shared by every
+// machine's runner (§13); none for a module's process, whose state approvals is its module's own (design 47 G §677).
+func (g *Gate) prefix() string {
+	if g.d.Holding {
+		return ""
+	}
+	return g.d.Node + "."
+}
+
+// askKey is the key the client keeps an ask under (§13).
+func (g *Gate) askKey(id string) string { return g.prefix() + "ask." + id }
+
+// newID is an ask's id: 128 random bits.
+func newID() string {
+	var b [16]byte
+	_, _ = rand.Read(b[:])
+	return hex.EncodeToString(b[:])
+}
+
+// askFor is the ask a marked call raises (§10, §11).
+func (g *Gate) askFor(c Call, digest, id string) Ask {
+	args, whole := shown(c.Args)
+	name := c.Name
+	if c.Seat != "" {
+		name = c.Seat + "." + c.Name
+	}
+	headline := headlineOf("Run", name, g.d.Node, whole)
+	first, _, _ := strings.Cut(strings.TrimSpace(c.Description), "\n")
+	if first == "" {
+		first = name
+	}
+	how := "called through the mesh's tools, which cannot tell who called."
+	if g.d.Holding {
+		how = "called by " + c.Caller + "."
+	}
+	lines := []string{first, "On " + g.d.Node + ", " + how}
+	if args != "" {
+		lines = append(lines, args)
+	}
+	if !whole {
+		read := "mesh_approvals on " + g.d.Node
+		if g.d.Holding {
+			read = c.Seat + ".approvals"
+		}
+		lines = append(lines, "The whole is read with "+read+", whose fingerprint must be the one on the phone.")
+	}
+	lines = append(lines, "Fingerprint "+Fingerprint(digest))
+	return Ask{ID: id, About: digest, Headline: headline,
+		Explanation: strings.Join(lines, "\n"), Expires: formatTime(g.d.Now().Add(AskLasts)), OnExpiry: OnExpiry,
+		Options: []Option{
+			{ID: OptionApprove, Label: "Approve", Does: "the same call, made again within 30 minutes, runs once", Binds: digest},
+			{ID: OptionDecline, Label: "Decline", Does: "nothing runs; the same call is not asked again for 10 minutes", Binds: digest}}}
+}
+
+// headlineOf is "<verb> <names> on <node>?", "<verb> <names>?" when that is longer than the router allows, and the names cut
+// with "…" when that too is longer; ending "Part shown" whenever an argument is not shown whole (§10, Q-HL). verb is "Run"
+// for a call and "Wait on" for a wait (design 34 every-event §35).
+func headlineOf(verb, name, node string, whole bool) string {
+	suffix := ""
+	if !whole {
+		suffix = " Part shown"
+	}
+	max := HeadlineLength
+	fits := func(s string) bool { return len([]rune(s)) <= max }
+	if h := verb + " " + name + " on " + node + "?" + suffix; fits(h) {
+		return h
+	}
+	if h := verb + " " + name + "?" + suffix; fits(h) {
+		return h
+	}
+	room := max - len([]rune(verb+" …?"+suffix))
+	r := []rune(name)
+	if room < 1 {
+		room = 1
+	}
+	if len(r) > room {
+		r = r[:room]
+	}
+	return verb + " " + string(r) + "…?" + suffix
+}
+
+// firstCall is a marked call whose act has no ask open: refused at once when its arguments may not be asked (§9), else
+// asked (§10, §12).
+func (g *Gate) firstCall(c Call) (any, error) {
+	if why := refusedUnasked(c.Args); why != "" {
+		return nil, g.refused(c, "", why)
+	}
+	act, err := ActOf(c, g.d.Node)
+	if err != nil {
+		return nil, g.refused(c, "", err.Error())
+	}
+	digest, err := operatorask.ActDigest(act)
+	if err != nil {
+		return nil, g.refused(c, "", err.Error())
+	}
+	return nil, g.raise(c, act, digest, "")
+}
+
+// raise raises the ask of a marked call whose act has none open (§10): kept in the runner's state with the act and the whole
+// arguments, published under the module's name, its act's key naming it; then the 5 seconds for the router's record and
+// the first answer (§12), always an error, never a result.
+func (g *Gate) raise(c Call, act operatorask.Act, digest, markedSince string) error {
+	id := newID()
+	if err := g.keepAsk(c, act, digest, g.askFor(c, digest, id)); err != nil {
+		return err
+	}
+	return g.firstAnswer(c, id, digest, markedSince)
+}
+
+// keepAsk raises an ask and keeps it in the runner's state with the act and the whole arguments, its act's key naming it
+// (§10, §13); refused, as an error, when it cannot be.
+func (g *Gate) keepAsk(c Call, act operatorask.Act, digest string, a Ask) error {
+	if size := keptSize(a, act, c.Args); size > MostKeptValue {
+		return g.refused(c, digest, fmt.Sprintf("its ask would keep %d bytes, more than the %d a value of the state %s holds", size, MostKeptValue, StateName))
+	}
+	if err := g.d.Channel.Ask(c.Module, a); err != nil {
+		return g.refused(c, digest, "the ask could not be raised: "+err.Error())
+	}
+	if err := g.keepCall(a.ID, act, c.Args); err != nil {
+		g.stateFailed(err)
+		return g.refused(c, digest, "the ask was raised and its call could not be kept: "+err.Error())
+	}
+	if _, err := g.d.State.Put(g.actKey(digest), a.ID); err != nil {
+		g.stateFailed(err)
+		return g.refused(c, digest, "the ask was raised and its act could not be kept: "+err.Error())
+	}
+	return nil
+}
+
+// keptSize is the bytes the kept ask would take.
+func keptSize(a Ask, act operatorask.Act, args json.RawMessage) int {
+	raw, _ := json.Marshal(Kept[Ask, Warrant]{Ask: a, Act: act, Arguments: args})
+	return len(raw)
+}
+
+// keepCall writes the act and the whole arguments beside the ask the client kept (§13).
+func (g *Gate) keepCall(id string, act operatorask.Act, args json.RawMessage) error {
+	e, err := g.d.State.Get(g.askKey(id))
+	if err != nil || e == nil {
+		return fmt.Errorf("the kept ask %s cannot be read: %v", id, err)
+	}
+	var k kept
+	if err := json.Unmarshal(e.Value, &k); err != nil {
+		return err
+	}
+	k.Act, k.Arguments = act, args
+	_, err = g.d.State.Update(g.askKey(id), k, e.Revision)
+	return err
+}
+
+// firstAnswer waits up to RecordWithin for the router's record of the ask and says the call was not run (§12).
+func (g *Gate) firstAnswer(c Call, id, digest, markedSince string) error {
+	rec, _ := g.awaitRecord(c.Module, id)
+	since := ""
+	if markedSince != "" {
+		since = "; marked since revision " + markedSince
+	}
+	if rec == nil {
+		return fmt.Errorf("Not run, asked; not yet taken by the router (ask %s, fingerprint %s); make the same call again later%s",
+			id, Fingerprint(digest), since)
+	}
+	return fmt.Errorf("Not run: this needs the operator's approval. Asked on %s at %s (ask %s, fingerprint %s); make the same call "+
+		"again within 30 minutes of the approval; the ask expires at %s%s", orNone(strings.Join(rec.OfferedOn, ", ")), rec.Opened,
+		id, Fingerprint(digest), rec.Expires, since)
+}
+
+// record is the router's record of an ask under the module's name, nil when it holds none.
+func (g *Gate) record(module, id string) (*Record, error) {
+	return g.d.Channel.Record(module, id)
+}
+
+// awaitRecord reads the router's record of a new ask until it is there, within RecordWithin: the seat answers a key's
+// value and says nothing when the router takes an ask, so it is read again after a growing pause (§12).
+func (g *Gate) awaitRecord(module, id string) (*Record, error) {
+	until := g.d.Now().Add(RecordWithin)
+	pause := 50 * time.Millisecond
+	for {
+		rec, err := g.record(module, id)
+		if rec != nil || g.d.Now().Add(pause).After(until) {
+			return rec, err
+		}
+		<-g.d.After(pause)
+		pause *= 2
+	}
+}
+
+// refused is a marked call refused, run nothing, written in the runner's log with the ask's fingerprint and never its
+// arguments (§19).
+func (g *Gate) refused(c Call, digest, why string) error {
+	g.d.Logf("[approval] %s on %s is refused (fingerprint %s): %s", c.Address, g.d.Node, orNone(Fingerprint(digest)), why)
+	return fmt.Errorf("Not run: %s needs the operator's approval and %s", c.Address, why)
+}

go/approval/channel.go

@@ -0,0 +1,115 @@
+package approval
+
+import (
+	"encoding/json"
+	"time"
+
+	"git.novox.be/novox/mesh-sdk/go/operatorask"
+)
+
+// What the gate reads beyond itself crosses in the gate's own terms, its caller translating from the generated contracts
+// (design 47 G lead answers A-219, A-224, A-228): the operator channel (Channel), the catalog's entries (Entry, through
+// Catalog), the finding writer (FindingWriter) and the seat holders (Deps.Holder). No form of a generated contract is
+// copied here: what the router keeps whole (an ask, a warrant) the gate holds as the bytes it was given.
+
+// Channel is the operator channel as the gate reaches it (A-219, A-228): operatorchannelclient implements it over the
+// generated types, keeping each ask in the gate's own state under the marked module's name.
+type Channel interface {
+	// Ask checks the ask, keeps it in the gate's state as a Kept and publishes it under module's name, at the level
+	// approve, to the operator (design 46 7-approval-mark §10).
+	Ask(module string, a Ask) error
+	// Record is the router's record of module's ask id, read under module's own name; nil while the router holds none
+	// (design 47 G §700).
+	Record(module, id string) (*Record, error)
+	// Claim takes the warrant once (design 46 7-approval-mark §14, §15): it holds it to the ask kept, checks that the
+	// chosen option binds act and marks the kept ask acted, then calls run; act's run happens only when it answers
+	// Claimed. A warrant already taken answers ClaimDone, one that does not hold ClaimRefused with why.
+	Claim(module string, w Warrant, act operatorask.Act, run func()) (Claim, error)
+	// Cancel takes module's ask back.
+	Cancel(module, id string) error
+	// Decided is the subject the router's `decided` for module is heard on.
+	Decided(module string) string
+	// Seat is the seat an ask is raised on, whose holder must be there for a marked call to be asked (§19).
+	Seat() string
+}
+
+// Claim is what came of a warrant handed to Channel.Claim.
+type Claim string
+
+const (
+	Claimed      Claim = "acted"
+	ClaimRefused Claim = "refused"
+	ClaimDone    Claim = "already acted on"
+	// ClaimEnded is a warrant of an ask that ended without a choice.
+	ClaimEnded Claim = "ended without a choice"
+)
+
+// Ask is an ask the gate raises: two options, each binding the act's digest (design 46 7-approval-mark §10, §11).
+type Ask struct {
+	ID, About, Headline, Explanation, Expires, OnExpiry string
+	Options                                             []Option
+}
+
+// Option is one option of an ask.
+type Option struct{ ID, Label, Does, Binds string }
+
+// Record is the router's record of an ask as the gate reads it.
+type Record struct {
+	State, Answer, Opened, Expires string
+	OfferedOn                      []string
+	Warrant                        *Warrant
+}
+
+// Warrant is a person's choice as the gate reads it; Whole is the warrant as the router recorded it, which Claim holds to
+// the kept ask.
+type Warrant struct {
+	Ask, Asker, Option, Channel, At string
+	Whole                           json.RawMessage
+}
+
+// Kept is one ask as its asker keeps it (design 46 7-approval-mark §13): the ask, beside it the act the ask binds, the
+// call's whole arguments, and whether the act's run was recorded in the hand-act log. A is the ask's form and W the
+// warrant's: operatorchannelclient's Kept is Kept of the generated contract's, the gate's of the bytes kept (A-228).
+type Kept[A, W any] struct {
+	Ask    A         `json:"ask"`
+	Asked  time.Time `json:"asked"`
+	Acted  bool      `json:"acted,omitempty"`
+	Ended  string    `json:"ended,omitempty"`
+	Answer *W        `json:"answer,omitempty"`
+	// Act is the act the ask's options bind, as its asker digested it.
+	Act operatorask.Act `json:"act,omitempty"`
+	// Arguments are the asked call's arguments whole.
+	Arguments json.RawMessage `json:"arguments,omitempty"`
+	// Recorded says the act's run is in the hand-act log (`mesh-hand-acts.warranted` answered).
+	Recorded bool `json:"recorded,omitempty"`
+}
+
+// kept is the gate's own reading of a Kept: the ask and the warrant as the bytes kept, so a write back keeps them whole.
+type kept = Kept[json.RawMessage, json.RawMessage]
+
+// HeadlineLength is the longest headline the router takes, in characters; operatorchannelclient re-exports it.
+const HeadlineLength = 60
+
+// Entry is a module's entry in the catalog as the marks are read from it (design 46 7-approval-mark §5): its module, the
+// build's fingerprint, the seat verbs it serves as `<seat>.<verb>`, and its manifest.
+type Entry struct {
+	Module, Fingerprint string
+	Serves              []string
+	Manifest            json.RawMessage
+}
+
+// formatTime is a time as the router's records carry it: RFC 3339 to the nanosecond; the zero time is empty.
+func formatTime(t time.Time) string {
+	if t.IsZero() {
+		return ""
+	}
+	return t.Format(time.RFC3339Nano)
+}
+
+// parseTime reads such a time; empty is the zero time.
+func parseTime(s string) (time.Time, error) {
+	if s == "" {
+		return time.Time{}, nil
+	}
+	return time.Parse(time.RFC3339Nano, s)
+}

go/approval/closed.go

@@ -0,0 +1,100 @@
+package approval
+
+import (
+	"fmt"
+	"time"
+)
+
+// UnreadableAfter is how long the state approvals fails before the runner's finding says so (§19).
+const UnreadableAfter = 5 * time.Minute
+
+// unreadableKey is the bound key whose expiry raises `approvals-unreadable` (lead answer A-157).
+func (g *Gate) unreadableKey() string { return g.d.Node + ".unreadable." + StateName }
+
+// held says why no marked call can be asked now, or "" (§19): no module holds operator-channel, as the assigner's view
+// of the seat's holders says, or that view is not read.
+func (g *Gate) held() string {
+	if g.d.Channel == nil {
+		return "the tool runner reaches no operator channel to ask on"
+	}
+	if g.d.Holder == nil && g.d.Holding {
+		return "" // a process holder reads no view of the seats' holders: an ask nobody takes is said by its gate-unanswered (design 47 G §677)
+	}
+	if g.d.Holder == nil {
+		return "the tool runner reads no view of the seats' holders, so it cannot tell that a module holds " + g.d.Channel.Seat()
+	}
+	on := g.d.Channel.Seat()
+	ok, err := g.d.Holder(on)
+	switch {
+	case err != nil:
+		return fmt.Sprintf("whether a module holds %s cannot be read: %v", on, err)
+	case !ok:
+		return "no module holds " + on + ", so nobody can be asked"
+	}
+	return ""
+}
+
+// stateFailed notes that the state approvals could not be read or written: no marked call runs on this machine until it
+// can, the failed read or write is made again at the next marked call and at the next membership change (A-157), and
+// five minutes on the runner's finding says it (§19).
+func (g *Gate) stateFailed(err error) {
+	g.mu.Lock()
+	first := g.failingSince.IsZero()
+	if first {
+		g.failingSince = g.d.Now()
+	}
+	g.mu.Unlock()
+	if first {
+		g.d.Logf("[approval] the state %s on %s cannot be read or written (%v): no marked call runs here until it can", StateName, g.d.Node, err)
+		if g.d.Bounds != nil && !g.d.Holding {
+			if e := g.d.Bounds.CreateTTL(g.unreadableKey(), map[string]string{"since": g.d.Now().UTC().Format(time.RFC3339)}, UnreadableAfter); e != nil {
+				g.d.Logf("[approval] the bound of the state %s's failure is not kept: %v", StateName, e)
+			}
+		}
+	}
+}
+
+// stateRead notes that the state approvals was read or written: a failure noted before ends, its finding cleared.
+func (g *Gate) stateRead() {
+	g.mu.Lock()
+	was := !g.failingSince.IsZero()
+	g.failingSince = time.Time{}
+	g.mu.Unlock()
+	if !was {
+		return
+	}
+	if g.d.Bounds != nil && !g.d.Holding {
+		_ = g.d.Bounds.Delete(g.unreadableKey())
+	}
+	g.finding(StateName, KindApprovalsUnreadable, false, "the state "+StateName+" is read again", "")
+}
+
+// failing says the state approvals is failing now.
+func (g *Gate) failing() bool {
+	g.mu.Lock()
+	defer g.mu.Unlock()
+	return !g.failingSince.IsZero()
+}
+
+// StateAgain makes the failed read of the state approvals again: at the next membership change the runner hears (A-157).
+func (g *Gate) StateAgain() {
+	if g.d.State == nil || !g.failing() {
+		return
+	}
+	if _, err := g.d.State.Keys(); err != nil {
+		return
+	}
+	g.stateRead()
+}
+
+// unreadableExpired is the bound key of a failing state expiring: the finding raised while the state still fails.
+func (g *Gate) unreadableExpired() {
+	g.mu.Lock()
+	since := g.failingSince
+	g.mu.Unlock()
+	if since.IsZero() {
+		return
+	}
+	g.finding(StateName, KindApprovalsUnreadable, true, fmt.Sprintf("the state %s on %s cannot be read or written since %s: no marked call "+
+		"runs here until it can", StateName, g.d.Node, since.UTC().Format(time.RFC3339)), "approvals unreadable on "+g.d.Node)
+}

go/approval/gate.go

@@ -0,0 +1,178 @@
+package approval
+
+import (
+	"context"
+	"encoding/json"
+	"fmt"
+	"sort"
+	"strings"
+	"sync"
+	"time"
+)
+
+// The runner's findings of the gate (design 46 7-approval-mark §4, §16, §19), written through its held writer.
+const (
+	KindMarkUnserved        = "mark-unserved"
+	KindCallUnanswered      = "call-unanswered"
+	KindApprovalsUnreadable = "approvals-unreadable"
+)
+
+// Kinds are the finding kinds the gate writes through the runner's writer.
+var Kinds = []string{KindMarkUnserved, KindCallUnanswered, KindApprovalsUnreadable}
+
+// FindingWriter raises and clears the gate's findings by kind and id (A-228): its caller writes each as the contract's
+// finding, about its own module on its machine, through its held writer.
+type FindingWriter interface {
+	Raise(ctx context.Context, kind, id, summary, headline string) error
+	Clear(ctx context.Context, kind, id, why string) error
+}
+
+// Deps is what the gate reaches the mesh through: the runner's connection in its one place, fakes in a test.
+type Deps struct {
+	// Node is the machine the runner serves; Runner its own module's name, the subject of its findings.
+	Node, Runner string
+	// Catalog is the catalog half the marks are read from.
+	Catalog Catalog
+	// Wait waits, within the bound, for the catalog half's first view, and is nil once it is read or why not.
+	Wait func(within time.Duration) error
+	// Findings is the runner's held writer; nil says a finding in the log only.
+	Findings FindingWriter
+	Logf     func(string, ...any)
+	Now      func() time.Time
+	// After is the clock's pause; nil is time.After.
+	After func(time.Duration) <-chan time.Time
+	// State is the runner's state approvals; nil when its membership binds none, so every marked call is refused (§13).
+	State Store
+	// Channel is the operator channel, its asks kept in State under this machine's keys (A-219, A-228).
+	Channel Channel
+	// Warranted asks `mesh-hand-acts.warranted` {asker, ask}, each try a kept call open while open says so (§16, A-157).
+	Warranted func(asker, ask string, open func() (bool, error)) error
+	// Bounds is the runner's key-ttl state bound (A-157, A-158), or a process holder's state approvals itself (A-255); nil
+	// keeps no bound.
+	Bounds Bounds
+	// Holder says whether a module holds a seat, from the assigner's view of the seats' holders the runner follows (§19).
+	Holder func(seat string) (bool, error)
+	// Build is the tool runner's own fingerprint, read from its MESH_FINGERPRINT at its start: the build a marked wait's
+	// act binds; empty while unknown, when every marked wait is refused (design 34 every-event §35).
+	Build string
+	// Hear waits within the bound for the first event on the subjects whose body match takes, or the caller's going: a
+	// marked wait's ask's `decided` (every-event §36); false when none came.
+	Hear func(ctx context.Context, subjects []string, within time.Duration, match func(json.RawMessage) bool) (bool, error)
+	// Go runs what goes on beside the call (a run's recording); nil is a goroutine.
+	Go func(func())
+	// Holding says the gate is a module's process's seat server's (design 47 G §677): its keys are its module's own, its
+	// calls held as waiting calls and their ends said through Say; Runner is then the holder's module.
+	Holding bool
+	// Say publishes one gated-ended on its subject with the message id given (§677).
+	Say func(subject string, body any, id string) error
+}
+
+// Gate is the approval gate: every call of a module the tool runner serves goes through it before the bundle (§20), and a
+// marked verb a module's process serves before its handler (design 47 G §677; lead answer A-224).
+type Gate struct {
+	d  Deps
+	mu sync.Mutex
+	// registered is each module's tools as its bundle registered them at its last load.
+	registered map[string]map[string]bool
+	// unserved is each module whose marks name a tool its bundle does not register, with those tools.
+	unserved map[string][]string
+	// unmarkedAt is each caller's address it last called unmarked, so a mark added since is named (§12).
+	unmarkedAt map[string]bool
+	// inFlight is each ask whose recording runs now.
+	inFlight map[string]bool
+	// failingSince is when the state approvals began to fail; zero while it is read.
+	failingSince time.Time
+	// handlers are a process holder's marked verbs' handlers, by `<seat>.<verb>` (design 47 G §677).
+	handlers map[string]func(string, json.RawMessage) (any, error)
+	// served is each module this runner serves, with the build its bundle serves, as its last load said (§18).
+	served map[string]string
+}
+
+// New is a gate over d.
+func New(d Deps) *Gate {
+	if d.Logf == nil {
+		d.Logf = func(string, ...any) {}
+	}
+	if d.Now == nil {
+		d.Now = time.Now
+	}
+	if d.After == nil {
+		d.After = time.After
+	}
+	if d.Go == nil {
+		d.Go = func(f func()) { go f() }
+	}
+	return &Gate{d: d, registered: map[string]map[string]bool{}, unserved: map[string][]string{}}
+}
+
+// Unserved is, of the module's marked tools, those its bundle does not register (§4): such a bundle is not loaded, its
+// finding `mark-unserved` raised; a bundle that serves them, or marks that no longer name them, clear it. Before the marks
+// are read nothing is known, and every marked call is refused until they are (§19).
+func (g *Gate) Unserved(module, fingerprint string, registered []string) []string {
+	set := map[string]bool{}
+	for _, t := range registered {
+		set[t] = true
+	}
+	g.mu.Lock()
+	g.registered[module] = set
+	if g.served == nil {
+		g.served = map[string]string{}
+	}
+	g.served[module] = fingerprint
+	g.mu.Unlock()
+	if g.d.Catalog == nil || g.d.Catalog.Ready() != nil {
+		return nil
+	}
+	return g.checkServed(Derive(g.d.Catalog, module, fingerprint))
+}
+
+// checkServed raises or clears the module's `mark-unserved` as its marks and its bundle's registrations stand now, and is
+// the tools it marks and does not register.
+func (g *Gate) checkServed(m Marks) []string {
+	g.mu.Lock()
+	set := g.registered[m.Module]
+	var missing []string
+	for t := range m.Tools {
+		if !set[t] {
+			missing = append(missing, t)
+		}
+	}
+	sort.Strings(missing)
+	was := g.unserved[m.Module]
+	if len(missing) > 0 {
+		g.unserved[m.Module] = missing
+	} else {
+		delete(g.unserved, m.Module)
+	}
+	g.mu.Unlock()
+	switch {
+	case len(missing) > 0 && strings.Join(was, ",") != strings.Join(missing, ","):
+		g.finding(m.Module, KindMarkUnserved, true, fmt.Sprintf("%s's marks (%s, catalog revision %s) name %s, which its bundle on %s does not "+
+			"register: no tool of %s is served here", m.Module, sourceOf(m, missing[0]), m.Revision, strings.Join(missing, ", "), g.d.Node, m.Module),
+			fmt.Sprintf("%s is not served on %s", m.Module, g.d.Node))
+	case len(missing) == 0 && len(was) > 0:
+		g.finding(m.Module, KindMarkUnserved, false, "a bundle that serves every marked tool, or marks without the tool, is loaded", "")
+	}
+	return missing
+}
+
+func sourceOf(m Marks, tool string) string { return m.Tools[tool] }
+
+// finding writes or clears one of the gate's findings, its id `<node>.<what>` escaped as a key's name is,
+// about the runner's module on this machine (lead answer A-154).
+func (g *Gate) finding(what, kind string, raised bool, summary, headline string) {
+	id := g.findingID(what)
+	if g.d.Findings == nil {
+		g.d.Logf("[approval] %s %s: %s", kind, id, summary)
+		return
+	}
+	var err error
+	if raised {
+		err = g.d.Findings.Raise(context.Background(), kind, id, summary, headline)
+	} else {
+		err = g.d.Findings.Clear(context.Background(), kind, id, summary)
+	}
+	if err != nil {
+		g.d.Logf("[approval] the finding %s of %s is not kept: %v", kind, id, err)
+	}
+}

go/approval/held.go

@@ -0,0 +1,699 @@
+package approval
+
+import (
+	"context"
+	"encoding/json"
+	"fmt"
+	"sort"
+	"strings"
+	"time"
+
+	"git.novox.be/novox/mesh-sdk/go/keys"
+	"git.novox.be/novox/mesh-sdk/go/operatorask"
+	"git.novox.be/novox/mesh-sdk/go/seatdef"
+)
+
+// A marked verb a module's process serves is one call with a gate before its running (design 47 G §677): the holder keeps
+// the call, asks under its own module's name, and on the Approve runs that same call, saying its end on the seat's event
+// `gated-ended`. These are the holder's half of the gate; the caller's is process.Conn's call.
+
+// WaitHeader is the bus header a call carries to say it waits for its end on `gated-ended` (lead answer A-244): a header,
+// never an argument, so no verb's input and no act's digest changes. WaitHeld is its one value.
+const (
+	WaitHeader = "x-wait"
+	WaitHeld   = "held"
+)
+
+// Held is the holder's answer to a call that waits (§677): the ask it waits on and its own call's id, in the reply's field
+// `held` beside result, error and node (A-244).
+type Held struct {
+	Asked string `json:"asked"`
+	Call  string `json:"call"`
+}
+
+// GatedEndedEvent is the seat's event a call's end is said on, kept last per subject for GatedEndedKeptFor (§677).
+const (
+	GatedEndedEvent   = seatdef.GatedEndedEvent
+	GatedEndedKeptFor = seatdef.GatedEndedKeptDays * 24 * time.Hour
+)
+
+// The outcomes of a held call (§677).
+const (
+	OutcomeRan      = "ran"
+	OutcomeDeclined = "declined"
+	OutcomeExpired  = "expired"
+	OutcomeRefused  = "refused"
+)
+
+// KindGateUnanswered is the holder's finding of a waiting call past its ask's 60 minutes with no decided heard (§677),
+// its id the call's.
+const KindGateUnanswered = "gate-unanswered"
+
+// GatedEnded is a held call's end as the holder says it (§677): no argument is in it.
+type GatedEnded struct {
+	Call     string `json:"call"`
+	Ask      string `json:"ask"`
+	Act      string `json:"act"`
+	Verb     string `json:"verb"`
+	Outcome  string `json:"outcome"`
+	Answer   any    `json:"answer,omitempty"`
+	Approval string `json:"approval,omitempty"`
+	Error    string `json:"error,omitempty"`
+}
+
+// GatedEndedSubject is the subject one call's end is said on: `mesh.seat.<seat>.event.gated-ended.<caller>.<call>`, the
+// caller the account the bus proved, escaped as a key's name is (§677, §73).
+func GatedEndedSubject(seat, caller, call string) string {
+	return "mesh.seat." + seat + ".event." + GatedEndedEvent + "." + keys.EscapeName(caller) + "." + call
+}
+
+// WaitingCall is one call the holder keeps under `call.<id>` (§677): the call whole, the caller the bus proved, its ask,
+// and once it ended its outcome, and whether that end was said.
+type WaitingCall struct {
+	ID        string          `json:"id"`
+	Caller    string          `json:"caller"`
+	Ask       string          `json:"ask"`
+	Digest    string          `json:"digest"`
+	Act       operatorask.Act `json:"act"`
+	Address   string          `json:"address"`
+	Seat      string          `json:"seat"`
+	Verb      string          `json:"verb"`
+	Arguments json.RawMessage `json:"arguments,omitempty"`
+	// Made is when the call was made; Asked when its ask (the newest, after an ask anew) was raised or taken.
+	Made  time.Time `json:"made"`
+	Asked time.Time `json:"asked"`
+	// End is its end once it ended; Said says End was said on gated-ended.
+	End  *GatedEnded `json:"end,omitempty"`
+	Said bool        `json:"said,omitempty"`
+}
+
+func callKey(id string) string    { return "call." + id }
+func claimedKey(id string) string { return "claimed." + id }
+
+// Serves names the handler a waiting call of seat's verb runs on its Approve (§677): process.Conn's AnswerSeat gives each
+// marked verb's.
+func (g *Gate) Serves(seat, verb string, h func(caller string, args json.RawMessage) (any, error)) {
+	g.mu.Lock()
+	defer g.mu.Unlock()
+	if g.handlers == nil {
+		g.handlers = map[string]func(string, json.RawMessage) (any, error){}
+	}
+	g.handlers[seat+"."+verb] = h
+}
+
+func (g *Gate) handler(seat, verb string) func(string, json.RawMessage) (any, error) {
+	g.mu.Lock()
+	defer g.mu.Unlock()
+	return g.handlers[seat+"."+verb]
+}
+
+// Hold is a call of a marked verb the holder serves (§677). A call whose arguments may not be asked, or that comes while
+// the state approvals cannot be read or written, is refused at once and nothing is kept. One that waits (the header
+// WaitHeader) is kept as a waiting call and answered at once with Held; one that does not takes ADR 0286 §37's path: it is
+// refused naming its act's ask, and the same call made again after the Approve runs. A call of an act declined within 10
+// minutes ends declined at once, unasked.
+func (g *Gate) Hold(c Call, wait bool, run func() (any, error)) (any, *Held, error) {
+	if c.Fingerprint == "" {
+		c.Fingerprint = g.d.Build
+	}
+	if c.Fingerprint == "" {
+		return nil, nil, g.refused(c, "", "the holder's own fingerprint is unknown, so no warrant can bind its build")
+	}
+	if g.d.State == nil {
+		return nil, nil, g.refused(c, "", "its holder keeps no state "+StateName+" to keep its calls in")
+	}
+	if why := refusedUnasked(c.Args); why != "" {
+		return nil, nil, g.refused(c, "", why)
+	}
+	if why := g.held(); why != "" {
+		return nil, nil, g.refused(c, "", why)
+	}
+	act, err := ActOf(c, "") // a process holder's act names no node, so two instances raise one ask (A-255)
+	if err != nil {
+		return nil, nil, g.refused(c, "", err.Error())
+	}
+	digest, err := operatorask.ActDigest(act)
+	if err != nil {
+		return nil, nil, g.refused(c, "", err.Error())
+	}
+	if !wait {
+		answer, err := g.unheld(c, act, digest, run)
+		return answer, nil, err
+	}
+	id, err := g.askOf(c, act, digest)
+	if err != nil {
+		return nil, nil, err
+	}
+	now := g.d.Now().UTC()
+	w := WaitingCall{ID: newID(), Caller: c.Caller, Ask: id, Digest: digest, Act: act, Address: c.Address, Seat: c.Seat,
+		Verb: c.Name, Arguments: c.Args, Made: now, Asked: now}
+	if _, err := g.d.State.Create(callKey(w.ID), w); err != nil {
+		g.stateFailed(err)
+		return nil, nil, g.refused(c, digest, "its call cannot be kept in "+StateName+": "+err.Error())
+	}
+	g.stateRead()
+	g.armUnanswered(w)
+	g.d.Go(func() { g.Decided(id) }) // a choice made before the call was kept is acted on now
+	return nil, &Held{Asked: id, Call: w.ID}, nil
+}
+
+// askOf is the ask a call of the act takes (§677): the one `act.<digest>` names while it is open, else a new one, written
+// with the bus's create (so two instances raise one ask) or, over an ended one, by compare-and-set on its revision. A call
+// of an act declined within 10 minutes is refused with the time it may be asked again.
+func (g *Gate) askOf(c Call, act operatorask.Act, digest string) (string, error) {
+	key := g.actKey(digest)
+	for {
+		e, err := g.d.State.Get(key)
+		if err != nil {
+			g.stateFailed(err)
+			return "", g.refused(c, digest, "its state "+StateName+" cannot be read: "+err.Error())
+		}
+		g.stateRead()
+		id := newID()
+		if e == nil {
+			if _, err := g.d.State.Create(key, id); err != nil {
+				if isChanged(err) {
+					continue
+				}
+				g.stateFailed(err)
+				return "", g.refused(c, digest, "its act cannot be kept in "+StateName+": "+err.Error())
+			}
+			return id, g.raiseHeld(c, act, digest, id)
+		}
+		var named string
+		if err := json.Unmarshal(e.Value, &named); err != nil || named == "" {
+			return "", g.refused(c, digest, fmt.Sprintf("its act's key in %s names no ask", StateName))
+		}
+		open, until, err := g.openAsk(c.Module, named)
+		if err != nil {
+			return "", g.refused(c, digest, err.Error())
+		}
+		if !until.IsZero() {
+			return "", fmt.Errorf("Not run: the operator declined ask %s; the same call is not asked again until %s", named, formatTime(until))
+		}
+		if open {
+			return named, nil
+		}
+		if _, err := g.d.State.Update(key, id, e.Revision); err != nil {
+			if isChanged(err) {
+				continue
+			}
+			g.stateFailed(err)
+			return "", g.refused(c, digest, "its act cannot be kept in "+StateName+": "+err.Error())
+		}
+		return id, g.raiseHeld(c, act, digest, id)
+	}
+}
+
+// openAsk says whether an ask is open for another call of its act: raised and not yet ended by the router; and, when it was
+// declined within 10 minutes, until when no call of its act is asked.
+func (g *Gate) openAsk(module, id string) (bool, time.Time, error) {
+	rec, err := g.record(module, id)
+	if err != nil {
+		return false, time.Time{}, fmt.Errorf("the router's record of its ask %s cannot be read: %v", id, err)
+	}
+	if rec == nil {
+		k, _, err := g.kept(id)
+		return err == nil && k != nil && k.Ended == "", time.Time{}, nil // raised and not yet taken by the router
+	}
+	switch rec.State {
+	case "open", "held-back":
+		return true, time.Time{}, nil
+	case "chosen":
+		if w := rec.Warrant; w != nil && w.Option == OptionDecline {
+			at, _ := parseTime(w.At)
+			if until := at.Add(DeclinedFor); g.d.Now().Before(until) {
+				return false, until, nil
+			}
+		}
+	}
+	return false, time.Time{}, nil
+}
+
+// raiseHeld raises the ask the act's key names, under the holder's module's name, keeping the act and the arguments beside
+// it (§677; design 46 7-approval-mark §10).
+func (g *Gate) raiseHeld(c Call, act operatorask.Act, digest, id string) error {
+	return g.keepAskHeld(c, act, digest, g.askFor(c, digest, id))
+}
+
+// keepAskHeld is keepAsk without its write of the act's key, which askOf made first.
+func (g *Gate) keepAskHeld(c Call, act operatorask.Act, digest string, a Ask) error {
+	if size := keptSize(a, act, c.Args); size > MostKeptValue {
+		return g.refused(c, digest, fmt.Sprintf("its ask would keep %d bytes, more than the %d a value of the state %s holds", size, MostKeptValue, StateName))
+	}
+	if err := g.d.Channel.Ask(c.Module, a); err != nil {
+		return g.refused(c, digest, "the ask could not be raised: "+err.Error())
+	}
+	if err := g.keepCall(a.ID, act, c.Args); err != nil {
+		g.stateFailed(err)
+		return g.refused(c, digest, "the ask was raised and its call could not be kept: "+err.Error())
+	}
+	return nil
+}
+
+// unheld is a call that does not wait (ADR 0286 §37's path, §677): run when its act's ask is chosen Approve within 30
+// minutes and unclaimed, claimed once; otherwise refused naming the ask, raising one when none is open.
+func (g *Gate) unheld(c Call, act operatorask.Act, digest string, run func() (any, error)) (any, error) {
+	named, err := g.d.State.Get(g.actKey(digest))
+	if err != nil {
+		g.stateFailed(err)
+		return nil, g.refused(c, digest, "its state "+StateName+" cannot be read: "+err.Error())
+	}
+	g.stateRead()
+	if named != nil {
+		var id string
+		if json.Unmarshal(named.Value, &id) == nil && id != "" {
+			rec, err := g.record(c.Module, id)
+			if err != nil {
+				return nil, g.refused(c, digest, "the router's record of its ask "+id+" cannot be read: "+err.Error())
+			}
+			if rec != nil && rec.State == "chosen" && rec.Warrant != nil && rec.Warrant.Option == OptionApprove {
+				if at, _ := parseTime(rec.Warrant.At); !g.d.Now().After(at.Add(RunWithin)) {
+					out := g.claimRun(c.Module, id, *rec.Warrant, act, run)
+					switch out.outcome {
+					case OutcomeRan:
+						return g.ran(c, id, rec, out.answer, out.err)
+					case OutcomeRefused:
+						return nil, g.refused(c, digest, out.why)
+					}
+				}
+			}
+		}
+	}
+	id, err := g.askOf(c, act, digest)
+	if err != nil {
+		return nil, err
+	}
+	return nil, g.firstAnswer(c, id, digest, "")
+}
+
+// claimed is what came of a claim of a warrant for one call.
+type claimed struct {
+	outcome string // OutcomeRan, OutcomeRefused, or "" when another took it
+	answer  any
+	err     error
+	why     string
+}
+
+// claimRun holds the warrant to the ask and the call's act, claims it once at `claimed.<ask id>` with the bus's create, and
+// runs the call (§677; ADR 0286 §27, §28, §30, §31): of two instances, or two deliveries, one runs.
+func (g *Gate) claimRun(module, id string, w Warrant, act operatorask.Act, run func() (any, error)) claimed {
+	var out claimed
+	var claimErr error
+	h, err := g.d.Channel.Claim(module, w, act, func() {
+		if _, err := g.d.State.Create(claimedKey(id), map[string]string{"at": formatTime(g.d.Now().UTC())}); err != nil {
+			claimErr = err
+			return
+		}
+		out.outcome = OutcomeRan
+		out.answer, out.err = run()
+	})
+	switch {
+	case h == Claimed && claimErr != nil && !isChanged(claimErr):
+		g.stateFailed(claimErr)
+		return claimed{outcome: OutcomeRefused, why: "its claim cannot be written in " + StateName + ": " + claimErr.Error()}
+	case h == Claimed:
+		return out
+	case h == ClaimDone:
+		return claimed{}
+	case h == "" && err != nil:
+		g.stateFailed(err)
+		return claimed{outcome: OutcomeRefused, why: "its state " + StateName + " cannot be written: " + err.Error()}
+	default: // refused, or the act about to run is not the one the option bound: nothing runs
+		return claimed{outcome: OutcomeRefused, why: "its warrant does not hold: " + errText(err)}
+	}
+}
+
+// Decided acts on the router's own record of one of the holder's asks (§677): heard on the holder's `decided`, never from
+// its body, and at the start for each ask a waiting call waits on. On the Approve the oldest waiting call of the ask runs,
+// within 30 minutes of the choice, else it ends expired; every other is asked anew. A Decline ends every one declined, an
+// ask that ended without a choice every one expired, and one the router refused every one refused with its words.
+func (g *Gate) Decided(id string) {
+	module := g.d.Runner
+	rec, err := g.record(module, id)
+	if err != nil {
+		g.d.Logf("[approval] the router's record of ask %s cannot be read (%v): read again at the next start", id, err)
+		return
+	}
+	if rec == nil || rec.State == "open" || rec.State == "held-back" {
+		return
+	}
+	calls, err := g.waiting(func(w WaitingCall) bool { return w.Ask == id })
+	if err != nil {
+		g.stateFailed(err)
+		g.d.Logf("[approval] the waiting calls of ask %s cannot be read (%v): read again at the next start", id, err)
+		return
+	}
+	if len(calls) == 0 {
+		return
+	}
+	end := func(w WaitingCall, outcome, why string) {
+		g.end(w, GatedEnded{Outcome: outcome, Error: why})
+	}
+	switch {
+	case rec.State == "refused":
+		for _, w := range calls {
+			end(w, OutcomeRefused, "the router refused its ask "+id+": "+orNone(rec.Answer))
+		}
+		return
+	case rec.State != "chosen":
+		for _, w := range calls {
+			end(w, OutcomeExpired, "its ask "+id+" ended "+rec.State+" with no choice; nothing ran")
+		}
+		return
+	case rec.Warrant == nil:
+		for _, w := range calls {
+			end(w, OutcomeRefused, "the router's record of its ask "+id+" is chosen and carries no warrant")
+		}
+		return
+	case rec.Warrant.Option == OptionDecline:
+		for _, w := range calls {
+			end(w, OutcomeDeclined, "the operator declined ask "+id+"; nothing ran")
+		}
+		return
+	}
+	first, rest := calls[0], calls[1:]
+	at, _ := parseTime(rec.Warrant.At)
+	if g.d.Now().After(at.Add(RunWithin)) {
+		end(first, OutcomeExpired, "the Approve of ask "+id+" was heard more than 30 minutes after it was given; nothing ran")
+	} else {
+		g.runWaiting(first, rec)
+	}
+	for _, w := range rest {
+		g.anew(w)
+	}
+}
+
+// runWaiting claims and runs one waiting call on its ask's warrant, saying its end.
+func (g *Gate) runWaiting(w WaitingCall, rec *Record) {
+	h := g.handler(w.Seat, w.Verb)
+	c := Call{Address: w.Address, Module: g.d.Runner, Seat: w.Seat, Name: w.Verb, Caller: w.Caller, Args: w.Arguments}
+	if h == nil {
+		g.end(w, GatedEnded{Outcome: OutcomeRefused, Error: "the holder serves no handler of " + w.Address + " now; nothing ran"})
+		return
+	}
+	out := g.claimRun(g.d.Runner, w.Ask, *rec.Warrant, w.Act, func() (any, error) { return h(w.Caller, w.Arguments) })
+	switch out.outcome {
+	case "": // another instance, or another call of the same ask, took the warrant
+		return
+	case OutcomeRefused:
+		g.end(w, GatedEnded{Outcome: OutcomeRefused, Error: out.why})
+		return
+	}
+	answered, err := g.ran(c, w.Ask, rec, out.answer, out.err)
+	if err != nil {
+		g.end(w, GatedEnded{Outcome: OutcomeRan, Error: err.Error()})
+		return
+	}
+	a := answered.(Answered)
+	g.end(w, GatedEnded{Outcome: OutcomeRan, Answer: a.Answer, Approval: a.Approval})
+}
+
+// anew asks a waiting call's act anew, as a new ask (ADR 0286 §33: a second run takes a second approval); its end comes
+// when its own ask ends.
+func (g *Gate) anew(w WaitingCall) {
+	c := Call{Address: w.Address, Module: g.d.Runner, Seat: w.Seat, Name: w.Verb, Caller: w.Caller, Args: w.Arguments,
+		Fingerprint: w.Act["build"]}
+	id, err := g.askOf(c, w.Act, w.Digest)
+	if err != nil {
+		g.end(w, GatedEnded{Outcome: OutcomeRefused, Error: err.Error()})
+		return
+	}
+	if err := g.updateCall(w.ID, func(k *WaitingCall) { k.Ask, k.Asked = id, g.d.Now().UTC() }); err != nil {
+		g.d.Logf("[approval] the call %s, asked anew as ask %s, cannot be kept (%v)", w.ID, id, err)
+		return
+	}
+	w.Ask, w.Asked = id, g.d.Now().UTC()
+	g.rearmUnanswered(w)
+	g.d.Go(func() { g.Decided(id) })
+}
+
+// end keeps a waiting call's end, then says it on gated-ended (§677); an end not said is said again at the next start.
+func (g *Gate) end(w WaitingCall, e GatedEnded) {
+	e.Call, e.Ask, e.Act, e.Verb = w.ID, w.Ask, w.Digest, w.Verb
+	ended := false
+	if err := g.updateCall(w.ID, func(k *WaitingCall) {
+		if k.End == nil {
+			k.End, ended = &e, true
+		}
+	}); err != nil {
+		g.d.Logf("[approval] the end %s of call %s cannot be kept (%v)", e.Outcome, w.ID, err)
+		return
+	}
+	if ended {
+		g.say(w.ID)
+	}
+}
+
+// say says a kept end on gated-ended and marks it said; its finding gate-unanswered is cleared.
+func (g *Gate) say(id string) {
+	e, err := g.d.State.Get(callKey(id))
+	if err != nil || e == nil {
+		return
+	}
+	var w WaitingCall
+	if json.Unmarshal(e.Value, &w) != nil || w.End == nil || w.Said {
+		return
+	}
+	// Its bound key still kept says gate-unanswered was not raised, and the key goes; one the bus ended is cleared once the
+	// end is said (A-255).
+	b, err := g.d.State.Get(unansweredHeldKey(id))
+	raised := err == nil && b == nil
+	if b != nil && g.d.Bounds != nil {
+		_ = g.d.Bounds.Delete(unansweredHeldKey(id))
+	}
+	if g.d.Say == nil {
+		g.d.Logf("[approval] the end %s of call %s is not said: the holder says no gated-ended", w.End.Outcome, id)
+		return
+	}
+	if err := g.d.Say(GatedEndedSubject(w.Seat, w.Caller, w.ID), *w.End, GatedEndedEvent+"."+w.ID); err != nil {
+		g.d.Logf("[approval] the end %s of call %s is not said (%v): said again at the next start", w.End.Outcome, id, err)
+		return
+	}
+	g.d.Logf("[approval] %s by %s ended %s (call %s, ask %s)", w.Address, w.Caller, w.End.Outcome, id, w.Ask)
+	_ = g.updateCall(id, func(k *WaitingCall) { k.Said = true })
+	if raised && g.d.Findings != nil {
+		_ = g.d.Findings.Clear(nilCtx(), KindGateUnanswered, id, "the call's end, "+w.End.Outcome+", is said")
+	}
+}
+
+// updateCall changes a kept call by compare-and-set, again when another write came first.
+func (g *Gate) updateCall(id string, change func(*WaitingCall)) error {
+	for {
+		e, err := g.d.State.Get(callKey(id))
+		if err != nil || e == nil {
+			return fmt.Errorf("the call %s cannot be read: %v", id, err)
+		}
+		var w WaitingCall
+		if err := json.Unmarshal(e.Value, &w); err != nil {
+			return err
+		}
+		change(&w)
+		if _, err := g.d.State.Update(callKey(id), w, e.Revision); err == nil {
+			return nil
+		} else if !isChanged(err) {
+			return err
+		}
+	}
+}
+
+// waiting is every kept call that has not ended and that keep takes, oldest first.
+func (g *Gate) waiting(keep func(WaitingCall) bool) ([]WaitingCall, error) {
+	all, err := g.calls()
+	if err != nil {
+		return nil, err
+	}
+	var out []WaitingCall
+	for _, w := range all {
+		if w.End == nil && keep(w) {
+			out = append(out, w)
+		}
+	}
+	return out, nil
+}
+
+// calls is every kept call, oldest first.
+func (g *Gate) calls() ([]WaitingCall, error) {
+	names, err := g.d.State.Keys()
+	if err != nil {
+		return nil, err
+	}
+	var out []WaitingCall
+	for _, key := range names {
+		if !strings.HasPrefix(key, "call.") {
+			continue
+		}
+		e, err := g.d.State.Get(key)
+		if err != nil {
+			return nil, err
+		}
+		var w WaitingCall
+		if e == nil || json.Unmarshal(e.Value, &w) != nil {
+			continue
+		}
+		out = append(out, w)
+	}
+	sort.Slice(out, func(i, j int) bool { return out[i].Made.Before(out[j].Made) })
+	return out, nil
+}
+
+// unansweredHeldKey is a waiting call's bound key in the holder's state approvals (lead answer A-255): created with the
+// ask's 60 minutes as its own time to live, its expiry heard as the bus's event raises gate-unanswered.
+func unansweredHeldKey(call string) string { return "unanswered." + call }
+
+// armUnanswered keeps the waiting call's bound key (§677; A-255): when its ask's 60 minutes pass with no end of it, the bus
+// ends the key and the holder, hearing that, raises gate-unanswered; no clock waits in the process. A call already past its
+// 60 minutes (its key ended while the holder was away) is judged at once.
+func (g *Gate) armUnanswered(w WaitingCall) {
+	left := w.Asked.Add(AskLasts).Sub(g.d.Now())
+	if left <= 0 {
+		g.heldUnanswered(w.ID)
+		return
+	}
+	if g.d.Bounds == nil {
+		g.d.Logf("[approval] the call %s waits on ask %s with no bound kept: the holder's %s keeps no key with its own time to live",
+			w.ID, w.Ask, StateName)
+		return
+	}
+	if err := g.d.Bounds.CreateTTL(unansweredHeldKey(w.ID), map[string]string{"call": w.ID, "ask": w.Ask}, left); err != nil && !isChanged(err) {
+		g.d.Logf("[approval] the bound of call %s on ask %s is not kept: %v", w.ID, w.Ask, err)
+	}
+}
+
+// rearmUnanswered keeps a call asked anew under a new bound of its new ask's 60 minutes.
+func (g *Gate) rearmUnanswered(w WaitingCall) {
+	if g.d.Bounds != nil {
+		_ = g.d.Bounds.Delete(unansweredHeldKey(w.ID))
+	}
+	g.armUnanswered(w)
+}
+
+// heldUnanswered is a waiting call's bound ended (A-255): gate-unanswered raised while the call has no end.
+func (g *Gate) heldUnanswered(id string) {
+	e, err := g.d.State.Get(callKey(id))
+	if err != nil || e == nil {
+		return
+	}
+	var w WaitingCall
+	if json.Unmarshal(e.Value, &w) != nil || w.End != nil || g.d.Findings == nil {
+		return
+	}
+	if err := g.d.Findings.Raise(nilCtx(), KindGateUnanswered, w.ID, fmt.Sprintf("the call %s of %s by %s waits on ask %s, "+
+		"past its %s with no decided heard: nothing ran; the holder's %s.approvals reads it", w.ID, w.Address, w.Caller, w.Ask,
+		AskLasts, w.Seat), "a call waits on an unanswered ask"); err != nil {
+		g.d.Logf("[approval] the finding %s of call %s is not kept: %v", KindGateUnanswered, w.ID, err)
+	}
+}
+
+// watchHeld hears the waiting calls' bound keys end (A-255) for the life of the holder's connection.
+func (g *Gate) watchHeld() error {
+	if g.d.Bounds == nil {
+		return nil
+	}
+	_, err := g.d.Bounds.Watch("unanswered.*", func(key string) { g.heldUnanswered(strings.TrimPrefix(key, "unanswered.")) })
+	return err
+}
+
+// StartHolding is the holder's read at its start (§677): every waiting call is read, each ask already decided acted on as
+// when its decided is heard, each end not yet said said, each waiting call's 60 minutes armed, and every acted, unrecorded
+// run recorded. A state that cannot be read leaves every marked call refused until it can.
+func (g *Gate) StartHolding() error {
+	all, err := g.calls()
+	if err != nil {
+		g.stateFailed(err)
+		return fmt.Errorf("the waiting calls in %s cannot be read: %w", StateName, err)
+	}
+	g.stateRead()
+	if err := g.watchHeld(); err != nil {
+		return fmt.Errorf("the bound keys in %s cannot be watched: %w", StateName, err)
+	}
+	asks := map[string]bool{}
+	for _, w := range all {
+		switch {
+		case w.End != nil && !w.Said:
+			g.say(w.ID)
+		case w.End == nil:
+			g.armUnanswered(w)
+			asks[w.Ask] = true
+		}
+	}
+	ids := make([]string, 0, len(asks))
+	for id := range asks {
+		ids = append(ids, id)
+	}
+	sort.Strings(ids)
+	for _, id := range ids {
+		g.Decided(id)
+	}
+	g.Recover()
+	return nil
+}
+
+// Approvals is the seat's verb `approvals` (§677): the waiting and ended calls with their caller, ask and state, the
+// `act.` keys and the claims; a call's arguments only to that call's caller.
+type Approvals struct {
+	Calls  []ListedCall `json:"calls"`
+	Acts   []ListedAct  `json:"acts"`
+	Claims []string     `json:"claims"`
+}
+
+// ListedCall is one kept call as `approvals` lists it.
+type ListedCall struct {
+	Call      string          `json:"call"`
+	Caller    string          `json:"caller"`
+	Ask       string          `json:"ask"`
+	Verb      string          `json:"verb"`
+	State     string          `json:"state"`
+	Made      time.Time       `json:"made"`
+	End       *GatedEnded     `json:"end,omitempty"`
+	Arguments json.RawMessage `json:"arguments,omitempty"`
+}
+
+// ListedAct is one `act.` key: its digest, escaped as kept, and the ask it names.
+type ListedAct struct {
+	Act string `json:"act"`
+	Ask string `json:"ask"`
+}
+
+// Approvals answers the verb for caller, the account the bus proved.
+func (g *Gate) Approvals(caller string) (Approvals, error) {
+	out := Approvals{Calls: []ListedCall{}, Acts: []ListedAct{}, Claims: []string{}}
+	if g.d.State == nil {
+		return out, fmt.Errorf("the holder keeps no state %s", StateName)
+	}
+	all, err := g.calls()
+	if err != nil {
+		return out, fmt.Errorf("the state %s cannot be read: %w", StateName, err)
+	}
+	for _, w := range all {
+		l := ListedCall{Call: w.ID, Caller: w.Caller, Ask: w.Ask, Verb: w.Verb, State: "waiting", Made: w.Made, End: w.End}
+		if w.End != nil {
+			l.State = w.End.Outcome
+		}
+		if caller != "" && caller == w.Caller {
+			l.Arguments = w.Arguments
+		}
+		out.Calls = append(out.Calls, l)
+	}
+	names, err := g.d.State.Keys()
+	if err != nil {
+		return out, fmt.Errorf("the state %s cannot be read: %w", StateName, err)
+	}
+	sort.Strings(names)
+	for _, key := range names {
+		switch {
+		case strings.HasPrefix(key, "act."):
+			e, err := g.d.State.Get(key)
+			var id string
+			if err == nil && e != nil {
+				_ = json.Unmarshal(e.Value, &id)
+			}
+			out.Acts = append(out.Acts, ListedAct{Act: strings.TrimPrefix(key, "act."), Ask: id})
+		case strings.HasPrefix(key, "claimed."):
+			out.Claims = append(out.Claims, strings.TrimPrefix(key, "claimed."))
+		}
+	}
+	return out, nil
+}
+
+func nilCtx() context.Context { return context.Background() }

go/approval/held_test.go

@@ -0,0 +1,439 @@
+package approval
+
+import (
+	"context"
+	"encoding/json"
+	"fmt"
+	"sort"
+	"strings"
+	"sync"
+	"testing"
+	"time"
+
+	stdio "git.novox.be/novox/mesh-sdk/go"
+	"git.novox.be/novox/mesh-sdk/go/operatorask"
+)
+
+// memStore is the holder's state approvals in memory: create refuses a key that exists, update is compare-and-set.
+type memStore struct {
+	mu   sync.Mutex
+	vals map[string][]byte
+	revs map[string]uint64
+	rev  uint64
+	fail error
+}
+
+func newMem() *memStore { return &memStore{vals: map[string][]byte{}, revs: map[string]uint64{}} }
+
+func (m *memStore) Get(key string) (*stdio.StateEntry, error) {
+	m.mu.Lock()
+	defer m.mu.Unlock()
+	if m.fail != nil {
+		return nil, m.fail
+	}
+	v, ok := m.vals[key]
+	if !ok {
+		return nil, nil
+	}
+	return &stdio.StateEntry{Key: key, Value: v, Revision: m.revs[key]}, nil
+}
+
+func (m *memStore) write(key string, value any, check func(exists bool, rev uint64) bool) (uint64, error) {
+	m.mu.Lock()
+	defer m.mu.Unlock()
+	if m.fail != nil {
+		return 0, m.fail
+	}
+	_, exists := m.vals[key]
+	if !check(exists, m.revs[key]) {
+		return 0, stdio.ErrChanged
+	}
+	raw, err := json.Marshal(value)
+	if err != nil {
+		return 0, err
+	}
+	m.rev++
+	m.vals[key], m.revs[key] = raw, m.rev
+	return m.rev, nil
+}
+
+func (m *memStore) Create(key string, value any) (uint64, error) {
+	return m.write(key, value, func(exists bool, _ uint64) bool { return !exists })
+}
+func (m *memStore) Update(key string, value any, revision uint64) (uint64, error) {
+	return m.write(key, value, func(exists bool, rev uint64) bool { return exists && rev == revision })
+}
+func (m *memStore) Put(key string, value any) (uint64, error) {
+	return m.write(key, value, func(bool, uint64) bool { return true })
+}
+func (m *memStore) Keys() ([]string, error) {
+	m.mu.Lock()
+	defer m.mu.Unlock()
+	if m.fail != nil {
+		return nil, m.fail
+	}
+	var out []string
+	for k := range m.vals {
+		out = append(out, k)
+	}
+	sort.Strings(out)
+	return out, nil
+}
+
+// bounds is the holder's bound keys in its state approvals as a fake (A-255): each key kept in the state with its time to
+// live, expire ending it as the bus does and handing it to the watch.
+type bounds struct {
+	state   *memStore
+	mu      sync.Mutex
+	ttl     map[string]time.Duration
+	watched func(string)
+}
+
+func (b *bounds) CreateTTL(key string, value any, ttl time.Duration) error {
+	if _, err := b.state.Create(key, value); err != nil {
+		return err
+	}
+	b.mu.Lock()
+	defer b.mu.Unlock()
+	b.ttl[key] = ttl
+	return nil
+}
+func (b *bounds) Delete(key string) error {
+	b.state.delete(key)
+	b.mu.Lock()
+	defer b.mu.Unlock()
+	delete(b.ttl, key)
+	return nil
+}
+func (b *bounds) Watch(pattern string, expired func(string)) (func(), error) {
+	b.mu.Lock()
+	defer b.mu.Unlock()
+	b.watched = expired
+	return func() {}, nil
+}
+func (b *bounds) expire(key string) {
+	b.mu.Lock()
+	_, ok := b.ttl[key]
+	delete(b.ttl, key)
+	w := b.watched
+	b.mu.Unlock()
+	b.state.delete(key)
+	if ok && w != nil {
+		w(key)
+	}
+}
+
+func (m *memStore) delete(key string) {
+	m.mu.Lock()
+	defer m.mu.Unlock()
+	delete(m.vals, key)
+	delete(m.revs, key)
+}
+
+// router is the operator channel as a fake: it keeps each ask the gate raises, and the test decides its record.
+type router struct {
+	mu      sync.Mutex
+	state   Store
+	asks    []Ask
+	records map[string]*Record
+}
+
+func (r *router) Ask(module string, a Ask) error {
+	raw, _ := json.Marshal(a)
+	if _, err := r.state.Create("ask."+a.ID, kept{Ask: raw, Asked: time.Now()}); err != nil {
+		return err
+	}
+	r.mu.Lock()
+	defer r.mu.Unlock()
+	r.asks = append(r.asks, a)
+	return nil
+}
+func (r *router) Record(module, id string) (*Record, error) {
+	r.mu.Lock()
+	defer r.mu.Unlock()
+	return r.records[id], nil
+}
+func (r *router) Claim(module string, w Warrant, act operatorask.Act, run func()) (Claim, error) {
+	e, _ := r.state.Get("ask." + w.Ask)
+	if e == nil {
+		return ClaimRefused, fmt.Errorf("no ask %s", w.Ask)
+	}
+	var k kept
+	_ = json.Unmarshal(e.Value, &k)
+	if k.Acted {
+		return ClaimDone, nil
+	}
+	var a Ask
+	_ = json.Unmarshal(k.Ask, &a)
+	digest, _ := operatorask.ActDigest(act)
+	if a.About != digest {
+		return ClaimRefused, fmt.Errorf("the option binds another act")
+	}
+	k.Acted = true
+	if _, err := r.state.Update("ask."+w.Ask, k, e.Revision); err != nil {
+		return ClaimDone, nil
+	}
+	run()
+	return Claimed, nil
+}
+func (r *router) Cancel(module, id string) error { return nil }
+func (r *router) Decided(module string) string   { return "decided." + module }
+func (r *router) Seat() string                   { return "operator-channel" }
+
+func (r *router) choose(id, option string, at time.Time) {
+	r.mu.Lock()
+	defer r.mu.Unlock()
+	r.records[id] = &Record{State: "chosen", OfferedOn: []string{"telegram"},
+		Warrant: &Warrant{Ask: id, Asker: "holder", Option: option, Channel: "telegram", At: formatTime(at)}}
+}
+
+type findings struct {
+	mu     sync.Mutex
+	raised map[string]bool
+	heard  chan string
+}
+
+func (f *findings) Raise(_ context.Context, kind, id, _, _ string) error {
+	f.mu.Lock()
+	defer f.mu.Unlock()
+	f.raised[kind+" "+id] = true
+	if f.heard != nil {
+		f.heard <- kind + " " + id
+	}
+	return nil
+}
+func (f *findings) Clear(_ context.Context, kind, id, _ string) error {
+	f.mu.Lock()
+	defer f.mu.Unlock()
+	delete(f.raised, kind+" "+id)
+	return nil
+}
+
+// Design 47 G §677 (lead answers A-158, A-209, A-244): a process holder's marked verb is one call with a gate before its
+// running, its waiting calls, act keys and claims kept in its own state.
+func TestAHolderHoldsAMarkedCall(t *testing.T) {
+	now := time.Date(2026, 11, 12, 10, 0, 0, 0, time.UTC)
+	type world struct {
+		g      *Gate
+		state  *memStore
+		router *router
+		said   map[string]GatedEnded
+		ran    *int
+		recs   *int
+		finds  *findings
+		after  chan time.Time
+		bounds *bounds
+	}
+	newGate := func(state *memStore, r *router, ran, recs *int, said map[string]GatedEnded, after chan time.Time, f *findings, b *bounds) *Gate {
+		g := New(Deps{Node: "n1", Runner: "holder", Holding: true, Build: "fp1", State: state, Channel: r, Findings: f, Bounds: b,
+			Now: func() time.Time { return now }, Go: func(f func()) { f() },
+			After: func(d time.Duration) <-chan time.Time {
+				if d < time.Minute { // the record's short pauses pass at once
+					fired := make(chan time.Time)
+					close(fired)
+					return fired
+				}
+				return after
+			},
+			Warranted: func(asker, ask string, open func() (bool, error)) error {
+				*recs++
+				return nil
+			},
+			Say: func(subject string, body any, id string) error {
+				said[subject] = body.(GatedEnded)
+				return nil
+			}})
+		g.Serves("wiper", "wipe", func(caller string, args json.RawMessage) (any, error) { *ran++; return "wiped", nil })
+		return g
+	}
+	setup := func() world {
+		state := newMem()
+		r := &router{state: state, records: map[string]*Record{}}
+		ran, recs := 0, 0
+		w := world{state: state, router: r, said: map[string]GatedEnded{}, ran: &ran, recs: &recs,
+			finds: &findings{raised: map[string]bool{}}, after: make(chan time.Time), bounds: &bounds{state: state, ttl: map[string]time.Duration{}}}
+		w.g = newGate(state, r, w.ran, w.recs, w.said, w.after, w.finds, w.bounds)
+		return w
+	}
+	call := func(caller, args string) Call {
+		return Call{Address: "wiper.wipe", Module: "holder", Seat: "wiper", Name: "wipe", Caller: caller, Args: json.RawMessage(args)}
+	}
+	hold := func(t *testing.T, w world, c Call, wait bool) (any, *Held, error) {
+		return w.g.Hold(c, wait, func() (any, error) { *w.ran++; return "wiped", nil })
+	}
+	ended := func(w world, caller, id string) GatedEnded { return w.said[GatedEndedSubject("wiper", caller, id)] }
+
+	t.Run("asked, run once on the Approve, its end said to its caller", func(t *testing.T) {
+		w := setup()
+		_, h, err := hold(t, w, call("n1.caller", `{"dir":"scratch"}`), true)
+		if err != nil || h == nil || h.Asked == "" || h.Call == "" {
+			t.Fatalf("held %+v, %v", h, err)
+		}
+		if e, _ := w.state.Get("call." + h.Call); e == nil {
+			t.Fatal("no call kept")
+		}
+		w.router.choose(h.Asked, OptionApprove, now)
+		w.g.Decided(h.Asked)
+		w.g.Decided(h.Asked) // heard twice: run once
+		end := ended(w, "n1.caller", h.Call)
+		if *w.ran != 1 || end.Outcome != OutcomeRan || end.Answer != "wiped" || !strings.Contains(end.Approval, h.Asked) || *w.recs != 1 {
+			t.Fatalf("ran %d, recorded %d, end %+v", *w.ran, *w.recs, end)
+		}
+		if e, _ := w.state.Get("claimed." + h.Asked); e == nil {
+			t.Error("no claim kept")
+		}
+		a, _ := w.g.Approvals("someone.else")
+		if len(a.Calls) != 1 || a.Calls[0].Arguments != nil || a.Calls[0].State != OutcomeRan || len(a.Acts) != 1 || len(a.Claims) != 1 {
+			t.Errorf("approvals %+v", a)
+		}
+		if a, _ := w.g.Approvals("n1.caller"); string(a.Calls[0].Arguments) != `{"dir":"scratch"}` {
+			t.Errorf("its caller reads %s", a.Calls[0].Arguments)
+		}
+	})
+	t.Run("a second call of the act takes the same ask, asked anew after the first runs", func(t *testing.T) {
+		w := setup()
+		_, h1, _ := hold(t, w, call("n1.a", `{}`), true)
+		now = now.Add(time.Second)
+		_, h2, _ := hold(t, w, call("n1.b", `{}`), true)
+		if h1.Asked != h2.Asked || h1.Call == h2.Call {
+			t.Fatalf("asks %s and %s", h1.Asked, h2.Asked)
+		}
+		w.router.choose(h1.Asked, OptionApprove, now)
+		w.g.Decided(h1.Asked)
+		if *w.ran != 1 || ended(w, "n1.a", h1.Call).Outcome != OutcomeRan || ended(w, "n1.b", h2.Call).Outcome != "" {
+			t.Fatalf("ran %d; ends %v", *w.ran, w.said)
+		}
+		e, _ := w.state.Get("call." + h2.Call)
+		var second WaitingCall
+		_ = json.Unmarshal(e.Value, &second)
+		if second.Ask == h1.Asked || len(w.router.asks) != 2 {
+			t.Errorf("the second call waits on %s (asks %d)", second.Ask, len(w.router.asks))
+		}
+	})
+	t.Run("a decline runs nothing; a call within 10 minutes ends declined unasked", func(t *testing.T) {
+		w := setup()
+		_, h, _ := hold(t, w, call("n1.a", `{}`), true)
+		w.router.choose(h.Asked, OptionDecline, now)
+		w.g.Decided(h.Asked)
+		if *w.ran != 0 || ended(w, "n1.a", h.Call).Outcome != OutcomeDeclined {
+			t.Fatalf("ran %d, end %+v", *w.ran, ended(w, "n1.a", h.Call))
+		}
+		if _, h2, err := hold(t, w, call("n1.a", `{}`), true); err == nil || h2 != nil || !strings.Contains(err.Error(), "declined") || len(w.router.asks) != 1 {
+			t.Errorf("a call within 10 minutes: %v, %d asks", err, len(w.router.asks))
+		}
+	})
+	t.Run("heard 31 minutes after the choice, it ends expired", func(t *testing.T) {
+		w := setup()
+		_, h, _ := hold(t, w, call("n1.a", `{}`), true)
+		w.router.choose(h.Asked, OptionApprove, now.Add(-31*time.Minute))
+		w.g.Decided(h.Asked)
+		if *w.ran != 0 || ended(w, "n1.a", h.Call).Outcome != OutcomeExpired {
+			t.Fatalf("ran %d, end %+v", *w.ran, ended(w, "n1.a", h.Call))
+		}
+	})
+	t.Run("a secret-shaped argument refused, nothing kept", func(t *testing.T) {
+		w := setup()
+		if _, h, err := hold(t, w, call("n1.a", `{"token":"ghp_0123456789abcdefghijklmnopqrstuvwxyzAB"}`), true); err == nil || h != nil {
+			t.Fatalf("held %+v, %v", h, err)
+		}
+		if keys, _ := w.state.Keys(); len(keys) != 0 || len(w.router.asks) != 0 || len(w.bounds.ttl) != 0 {
+			t.Errorf("kept %v, asked %d", keys, len(w.router.asks))
+		}
+	})
+	t.Run("a call with no wait refused with the ask, and run when made again after the Approve", func(t *testing.T) {
+		w := setup()
+		_, h, err := hold(t, w, call("n1.a", `{}`), false)
+		if err == nil || h != nil || len(w.router.asks) != 1 || !strings.Contains(err.Error(), w.router.asks[0].ID) {
+			t.Fatalf("first: %v", err)
+		}
+		w.router.choose(w.router.asks[0].ID, OptionApprove, now)
+		answer, _, err := hold(t, w, call("n1.a", `{}`), false)
+		if a, ok := answer.(Answered); err != nil || !ok || a.Answer != "wiped" || *w.ran != 1 {
+			t.Fatalf("again: %+v, %v", answer, err)
+		}
+	})
+	t.Run("a restart between the ask and the Approve runs the waiting call once", func(t *testing.T) {
+		w := setup()
+		_, h, _ := hold(t, w, call("n1.a", `{}`), true)
+		w.router.choose(h.Asked, OptionApprove, now)
+		again := newGate(w.state, w.router, w.ran, w.recs, w.said, w.after, w.finds, w.bounds)
+		if err := again.StartHolding(); err != nil || *w.ran != 1 || ended(w, "n1.a", h.Call).Outcome != OutcomeRan {
+			t.Fatalf("start: %v, ran %d", err, *w.ran)
+		}
+		_ = again.StartHolding()
+		if *w.ran != 1 {
+			t.Errorf("ran %d after a second start", *w.ran)
+		}
+	})
+	t.Run("past its ask's 60 minutes with no decided, gate-unanswered on its bound key's end", func(t *testing.T) {
+		// A-255: a bound key with the ask's 60 minutes to live in the state approvals, never a clock wait.
+		w := setup()
+		if err := w.g.StartHolding(); err != nil {
+			t.Fatal(err)
+		}
+		_, h, _ := hold(t, w, call("n1.a", `{}`), true)
+		key := "unanswered." + h.Call
+		if ttl := w.bounds.ttl[key]; ttl != AskLasts {
+			t.Fatalf("bound %s kept for %s (%v)", key, ttl, w.bounds.ttl)
+		}
+		if w.finds.raised[KindGateUnanswered+" "+h.Call] {
+			t.Fatal("raised before its bound ended")
+		}
+		w.bounds.expire(key)
+		if !w.finds.raised[KindGateUnanswered+" "+h.Call] {
+			t.Errorf("not raised on its bound's end: %v", w.finds.raised)
+		}
+		w.router.choose(h.Asked, OptionDecline, now)
+		w.g.Decided(h.Asked)
+		if w.finds.raised[KindGateUnanswered+" "+h.Call] {
+			t.Error("not cleared once its end is said")
+		}
+	})
+	t.Run("a call whose bound ended while the holder was away is judged at its start", func(t *testing.T) {
+		w := setup()
+		_, h, _ := hold(t, w, call("n1.a", `{}`), true)
+		w.bounds.watched = nil
+		w.bounds.expire("unanswered." + h.Call) // the bus ended it with nobody watching
+		now = now.Add(AskLasts + time.Minute)
+		defer func() { now = now.Add(-AskLasts - time.Minute) }()
+		again := newGate(w.state, w.router, w.ran, w.recs, w.said, w.after, w.finds, w.bounds)
+		if err := again.StartHolding(); err != nil || !w.finds.raised[KindGateUnanswered+" "+h.Call] {
+			t.Errorf("start: %v, raised %v", err, w.finds.raised)
+		}
+	})
+	t.Run("two instances of the holder raise one ask and run once", func(t *testing.T) {
+		// A-255: a process holder's act names no node.
+		w := setup()
+		other := New(Deps{Node: "n2", Runner: "holder", Holding: true, Build: "fp1", State: w.state, Channel: w.router,
+			Findings: w.finds, Bounds: w.bounds, Now: func() time.Time { return now }, Go: func(f func()) { f() },
+			Say: func(subject string, body any, id string) error { w.said[subject] = body.(GatedEnded); return nil }})
+		other.Serves("wiper", "wipe", func(string, json.RawMessage) (any, error) { *w.ran++; return "wiped", nil })
+		_, h1, _ := hold(t, w, call("n1.a", `{}`), true)
+		_, h2, err := other.Hold(call("n2.b", `{}`), true, nil)
+		if err != nil || h2 == nil || h2.Asked != h1.Asked || len(w.router.asks) != 1 {
+			t.Fatalf("second instance: %+v, %v; asks %d", h2, err, len(w.router.asks))
+		}
+		if strings.Contains(w.router.asks[0].About, "n1") {
+			t.Errorf("the ask binds %s", w.router.asks[0].About)
+		}
+		var first WaitingCall
+		e, _ := w.state.Get("call." + h1.Call)
+		_ = json.Unmarshal(e.Value, &first)
+		if _, ok := first.Act["node"]; ok {
+			t.Errorf("the act names a node: %v", first.Act)
+		}
+		w.router.choose(h1.Asked, OptionApprove, now)
+		w.g.Decided(h1.Asked)
+		other.Decided(h1.Asked)
+		if *w.ran != 1 {
+			t.Errorf("ran %d", *w.ran)
+		}
+	})
+	t.Run("a state that cannot be read refuses every marked call", func(t *testing.T) {
+		w := setup()
+		w.state.fail = fmt.Errorf("the bus is away")
+		if _, h, err := hold(t, w, call("n1.a", `{}`), true); err == nil || h != nil || *w.ran != 0 {
+			t.Fatalf("held %+v, %v", h, err)
+		}
+	})
+}

go/approval/marks.go

@@ -0,0 +1,172 @@
+// Package approval is the one gate on a call that needs the operator's approval (design 46 7-approval-mark; design 47 G
+// §677, lead answer A-224): the tool runner's and a module's process's seat server's. It holds the marks it reads from the
+// catalog half, the act it digests, the ask it raises on the seat operator-channel under the marked module's name, the judging of the same call again on the router's record, the claim, the recording in the
+// hand-act log, and the refusals when a part of the check is missing (§5, §8 to §20). No module's name is written here.
+package approval
+
+import (
+	"encoding/json"
+	"fmt"
+	"sort"
+	"strings"
+
+	"git.novox.be/novox/mesh-sdk/go/buscompose"
+	"git.novox.be/novox/mesh-sdk/go/seatdef"
+)
+
+// Catalog is what the marks are read from: the catalog half the runner follows (design 46 7-approval-mark §5, design 47 G
+// §196, §443) and the seat definitions it carries (§2).
+type Catalog interface {
+	// Ready is nil once the catalog half's first view is read, else says what it waits for.
+	Ready() error
+	// Revision is the catalog revision the marks are read at, as the runner names it.
+	Revision() string
+	// Served is the entry of the build a bundle serves, by the fingerprint its composed environment carries; false when
+	// none is read (not yet, or not found), with why.
+	Served(fingerprint string) (Entry, bool, string)
+	// Newest is the module's entry at the newest revision; false when the catalog half lists none.
+	Newest(module string) (Entry, bool)
+	// Definitions are the seat definitions the catalog half carries, by seat.
+	Definitions() map[string]seatdef.Definition
+	// Entries are the newest entry of every module in every followed branch's half, a marked wait's marks (lead answer
+	// A-168).
+	Entries() []Entry
+}
+
+// Marks is what one module's calls are gated by: its marked tools and seat verbs, and the subjects of its marked events and
+// restricted streams, each with its source (§18: its module's entry in the catalog half, or its seat's definition).
+type Marks struct {
+	Module string
+	// Tools are its marked tools by name, Verbs its marked seat verbs as `<seat>.<verb>`, Subjects the bus subjects of its
+	// marked events and restricted streams (design 34 every-event §33); each to its source.
+	Tools, Verbs, Subjects map[string]string
+	// Revision is the catalog revision read; Served the served entry's fingerprint, empty when it could not be read.
+	Revision, Served string
+	// Unread says why the served entry could not be read: every marked call is then refused (§5, §19).
+	Unread string
+}
+
+// Marked says whether a tool or a seat verb of the module needs the operator's approval, and its source.
+func (m Marks) Marked(seat, name string) (bool, string) {
+	if seat == "" {
+		src, ok := m.Tools[name]
+		return ok, src
+	}
+	src, ok := m.Verbs[seat+"."+name]
+	return ok, src
+}
+
+// Any says the module marks anything at all.
+func (m Marks) Any() bool { return len(m.Tools)+len(m.Verbs)+len(m.Subjects) > 0 }
+
+// marked is what an entry's manifest says of its marks: `needs-approval`, its events and its streams.
+type marked struct {
+	NeedsApproval []string `json:"needs-approval"`
+	Emits         []string `json:"emits"`
+	// Streams are read for their events and whether each carries a `grant`, and no other word, so a word added to a
+	// stream's declaration later never hides its marks.
+	Streams []struct {
+		Events []string        `json:"events"`
+		Grant  json.RawMessage `json:"grant"`
+	} `json:"streams"`
+}
+
+// Derive is a module's marks from its served entry and its newest one, unioned while they differ so a mark is never lost
+// before or after the module moves (§5, ADR 0286 §3), and the seat definitions' verb marks for every verb an entry serves,
+// which no holder unmarks (§2, §3). fingerprint is the build its bundle serves; empty, or an entry not read, leaves the
+// marks of the newest entry and the seats, with Unread saying why.
+func Derive(c Catalog, module, fingerprint string) Marks {
+	m := Marks{Module: module, Tools: map[string]string{}, Verbs: map[string]string{}, Subjects: map[string]string{},
+		Revision: c.Revision()}
+	defs := c.Definitions()
+	var entries []Entry
+	if fingerprint == "" {
+		m.Unread = "its bundle's environment carries no fingerprint, so the build it serves cannot be read"
+	} else if e, ok, why := c.Served(fingerprint); ok {
+		entries, m.Served = append(entries, e), fingerprint
+	} else {
+		m.Unread = fmt.Sprintf("the catalog half's entry of %s cannot be read: %s", fingerprint, why)
+	}
+	if e, ok := c.Newest(module); ok && (len(entries) == 0 || e.Fingerprint != entries[0].Fingerprint) {
+		entries = append(entries, e)
+	}
+	for _, e := range entries {
+		m.add(e, defs)
+	}
+	return m
+}
+
+// add takes one entry's marks into m: its `needs-approval` (a tool, a verb it serves or an event it declares), the seat
+// definitions' marks of every verb it serves, and every stream it declares with a `grant`, each with its source.
+func (m *Marks) add(e Entry, defs map[string]seatdef.Definition) {
+	source := "entry " + e.Module + " " + orNone(e.Fingerprint)
+	var said marked
+	_ = json.Unmarshal(e.Manifest, &said)
+	serves := map[string]bool{}
+	for _, sv := range e.Serves {
+		serves[sv] = true
+		seat, verb, _ := strings.Cut(sv, ".")
+		for _, v := range defs[seat].Verbs {
+			if v.Name == verb && v.NeedsApproval {
+				m.Verbs[sv] = "seat " + seat
+			}
+		}
+	}
+	events := map[string]bool{}
+	for _, ev := range said.Emits {
+		events[ev] = true
+	}
+	for _, s := range said.Streams {
+		for _, ev := range s.Events {
+			events[ev] = true
+		}
+	}
+	for _, name := range said.NeedsApproval {
+		switch {
+		case serves[name]:
+			if _, bySeat := m.Verbs[name]; !bySeat {
+				m.Verbs[name] = source
+			}
+		case events[name]:
+			for _, s := range eventSubjects(e.Module, name) {
+				m.Subjects[s] = source
+			}
+		default:
+			m.Tools[name] = source
+		}
+	}
+	for _, s := range said.Streams {
+		if len(s.Grant) == 0 || string(s.Grant) == "null" {
+			continue
+		}
+		wire := make([]string, 0, len(s.Events))
+		for _, ev := range s.Events {
+			wire = append(wire, buscompose.WirePattern(ev))
+		}
+		for _, sub := range (buscompose.ModuleStream{Module: e.Module, Events: wire}).Subjects() {
+			m.Subjects[sub] = source
+			if !strings.HasSuffix(sub, ">") {
+				m.Subjects[sub+".>"] = source
+			}
+		}
+	}
+}
+
+// eventSubjects are a marked event's subjects on the bus (design 34 every-event §33): said on the module's events and on its
+// own stream, each also with every subject below it.
+func eventSubjects(module, event string) []string {
+	ev := buscompose.WirePattern(event)
+	out := []string{"mesh.mod." + module + ".event." + ev, buscompose.ModuleStreamSubject(module, ev)}
+	if !strings.HasSuffix(ev, ">") {
+		out = append(out, out[0]+".>", out[1]+".>")
+	}
+	sort.Strings(out)
+	return out
+}
+
+func orNone(s string) string {
+	if s == "" {
+		return "none"
+	}
+	return s
+}

go/approval/record.go

@@ -0,0 +1,255 @@
+package approval
+
+import (
+	"encoding/json"
+	"errors"
+	"fmt"
+	"strings"
+	"time"
+
+	stdio "git.novox.be/novox/mesh-sdk/go"
+	"git.novox.be/novox/mesh-sdk/go/keys"
+)
+
+// The bounds of a run's recording (§13, §16; lead answers A-157, A-158).
+const (
+	UnansweredAfter = 5 * time.Minute
+	KeptFor         = 48 * time.Hour
+	SaidBefore      = time.Hour
+)
+
+// Bounds is the runner's key-ttl state `bound` (lead answers A-157, A-158): a key created with its own time to live, which
+// the bus removes when it passes, every watch hearing the removal as an expiry, so the gate's waits need no timer.
+type Bounds interface {
+	CreateTTL(key string, value any, ttl time.Duration) error
+	Delete(key string) error
+	// Watch hands expired every key under the pattern whose time to live passed, until the stop is called.
+	Watch(pattern string, expired func(key string)) (stop func(), err error)
+}
+
+// Answered is a call run on the operator's approval: the tool's own answer and the line naming the approval (§16), in the
+// form a process holder's `gated-ended` says it (design 47 G §677; lead answer A-158).
+type Answered struct {
+	Answer   any    `json:"answer"`
+	Approval string `json:"approval"`
+}
+
+// The bound keys of a run (lead answer A-158; §13).
+func (g *Gate) unansweredKey(id string) string { return g.d.Node + ".unanswered." + id }
+func (g *Gate) unrecordedKey(id string) string { return g.d.Node + ".unrecorded." + id }
+
+// ran is a call run on the operator's approval: answered with the tool's answer and the approval's line, and its warrant
+// recorded in the hand-act log (§16).
+func (g *Gate) ran(c Call, id string, rec *Record, answer any, err error) (any, error) {
+	channel := ""
+	at := ""
+	if w := rec.Warrant; w != nil {
+		channel, at = w.Channel, w.At
+	}
+	if channel == "" {
+		channel = strings.Join(rec.OfferedOn, ", ")
+	}
+	line := fmt.Sprintf("run on the operator's approval via %s at %s, ask %s", orNone(channel), at, id)
+	g.d.Logf("[approval] %s on %s %s", c.Address, g.d.Node, line)
+	g.bindRecording(c.Module, id)
+	g.d.Go(func() { g.recordRun(c.Module, id) })
+	if err != nil {
+		return nil, fmt.Errorf("%w (%s)", err, line)
+	}
+	return Answered{Answer: answer, Approval: line}, nil
+}
+
+// bindRecording keeps the run's two bound keys: one that raises `call-unanswered` when `warranted` has not answered within
+// five minutes, one that says an unrecorded run an hour before its key's 48 hours end (§13, §16).
+func (g *Gate) bindRecording(module, id string) {
+	if g.d.Bounds == nil || g.d.Holding { // a process holder's bound keys are its waiting calls' alone (A-255)
+		return
+	}
+	for key, ttl := range map[string]time.Duration{g.unansweredKey(id): UnansweredAfter, g.unrecordedKey(id): KeptFor - SaidBefore} {
+		if err := g.d.Bounds.CreateTTL(key, map[string]string{"asker": module, "ask": id}, ttl); err != nil {
+			g.d.Logf("[approval] the bound %s of the run of ask %s is not kept: %v", key, id, err)
+		}
+	}
+}
+
+// recordRun calls `mesh-hand-acts.warranted` for one acted ask, each try a kept call open while the ask lacks `recorded`
+// (§16, A-157), and on its answer writes `recorded` and clears what waited on it. One recording per ask at a time.
+func (g *Gate) recordRun(module, id string) {
+	if !g.recording(id, true) {
+		return
+	}
+	defer g.recording(id, false)
+	if g.d.Warranted == nil {
+		g.d.Logf("[approval] the run of ask %s is not recorded: the tool runner reaches no hand-act log", id)
+		return
+	}
+	err := g.d.Warranted(module, id, func() (bool, error) { return g.unrecorded(id) })
+	g.judged(id) // made again: its answer, or the bound of its key, judges it from now
+	if err != nil {
+		g.d.Logf("[approval] mesh-hand-acts.warranted has not answered for ask %s (%v): asked again when the hand-act seat's "+
+			"holder is heard again and at the next start", id, err)
+		return
+	}
+	if err := g.markRecorded(id); err != nil {
+		g.d.Logf("[approval] ask %s is recorded in the hand-act log and its mark recorded is not kept: %v", id, err)
+		return
+	}
+	if g.d.Bounds != nil {
+		_ = g.d.Bounds.Delete(g.unansweredKey(id))
+		_ = g.d.Bounds.Delete(g.unrecordedKey(id))
+	}
+	g.finding(id, KindCallUnanswered, false, "mesh-hand-acts.warranted answered for ask "+id, "")
+}
+
+// recording claims or releases an ask's recording: false when one runs already.
+func (g *Gate) recording(id string, start bool) bool {
+	g.mu.Lock()
+	defer g.mu.Unlock()
+	if g.inFlight == nil {
+		g.inFlight = map[string]bool{}
+	}
+	if start {
+		if g.inFlight[id] {
+			return false
+		}
+		g.inFlight[id] = true
+		return true
+	}
+	delete(g.inFlight, id)
+	return true
+}
+
+// kept is the ask the client keeps under its id, with its revision; nil when there is none.
+func (g *Gate) kept(id string) (*kept, uint64, error) {
+	e, err := g.d.State.Get(g.askKey(id))
+	if err != nil || e == nil {
+		return nil, 0, err
+	}
+	var k kept
+	if err := json.Unmarshal(e.Value, &k); err != nil {
+		return nil, 0, err
+	}
+	return &k, e.Revision, nil
+}
+
+// unrecorded says the ask is acted on and its run not yet recorded: the key that keeps `warranted` open (§16).
+func (g *Gate) unrecorded(id string) (bool, error) {
+	k, _, err := g.kept(id)
+	if err != nil || k == nil {
+		return false, err
+	}
+	return k.Acted && !k.Recorded, nil
+}
+
+// markRecorded writes `recorded` on the kept ask by compare-and-set, again when another write came first.
+func (g *Gate) markRecorded(id string) error {
+	for {
+		k, rev, err := g.kept(id)
+		if err != nil || k == nil {
+			return fmt.Errorf("the kept ask cannot be read: %v", err)
+		}
+		if k.Recorded {
+			return nil
+		}
+		k.Recorded = true
+		if _, err := g.d.State.Update(g.askKey(id), k, rev); err == nil {
+			return nil
+		} else if !isChanged(err) {
+			return err
+		}
+	}
+}
+
+// Recover calls `warranted` again for every acted, unrecorded ask this machine's keys hold within their 48 hours (§16): at
+// each start, and when the hand-act seat's holder is heard again (A-157).
+func (g *Gate) Recover() {
+	if g.d.State == nil {
+		return
+	}
+	keys, err := g.d.State.Keys()
+	if err != nil {
+		g.d.Logf("[approval] the acted, unrecorded asks cannot be read (%v): read again at the next start or holder heard", err)
+		return
+	}
+	prefix := g.prefix() + "ask."
+	for _, key := range keys {
+		if !strings.HasPrefix(key, prefix) {
+			continue
+		}
+		id := strings.TrimPrefix(key, prefix)
+		k, _, err := g.kept(id)
+		if err != nil || k == nil || !k.Acted || k.Recorded || g.d.Now().Sub(k.Asked) > KeptFor {
+			continue
+		}
+		module := moduleOf(k)
+		g.pend(id)
+		g.d.Go(func() { g.recordRun(module, id) })
+	}
+}
+
+// moduleOf is the module an ask was asked under: the warrant's asker.
+func moduleOf(k *kept) string {
+	var w struct {
+		Asker string `json:"asker"`
+	}
+	if k.Answer != nil {
+		_ = json.Unmarshal(*k.Answer, &w)
+	}
+	return w.Asker
+}
+
+// WatchBounds hears the run's bound keys expire (A-157): `call-unanswered` raised when `warranted` has not answered within
+// five minutes; an unrecorded run said in the log an hour before its key's 48 hours end (§13).
+func (g *Gate) WatchBounds() (func(), error) {
+	if g.d.Bounds == nil {
+		return func() {}, nil
+	}
+	return g.d.Bounds.Watch(g.d.Node+".**", func(key string) {
+		if key == g.unreadableKey() {
+			g.unreadableExpired()
+			return
+		}
+		rest := strings.TrimPrefix(key, g.d.Node+".")
+		kind, id, _ := strings.Cut(rest, ".")
+		if open, err := g.unrecorded(id); err != nil || !open {
+			return
+		}
+		switch kind {
+		case "unanswered":
+			g.finding(id, KindCallUnanswered, true, fmt.Sprintf("mesh-hand-acts.warranted has not answered for ask %s, run on the "+
+				"operator's approval on %s, within %s: the run is not yet in the hand-act log", id, g.d.Node, UnansweredAfter),
+				"a run's hand-act is unrecorded on "+g.d.Node)
+		case "unrecorded":
+			g.d.Logf("[approval] ERROR the run of ask %s on %s is still unrecorded an hour before its key's 48 hours end", id, g.d.Node)
+		}
+	})
+}
+
+// Pender is the held writer's pending (views.HeldWriter's Pend and Judged), by a finding's kind and id: the findings it
+// cannot judge yet since its start, named in its `findings-stated` (design 47 G §384).
+type Pender interface {
+	Pend(kind, id string, since time.Time, bound time.Duration)
+	Judged(kind, id string)
+}
+
+// pend names an acted, unrecorded ask's `call-unanswered` in the runner's `findings-stated` until its `warranted` is made
+// again (§16; design 47 G §384), its bound the five minutes the finding waits.
+func (g *Gate) pend(id string) {
+	if p, ok := g.d.Findings.(Pender); ok {
+		p.Pend(KindCallUnanswered, g.findingID(id), g.d.Now().UTC(), UnansweredAfter)
+	}
+}
+
+// judged ends that pending.
+func (g *Gate) judged(id string) {
+	if p, ok := g.d.Findings.(Pender); ok {
+		p.Judged(KindCallUnanswered, g.findingID(id))
+	}
+}
+
+// findingID is the id of a finding about what on this machine, `<node>.<what>` escaped as a key's name is (lead answer
+// A-154).
+func (g *Gate) findingID(what string) string { return keys.EscapeName(g.d.Node + "." + what) }
+
+// isChanged says a compare-and-set lost to another write.
+func isChanged(err error) bool { return errors.Is(err, stdio.ErrChanged) }

go/approval/run.go

@@ -0,0 +1,176 @@
+package approval
+
+import (
+	"encoding/json"
+	"fmt"
+	"strings"
+
+	"git.novox.be/novox/mesh-sdk/go/operatorask"
+)
+
+// Run is a call through the gate (§20): an unmarked call runs; a marked one runs only on the operator's approval of that
+// one call, judged on the router's record and claimed once (§14, §15), and is otherwise answered as an error saying why
+// (§12, §17, §19). run is called at most once.
+func (g *Gate) Run(c Call, run func() (any, error)) (any, error) {
+	m, err := g.marksOf(c)
+	if err != nil {
+		return nil, err
+	}
+	if missing := g.unservedOf(c.Module); len(missing) > 0 {
+		return nil, fmt.Errorf("Not run: %s's marks name %s, which its bundle on %s does not register, so none of its tools is "+
+			"served here (design 46 7-approval-mark §4)", c.Module, strings.Join(missing, ", "), g.d.Node)
+	}
+	marked, _ := m.Marked(c.Seat, c.Name)
+	since := g.markedSince(c, marked, m.Revision)
+	if !marked {
+		return run()
+	}
+	if c.Own {
+		return nil, g.refused(c, "", "it is one of the tool runner's own tools, which no ask covers")
+	}
+	if m.Unread != "" {
+		return nil, g.refused(c, "", m.Unread)
+	}
+	if b, ok := g.d.State.(Binding); g.d.State == nil || ok && !b.Bound() {
+		return nil, g.refused(c, "", "the tool runner's membership binds no state "+StateName+" to keep its asks in")
+	}
+	if why := refusedUnasked(c.Args); why != "" {
+		return nil, g.refused(c, "", why)
+	}
+	if why := g.held(); why != "" {
+		return nil, g.refused(c, "", why)
+	}
+	act, err := ActOf(c, g.d.Node)
+	if err != nil {
+		return nil, g.refused(c, "", err.Error())
+	}
+	digest, err := operatorask.ActDigest(act)
+	if err != nil {
+		return nil, g.refused(c, "", err.Error())
+	}
+	named, err := g.d.State.Get(g.actKey(digest))
+	if err != nil {
+		g.stateFailed(err)
+		return nil, g.refused(c, digest, "its state "+StateName+" cannot be read: "+err.Error())
+	}
+	g.stateRead()
+	if named == nil {
+		return nil, g.raise(c, act, digest, since)
+	}
+	var id string
+	if err := json.Unmarshal(named.Value, &id); err != nil || id == "" {
+		return nil, g.refused(c, digest, fmt.Sprintf("its act's key in %s names no ask", StateName))
+	}
+	return g.judge(c, act, digest, id, since, run)
+}
+
+// Binding is a Store that says whether the runner's membership binds the state now (§13).
+type Binding interface{ Bound() bool }
+
+// marksOf is the module's marks as the catalog half has them now; before its first view, the call waits for it within
+// RecordWithin and is then judged, refused naming mesh_first_views when it is still unread (§19).
+func (g *Gate) marksOf(c Call) (Marks, error) {
+	if g.d.Catalog == nil {
+		return Marks{}, g.refused(c, "", "the tool runner reads no catalog half, so its marks are not read")
+	}
+	if err := g.d.Catalog.Ready(); err != nil {
+		if g.d.Wait != nil {
+			err = g.d.Wait(RecordWithin)
+		}
+		if err != nil {
+			return Marks{}, fmt.Errorf("Not run: the marks of %s are not read yet (%v); mesh_first_views says what the tool runner "+
+				"waits for", c.Module, err)
+		}
+	}
+	m := Derive(g.d.Catalog, c.Module, c.Fingerprint)
+	g.checkServed(m)
+	return m, nil
+}
+
+func (g *Gate) unservedOf(module string) []string {
+	g.mu.Lock()
+	defer g.mu.Unlock()
+	return g.unserved[module]
+}
+
+// markedSince is the revision a call was marked at when the same caller last called it unmarked (§12), empty otherwise.
+func (g *Gate) markedSince(c Call, marked bool, revision string) string {
+	key := c.Caller + " " + c.Address
+	g.mu.Lock()
+	defer g.mu.Unlock()
+	if g.unmarkedAt == nil {
+		g.unmarkedAt = map[string]bool{}
+	}
+	was := g.unmarkedAt[key]
+	if marked {
+		delete(g.unmarkedAt, key)
+		if was {
+			return revision
+		}
+		return ""
+	}
+	g.unmarkedAt[key] = true
+	return ""
+}
+
+// judge is the same call made again, judged on the router's own record of its act's newest ask (§14 to §17).
+func (g *Gate) judge(c Call, act operatorask.Act, digest, id, since string, run func() (any, error)) (any, error) {
+	rec, err := g.record(c.Module, id)
+	if err != nil {
+		return nil, g.refused(c, digest, "the router's record of its ask "+id+" cannot be read: "+err.Error())
+	}
+	if rec == nil {
+		return nil, g.firstAnswer(c, id, digest, since) // §17: not yet taken by the router
+	}
+	again := func(why string) (any, error) {
+		err := g.raise(c, act, digest, since)
+		return nil, fmt.Errorf("The ask %s %s; asked again. %w", id, why, err)
+	}
+	switch rec.State {
+	case "open", "held-back":
+		return nil, fmt.Errorf("Not run: still waiting for the operator's answer to ask %s (fingerprint %s); it expires at %s",
+			id, Fingerprint(digest), rec.Expires)
+	case "refused":
+		return nil, g.refused(c, digest, "the router refused its ask "+id+": "+orNone(rec.Answer))
+	case "chosen":
+	default: // expired, cancelled, replaced: each asks again (§15, §17)
+		return again("ended " + rec.State)
+	}
+	w := rec.Warrant
+	if w == nil {
+		return nil, g.refused(c, digest, "the router's record of its ask "+id+" is chosen and carries no warrant")
+	}
+	at, _ := parseTime(w.At)
+	if w.Option == OptionDecline {
+		if until := at.Add(DeclinedFor); g.d.Now().Before(until) {
+			return nil, fmt.Errorf("Not run: the operator declined ask %s; the same call is not asked again until %s",
+				id, formatTime(until))
+		}
+		return again("was declined more than 10 minutes ago")
+	}
+	if g.d.Now().After(at.Add(RunWithin)) {
+		return again("was approved too long ago (more than 30 minutes)")
+	}
+	var answer any
+	var ran error
+	h, err := g.d.Channel.Claim(c.Module, *w, act, func() { answer, ran = run() })
+	switch {
+	case h == ClaimDone:
+		return again("was already run")
+	case h == ClaimRefused:
+		return nil, g.refused(c, digest, "its warrant does not hold: "+errText(err))
+	case h == "" && err != nil:
+		g.stateFailed(err)
+		return nil, g.refused(c, digest, "its state "+StateName+" cannot be written: "+err.Error())
+	case err != nil: // the act about to run is not the one the option bound: nothing runs, the warrant stays used
+		return nil, g.refused(c, digest, err.Error())
+	}
+	return g.ran(c, id, rec, answer, ran)
+}
+
+func errText(err error) string {
+	if err == nil {
+		return "no reason given"
+	}
+	return err.Error()
+}

go/approval/tools.go

@@ -0,0 +1,172 @@
+package approval
+
+import (
+	"encoding/json"
+	"fmt"
+	"sort"
+	"strings"
+	"time"
+)
+
+// The mesh MCP server's mesh_approvals reads and steers what the gate asked on this machine (§18).
+
+// Listed is one ask of the last day as mesh_approvals lists it: its state and its act's fingerprint.
+type Listed struct {
+	Ask         string    `json:"ask"`
+	Address     string    `json:"address"`
+	Module      string    `json:"module"`
+	Asked       time.Time `json:"asked"`
+	State       string    `json:"state"`
+	Fingerprint string    `json:"fingerprint"`
+}
+
+// Whole is one ask read whole: its arguments and the act's digest.
+type Whole struct {
+	Listed
+	Digest    string            `json:"digest"`
+	Act       map[string]string `json:"act"`
+	Arguments json.RawMessage   `json:"arguments"`
+	Recorded  bool              `json:"recorded"`
+}
+
+// stateOf is a kept ask's state as the runner knows it.
+func stateOf(acted, recorded bool, ended string) string {
+	switch {
+	case acted && recorded:
+		return "run, recorded"
+	case acted:
+		return "run, not yet recorded"
+	case ended != "":
+		return ended
+	}
+	return "asked"
+}
+
+// List is the calls asked on this machine in the last day, newest first (§18).
+func (g *Gate) List() ([]Listed, error) {
+	if g.d.State == nil {
+		return nil, fmt.Errorf("the tool runner's membership binds no state %s", StateName)
+	}
+	keys, err := g.d.State.Keys()
+	if err != nil {
+		return nil, err
+	}
+	prefix := g.d.Node + ".ask."
+	out := []Listed{}
+	for _, key := range keys {
+		if !strings.HasPrefix(key, prefix) {
+			continue
+		}
+		w, err := g.Read(strings.TrimPrefix(key, prefix))
+		if err != nil || g.d.Now().Sub(w.Asked) > 24*time.Hour {
+			continue
+		}
+		out = append(out, w.Listed)
+	}
+	sort.Slice(out, func(i, j int) bool { return out[i].Asked.After(out[j].Asked) })
+	return out, nil
+}
+
+// Read is one ask whole: its arguments and the act's digest (§18).
+func (g *Gate) Read(id string) (Whole, error) {
+	if g.d.State == nil {
+		return Whole{}, fmt.Errorf("the tool runner's membership binds no state %s", StateName)
+	}
+	k, _, err := g.kept(id)
+	if err != nil {
+		return Whole{}, err
+	}
+	if k == nil {
+		return Whole{}, fmt.Errorf("no ask %s is kept on %s", id, g.d.Node)
+	}
+	module := k.Act["module"]
+	if module == "" {
+		module = moduleOf(k)
+	}
+	var ask struct {
+		About string `json:"about"`
+	}
+	_ = json.Unmarshal(k.Ask, &ask)
+	return Whole{Listed: Listed{Ask: id, Address: k.Act["address"], Module: module, Asked: k.Asked,
+		State: stateOf(k.Acted, k.Recorded, k.Ended), Fingerprint: Fingerprint(ask.About)},
+		Digest: ask.About, Act: k.Act, Arguments: k.Arguments, Recorded: k.Recorded}, nil
+}
+
+// Applied are the marks the gate applies on this machine, each module's marked tools and verbs with their source and the
+// catalog revision read (§18).
+func (g *Gate) Applied() []Marks {
+	g.mu.Lock()
+	modules := make([]string, 0, len(g.served))
+	for m := range g.served {
+		modules = append(modules, m)
+	}
+	g.mu.Unlock()
+	sort.Strings(modules)
+	var out []Marks
+	if g.d.Catalog == nil {
+		return out
+	}
+	for _, m := range modules {
+		if marks := Derive(g.d.Catalog, m, g.servedFingerprint(m)); marks.Any() {
+			out = append(out, marks)
+		}
+	}
+	return out
+}
+
+func (g *Gate) servedFingerprint(module string) string {
+	g.mu.Lock()
+	defer g.mu.Unlock()
+	return g.served[module]
+}
+
+// Describe says whether a tool or a seat verb of a module is marked, and its source, for mesh_describe (§18): the served
+// build's marks where this machine serves the module, else the newest entry's and its seat's.
+func (g *Gate) Describe(module, seat, name string) (bool, string) {
+	if g.d.Catalog == nil || g.d.Catalog.Ready() != nil {
+		return false, ""
+	}
+	if seat != "" && module == "" {
+		for s, d := range g.d.Catalog.Definitions() {
+			if s != seat {
+				continue
+			}
+			for _, v := range d.Verbs {
+				if v.Name == name && v.NeedsApproval {
+					return true, "seat " + seat
+				}
+			}
+		}
+		return false, ""
+	}
+	return Derive(g.d.Catalog, module, g.servedFingerprint(module)).Marked(seat, name)
+}
+
+// Again asks `warranted` again for one acted, unrecorded ask, by hand, in the kept-call form of §16 (§18); the caller
+// records the hand act first.
+func (g *Gate) Again(id string) error {
+	w, err := g.Read(id)
+	if err != nil {
+		return err
+	}
+	if !strings.HasPrefix(w.State, "run, not yet") {
+		return fmt.Errorf("the ask %s is %s: only a run not yet recorded is asked again", id, w.State)
+	}
+	g.recordRun(w.Module, id)
+	if again, _ := g.Read(id); !again.Recorded {
+		return fmt.Errorf("mesh-hand-acts.warranted has not answered for ask %s yet", id)
+	}
+	return nil
+}
+
+// Cancel takes an open ask back through operator-channel's client (§18); the caller records the hand act first.
+func (g *Gate) Cancel(id string) error {
+	w, err := g.Read(id)
+	if err != nil {
+		return err
+	}
+	if w.State != "asked" {
+		return fmt.Errorf("the ask %s is %s, not open", id, w.State)
+	}
+	return g.d.Channel.Cancel(w.Module, id)
+}

go/approval/wait.go

@@ -0,0 +1,290 @@
+package approval
+
+import (
+	"context"
+	"encoding/json"
+	"fmt"
+	"strings"
+	"time"
+
+	"git.novox.be/novox/mesh-sdk/go/buscompose"
+	"git.novox.be/novox/mesh-sdk/go/operatorask"
+	"git.novox.be/novox/mesh-sdk/go/outward"
+)
+
+// Wait is one mesh_wait call as the gate judges it (design 34 every-event §34 to §36): the event names given, the subjects
+// they became (after `from`), the filter and the timeout.
+type Wait struct {
+	Names    []string
+	From     string
+	Subjects []string
+	Filter   map[string]any
+	Timeout  time.Duration
+}
+
+// Waited is a wait through the gate (every-event §34 to §36). An unmarked wait is heard at once by hear, given how long it
+// may wait. A marked one is heard only on the operator's warrant for that one wait, its timeout running from then; with
+// none it subscribes to nothing, its ask raised once under the runner's own module's name, and is answered as an error at
+// its timeout, when its caller goes, or as soon as the router's record says the ask was chosen, never in a hot loop. c is
+// the call as the console makes it: its address, its tool's name, its caller and its arguments as given.
+func (g *Gate) Waited(ctx context.Context, c Call, w Wait, hear func(within time.Duration) (any, error)) (any, error) {
+	deadline := g.d.Now().Add(w.Timeout)
+	// A wait from a seat is never marked, and a seat's event never is (§32, §34).
+	if w.From == "seat" || !outsideSeats(w.Subjects) {
+		return hear(w.Timeout)
+	}
+	if g.d.Catalog == nil {
+		return nil, g.holdRefused(ctx, deadline, "this wait is refused: the tool runner reads no catalog half, so the marks are not read")
+	}
+	if err := g.d.Catalog.Ready(); err != nil {
+		// Before the marks are read nothing is asked: the wait waits for the first view within its own timeout and is
+		// then judged, and is refused at its timeout when it does not come (§34).
+		if g.d.Wait != nil {
+			err = g.waitCatalog(ctx, w.Timeout)
+		}
+		if err != nil {
+			return nil, g.holdRefused(ctx, deadline, fmt.Sprintf("this wait is refused at its timeout: the marks are not yet read (%v); "+
+				"mesh_first_views says what the tool runner waits for", err))
+		}
+	}
+	if !overlapsAny(w.Subjects, g.waitMarks()) {
+		return hear(deadline.Sub(g.d.Now()))
+	}
+	c.Module, c.Seat, c.Fingerprint = g.d.Runner, "", g.d.Build
+	if c.Fingerprint == "" {
+		return nil, g.holdRefused(ctx, deadline, "this wait needs the operator's approval, and the tool runner's own fingerprint is "+
+			"unknown (its MESH_FINGERPRINT was not set at its start), so no warrant can bind its build")
+	}
+	if b, ok := g.d.State.(Binding); g.d.State == nil || ok && !b.Bound() {
+		return nil, g.holdRefused(ctx, deadline, g.refused(c, "", "the tool runner's membership binds no state "+StateName+" to keep its asks in").Error())
+	}
+	if why := refusedUnasked(c.Args); why != "" {
+		return nil, g.holdRefused(ctx, deadline, g.refused(c, "", why).Error())
+	}
+	if why := g.held(); why != "" {
+		return nil, g.holdRefused(ctx, deadline, g.refused(c, "", why).Error())
+	}
+	act, err := ActOf(c, g.d.Node)
+	if err != nil {
+		return nil, g.holdRefused(ctx, deadline, g.refused(c, "", err.Error()).Error())
+	}
+	digest, err := operatorask.ActDigest(act)
+	if err != nil {
+		return nil, g.holdRefused(ctx, deadline, g.refused(c, "", err.Error()).Error())
+	}
+	named, err := g.d.State.Get(g.actKey(digest))
+	if err != nil {
+		g.stateFailed(err)
+		return nil, g.holdRefused(ctx, deadline, g.refused(c, digest, "its state "+StateName+" cannot be read: "+err.Error()).Error())
+	}
+	g.stateRead()
+	anew := func() (any, error) {
+		id := newID()
+		if err := g.keepAsk(c, act, digest, g.askForWait(c, w, digest, id)); err != nil {
+			return nil, g.holdRefused(ctx, deadline, err.Error())
+		}
+		return nil, g.holdAsk(ctx, deadline, c.Module, id, digest, true)
+	}
+	if named == nil {
+		return anew()
+	}
+	var id string
+	if err := json.Unmarshal(named.Value, &id); err != nil || id == "" {
+		return nil, g.holdRefused(ctx, deadline, g.refused(c, digest, fmt.Sprintf("its act's key in %s names no ask", StateName)).Error())
+	}
+	rec, err := g.record(c.Module, id)
+	switch {
+	case err != nil:
+		return nil, g.holdRefused(ctx, deadline, g.refused(c, digest, "the router's record of its ask "+id+" cannot be read: "+err.Error()).Error())
+	case rec == nil, rec.State == "open", rec.State == "held-back":
+		return nil, g.holdAsk(ctx, deadline, c.Module, id, digest, false)
+	case rec.State == "refused":
+		return nil, g.holdRefused(ctx, deadline, g.refused(c, digest, "the router refused its ask "+id+": "+orNone(rec.Answer)).Error())
+	case rec.State != "chosen":
+		return anew() // expired, cancelled, replaced: asked again (§15, §17)
+	}
+	wt := rec.Warrant
+	if wt == nil {
+		return nil, g.holdRefused(ctx, deadline, g.refused(c, digest, "the router's record of its ask "+id+" is chosen and carries no warrant").Error())
+	}
+	at, _ := parseTime(wt.At)
+	if wt.Option == OptionDecline {
+		if g.d.Now().Before(at.Add(DeclinedFor)) {
+			return nil, g.holdRefused(ctx, deadline, declinedWords(id, at))
+		}
+		return anew()
+	}
+	if g.d.Now().After(at.Add(RunWithin)) {
+		return anew()
+	}
+	var answer any
+	var ran error
+	// On the warrant it subscribes, and the wait's timeout runs from then (§35).
+	h, err := g.d.Channel.Claim(c.Module, *wt, act, func() { answer, ran = hear(w.Timeout) })
+	switch {
+	case h == ClaimDone:
+		return anew() // already run: one warrant is one wait (§35)
+	case h == ClaimRefused:
+		return nil, g.holdRefused(ctx, deadline, g.refused(c, digest, "its warrant does not hold: "+errText(err)).Error())
+	case h == "" && err != nil:
+		g.stateFailed(err)
+		return nil, g.holdRefused(ctx, deadline, g.refused(c, digest, "its state "+StateName+" cannot be written: "+err.Error()).Error())
+	case err != nil:
+		return nil, g.holdRefused(ctx, deadline, g.refused(c, digest, err.Error()).Error())
+	}
+	return g.ran(c, id, rec, answer, ran)
+}
+
+// outsideSeats says a subject is not a seat's: only such a subject can be marked (§32, §34).
+func outsideSeats(subjects []string) bool {
+	for _, s := range subjects {
+		if !strings.HasPrefix(s, "mesh.seat.") {
+			return true
+		}
+	}
+	return false
+}
+
+// waitMarks are the marked subjects of every module the catalog half lists (§33): the newest entry of every followed
+// branch, and the served entry of each module this runner serves (lead answer A-168), so a mark is never lost.
+func (g *Gate) waitMarks() map[string]string {
+	m := Marks{Tools: map[string]string{}, Verbs: map[string]string{}, Subjects: map[string]string{}}
+	defs := g.d.Catalog.Definitions()
+	for _, e := range g.d.Catalog.Entries() {
+		m.add(e, defs)
+	}
+	g.mu.Lock()
+	served := make(map[string]string, len(g.served))
+	for module, fp := range g.served {
+		served[module] = fp
+	}
+	g.mu.Unlock()
+	for _, fp := range served {
+		if e, ok, _ := g.d.Catalog.Served(fp); ok {
+			m.add(e, defs)
+		}
+	}
+	return m.Subjects
+}
+
+// overlapsAny says a subject a wait subscribes overlaps a marked subject (§34).
+func overlapsAny(subjects []string, marked map[string]string) bool {
+	for _, s := range subjects {
+		for mk := range marked {
+			if buscompose.Overlaps(s, mk) {
+				return true
+			}
+		}
+	}
+	return false
+}
+
+// waitCatalog waits for the catalog half's first view within the bound, or until the caller goes.
+func (g *Gate) waitCatalog(ctx context.Context, within time.Duration) error {
+	done := make(chan error, 1)
+	go func() { done <- g.d.Wait(within) }()
+	select {
+	case err := <-done:
+		return err
+	case <-ctx.Done():
+		return ctx.Err()
+	}
+}
+
+// pause waits until the deadline or the caller's going.
+func (g *Gate) pause(ctx context.Context, deadline time.Time) {
+	if left := deadline.Sub(g.d.Now()); left > 0 {
+		select {
+		case <-g.d.After(left):
+		case <-ctx.Done():
+		}
+	}
+}
+
+// holdRefused is a refused marked wait, said at its timeout or when its caller goes, never at once, so a watcher's loop
+// is never a hot one (§36).
+func (g *Gate) holdRefused(ctx context.Context, deadline time.Time, words string) error {
+	g.pause(ctx, deadline)
+	if !strings.HasPrefix(words, "Not run") {
+		words = "Not run: " + words
+	}
+	return fmt.Errorf("%s", words)
+}
+
+// holdAsk holds a marked wait whose ask is open, subscribing to nothing but its ask's `decided` (§36): it answers, as an
+// error, at its timeout, when its caller goes, or once the router's record says the ask was chosen, the event only waking it.
+func (g *Gate) holdAsk(ctx context.Context, deadline time.Time, module, id, digest string, first bool) error {
+	for {
+		left := deadline.Sub(g.d.Now())
+		heard := false
+		if left > 0 && ctx.Err() == nil {
+			var err error
+			if g.d.Hear != nil {
+				heard, err = g.d.Hear(ctx, []string{g.d.Channel.Decided(module)}, left, func(body json.RawMessage) bool {
+					var w struct {
+						Ask string `json:"ask"`
+					}
+					return json.Unmarshal(body, &w) == nil && w.Ask == id
+				})
+			}
+			if g.d.Hear == nil || err != nil {
+				g.pause(ctx, deadline)
+			}
+		}
+		rec, _ := g.record(module, id)
+		if heard && (rec == nil || rec.State != "chosen") {
+			continue // the event only wakes it: the record says nothing chosen yet
+		}
+		return g.waitWords(rec, id, digest, first)
+	}
+}
+
+// waitWords are §12's and §17's words for a marked wait not run, "this wait" for "the call" (§36).
+func (g *Gate) waitWords(rec *Record, id, digest string, first bool) error {
+	switch {
+	case rec == nil:
+		return fmt.Errorf("Not run, asked; not yet taken by the router (ask %s, fingerprint %s); make this wait again later", id, Fingerprint(digest))
+	case rec.State == "chosen" && rec.Warrant != nil && rec.Warrant.Option == OptionDecline:
+		at, _ := parseTime(rec.Warrant.At)
+		return fmt.Errorf("%s", declinedWords(id, at))
+	case rec.State == "chosen", first:
+		return fmt.Errorf("Not run: this wait needs the operator's approval. Asked on %s at %s (ask %s, fingerprint %s); make this wait "+
+			"again within 30 minutes of the approval; the ask expires at %s", orNone(strings.Join(rec.OfferedOn, ", ")), rec.Opened,
+			id, Fingerprint(digest), rec.Expires)
+	case rec.State == "open", rec.State == "held-back":
+		return fmt.Errorf("Not run: still waiting for the operator's answer to ask %s (fingerprint %s); it expires at %s",
+			id, Fingerprint(digest), rec.Expires)
+	}
+	return fmt.Errorf("Not run: the ask %s ended %s; make this wait again to ask anew", id, rec.State)
+}
+
+func declinedWords(id string, at time.Time) string {
+	return fmt.Sprintf("Not run: the operator declined ask %s; this wait is not asked again until %s", id,
+		formatTime(at.Add(DeclinedFor)))
+}
+
+// askForWait is a marked wait's ask (§35): "Wait on <names> on <node>?", shortened as §10 says, and an explanation naming
+// every event name one per line, the filter, and the bound as the timeout in minutes, then the act's fingerprint.
+func (g *Gate) askForWait(c Call, w Wait, digest, id string) Ask {
+	a := g.askFor(c, digest, id)
+	filter, whole := "none", true
+	if len(w.Filter) > 0 {
+		raw, _ := json.Marshal(w.Filter)
+		filter = string(raw)
+		if r, ok := outward.Check(filter); !ok {
+			filter, whole = shapeOf(r), false
+		}
+	}
+	a.Headline = headlineOf("Wait on", strings.Join(w.Names, ", "), g.d.Node, whole)
+	lines := append([]string{"Wait on " + g.d.Node + ", called through the mesh's tools, which cannot tell who called, for:"}, w.Names...)
+	lines = append(lines, "Filter: "+filter, fmt.Sprintf("Timeout: %s minutes", minutes(w.Timeout)), "Fingerprint "+Fingerprint(digest))
+	a.Explanation = strings.Join(lines, "\n")
+	a.Options[0].Does = "the same wait, made again within 30 minutes, subscribes once, its timeout running from then"
+	a.Options[1].Does = "nothing is heard; the same wait is not asked again for 10 minutes"
+	return a
+}
+
+// minutes is a timeout in minutes, as few digits as say it.
+func minutes(d time.Duration) string {
+	return strings.TrimSuffix(strings.TrimRight(fmt.Sprintf("%.2f", d.Minutes()), "0"), ".")
+}

go/asker/asker.go

@@ -1,196 +0,0 @@
-// Package asker is a module's client for asking a person (novox/hq ADR 0259 §10): it publishes an ask under
-// the module's own name, cancels it, reads its state from the router's record, and hands the module each
-// warrant once — only one for an ask it made, for an option it offered, at that option's level, before it
-// expired. The module then acts with its own grants.
-//
-// It keeps what it asked, and which warrants it acted on, in a state of the module's own (declared in its
-// manifest, by default `asked`): the ask is written before it is published, and a warrant is marked acted on
-// by compare-and-set before the module's handler runs, so a redelivery, or a second instance, acts once.
-package asker
-
-import (
-	"encoding/json"
-	"errors"
-	"fmt"
-	"os"
-	"strings"
-	"time"
-
-	stdio "git.novox.be/novox/mesh-sdk/go"
-	"git.novox.be/novox/mesh-sdk/go/asks"
-)
-
-// Client asks as one module.
-type Client struct {
-	// Module is the asking module's name: the one the bus grants its asks under.
-	Module string
-	// State is the module's own state the asks are kept in.
-	State Store
-	// Now is the clock; nil is time.Now.
-	Now func() time.Time
-	// Publish, Record and Subscribe reach the bus; nil is the stdio SDK's, through the module's runtime.
-	Publish   func(subject string, body any, id string) error
-	Record    func(key string) (*stdio.StateEntry, error)
-	Subscribe func(pattern string, handle func(stdio.Envelope) error) error
-}
-
-// Store is where the asks are kept: stdio.State(name) is one.
-type Store interface {
-	Get(key string) (*stdio.StateEntry, error)
-	Create(key string, value any) (uint64, error)
-	Update(key string, value any, revision uint64) (uint64, error)
-}
-
-// New is a client for the module the runtime serves, keeping its asks in the state named.
-func New(state string) *Client {
-	return &Client{Module: os.Getenv("MESH_MODULE"), State: stdio.State(state)}
-}
-
-func (c *Client) now() time.Time {
-	if c.Now != nil {
-		return c.Now()
-	}
-	return time.Now()
-}
-
-// Kept is one ask as the module keeps it.
-type Kept struct {
-	Ask    asks.Ask      `json:"ask"`
-	Asked  time.Time     `json:"asked"`
-	Acted  bool          `json:"acted,omitempty"`
-	Ended  asks.Outcome  `json:"ended,omitempty"`
-	Answer *asks.Warrant `json:"answer,omitempty"`
-}
-
-func key(id string) string { return "ask." + id }
-
-// Ask checks an ask, keeps it, and publishes it under the module's own name. An ask with an id already kept
-// is refused: a new question is a new id.
-func (c *Client) Ask(a asks.Ask) error {
-	if err := a.Check(c.now()); err != nil {
-		return err
-	}
-	if _, err := c.State.Create(key(a.ID), Kept{Ask: a, Asked: c.now()}); err != nil {
-		if errors.Is(err, stdio.ErrChanged) {
-			return fmt.Errorf("an ask %s was already made: a new question is a new id", a.ID)
-		}
-		return err
-	}
-	return c.publish(asks.AskSubject(c.Module), a, a.ID)
-}
-
-// Cancel takes an ask back: the router ends it and edits every copy.
-func (c *Client) Cancel(id string) error {
-	return c.publish(asks.CancelSubject(c.Module), map[string]string{"id": id}, "cancel."+id)
-}
-
-func (c *Client) publish(subject string, body any, id string) error {
-	if c.Publish != nil {
-		return c.Publish(subject, body, id)
-	}
-	return stdio.SeatPublish(subject, body, id)
-}
-
-// Where is an ask's state as the router keeps it: its state and its warrant, if any — read under the
-// module's own name and no other's.
-func (c *Client) Where(id string) (state string, w *asks.Warrant, err error) {
-	read := c.Record
-	if read == nil {
-		read = func(k string) (*stdio.StateEntry, error) { return stdio.SeatRecord("", k) }
-	}
-	e, err := read(id)
-	if err != nil || e == nil {
-		return "", nil, err
-	}
-	var rec struct {
-		State   string        `json:"state"`
-		Warrant *asks.Warrant `json:"warrant"`
-	}
-	if err := json.Unmarshal(e.Value, &rec); err != nil {
-		return "", nil, fmt.Errorf("the router's record of %s cannot be read: %w", id, err)
-	}
-	return rec.State, rec.Warrant, nil
-}
-
-// Handled is what came of a warrant: acted on, refused (and why), or already done.
-type Handled string
-
-const (
-	Acted    Handled = "acted"
-	Refused  Handled = "refused"
-	Done     Handled = "already acted on"
-	Recorded Handled = "ended without a choice"
-)
-
-// Take hands act a warrant once, after holding it to the ask it answers. act performs the option with the
-// module's own grants; its error is said and the warrant stays acted on (a person's decision is not
-// performed twice; the module says the failure in its own record).
-func (c *Client) Take(w asks.Warrant, act func(asks.Option, asks.Warrant) error) (Handled, error) {
-	if w.Asker != c.Module {
-		return Refused, fmt.Errorf("a warrant for %s reached %s", w.Asker, c.Module)
-	}
-	e, err := c.State.Get(key(w.Ask))
-	if err != nil {
-		return "", err
-	}
-	if e == nil {
-		return Refused, fmt.Errorf("%s holds no ask %s", c.Module, w.Ask)
-	}
-	var k Kept
-	if err := json.Unmarshal(e.Value, &k); err != nil {
-		return "", err
-	}
-	if k.Acted || k.Ended != "" {
-		return Done, nil
-	}
-	if w.Outcome != asks.OutcomeChosen {
-		k.Ended = w.Outcome
-		k.Answer = &w
-		if _, err := c.State.Update(key(w.Ask), k, e.Revision); err != nil && !errors.Is(err, stdio.ErrChanged) {
-			return "", err
-		}
-		return Recorded, nil
-	}
-	o, err := w.For(c.Module, k.Ask)
-	if err != nil {
-		return Refused, err
-	}
-	// Marked before acting: of two deliveries, or two instances, only the one whose write stands acts.
-	k.Acted, k.Ended, k.Answer = true, asks.OutcomeChosen, &w
-	if _, err := c.State.Update(key(w.Ask), k, e.Revision); err != nil {
-		if errors.Is(err, stdio.ErrChanged) {
-			return Done, nil
-		}
-		return "", err
-	}
-	return Acted, act(o, w)
-}
-
-// Listen hands every warrant for this module to Take, with act. It asks the runtime for the module's
-// events matching the router's `decided` subject for this module.
-func (c *Client) Listen(act func(asks.Option, asks.Warrant) error, said func(Handled, asks.Warrant, error)) error {
-	subscribe := c.Subscribe
-	if subscribe == nil {
-		subscribe = stdio.Subscribe
-	}
-	return subscribe(asks.Seat+".decided."+c.Module, func(e stdio.Envelope) error {
-		if !strings.HasPrefix(e.Key, asks.Seat+".decided.") {
-			return nil
-		}
-		var w asks.Warrant
-		if err := json.Unmarshal(e.Body, &w); err != nil {
-			if said != nil {
-				said(Refused, w, fmt.Errorf("a warrant could not be read: %w", err))
-			}
-			return nil
-		}
-		h, err := c.Take(w, act)
-		if h == "" && err != nil {
-			return err // the state could not be reached: offered again
-		}
-		if said != nil {
-			said(h, w, err)
-		}
-		return nil
-	})
-}

go/asker/asker_test.go

@@ -1,141 +0,0 @@
-package asker
-
-import (
-	"encoding/json"
-	"strings"
-	"testing"
-	"time"
-
-	stdio "git.novox.be/novox/mesh-sdk/go"
-	"git.novox.be/novox/mesh-sdk/go/asks"
-)
-
-type mem struct {
-	vals map[string]json.RawMessage
-	revs map[string]uint64
-	n    uint64
-}
-
-func (m *mem) Get(k string) (*stdio.StateEntry, error) {
-	v, ok := m.vals[k]
-	if !ok {
-		return nil, nil
-	}
-	return &stdio.StateEntry{Key: k, Value: v, Revision: m.revs[k]}, nil
-}
-func (m *mem) Create(k string, v any) (uint64, error) {
-	if _, ok := m.vals[k]; ok {
-		return 0, stdio.ErrChanged
-	}
-	return m.put(k, v)
-}
-func (m *mem) Update(k string, v any, rev uint64) (uint64, error) {
-	if rev == 0 || m.revs[k] != rev {
-		return 0, stdio.ErrChanged
-	}
-	return m.put(k, v)
-}
-func (m *mem) put(k string, v any) (uint64, error) {
-	raw, _ := json.Marshal(v)
-	m.n++
-	m.vals[k], m.revs[k] = raw, m.n
-	return m.n, nil
-}
-
-var now = time.Date(2026, 10, 8, 14, 0, 0, 0, time.UTC)
-
-func client() (*Client, map[string][]string) {
-	sent := map[string][]string{}
-	c := &Client{Module: "mesh-delivery", State: &mem{vals: map[string]json.RawMessage{}, revs: map[string]uint64{}},
-		Now: func() time.Time { return now },
-		Publish: func(subject string, body any, id string) error {
-			sent[subject] = append(sent[subject], id)
-			return nil
-		}}
-	return c, sent
-}
-
-// releaseHQ is the act the ask's one option binds.
-var releaseHQ = map[string]string{"verb": "release", "delivery": "hq"}
-
-func held() asks.Ask {
-	binds, _ := asks.ActDigest(releaseHQ)
-	return asks.Ask{ID: "d-1", Headline: "Delivery of hq held", Explanation: "Needs you: release it, or stop it.",
-		Who: asks.Operator, Expires: now.Add(time.Hour), OnExpiry: "the delivery stays held",
-		Options: []asks.Option{{ID: "release", Label: "Release", Does: "it goes on", Level: asks.Approve, Binds: binds}}}
-}
-
-func warrant() asks.Warrant {
-	return asks.Warrant{Ask: "d-1", Asker: "mesh-delivery", Outcome: asks.OutcomeChosen, Option: "release",
-		Label: "Release", Level: asks.Approve, At: now.Add(time.Minute), AskDigest: held().Digest(),
-		By: &asks.Person{Who: asks.Operator, Kind: "telegram", Identity: "42", Verified: "user id verified"}}
-}
-
-func TestAnAskIsKeptThenPublishedUnderTheModulesOwnName(t *testing.T) {
-	c, sent := client()
-	if err := c.Ask(held()); err != nil {
-		t.Fatal(err)
-	}
-	if got := sent[asks.AskSubject("mesh-delivery")]; len(got) != 1 || got[0] != "d-1" {
-		t.Fatalf("%v", sent)
-	}
-	if err := c.Ask(held()); err == nil || !strings.Contains(err.Error(), "already made") {
-		t.Errorf("the same id was asked twice: %v", err)
-	}
-	bad := held()
-	bad.Who = "agent"
-	if err := c.Ask(bad); err == nil {
-		t.Error("an ask the contract refuses was published")
-	}
-}
-
-func TestAWarrantIsActedOnOnceAndOnlyForItsOwnAsk(t *testing.T) {
-	c, _ := client()
-	_ = c.Ask(held())
-	acted := 0
-	act := func(o asks.Option, _ asks.Warrant) error {
-		if err := o.Performs(releaseHQ); err != nil {
-			t.Errorf("the bound act: %v", err)
-		}
-		acted++
-		return nil
-	}
-	if h, err := c.Take(warrant(), act); h != Acted || err != nil || acted != 1 {
-		t.Fatalf("%s %v %d", h, err, acted)
-	}
-	if h, _ := c.Take(warrant(), act); h != Done || acted != 1 {
-		t.Errorf("a redelivery was acted on: %s", h)
-	}
-	for why, change := range map[string]func(*asks.Warrant){
-		"another asker":         func(w *asks.Warrant) { w.Asker = "mesh-controller" },
-		"an ask not made":       func(w *asks.Warrant) { w.Ask = "d-9" },
-		"another level":         func(w *asks.Warrant) { w.Level = asks.Acknowledge },
-		"an option not offered": func(w *asks.Warrant) { w.Option = "delete" },
-		"after its expiry":      func(w *asks.Warrant) { w.At = now.Add(2 * time.Hour) },
-		"another ask's digest":  func(w *asks.Warrant) { w.AskDigest = "sha256:00" },
-	} {
-		c2, _ := client()
-		_ = c2.Ask(held())
-		w := warrant()
-		change(&w)
-		if h, _ := c2.Take(w, act); h == Acted {
-			t.Errorf("a warrant from %s was acted on", why)
-		}
-	}
-	if acted != 1 {
-		t.Errorf("acted %d times", acted)
-	}
-}
-
-func TestAnAskEndedWithoutAChoiceIsRecordedAndNothingDone(t *testing.T) {
-	c, _ := client()
-	_ = c.Ask(held())
-	w := warrant()
-	w.Outcome, w.Option, w.By = asks.OutcomeExpired, "", nil
-	if h, err := c.Take(w, func(asks.Option, asks.Warrant) error { t.Fatal("acted"); return nil }); h != Recorded || err != nil {
-		t.Fatalf("%s %v", h, err)
-	}
-	if h, _ := c.Take(warrant(), func(asks.Option, asks.Warrant) error { t.Fatal("acted after it ended"); return nil }); h != Done {
-		t.Errorf("%s", h)
-	}
-}

go/asks/asks.go

@@ -1,573 +0,0 @@
-// Package asks is the contract of asking a person and answering on a channel (novox/hq ADR 0259): the
-// shapes an asker, the router and a channel exchange on the bus, and the subjects they travel on. No
-// transport and no channel's service: an asker publishes an Ask under its own name and acts on the Warrant
-// it hears; the router holds the ask, sends channels a Message, and judges the Choice a channel says; a
-// channel shows a Message and says what was chosen and by whom, as its service authenticated it.
-package asks
-
-import (
-	"crypto/sha256"
-	"encoding/hex"
-	"errors"
-	"fmt"
-	"regexp"
-	"sort"
-	"strconv"
-	"strings"
-	"time"
-)
-
-// The seats (novox/hq ADR 0259 §3).
-const (
-	// Seat is held by the router: an ask and its cancel are its accepts, a warrant its event, each named by
-	// the asker.
-	Seat = "operator-channel"
-	// ChannelSeat is the kinded bench a channel holds to show and say: its accepts carry the kind.
-	ChannelSeat = "channel"
-	// IntakeSeat is the kinded bench a channel holds to say what was chosen: its events and proofs carry
-	// the kind.
-	IntakeSeat = "intake"
-)
-
-// AskSubject is where an asker publishes an ask, CancelSubject its cancel, and DecidedSubject where it
-// hears the warrant, or the ask's end without one.
-func AskSubject(asker string) string     { return "mesh.seat." + Seat + ".accept.ask." + asker }
-func CancelSubject(asker string) string  { return "mesh.seat." + Seat + ".accept.cancel." + asker }
-func DecidedSubject(asker string) string { return "mesh.seat." + Seat + ".event.decided." + asker }
-
-// The work a channel takes, on ChannelSubject.
-const (
-	Show = "show" // a message offering answers
-	Edit = "edit" // a message shown before, replaced
-	Send = "send" // a message offering nothing
-)
-
-// ChannelSubject is where the router sends a channel of a kind its work.
-func ChannelSubject(verb, kind string) string {
-	return "mesh.seat." + ChannelSeat + ".accept." + verb + "." + kind
-}
-
-// What a channel says, on IntakeSubject.
-const (
-	Chosen = "choice" // a button tapped
-	Link   = "link"   // somebody asked to be linked as the operator
-)
-
-// IntakeSubject is where a channel of a kind says what arrived.
-func IntakeSubject(what, kind string) string {
-	return "mesh.seat." + IntakeSeat + ".event." + what + "." + kind
-}
-
-// CodeProof is the one proof verb: a code the operator typed, carried by request and reply, never kept.
-const CodeProof = "code"
-
-// ProofSubject is where a channel of a kind asks a proof.
-func ProofSubject(verb, kind string) string {
-	return "mesh.seat." + IntakeSeat + ".proof." + verb + "." + kind
-}
-
-// A Level is how much proof an option's answer needs (novox/hq ADR 0234 §8, the glossary's assurance level).
-type Level string
-
-const (
-	// Acknowledge performs only what any granted principal may already do: silencing, details. No proof.
-	Acknowledge Level = "acknowledge"
-	// Approve needs one proof: a verified sender (a linked account, linked an hour or more) or a code.
-	Approve Level = "approve"
-	// Destroy needs two proofs, one of them a code.
-	Destroy Level = "destroy"
-)
-
-// Rank orders the levels; an unknown level ranks above every known one, so it is never taken as less.
-func (l Level) Rank() int {
-	switch l {
-	case Acknowledge:
-		return 0
-	case Approve:
-		return 1
-	case Destroy:
-		return 2
-	}
-	return 3
-}
-
-// Operator is the one role an ask may be answered by today.
-const Operator = "operator"
-
-// Option is one answer an ask offers: a label for the button, what it does in plain words, its level.
-type Option struct {
-	ID    string `json:"id"`
-	Label string `json:"label"`
-	Does  string `json:"does"`
-	Level Level  `json:"level"`
-	// Binds is the digest of exactly what the asker performs when this option is chosen — the verb, the
-	// machine and every argument — as ActDigest gives it. It travels in the ask, so the router's warrant,
-	// which names the ask's digest, names it too: a warrant then authorises that act and no other, and an
-	// asker whose record of the act changed after it asked finds the digests differ and does nothing.
-	// Required on an option above acknowledge.
-	Binds string `json:"binds,omitempty"`
-}
-
-// An Act is what an option binds: named fields, each a string — the verb, the machine, the level, and each
-// argument under a name of its own ("arg.delivery"). Flat on purpose: its digest is over these names and
-// values alone, never over how a language happens to encode a struct.
-type Act map[string]string
-
-// ActDigest is the digest an asker puts in Option.Binds: SHA-256 over the act's canonical encoding (canonical),
-// written "sha256:<hex>". The same names and values give the same digest in any language, whatever order
-// they were set in; a field renamed, added or emptied gives another.
-func ActDigest(act Act) (string, error) {
-	if len(act) == 0 {
-		return "", fmt.Errorf("the act cannot be digested: it names nothing")
-	}
-	keys := make([]string, 0, len(act))
-	for k := range act {
-		if k == "" {
-			return "", fmt.Errorf("the act cannot be digested: a field has no name")
-		}
-		keys = append(keys, k)
-	}
-	sort.Strings(keys)
-	var b strings.Builder
-	b.WriteString("novox.act.v1\n")
-	for _, k := range keys {
-		canonical(&b, k)
-		canonical(&b, act[k])
-	}
-	sum := sha256.Sum256([]byte(b.String()))
-	return "sha256:" + hex.EncodeToString(sum[:]), nil
-}
-
-// canonical writes one value as its length in bytes, a colon, the bytes and a newline: no value can be read
-// as another's end or start, so two different sequences of values never encode the same.
-func canonical(b *strings.Builder, v string) {
-	b.WriteString(strconv.Itoa(len(v)))
-	b.WriteByte(':')
-	b.WriteString(v)
-	b.WriteByte('\n')
-}
-
-// Digest is the digest of the ask exactly as its asker published it: its id, words, options with what each
-// binds, who answers, and its expiry. The router puts it in the warrant (Warrant.AskDigest), and an asker
-// acts only on a warrant whose digest is that of the ask it keeps — so a warrant answers one ask, as the
-// person was shown it, and nothing published under the same id before or after.
-//
-// It is over the ask's named fields in a fixed order, each written canonically, and the expiry as UTC
-// RFC 3339 to the nanosecond — never over a language's encoding of the struct, so a field added to Ask
-// later changes no digest until it is added here, on purpose. Whole and Details (novox/hq issue 383) follow
-// the options only when the ask gives either: an ask without them digests as it did before they existed, so
-// a router and an asker of different builds still agree on every such ask.
-func (a Ask) Digest() string {
-	var b strings.Builder
-	b.WriteString("novox.ask.v1\n")
-	for _, v := range []string{a.ID, a.Headline, a.Explanation, a.Who,
-		a.Expires.UTC().Format(time.RFC3339Nano), a.OnExpiry, a.About, strconv.FormatBool(a.Urgent),
-		strconv.Itoa(len(a.Options))} {
-		canonical(&b, v)
-	}
-	for _, o := range a.Options {
-		for _, v := range []string{o.ID, o.Label, o.Does, string(o.Level), o.Binds} {
-			canonical(&b, v)
-		}
-	}
-	// Whole and Details are written whenever either or WholeDetails is given, and WholeDetails after them whenever
-	// it is given (novox/hq ADR 0347): the fields after the options are then always one of three fixed shapes —
-	// none, the two, or the three — and the count of values the sequence holds tells them apart, so no two asks
-	// encode the same (the review of mesh-sdk #25). An ask with none of them digests as before they existed, and
-	// one without WholeDetails as before it existed.
-	if a.Whole != "" || a.Details != "" || a.WholeDetails != "" {
-		canonical(&b, a.Whole)
-		canonical(&b, a.Details)
-	}
-	if a.WholeDetails != "" {
-		canonical(&b, a.WholeDetails)
-	}
-	sum := sha256.Sum256([]byte(b.String()))
-	return "sha256:" + hex.EncodeToString(sum[:])
-}
-
-// Ask is a request for a person's word (novox/hq ADR 0259 §4).
-type Ask struct {
-	// ID is the asker's own, unique to it.
-	ID string `json:"id"`
-	// Headline names the thing and what is wrong, in a few plain words; Explanation is what happened and
-	// what it means. Both are held to the plain rule and the content rule by the router.
-	Headline    string   `json:"headline"`
-	Explanation string   `json:"explanation"`
-	Options     []Option `json:"options"`
-	// Who may answer: Operator.
-	Who string `json:"who"`
-	// Expires is when the ask ends unanswered; OnExpiry is what the asker then does, in words the person
-	// is shown ("the delivery stays held"). An ask that authorises never defaults.
-	Expires  time.Time `json:"expires"`
-	OnExpiry string    `json:"on-expiry"`
-	// About is what the ask is about (a condition's key): a newer ask about it replaces the older.
-	About  string `json:"about,omitempty"`
-	Urgent bool   `json:"urgent,omitempty"`
-	// Whole is the explanation with its exact values whole, shown in place of Explanation on a channel kind
-	// that proves who answers (verified-sender) and carries the ask's answers (novox/hq issue 383): what the
-	// person approves — a mount point, a share, a private address — must be readable where they approve it.
-	// The asker withholds a value shaped like a secret in it, and the router refuses the ask when one is left;
-	// Explanation stays under the whole content rule everywhere else. Empty, Explanation is shown everywhere.
-	Whole string `json:"whole,omitempty"`
-	// Details are the ask's secondary words, line by line under the content rule: who proposed it, a
-	// fingerprint, how to read it whole. The router shows them in the note of the ask's own message
-	// (Message.Note), after what the ask's options do and when it expires — never in its body (novox/hq
-	// issue 639).
-	Details string `json:"details,omitempty"`
-	// WholeDetails are the Details with their exact values whole, shown in place of Details where Whole is shown
-	// in place of the explanation (a kind that proves who answers, given the ask's answers): every value an
-	// approval sets, whole, so the person reads exactly what they approve (novox/hq issue 383). Held, like
-	// Whole, to the secret rule alone; the router refuses the ask when a secret's shape is left in it. Empty,
-	// Details are shown everywhere.
-	WholeDetails string `json:"whole-details,omitempty"`
-}
-
-// What an ask's explanation is held to, so it reads at a glance on a phone (novox/hq issue 639): a summary
-// of two or three short sentences on its first line — what changes, why, what it costs or risks — then at
-// most three points, a line each, only where they add something. Whole is held to the same. Who asked, when,
-// the fingerprint and how to read it whole are Details, never the explanation.
-const (
-	SummaryLength = 300
-	MostPoints    = 3
-	PointLength   = 160
-)
-
-// Glance says why an explanation does not read at a glance, or nil: its first line, the summary, longer than
-// SummaryLength; more than MostPoints lines after it; a point longer than PointLength. Blank lines are not
-// counted. An asker holds its asks to it in its own tests; the router says, without refusing, an ask that
-// does not hold to it.
-func Glance(explanation string) error {
-	var lines []string
-	for _, l := range strings.Split(explanation, "\n") {
-		if strings.TrimSpace(l) != "" {
-			lines = append(lines, strings.TrimSpace(l))
-		}
-	}
-	var problems []string
-	switch {
-	case len(lines) == 0:
-		problems = append(problems, "it has no summary")
-	case len([]rune(lines[0])) > SummaryLength:
-		problems = append(problems, fmt.Sprintf("its summary is %d characters, more than %d", len([]rune(lines[0])), SummaryLength))
-	}
-	if len(lines) > 1+MostPoints {
-		problems = append(problems, fmt.Sprintf("it has %d points after its summary, more than %d", len(lines)-1, MostPoints))
-	}
-	for i, l := range lines {
-		if i > 0 && len([]rune(l)) > PointLength {
-			problems = append(problems, fmt.Sprintf("its point %d is %d characters, more than %d", i, len([]rune(l)), PointLength))
-		}
-	}
-	if len(problems) > 0 {
-		return errors.New("the explanation does not read at a glance: " + strings.Join(problems, "; "))
-	}
-	return nil
-}
-
-// The bounds of an ask (novox/hq ADR 0234 §8, ADR 0259 §4).
-const (
-	MostOptions    = 4
-	MostOpen       = 3
-	ApproveLasts   = 24 * time.Hour
-	DestroyLasts   = 10 * time.Minute
-	HeadlineLength = 60
-	LabelLength    = 24
-)
-
-var usableID = regexp.MustCompile(`^[A-Za-z0-9][A-Za-z0-9_-]{0,63}$`)
-
-// UsableID says whether a name can be an ask's or an option's id: a key and a subject token both.
-func UsableID(id string) bool { return usableID.MatchString(id) }
-
-// Highest is the highest level among the ask's options.
-func (a Ask) Highest() Level {
-	high := Acknowledge
-	for _, o := range a.Options {
-		if o.Level.Rank() > high.Rank() {
-			high = o.Level
-		}
-	}
-	return high
-}
-
-// Option is the option of this id, or false.
-func (a Ask) Option(id string) (Option, bool) {
-	for _, o := range a.Options {
-		if o.ID == id {
-			return o, true
-		}
-	}
-	return Option{}, false
-}
-
-// Check is what an ask is held to before anything is shown: every refusal, in words its asker can act on.
-func (a Ask) Check(now time.Time) error {
-	var problems []string
-	say := func(format string, args ...any) { problems = append(problems, fmt.Sprintf(format, args...)) }
-	if !UsableID(a.ID) {
-		say("its id %q is not letters, digits, - and _, at most 64", a.ID)
-	}
-	if strings.TrimSpace(a.Headline) == "" || len([]rune(a.Headline)) > HeadlineLength {
-		say("its headline is empty or longer than %d characters", HeadlineLength)
-	}
-	if strings.TrimSpace(a.Explanation) == "" {
-		say("it explains nothing")
-	}
-	if a.Who != Operator {
-		say("it is answered by %q, and only the operator answers today", a.Who)
-	}
-	if len(a.Options) == 0 || len(a.Options) > MostOptions {
-		say("it offers %d options, and an ask offers one to %d", len(a.Options), MostOptions)
-	}
-	seen := map[string]bool{}
-	for _, o := range a.Options {
-		switch {
-		case !UsableID(o.ID):
-			say("an option's id %q is not letters, digits, - and _", o.ID)
-		case seen[o.ID]:
-			say("the option %s is offered twice", o.ID)
-		}
-		seen[o.ID] = true
-		if strings.TrimSpace(o.Label) == "" || len([]rune(o.Label)) > LabelLength {
-			say("the option %s's label is empty or longer than %d characters", o.ID, LabelLength)
-		}
-		if strings.TrimSpace(o.Does) == "" {
-			say("the option %s does not say what it does", o.ID)
-		}
-		if o.Level.Rank() > Destroy.Rank() {
-			say("the option %s has the level %q, which is none of acknowledge, approve, destroy", o.ID, o.Level)
-		}
-		if o.Level != Acknowledge && !strings.HasPrefix(o.Binds, "sha256:") {
-			say("the option %s authorises and does not bind what it performs (its binds is not an ActDigest)", o.ID)
-		}
-	}
-	if !a.Expires.After(now) {
-		say("it expires before it is asked")
-	}
-	switch a.Highest() {
-	case Approve:
-		if a.Expires.After(now.Add(ApproveLasts)) {
-			say("an ask that approves lasts at most %s", ApproveLasts)
-		}
-	case Destroy:
-		if a.Expires.After(now.Add(DestroyLasts)) {
-			say("an ask that destroys lasts at most %s", DestroyLasts)
-		}
-	}
-	if a.Highest() != Acknowledge && strings.TrimSpace(a.OnExpiry) == "" {
-		say("it does not say what happens when nobody answers, and an ask that authorises never defaults")
-	}
-	if a.About != "" && strings.ContainsAny(a.About, " \n") {
-		say("what it is about is a key, without spaces")
-	}
-	if len(problems) > 0 {
-		return errors.New("the ask is refused: " + strings.Join(problems, "; "))
-	}
-	return nil
-}
-
-// Outcome is how an ask ended.
-type Outcome string
-
-const (
-	OutcomeChosen    Outcome = "chosen"    // a person chose an option: a warrant
-	OutcomeExpired   Outcome = "expired"   // nobody answered in time
-	OutcomeCancelled Outcome = "cancelled" // its asker took it back
-	OutcomeReplaced  Outcome = "replaced"  // a newer ask about the same thing replaced it
-	OutcomeRefused   Outcome = "refused"   // it was never shown: Words says why
-)
-
-// Person is who chose, as the router verified them.
-type Person struct {
-	// Who is the role: Operator.
-	Who string `json:"who"`
-	// Kind is the channel kind they answered on, Identity their account on that service, Display the name
-	// the service shows, and Verified how the router knew it was them.
-	Kind     string `json:"kind"`
-	Identity string `json:"identity"`
-	Display  string `json:"display,omitempty"`
-	Verified string `json:"verified"`
-}
-
-// Warrant is the router's record that a person chose one option of one ask, or the ask's end without one
-// (novox/hq ADR 0259 §6). It carries no secret.
-type Warrant struct {
-	Ask     string  `json:"ask"`
-	Asker   string  `json:"asker"`
-	About   string  `json:"about,omitempty"`
-	Outcome Outcome `json:"outcome"`
-	// Option, Label and Level are the option chosen; By who chose it, Channel the module it came through,
-	// Proofs which proofs were present (P1, P2, P3).
-	Option  string    `json:"option,omitempty"`
-	Label   string    `json:"label,omitempty"`
-	Level   Level     `json:"level,omitempty"`
-	By      *Person   `json:"by,omitempty"`
-	Channel string    `json:"channel,omitempty"`
-	Proofs  []string  `json:"proofs,omitempty"`
-	At      time.Time `json:"at"`
-	// AskDigest is the digest of the ask as the router took it (Ask.Digest): the warrant answers that ask
-	// alone, with the options it bound.
-	AskDigest string `json:"ask-digest,omitempty"`
-	// Words are why an ask ended without a choice, or what refused it.
-	Words string `json:"words,omitempty"`
-}
-
-// Says is the warrant in the words an asker records with its act: "the operator, via telegram (user id
-// verified), chose Release".
-func (w Warrant) Says() string {
-	if w.Outcome != OutcomeChosen || w.By == nil {
-		return fmt.Sprintf("no person chose: the ask %s %s", w.Ask, w.Outcome)
-	}
-	via := w.By.Kind
-	if w.By.Verified != "" {
-		via += " (" + w.By.Verified + ")"
-	}
-	return fmt.Sprintf("the %s, via %s, chose %s", w.By.Who, via, w.Label)
-}
-
-// For checks a warrant against the ask its asker made: the same asker and ask, the same ask's digest (so the
-// same words, options and binds), a choice, an option the ask offered, at that option's level, before the
-// ask expired. An asker acts on nothing else, and then performs only what the option's Binds names.
-func (w Warrant) For(asker string, a Ask) (Option, error) {
-	if w.Asker != asker || w.Ask != a.ID {
-		return Option{}, fmt.Errorf("the warrant is for %s's ask %s, not %s's %s", w.Asker, w.Ask, asker, a.ID)
-	}
-	if w.Outcome != OutcomeChosen || w.By == nil || w.By.Who != a.Who {
-		return Option{}, fmt.Errorf("the ask %s ended %s; no person chose", a.ID, w.Outcome)
-	}
-	if d := a.Digest(); w.AskDigest != d {
-		return Option{}, fmt.Errorf("the warrant answers an ask whose digest is %q, and the ask %s kept here is %s: "+
-			"it was not the ask the person was shown", w.AskDigest, a.ID, d)
-	}
-	o, offered := a.Option(w.Option)
-	if !offered {
-		return Option{}, fmt.Errorf("the ask %s offered no option %s", a.ID, w.Option)
-	}
-	if w.Level != o.Level {
-		return Option{}, fmt.Errorf("the option %s is %s, and the warrant says %s", o.ID, o.Level, w.Level)
-	}
-	// A choice made after the ask expired is no answer to it, whatever the router said. An ask that says no
-	// expiry, or a warrant that says no time, is no answer either: neither can be shown to be in time (the
-	// confirmation review of 2026-10-09).
-	if a.Expires.IsZero() {
-		return Option{}, fmt.Errorf("the ask %s says no expiry, so no answer to it can be in time", a.ID)
-	}
-	if w.At.IsZero() {
-		return Option{}, fmt.Errorf("the warrant for the ask %s says no time it was given, so it cannot be shown to be in time", a.ID)
-	}
-	if w.At.After(a.Expires) {
-		return Option{}, fmt.Errorf("the warrant was given at %s, after the ask %s expired at %s",
-			w.At.UTC().Format(time.RFC3339), a.ID, a.Expires.UTC().Format(time.RFC3339))
-	}
-	return o, nil
-}
-
-// Performs checks that the act an asker is about to perform is the one the chosen option bound when it
-// asked: the act's digest equals the option's Binds. An acknowledge option that bound nothing passes.
-func (o Option) Performs(act Act) error {
-	if o.Binds == "" && o.Level == Acknowledge {
-		return nil
-	}
-	d, err := ActDigest(act)
-	if err != nil {
-		return err
-	}
-	if d != o.Binds {
-		return fmt.Errorf("the option %s bound %s, and the act about to be performed is %s: nothing is done", o.ID, o.Binds, d)
-	}
-	return nil
-}
-
-// Button is one answer a channel offers: its label and the router's one-time ticket for it.
-type Button struct {
-	Label  string `json:"label"`
-	Ticket string `json:"ticket"`
-}
-
-// Message is the work a channel takes: shown with buttons (Show), shown again in place (Edit), or said
-// (Send). Handle is the router's name for it, the same across a show and its edits; the channel keeps
-// which of its own messages that is. The words are the router's, shown as given.
-type Message struct {
-	Handle  string   `json:"handle"`
-	Title   string   `json:"title"`
-	Body    string   `json:"body"`
-	Buttons []Button `json:"buttons,omitempty"`
-	// Note is the message's secondary words, after its body and its buttons: who asked and when, what each
-	// answer does, when it expires, and the ask's Details. A channel shows it smaller, collapsed or set apart
-	// where it can, and after the body where it cannot (novox/hq issue 639). A channel that bounds a message's
-	// length cuts the body first and the note only when the title and the note alone do not fit, saying each
-	// cut (novox/hq ADR 0347 §5).
-	Note   string `json:"note,omitempty"`
-	Urgent bool   `json:"urgent,omitempty"`
-	Silent bool   `json:"silent,omitempty"`
-	// Reply is the Choice or LinkAsked this answers, by its ID: the channel shows it where that was made.
-	Reply string `json:"reply,omitempty"`
-	// To is the account linked as the operator on this kind, for a channel that verifies its sender: where
-	// the channel sends what is not a reply. The router's word, from its list; empty when none is linked.
-	To string `json:"to,omitempty"`
-	// Secret says the words carry something shown once (a link's code): the channel shows it and keeps no
-	// copy of it — no state, no history of its own.
-	Secret bool `json:"secret,omitempty"`
-}
-
-// Sender is who a channel's service says sent something: the account, the name it shows, and whether the
-// service authenticated it. The router alone judges whether that is the operator.
-type Sender struct {
-	Identity      string `json:"identity"`
-	Display       string `json:"display,omitempty"`
-	Authenticated bool   `json:"authenticated"`
-}
-
-// Failed is a message a channel could not deliver: its handle, why, and whether trying again could help.
-type Failed struct {
-	Handle    string    `json:"handle"`
-	Why       string    `json:"why"`
-	Permanent bool      `json:"permanent,omitempty"`
-	At        time.Time `json:"at"`
-}
-
-// Standing is what a channel says of itself, at least every five minutes and whenever it changes:
-// whether it can send now, why not, and whether its edits notify nobody.
-type Standing struct {
-	Ready         bool      `json:"ready"`
-	Why           string    `json:"why,omitempty"`
-	EditsSilently bool      `json:"edits-silently,omitempty"`
-	At            time.Time `json:"at"`
-}
-
-// What a channel says of its own delivery, on IntakeSubject.
-const (
-	FailedWhat   = "failed"
-	StandingWhat = "standing"
-)
-
-// Choice is a button chosen on a channel.
-type Choice struct {
-	// ID is the channel's own for this arrival, unique, so the router acts on it once.
-	ID     string    `json:"id"`
-	Ticket string    `json:"ticket"`
-	Handle string    `json:"handle,omitempty"`
-	Sender Sender    `json:"sender"`
-	At     time.Time `json:"at"`
-}
-
-// LinkAsked is somebody on a channel asking to be linked as the operator.
-type LinkAsked struct {
-	ID     string    `json:"id"`
-	Sender Sender    `json:"sender"`
-	At     time.Time `json:"at"`
-}
-
-// Code is a code a person typed on a channel, asked as a proof: never in an event, never kept.
-type Code struct {
-	Sender  Sender `json:"sender"`
-	Code    string `json:"code"`
-	Purpose string `json:"purpose"`
-}
-
-// ProofAnswer is the router's answer to a proof: whether it was taken, and words to say to the person.
-type ProofAnswer struct {
-	Accepted bool   `json:"accepted"`
-	Words    string `json:"words"`
-}

go/asks/asks_test.go

@@ -1,367 +0,0 @@
-package asks
-
-import (
-	"crypto/sha256"
-	"encoding/hex"
-	"encoding/json"
-	"reflect"
-	"strings"
-	"testing"
-	"time"
-)
-
-var now = time.Date(2026, 10, 8, 14, 0, 0, 0, time.UTC)
-
-func held() Ask {
-	return Ask{ID: "d-1", Headline: "openrazer delivery held", Explanation: "Needs you: release it, or stop it.",
-		Who: Operator, Expires: now.Add(time.Hour), OnExpiry: "the delivery stays held", About: "delivery.openrazer",
-		Options: []Option{
-			{ID: "release", Label: "Release", Does: "the delivery goes on", Level: Approve, Binds: bind("release", "openrazer")},
-			{ID: "stop", Label: "Stop", Does: "the delivery ends", Level: Approve, Binds: bind("stop", "openrazer")},
-			{ID: "silence", Label: "Silence for a week", Does: "nothing more is said for a week", Level: Acknowledge},
-		}}
-}
-
-func bind(verb, what string) string {
-	d, err := ActDigest(Act{"verb": verb, "delivery": what})
-	if err != nil {
-		panic(err)
-	}
-	return d
-}
-
-func TestASoundAskPasses(t *testing.T) {
-	if err := held().Check(now); err != nil {
-		t.Fatal(err)
-	}
-}
-
-func TestAnAskIsRefusedInWordsForEachFault(t *testing.T) {
-	for want, change := range map[string]func(*Ask){
-		"is not letters":             func(a *Ask) { a.ID = "a.b" },
-		"headline is empty":          func(a *Ask) { a.Headline = "" },
-		"explains nothing":           func(a *Ask) { a.Explanation = " " },
-		"only the operator answers":  func(a *Ask) { a.Who = "agent" },
-		"offers 0 options":           func(a *Ask) { a.Options = nil },
-		"offers 5 options":           func(a *Ask) { a.Options = append(a.Options, a.Options[0], a.Options[1]) },
-		"is offered twice":           func(a *Ask) { a.Options[1].ID = "release" },
-		"does not say what it does":  func(a *Ask) { a.Options[0].Does = "" },
-		"none of acknowledge":        func(a *Ask) { a.Options[0].Level = "admin" },
-		"expires before it is asked": func(a *Ask) { a.Expires = now },
-		"approves lasts at most":     func(a *Ask) { a.Expires = now.Add(25 * time.Hour) },
-		"destroys lasts at most":     func(a *Ask) { a.Options[0].Level = Destroy },
-		"never defaults":             func(a *Ask) { a.OnExpiry = "" },
-		"is a key, without spaces":   func(a *Ask) { a.About = "a b" },
-		"does not bind what it":      func(a *Ask) { a.Options[0].Binds = "" },
-	} {
-		a := held()
-		change(&a)
-		if err := a.Check(now); err == nil || !strings.Contains(err.Error(), want) {
-			t.Errorf("want a refusal saying %q, got %v", want, err)
-		}
-	}
-	ack := held()
-	ack.Options = ack.Options[2:]
-	ack.OnExpiry = ""
-	ack.Expires = now.Add(7 * 24 * time.Hour)
-	if err := ack.Check(now); err != nil {
-		t.Errorf("an ask that only acknowledges needs no expiry words and may last a week: %v", err)
-	}
-}
-
-func TestAnAskerActsOnlyOnAWarrantForItsOwnAskAndOption(t *testing.T) {
-	w := Warrant{Ask: "d-1", Asker: "mesh-delivery", Outcome: OutcomeChosen, Option: "release", Label: "Release",
-		Level: Approve, By: &Person{Who: Operator, Kind: "telegram", Identity: "42", Verified: "user id verified"},
-		AskDigest: held().Digest(), At: now.Add(time.Minute)}
-	if o, err := w.For("mesh-delivery", held()); err != nil || o.ID != "release" {
-		t.Fatalf("a sound warrant was refused: %v", err)
-	}
-	if got := w.Says(); got != "the operator, via telegram (user id verified), chose Release" {
-		t.Errorf("the warrant says %q", got)
-	}
-	for why, change := range map[string]func(*Warrant){
-		"another asker": func(w *Warrant) { w.Asker = "mesh-controller" },
-		"another ask":   func(w *Warrant) { w.Ask = "d-2" },
-		"no choice":     func(w *Warrant) { w.Outcome = OutcomeExpired },
-		"nobody":        func(w *Warrant) { w.By = nil },
-		"not offered":   func(w *Warrant) { w.Option = "delete" },
-		"a lower level": func(w *Warrant) { w.Level = Acknowledge },
-		"another role":  func(w *Warrant) { w.By = &Person{Who: "agent"} },
-		"no digest":     func(w *Warrant) { w.AskDigest = "" },
-		"no time given": func(w *Warrant) { w.At = time.Time{} },
-		"after expiry":  func(w *Warrant) { w.At = now.Add(2 * time.Hour) },
-		"another ask's digest": func(w *Warrant) {
-			other := held()
-			other.Options[0].Binds = bind("release", "another")
-			w.AskDigest = other.Digest()
-		},
-	} {
-		c := w
-		by := *w.By
-		c.By = &by
-		change(&c)
-		if _, err := c.For("mesh-delivery", held()); err == nil {
-			t.Errorf("a warrant with %s was acted on", why)
-		}
-	}
-}
-
-func TestTheSubjectsNameTheirPublisher(t *testing.T) {
-	for got, want := range map[string]string{
-		AskSubject("mesh-delivery"):         "mesh.seat.operator-channel.accept.ask.mesh-delivery",
-		DecidedSubject("mesh-delivery"):     "mesh.seat.operator-channel.event.decided.mesh-delivery",
-		ChannelSubject(Show, "telegram"):    "mesh.seat.channel.accept.show.telegram",
-		IntakeSubject(Chosen, "desktop"):    "mesh.seat.intake.event.choice.desktop",
-		ProofSubject(CodeProof, "telegram"): "mesh.seat.intake.proof.code.telegram",
-	} {
-		if got != want {
-			t.Errorf("%s, want %s", got, want)
-		}
-	}
-}
-
-// A warrant answers one ask as it was shown, and authorises the act its option bound and no other
-// (novox/hq ADR 0259 §6: the warrant is bound to the exact ask and its arguments).
-func TestAWarrantAuthorisesOnlyTheActItsOptionBound(t *testing.T) {
-	a := held()
-	// The digest survives the trip through the bus: what the router decodes and digests is what was sent.
-	raw, err := json.Marshal(a)
-	if err != nil {
-		t.Fatal(err)
-	}
-	var decoded Ask
-	if err := json.Unmarshal(raw, &decoded); err != nil {
-		t.Fatal(err)
-	}
-	if decoded.Digest() != a.Digest() {
-		t.Fatalf("the ask's digest changed on the way: %s, %s", decoded.Digest(), a.Digest())
-	}
-	local := a
-	local.Expires = a.Expires.In(time.FixedZone("CEST", 2*3600))
-	if local.Digest() != a.Digest() {
-		t.Error("the same instant in another zone digests differently")
-	}
-	// Changing anything the person was shown, or what an option binds, changes the digest.
-	for what, change := range map[string]func(*Ask){
-		"the headline":     func(a *Ask) { a.Headline += "!" },
-		"the explanation":  func(a *Ask) { a.Explanation += " " },
-		"a label":          func(a *Ask) { a.Options[0].Label = "Go" },
-		"what it binds":    func(a *Ask) { a.Options[0].Binds = bind("release", "another") },
-		"the expiry":       func(a *Ask) { a.Expires = a.Expires.Add(time.Second) },
-		"what it is about": func(a *Ask) { a.About = "delivery.other" },
-	} {
-		c := held()
-		change(&c)
-		if c.Digest() == a.Digest() {
-			t.Errorf("changing %s leaves the digest", what)
-		}
-	}
-	o, _ := a.Option("release")
-	if err := o.Performs(Act{"verb": "release", "delivery": "openrazer"}); err != nil {
-		t.Errorf("the bound act was refused: %v", err)
-	}
-	if err := o.Performs(Act{"verb": "release", "delivery": "another"}); err == nil {
-		t.Error("an act the option did not bind was let through")
-	}
-	ack, _ := a.Option("silence")
-	if err := ack.Performs(Act{"anything": "x"}); err != nil {
-		t.Errorf("an acknowledgement that bound nothing: %v", err)
-	}
-}
-
-// The digests are over named fields in a canonical encoding (the review of 2026-10-09): not over Go's
-// encoding of a struct, so a field added to Ask or Option, a JSON tag renamed, or a map built in another
-// order changes nothing it should not — and every field that is shown or bound is in it.
-func TestDigestsAreCanonicalOverNamedFields(t *testing.T) {
-	a1, _ := ActDigest(Act{"verb": "release", "arg.delivery": "hq"})
-	b := Act{}
-	b["arg.delivery"] = "hq"
-	b["verb"] = "release"
-	a2, _ := ActDigest(b)
-	if a1 != a2 {
-		t.Error("the order an act was built in changed its digest")
-	}
-	// A value cannot be read as two: "a"+"b=c" is not "a=b"+"c".
-	x, _ := ActDigest(Act{"a": "b\n1:c"})
-	y, _ := ActDigest(Act{"a": "b", "c": ""})
-	if x == y {
-		t.Error("two different acts encode the same")
-	}
-	if _, err := ActDigest(Act{}); err == nil {
-		t.Error("an empty act was digested")
-	}
-	// The encoding, by hand: any language reproduces it.
-	sum := sha256.Sum256([]byte("novox.act.v1\n4:verb\n7:release\n"))
-	if got, _ := ActDigest(Act{"verb": "release"}); got != "sha256:"+hex.EncodeToString(sum[:]) {
-		t.Errorf("the act's encoding is not the one written down: %s", got)
-	}
-
-	// Every exported field of Ask and Option is in the digest: changing any one changes it.
-	base := held()
-	mutations := map[string]func(*Ask){
-		"ID":          func(a *Ask) { a.ID = "other" },
-		"Headline":    func(a *Ask) { a.Headline += "!" },
-		"Explanation": func(a *Ask) { a.Explanation += "!" },
-		"Who":         func(a *Ask) { a.Who = "someone" },
-		"Expires":     func(a *Ask) { a.Expires = a.Expires.Add(time.Nanosecond) },
-		"OnExpiry":    func(a *Ask) { a.OnExpiry += "!" },
-		"About":       func(a *Ask) { a.About += "!" },
-		"Urgent":      func(a *Ask) { a.Urgent = !a.Urgent },
-		"Options":     func(a *Ask) { a.Options = a.Options[:1] },
-		"Option.ID":   func(a *Ask) { a.Options = append([]Option(nil), a.Options...); a.Options[0].ID = "x" },
-		"Option.Label": func(a *Ask) {
-			a.Options = append([]Option(nil), a.Options...)
-			a.Options[0].Label += "!"
-		},
-		"Option.Does": func(a *Ask) { a.Options = append([]Option(nil), a.Options...); a.Options[0].Does += "!" },
-		"Option.Level": func(a *Ask) {
-			a.Options = append([]Option(nil), a.Options...)
-			a.Options[0].Level = Destroy
-		},
-		"Option.Binds": func(a *Ask) {
-			a.Options = append([]Option(nil), a.Options...)
-			a.Options[0].Binds = "sha256:00"
-		},
-	}
-	for name, mutate := range mutations {
-		c := base
-		mutate(&c)
-		if c.Digest() == base.Digest() {
-			t.Errorf("changing %s left the digest the same", name)
-		}
-	}
-	// Whole and Details (issue 383) are in the digest once given, and change it; an ask without either digests
-	// exactly as before they existed — the encoding by hand, so no build can drift from it unseen.
-	plain := Ask{ID: "p", Headline: "h", Explanation: "e", Who: Operator, Expires: now, OnExpiry: "o", About: "a",
-		Options: []Option{{ID: "ok", Label: "OK", Does: "d", Level: Acknowledge}}}
-	byHand := sha256.Sum256([]byte("novox.ask.v1\n1:p\n1:h\n1:e\n8:operator\n20:2026-10-08T14:00:00Z\n1:o\n1:a\n5:false\n1:1\n" +
-		"2:ok\n2:OK\n1:d\n11:acknowledge\n0:\n"))
-	if plain.Digest() != "sha256:"+hex.EncodeToString(byHand[:]) {
-		t.Errorf("an ask without Whole and Details does not digest as it did before them: %s", plain.Digest())
-	}
-	withWhole, withDetails := plain, plain
-	withWhole.Whole = "e, whole"
-	withDetails.Details = "fingerprint 1234"
-	if withWhole.Digest() == plain.Digest() || withDetails.Digest() == plain.Digest() || withWhole.Digest() == withDetails.Digest() {
-		t.Error("Whole or Details left the digest the same")
-	}
-	both := withWhole
-	both.Details = "fingerprint 1234"
-	changed := both
-	changed.Whole += "!"
-	if changed.Digest() == both.Digest() {
-		t.Error("changing Whole beside Details left the digest the same")
-	}
-	// A field added to Ask or Option without being added to Digest fails here.
-	if n := reflect.TypeOf(Ask{}).NumField(); n != 12 {
-		t.Errorf("Ask has %d fields, and Digest covers 12: add the new one to Digest and to this test", n)
-	}
-	if n := reflect.TypeOf(Option{}).NumField(); n != 5 {
-		t.Errorf("Option has %d fields, and Digest covers 5: add the new one to Digest and to this test", n)
-	}
-	// The same instant in another zone is the same ask.
-	z := base
-	z.Expires = z.Expires.In(time.FixedZone("x", 3600))
-	if z.Digest() != base.Digest() {
-		t.Error("the expiry's zone changed the digest")
-	}
-}
-
-// An ask that says no expiry is answered by no warrant (the confirmation review of 2026-10-09): nothing could
-// show the answer was in time.
-func TestAWarrantForAnAskWithNoExpiryIsRefused(t *testing.T) {
-	a := held()
-	a.Expires = time.Time{}
-	w := Warrant{Ask: "d-1", Asker: "mesh-delivery", Outcome: OutcomeChosen, Option: "release", Label: "Release",
-		Level: Approve, By: &Person{Who: Operator, Kind: "telegram", Identity: "42"}, AskDigest: a.Digest(),
-		At: now.Add(time.Minute)}
-	if _, err := w.For("mesh-delivery", a); err == nil {
-		t.Error("a warrant for an ask with no expiry was taken")
-	}
-}
-
-// An explanation that reads at a glance passes; a wall of text says each way it is one (novox/hq issue 639).
-func TestAnExplanationReadsAtAGlance(t *testing.T) {
-	if err := Glance("Your agents' memory follows you to every machine. A file changed on two keeps both.\n\n• Only the memory folders are carried\n• A conflict reaches you as a warning"); err != nil {
-		t.Fatalf("a summary and two points: %v", err)
-	}
-	var wall strings.Builder
-	wall.WriteString("ADR 0343 was proposed by fix-367 and approved by the knowledge base's own review.")
-	for i := 1; i <= 13; i++ {
-		wall.WriteString("\n" + strings.Repeat("A clause lead. ", 3))
-	}
-	err := Glance(wall.String())
-	if err == nil || !strings.Contains(err.Error(), "13 points") {
-		t.Fatalf("thirteen clause lines pass as a glance: %v", err)
-	}
-	if err := Glance(strings.Repeat("word ", 70)); err == nil || !strings.Contains(err.Error(), "summary is 349") {
-		t.Fatalf("a long summary passes: %v", err)
-	}
-	if err := Glance("short.\n" + strings.Repeat("p", PointLength+1)); err == nil || !strings.Contains(err.Error(), "point 1") {
-		t.Fatalf("a long point passes: %v", err)
-	}
-	if err := Glance(" \n"); err == nil {
-		t.Fatal("an empty explanation passes")
-	}
-}
-
-// A message's note travels beside its body, and is left out of the encoding when empty, so a channel older
-// than it reads every message it read before.
-func TestAMessageCarriesItsNoteApart(t *testing.T) {
-	raw, _ := json.Marshal(Message{Handle: "h", Title: "t", Body: "b", Note: "Asked by x."})
-	if !strings.Contains(string(raw), `"note":"Asked by x."`) {
-		t.Fatalf("the note is not encoded: %s", raw)
-	}
-	raw, _ = json.Marshal(Message{Handle: "h", Title: "t"})
-	if strings.Contains(string(raw), "note") {
-		t.Fatalf("an empty note is encoded: %s", raw)
-	}
-}
-
-// WholeDetails is digested when given, and an ask without it digests as before it existed: a router and an asker
-// of different builds still agree on every such ask.
-func TestWholeDetailsAreDigestedOnlyWhenGiven(t *testing.T) {
-	a := Ask{ID: "a", Headline: "h", Explanation: "e", Details: "d"}
-	before := a.Digest()
-	a.WholeDetails = "+ shares: media=/storage/media"
-	if a.Digest() == before {
-		t.Fatal("the whole details are not in the digest")
-	}
-	b := a
-	b.WholeDetails = "+ shares: media=/storage/other"
-	if a.Digest() == b.Digest() {
-		t.Fatal("two whole details digest the same")
-	}
-	a.WholeDetails = ""
-	if a.Digest() != before {
-		t.Fatal("an ask without whole details digests otherwise than before")
-	}
-}
-
-// No two asks encode the same (the review of mesh-sdk #25): whole details given beside nothing else are not read as
-// a Whole and Details that happen to spell the same values, nor as any other split of the three fields.
-func TestWholeDetailsCollideWithNoOtherAsk(t *testing.T) {
-	base := Ask{ID: "a", Headline: "h", Explanation: "e"}
-	shapes := []Ask{}
-	for _, f := range []struct{ whole, details, wholeDetails string }{
-		{"", "", "+ x: 1"},
-		{"whole-details", "+ x: 1", ""},
-		{"", "+ x: 1", ""},
-		{"+ x: 1", "", ""},
-		{"", "", "whole-details"},
-		{"", "+ x: 1", "+ x: 1"},
-		{"+ x: 1", "+ x: 1", ""},
-		{"", "", ""},
-	} {
-		a := base
-		a.Whole, a.Details, a.WholeDetails = f.whole, f.details, f.wholeDetails
-		shapes = append(shapes, a)
-	}
-	seen := map[string]int{}
-	for i, a := range shapes {
-		if j, ok := seen[a.Digest()]; ok {
-			t.Errorf("asks %d and %d digest the same: %+v / %+v", j, i, shapes[j], a)
-		}
-		seen[a.Digest()] = i
-	}
-}

go/asks/condition.go

@@ -1,149 +0,0 @@
-package asks
-
-import (
-	"encoding/json"
-	"errors"
-	"fmt"
-	"reflect"
-	"strings"
-)
-
-// ConditionSubject is where a module says a condition to the operator: a by-caller accept of the operator-channel
-// seat, `mesh.seat.operator-channel.accept.condition.<publisher>` (novox/hq ADR 0437 §9). The router reads the
-// verb at the fifth part and the caller at the sixth, so the publisher is one token, the module's own name; it is
-// refused when empty or when it holds a dot, a wildcard or whitespace.
-func ConditionSubject(publisher string) (string, error) {
-	if publisher == "" {
-		return "", errors.New("asks: the condition's publisher is empty")
-	}
-	if strings.ContainsAny(publisher, ".*> \t\r\n") || strings.ContainsFunc(publisher, func(r rune) bool { return r <= ' ' }) {
-		return "", fmt.Errorf("asks: the condition's publisher %q is not one token: it holds a dot, a wildcard or whitespace", publisher)
-	}
-	return "mesh.seat." + Seat + ".accept.condition." + publisher, nil
-}
-
-// ConditionVersion is the version of the condition value this package writes and the only one it reads.
-const ConditionVersion = 1
-
-// ErrUnknownConditionVersion is what DecodeCondition returns for a value whose version is missing or not
-// ConditionVersion. Test it with errors.Is.
-var ErrUnknownConditionVersion = errors.New("asks: unknown condition version")
-
-// The words a condition's explanation opens with (novox/hq ADR 0253 §1).
-const (
-	NothingToDo = "Nothing for you to do."
-	NeedsYou    = "Needs you: "
-)
-
-// The severities and states of a condition.
-const (
-	SeverityUrgent  = "urgent"
-	SeverityWarning = "warning"
-	StateRaised     = "raised"
-	StateCleared    = "cleared"
-)
-
-// Scope is what a condition is about, under the controller's names.
-type Scope struct {
-	Scope   string `json:"scope"`
-	ID      string `json:"id"`
-	Machine string `json:"machine,omitempty"`
-}
-
-// Action is one answer a notification offers, under the controller's names.
-type Action struct {
-	Label     string            `json:"label"`
-	Verb      string            `json:"verb"`
-	Machine   string            `json:"machine,omitempty"`
-	Arguments map[string]string `json:"arguments,omitempty"`
-	Level     Level             `json:"level,omitempty"`
-}
-
-// Condition is a condition a module says to the operator, under the names of the controller's conditions: its key,
-// severity, subject, state (raised or cleared), summary and the plain words of ADR 0253. A cleared condition needs
-// only its key, subject and state. The router alone chooses the channels.
-type Condition struct {
-	V           int      `json:"v"`
-	Key         string   `json:"key"`
-	Severity    string   `json:"severity,omitempty"`
-	Subject     Scope    `json:"subject"`
-	State       string   `json:"state"`
-	Summary     string   `json:"summary,omitempty"`
-	Headline    string   `json:"headline,omitempty"`
-	Needs       string   `json:"needs,omitempty"`
-	Explanation string   `json:"explanation,omitempty"`
-	Resolved    string   `json:"resolved,omitempty"`
-	Actions     []Action `json:"actions,omitempty"`
-}
-
-func (c Condition) check() error {
-	if c.Key == "" {
-		return errors.New("asks: a condition has no key")
-	}
-	if c.Subject.Scope == "" || c.Subject.ID == "" {
-		return errors.New("asks: a condition's subject needs its scope and id")
-	}
-	switch c.State {
-	case StateCleared:
-		return nil
-	case StateRaised:
-	default:
-		return fmt.Errorf("asks: the condition's state %q is not raised or cleared", c.State)
-	}
-	switch c.Severity {
-	case SeverityUrgent, SeverityWarning:
-	default:
-		return fmt.Errorf("asks: the condition's severity %q is not urgent or warning", c.Severity)
-	}
-	if c.Headline == "" {
-		return errors.New("asks: a raised condition has no headline")
-	}
-	if n := len([]rune(c.Headline)); n > HeadlineLength {
-		return fmt.Errorf("asks: the condition's headline is %d characters, more than %d", n, HeadlineLength)
-	}
-	verdict := NothingToDo
-	if c.Needs != "" {
-		verdict = NeedsYou + c.Needs
-	}
-	if !strings.HasPrefix(c.Explanation, verdict) {
-		return fmt.Errorf("asks: the condition's explanation must open with %q", verdict)
-	}
-	return nil
-}
-
-// EncodeCondition is c as JSON at ConditionVersion; it refuses what ADR 0253 and ADR 0437 §9 refuse.
-func EncodeCondition(c Condition) ([]byte, error) {
-	if err := c.check(); err != nil {
-		return nil, err
-	}
-	c.V = ConditionVersion
-	return json.Marshal(c)
-}
-
-// DecodeCondition reads a condition; it refuses an unknown version (ErrUnknownConditionVersion) and what
-// EncodeCondition refuses.
-func DecodeCondition(data []byte) (Condition, error) {
-	var probe struct {
-		V *int `json:"v"`
-	}
-	if err := json.Unmarshal(data, &probe); err != nil {
-		return Condition{}, fmt.Errorf("asks: the condition is not JSON: %w", err)
-	}
-	if probe.V == nil {
-		return Condition{}, fmt.Errorf("%w: no version in the value, this reader reads %d", ErrUnknownConditionVersion, ConditionVersion)
-	}
-	if *probe.V != ConditionVersion {
-		return Condition{}, fmt.Errorf("%w: the value is version %d, this reader reads %d", ErrUnknownConditionVersion, *probe.V, ConditionVersion)
-	}
-	var c Condition
-	if err := json.Unmarshal(data, &c); err != nil {
-		return Condition{}, fmt.Errorf("asks: the condition does not fit its shape: %w", err)
-	}
-	if err := c.check(); err != nil {
-		return Condition{}, err
-	}
-	return c, nil
-}
-
-// SameCondition says whether two conditions are the same value.
-func SameCondition(a, b Condition) bool { return reflect.DeepEqual(a, b) }

go/asks/condition_test.go

@@ -1,143 +0,0 @@
-package asks
-
-import (
-	"encoding/json"
-	"errors"
-	"strings"
-	"testing"
-)
-
-func TestConditionSubject(t *testing.T) { // 1202/AC1
-	s, err := ConditionSubject("mesh-delivery-teller")
-	if err != nil || s != "mesh.seat.operator-channel.accept.condition.mesh-delivery-teller" {
-		t.Fatalf("subject = %q, %v", s, err)
-	}
-	// The router splits an accept subject in six parts and reads the verb at 4 and the caller at 5.
-	parts := strings.Split(s, ".")
-	if len(parts) != 6 || parts[4] != "condition" || parts[5] != "mesh-delivery-teller" {
-		t.Errorf("subject %q does not keep the router's shape: %v", s, parts)
-	}
-	for _, bad := range []string{"", "a.b", "a*", "a>", "a b", "a\tb", "a\nb"} {
-		if _, err := ConditionSubject(bad); err == nil {
-			t.Errorf("publisher %q accepted", bad)
-		}
-	}
-}
-
-func raisedCondition() Condition {
-	return Condition{
-		Key: "delivery.stuck.mesh-mail", Severity: "warning",
-		Subject: Scope{Scope: "module", ID: "mesh-mail", Machine: "ace"}, State: "raised",
-		Summary: "plan 12 stopped", Headline: "Delivery of mesh-mail is stuck",
-		Needs: "approve the merge.", Explanation: "Needs you: approve the merge. The plan waits.",
-		Resolved: "The delivery of mesh-mail moved on.",
-		Actions: []Action{{Label: "Approve", Verb: "mesh-controller.assign", Machine: "ace",
-			Arguments: map[string]string{"why": ""}, Level: Approve}},
-	}
-}
-
-func clearedCondition() Condition {
-	return Condition{Key: "delivery.stuck.mesh-mail", Subject: Scope{Scope: "module", ID: "mesh-mail"}, State: "cleared"}
-}
-
-func TestConditionRoundTrip(t *testing.T) { // 1202/AC2
-	for _, c := range []Condition{raisedCondition(), clearedCondition()} {
-		data, err := EncodeCondition(c)
-		if err != nil {
-			t.Fatalf("%s: %v", c.State, err)
-		}
-		var probe map[string]any
-		if err := json.Unmarshal(data, &probe); err != nil || probe["v"] != float64(1) {
-			t.Fatalf("%s: %s does not carry v:1", c.State, data)
-		}
-		c.V = ConditionVersion
-		got, err := DecodeCondition(data)
-		if err != nil || !SameCondition(got, c) {
-			t.Errorf("%s round trip: %+v %v", c.State, got, err)
-		}
-	}
-	data, _ := EncodeCondition(raisedCondition())
-	var probe map[string]any
-	_ = json.Unmarshal(data, &probe)
-	for _, name := range []string{"key", "severity", "subject", "summary", "headline", "needs", "explanation", "resolved", "actions", "state"} {
-		if _, ok := probe[name]; !ok {
-			t.Errorf("the JSON has no %q: %s", name, data)
-		}
-	}
-	subject := probe["subject"].(map[string]any)
-	for _, name := range []string{"scope", "id", "machine"} {
-		if _, ok := subject[name]; !ok {
-			t.Errorf("the subject has no %q: %s", name, data)
-		}
-	}
-	action := probe["actions"].([]any)[0].(map[string]any)
-	for _, name := range []string{"label", "verb", "machine", "arguments", "level"} {
-		if _, ok := action[name]; !ok {
-			t.Errorf("the action has no %q: %s", name, data)
-		}
-	}
-	for _, in := range []string{`{"key":"k"}`, `{"v":2,"key":"k"}`} {
-		if _, err := DecodeCondition([]byte(in)); !errors.Is(err, ErrUnknownConditionVersion) {
-			t.Errorf("decode of %s = %v, want ErrUnknownConditionVersion", in, err)
-		}
-	}
-}
-
-func TestConditionVerdict(t *testing.T) { // 1202/AC3
-	c := raisedCondition()
-	c.Needs, c.Explanation = "", "The plan waits."
-	_, err := EncodeCondition(c)
-	if err == nil || !strings.Contains(err.Error(), "Nothing for you to do.") {
-		t.Errorf("empty needs without its verdict: %v", err)
-	}
-	c.Explanation = "Nothing for you to do. The plan waits."
-	if _, err := EncodeCondition(c); err != nil {
-		t.Errorf("empty needs with its verdict refused: %v", err)
-	}
-	c = raisedCondition()
-	c.Explanation = "Nothing for you to do. The plan waits."
-	_, err = EncodeCondition(c)
-	if err == nil || !strings.Contains(err.Error(), "Needs you: approve the merge.") {
-		t.Errorf("needs set with the wrong verdict: %v", err)
-	}
-	c.Explanation = "Needs you: something else. The plan waits."
-	if _, err = EncodeCondition(c); err == nil {
-		t.Error("needs set with other needs in the verdict accepted")
-	}
-}
-
-func TestConditionRefused(t *testing.T) { // 1202/AC4
-	mutate := func(f func(*Condition)) error {
-		c := raisedCondition()
-		f(&c)
-		_, err := EncodeCondition(c)
-		return err
-	}
-	for name, f := range map[string]func(*Condition){
-		"severity":      func(c *Condition) { c.Severity = "critical" },
-		"state":         func(c *Condition) { c.State = "open" },
-		"key":           func(c *Condition) { c.Key = "" },
-		"headline":      func(c *Condition) { c.Headline = "" },
-		"long headline": func(c *Condition) { c.Headline = strings.Repeat("h", HeadlineLength+1) },
-	} {
-		if err := mutate(f); err == nil {
-			t.Errorf("a condition with a bad %s accepted", name)
-		}
-	}
-	if err := mutate(func(c *Condition) { c.Headline = strings.Repeat("h", HeadlineLength) }); err != nil {
-		t.Errorf("a headline of the greatest length refused: %v", err)
-	}
-	if _, err := EncodeCondition(clearedCondition()); err != nil {
-		t.Errorf("a cleared condition with only key, subject and state refused: %v", err)
-	}
-	c := clearedCondition()
-	c.Key = ""
-	if _, err := EncodeCondition(c); err == nil {
-		t.Error("a cleared condition without its key accepted")
-	}
-	c = clearedCondition()
-	c.State = "gone"
-	if _, err := EncodeCondition(c); err == nil {
-		t.Error("a condition with an unknown state accepted")
-	}
-}

go/buildcpu/buildcpu.go

@@ -1,215 +0,0 @@
-// Package buildcpu is how much of a build node's processors its builds may take, and how they yield to everything else
-// there (novox/hq ADR 0553, issue 1806; the operator, 2026-10-26: "limit CPU usage on our build nodes so the total cpu
-// usage never impacts the normal workings of our nodes ... We have 3 build agents so they should share the cpu power").
-//
-// Three parts, each with one owner:
-//
-//   - **Priority.** A build seat's holder (catalogue.Seat.Yields) runs at the lowest priority there is: the composer
-//     gives its runtime process declaration.Yields, and the node-engine places every yielding process of the node in
-//     one slice (declaration.YieldSlice) whose CPU weight is idle, with Nice=19 for every process it starts.
-//     Interactive and service work always comes first; builds take the cycles nothing else wants.
-//   - **One cap per node, shared.** The node's share of its processors is one value, the node-engine's own config
-//     `build-cpu-share` (ShareSetting), set per node through the node's settings layer. The node-engine writes it as the
-//     slice's CPUQuota: one bound the kernel holds for all the node's build modules together, never one per module.
-//   - **Threads.** The quota bounds the total; threads only size each step. A step gets the share divided by its own
-//     module's capacity (Threads), from the share the composer hands as a word (ShareWord): GOMAXPROCS sets every go
-//     command's -p, the compiler's concurrency, a test binary's processors and -parallel. A module given no word sets
-//     no thread limit at all: without the slice there is nothing to size a step to, and a limit then would only slow
-//     builds.
-package buildcpu
-
-import (
-	"os"
-	"runtime"
-	"strconv"
-	"strings"
-)
-
-// ShareSetting is the node-engine's config value of the node's processor share for its builds, in percent of the
-// machine's processors, 1 to 100: one value per node, set through the node's settings layer (novox/hq ADR 0553 §3).
-const ShareSetting = "build-cpu-share"
-
-// DefaultPercent is the share where nothing sets one: half the machine, so a desktop keeps half its processors for
-// itself whatever builds.
-const DefaultPercent = 50
-
-// ShareWord is the word the composer gives every yielding module (novox/hq ADR 0553 §4): the node's share, in percent.
-const ShareWord = "MESH_BUILD_CPU_SHARE"
-
-// Quota is a CPUQuota for a share of a machine with cores processors: systemd counts a quota in percent of one
-// processor, so half of 24 is 1200%. At least 100%, one processor, so a share on a small machine never stops a step.
-func Quota(percent, cores int) int {
-	q := percent * cores
-	if q < 100 {
-		q = 100
-	}
-	return q
-}
-
-// Threads is how many threads one step may run at once: its part of the share when its own module runs slots steps at
-// once, at least one. The slice's quota bounds the steps of all the node's build modules together; this only sizes one.
-func Threads(percent, cores, slots int) int {
-	if slots < 1 {
-		slots = 1
-	}
-	if percent < 1 || percent > 100 {
-		percent = DefaultPercent
-	}
-	t := cores * percent / 100 / slots
-	if t < 1 {
-		t = 1
-	}
-	return t
-}
-
-// Limits is what one step is held to on this node, as a status tool says it.
-type Limits struct {
-	// Percent is the node's share in percent of its processors, and From where it was read: ShareWord, or "none" when
-	// the composer gave no share and a step runs without a thread limit.
-	Percent int    `json:"share-percent,omitempty"`
-	From    string `json:"share-from"`
-	// Cores is the machine's processor count.
-	Cores int `json:"cores"`
-	// Slots is this module's own capacity on the node: steps at once.
-	Slots int `json:"slots"`
-	// Threads is what each step is given (Threads); 0 is no limit.
-	Threads int `json:"threads-per-step"`
-}
-
-// FromWords is the limits of a step from the share the composer gave this process (ShareWord) and the module's own
-// capacity. Without a usable share there is no limit: Threads is 0.
-func FromWords(getenv func(string) string, own int) Limits {
-	if own < 1 {
-		own = 1
-	}
-	l := Limits{From: "none", Cores: runtime.NumCPU(), Slots: own}
-	if n, err := strconv.Atoi(strings.TrimSpace(getenv(ShareWord))); err == nil && n >= 1 && n <= 100 {
-		l.Percent, l.From = n, ShareWord
-		l.Threads = Threads(n, l.Cores, own)
-	}
-	return l
-}
-
-// Env is the environment a step's commands are given so they start no more threads than they may: GOMAXPROCS for every
-// Go program (the compiler, a test binary, esbuild, buildah), UV_THREADPOOL_SIZE for Node's worker pool. Returned as
-// KEY=value words to append to a command's environment; nothing for 0 threads, no limit.
-func Env(threads int) []string {
-	if threads < 1 {
-		return nil
-	}
-	t := strconv.Itoa(threads)
-	return []string{"GOMAXPROCS=" + t, "UV_THREADPOOL_SIZE=" + t}
-}
-
-// InForce is what the kernel holds this process to, read rather than assumed (evidence over assertion): its nice
-// level, its cgroup (the unit) and the cgroup's parent (the slice the node-engine placed it in), each one's CPU weight,
-// idle mark and quota. A field the machine does not answer is left empty and Unread says which.
-//
-// The IO weight is read but binds only where the disk's scheduler honours it (bfq, or the io.cost controller); under
-// the scheduler `none`, the usual one for NVMe, it does nothing, and the CPU bound is what holds.
-type InForce struct {
-	Nice   int    `json:"nice"`
-	Cgroup string `json:"cgroup,omitempty"`
-	Unit   Group  `json:"unit"`
-	Slice  Group  `json:"slice"`
-	// Quota is the tighter of the two groups' cpu.max as a percent of one processor, 0 with none.
-	Quota  int      `json:"quota-percent,omitempty"`
-	Unread []string `json:"unread,omitempty"`
-}
-
-// Group is one cgroup's controls.
-type Group struct {
-	Path      string `json:"path,omitempty"`
-	CPUIdle   string `json:"cpu-idle,omitempty"`
-	CPUWeight string `json:"cpu-weight,omitempty"`
-	// CPUMax is the cgroup's cpu.max: "<quota µs> <period µs>", or "max" with no quota.
-	CPUMax   string `json:"cpu-max,omitempty"`
-	IOWeight string `json:"io-weight,omitempty"`
-}
-
-// cgroupRoot is where the unified hierarchy is mounted. A variable so a test can point it elsewhere.
-var cgroupRoot = "/sys/fs/cgroup"
-
-// procSelfCgroup is this process's cgroup file. A variable so a test can point it elsewhere.
-var procSelfCgroup = "/proc/self/cgroup"
-
-// procSelfStat is this process's stat file. A variable so a test can point it elsewhere.
-var procSelfStat = "/proc/self/stat"
-
-// ReadInForce reads what the kernel holds this process to.
-func ReadInForce() InForce {
-	var f InForce
-	f.Nice = nice()
-	raw, err := os.ReadFile(procSelfCgroup)
-	if err != nil {
-		f.Unread = append(f.Unread, "cgroup: "+err.Error())
-		return f
-	}
-	for _, line := range strings.Split(strings.TrimSpace(string(raw)), "\n") {
-		if strings.HasPrefix(line, "0::") {
-			f.Cgroup = strings.TrimPrefix(line, "0::")
-		}
-	}
-	if f.Cgroup == "" {
-		f.Unread = append(f.Unread, "cgroup: not on the unified hierarchy")
-		return f
-	}
-	read := func(path string) Group {
-		g := Group{Path: path}
-		value := func(name string) string {
-			b, err := os.ReadFile(cgroupRoot + path + "/" + name)
-			if err != nil {
-				f.Unread = append(f.Unread, path+"/"+name+": "+err.Error())
-				return ""
-			}
-			return strings.TrimSpace(string(b))
-		}
-		g.CPUIdle, g.CPUWeight, g.CPUMax, g.IOWeight = value("cpu.idle"), value("cpu.weight"), value("cpu.max"), value("io.weight")
-		return g
-	}
-	f.Unit = read(f.Cgroup)
-	if i := strings.LastIndex(f.Cgroup, "/"); i > 0 {
-		f.Slice = read(f.Cgroup[:i])
-	}
-	for _, q := range []int{quotaOf(f.Unit.CPUMax), quotaOf(f.Slice.CPUMax)} {
-		if q > 0 && (f.Quota == 0 || q < f.Quota) {
-			f.Quota = q
-		}
-	}
-	return f
-}
-
-// quotaOf is a cpu.max value as a percent of one processor: "1200000 100000" is 1200; "max ..." or nothing is 0.
-func quotaOf(cpuMax string) int {
-	fields := strings.Fields(cpuMax)
-	if len(fields) != 2 || fields[0] == "max" {
-		return 0
-	}
-	q, err1 := strconv.Atoi(fields[0])
-	p, err2 := strconv.Atoi(fields[1])
-	if err1 != nil || err2 != nil || p <= 0 {
-		return 0
-	}
-	return q * 100 / p
-}
-
-// nice is this process's nice level from its stat file (the 19th field, counted after the command's closing
-// parenthesis, which may itself hold spaces); 0 when it cannot be read.
-func nice() int {
-	raw, err := os.ReadFile(procSelfStat)
-	if err != nil {
-		return 0
-	}
-	s := string(raw)
-	i := strings.LastIndex(s, ")")
-	if i < 0 {
-		return 0
-	}
-	fields := strings.Fields(s[i+1:])
-	// After the command: state is field 3, so nice (field 19) is index 16.
-	if len(fields) < 17 {
-		return 0
-	}
-	n, _ := strconv.Atoi(fields[16])
-	return n
-}

go/buildcpu/buildcpu_test.go

@@ -1,90 +0,0 @@
-package buildcpu
-
-import (
-	"os"
-	"path/filepath"
-	"reflect"
-	"runtime"
-	"testing"
-)
-
-// The node's share as a quota, the threads one step is given for its own module's capacity, and the word the composer
-// hands, in one table (ADR 0553, issue 1806).
-func TestShareQuotaAndThreads(t *testing.T) {
-	for _, c := range []struct {
-		name                  string
-		percent, cores, slots int
-		quota, threads        int
-	}{
-		{"shanks: half of 24, three slots", 50, 24, 3, 1200, 4},
-		{"ace: three quarters of 24, two slots", 75, 24, 2, 1800, 9},
-		{"g14: half of 16, one slot", 50, 16, 1, 800, 8},
-		{"one processor at least", 10, 2, 4, 100, 1},
-		{"no slots counts as one", 100, 4, 0, 400, 4},
-		{"a share out of range is the default", 0, 8, 1, 0, 4},
-	} {
-		if c.quota != 0 {
-			if q := Quota(c.percent, c.cores); q != c.quota {
-				t.Errorf("%s: Quota = %d, want %d", c.name, q, c.quota)
-			}
-		}
-		if th := Threads(c.percent, c.cores, c.slots); th != c.threads {
-			t.Errorf("%s: Threads = %d, want %d", c.name, th, c.threads)
-		}
-	}
-	l := FromWords(func(k string) string { return map[string]string{ShareWord: "75"}[k] }, 2)
-	if l.Percent != 75 || l.From != ShareWord || l.Slots != 2 || l.Threads != Threads(75, runtime.NumCPU(), 2) {
-		t.Errorf("from the word: %+v", l)
-	}
-	// Told nothing usable, a step has no thread limit: nothing in its environment.
-	for _, word := range []string{"", "250", "lots"} {
-		l := FromWords(func(string) string { return word }, 3)
-		if l.Threads != 0 || l.From != "none" || Env(l.Threads) != nil {
-			t.Errorf("share %q: %+v, env %v", word, l, Env(l.Threads))
-		}
-	}
-	if got := Env(3); !reflect.DeepEqual(got, []string{"GOMAXPROCS=3", "UV_THREADPOOL_SIZE=3"}) {
-		t.Errorf("Env = %q", got)
-	}
-}
-
-// What the kernel holds a process to is read from its unit's and its slice's cgroup and its stat file, not assumed.
-func TestReadInForce(t *testing.T) {
-	dir := t.TempDir()
-	cg := filepath.Join(dir, "cg")
-	slice := filepath.Join(cg, "meshyield.slice")
-	unit := filepath.Join(slice, "mesh-build-go-runtime.service")
-	if err := os.MkdirAll(unit, 0o755); err != nil {
-		t.Fatal(err)
-	}
-	for at, files := range map[string]map[string]string{
-		slice: {"cpu.idle": "1\n", "cpu.weight": "0\n", "cpu.max": "1200000 100000\n", "io.weight": "default 1\n"},
-		unit:  {"cpu.idle": "0\n", "cpu.weight": "100\n", "cpu.max": "max 100000\n", "io.weight": "default 100\n"},
-	} {
-		for name, v := range files {
-			if err := os.WriteFile(filepath.Join(at, name), []byte(v), 0o644); err != nil {
-				t.Fatal(err)
-			}
-		}
-	}
-	self := filepath.Join(dir, "cgroup")
-	stat := filepath.Join(dir, "stat")
-	_ = os.WriteFile(self, []byte("0::/meshyield.slice/mesh-build-go-runtime.service\n"), 0o644)
-	// A command with a space and a parenthesis in it, then nice 19 in field 19.
-	_ = os.WriteFile(stat, []byte("42 (mesh (build) go) S 1 42 42 0 -1 4194560 1 0 0 0 0 0 0 0 39 19 8 0 1 2 3\n"), 0o644)
-	cgroupRoot, procSelfCgroup, procSelfStat = cg, self, stat
-	t.Cleanup(func() {
-		cgroupRoot, procSelfCgroup, procSelfStat = "/sys/fs/cgroup", "/proc/self/cgroup", "/proc/self/stat"
-	})
-
-	got := ReadInForce()
-	want := InForce{Nice: 19, Cgroup: "/meshyield.slice/mesh-build-go-runtime.service",
-		Unit: Group{Path: "/meshyield.slice/mesh-build-go-runtime.service", CPUIdle: "0", CPUWeight: "100",
-			CPUMax: "max 100000", IOWeight: "default 100"},
-		Slice: Group{Path: "/meshyield.slice", CPUIdle: "1", CPUWeight: "0", CPUMax: "1200000 100000",
-			IOWeight: "default 1"},
-		Quota: 1200}
-	if !reflect.DeepEqual(got, want) {
-		t.Fatalf("ReadInForce = %+v\nwant %+v", got, want)
-	}
-}

go/buildstep/askrun.go

@@ -1,437 +0,0 @@
-package buildstep
-
-import (
-	"context"
-	"encoding/json"
-	"fmt"
-	"path"
-	"slices"
-	"sort"
-	"strings"
-
-	"git.novox.be/novox/mesh-sdk/go/delivery"
-)
-
-// **One ask, one whole job** (novox/hq ADR 0525 §3). A build module runs a pulled ask with its own step tools' bodies,
-// the same ones its request and reply tools run (ADR 0525 §8), in the order the job names: a build ask fetches, then
-// builds or copies each artifact; a check ask fetches, digests the level, takes the kept verdicts and tests the rest,
-// the packages whose tests the change touches first. The answers are the tools' own, whole, so the asker judges them as
-// it judged the tools' answers.
-
-// StepFunc is one step tool's body: its arguments in, its answer out.
-type StepFunc func(ctx context.Context, args map[string]any) (any, error)
-
-// AskSteps are the step tools a build module runs an ask with. Copy is the image module's alone; Digest the Go module's.
-type AskSteps struct {
-	Fetch, Build, Copy, Digest, Test StepFunc
-	// Toolchain is the toolchain the module builds with now; a build ask naming another is refused. Nil checks nothing
-	// (an image or an archive names none).
-	Toolchain func(ctx context.Context) (delivery.ToolchainUsed, error)
-	// Kept looks up a kept verdict by level and digest (the checker's kept bucket, delivery.KeptKey): whether one is
-	// kept and how many tests it counted. Nil takes none.
-	Kept func(ctx context.Context, level, digest string) (tests int, found bool, err error)
-	// Release removes a workspace once the ask's steps on it ended (the module's release tool's body); nil leaves it to
-	// the module's sweep.
-	Release func(workspace string) error
-	Logf    func(format string, args ...any)
-	// Has says whether this node has a need a package's tests declare (delivery.AskNeeds, issue 890); a package needing
-	// what it lacks is not tested here but named in the level's Unmet, for the asker to place. Nil has nothing.
-	Has func(need string) bool
-}
-
-// RunAsk runs ask's job with steps and answers a delivery.BuildAnswer or a delivery.CheckAnswer.
-func RunAsk(ctx context.Context, steps AskSteps, ask delivery.StepAsk) (any, error) {
-	if ask.Build != nil {
-		return steps.build(ctx, *ask.Build)
-	}
-	if ask.Check != nil {
-		return steps.check(ctx, *ask.Check)
-	}
-	return nil, Refuse("the ask %s holds no job", ask.ID)
-}
-
-func raw(v any) (json.RawMessage, error) {
-	if r, ok := v.(json.RawMessage); ok {
-		return r, nil
-	}
-	return json.Marshal(v)
-}
-
-// fetched is what an ask reads of a fetch's answer.
-type fetched struct {
-	Workspace string   `json:"workspace"`
-	Merge     string   `json:"merge"`
-	Conflicts []string `json:"conflicts"`
-	Changed   []string `json:"changed"`
-	Modules   []string `json:"modules"`
-}
-
-func (s AskSteps) fetch(ctx context.Context, args map[string]any) (json.RawMessage, fetched, error) {
-	if s.Fetch == nil {
-		return nil, fetched{}, Refuse("this build module fetches nothing")
-	}
-	if _, merges := args["base"]; merges {
-		Phase(ctx, "fetch and merge")
-	} else {
-		Phase(ctx, "fetch")
-	}
-	out, err := s.Fetch(ctx, args)
-	if err != nil {
-		return nil, fetched{}, err
-	}
-	r, err := raw(out)
-	if err != nil {
-		return nil, fetched{}, err
-	}
-	var f fetched
-	if err := json.Unmarshal(r, &f); err != nil || f.Workspace == "" {
-		return r, f, fmt.Errorf("the fetch answered no workspace: %s", r)
-	}
-	return r, f, nil
-}
-
-func (s AskSteps) build(ctx context.Context, job delivery.BuildJob) (any, error) {
-	answer := delivery.BuildAnswer{}
-	if job.Toolchain != nil && s.Toolchain != nil {
-		tc, err := s.Toolchain(ctx)
-		if err != nil {
-			return nil, err
-		}
-		if tc.Version != job.Toolchain.Version || tc.Recipe != job.Toolchain.Recipe {
-			return nil, Refuse("the ask is for %s (recipe %s) and this node builds with %s (recipe %s)",
-				job.Toolchain.Version, job.Toolchain.Recipe, tc.Version, tc.Recipe)
-		}
-		answer.Toolchain = &tc
-	}
-	var f fetched
-	defer func() { s.release(f.Workspace) }()
-	for _, a := range job.Artifacts {
-		if a.From == "" && f.Workspace == "" {
-			r, got, err := s.fetch(ctx, job.Fetch)
-			if err != nil {
-				return nil, err
-			}
-			if _, candidate := job.Fetch["base"]; candidate {
-				// A candidate is built from its head merged onto the trunk; a head that does not merge leaves the tree at the
-				// trunk, and building that would store the trunk's build under the candidate's fingerprint.
-				if len(got.Conflicts) > 0 {
-					return nil, fmt.Errorf("the head does not merge into the trunk: files in conflict: %s", strings.Join(got.Conflicts, ", "))
-				}
-				if got.Merge == "" {
-					return nil, fmt.Errorf("the fetch with a base answered no merge: %s", r)
-				}
-			}
-			f = got
-		}
-		var (
-			out any
-			err error
-		)
-		if a.From != "" {
-			if s.Copy == nil {
-				return nil, Refuse("this build module copies no artifact (%s)", a.Artifact)
-			}
-			Phase(ctx, "copy "+a.Artifact)
-			out, err = s.Copy(ctx, map[string]any{"module": job.Module, "artifact": a.Artifact, "from": a.From})
-		} else {
-			if s.Build == nil {
-				return nil, Refuse("this build module builds no artifact (%s)", a.Artifact)
-			}
-			args := map[string]any{"workspace": f.Workspace, "module": job.Path, "artifact": a.Artifact}
-			if job.Publish {
-				args["publish"] = true
-			}
-			Phase(ctx, "build "+a.Artifact)
-			out, err = s.Build(ctx, args)
-		}
-		if err != nil {
-			return nil, fmt.Errorf("%s: %w", a.Artifact, err)
-		}
-		r, err := raw(out)
-		if err != nil {
-			return nil, err
-		}
-		var built struct {
-			Digest    string `json:"digest"`
-			Reference string `json:"reference"`
-		}
-		if err := json.Unmarshal(r, &built); err != nil || built.Digest == "" {
-			return nil, fmt.Errorf("the build of %s answered no digest: %s", a.Artifact, r)
-		}
-		answer.Artifacts = append(answer.Artifacts, delivery.AskBuilt{Artifact: a.Artifact, Digest: built.Digest, Reference: built.Reference})
-	}
-	return answer, nil
-}
-
-func (s AskSteps) check(ctx context.Context, job delivery.CheckJob) (any, error) {
-	r, f, err := s.fetch(ctx, job.Fetch)
-	if err != nil {
-		return nil, err
-	}
-	defer s.release(f.Workspace)
-	answer := delivery.CheckAnswer{Fetch: r}
-	if len(f.Conflicts) > 0 {
-		return answer, nil // the asker reads the conflict from the fetch's answer: a verdict, not an error
-	}
-	if s.Test == nil {
-		return nil, Refuse("this build module tests nothing")
-	}
-	runner := ""
-	if job.Runner != "" && (job.RunnerWhen == "" || changesUnder(f.Changed, job.RunnerWhen)) {
-		runner = job.Runner
-	}
-	for _, level := range job.Levels {
-		la := delivery.LevelAnswer{Level: level}
-		passed, err := s.level(ctx, job, level, f, runner, &la)
-		answer.Levels = append(answer.Levels, la)
-		if err != nil {
-			return nil, err
-		}
-		if !passed {
-			return answer, nil // the first level that did not pass ends the check (ADR 0484 clause 13)
-		}
-	}
-	return answer, nil
-}
-
-// level runs one level of a check ask and says whether it passed.
-func (s AskSteps) level(ctx context.Context, job delivery.CheckJob, level string, f fetched, runner string, la *delivery.LevelAnswer) (bool, error) {
-	withRunner := func(args map[string]any) map[string]any {
-		if runner != "" {
-			args["runner"] = runner
-		}
-		return args
-	}
-	test := func(args map[string]any) (bool, error) {
-		what := "the whole level"
-		if dir, _ := args["module"].(string); dir != "" {
-			what = dir
-		} else if pkgs, _ := args["packages"].([]string); len(pkgs) > 0 {
-			what = fmt.Sprintf("%d packages", len(pkgs))
-		}
-		Phase(ctx, fmt.Sprintf("%s: tests of %s", level, what))
-		out, err := s.Test(ctx, args)
-		if err != nil {
-			return false, err
-		}
-		r, err := raw(out)
-		if err != nil {
-			return false, err
-		}
-		la.Tests = append(la.Tests, r)
-		var t struct {
-			Passed bool `json:"passed"`
-		}
-		_ = json.Unmarshal(r, &t)
-		return t.Passed, nil
-	}
-	// Every test step of the level runs, also after one that did not pass, so one check names every failing test of the
-	// level and not only the first (issue 1921); the level as a whole passes only when each of its steps did.
-	all := true
-	if s.Digest == nil {
-		// A module with no digest (Node) tests each module directory of the tree, those whose tests changed first.
-		for _, priority := range []bool{true, false} {
-			for _, dir := range f.Modules {
-				if changesTestIn(f.Changed, dir) != priority {
-					continue
-				}
-				passed, err := test(withRunner(map[string]any{"workspace": f.Workspace, "module": dir, "level": level}))
-				if err != nil {
-					return false, fmt.Errorf("the %s level of %s: %w", level, dir, err)
-				}
-				all = all && passed
-			}
-		}
-		return all, nil
-	}
-	todo, whole, keepRunner := s.plan(ctx, job, level, f, runner, withRunner, la)
-	if !keepRunner {
-		runner = "" // an installed module that ignores the runner judges the level as it judges any other (ADR 0535 §2)
-	}
-	if whole && len(job.Packages) > 0 {
-		todo, whole = job.Packages, false // a placed ask tests its packages alone, whatever the digest said (ADR 0552 §4)
-	}
-	for _, priority := range []bool{true, false} {
-		args := withRunner(map[string]any{"workspace": f.Workspace, "level": level})
-		if job.Run != "" {
-			args["run"] = job.Run
-		}
-		if whole {
-			if priority {
-				continue // nothing to put first: the level runs whole after
-			}
-		} else {
-			var run []string
-			for _, p := range todo {
-				if changesTestOf(f.Changed, p) == priority {
-					run = append(run, p)
-				}
-			}
-			if len(run) == 0 {
-				continue
-			}
-			args["packages"] = run
-		}
-		passed, err := test(args)
-		if err != nil {
-			return false, fmt.Errorf("the %s level: %w", level, err)
-		}
-		all = all && passed // the packages left still run (issue 1921)
-	}
-	return all, nil
-}
-
-// release removes an ask's workspace, saying a failure: the module's sweep removes it later.
-func (s AskSteps) release(workspace string) {
-	if workspace == "" || s.Release == nil {
-		return
-	}
-	if err := s.Release(workspace); err != nil && s.Logf != nil {
-		s.Logf("the workspace %s is left to the sweep: %v", workspace, err)
-	}
-}
-
-// plan digests the level and takes the kept verdicts: the packages left to test, or all when the level runs whole, and
-// whether the runner stays. A try of some tests runs whole, digesting nothing (a partial run proves no package). Under the
-// candidate's runner the digest is asked as the candidate: when the candidate answers it, every package runs and nothing
-// is digested for keeping (ADR 0535 §4); when the installed module answers it (it does not take the runner), the level is
-// planned as any other and the runner is dropped. The level runs whole and takes nothing when the digest names no package
-// or does not cover the siblings the fetch placed (ADR 0444, L5).
-func (s AskSteps) plan(ctx context.Context, job delivery.CheckJob, level string, f fetched, runner string, withRunner func(map[string]any) map[string]any, la *delivery.LevelAnswer) ([]string, bool, bool) {
-	if job.Run != "" {
-		return nil, true, true
-	}
-	Phase(ctx, level+": digest")
-	out, err := s.Digest(ctx, withRunner(map[string]any{"workspace": f.Workspace, "level": level}))
-	if err != nil {
-		if s.Logf != nil {
-			s.Logf("no digest of the %s level, so it runs whole: %v", level, err)
-		}
-		return nil, true, true
-	}
-	r, err := raw(out)
-	if err != nil {
-		return nil, true, true
-	}
-	var d delivery.LevelDigest // packages kept as a sorted list, never keyed by a package path (issue 1930)
-	if err := json.Unmarshal(r, &d); err != nil {
-		return nil, true, true
-	}
-	if runner != "" {
-		if strings.HasPrefix(d.JudgedBy, "candidate ") {
-			la.Judged = d.JudgedBy
-			return nil, true, true // the candidate decides which verdicts would be taken: all run, nothing kept
-		}
-		runner = ""
-	}
-	if len(d.Packages) == 0 || !slices.Equal(d.Beside, besideOf(job.Fetch)) {
-		return nil, true, runner != "" // a digest that names nothing or not the siblings keys no verdict: the level runs whole
-	}
-	la.Digest = &d
-	only := map[string]bool{}
-	for _, p := range job.Packages {
-		only[p] = true
-	}
-	var todo []string
-	for _, pd := range d.Packages {
-		p := pd.Package
-		if len(only) > 0 && !only[p] {
-			continue // a placed ask's other packages were judged by the first ask (ADR 0552 §4)
-		}
-		if job.Kept && s.Kept != nil {
-			tests, found, err := s.Kept(ctx, level, pd.Digest)
-			if err != nil && s.Logf != nil {
-				s.Logf("the kept verdict of %s at %s cannot be read, so it runs: %v", p, level, err)
-			}
-			if err == nil && found {
-				la.Kept = append(la.Kept, delivery.KeptTaken{Package: p, Digest: pd.Digest, Tests: tests})
-				continue
-			}
-		}
-		if needs := d.NeedsOf(p); len(delivery.Lacks(needs, s.Has)) > 0 {
-			// Its tests would only skip here (issue 890): it is left for a node that has what they need.
-			la.Unmet = append(la.Unmet, delivery.PackageNeeds{Package: p, Needs: needs})
-			if s.Logf != nil {
-				s.Logf("the %s level of %s is left to a node with %s: this node lacks %s", level, p,
-					strings.Join(needs, ", "), strings.Join(delivery.Lacks(needs, s.Has), ", "))
-			}
-			continue
-		}
-		todo = append(todo, p)
-	}
-	return todo, false, false
-}
-
-// besideOf are the siblings a fetch's arguments place, as a digest echoes them: `<owner/repo> <commit>`, sorted.
-func besideOf(fetch map[string]any) []string {
-	raw, err := json.Marshal(fetch["beside"])
-	if err != nil {
-		return nil
-	}
-	var refs []struct {
-		Repository string `json:"repository"`
-		Commit     string `json:"commit"`
-	}
-	_ = json.Unmarshal(raw, &refs)
-	var out []string
-	for _, r := range refs {
-		out = append(out, r.Repository+" "+r.Commit)
-	}
-	sort.Strings(out)
-	return out
-}
-
-// changesUnder says whether a path the merge changes is under prefix.
-func changesUnder(changed []string, prefix string) bool {
-	for _, p := range changed {
-		if strings.HasPrefix(p, prefix) {
-			return true
-		}
-	}
-	return false
-}
-
-// isTestFile says whether a repository-relative path is a test file: Go's _test.go, and a TypeScript module's .test.
-// and .spec. files and test directories.
-func isTestFile(p string) bool {
-	switch {
-	case strings.HasSuffix(p, "_test.go"):
-		return true
-	case strings.Contains(p, ".test.") || strings.Contains(p, ".spec."):
-		return true
-	}
-	for _, seg := range strings.Split(path.Dir(p), "/") {
-		if seg == "__tests__" || seg == "test" || seg == "tests" {
-			return true
-		}
-	}
-	return false
-}
-
-// changesTestOf says whether the merge changes a test file of the Go package with the import path pkg: the file's
-// directory and the import path agree on their last segments.
-func changesTestOf(changed []string, pkg string) bool {
-	for _, f := range changed {
-		if !strings.HasSuffix(f, "_test.go") {
-			continue
-		}
-		dir := path.Dir(f)
-		if dir == pkg || strings.HasSuffix(pkg, "/"+dir) || strings.HasSuffix(dir, "/"+pkg) {
-			return true
-		}
-	}
-	return false
-}
-
-// changesTestIn says whether the merge changes a test file inside the directory of a Node module.
-func changesTestIn(changed []string, dir string) bool {
-	for _, f := range changed {
-		if !isTestFile(f) || strings.HasSuffix(f, "_test.go") {
-			continue
-		}
-		if dir == "." || dir == "" || strings.HasPrefix(f, strings.TrimSuffix(dir, "/")+"/") {
-			return true
-		}
-	}
-	return false
-}

go/buildstep/askrun_test.go

@@ -1,285 +0,0 @@
-package buildstep
-
-import (
-	"context"
-	"encoding/json"
-	"errors"
-	"fmt"
-	"strings"
-	"testing"
-	"time"
-
-	"git.novox.be/novox/mesh-sdk/go/delivery"
-)
-
-const runCommit = "0123456789abcdef0123456789abcdef01234567"
-
-// recorder is a build module's step tools that record each call.
-type recorder struct {
-	calls   []string
-	fetch   map[string]any
-	tests   map[string]bool // package or module directory -> passed
-	digests map[string]string
-	needs   []delivery.PackageNeeds
-}
-
-func (r *recorder) steps() AskSteps {
-	call := func(name string, answer func(args map[string]any) any) StepFunc {
-		return func(ctx context.Context, args map[string]any) (any, error) {
-			b, _ := json.Marshal(args)
-			r.calls = append(r.calls, name+" "+string(b))
-			return answer(args), nil
-		}
-	}
-	return AskSteps{
-		Fetch: call("fetch", func(map[string]any) any { return r.fetch }),
-		Build: call("build", func(args map[string]any) any {
-			return map[string]any{"digest": "sha256:" + args["artifact"].(string), "reference": "artifact-store://" + args["artifact"].(string)}
-		}),
-		Copy: call("copy", func(args map[string]any) any { return map[string]any{"digest": "sha256:copied"} }),
-		Digest: call("digest", func(map[string]any) any {
-			return map[string]any{"level": "unit", "packages": r.digests, "needs": r.needs}
-		}),
-		Test: call("test", func(args map[string]any) any {
-			passed := true
-			if pkgs, ok := args["packages"].([]string); ok {
-				for _, p := range pkgs {
-					passed = passed && r.tests[p]
-				}
-			}
-			if dir, ok := args["module"].(string); ok {
-				passed = r.tests[dir]
-			}
-			return map[string]any{"passed": passed, "tests": 1}
-		}),
-		Kept: func(ctx context.Context, level, digest string) (int, bool, error) { return 7, digest == "d-kept", nil },
-	}
-}
-
-func ask(job any) delivery.StepAsk {
-	a := delivery.StepAsk{ID: NewID(), Kind: delivery.AskCheck, Language: delivery.AskGo, Asker: "t", At: time.Now()}
-	switch j := job.(type) {
-	case delivery.BuildJob:
-		a.Build = &j
-	case delivery.CheckJob:
-		a.Check = &j
-	}
-	return a
-}
-
-// 1887/A3: a build ask fetches once, builds each artifact from the workspace with publish, copies a pinned one without a
-// fetch, and answers each artifact's digest and reference.
-func TestRunAskBuilds(t *testing.T) {
-	r := &recorder{fetch: map[string]any{"workspace": "/w/1"}}
-	steps := r.steps()
-	var released []string
-	steps.Release = func(ws string) error { released = append(released, ws); return nil }
-	out, err := RunAsk(context.Background(), steps, ask(delivery.BuildJob{Module: "m", Path: "modules/m", Publish: true,
-		Fetch:     map[string]any{"repository": "novox/x", "commit": runCommit},
-		Artifacts: []delivery.AskArtifact{{Artifact: "base", From: "registry/b@sha256:00"}, {Artifact: "bundle"}, {Artifact: "lib"}}}))
-	if err != nil {
-		t.Fatal(err)
-	}
-	got := strings.Join(r.calls, "\n")
-	want := `copy {"artifact":"base","from":"registry/b@sha256:00","module":"m"}
-fetch {"commit":"` + runCommit + `","repository":"novox/x"}
-build {"artifact":"bundle","module":"modules/m","publish":true,"workspace":"/w/1"}
-build {"artifact":"lib","module":"modules/m","publish":true,"workspace":"/w/1"}`
-	if got != want {
-		t.Fatalf("calls:\n%s\nwant:\n%s", got, want)
-	}
-	if len(released) != 1 || released[0] != "/w/1" {
-		t.Errorf("released %v, want the one workspace", released)
-	}
-	a := out.(delivery.BuildAnswer)
-	if len(a.Artifacts) != 3 || a.Artifacts[1].Reference != "artifact-store://bundle" {
-		t.Fatalf("answer %+v", a)
-	}
-}
-
-// A build ask for another toolchain is refused, so its step ends refused and the asker reads why.
-func TestRunAskRefusesAnotherToolchain(t *testing.T) {
-	r := &recorder{fetch: map[string]any{"workspace": "/w"}}
-	s := r.steps()
-	s.Toolchain = func(context.Context) (delivery.ToolchainUsed, error) {
-		return delivery.ToolchainUsed{Version: "go1.27", Recipe: "3"}, nil
-	}
-	_, err := RunAsk(context.Background(), s, ask(delivery.BuildJob{Module: "m", Path: ".", Fetch: map[string]any{"repository": "novox/x", "commit": runCommit},
-		Artifacts: []delivery.AskArtifact{{Artifact: "bundle"}}, Toolchain: &delivery.ToolchainUsed{Version: "go1.26", Recipe: "3"}}))
-	var ref *Refusal
-	if !errors.As(err, &ref) || len(r.calls) != 0 {
-		t.Fatalf("err %v, calls %v", err, r.calls)
-	}
-}
-
-// 1887/A3, A5a: a check ask runs the levels of one check after one fetch: it digests the unit level, takes the kept
-// verdicts, tests the packages whose tests changed first, then the rest also after a failure (issue 1921), and runs no
-// level after one that did not pass (ADR 0484 clause 13).
-func TestRunAskChecksTheLevelsOfOneCheck(t *testing.T) {
-	r := &recorder{
-		fetch:   map[string]any{"workspace": "/w", "changed": []string{"pkg/b/b_test.go"}},
-		digests: map[string]string{"x/pkg/a": "d-a", "x/pkg/b": "d-b", "x/pkg/k": "d-kept"},
-		tests:   map[string]bool{"x/pkg/a": true, "x/pkg/b": false},
-	}
-	out, err := RunAsk(context.Background(), r.steps(), ask(delivery.CheckJob{Levels: []string{delivery.LevelUnit, delivery.LevelIntegration}, Kept: true,
-		Runner: "workspace", RunnerWhen: "modules/mesh-build-go/", Fetch: map[string]any{"repository": "novox/x", "commit": runCommit, "base": runCommit}}))
-	if err != nil {
-		t.Fatal(err)
-	}
-	got := strings.Join(r.calls, "\n")
-	want := `fetch {"base":"` + runCommit + `","commit":"` + runCommit + `","repository":"novox/x"}
-digest {"level":"unit","workspace":"/w"}
-test {"level":"unit","packages":["x/pkg/b"],"workspace":"/w"}
-test {"level":"unit","packages":["x/pkg/a"],"workspace":"/w"}`
-	if got != want {
-		t.Fatalf("calls:\n%s\nwant:\n%s", got, want)
-	}
-	a := out.(delivery.CheckAnswer)
-	if len(a.Levels) != 1 {
-		t.Fatalf("levels %+v, want the unit level alone", a.Levels)
-	}
-	u := a.Levels[0]
-	if u.Level != delivery.LevelUnit || len(u.Kept) != 1 || u.Kept[0].Package != "x/pkg/k" || u.Kept[0].Tests != 7 || len(u.Tests) != 2 || u.Digest == nil {
-		t.Fatalf("the unit level %+v", u)
-	}
-
-	// Issue 890/AC2: a package declaring node-build-node is not tested on a node that lacks it but named unmet, and is
-	// tested on a node that has it.
-	for _, has := range []bool{false, true} {
-		r.calls, r.tests["x/pkg/b"] = nil, true
-		r.needs = []delivery.PackageNeeds{{Package: "x/pkg/a", Needs: []string{delivery.NeedNodeBuildNode}}}
-		steps := r.steps()
-		if has {
-			steps.Has = func(n string) bool { return n == delivery.NeedNodeBuildNode }
-		}
-		out, err := RunAsk(context.Background(), steps, ask(delivery.CheckJob{Levels: []string{delivery.LevelUnit}, Kept: true,
-			Fetch: map[string]any{"repository": "novox/x", "commit": runCommit}}))
-		if err != nil {
-			t.Fatal(err)
-		}
-		u := out.(delivery.CheckAnswer).Levels[0]
-		tested := strings.Contains(strings.Join(r.calls, "\n"), `"x/pkg/a"`)
-		if tested != has || (len(u.Unmet) == 0) == !has || (!has && (u.Unmet[0].Package != "x/pkg/a" || delivery.UnmetNeeds([]delivery.LevelAnswer{u})[0] != delivery.NeedNodeBuildNode)) {
-			t.Fatalf("has %v: tested x/pkg/a %v, unmet %+v, calls %v", has, tested, u.Unmet, r.calls)
-		}
-	}
-	// A placed ask naming its packages tests those alone and takes no other's kept verdict, also when the level would
-	// run whole (ADR 0552 §4).
-	for _, digests := range []map[string]string{r.digests, nil} {
-		r.calls, r.digests = nil, digests
-		steps := r.steps()
-		steps.Has = func(string) bool { return true }
-		out, err := RunAsk(context.Background(), steps, ask(delivery.CheckJob{Levels: []string{delivery.LevelUnit}, Kept: true, Packages: []string{"x/pkg/a"},
-			Fetch: map[string]any{"repository": "novox/x", "commit": runCommit}}))
-		if err != nil {
-			t.Fatal(err)
-		}
-		u := out.(delivery.CheckAnswer).Levels[0]
-		if last := r.calls[len(r.calls)-1]; !strings.HasSuffix(last, `"packages":["x/pkg/a"],"workspace":"/w"}`) || len(u.Kept) != 0 || len(u.Tests) != 1 {
-			t.Fatalf("digests %v: calls %v, kept %+v: want x/pkg/a alone tested, nothing taken kept", digests != nil, r.calls, u.Kept)
-		}
-	}
-}
-
-// ADR 0535 §2, §4: a merge that changes the build module's own code is judged by the candidate's runner: its digest says
-// the candidate ran, and every package runs with nothing kept; an installed module that ignores the runner is planned as
-// any other, the runner dropped. A digest that does not cover the fetch's siblings runs the level whole too.
-func TestRunAskRunsWholeUnderTheRunnerOrWithoutTheSiblings(t *testing.T) {
-	for _, tc := range []struct{ judged, want string }{
-		{"candidate 999", `digest {"level":"unit","runner":"workspace","workspace":"/w"}
-test {"level":"unit","runner":"workspace","workspace":"/w"}`},
-		{"installed", `digest {"level":"unit","runner":"workspace","workspace":"/w"}`},
-	} {
-		r := &recorder{fetch: map[string]any{"workspace": "/w", "changed": []string{"modules/mesh-build-go/x.go"}},
-			digests: map[string]string{"x/pkg/a": "d-kept"}, tests: map[string]bool{}}
-		steps := r.steps()
-		digest := steps.Digest
-		steps.Digest = func(ctx context.Context, args map[string]any) (any, error) {
-			_, _ = digest(ctx, args)
-			return map[string]any{"level": "unit", "packages": r.digests, "judged_by": tc.judged}, nil
-		}
-		out, err := RunAsk(context.Background(), steps, ask(delivery.CheckJob{Levels: []string{delivery.LevelUnit}, Kept: true,
-			Runner: "workspace", RunnerWhen: "modules/mesh-build-go/", Fetch: map[string]any{"repository": "novox/x", "commit": runCommit}}))
-		if err != nil {
-			t.Fatal(err)
-		}
-		if got := strings.Join(r.calls[1:], "\n"); got != tc.want {
-			t.Errorf("judged by %s: calls\n%s\nwant\n%s", tc.judged, got, tc.want)
-		}
-		l := out.(delivery.CheckAnswer).Levels[0]
-		if tc.judged == "installed" && (len(l.Kept) != 1 || l.Judged != "") {
-			t.Errorf("an installed module's level %+v, want the kept verdict taken", l)
-		}
-		if tc.judged != "installed" && (len(l.Kept) != 0 || l.Digest != nil || l.Judged != tc.judged) {
-			t.Errorf("the candidate's level %+v, want nothing kept and the program named", l)
-		}
-	}
-	r := &recorder{fetch: map[string]any{"workspace": "/w"}, digests: map[string]string{"x/pkg/a": "d-kept"}, tests: map[string]bool{}}
-	out, err := RunAsk(context.Background(), r.steps(), ask(delivery.CheckJob{Levels: []string{delivery.LevelUnit}, Kept: true,
-		Fetch: map[string]any{"repository": "novox/x", "commit": runCommit, "beside": []any{map[string]any{"repository": "novox/mesh-sdk", "commit": runCommit}}}}))
-	if err != nil {
-		t.Fatal(err)
-	}
-	if l := out.(delivery.CheckAnswer).Levels[0]; len(l.Kept) != 0 || l.Digest != nil {
-		t.Fatalf("a digest without the siblings kept %+v", l)
-	}
-}
-
-// A Node check tests each module directory, the one whose tests changed first; a conflict ends the ask with the fetch
-// alone, a verdict for the asker.
-func TestRunAskChecksNodeModulesAndConflicts(t *testing.T) {
-	r := &recorder{fetch: map[string]any{"workspace": "/w", "modules": []string{"a", "b"}, "changed": []string{"b/test/x.test.ts"}},
-		tests: map[string]bool{"a": true, "b": true}}
-	s := r.steps()
-	s.Digest = nil
-	if _, err := RunAsk(context.Background(), s, ask(delivery.CheckJob{Levels: []string{delivery.LevelUnit}, Fetch: map[string]any{"repository": "novox/x", "commit": runCommit}})); err != nil {
-		t.Fatal(err)
-	}
-	if fmt.Sprint(r.calls[1:]) != `[test {"level":"unit","module":"b","workspace":"/w"} test {"level":"unit","module":"a","workspace":"/w"}]` {
-		t.Fatalf("calls %v", r.calls)
-	}
-	r = &recorder{fetch: map[string]any{"workspace": "/w", "conflicts": []string{"go.mod"}}}
-	out, err := RunAsk(context.Background(), r.steps(), ask(delivery.CheckJob{Levels: []string{delivery.LevelUnit}, Fetch: map[string]any{"repository": "novox/x", "commit": runCommit}}))
-	if err != nil || len(r.calls) != 1 || len(out.(delivery.CheckAnswer).Levels) != 0 {
-		t.Fatalf("a conflict: %v %v", err, r.calls)
-	}
-}
-
-// Issue 1921: a failure in the packages whose tests changed does not stop the level: the other packages still run, so two
-// failing packages, one changed and one not, are two test results of the one level, and the level does not pass. A Node
-// check runs every module directory after one fails too.
-func TestRunAskRunsEveryPackageAfterAFailure(t *testing.T) {
-	r := &recorder{
-		fetch:   map[string]any{"workspace": "/w", "changed": []string{"pkg/b/b_test.go"}},
-		digests: map[string]string{"x/pkg/a": "d-a", "x/pkg/b": "d-b"},
-		tests:   map[string]bool{"x/pkg/a": false, "x/pkg/b": false},
-	}
-	out, err := RunAsk(context.Background(), r.steps(), ask(delivery.CheckJob{Levels: []string{delivery.LevelIntegration, delivery.LevelUnit},
-		Fetch: map[string]any{"repository": "novox/x", "commit": runCommit}}))
-	if err != nil {
-		t.Fatal(err)
-	}
-	a := out.(delivery.CheckAnswer)
-	if len(a.Levels) != 1 || len(a.Levels[0].Tests) != 2 {
-		t.Fatalf("levels %+v, want the one level with both packages' results", a.Levels)
-	}
-	for i, raw := range a.Levels[0].Tests {
-		var res struct{ Passed bool }
-		if err := json.Unmarshal(raw, &res); err != nil || res.Passed {
-			t.Errorf("result %d %s, want a failure", i, raw)
-		}
-	}
-
-	r = &recorder{fetch: map[string]any{"workspace": "/w", "modules": []string{"a", "b"}, "changed": []string{"b/test/x.test.ts"}},
-		tests: map[string]bool{"a": true, "b": false}}
-	s := r.steps()
-	s.Digest = nil
-	out, err = RunAsk(context.Background(), s, ask(delivery.CheckJob{Levels: []string{delivery.LevelUnit, delivery.LevelIntegration},
-		Fetch: map[string]any{"repository": "novox/x", "commit": runCommit}}))
-	if err != nil {
-		t.Fatal(err)
-	}
-	if a := out.(delivery.CheckAnswer); len(r.calls) != 3 || len(a.Levels) != 1 || len(a.Levels[0].Tests) != 2 {
-		t.Fatalf("calls %v, levels %+v: want both directories of the unit level and no integration level", r.calls, a.Levels)
-	}
-}

go/buildstep/blob.go

@@ -1,170 +0,0 @@
-package buildstep
-
-import (
-	"bytes"
-	"context"
-	"crypto/sha256"
-	"encoding/hex"
-	"errors"
-	"fmt"
-	"io"
-	"net/http"
-	"net/url"
-	"strings"
-	"syscall"
-	"time"
-)
-
-// RegistryWait is how long a push waits for an artifact store that refuses connections, longer than its nightly
-// collection holds it still (about a minute and a half, issue 457); RegistryFirstPause is the first pause, doubling
-// to RegistryMostPause. Variables so a test shortens them.
-var (
-	RegistryWait       = 5 * time.Minute
-	RegistryFirstPause = time.Second
-	RegistryMostPause  = 10 * time.Second
-)
-
-// BlobReference is where a pushed bundle or archive is, as a done key names it and the controller delivers from
-// (novox/hq ADR 0498 clause 1): artifact-store://<module>/<artifact>/blobs/<digest>, the store's address left out
-// (issue 102).
-func BlobReference(module, artifact, digest string) string {
-	return "artifact-store://" + module + "/" + artifact + "/blobs/" + digest
-}
-
-// PushBlob puts body into the artifact store at registry (host:port) as a blob of repository (<module>/<artifact>) by
-// its digest (`sha256:` and hex), from the build module's own process, after the build step ended (novox/hq ADR 0498
-// clauses 1 and 2): a blob the store already holds is done without an upload; otherwise it is uploaded (POST
-// blobs/uploads/, then PUT with the digest). A store refusing connections is waited out up to RegistryWait; any other
-// refusal fails, naming the store's status and its own words, for the caller's `not stored:` error. Bytes that are not
-// their digest are refused before anything is sent.
-func PushBlob(ctx context.Context, client *http.Client, registry, repository, digest string, body []byte) error {
-	sum := sha256.Sum256(body)
-	if got := "sha256:" + hex.EncodeToString(sum[:]); got != digest {
-		return fmt.Errorf("the blob is %s, not the digest %s it was to be pushed as", got, digest)
-	}
-	if client == nil {
-		client = http.DefaultClient
-	}
-	base := "http://" + registry + "/v2/" + repository + "/blobs/"
-	var present bool
-	if err := waitForStore(ctx, registry, func() error {
-		var err error
-		present, err = blobPresent(ctx, client, base+digest)
-		return err
-	}); err != nil {
-		return err
-	}
-	if present {
-		return nil
-	}
-	var location string
-	if err := waitForStore(ctx, registry, func() error {
-		var err error
-		location, err = startUpload(ctx, client, base+"uploads/")
-		return err
-	}); err != nil {
-		return err
-	}
-	target, err := url.Parse(base)
-	if err != nil {
-		return err
-	}
-	loc, err := target.Parse(location)
-	if err != nil {
-		return fmt.Errorf("the store answered the upload's location %q, which is not a URL: %w", location, err)
-	}
-	q := loc.Query()
-	q.Set("digest", digest)
-	loc.RawQuery = q.Encode()
-	req, err := http.NewRequestWithContext(ctx, http.MethodPut, loc.String(), bytes.NewReader(body))
-	if err != nil {
-		return err
-	}
-	req.Header.Set("Content-Type", "application/octet-stream")
-	resp, err := client.Do(req)
-	if err != nil {
-		return fmt.Errorf("putting %s of %s: %w", digest, repository, err)
-	}
-	defer resp.Body.Close()
-	if resp.StatusCode != http.StatusCreated {
-		return storeSaid(resp, "putting "+digest+" of "+repository)
-	}
-	return nil
-}
-
-func blobPresent(ctx context.Context, client *http.Client, at string) (bool, error) {
-	req, err := http.NewRequestWithContext(ctx, http.MethodHead, at, nil)
-	if err != nil {
-		return false, err
-	}
-	resp, err := client.Do(req)
-	if err != nil {
-		return false, err
-	}
-	resp.Body.Close()
-	switch resp.StatusCode {
-	case http.StatusOK:
-		return true, nil
-	case http.StatusNotFound:
-		return false, nil
-	}
-	return false, fmt.Errorf("asking the store for %s: it answered %s", at, resp.Status)
-}
-
-func startUpload(ctx context.Context, client *http.Client, at string) (string, error) {
-	req, err := http.NewRequestWithContext(ctx, http.MethodPost, at, nil)
-	if err != nil {
-		return "", err
-	}
-	resp, err := client.Do(req)
-	if err != nil {
-		return "", err
-	}
-	defer resp.Body.Close()
-	if resp.StatusCode != http.StatusAccepted {
-		return "", storeSaid(resp, "starting an upload at "+at)
-	}
-	location := resp.Header.Get("Location")
-	if location == "" {
-		return "", fmt.Errorf("starting an upload at %s: the store named no location", at)
-	}
-	return location, nil
-}
-
-// storeSaid is the store's refusal: its status and the first of its own words.
-func storeSaid(resp *http.Response, what string) error {
-	words, _ := io.ReadAll(io.LimitReader(resp.Body, 2048))
-	return fmt.Errorf("%s: the store answered %s: %s", what, resp.Status, strings.TrimSpace(string(words)))
-}
-
-// refused is whether an error is a connection refused.
-func refused(err error) bool {
-	return err != nil && (errors.Is(err, syscall.ECONNREFUSED) || strings.Contains(err.Error(), "connection refused"))
-}
-
-// waitForStore runs try, and while it fails because the store refuses connections, tries again with a growing pause
-// until RegistryWait has passed. A refusal is the one error waited for: nothing was sent, so trying again does nothing
-// twice.
-func waitForStore(ctx context.Context, registry string, try func() error) error {
-	err := try()
-	if !refused(err) {
-		return err
-	}
-	started, pause := time.Now(), RegistryFirstPause
-	for {
-		left := RegistryWait - time.Since(started)
-		if left <= 0 {
-			return fmt.Errorf("the artifact store at %s refused every connection for %s, longer than its nightly collection holds it still, so it is down, not paused: %w",
-				registry, time.Since(started).Round(time.Millisecond), err)
-		}
-		select {
-		case <-ctx.Done():
-			return fmt.Errorf("stopped while waiting for the artifact store at %s: %w (last: %v)", registry, ctx.Err(), err)
-		case <-time.After(min(pause, left)):
-		}
-		pause = min(pause*2, RegistryMostPause)
-		if err = try(); !refused(err) {
-			return err
-		}
-	}
-}

go/buildstep/blob_test.go

@@ -1,151 +0,0 @@
-package buildstep
-
-import (
-	"context"
-	"crypto/sha256"
-	"encoding/hex"
-	"io"
-	"net"
-	"net/http"
-	"net/http/httptest"
-	"strings"
-	"sync"
-	"testing"
-	"time"
-
-	"git.novox.be/novox/mesh-sdk/go/delivery"
-)
-
-func digestOfBytes(b []byte) string {
-	h := sha256.Sum256(b)
-	return "sha256:" + hex.EncodeToString(h[:])
-}
-
-// registry is an artifact store as far as a blob push needs one: HEAD a blob, start an upload, PUT it with its digest.
-type registry struct {
-	mu    sync.Mutex
-	blobs map[string][]byte
-	calls []string
-	put   int // the status a PUT answers, 201 when 0
-}
-
-func (r *registry) ServeHTTP(w http.ResponseWriter, req *http.Request) {
-	r.mu.Lock()
-	defer r.mu.Unlock()
-	r.calls = append(r.calls, req.Method+" "+req.URL.Path)
-	switch {
-	case req.Method == http.MethodHead && strings.Contains(req.URL.Path, "/blobs/sha256:"):
-		if _, ok := r.blobs[req.URL.Path[strings.LastIndex(req.URL.Path, "/")+1:]]; ok {
-			w.WriteHeader(http.StatusOK)
-			return
-		}
-		w.WriteHeader(http.StatusNotFound)
-	case req.Method == http.MethodPost && strings.HasSuffix(req.URL.Path, "/blobs/uploads/"):
-		w.Header().Set("Location", strings.TrimSuffix(req.URL.Path, "/")+"/u1?state=x")
-		w.WriteHeader(http.StatusAccepted)
-	case req.Method == http.MethodPut && strings.Contains(req.URL.Path, "/blobs/uploads/u1"):
-		if r.put != 0 {
-			w.WriteHeader(r.put)
-			_, _ = io.WriteString(w, `{"errors":[{"code":"DIGEST_INVALID","message":"provided digest did not match uploaded content"}]}`)
-			return
-		}
-		body, _ := io.ReadAll(req.Body)
-		d := req.URL.Query().Get("digest")
-		if req.URL.Query().Get("state") != "x" || d != digestOfBytes(body) {
-			w.WriteHeader(http.StatusBadRequest)
-			return
-		}
-		r.blobs[d] = body
-		w.WriteHeader(http.StatusCreated)
-	default:
-		w.WriteHeader(http.StatusMethodNotAllowed)
-	}
-}
-
-// A done build's bundle or archive is pushed to the artifact store by its build module (novox/hq ADR 0498 clauses 1
-// and 2): a blob the store already holds is done with no upload; one it lacks is uploaded by digest; its reference is
-// the artifact-store form the builder's key and the controller check.
-func TestABlobIsPushedOnceByItsDigest(t *testing.T) {
-	reg := &registry{blobs: map[string][]byte{}}
-	srv := httptest.NewServer(reg)
-	defer srv.Close()
-	addr := strings.TrimPrefix(srv.URL, "http://")
-	body := []byte("the packed bundle")
-	d := digestOfBytes(body)
-	if err := PushBlob(context.Background(), srv.Client(), addr, "mail/code", d, body); err != nil {
-		t.Fatal(err)
-	}
-	if string(reg.blobs[d]) != string(body) {
-		t.Fatalf("the store holds %q", reg.blobs[d])
-	}
-	reg.calls = nil
-	if err := PushBlob(context.Background(), srv.Client(), addr, "mail/code", d, body); err != nil {
-		t.Fatal(err)
-	}
-	if len(reg.calls) != 1 || !strings.HasPrefix(reg.calls[0], "HEAD ") {
-		t.Fatalf("a blob the store holds was uploaded again: %v", reg.calls)
-	}
-	ref := BlobReference("mail", "code", d)
-	if ref != "artifact-store://mail/code/blobs/"+d {
-		t.Fatalf("BlobReference = %q", ref)
-	}
-	b := delivery.BuilderBuild{State: delivery.BuildDone, Manifest: strings.Repeat("4", 64),
-		Artifacts: []delivery.BuiltArtifact{{Name: "code", Kind: "bundle", Digest: d, Reference: ref}}}
-	if _, err := delivery.EncodeBuilderBuild(b); err != nil {
-		t.Fatalf("the key refuses the reference BlobReference gives: %v", err)
-	}
-}
-
-// A store that refuses the upload fails the push naming the store's own words; bytes that are not the digest are
-// refused before anything is sent.
-func TestAPushTheStoreRefusesSaysTheStoresWords(t *testing.T) {
-	reg := &registry{blobs: map[string][]byte{}, put: http.StatusBadRequest}
-	srv := httptest.NewServer(reg)
-	defer srv.Close()
-	addr := strings.TrimPrefix(srv.URL, "http://")
-	body := []byte("x")
-	err := PushBlob(context.Background(), srv.Client(), addr, "mail/code", digestOfBytes(body), body)
-	if err == nil || !strings.Contains(err.Error(), "provided digest did not match") || !strings.Contains(err.Error(), "400") {
-		t.Fatalf("a refused upload said %v", err)
-	}
-	reg.calls = nil
-	err = PushBlob(context.Background(), srv.Client(), addr, "mail/code", digestOfBytes([]byte("other")), body)
-	if err == nil || len(reg.calls) != 0 {
-		t.Fatalf("bytes that are not their digest: %v, calls %v", err, reg.calls)
-	}
-}
-
-// A store refusing connections (its nightly collection holds it still) is waited out, up to RegistryWait (issue 457).
-func TestAPushWaitsOutAStoreRefusingConnections(t *testing.T) {
-	l, err := net.Listen("tcp", "127.0.0.1:0")
-	if err != nil {
-		t.Fatal(err)
-	}
-	addr := l.Addr().String()
-	l.Close() // refusing now
-	reg := &registry{blobs: map[string][]byte{}}
-	go func() {
-		time.Sleep(300 * time.Millisecond)
-		l2, err := net.Listen("tcp", addr)
-		if err != nil {
-			return
-		}
-		_ = http.Serve(l2, reg)
-	}()
-	beforeWait, beforePause := RegistryWait, RegistryFirstPause
-	RegistryWait, RegistryFirstPause = 3*time.Second, 100*time.Millisecond
-	defer func() { RegistryWait, RegistryFirstPause = beforeWait, beforePause }()
-	body := []byte("late")
-	if err := PushBlob(context.Background(), http.DefaultClient, addr, "mail/code", digestOfBytes(body), body); err != nil {
-		t.Fatalf("a store that came back was not waited for: %v", err)
-	}
-
-	l3, _ := net.Listen("tcp", "127.0.0.1:0")
-	gone := l3.Addr().String()
-	l3.Close()
-	RegistryWait = 300 * time.Millisecond
-	err = PushBlob(context.Background(), http.DefaultClient, gone, "mail/code", digestOfBytes(body), body)
-	if err == nil || !strings.Contains(err.Error(), "refused every connection") {
-		t.Fatalf("a store that stayed down said %v", err)
-	}
-}

go/buildstep/buildhours.go

@@ -1,135 +0,0 @@
-package buildstep
-
-import (
-	"encoding/json"
-	"fmt"
-	"os"
-	"strings"
-	"time"
-)
-
-// **A node may build only within its build hours** (the operator, 2026-10-26 21:18: "we should only use g14 as a builder
-// outside office hours", "from 18 o'clock until 6 in the morning"). A build module's `build-hours` setting names, per
-// node, the window in the node's local time in which it takes asks; outside it the capacity judged by is 0: steps running
-// finish, no new one is taken. A node it does not name, or an empty setting, builds at any hour. The puller judges it at
-// every judgement and wakes on one timer to the window's next edge (a clock edge, not a poll of another part).
-
-// BuildHoursSetting is the build modules' setting of the nodes' build windows: `<node>=HH:MM-HH:MM` pairs separated by
-// commas, in the node's local time; an end before its start crosses midnight (g14=18:00-06:00).
-const BuildHoursSetting = "build-hours"
-
-// BuildWindow is one node's build hours: minutes after local midnight, Start inclusive, End exclusive.
-type BuildWindow struct {
-	Start, End int
-}
-
-// String is the window as the setting writes it.
-func (w BuildWindow) String() string {
-	return fmt.Sprintf("%02d:%02d-%02d:%02d", w.Start/60, w.Start%60, w.End/60, w.End%60)
-}
-
-// Open says whether t, in its own location, falls in the window.
-func (w BuildWindow) Open(t time.Time) bool {
-	m := t.Hour()*60 + t.Minute()
-	if w.Start < w.End {
-		return m >= w.Start && m < w.End
-	}
-	return m >= w.Start || m < w.End
-}
-
-// NextEdge is the first time after t, in t's location, at which the window opens or closes.
-func (w BuildWindow) NextEdge(t time.Time) time.Time {
-	var next time.Time
-	for day := 0; day <= 1; day++ {
-		for _, m := range []int{w.Start, w.End} {
-			e := time.Date(t.Year(), t.Month(), t.Day()+day, m/60, m%60, 0, 0, t.Location())
-			if e.After(t) && (next.IsZero() || e.Before(next)) {
-				next = e
-			}
-		}
-	}
-	return next
-}
-
-// ParseBuildHours is node's window in a build-hours setting: nil when the setting is empty or does not name the node.
-func ParseBuildHours(setting, node string) (*BuildWindow, error) {
-	var found *BuildWindow
-	for _, pair := range strings.Split(setting, ",") {
-		pair = strings.TrimSpace(pair)
-		if pair == "" {
-			continue
-		}
-		name, span, ok := strings.Cut(pair, "=")
-		from, to, ok2 := strings.Cut(span, "-")
-		if !ok || !ok2 || strings.TrimSpace(name) == "" {
-			return nil, fmt.Errorf("the build hours %q: %q is not <node>=HH:MM-HH:MM", setting, pair)
-		}
-		start, err := minuteOf(from)
-		if err != nil {
-			return nil, fmt.Errorf("the build hours %q: %v", setting, err)
-		}
-		end, err := minuteOf(to)
-		if err != nil {
-			return nil, fmt.Errorf("the build hours %q: %v", setting, err)
-		}
-		if start == end {
-			return nil, fmt.Errorf("the build hours %q: %s opens and closes at the same minute", setting, pair)
-		}
-		if strings.TrimSpace(name) == node {
-			found = &BuildWindow{Start: start, End: end}
-		}
-	}
-	return found, nil
-}
-
-// minuteOf reads HH:MM as minutes after midnight.
-func minuteOf(s string) (int, error) {
-	var h, m int
-	s = strings.TrimSpace(s)
-	if n, err := fmt.Sscanf(s, "%d:%d", &h, &m); err != nil || n != 2 || h < 0 || h > 23 || m < 0 || m > 59 || len(s) != 5 {
-		return 0, fmt.Errorf("%q is not a time HH:MM", s)
-	}
-	return h*60 + m, nil
-}
-
-// NodeBuildHours is node's build window, read from the module's settings file at path at every call, and why it is
-// none when the value cannot be read. No path, no file value or an empty one is no window and no fault. A value that
-// cannot be read is no window too, so the node builds at any hour; the setting is a preference of hours, not a safety
-// bound (a node that must never build has capacity 0). It is loud: the fault is said once per distinct fault through
-// logf, and the puller writes it in the capacity record that build_usage shows.
-func NodeBuildHours(path, node string, logf func(string, ...any)) func() (*BuildWindow, string) {
-	said := ""
-	say := func(why string) {
-		if logf != nil && why != said {
-			said = why
-			logf("%s, so %s builds at any hour", why, node)
-		}
-	}
-	fault := func(why string) (*BuildWindow, string) {
-		say(why)
-		return nil, why
-	}
-	return func() (*BuildWindow, string) {
-		if path == "" {
-			return nil, ""
-		}
-		raw, err := os.ReadFile(path)
-		if err != nil {
-			return fault(fmt.Sprintf("the setting %s cannot be read: %v", BuildHoursSetting, err))
-		}
-		var s map[string]json.RawMessage
-		if err := json.Unmarshal(raw, &s); err != nil {
-			return fault(fmt.Sprintf("the settings file %s is not JSON: %v", path, err))
-		}
-		setting := ""
-		if v, ok := s[BuildHoursSetting]; ok && json.Unmarshal(v, &setting) != nil {
-			return fault(fmt.Sprintf("the setting %s %s is not a string", BuildHoursSetting, v))
-		}
-		w, err := ParseBuildHours(setting, node)
-		if err != nil {
-			return fault(err.Error())
-		}
-		said = ""
-		return w, ""
-	}
-}

go/buildstep/capacity.go

@@ -1,61 +0,0 @@
-package buildstep
-
-import (
-	"encoding/json"
-	"fmt"
-	"os"
-
-	"git.novox.be/novox/mesh-sdk/go/delivery/buildrun"
-)
-
-// CapacitySetting is the build modules' setting of each node's build capacity (novox/hq ADR 0525 §5): `<node>=<asks at
-// once>` pairs separated by commas, as the builder's was (ADR 0485 §1). Each build module declares it with
-// DefaultCapacities as its default, and the controller lays it into the module's settings file.
-const CapacitySetting = "capacity"
-
-// DefaultCapacities is the setting's default, the builder's before R4g: the control-node (novox) and the laptop (g14)
-// build nothing.
-const DefaultCapacities = "shanks=3,ace=2,g14=0,novox=0"
-
-// NodeCapacity is node's build capacity, read from the module's settings file at path at every call, so a change takes
-// effect at the next pull; with no path it reads fallback. A node the setting does not name runs one ask at a time (as
-// the builder's did). A file or a setting that cannot be read gives 0 and says why: pulling on a setting nobody can read
-// could build on a node that must not.
-func NodeCapacity(path, fallback, node string, logf func(string, ...any)) func() int {
-	say := func(format string, args ...any) {
-		if logf != nil {
-			logf(format, args...)
-		}
-	}
-	return func() int {
-		setting := fallback
-		if path != "" {
-			raw, err := os.ReadFile(path)
-			if err != nil {
-				say("the build capacity cannot be read, so %s pulls nothing: %v", node, err)
-				return 0
-			}
-			var s map[string]any
-			if err := json.Unmarshal(raw, &s); err != nil {
-				say("the settings file %s is not JSON, so %s pulls nothing: %v", path, node, err)
-				return 0
-			}
-			setting, _ = s[CapacitySetting].(string)
-		}
-		n, err := capacityOf(setting, node)
-		if err != nil {
-			say("%v, so %s pulls nothing", err, node)
-			return 0
-		}
-		return n
-	}
-}
-
-// capacityOf is node's capacity in a setting's `<node>=<asks>` pairs: DefaultCapacity for a node it does not name.
-func capacityOf(setting, node string) (int, error) {
-	caps, err := buildrun.ParseCapacity(setting)
-	if err != nil {
-		return 0, fmt.Errorf("the build capacity: %w", err)
-	}
-	return (&buildrun.Places{Capacity: caps}).CapacityOf(node), nil
-}

go/buildstep/capacity_cpu.go

@@ -1,141 +0,0 @@
-package buildstep
-
-import (
-	"encoding/json"
-	"fmt"
-	"math"
-	"os"
-	"runtime"
-	"strconv"
-	"strings"
-
-	"git.novox.be/novox/mesh-sdk/go/buildcpu"
-	"git.novox.be/novox/mesh-sdk/go/delivery"
-)
-
-// **A build seat's capacity follows the CPU its node gives builds** (issue 1806's follow-up; issue 1890, 2026-10-26
-// 19:41: under the 50 % cap shanks' mesh-build-go kept capacity 3, three full mesh-catalog checks shared 12 cores, and
-// each step ran past the 30-minute step bound with no test run). The configured capacity is an upper bound; the node's
-// build slice bounds it again by the cores a step needs: floor(the slice's quota in cores / cores-per-step), one at
-// least. The quota is read live from the cgroup at every judgement, so a changed cap is followed at the next take
-// without a restart, and the result is said (the seat's current verb, the status tools, `capacity.<node>` in the pauses
-// state that the delivery view's build_usage reads).
-
-// CoresPerStepSetting is a build module's setting of the processors one of its steps needs: a number above zero, the
-// same on every node (a step's need is the module's, not the node's). Each build module declares it with its own default
-// (DefaultCoresPerStep).
-const CoresPerStepSetting = "cores-per-step"
-
-// DefaultCoresPerStep are the build modules' defaults by language, from measured steps (2026-10-26): a full mesh-catalog
-// check on mesh-build-go takes what it is given (three at once took 965 % of shanks' 1200 % slice, about 4 cores each,
-// and ran past the 30-minute step bound), so a Go step is given 6, half again what starved; a Node step (tsc, esbuild, a
-// test runner: median 15 s) and an image build (buildah, its RUN lines mostly fetches) need 2.
-var DefaultCoresPerStep = map[string]float64{delivery.AskGo: 6, delivery.AskNode: 2, delivery.AskImage: 2}
-
-// Quota is the build slice's CPU quota as this process's cgroup holds it, in percent of one processor (1200 is 12
-// cores), and where it was read: the cgroup's cpu.max (buildcpu.ReadInForce, the tighter of its unit's and its slice's),
-// else the share the composer gave (buildcpu.ShareWord) over the machine's processors, else 0 and why none is known.
-func Quota() (percent int, from string) {
-	f := buildcpu.ReadInForce()
-	if f.Quota > 0 {
-		path := f.Slice.Path
-		if path == "" {
-			path = f.Cgroup
-		}
-		return f.Quota, "the cpu.max of " + path
-	}
-	if n, err := strconv.Atoi(strings.TrimSpace(os.Getenv(buildcpu.ShareWord))); err == nil && n >= 1 && n <= 100 {
-		return buildcpu.Quota(n, runtime.NumCPU()), fmt.Sprintf("the share %d%% the composer gave (%s), of %d processors; no cpu.max is read", n, buildcpu.ShareWord, runtime.NumCPU())
-	}
-	return 0, "no CPU quota: neither a cpu.max on its cgroup nor a share from the composer"
-}
-
-// EffectiveCapacity is the capacity a seat's holder judges by, from its configured capacity, its node's quota (percent of
-// one processor, 0 when none is known) and the cores one of its steps needs. Without a quota it is the configured one;
-// with one, min(configured, floor(quota cores / coresPerStep)), and one at least while the configured one is above
-// zero. A coresPerStep of zero or less is taken as 1.
-func EffectiveCapacity(configured, quotaPercent int, quotaFrom string, coresPerStep float64) delivery.Capacity {
-	if coresPerStep <= 0 || math.IsNaN(coresPerStep) || math.IsInf(coresPerStep, 0) {
-		coresPerStep = 1
-	}
-	c := delivery.Capacity{Configured: configured, Effective: configured, QuotaFrom: quotaFrom, CoresPerStep: coresPerStep}
-	switch {
-	case configured <= 0:
-		c.Effective = 0
-		c.Why = fmt.Sprintf("its configured capacity is %d, so it pulls nothing", configured)
-		return c
-	case quotaPercent <= 0:
-		c.Why = fmt.Sprintf("its configured capacity %d; %s, so the CPU bounds nothing", configured, quotaFrom)
-		return c
-	}
-	c.QuotaCores = float64(quotaPercent) / 100
-	c.ByCPU = int(math.Floor(c.QuotaCores/coresPerStep + 1e-9))
-	if c.ByCPU < 1 {
-		c.ByCPU = 1
-	}
-	byCPU := fmt.Sprintf("%g cores of the build slice (%s) / %g cores a step = %d", c.QuotaCores, quotaFrom, coresPerStep, c.ByCPU)
-	if c.ByCPU < configured {
-		c.Effective = c.ByCPU
-		c.Why = fmt.Sprintf("%d, bounded by the CPU: %s, under its configured %d", c.Effective, byCPU, configured)
-	} else {
-		c.Why = fmt.Sprintf("%d, its configured capacity; the CPU allows %s", configured, byCPU)
-	}
-	return c
-}
-
-// NodeCoresPerStep is the module's cores-per-step, read from its settings file at path at every call so a change is
-// followed at the next judgement; fallback when there is no path, no value or one that is not a number above zero, said
-// once per distinct fault through logf.
-func NodeCoresPerStep(path string, fallback float64, logf func(string, ...any)) func() float64 {
-	said := ""
-	say := func(why string) {
-		if logf != nil && why != said {
-			said = why
-			logf("%s, so a step is taken to need %g cores", why, fallback)
-		}
-	}
-	return func() float64 {
-		if path == "" {
-			return fallback
-		}
-		raw, err := os.ReadFile(path)
-		if err != nil {
-			say(fmt.Sprintf("the setting %s cannot be read: %v", CoresPerStepSetting, err))
-			return fallback
-		}
-		var s map[string]json.RawMessage
-		if err := json.Unmarshal(raw, &s); err != nil {
-			say(fmt.Sprintf("the settings file %s is not JSON: %v", path, err))
-			return fallback
-		}
-		v, ok := s[CoresPerStepSetting]
-		if !ok {
-			return fallback // not declared yet (a module before its manifest names it): the default, nothing to say
-		}
-		n, err := coresOf(v)
-		if err != nil {
-			say(fmt.Sprintf("the setting %s %s: %v", CoresPerStepSetting, v, err))
-			return fallback
-		}
-		said = ""
-		return n
-	}
-}
-
-// coresOf reads a cores-per-step value: a JSON number or a string holding one, above zero.
-func coresOf(v json.RawMessage) (float64, error) {
-	var n float64
-	if err := json.Unmarshal(v, &n); err != nil {
-		var s string
-		if err := json.Unmarshal(v, &s); err != nil {
-			return 0, fmt.Errorf("is neither a number nor a string")
-		}
-		if n, err = strconv.ParseFloat(strings.TrimSpace(s), 64); err != nil {
-			return 0, fmt.Errorf("is not a number")
-		}
-	}
-	if n <= 0 || math.IsNaN(n) || math.IsInf(n, 0) {
-		return 0, fmt.Errorf("is not above zero")
-	}
-	return n, nil
-}

go/buildstep/capacity_test.go

@@ -1,137 +0,0 @@
-package buildstep
-
-import (
-	"os"
-	"path/filepath"
-	"strings"
-	"testing"
-	"time"
-)
-
-// 1887/A7: the node's build capacity is the build module's setting, read at every pull: the control-node at 0 pulls
-// nothing, a change takes effect at the next read, and a setting that cannot be read pulls nothing.
-func TestNodeCapacity(t *testing.T) {
-	if got := NodeCapacity("", DefaultCapacities, "novox", nil)(); got != 0 {
-		t.Errorf("novox = %d by default, want 0", got)
-	}
-	if got := NodeCapacity("", DefaultCapacities, "shanks", nil)(); got != 3 {
-		t.Errorf("shanks = %d by default, want 3", got)
-	}
-	file := filepath.Join(t.TempDir(), "settings.json")
-	os.WriteFile(file, []byte(`{"capacity":"shanks=1,ace=2"}`), 0o600)
-	capacity := NodeCapacity(file, DefaultCapacities, "shanks", nil)
-	if got := capacity(); got != 1 {
-		t.Errorf("shanks = %d from the file, want 1", got)
-	}
-	os.WriteFile(file, []byte(`{"capacity":"shanks=4"}`), 0o600)
-	if got := capacity(); got != 4 {
-		t.Errorf("shanks = %d after the change, want 4", got)
-	}
-	if got := NodeCapacity(file, "", "pi", nil)(); got != 1 {
-		t.Errorf("a node not named = %d, want 1", got)
-	}
-	os.WriteFile(file, []byte(`{"capacity":"shanks=lots"}`), 0o600)
-	if got := capacity(); got != 0 {
-		t.Errorf("an unreadable setting = %d, want 0", got)
-	}
-	if got := NodeCapacity(filepath.Join(t.TempDir(), "none"), DefaultCapacities, "shanks", nil)(); got != 0 {
-		t.Errorf("a missing file = %d, want 0", got)
-	}
-}
-
-// ADR 0553 §4: a step's threads are the composer's share over the module's own capacity; without the word, none. And
-// issue 1806's follow-up: the capacity judged by is the configured one bounded by the build slice's cores over the cores
-// a step needs (the three build nodes as they stand on 2026-10-26), and cores-per-step is read from the settings file.
-func TestNodeLimitsAndTheCPUBound(t *testing.T) {
-	t.Setenv("MESH_BUILD_CPU_SHARE", "")
-	if l := NodeLimits(3); l.Threads != 0 || l.Slots != 3 {
-		t.Errorf("without the word: %+v", l)
-	}
-	t.Setenv("MESH_BUILD_CPU_SHARE", "75")
-	if l := NodeLimits(3); l.Percent != 75 || l.Slots != 3 || l.Threads < 1 {
-		t.Errorf("from the word: %+v", l)
-	}
-	for _, c := range []struct {
-		name              string
-		configured, quota int
-		cores             float64
-		effective, byCPU  int
-	}{
-		{"shanks: 12 cores, configured 3", 3, 1200, 6, 2, 2},
-		{"ace: 18 cores, configured 2", 2, 1800, 6, 2, 3},
-		{"g14: 8 cores, configured 2", 2, 800, 6, 1, 1},
-		{"node on shanks: 12 cores at 2", 3, 1200, 2, 3, 6},
-		{"no quota: the configured one", 3, 0, 6, 3, 0},
-		{"configured 0 pulls nothing", 0, 1200, 6, 0, 0},
-		{"a quota under one step still builds one", 2, 100, 6, 1, 1},
-		{"no cores a step is one", 2, 150, 0, 1, 1},
-	} {
-		got := EffectiveCapacity(c.configured, c.quota, "test", c.cores)
-		if got.Effective != c.effective || got.ByCPU != c.byCPU || got.Why == "" {
-			t.Errorf("%s: %+v, want effective %d, by CPU %d", c.name, got, c.effective, c.byCPU)
-		}
-	}
-	file := filepath.Join(t.TempDir(), "settings.json")
-	var said []string
-	cores := NodeCoresPerStep(file, 6, func(f string, a ...any) { said = append(said, f) })
-	for _, c := range []struct {
-		file string
-		want float64
-	}{{`{"capacity":"shanks=2"}`, 6}, {`{"cores-per-step":4}`, 4}, {`{"cores-per-step":"3.5"}`, 3.5}, {`{"cores-per-step":0}`, 6}, {`{"cores-per-step":0}`, 6}} {
-		os.WriteFile(file, []byte(c.file), 0o600)
-		if got := cores(); got != c.want {
-			t.Errorf("cores-per-step from %s = %g, want %g", c.file, got, c.want)
-		}
-	}
-	if len(said) != 1 {
-		t.Errorf("a value not above zero is said once, said %d times", len(said))
-	}
-
-	// The operator, 2026-10-26 21:18: g14 builds only from 18:00 to 06:00, its local time. Outside its build hours the
-	// capacity judged by is 0, said with the window and when it opens; a node not named, or a bad value, builds at any hour.
-	cet := time.FixedZone("CET", 3600)
-	day := func(hh, mm int) time.Time { return time.Date(2026, 10, 26, hh, mm, 0, 0, cet) }
-	was := now
-	defer func() { now = was }()
-	for _, c := range []struct {
-		name, setting, node string
-		at                  time.Time
-		effective           int
-		edge                string // the window's next edge, HH:MM; "" for no window
-		bad                 bool
-	}{
-		{"g14 in the office", "g14=18:00-06:00", "g14", day(10, 0), 0, "18:00", false},
-		{"g14 in the evening", "g14=18:00-06:00", "g14", day(18, 0), 2, "06:00", false},
-		{"g14 past midnight", "g14=18:00-06:00", "g14", day(5, 59), 2, "06:00", false},
-		{"g14 at the close", "g14=18:00-06:00", "g14", day(6, 0), 0, "18:00", false},
-		{"a day window", "shanks=09:00-17:30,g14=18:00-06:00", "shanks", day(17, 29), 2, "17:30", false},
-		{"a node not named", "g14=18:00-06:00", "ace", day(10, 0), 2, "", false},
-		{"a bad time", "g14=18:00-6", "g14", day(10, 0), 2, "", true},
-		{"no span", "g14=18:00-18:00", "g14", day(10, 0), 2, "", true},
-	} {
-		w, err := ParseBuildHours(c.setting, c.node)
-		if (err != nil) != c.bad {
-			t.Errorf("%s: parse %v", c.name, err)
-		}
-		if edge := ""; w != nil {
-			edge = w.NextEdge(c.at).Format("15:04")
-			if edge != c.edge {
-				t.Errorf("%s: next edge %s, want %s", c.name, edge, c.edge)
-			}
-		} else if c.edge != "" {
-			t.Errorf("%s: no window, want one", c.name)
-		}
-		file := filepath.Join(t.TempDir(), "settings.json")
-		os.WriteFile(file, []byte(`{"build-hours":"`+c.setting+`"}`), 0o600)
-		now = func() time.Time { return c.at }
-		p := &Puller{Language: "go", Node: c.node, Capacity: func() int { return 2 }, BuildHours: NodeBuildHours(file, c.node, nil)}
-		got := p.CapacityDetail()
-		if got.Effective != c.effective || got.OutsideHours != (c.effective == 0) || (c.effective == 0 && !strings.Contains(got.Why, "outside its build hours 18:00-06:00 CET until 18:00")) {
-			t.Errorf("%s: %+v, want capacity %d", c.name, got, c.effective)
-		}
-		// A value that cannot be read builds at any hour, loudly: the record names the value and says why.
-		if c.bad && (!strings.Contains(got.BuildHoursFault, c.setting) || !strings.Contains(got.Why, "at any hour, because its build hours cannot be read")) {
-			t.Errorf("%s: a bad value is not said in the record: %+v", c.name, got)
-		}
-	}
-}

go/buildstep/cpu.go

@@ -1,14 +0,0 @@
-package buildstep
-
-import (
-	"os"
-
-	"git.novox.be/novox/mesh-sdk/go/buildcpu"
-)
-
-// NodeLimits is what one step of a build module is held to (novox/hq ADR 0553 §4): the node's processor share from the
-// word the composer gives the module (buildcpu.ShareWord), divided by the module's own capacity, own, over the machine's
-// processors. Without the word, no thread limit: Threads is 0.
-func NodeLimits(own int) buildcpu.Limits {
-	return buildcpu.FromWords(os.Getenv, own)
-}

go/buildstep/digestshape_test.go

@@ -1,234 +0,0 @@
-package buildstep
-
-import (
-	"context"
-	"encoding/json"
-	"errors"
-	"fmt"
-	"sort"
-	"strings"
-	"sync"
-	"testing"
-	"time"
-
-	"git.novox.be/novox/mesh-sdk/go/delivery"
-)
-
-// credentialField is the node runtime's rule for a state value (mesh-tools node-tools/internal/bus/state.go, novox/hq
-// ADR 0201), copied whole: the first field anywhere in the value whose name, lower-cased and without - _ and spaces, ends
-// in a credential word, or "". A step's end is refused when it answers a field.
-func credentialField(value json.RawMessage) string {
-	endings := []string{"password", "passwd", "secret", "token", "credential", "credentials",
-		"authorization", "apikey", "privatekey", "accesskey", "cookie"}
-	var v any
-	if json.Unmarshal(value, &v) != nil {
-		return ""
-	}
-	var walk func(any) string
-	walk = func(v any) string {
-		switch t := v.(type) {
-		case map[string]any:
-			keys := make([]string, 0, len(t))
-			for k := range t {
-				keys = append(keys, k)
-			}
-			sort.Strings(keys)
-			for _, k := range keys {
-				norm := strings.NewReplacer("-", "", "_", "", " ", "").Replace(strings.ToLower(k))
-				for _, end := range endings {
-					if strings.HasSuffix(norm, end) {
-						return k
-					}
-				}
-				if found := walk(t[k]); found != "" {
-					return found
-				}
-			}
-		case []any:
-			for _, x := range t {
-				if found := walk(x); found != "" {
-					return found
-				}
-			}
-		}
-		return ""
-	}
-	return walk(v)
-}
-
-// runtimeState is a steps state that refuses a value as the node runtime does, and keeps every value it took.
-type runtimeState struct {
-	mu      sync.Mutex
-	took    map[string][]delivery.Step
-	refused int
-}
-
-func newRuntimeState() *runtimeState { return &runtimeState{took: map[string][]delivery.Step{}} }
-
-func (s *runtimeState) put(key string, value any) (uint64, error) {
-	raw, _ := value.(json.RawMessage)
-	if f := credentialField(raw); f != "" {
-		s.mu.Lock()
-		s.refused++
-		s.mu.Unlock()
-		return 0, fmt.Errorf("steps.%s carries a field %q, which names a credential", key, f)
-	}
-	st, err := delivery.DecodeStep(raw)
-	if err != nil {
-		return 0, err
-	}
-	s.mu.Lock()
-	defer s.mu.Unlock()
-	s.took[key] = append(s.took[key], st)
-	return uint64(len(s.took[key])), nil
-}
-
-func (s *runtimeState) last(key string) (delivery.Step, bool) {
-	s.mu.Lock()
-	defer s.mu.Unlock()
-	t := s.took[key]
-	if len(t) == 0 {
-		return delivery.Step{}, false
-	}
-	return t[len(t)-1], true
-}
-
-func fastEnds(t *testing.T) {
-	attempts, retry := EndAttempts, EndRetry
-	EndAttempts, EndRetry = 2, time.Millisecond
-	t.Cleanup(func() { EndAttempts, EndRetry = attempts, retry })
-}
-
-// 1930/AC1: given a check of a repository with the package .../internal/token, when its ask's answer is stored as the
-// step's end, then no field is keyed by a package path: the runtime's credential rule takes the value, and the package
-// and its digest read back from the stored end.
-func TestADigestOfAPackageNamedTokenIsStoredAsAList(t *testing.T) {
-	fastEnds(t)
-	r := &recorder{
-		fetch:   map[string]any{"workspace": "/w"},
-		digests: map[string]string{"x/internal/token": "d-token", "x/pkg/a": "d-a"},
-		tests:   map[string]bool{"x/internal/token": true, "x/pkg/a": true},
-	}
-	out, err := RunAsk(context.Background(), r.steps(), ask(delivery.CheckJob{Levels: []string{delivery.LevelUnit},
-		Fetch: map[string]any{"repository": "novox/x", "commit": runCommit}}))
-	if err != nil {
-		t.Fatal(err)
-	}
-	old, _ := json.Marshal(map[string]any{"levels": []any{map[string]any{"level": "unit", "digest": map[string]any{"packages": r.digests}}}})
-	if credentialField(old) != "x/internal/token" {
-		t.Fatalf("the rule does not refuse the form before issue 1930 (%s): the test proves nothing", old)
-	}
-	st := newRuntimeState()
-	if err := finish(st.put, "shanks.a1", delivery.Step{ID: "a1", Tool: "check ask", Node: "shanks", State: delivery.StepRunning, Started: time.Now()}, out, nil, t.Logf); err != nil {
-		t.Fatal(err)
-	}
-	s, ok := st.last("shanks.a1")
-	if !ok || s.State != delivery.StepPassed || st.refused != 0 {
-		t.Fatalf("the end %+v (written %v, refused %d), want it passed and taken at once", s, ok, st.refused)
-	}
-	var a delivery.CheckAnswer
-	if err := json.Unmarshal(s.Result, &a); err != nil {
-		t.Fatal(err)
-	}
-	if len(a.Levels) != 1 || a.Levels[0].Digest == nil {
-		t.Fatalf("levels %+v, want the unit level with its digest", a.Levels)
-	}
-	want := []delivery.PackageDigest{{Package: "x/internal/token", Digest: "d-token"}, {Package: "x/pkg/a", Digest: "d-a"}}
-	if got := a.Levels[0].Digest.Packages; fmt.Sprint(got) != fmt.Sprint(want) {
-		t.Errorf("packages %v, want %v", got, want)
-	}
-	if !strings.Contains(string(s.Result), `"package":"x/internal/token"`) {
-		t.Errorf("the stored end does not name the package as a value: %s", s.Result)
-	}
-}
-
-// 1930/AC2: given an end the state refuses every time, when finish writes it, then it logs the refusal and writes a small
-// failed end without the result that names the write's error; and when no end can be written at all it answers an error.
-func TestARefusedEndIsSaidAndEndsTheStepFailed(t *testing.T) {
-	fastEnds(t)
-	big := errors.New("the value carries a field \"x/internal/token\", which names a credential")
-	var refused int
-	var stored []delivery.Step
-	put := func(key string, value any) (uint64, error) {
-		st, _ := delivery.DecodeStep(value.(json.RawMessage))
-		if len(st.Result) > 0 {
-			refused++
-			return 0, big
-		}
-		stored = append(stored, st)
-		return 1, nil
-	}
-	var logged []string
-	logf := func(format string, args ...any) { logged = append(logged, fmt.Sprintf(format, args...)) }
-	err := finish(put, "shanks.a2", delivery.Step{ID: "a2", Tool: "check ask", Node: "shanks", State: delivery.StepRunning, Started: time.Now()}, map[string]any{"levels": 1}, nil, logf)
-	if err != nil {
-		t.Fatalf("finish answered %v, want the small end written", err)
-	}
-	if refused != EndAttempts || len(stored) != 1 {
-		t.Fatalf("refused %d, stored %d, want %d refusals and one small end", refused, len(stored), EndAttempts)
-	}
-	s := stored[0]
-	if s.State != delivery.StepFailed || len(s.Result) != 0 || !strings.Contains(s.Reason, "could not be written") ||
-		!strings.Contains(s.Reason, big.Error()) || !strings.Contains(s.Reason, "passed") {
-		t.Errorf("the small end %+v, want failed, no result, naming the write's error and that it passed", s)
-	}
-	if len(logged) == 0 || !strings.Contains(logged[0], big.Error()) {
-		t.Errorf("logged %q, want the refusal said", logged)
-	}
-	none := func(string, any) (uint64, error) { return 0, errors.New("the bus is gone") }
-	if err := finish(none, "shanks.a3", delivery.Step{ID: "a3", Tool: "check ask", Node: "shanks", Started: time.Now()}, nil, nil, logf); err == nil || !strings.Contains(err.Error(), "the bus is gone") {
-		t.Errorf("finish with no write possible answered %v, want the error", err)
-	}
-}
-
-// 1930/AC2: given an ask whose end the state refuses, when it runs, then the ask is acknowledged only once its small
-// failed end is written; when no end can be written at all, it is given back, never acknowledged as done.
-func TestAnAskWhoseEndCannotBeWrittenIsNotAcked(t *testing.T) {
-	fastEnds(t)
-	for _, tc := range []struct {
-		name      string
-		smallOK   bool
-		wantAcked bool
-	}{{"the small end written", true, true}, {"no end written", false, false}} {
-		t.Run(tc.name, func(t *testing.T) {
-			src := NewFakeAsks()
-			a := testAsk(delivery.AskCheck)
-			_ = src.PublishAsk(a)
-			var mu sync.Mutex
-			var ends []delivery.Step
-			put := func(key string, value any) (uint64, error) {
-				st, err := delivery.DecodeStep(value.(json.RawMessage))
-				if err != nil {
-					return 0, err
-				}
-				if st.State != delivery.StepRunning && (len(st.Result) > 0 || !tc.smallOK) {
-					return 0, errors.New("refused")
-				}
-				mu.Lock()
-				ends = append(ends, st)
-				mu.Unlock()
-				return 1, nil
-			}
-			p := &Puller{Source: src, Language: delivery.AskGo, Node: "shanks", Put: put, Capacity: func() int { return 1 },
-				PullWait: 10 * time.Millisecond, Logf: t.Logf,
-				Run: func(ctx context.Context, a delivery.StepAsk) (any, error) { return map[string]any{"ran": true}, nil }}
-			ctx, cancel := context.WithCancel(context.Background())
-			defer cancel()
-			go p.Pull(ctx)
-			waitFor(t, "the ask's fate", func() bool { ac, tm, nk := src.Fates(); return len(ac)+len(tm)+len(nk) > 0 })
-			cancel()
-			acked, termed, naked := src.Fates()
-			if tc.wantAcked && (len(acked) != 1 || len(naked) != 0) || !tc.wantAcked && (len(acked) != 0 || len(naked) == 0) || len(termed) != 0 {
-				t.Fatalf("acked %v naked %v termed %v", acked, naked, termed)
-			}
-			mu.Lock()
-			defer mu.Unlock()
-			if tc.smallOK {
-				last := ends[len(ends)-1]
-				if last.State != delivery.StepFailed || !strings.Contains(last.Reason, "refused") {
-					t.Errorf("the end %+v, want the small failed end", last)
-				}
-			}
-		})
-	}
-}

go/buildstep/fetch.go

@@ -1,196 +0,0 @@
-package buildstep
-
-import (
-	"context"
-	"fmt"
-	"net/url"
-	"os"
-	"path/filepath"
-	"regexp"
-	"strings"
-
-	"git.novox.be/novox/mesh-sdk/go/forgekey"
-)
-
-// Option changes FetchCommit.
-type Option func(*fetchOptions)
-
-type fetchOptions struct {
-	allowFile bool
-	mirror    string
-}
-
-// AllowFileRemote lets FetchCommit take a file:// remote. It is for a test's local repository; production
-// code does not pass it, and FetchCommit then refuses anything but ssh://.
-func AllowFileRemote() Option { return func(o *fetchOptions) { o.allowFile = true } }
-
-// WithMirror makes FetchCommit (and MergeInto) borrow objects from mirror, a bare repository that UpdateMirror keeps
-// in the build module's own cache (novox/hq ADR 0536 §2; issue 890): the workspace's .git/objects/info/alternates
-// names the mirror's objects directory, so git transfers only the objects the mirror lacks. It is a plain file, never
-// a symlink. mirror must be an absolute path of an existing directory; the workspace never writes to it.
-func WithMirror(mirror string) Option { return func(o *fetchOptions) { o.mirror = mirror } }
-
-// useMirror writes the alternates file of the repository in dir, when a mirror is set.
-func useMirror(o fetchOptions, dir string) error {
-	if o.mirror == "" {
-		return nil
-	}
-	info := filepath.Join(dir, ".git", "objects", "info")
-	if err := os.MkdirAll(info, 0o755); err != nil {
-		return fmt.Errorf("buildstep: the mirror cannot be used: %w", err)
-	}
-	line := filepath.Join(o.mirror, "objects") + "\n"
-	if err := os.WriteFile(filepath.Join(info, "alternates"), []byte(line), 0o644); err != nil {
-		return fmt.Errorf("buildstep: the mirror cannot be used: %w", err)
-	}
-	return nil
-}
-
-var (
-	commitOK = regexp.MustCompile(`^[0-9a-f]{40}$`)
-	refOK    = regexp.MustCompile(`^refs/[A-Za-z0-9._/-]+$`)
-)
-
-// FetchCommit fetches one commit of a forge repository into dir, an empty directory, and checks it out detached
-// (novox/hq ADR 0466 §4, §5; issue 1474). remote is ssh://<ssh name>/<owner>/<repo>.git, the ssh name being the
-// one the build module's templates set up (ADR 0409 §1); commit is a full 40-hex sha; ref is optional, and names
-// the pull request's head (refs/pull/<n>/head) when the commit is only there. Every git command runs through run
-// as `git -C dir ...` with GIT_TERMINAL_PROMPT=0 and no credential helper, so nothing is asked for and no
-// credential is used. A remote that is not ssh://, or one with user information, and a commit that is not 40
-// hex digits are refused before anything runs.
-func FetchCommit(ctx context.Context, run forgekey.Runner, dir, remote, commit, ref string, opts ...Option) error {
-	var o fetchOptions
-	for _, opt := range opts {
-		opt(&o)
-	}
-	if err := checkFetch(o, dir, remote, commit, ref); err != nil {
-		return err
-	}
-	env := []string{"GIT_TERMINAL_PROMPT=0"}
-	git := func(args ...string) (string, error) {
-		full := append([]string{"-c", "credential.helper=", "-C", dir}, args...)
-		r := run(ctx, env, "git", full...)
-		if r.Status != 0 || r.Err != "" {
-			return "", fmt.Errorf("git %s: %s", args[0], forgekey.Said(r.Err+"\n"+r.Stderr))
-		}
-		return r.Stdout, nil
-	}
-	if _, err := git("init", "-q"); err != nil {
-		return err
-	}
-	if err := useMirror(o, dir); err != nil {
-		return err
-	}
-	if _, err := git("remote", "add", "origin", remote); err != nil {
-		return err
-	}
-	if _, err := git("fetch", "--no-tags", "--depth", "1", "origin", commit); err != nil {
-		if ref == "" {
-			return err
-		}
-		if _, rerr := git("fetch", "--no-tags", "origin", ref); rerr != nil {
-			return fmt.Errorf("%v; then the ref %s: %w", err, ref, rerr)
-		}
-		if _, verr := git("cat-file", "-e", commit+"^{commit}"); verr != nil {
-			return fmt.Errorf("the commit %s is not in %s: %w", commit, ref, verr)
-		}
-	}
-	if _, err := git("checkout", "-q", "--detach", commit); err != nil {
-		return err
-	}
-	out, err := git("rev-parse", "HEAD")
-	if err != nil {
-		return err
-	}
-	if head := strings.TrimSpace(out); head != commit {
-		return fmt.Errorf("the checkout is at %s, not at the commit %s", head, commit)
-	}
-	return nil
-}
-
-// UpdateMirror brings the bare repository mirror to commit: it makes the mirror when it is absent (git init --bare,
-// origin set to remote), then fetches the commit, or the ref when only the ref holds it, with the same rules as
-// FetchCommit (no prompt, no credential helper, ssh:// or an allowed file:// remote, a 40-hex commit). The mirror
-// keeps every commit it was brought to, so later fetches through WithMirror transfer only what is new. Callers
-// serialise updates of one mirror.
-func UpdateMirror(ctx context.Context, run forgekey.Runner, mirror, remote, commit, ref string, opts ...Option) error {
-	var o fetchOptions
-	for _, opt := range opts {
-		opt(&o)
-	}
-	if !filepath.IsAbs(mirror) {
-		return fmt.Errorf("buildstep: the mirror %q is not an absolute path", mirror)
-	}
-	if err := checkFetch(o, mirror, remote, commit, ref); err != nil {
-		return err
-	}
-	env := []string{"GIT_TERMINAL_PROMPT=0"}
-	git := func(args ...string) error {
-		r := run(ctx, env, "git", append([]string{"-c", "credential.helper="}, args...)...)
-		if r.Status != 0 || r.Err != "" {
-			verb := args[0]
-			if verb == "-C" && len(args) > 2 { // the mirror's commands are named by what they do, not by -C
-				verb = args[2]
-			}
-			return fmt.Errorf("git %s: %s", verb, forgekey.Said(r.Err+"\n"+r.Stderr))
-		}
-		return nil
-	}
-	in := func(args ...string) error { return git(append([]string{"-C", mirror}, args...)...) }
-	if _, err := os.Stat(filepath.Join(mirror, "HEAD")); err != nil {
-		if err := git("init", "-q", "--bare", mirror); err != nil {
-			return err
-		}
-		if err := in("remote", "add", "origin", remote); err != nil {
-			return err
-		}
-	} else if err := in("remote", "set-url", "origin", remote); err != nil {
-		return err
-	}
-	if err := in("fetch", "--no-tags", "origin", commit); err != nil {
-		if ref == "" {
-			return err
-		}
-		if rerr := in("fetch", "--no-tags", "origin", ref); rerr != nil {
-			return fmt.Errorf("%v; then the ref %s: %w", err, ref, rerr)
-		}
-	}
-	if err := in("cat-file", "-e", commit+"^{commit}"); err != nil {
-		return fmt.Errorf("the commit %s is not in the mirror: %w", commit, err)
-	}
-	return nil
-}
-
-func checkFetch(o fetchOptions, dir, remote, commit, ref string) error {
-	if dir == "" {
-		return fmt.Errorf("buildstep: no workspace directory")
-	}
-	if o.mirror != "" {
-		if !filepath.IsAbs(o.mirror) {
-			return fmt.Errorf("buildstep: the mirror %q is not an absolute path", o.mirror)
-		}
-		if fi, err := os.Stat(o.mirror); err != nil || !fi.IsDir() {
-			return fmt.Errorf("buildstep: the mirror %q is not an existing directory", o.mirror)
-		}
-	}
-	if !commitOK.MatchString(commit) {
-		return fmt.Errorf("buildstep: %q is not a full commit (40 hex digits)", commit)
-	}
-	if ref != "" && !refOK.MatchString(ref) {
-		return fmt.Errorf("buildstep: %q is not a ref (refs/...)", ref)
-	}
-	u, err := url.Parse(remote)
-	if err != nil {
-		return fmt.Errorf("buildstep: the remote is not a URL: %w", err)
-	}
-	if u.User != nil {
-		return fmt.Errorf("buildstep: the remote carries user information; the key is the credential")
-	}
-	switch {
-	case u.Scheme == "ssh" && u.Host != "":
-	case u.Scheme == "file" && o.allowFile:
-	default:
-		return fmt.Errorf("buildstep: the remote %q is not ssh://", remote)
-	}
-	return nil
-}

go/buildstep/fetch_integration_test.go

@@ -1,59 +0,0 @@
-//go:build integration
-
-package buildstep
-
-import (
-	"context"
-	"os"
-	"os/exec"
-	"path/filepath"
-	"strings"
-	"testing"
-
-	"git.novox.be/novox/mesh-sdk/go/forgekey"
-)
-
-func gitIn(t *testing.T, dir string, args ...string) string {
-	t.Helper()
-	cmd := exec.Command("git", append([]string{"-C", dir, "-c", "user.name=t", "-c", "user.email=t@example.invalid"}, args...)...)
-	out, err := cmd.CombinedOutput()
-	if err != nil {
-		t.Fatalf("git %v: %v\n%s", args, err, out)
-	}
-	return strings.TrimSpace(string(out))
-}
-
-// 1474/AC5: a local bare repository with a commit only under refs/pull/1/head (a file:// remote, allowed by the
-// test-only option): the workspace's HEAD is the commit. The forge itself is proven live after the build
-// modules' delivery (ADR 0466 §5).
-func TestFetchCommitFromAPullRefOnly(t *testing.T) {
-	root := t.TempDir()
-	bare := filepath.Join(root, "r.git")
-	work := filepath.Join(root, "work")
-	for _, d := range []string{bare, work} {
-		if err := os.MkdirAll(d, 0o755); err != nil {
-			t.Fatal(err)
-		}
-	}
-	gitIn(t, bare, "init", "-q", "--bare")
-	gitIn(t, work, "init", "-q")
-	if err := os.WriteFile(filepath.Join(work, "f"), []byte("x"), 0o644); err != nil {
-		t.Fatal(err)
-	}
-	gitIn(t, work, "add", "f")
-	gitIn(t, work, "commit", "-q", "-m", "pull request head")
-	commit := gitIn(t, work, "rev-parse", "HEAD")
-	gitIn(t, work, "push", "-q", bare, "HEAD:refs/pull/1/head")
-
-	ws := filepath.Join(root, "ws")
-	if err := os.MkdirAll(ws, 0o755); err != nil {
-		t.Fatal(err)
-	}
-	err := FetchCommit(context.Background(), forgekey.ExecRunner, ws, "file://"+bare, commit, "refs/pull/1/head", AllowFileRemote())
-	if err != nil {
-		t.Fatal(err)
-	}
-	if head := gitIn(t, ws, "rev-parse", "HEAD"); head != commit {
-		t.Errorf("HEAD = %s, want %s", head, commit)
-	}
-}

go/buildstep/fetch_test.go

@@ -1,137 +0,0 @@
-package buildstep
-
-import (
-	"context"
-	"strings"
-	"testing"
-
-	"git.novox.be/novox/mesh-sdk/go/forgekey"
-)
-
-const sha = "0123456789abcdef0123456789abcdef01234567"
-
-// fakeGit records every command and answers by a rule.
-type fakeGit struct {
-	calls []string
-	envs  [][]string
-	rule  func(args string) forgekey.Ran
-}
-
-func (f *fakeGit) run(ctx context.Context, env []string, name string, args ...string) forgekey.Ran {
-	line := name + " " + strings.Join(args, " ")
-	f.calls = append(f.calls, line)
-	f.envs = append(f.envs, env)
-	if f.rule != nil {
-		if r := f.rule(line); r.Status != 0 || r.Stdout != "" || r.Err != "" {
-			return r
-		}
-	}
-	if len(args) > 4 && args[4] == "rev-parse" {
-		return forgekey.Ran{Stdout: sha + "\n"}
-	}
-	return forgekey.Ran{}
-}
-
-const pre = "git -c credential.helper= -C /w "
-
-// 1474/AC1: the git commands are exactly the sequence, none with a credential or an https remote.
-func TestFetchCommitRunsTheSequence(t *testing.T) {
-	f := &fakeGit{}
-	if err := FetchCommit(context.Background(), f.run, "/w", "ssh://mesh-forge/novox/mesh-sdk.git", sha, ""); err != nil {
-		t.Fatal(err)
-	}
-	want := []string{
-		pre + "init -q",
-		pre + "remote add origin ssh://mesh-forge/novox/mesh-sdk.git",
-		pre + "fetch --no-tags --depth 1 origin " + sha,
-		pre + "checkout -q --detach " + sha,
-		pre + "rev-parse HEAD",
-	}
-	if strings.Join(f.calls, "\n") != strings.Join(want, "\n") {
-		t.Errorf("commands:\n%s\nwant:\n%s", strings.Join(f.calls, "\n"), strings.Join(want, "\n"))
-	}
-	for i, c := range f.calls {
-		if strings.Contains(c, "https://") || strings.Contains(c, "@") || !strings.Contains(c, "credential.helper= ") {
-			t.Errorf("command %q carries a credential or https", c)
-		}
-		if len(f.envs[i]) != 1 || f.envs[i][0] != "GIT_TERMINAL_PROMPT=0" {
-			t.Errorf("env %v", f.envs[i])
-		}
-	}
-}
-
-// 1474/AC2: the depth-1 fetch fails and a pull ref is given: the ref is fetched and the commit verified; with no
-// ref, the fetch's failure is the answer.
-func TestFetchCommitFallsBackToThePullRef(t *testing.T) {
-	f := &fakeGit{rule: func(l string) forgekey.Ran {
-		if strings.Contains(l, "--depth 1") {
-			return forgekey.Ran{Status: 128, Stderr: "fatal: couldn't find remote ref " + sha + "\n"}
-		}
-		return forgekey.Ran{}
-	}}
-	if err := FetchCommit(context.Background(), f.run, "/w", "ssh://mesh-forge/o/r.git", sha, "refs/pull/1/head"); err != nil {
-		t.Fatal(err)
-	}
-	want := []string{pre + "fetch --no-tags origin refs/pull/1/head", pre + "cat-file -e " + sha + "^{commit}", pre + "checkout -q --detach " + sha}
-	got := strings.Join(f.calls[3:6], "\n")
-	if got != strings.Join(want, "\n") {
-		t.Errorf("after the failed fetch:\n%s\nwant:\n%s", got, strings.Join(want, "\n"))
-	}
-
-	g := &fakeGit{rule: f.rule}
-	err := FetchCommit(context.Background(), g.run, "/w", "ssh://mesh-forge/o/r.git", sha, "")
-	if err == nil || !strings.Contains(err.Error(), "couldn't find remote ref") || len(g.calls) != 3 {
-		t.Errorf("without a ref: %v after %d commands", err, len(g.calls))
-	}
-
-	h := &fakeGit{rule: func(l string) forgekey.Ran {
-		if strings.Contains(l, "--depth 1") || strings.Contains(l, "cat-file") {
-			return forgekey.Ran{Status: 1, Stderr: "no"}
-		}
-		return forgekey.Ran{}
-	}}
-	if err := FetchCommit(context.Background(), h.run, "/w", "ssh://mesh-forge/o/r.git", sha, "refs/pull/1/head"); err == nil {
-		t.Error("a commit that is not in the ref was accepted")
-	}
-}
-
-// 1474/AC3: HEAD differs from the commit after the checkout: an error naming both.
-func TestFetchCommitAnswersAHeadThatIsNotTheCommit(t *testing.T) {
-	other := strings.Repeat("a", 40)
-	f := &fakeGit{rule: func(l string) forgekey.Ran {
-		if strings.HasSuffix(l, "rev-parse HEAD") {
-			return forgekey.Ran{Stdout: other + "\n"}
-		}
-		return forgekey.Ran{}
-	}}
-	err := FetchCommit(context.Background(), f.run, "/w", "ssh://mesh-forge/o/r.git", sha, "")
-	if err == nil || !strings.Contains(err.Error(), other) || !strings.Contains(err.Error(), sha) {
-		t.Errorf("error = %v, want both shas", err)
-	}
-}
-
-// 1474/AC4: an https remote, user information, a file remote without the option, or a commit that is not 40
-// hex digits is refused before anything runs.
-func TestFetchCommitRefusesBeforeRunningAnything(t *testing.T) {
-	for _, c := range []struct{ remote, commit, ref string }{
-		{"https://forge.example/o/r.git", sha, ""},
-		{"http://forge.example/o/r.git", sha, ""},
-		{"ssh://git@mesh-forge/o/r.git", sha, ""},
-		{"ssh://user:pw@mesh-forge/o/r.git", sha, ""},
-		{"file:///tmp/r.git", sha, ""},
-		{"/tmp/r.git", sha, ""},
-		{"ssh://mesh-forge/o/r.git", "abc123", ""},
-		{"ssh://mesh-forge/o/r.git", strings.ToUpper(sha), ""},
-		{"ssh://mesh-forge/o/r.git", "main", ""},
-		{"ssh://mesh-forge/o/r.git", sha, "--upload-pack=x"},
-	} {
-		f := &fakeGit{}
-		if err := FetchCommit(context.Background(), f.run, "/w", c.remote, c.commit, c.ref); err == nil || len(f.calls) != 0 {
-			t.Errorf("%+v: err %v, %d commands", c, err, len(f.calls))
-		}
-	}
-	f := &fakeGit{}
-	if err := FetchCommit(context.Background(), f.run, "/w", "file:///tmp/r.git", sha, "", AllowFileRemote()); err != nil {
-		t.Errorf("a file remote with the option: %v", err)
-	}
-}

go/buildstep/guard.go

@@ -1,52 +0,0 @@
-package buildstep
-
-import (
-	"context"
-	"encoding/json"
-	"fmt"
-
-	"git.novox.be/novox/mesh-sdk/go/delivery"
-)
-
-// Guard is a build module's check that the toolchain installed on its node is the one its recipe builds with
-// (novox/hq ADR 0469 §1; issue 1473). The same guard serves ADR 0470 §4's postgres major for the integration
-// level, with its own Probe and Want.
-type Guard struct {
-	// Language is the toolchain's key part: go or typescript (delivery.ToolchainKey).
-	Language string
-	// Want is the toolchain version the recipe builds with, and Recipe the recipe's own version. The indexer
-	// compares both texts as they are written here.
-	Want, Recipe string
-	// Probe reads the installed version (go version, node --version).
-	Probe func(ctx context.Context) (installed string, err error)
-	Node  string
-	// Put is the toolchains state's Put (stdio.State(delivery.ToolchainsState).Put).
-	Put Put
-}
-
-// Check probes the installed version, writes it to <node>.<language> of the toolchains state every time it runs,
-// and answers nil when it is the recipe's. Otherwise it answers a *Refusal naming both versions; the installed
-// version is written even then, so the indexer sees that builders disagree. A probe that fails is a *Refusal
-// naming its failure, and nothing is written. A write that fails is an error that is not a Refusal.
-func (g Guard) Check(ctx context.Context) error {
-	installed, err := g.Probe(ctx)
-	if err != nil {
-		return &Refusal{Text: fmt.Sprintf("the installed %s version could not be read: %v", g.Language, err), Want: g.Want}
-	}
-	key, err := delivery.ToolchainKey(g.Node, g.Language)
-	if err != nil {
-		return err
-	}
-	raw, err := delivery.EncodeToolchain(delivery.Toolchain{Language: g.Language, Version: installed, Recipe: g.Recipe, At: now().UTC()})
-	if err != nil {
-		return err
-	}
-	if _, err := g.Put(key, json.RawMessage(raw)); err != nil {
-		return fmt.Errorf("buildstep: writing the toolchain %s: %w", key, err)
-	}
-	if installed != g.Want {
-		return &Refusal{Text: fmt.Sprintf("%s %s installed, the recipe builds with %s %s", g.Language, installed, g.Language, g.Want),
-			Want: g.Want, Have: installed}
-	}
-	return nil
-}

go/buildstep/guard_test.go

@@ -1,79 +0,0 @@
-package buildstep
-
-import (
-	"context"
-	"encoding/json"
-	"errors"
-	"strings"
-	"testing"
-
-	"git.novox.be/novox/mesh-sdk/go/delivery"
-)
-
-type toolchainKeys map[string]delivery.Toolchain
-
-func (k toolchainKeys) put(key string, value any) (uint64, error) {
-	tc, err := delivery.DecodeToolchain(value.(json.RawMessage))
-	if err != nil {
-		return 0, err
-	}
-	k[key] = tc
-	return uint64(len(k)), nil
-}
-
-func guardFor(k toolchainKeys, installed string, probeErr error) Guard {
-	return Guard{Language: "go", Want: "1.27.0", Recipe: "r7", Node: "ace", Put: k.put,
-		Probe: func(context.Context) (string, error) { return installed, probeErr }}
-}
-
-// 1473/AC1: the probe answers the recipe's version: nil, and <node>.go holds that version and the recipe's.
-func TestCheckPassesAndWritesTheToolchain(t *testing.T) {
-	k := toolchainKeys{}
-	if err := guardFor(k, "1.27.0", nil).Check(context.Background()); err != nil {
-		t.Fatal(err)
-	}
-	tc, ok := k["ace.go"]
-	if !ok || tc.Version != "1.27.0" || tc.Recipe != "r7" || tc.Language != "go" || tc.At.IsZero() {
-		t.Errorf("keys = %+v", k)
-	}
-}
-
-// 1473/AC2: another version: a Refusal naming both, and the key holds the installed version.
-func TestCheckRefusesAnotherVersionAndWritesTheInstalledOne(t *testing.T) {
-	k := toolchainKeys{}
-	err := guardFor(k, "1.27.1", nil).Check(context.Background())
-	var ref *Refusal
-	if !errors.As(err, &ref) {
-		t.Fatalf("Check = %v, want a Refusal", err)
-	}
-	if ref.Text != "go 1.27.1 installed, the recipe builds with go 1.27.0" || ref.Want != "1.27.0" || ref.Have != "1.27.1" {
-		t.Errorf("refusal = %+v", ref)
-	}
-	if k["ace.go"].Version != "1.27.1" {
-		t.Errorf("the key holds %q, want the installed 1.27.1", k["ace.go"].Version)
-	}
-}
-
-// 1473/AC3: a probe that fails: a Refusal naming the failure, and nothing put.
-func TestCheckRefusesAFailedProbeAndPutsNothing(t *testing.T) {
-	k := toolchainKeys{}
-	err := guardFor(k, "", errors.New("go: not found")).Check(context.Background())
-	var ref *Refusal
-	if !errors.As(err, &ref) || !strings.Contains(ref.Text, "go: not found") {
-		t.Fatalf("Check = %v, want a Refusal naming the probe's failure", err)
-	}
-	if len(k) != 0 {
-		t.Errorf("put %v", k)
-	}
-}
-
-// A failed write is an error, not a refusal: the step fails instead of refusing.
-func TestCheckAnswersAFailedWriteAsAnError(t *testing.T) {
-	g := guardFor(toolchainKeys{}, "1.27.0", nil)
-	g.Put = func(string, any) (uint64, error) { return 0, errors.New("no grant") }
-	err := g.Check(context.Background())
-	var ref *Refusal
-	if err == nil || errors.As(err, &ref) {
-		t.Errorf("Check = %v", err)
-	}
-}

go/buildstep/isolate.go

@@ -1,175 +0,0 @@
-package buildstep
-
-import (
-	"context"
-	"fmt"
-	"os"
-	"path"
-	"path/filepath"
-	"strings"
-
-	"git.novox.be/novox/mesh-sdk/go/forgekey"
-)
-
-// Bubblewrap is the program a run step runs in (novox/hq ADR 0448): a build module declares its package, which needs
-// unprivileged user namespaces (issue 1308).
-const Bubblewrap = "bwrap"
-
-// Isolation is how a run step's command is shut off (novox/hq ADR 0448; issue 1309, the lead's decision L2 of R4e: one
-// runner in the SDK for every build module). The fetch step holds the forge key and the network and runs none of the
-// change's code; the run step runs the change's build and tests in bubblewrap with:
-//
-//   - no network: its own network namespace, with only a loopback, so a test may start a bus or a store of its own but
-//     resolves no name and reaches no socket of the machine;
-//   - none of the account: not its home, not the forge key, not a bus login, not the runtime directory (/run), since
-//     none of them is bound; HOME is a directory in the step's own /tmp unless Env names one;
-//   - an environment of exactly Env and the runner's env: nothing of the build module's own passes;
-//   - the system's programs and libraries read-only, and of /etc only what a program needs to run (users, libraries,
-//     certificates, time zone), with a hosts file naming only the loopback;
-//   - the Workspace and Writable directories read-write, the ReadOnly ones (the toolchain, the modules the fetch step
-//     downloaded) read-only;
-//   - the shared warm Caches read-only under a throwaway writable layer (S18), or read-write for a trunk build alone
-//     (WriteCaches), so a candidate's code never changes what a later build reads.
-type Isolation struct {
-	Workspace   string
-	Writable    []string
-	ReadOnly    []string
-	Caches      []string
-	WriteCaches bool
-	Env         []string
-	// Hosts is the file bound as /etc/hosts; Isolated writes one naming only the loopback.
-	Hosts string
-}
-
-// etcNeeded is what of /etc a program in the step may read: who the users are, where the libraries are, the
-// certificates, the time zone. Not resolv.conf, not hosts: the step resolves no name.
-var etcNeeded = []string{"/etc/passwd", "/etc/group", "/etc/nsswitch.conf", "/etc/ld.so.cache", "/etc/ld.so.conf",
-	"/etc/ld.so.conf.d", "/etc/ssl", "/etc/ca-certificates", "/etc/pki", "/etc/localtime", "/etc/os-release", "/etc/alternatives"}
-
-// systemArgs binds the system's programs and libraries read-only: /usr, and /bin, /sbin, /lib, /lib64 as the symlinks
-// they are on a merged-usr system, or bound when they are directories. A variable so a unit test fixes it.
-var systemArgs = func() []string {
-	args := []string{"--ro-bind", "/usr", "/usr"}
-	for _, d := range []string{"/bin", "/sbin", "/lib", "/lib64"} {
-		info, err := os.Lstat(d)
-		switch {
-		case err != nil:
-		case info.Mode()&os.ModeSymlink != 0:
-			if target, err := os.Readlink(d); err == nil {
-				args = append(args, "--symlink", target, d)
-			}
-		case info.IsDir():
-			args = append(args, "--ro-bind", d, d)
-		}
-	}
-	for _, e := range etcNeeded {
-		args = append(args, "--ro-bind-try", e, e)
-	}
-	return args
-}
-
-// stepHome is the HOME of a step that is given none: inside its own /tmp, gone with it.
-const stepHome = "/tmp/home"
-
-func checkDir(what, dir string) error {
-	if dir == "" || !strings.HasPrefix(dir, "/") || path.Clean(dir) != dir || dir == "/" {
-		return fmt.Errorf("buildstep: the %s %q is not an absolute, clean directory other than the root", what, dir)
-	}
-	return nil
-}
-
-// Command is the bubblewrap command line that runs name with args shut off as iso says, env added to iso.Env. It
-// refuses a directory that is not absolute and clean, or is the root, and an environment word without "=".
-func (iso Isolation) Command(name string, args ...string) ([]string, error) {
-	return iso.command(nil, name, args...)
-}
-
-func (iso Isolation) command(env []string, name string, args ...string) ([]string, error) {
-	if err := checkDir("workspace", iso.Workspace); err != nil {
-		return nil, err
-	}
-	for _, group := range []struct {
-		what string
-		dirs []string
-	}{{"writable directory", iso.Writable}, {"read-only directory", iso.ReadOnly}, {"cache", iso.Caches}} {
-		for _, d := range group.dirs {
-			if err := checkDir(group.what, d); err != nil {
-				return nil, err
-			}
-		}
-	}
-	words := append(append([]string{}, iso.Env...), env...)
-	home := false
-	for _, w := range words {
-		k, _, ok := strings.Cut(w, "=")
-		if !ok || k == "" {
-			return nil, fmt.Errorf("buildstep: the environment word %q is not NAME=value", w)
-		}
-		home = home || k == "HOME"
-	}
-	argv := []string{"--unshare-all", "--die-with-parent", "--new-session", "--clearenv",
-		"--proc", "/proc", "--dev", "/dev", "--tmpfs", "/tmp", "--dir", stepHome}
-	argv = append(argv, systemArgs()...)
-	for _, d := range iso.ReadOnly {
-		argv = append(argv, "--ro-bind", d, d)
-	}
-	argv = append(argv, cacheArgs(iso.Caches, iso.WriteCaches)...)
-	argv = append(argv, "--bind", iso.Workspace, iso.Workspace)
-	for _, d := range iso.Writable {
-		argv = append(argv, "--bind", d, d)
-	}
-	if iso.Hosts != "" {
-		argv = append(argv, "--ro-bind", iso.Hosts, "/etc/hosts")
-	}
-	for _, w := range words {
-		k, v, _ := strings.Cut(w, "=")
-		argv = append(argv, "--setenv", k, v)
-	}
-	if !home {
-		argv = append(argv, "--setenv", "HOME", stepHome)
-	}
-	argv = append(argv, "--chdir", iso.Workspace, "--", name)
-	return append(argv, args...), nil
-}
-
-// cacheArgs binds the shared warm caches (S18): for a trunk build read-write, so the next build is warm; for any other
-// read-only beneath an overlay whose writes go to a tmpfs of the step's own, so the step writes as a build does and
-// nothing it wrote outlives it (bubblewrap's --tmp-overlay, an overlay mount in the step's user namespace).
-func cacheArgs(caches []string, write bool) []string {
-	var argv []string
-	for _, c := range caches {
-		if write {
-			argv = append(argv, "--bind", c, c)
-			continue
-		}
-		argv = append(argv, "--overlay-src", c, "--tmp-overlay", c)
-	}
-	return argv
-}
-
-// loopbackHosts is the hosts file of a step: the loopback and nothing else.
-const loopbackHosts = "127.0.0.1 localhost\n::1 localhost\n"
-
-// Isolated is run with every command shut off as iso says (Command), run's env going inside the step: the build modules'
-// run steps call their test, build and digest commands through it, never run itself. Each command gets a hosts file of
-// its own, naming only the loopback, removed when it ends.
-func Isolated(run forgekey.Runner, iso Isolation) forgekey.Runner {
-	return func(ctx context.Context, env []string, name string, args ...string) forgekey.Ran {
-		dir, err := os.MkdirTemp("", "step-hosts-")
-		if err != nil {
-			return forgekey.Ran{Status: 1, Err: "the step's hosts file: " + err.Error()}
-		}
-		defer os.RemoveAll(dir)
-		hosts := filepath.Join(dir, "hosts")
-		if err := os.WriteFile(hosts, []byte(loopbackHosts), 0o644); err != nil {
-			return forgekey.Ran{Status: 1, Err: "the step's hosts file: " + err.Error()}
-		}
-		iso := iso
-		iso.Hosts = hosts
-		argv, err := iso.command(env, name, args...)
-		if err != nil {
-			return forgekey.Ran{Status: 1, Err: err.Error()}
-		}
-		return run(ctx, nil, Bubblewrap, argv...)
-	}
-}

go/buildstep/isolate_caches_test.go

@@ -1,30 +0,0 @@
-package buildstep
-
-import "testing"
-
-// The shared warm caches are read under a throwaway writable layer (novox/hq ADR 0448; issue 1309): a candidate's step
-// writes into them as a build does, and nothing it writes outlives it or reaches a later build; only a trunk build
-// writes them.
-func TestACandidatesStepWritesTheCachesOnlyIntoAThrowawayLayer(t *testing.T) {
-	fixedSystem(t)
-	iso := Isolation{Workspace: "/w", Caches: []string{"/var/cache/go-build", "/var/cache/npm"}}
-	argv, err := iso.Command("go", "test")
-	if err != nil {
-		t.Fatal(err)
-	}
-	for _, c := range iso.Caches {
-		if !holds(argv, "--overlay-src", c, "--tmp-overlay", c) {
-			t.Errorf("the cache %s is not under a throwaway layer: %v", c, argv)
-		}
-		if holds(argv, "--bind", c, c) {
-			t.Errorf("a candidate's step writes the cache %s: %v", c, argv)
-		}
-	}
-	iso.WriteCaches = true
-	argv, _ = iso.Command("go", "build")
-	for _, c := range iso.Caches {
-		if !holds(argv, "--bind", c, c) || holds(argv, "--tmp-overlay", c) {
-			t.Errorf("a trunk build does not write the cache %s: %v", c, argv)
-		}
-	}
-}

go/buildstep/isolate_integration_test.go

@@ -1,66 +0,0 @@
-//go:build integration && isolation
-
-package buildstep
-
-import (
-	"context"
-	"net"
-	"os"
-	"os/exec"
-	"path/filepath"
-	"strings"
-	"testing"
-
-	"git.novox.be/novox/mesh-sdk/go/forgekey"
-)
-
-// 1309/S19, the issue's proof: a run step, in bubblewrap as Isolated runs it, reads no key and no login, resolves no
-// name, reaches no TCP or unix socket of the machine, finds no home of the account, and leaves the shared cache it
-// wrote unchanged; the workspace it writes keeps what it wrote. It needs bubblewrap and unprivileged user namespaces
-// (issue 1308) on the machine that runs it, and fails naming them when they are not there.
-func TestARunStepReachesNothingAndLeavesTheCachesUnchanged(t *testing.T) {
-	if _, err := exec.LookPath(Bubblewrap); err != nil {
-		t.Fatalf("bubblewrap is not installed here, so the isolation of a run step cannot be proved (issue 1309): %v", err)
-	}
-	root := t.TempDir()
-	account := filepath.Join(root, "account")
-	key, login := filepath.Join(account, ".ssh", "id_ed25519"), filepath.Join(account, "bus-login.json")
-	writeFile(t, filepath.Dir(key), filepath.Base(key), "PRIVATE KEY")
-	writeFile(t, account, "bus-login.json", `{"password":"secret"}`)
-	cacheDir := filepath.Join(root, "cache")
-	writeFile(t, cacheDir, "warm", "warm\n")
-	workspace := filepath.Join(root, "work", "tree")
-	if err := os.MkdirAll(workspace, 0o755); err != nil {
-		t.Fatal(err)
-	}
-	probe := filepath.Join(workspace, "probe")
-	if out, err := exec.Command("go", "build", "-o", probe, "./testdata/isolated-probe").CombinedOutput(); err != nil {
-		t.Fatalf("building the probe: %v\n%s", err, out)
-	}
-	tcp, err := net.Listen("tcp", "127.0.0.1:0")
-	if err != nil {
-		t.Fatal(err)
-	}
-	defer tcp.Close()
-	socket := filepath.Join(account, "bus.sock")
-	unix, err := net.Listen("unix", socket)
-	if err != nil {
-		t.Fatal(err)
-	}
-	defer unix.Close()
-
-	run := Isolated(forgekey.ExecRunnerFor(0), Isolation{Workspace: workspace, Caches: []string{cacheDir}})
-	r := run(context.Background(), []string{"PATH=/usr/bin:/bin"}, probe, key, login, tcp.Addr().String(), socket, "localhost.localdomain.invalid", filepath.Join(cacheDir, "warm"))
-	if r.Status != 0 || r.Err != "" || strings.TrimSpace(r.Stdout) != "shut off" {
-		t.Fatalf("the run step was not shut off (status %d, %s):\n%s%s", r.Status, r.Err, r.Stdout, r.Stderr)
-	}
-	if b, _ := os.ReadFile(filepath.Join(cacheDir, "warm")); string(b) != "warm\n" {
-		t.Fatalf("the step changed the shared cache: %q", b)
-	}
-
-	// The workspace is the step's own: what it writes there stays.
-	r = run(context.Background(), nil, "/bin/sh", "-c", "echo built > out")
-	if b, err := os.ReadFile(filepath.Join(workspace, "out")); r.Status != 0 || err != nil || string(b) != "built\n" {
-		t.Fatalf("the step's write to its workspace did not stay (status %d, %s%s): %q %v", r.Status, r.Stderr, r.Err, b, err)
-	}
-}

go/buildstep/isolate_test.go

@@ -1,115 +0,0 @@
-package buildstep
-
-import (
-	"context"
-	"strings"
-	"testing"
-
-	"git.novox.be/novox/mesh-sdk/go/forgekey"
-)
-
-// pairs says whether argv holds the words of want one after another.
-func holds(argv []string, want ...string) bool {
-	for i := 0; i+len(want) <= len(argv); i++ {
-		match := true
-		for j, w := range want {
-			if argv[i+j] != w {
-				match = false
-				break
-			}
-		}
-		if match {
-			return true
-		}
-	}
-	return false
-}
-
-func fixedSystem(t *testing.T) {
-	t.Helper()
-	before := systemArgs
-	systemArgs = func() []string { return []string{"--ro-bind", "/usr", "/usr", "--symlink", "usr/bin", "/bin"} }
-	t.Cleanup(func() { systemArgs = before })
-}
-
-// A run step's command runs in bubblewrap (novox/hq ADR 0448; issue 1309): no network, no namespace shared, an
-// environment of exactly what the step is given, the workspace the one tree it writes, the toolchain read-only, and
-// nothing else of the machine's: not the account's home, not the forge key or a bus login, not the runtime directory,
-// and no name service.
-func TestARunStepRunsShutOffInBubblewrap(t *testing.T) {
-	fixedSystem(t)
-	iso := Isolation{Workspace: "/work/ab12/tree", ReadOnly: []string{"/usr/lib/go"}, Writable: []string{"/work/ab12/out"},
-		Env: []string{"GOFLAGS=-mod=mod", "PATH=/usr/bin"}, Hosts: "/work/ab12/hosts"}
-	argv, err := iso.Command("go", "test", "./...")
-	if err != nil {
-		t.Fatal(err)
-	}
-	for _, want := range [][]string{
-		{"--unshare-all"}, {"--die-with-parent"}, {"--new-session"}, {"--clearenv"},
-		{"--proc", "/proc"}, {"--dev", "/dev"}, {"--tmpfs", "/tmp"},
-		{"--ro-bind", "/usr", "/usr"}, {"--symlink", "usr/bin", "/bin"},
-		{"--ro-bind", "/usr/lib/go", "/usr/lib/go"},
-		{"--bind", "/work/ab12/tree", "/work/ab12/tree"}, {"--bind", "/work/ab12/out", "/work/ab12/out"},
-		{"--ro-bind", "/work/ab12/hosts", "/etc/hosts"},
-		{"--setenv", "GOFLAGS", "-mod=mod"}, {"--setenv", "PATH", "/usr/bin"}, {"--setenv", "HOME", "/tmp/home"},
-		{"--chdir", "/work/ab12/tree"},
-		{"--", "go", "test", "./..."},
-	} {
-		if !holds(argv, want...) {
-			t.Errorf("the command has no %v: %v", want, argv)
-		}
-	}
-	if holds(argv, "--share-net") || strings.Contains(strings.Join(argv, " "), "resolv.conf") || strings.Contains(strings.Join(argv, " "), "/run") {
-		t.Errorf("the command reaches the network, the name service or the runtime directory: %v", argv)
-	}
-	// The workspace is mounted after /tmp's tmpfs, so a workspace under /tmp is not hidden by it.
-	if strings.Index(strings.Join(argv, "\x00"), "--tmpfs\x00/tmp") > strings.Index(strings.Join(argv, "\x00"), "--bind\x00/work/ab12/tree") {
-		t.Errorf("the tmpfs of /tmp comes after the workspace: %v", argv)
-	}
-	// A HOME the step is given is its own.
-	iso.Env = append(iso.Env, "HOME=/work/ab12/home")
-	argv, _ = iso.Command("true")
-	if holds(argv, "--setenv", "HOME", "/tmp/home") || !holds(argv, "--setenv", "HOME", "/work/ab12/home") {
-		t.Errorf("the step's own HOME was replaced: %v", argv)
-	}
-}
-
-func TestAnIsolationNamesNoPathItCannotPin(t *testing.T) {
-	for _, iso := range []Isolation{
-		{Workspace: ""},
-		{Workspace: "tree"},
-		{Workspace: "/"},
-		{Workspace: "/w", ReadOnly: []string{"relative"}},
-		{Workspace: "/w", Writable: []string{"/"}},
-		{Workspace: "/w", Caches: []string{"/a/../b"}},
-		{Workspace: "/w", Env: []string{"NOEQUALS"}},
-	} {
-		if _, err := iso.Command("true"); err == nil {
-			t.Errorf("%+v was accepted", iso)
-		}
-	}
-}
-
-// Isolated runs every command through bwrap, with the step's environment inside and a hosts file that names only the
-// loopback, removed after.
-func TestIsolatedRunsEachCommandThroughBubblewrap(t *testing.T) {
-	fixedSystem(t)
-	var ran []string
-	var hosts string
-	inner := func(ctx context.Context, env []string, name string, args ...string) forgekey.Ran {
-		ran = append([]string{name}, args...)
-		for i, a := range args {
-			if a == "/etc/hosts" && i > 0 {
-				hosts = args[i-1]
-			}
-		}
-		return forgekey.Ran{Stdout: "ok"}
-	}
-	r := Isolated(inner, Isolation{Workspace: "/w"})(context.Background(), []string{"A=1"}, "go", "build")
-	if r.Stdout != "ok" || ran[0] != Bubblewrap || !holds(ran, "--setenv", "A", "1") || !holds(ran, "--", "go", "build") {
-		t.Fatalf("ran %v: %+v", ran, r)
-	}
-	if hosts == "" {
-		t.Fatalf("no hosts file was bound: %v", ran)
-	}
-}

go/buildstep/launchers_test.go

@@ -1,22 +0,0 @@
-package buildstep
-
-import (
-	"reflect"
-	"testing"
-)
-
-// A TypeScript bundle's entrypoint x.js is started as x.serve.mjs beside it (novox/hq ADR 0193), the rule mesh-build-node
-// and build-agent both apply; an entrypoint that is not .js gets none, and another language gets none.
-func TestATypeScriptEntrypointIsStartedByTheLauncherBesideIt(t *testing.T) {
-	got := Launchers("typescript", []string{"index.js", "tools/x.js", "data.json"})
-	want := map[string]string{"index.js": "index.serve.mjs", "tools/x.js": "tools/x.serve.mjs"}
-	if !reflect.DeepEqual(got, want) {
-		t.Fatalf("Launchers(typescript) = %v, want %v", got, want)
-	}
-	if got := Launchers("go", []string{"index.js"}); len(got) != 0 {
-		t.Fatalf("a Go bundle got launchers: %v", got)
-	}
-	if got := Launchers("typescript", nil); len(got) != 0 {
-		t.Fatalf("a bundle with no entrypoint got launchers: %v", got)
-	}
-}

go/buildstep/merge.go

@@ -1,128 +0,0 @@
-package buildstep
-
-import (
-	"context"
-	"fmt"
-	"strings"
-
-	"git.novox.be/novox/mesh-sdk/go/forgekey"
-)
-
-// MergeResult is what MergeInto made of a head and a trunk commit: the trunk commit (Base) and the head, whole, and the
-// merge commit and the paths the merge changes against the trunk commit; or, when the head does not merge cleanly, the
-// files in conflict, with Merge and Changed empty.
-type MergeResult struct {
-	Base, Head, Merge string
-	Conflicts         []string
-	Changed           []string
-	// Programs are the changed files that are compiled programs (ExecutableKind of their first bytes, read in the workspace
-	// at the merge); never nil for a clean merge, so a caller tells none from a module that reports none (issue 1577).
-	Programs []Program
-}
-
-// MergeInto makes, in the workspace dir that FetchCommit left at commit, the merge of commit into the trunk commit
-// base, as the forge's default merge would (a merge commit, never a fast-forward), and leaves the workspace at the merge
-// (novox/hq ADR 0484 clause 3, ADR 0323). It is the one merge the build modules' fetch steps make, with the identity
-// and flags of the controller's check merge (mesh-controller internal/builder/check_merge.go): a name nobody owns, no
-// signature, no hook, nothing of the machine's git configuration that changes a merge. Nothing is pushed.
-//
-// A merge needs both histories, so it makes the fetch whole (the shallow clone FetchCommit made is deepened) and
-// fetches base by its sha. A head that does not merge cleanly is an answer, not an error: the files in conflict, the
-// merge undone and the workspace left at base. A head already in base answers a Merge equal to Base and no changed
-// paths. An error is that the merge could not be tried: a base or commit that is not a full sha, no base, a workspace
-// not at commit, or a fetch or git command that failed. remote and the options are those of FetchCommit; the runner's
-// bound must allow a whole fetch.
-func MergeInto(ctx context.Context, run forgekey.Runner, dir, remote, base, commit string, opts ...Option) (MergeResult, error) {
-	var o fetchOptions
-	for _, opt := range opts {
-		opt(&o)
-	}
-	res := MergeResult{Base: base, Head: commit}
-	if base == "" {
-		return res, fmt.Errorf("buildstep: no base: a merge needs the trunk commit it is made onto")
-	}
-	if err := checkFetch(o, dir, remote, base, ""); err != nil {
-		return res, err
-	}
-	if err := checkFetch(o, dir, remote, commit, ""); err != nil {
-		return res, err
-	}
-	if err := useMirror(o, dir); err != nil {
-		return res, err
-	}
-	env := []string{"GIT_TERMINAL_PROMPT=0"}
-	git := func(args ...string) (string, error) {
-		full := append([]string{"-c", "credential.helper=", "-C", dir}, args...)
-		r := run(ctx, env, "git", full...)
-		if r.Status != 0 || r.Err != "" {
-			return "", fmt.Errorf("git %s: %s", args[0], forgekey.Said(r.Err+"\n"+r.Stderr))
-		}
-		return r.Stdout, nil
-	}
-	at, err := git("rev-parse", "HEAD")
-	if err != nil {
-		return res, err
-	}
-	if head := strings.TrimSpace(at); head != commit {
-		return res, fmt.Errorf("buildstep: the workspace is at %s, not at the commit %s", head, commit)
-	}
-	shallow, err := git("rev-parse", "--is-shallow-repository")
-	if err != nil {
-		return res, err
-	}
-	fetch := []string{"fetch", "--no-tags", "origin", base}
-	if strings.TrimSpace(shallow) == "true" {
-		fetch = []string{"fetch", "--no-tags", "--unshallow", "origin", base}
-	}
-	if _, err := git(fetch...); err != nil {
-		return res, fmt.Errorf("the trunk commit %s: %w", base, err)
-	}
-	if _, err := git("checkout", "-q", "--detach", base); err != nil {
-		return res, fmt.Errorf("the trunk commit %s cannot be checked out: %w", base, err)
-	}
-	message := fmt.Sprintf("Check the merge of %s into %s (made for a check, never pushed)", short(commit), short(base))
-	args := append(append([]string{}, mergeIdentity...), "merge", "--no-ff", "--no-edit", "--no-verify", "--quiet", "-m", message, commit)
-	if _, err := git(args...); err != nil {
-		out, _ := git("diff", "--name-only", "--diff-filter=U")
-		res.Conflicts = strings.Fields(out)
-		_, _ = git("merge", "--abort")
-		if len(res.Conflicts) == 0 {
-			return res, fmt.Errorf("the head %s could not be merged into the trunk commit %s: %w", short(commit), short(base), err)
-		}
-		return res, nil
-	}
-	merge, err := git("rev-parse", "HEAD")
-	if err != nil {
-		return res, fmt.Errorf("the merge cannot be read: %w", err)
-	}
-	res.Merge = strings.TrimSpace(merge)
-	changed, err := git("diff", "--name-only", "--no-renames", base, res.Merge)
-	if err != nil {
-		return res, fmt.Errorf("the paths the merge changes cannot be read: %w", err)
-	}
-	res.Changed = strings.Fields(changed)
-	raw, err := git("diff", "--raw", "-z", "--no-renames", "--diff-filter=AM", base, res.Merge)
-	if err != nil {
-		return res, fmt.Errorf("the files the merge adds or modifies cannot be read: %w", err)
-	}
-	res.Programs = programsIn(dir, raw)
-	history, err := historyPrograms(git, base, commit, res.Programs)
-	if err != nil {
-		return res, fmt.Errorf("the commits of the branch cannot be read for compiled programs: %w", err)
-	}
-	res.Programs = append(res.Programs, history...)
-	return res, nil
-}
-
-// mergeIdentity is who a check's merge is made as: it is never pushed, so it names nobody's account. No hook of the
-// clone's or the build machine's git configuration runs, and no setting there changes the merge (the controller's
-// check merge, internal/builder/check_merge.go).
-var mergeIdentity = []string{"-c", "user.name=mesh merge check", "-c", "user.email=merge-check@mesh.invalid",
-	"-c", "commit.gpgsign=false", "-c", "core.hooksPath=/dev/null", "-c", "merge.verifySignatures=false"}
-
-func short(commit string) string {
-	if len(commit) > 12 {
-		return commit[:12]
-	}
-	return commit
-}

go/buildstep/merge_integration_test.go

@@ -1,199 +0,0 @@
-//go:build integration
-
-package buildstep
-
-import (
-	"context"
-	"os"
-	"os/exec"
-	"path/filepath"
-	"reflect"
-	"strings"
-	"testing"
-
-	"git.novox.be/novox/mesh-sdk/go/forgekey"
-)
-
-// The merge on real git repositories starts git processes, so it is an integration test (the unit level keeps its bound,
-// issue 895); the unit tests of merge_test.go prove the commands and the refusals with a fake runner.
-
-func realGit(t *testing.T, dir string, args ...string) string {
-	t.Helper()
-	cmd := exec.Command("git", append([]string{"-C", dir, "-c", "user.name=t", "-c", "user.email=t@example.invalid", "-c", "commit.gpgsign=false"}, args...)...)
-	out, err := cmd.CombinedOutput()
-	if err != nil {
-		t.Fatalf("git %v: %v\n%s", args, err, out)
-	}
-	return strings.TrimSpace(string(out))
-}
-
-func writeFile(t *testing.T, dir, name, content string) {
-	t.Helper()
-	p := filepath.Join(dir, name)
-	if err := os.MkdirAll(filepath.Dir(p), 0o755); err != nil {
-		t.Fatal(err)
-	}
-	if err := os.WriteFile(p, []byte(content), 0o644); err != nil {
-		t.Fatal(err)
-	}
-}
-
-// mergeRig is a local bare repository standing in for the forge, a work repository that pushes to it, and an empty
-// workspace: the fetch step's shape (FetchCommit of the head into the workspace, then MergeInto).
-type mergeRig struct {
-	t              *testing.T
-	bare, work, ws string
-	fork, trunk    string // the commit both histories share, and the trunk's head
-	remote         string
-}
-
-func newMergeRig(t *testing.T) *mergeRig {
-	root := t.TempDir()
-	r := &mergeRig{t: t, bare: filepath.Join(root, "r.git"), work: filepath.Join(root, "work"), ws: filepath.Join(root, "ws")}
-	for _, d := range []string{r.bare, r.work, r.ws} {
-		if err := os.MkdirAll(d, 0o755); err != nil {
-			t.Fatal(err)
-		}
-	}
-	r.remote = "file://" + r.bare
-	realGit(t, r.bare, "init", "-q", "--bare")
-	realGit(t, r.work, "init", "-q", "-b", "main")
-	writeFile(t, r.work, "a.txt", "one\ntwo\nthree\n")
-	writeFile(t, r.work, "modules/m/module.json", "{}\n")
-	realGit(t, r.work, "add", ".")
-	realGit(t, r.work, "commit", "-q", "-m", "fork point")
-	r.fork = realGit(t, r.work, "rev-parse", "HEAD")
-	return r
-}
-
-// head makes a commit on a branch off the fork point, pushes it as the pull request's head ref and answers its sha.
-func (r *mergeRig) head(files map[string]string) string {
-	realGit(r.t, r.work, "checkout", "-q", "-B", "pr", r.fork)
-	for n, c := range files {
-		writeFile(r.t, r.work, n, c)
-	}
-	realGit(r.t, r.work, "add", ".")
-	realGit(r.t, r.work, "commit", "-q", "-m", "head")
-	h := realGit(r.t, r.work, "rev-parse", "HEAD")
-	realGit(r.t, r.work, "push", "-q", r.bare, "HEAD:refs/pull/1/head")
-	return h
-}
-
-// headThatAddsAndRemoves is head with an earlier commit on the branch that adds a program and a later one that removes it: the
-// branch's tree is clean, its history is not. It answers the head and the earlier commit.
-func (r *mergeRig) headThatAddsAndRemoves(files map[string]string) (head, added string) {
-	realGit(r.t, r.work, "checkout", "-q", "-B", "pr", r.fork)
-	writeFile(r.t, r.work, "gone/prog", "\x7fELF\x02\x01")
-	realGit(r.t, r.work, "add", ".")
-	realGit(r.t, r.work, "commit", "-q", "-m", "oops")
-	added = realGit(r.t, r.work, "rev-parse", "HEAD")
-	realGit(r.t, r.work, "rm", "-q", "gone/prog")
-	return r.head2(files), added
-}
-
-// head2 commits files on the current branch and pushes it as the pull request's head.
-func (r *mergeRig) head2(files map[string]string) string {
-	for n, c := range files {
-		writeFile(r.t, r.work, n, c)
-	}
-	realGit(r.t, r.work, "add", ".")
-	realGit(r.t, r.work, "commit", "-q", "-m", "head")
-	h := realGit(r.t, r.work, "rev-parse", "HEAD")
-	realGit(r.t, r.work, "push", "-q", r.bare, "HEAD:refs/pull/1/head")
-	return h
-}
-
-// advance moves the trunk past the fork point with a commit changing files, pushes it and answers its sha.
-func (r *mergeRig) advance(files map[string]string) string {
-	realGit(r.t, r.work, "checkout", "-q", "-B", "main", r.fork)
-	for n, c := range files {
-		writeFile(r.t, r.work, n, c)
-	}
-	realGit(r.t, r.work, "add", ".")
-	realGit(r.t, r.work, "commit", "-q", "-m", "trunk moves")
-	r.trunk = realGit(r.t, r.work, "rev-parse", "HEAD")
-	realGit(r.t, r.work, "push", "-q", "-f", r.bare, "HEAD:refs/heads/main")
-	return r.trunk
-}
-
-func (r *mergeRig) fetch(head string) {
-	if err := FetchCommit(context.Background(), forgekey.ExecRunner, r.ws, r.remote, head, "refs/pull/1/head", AllowFileRemote()); err != nil {
-		r.t.Fatal(err)
-	}
-}
-
-// 1674/AC1: a clean merge answers the merge commit and the changed files, and leaves the workspace at the merge, which
-// holds both sides' changes.
-func TestMergeIntoACleanMergeAnswersTheMergeCommitAndTheChangedFiles(t *testing.T) {
-	r := newMergeRig(t)
-	head, added := r.headThatAddsAndRemoves(map[string]string{"b.txt": "head\n", "prog": "\x7fELF\x02\x01"})
-	base := r.advance(map[string]string{"a.txt": "one\ntwo\nthree\nfour\n"})
-	r.fetch(head)
-	res, err := MergeInto(context.Background(), forgekey.ExecRunner, r.ws, r.remote, base, head, AllowFileRemote())
-	if err != nil {
-		t.Fatal(err)
-	}
-	if res.Base != base || res.Head != head || len(res.Merge) != 40 || res.Merge == base || res.Merge == head || len(res.Conflicts) != 0 {
-		t.Fatalf("result = %+v", res)
-	}
-	if !reflect.DeepEqual(res.Changed, []string{"b.txt", "prog"}) {
-		t.Errorf("changed = %v, want only what the head adds to the trunk: b.txt, prog", res.Changed)
-	}
-	if !reflect.DeepEqual(res.Programs, []Program{{"prog", "ELF", ""}, {"gone/prog", "ELF", added}}) { // issue 1577
-		t.Errorf("programs = %v, want the ELF the head adds and the one an earlier commit added and a later one removed", res.Programs)
-	}
-	if at := realGit(t, r.ws, "rev-parse", "HEAD"); at != res.Merge {
-		t.Errorf("the workspace is at %s, not at the merge %s", at, res.Merge)
-	}
-	for f, want := range map[string]string{"b.txt": "head\n", "a.txt": "one\ntwo\nthree\nfour\n"} {
-		if got, _ := os.ReadFile(filepath.Join(r.ws, f)); string(got) != want {
-			t.Errorf("%s = %q, want %q", f, got, want)
-		}
-	}
-	if parents := strings.Fields(realGit(t, r.ws, "rev-list", "--parents", "-n", "1", res.Merge)); len(parents) != 3 || parents[1] != base || parents[2] != head {
-		t.Errorf("the merge commit's parents = %v, want the trunk commit and the head", parents)
-	}
-	if author := realGit(t, r.ws, "log", "-1", "--format=%an <%ae>", res.Merge); author != "mesh merge check <merge-check@mesh.invalid>" {
-		t.Errorf("the merge is made as %q", author)
-	}
-}
-
-// 1674/AC2: a conflict is an answer: the files in conflict, no merge commit, and the workspace left at the trunk commit.
-func TestMergeIntoAConflictAnswersTheFilesAndLeavesTheTreeAtTheTrunk(t *testing.T) {
-	r := newMergeRig(t)
-	head := r.head(map[string]string{"a.txt": "one\nHEAD\nthree\n", "c.txt": "c\n"})
-	base := r.advance(map[string]string{"a.txt": "one\nTRUNK\nthree\n"})
-	r.fetch(head)
-	res, err := MergeInto(context.Background(), forgekey.ExecRunner, r.ws, r.remote, base, head, AllowFileRemote())
-	if err != nil {
-		t.Fatalf("a conflict is an answer, not an error: %v", err)
-	}
-	if !reflect.DeepEqual(res.Conflicts, []string{"a.txt"}) || res.Merge != "" || len(res.Changed) != 0 || res.Base != base || res.Head != head {
-		t.Fatalf("result = %+v", res)
-	}
-	if at := realGit(t, r.ws, "rev-parse", "HEAD"); at != base {
-		t.Errorf("the workspace is at %s, not at the trunk commit %s", at, base)
-	}
-	if got, _ := os.ReadFile(filepath.Join(r.ws, "a.txt")); string(got) != "one\nTRUNK\nthree\n" {
-		t.Errorf("a.txt = %q, want the trunk's", got)
-	}
-	if st := realGit(t, r.ws, "status", "--porcelain"); st != "" {
-		t.Errorf("the tree is not clean after the aborted merge: %q", st)
-	}
-	if _, err := os.Stat(filepath.Join(r.ws, "c.txt")); err == nil {
-		t.Error("a file of the head is in a tree left at the trunk")
-	}
-}
-
-// A head already in the trunk merges into nothing: the merge is the trunk commit and no path changes.
-func TestMergeIntoAHeadAlreadyInTheTrunkChangesNothing(t *testing.T) {
-	r := newMergeRig(t)
-	head := r.head(map[string]string{"b.txt": "head\n"})
-	r.fork = head // the trunk continues from the head
-	base := r.advance(map[string]string{"a.txt": "one\ntwo\nthree\nfour\n"})
-	r.fetch(head)
-	res, err := MergeInto(context.Background(), forgekey.ExecRunner, r.ws, r.remote, base, head, AllowFileRemote())
-	if err != nil || res.Merge != base || len(res.Changed) != 0 || len(res.Conflicts) != 0 {
-		t.Errorf("result = %+v, %v", res, err)
-	}
-}

go/buildstep/merge_test.go

@@ -1,74 +0,0 @@
-package buildstep
-
-import (
-	"context"
-	"strings"
-	"testing"
-
-	"git.novox.be/novox/mesh-sdk/go/forgekey"
-)
-
-// 1674/AC3: no base is refused before anything runs; so is a base or a commit that is not a full sha, a workspace that
-// is not at the commit, and a remote that is not ssh://.
-func TestMergeIntoRefusesWhatIsNotAMerge(t *testing.T) {
-	f := &fakeGit{}
-	for name, c := range map[string]struct{ remote, base, commit string }{
-		"no base":          {"ssh://mesh-forge/o/r.git", "", sha},
-		"a short base":     {"ssh://mesh-forge/o/r.git", "abc123", sha},
-		"a branch as base": {"ssh://mesh-forge/o/r.git", "main", sha},
-		"a short commit":   {"ssh://mesh-forge/o/r.git", sha, "abc"},
-		"an https remote":  {"https://forge.example/o/r.git", sha, sha},
-	} {
-		_, err := MergeInto(context.Background(), f.run, "/w", c.remote, c.base, c.commit)
-		if err == nil {
-			t.Errorf("%s accepted", name)
-		}
-	}
-	if len(f.calls) != 0 {
-		t.Errorf("git ran for a refused merge: %v", f.calls)
-	}
-	g := &fakeGit{rule: func(l string) forgekey.Ran {
-		if strings.Contains(l, "rev-parse HEAD") {
-			return forgekey.Ran{Stdout: strings.Repeat("f", 40) + "\n"}
-		}
-		return forgekey.Ran{}
-	}}
-	_, err := MergeInto(context.Background(), g.run, "/w", "ssh://mesh-forge/o/r.git", strings.Repeat("a", 40), sha)
-	if err == nil || !strings.Contains(err.Error(), "not at the commit") || len(g.calls) != 1 {
-		t.Errorf("a workspace at another commit: %v after %d commands", err, len(g.calls))
-	}
-}
-
-// 1674/AC4: the merge is made with the check merge's identity and flags, hooks off, and fetches with no credential.
-func TestMergeIntoRunsTheCheckMergesCommands(t *testing.T) {
-	base := strings.Repeat("b", 40)
-	f := &fakeGit{rule: func(l string) forgekey.Ran {
-		switch {
-		case strings.HasSuffix(l, "rev-parse HEAD"):
-			return forgekey.Ran{Stdout: sha + "\n"}
-		case strings.Contains(l, "--is-shallow-repository"):
-			return forgekey.Ran{Stdout: "true\n"}
-		}
-		return forgekey.Ran{}
-	}}
-	if _, err := MergeInto(context.Background(), f.run, "/w", "ssh://mesh-forge/o/r.git", base, sha); err != nil {
-		t.Fatal(err)
-	}
-	all := strings.Join(f.calls, "\n")
-	for _, want := range []string{
-		pre + "fetch --no-tags --unshallow origin " + base,
-		pre + "checkout -q --detach " + base,
-		"user.name=mesh merge check", "user.email=merge-check@mesh.invalid", "commit.gpgsign=false", "core.hooksPath=/dev/null",
-		"merge --no-ff --no-edit --no-verify --quiet -m",
-		pre + "diff --name-only --no-renames " + base,
-	} {
-		if !strings.Contains(all, want) {
-			t.Errorf("the commands lack %q:\n%s", want, all)
-		}
-	}
-	for _, c := range f.calls {
-		if strings.Contains(c, "https://") || !strings.Contains(c, "credential.helper= ") {
-			t.Errorf("command %q carries a credential or https", c)
-		}
-	}
-}

go/buildstep/mirror_integration_test.go

@@ -1,65 +0,0 @@
-//go:build integration
-
-package buildstep
-
-import (
-	"context"
-	"os"
-	"path/filepath"
-	"strings"
-	"testing"
-
-	"git.novox.be/novox/mesh-sdk/go/forgekey"
-)
-
-// Issue 890 C1 (AC3): a mirror brought to two commits in turn; a fetch through it checks out each commit, the
-// alternates name the mirror, and no symlink is in the workspace.
-func TestMirrorServesTwoCommitsWithoutSymlinks(t *testing.T) {
-	root := t.TempDir()
-	src := filepath.Join(root, "src.git")
-	work := filepath.Join(root, "work")
-	for _, d := range []string{src, work} {
-		if err := os.MkdirAll(d, 0o755); err != nil {
-			t.Fatal(err)
-		}
-	}
-	gitIn(t, src, "init", "-q", "--bare")
-	gitIn(t, work, "init", "-q")
-	var commits []string
-	for _, c := range []string{"one", "two"} {
-		if err := os.WriteFile(filepath.Join(work, "f"), []byte(c), 0o644); err != nil {
-			t.Fatal(err)
-		}
-		gitIn(t, work, "add", "f")
-		gitIn(t, work, "commit", "-q", "-m", c)
-		commits = append(commits, gitIn(t, work, "rev-parse", "HEAD"))
-		gitIn(t, work, "push", "-q", src, "HEAD:refs/heads/main")
-	}
-	remote := "file://" + src
-	mirror := filepath.Join(root, "mirror.git")
-	for i, commit := range commits {
-		if err := UpdateMirror(context.Background(), forgekey.ExecRunner, mirror, remote, commit, "", AllowFileRemote()); err != nil {
-			t.Fatal(err)
-		}
-		ws := filepath.Join(root, "ws"+string(rune('0'+i)))
-		if err := os.MkdirAll(ws, 0o755); err != nil {
-			t.Fatal(err)
-		}
-		if err := FetchCommit(context.Background(), forgekey.ExecRunner, ws, remote, commit, "", AllowFileRemote(), WithMirror(mirror)); err != nil {
-			t.Fatal(err)
-		}
-		if head := gitIn(t, ws, "rev-parse", "HEAD"); head != commit {
-			t.Errorf("HEAD = %s, want %s", head, commit)
-		}
-		b, _ := os.ReadFile(filepath.Join(ws, ".git", "objects", "info", "alternates"))
-		if !strings.Contains(string(b), filepath.Join(mirror, "objects")) {
-			t.Errorf("alternates %q", b)
-		}
-		_ = filepath.Walk(ws, func(p string, fi os.FileInfo, err error) error {
-			if err == nil && fi.Mode()&os.ModeSymlink != 0 {
-				t.Errorf("symlink %s", p)
-			}
-			return nil
-		})
-	}
-}

go/buildstep/mirror_test.go

@@ -1,124 +0,0 @@
-package buildstep
-
-import (
-	"context"
-	"os"
-	"path/filepath"
-	"strings"
-	"testing"
-
-	"git.novox.be/novox/mesh-sdk/go/forgekey"
-)
-
-// Issue 890 C1 (ADR 0536 §2): a fetch through a bare mirror names the mirror in .git/objects/info/alternates, a
-// plain file, and never links it.
-func TestFetchCommitWithMirrorWritesAlternates(t *testing.T) {
-	mirror := t.TempDir()
-	ws := t.TempDir()
-	f := &fakeGit{}
-	// the fake's init does not create .git; make the objects directory as git init would.
-	if err := os.MkdirAll(filepath.Join(ws, ".git", "objects", "info"), 0o755); err != nil {
-		t.Fatal(err)
-	}
-	err := FetchCommit(context.Background(), f.run, ws, "ssh://mesh-forge/novox/mesh-sdk.git", sha, "", WithMirror(mirror))
-	if err != nil {
-		t.Fatal(err)
-	}
-	p := filepath.Join(ws, ".git", "objects", "info", "alternates")
-	b, err := os.ReadFile(p)
-	if err != nil {
-		t.Fatal(err)
-	}
-	if got, want := strings.TrimSpace(string(b)), filepath.Join(mirror, "objects"); got != want {
-		t.Errorf("alternates %q, want %q", got, want)
-	}
-	if fi, err := os.Lstat(p); err != nil || !fi.Mode().IsRegular() {
-		t.Errorf("alternates is not a plain file: %v %v", fi, err)
-	}
-	// the alternates exist before the fetch runs
-	if len(f.calls) < 3 || !strings.Contains(f.calls[2], "fetch") {
-		t.Errorf("calls %v", f.calls)
-	}
-}
-
-func TestWithMirrorRefusesARelativeOrMissingMirror(t *testing.T) {
-	for _, m := range []string{"rel/mirror", filepath.Join(t.TempDir(), "absent")} {
-		f := &fakeGit{}
-		err := FetchCommit(context.Background(), f.run, t.TempDir(), "ssh://mesh-forge/novox/x.git", sha, "", WithMirror(m))
-		if err == nil || len(f.calls) != 0 {
-			t.Errorf("mirror %q: err %v, calls %v", m, err, f.calls)
-		}
-	}
-}
-
-func TestUpdateMirrorInitsBareThenFetches(t *testing.T) {
-	mirror := filepath.Join(t.TempDir(), "mirror.git")
-	f := &fakeGit{}
-	if err := UpdateMirror(context.Background(), f.run, mirror, "ssh://mesh-forge/novox/x.git", sha, ""); err != nil {
-		t.Fatal(err)
-	}
-	pm := "git -c credential.helper= -C " + mirror + " "
-	want := []string{
-		"git -c credential.helper= init -q --bare " + mirror,
-		pm + "remote add origin ssh://mesh-forge/novox/x.git",
-		pm + "fetch --no-tags origin " + sha,
-		pm + "cat-file -e " + sha + "^{commit}",
-	}
-	if strings.Join(f.calls, "\n") != strings.Join(want, "\n") {
-		t.Errorf("commands:\n%s\nwant:\n%s", strings.Join(f.calls, "\n"), strings.Join(want, "\n"))
-	}
-}
-
-func TestUpdateMirrorKeepsAnExistingMirrorAndFallsBackToTheRef(t *testing.T) {
-	mirror := t.TempDir() // exists: no init
-	if err := os.WriteFile(filepath.Join(mirror, "HEAD"), []byte("ref: refs/heads/main\n"), 0o644); err != nil {
-		t.Fatal(err)
-	}
-	f := &fakeGit{}
-	f.rule = func(args string) (r forgekey.Ran) {
-		if strings.HasSuffix(args, "origin "+sha) {
-			r.Status = 1
-			r.Stderr = "not our ref"
-		}
-		return
-	}
-	if err := UpdateMirror(context.Background(), f.run, mirror, "ssh://mesh-forge/novox/x.git", sha, "refs/pull/3/head"); err != nil {
-		t.Fatal(err)
-	}
-	all := strings.Join(f.calls, "\n")
-	if strings.Contains(all, "init") || strings.Contains(all, "remote add") || !strings.Contains(all, "fetch --no-tags origin refs/pull/3/head") {
-		t.Errorf("commands:\n%s", all)
-	}
-}
-
-func TestUpdateMirrorRefusesBeforeRunning(t *testing.T) {
-	f := &fakeGit{}
-	for _, c := range []struct{ remote, commit string }{
-		{"https://x/y.git", sha}, {"ssh://u@h/o/r.git", sha}, {"ssh://h/o/r.git", "abc"},
-	} {
-		if err := UpdateMirror(context.Background(), f.run, t.TempDir(), c.remote, c.commit, ""); err == nil {
-			t.Errorf("%v accepted", c)
-		}
-	}
-	if len(f.calls) != 0 {
-		t.Errorf("ran %v", f.calls)
-	}
-}
-
-// The forge's refusal reaches the reason in git's own words: the mirror of a repository its account cannot read said
-// only "git -C: error:" (2026-10-26), since git writes a bare "error:" line before the forge's message.
-func TestUpdateMirrorSaysTheForgesRefusal(t *testing.T) {
-	f := &fakeGit{}
-	f.rule = func(args string) (r forgekey.Ran) {
-		if strings.Contains(args, "fetch") {
-			r.Status = 128
-			r.Stderr = "error: \nerror: User: 22:nox-builder with Key: 30:mesh:ace.mesh-build-go is not authorized to read o/r.\nerror: \nfatal: Could not read from remote repository.\n"
-		}
-		return
-	}
-	err := UpdateMirror(context.Background(), f.run, filepath.Join(t.TempDir(), "m.git"), "ssh://mesh-forge/o/r.git", sha, "")
-	if err == nil || !strings.Contains(err.Error(), "nox-builder with Key: 30:mesh:ace.mesh-build-go is not authorized to read o/r.") ||
-		!strings.Contains(err.Error(), "Could not read from remote repository") || !strings.HasPrefix(err.Error(), "git fetch: ") {
-		t.Errorf("err = %v", err)
-	}
-}

go/buildstep/narrow.go

@@ -1,71 +0,0 @@
-package buildstep
-
-import (
-	"fmt"
-	"os"
-	"path"
-	"path/filepath"
-	"strings"
-)
-
-// narrowKept are the files of a module's directory a narrowed build keeps beside its named paths: its manifest and
-// its lock files, each an input of the module's key (ModuleTree's Manifest and Locks). package.json and go.mod are
-// not kept: neither is in the named tree, so a build that needs one names it among its artifact's paths, which puts
-// it in the key (novox/hq ADR 0499 clause 4).
-var narrowKept = append([]string{"module.json"}, lockFiles...)
-
-// Narrow leaves in the fetched tree only what a build of an artifact that names its paths may see (novox/hq ADR 0499
-// clause 4): r.Dir's named paths, its manifest and lock files, and .git; everything else is removed, so a file outside
-// them cannot change what is built without changing its key. A named path absent at the tree is an error naming it,
-// and nothing is removed then. With no paths in r it changes nothing. Both build modules' fetch steps call it.
-func Narrow(tree string, r FetchRequest) error {
-	if len(r.Paths) == 0 {
-		return nil
-	}
-	keep := map[string]bool{".git": true}
-	for _, p := range r.Paths {
-		rel := path.Join(r.Dir, p)
-		if strings.HasPrefix(rel, "../") || rel == ".." || path.IsAbs(p) {
-			return fmt.Errorf("the named path %q leaves the module's directory", p)
-		}
-		if _, err := os.Lstat(filepath.Join(tree, filepath.FromSlash(rel))); err != nil {
-			return fmt.Errorf("the named path %q is not in the fetched tree: %w", p, err)
-		}
-		keep[rel] = true
-	}
-	for _, f := range narrowKept {
-		keep[path.Join(r.Dir, f)] = true
-	}
-	return prune(tree, "", keep)
-}
-
-// prune removes from dir (rel within the tree) every entry that is neither kept nor on the way to one.
-func prune(root, rel string, keep map[string]bool) error {
-	entries, err := os.ReadDir(filepath.Join(root, filepath.FromSlash(rel)))
-	if err != nil {
-		return err
-	}
-	for _, e := range entries {
-		p := path.Join(rel, e.Name())
-		if keep[p] {
-			continue
-		}
-		ancestor := false
-		for k := range keep {
-			if strings.HasPrefix(k, p+"/") {
-				ancestor = true
-				break
-			}
-		}
-		if ancestor && e.IsDir() {
-			if err := prune(root, p, keep); err != nil {
-				return err
-			}
-			continue
-		}
-		if err := os.RemoveAll(filepath.Join(root, filepath.FromSlash(p))); err != nil {
-			return err
-		}
-	}
-	return nil
-}

go/buildstep/narrow_test.go

@@ -1,82 +0,0 @@
-package buildstep
-
-import (
-	"os"
-	"path/filepath"
-	"sort"
-	"strings"
-	"testing"
-)
-
-func filesUnder(t *testing.T, root string) []string {
-	t.Helper()
-	var out []string
-	_ = filepath.Walk(root, func(p string, info os.FileInfo, err error) error {
-		if err == nil && !info.IsDir() {
-			rel, _ := filepath.Rel(root, p)
-			out = append(out, filepath.ToSlash(rel))
-		}
-		return nil
-	})
-	sort.Strings(out)
-	return out
-}
-
-// A build of an artifact that names its paths sees only those paths, its manifest and its lock files (novox/hq ADR 0499
-// clause 4): Narrow removes everything else of the fetched tree but .git, package.json and go.mod among it, since
-// neither is in the named tree nor among the lock files; with no paths it changes nothing.
-func TestNarrowLeavesOnlyTheNamedPathsTheManifestAndTheLocks(t *testing.T) {
-	tree := t.TempDir()
-	for _, f := range []string{".git/HEAD", "module.json", "package.json", "package-lock.json", "go.sum", "src/index.ts",
-		"src/deep/a.ts", "test/a.test.ts", "tsconfig.json", "go/delivery/x.go", "README.md", "other/module.json"} {
-		writeTreeFile(t, tree, f, "x")
-	}
-	if err := Narrow(tree, FetchRequest{}); err != nil {
-		t.Fatal(err)
-	}
-	if got := len(filesUnder(t, tree)); got != 12 {
-		t.Fatalf("a request without paths changed the tree: %d files", got)
-	}
-	if err := Narrow(tree, FetchRequest{Dir: ".", Paths: []string{"src", "test", "tsconfig.json"}}); err != nil {
-		t.Fatal(err)
-	}
-	want := ".git/HEAD,go.sum,module.json,package-lock.json,src/deep/a.ts,src/index.ts,test/a.test.ts,tsconfig.json"
-	if got := strings.Join(filesUnder(t, tree), ","); got != want {
-		t.Fatalf("the narrowed tree holds %s\nwant %s", got, want)
-	}
-}
-
-func TestNarrowKeepsAModuleDirectorysPathsAndFailsOnAnAbsentOne(t *testing.T) {
-	tree := t.TempDir()
-	for _, f := range []string{".git/config", "modules/a/module.json", "modules/a/go.mod", "modules/a/src/x.ts",
-		"modules/a/notes.md", "modules/b/module.json", "root.txt"} {
-		writeTreeFile(t, tree, f, "x")
-	}
-	err := Narrow(tree, FetchRequest{Dir: "modules/a", Paths: []string{"src", "gone"}})
-	if err == nil || !strings.Contains(err.Error(), `"gone"`) {
-		t.Fatalf("an absent named path gave %v", err)
-	}
-	if len(filesUnder(t, tree)) != 7 {
-		t.Fatal("a refused narrowing removed files")
-	}
-	if err := Narrow(tree, FetchRequest{Dir: "modules/a", Paths: []string{"src"}}); err != nil {
-		t.Fatal(err)
-	}
-	if got := strings.Join(filesUnder(t, tree), ","); got != ".git/config,modules/a/module.json,modules/a/src/x.ts" {
-		t.Fatalf("the narrowed tree holds %s", got)
-	}
-}
-
-// A build that needs package.json or go.mod names it among its paths, and so keys on it (ADR 0499 clause 4).
-func TestNarrowKeepsAManifestOfTheLanguageOnlyWhenNamed(t *testing.T) {
-	tree := t.TempDir()
-	for _, f := range []string{"module.json", "package.json", "go.mod", "src/a.ts"} {
-		writeTreeFile(t, tree, f, "x")
-	}
-	if err := Narrow(tree, FetchRequest{Dir: ".", Paths: []string{"src", "package.json"}}); err != nil {
-		t.Fatal(err)
-	}
-	if got := strings.Join(filesUnder(t, tree), ","); got != "module.json,package.json,src/a.ts" {
-		t.Fatalf("the narrowed tree holds %s", got)
-	}
-}

go/buildstep/pack.go

@@ -1,100 +0,0 @@
-package buildstep
-
-import (
-	"archive/tar"
-	"bytes"
-	"compress/gzip"
-	"crypto/sha256"
-	"encoding/hex"
-	"fmt"
-	"os"
-	"path/filepath"
-	"sort"
-)
-
-// Pack tars and gzips a directory the way the build agent does, byte for byte, and answers the archive and its
-// digest, "sha256:" and the hex of the archive's bytes (issue 1479; novox/hq ADR 0405 §7, ADR 0453 §7). It is a
-// copy of mesh-controller's internal/builder/builder.go pack (origin/main 073ccc29, :1351-1425), which stays
-// where it is until the build agent goes: a build module's digest is compared with the build agent's for one
-// fingerprint, so the bytes must be equal.
-//
-// Deterministically: regular files only (a symlink or a device is refused), sorted relative paths with
-// slashes, each header carrying its name, permission bits and size and nothing else, the gzip default writer.
-func Pack(root string) (archive []byte, digest string, err error) {
-	raw, err := pack(root)
-	if err != nil {
-		return nil, "", err
-	}
-	sum := sha256.Sum256(raw)
-	return raw, "sha256:" + hex.EncodeToString(sum[:]), nil
-}
-
-func pack(root string) ([]byte, error) {
-	info, err := os.Stat(root)
-	if err != nil {
-		return nil, err
-	}
-	if !info.IsDir() {
-		return nil, fmt.Errorf("%s is not a directory", root)
-	}
-
-	var paths []string
-	err = filepath.Walk(root, func(path string, info os.FileInfo, err error) error {
-		if err != nil {
-			return err
-		}
-		if info.IsDir() || !info.Mode().IsRegular() {
-			// Only files. A symlink or a device in an archive is refused by the host that unpacks
-			// it, so putting one in would build something that cannot be applied.
-			if !info.IsDir() && !info.Mode().IsRegular() {
-				return fmt.Errorf("%s is neither a file nor a directory, and an archive carries "+
-					"only those", path)
-			}
-			return nil
-		}
-		paths = append(paths, path)
-		return nil
-	})
-	if err != nil {
-		return nil, err
-	}
-	// filepath.Walk walks in lexical order; the sort is kept as the build agent keeps it, since an archive
-	// whose digest changes because the traversal did is a silent failure.
-	sort.Strings(paths)
-
-	var out bytes.Buffer
-	zipped := gzip.NewWriter(&out)
-	writer := tar.NewWriter(zipped)
-	for _, path := range paths {
-		body, err := os.ReadFile(path)
-		if err != nil {
-			return nil, err
-		}
-		relative, err := filepath.Rel(root, path)
-		if err != nil {
-			return nil, err
-		}
-		info, err := os.Stat(path)
-		if err != nil {
-			return nil, err
-		}
-		mode := int64(info.Mode().Perm())
-		if err := writer.WriteHeader(&tar.Header{
-			Name: filepath.ToSlash(relative), Mode: mode, Size: int64(len(body)),
-			Typeflag: tar.TypeReg,
-			// Everything else left at its zero value on purpose: no times, owners or names.
-		}); err != nil {
-			return nil, err
-		}
-		if _, err := writer.Write(body); err != nil {
-			return nil, err
-		}
-	}
-	if err := writer.Close(); err != nil {
-		return nil, err
-	}
-	if err := zipped.Close(); err != nil {
-		return nil, err
-	}
-	return out.Bytes(), nil
-}

go/buildstep/pack_test.go

@@ -1,84 +0,0 @@
-package buildstep
-
-import (
-	"bytes"
-	"compress/gzip"
-	"crypto/sha256"
-	"encoding/hex"
-	"io"
-	"os"
-	"path/filepath"
-	"testing"
-	"time"
-)
-
-// fixture writes three files in two directories (modes 0644 and 0755).
-func fixture(t *testing.T) string {
-	t.Helper()
-	root := t.TempDir()
-	for _, f := range []struct {
-		p    string
-		mode os.FileMode
-		body string
-	}{{"a/x.txt", 0o644, "x\n"}, {"a/run.sh", 0o755, "#!/bin/sh\necho hi\n"}, {"b/c/y.txt", 0o644, "why\n"}} {
-		path := filepath.Join(root, f.p)
-		if err := os.MkdirAll(filepath.Dir(path), 0o755); err != nil {
-			t.Fatal(err)
-		}
-		if err := os.WriteFile(path, []byte(f.body), f.mode); err != nil {
-			t.Fatal(err)
-		}
-		if err := os.Chmod(path, f.mode); err != nil {
-			t.Fatal(err)
-		}
-	}
-	return root
-}
-
-// 1479/AC1: the tar stream inside the archive equals the bytes mesh-controller's pack makes for this tree.
-// testdata/pack-golden.tar is the uncompressed stream, made once by running mesh-controller
-// internal/builder/builder.go pack (origin/main 073ccc29, :1351-1425) on this fixture (above, modes set by chmod)
-// and gunzipping its archive. The gzip layer is not compared byte for byte, since compress/gzip's output differs
-// between Go versions; its header is checked to carry no name, no comment and no time.
-func TestPackEqualsTheBuildAgentsArchive(t *testing.T) {
-	golden, err := os.ReadFile("testdata/pack-golden.tar")
-	if err != nil {
-		t.Fatal(err)
-	}
-	archive, digest, err := Pack(fixture(t))
-	if err != nil {
-		t.Fatal(err)
-	}
-	zr, err := gzip.NewReader(bytes.NewReader(archive))
-	if err != nil {
-		t.Fatal(err)
-	}
-	if zr.Name != "" || zr.Comment != "" || !zr.ModTime.IsZero() {
-		t.Errorf("gzip header = name %q, comment %q, time %v; want none", zr.Name, zr.Comment, zr.ModTime)
-	}
-	tarBytes, err := io.ReadAll(zr)
-	if err != nil {
-		t.Fatal(err)
-	}
-	if !bytes.Equal(tarBytes, golden) {
-		t.Errorf("the tar stream is %d bytes, the build agent's %d, and they differ", len(tarBytes), len(golden))
-	}
-	sum := sha256.Sum256(archive)
-	if digest != "sha256:"+hex.EncodeToString(sum[:]) {
-		t.Errorf("digest = %s, not the sha256 of the archive", digest)
-	}
-}
-
-// 1479/AC2: touching every file's time changes nothing.
-func TestPackDigestIgnoresFileTimes(t *testing.T) {
-	root := fixture(t)
-	_, first, err := Pack(root)
-	if err != nil {
-		t.Fatal(err)
-	}
-	later := time.Now().Add(48 * time.Hour)
-	filepath.Walk(root, func(p string, _ os.FileInfo, _ error) error { return os.Chtimes(p, later, later) })
-	if _, second, err := Pack(root); err != nil || second != first {
-		t.Errorf("digests %s and %s (%v)", first, second, err)
-	}
-}

go/buildstep/pack_unix_test.go

@@ -1,25 +0,0 @@
-//go:build unix
-
-package buildstep
-
-import (
-	"path/filepath"
-	"strings"
-	"syscall"
-	"testing"
-)
-
-// 1479/AC3: anything but a file or a directory is refused, naming it. The rule of this repository is that no
-// test makes a symlink, so the non-regular entry is a named pipe: Pack refuses a symlink on the same branch
-// (filepath.Walk reports it by lstat as not regular).
-func TestPackRefusesAnEntryThatIsNotAFile(t *testing.T) {
-	root := fixture(t)
-	pipe := filepath.Join(root, "a", "pipe")
-	if err := syscall.Mkfifo(pipe, 0o644); err != nil {
-		t.Fatal(err)
-	}
-	_, _, err := Pack(root)
-	if err == nil || !strings.Contains(err.Error(), pipe) {
-		t.Errorf("Pack = %v, want a refusal naming %s", err, pipe)
-	}
-}

go/buildstep/phase.go

@@ -1,67 +0,0 @@
-package buildstep
-
-import (
-	"context"
-	"strings"
-	"sync"
-	"time"
-
-	"git.novox.be/novox/mesh-sdk/go/delivery"
-)
-
-// **A running ask says its phases** (issue 1890, 2026-10-26 19:09: a mesh-catalog try's step on shanks ran 30 minutes
-// and its module's journal held no line naming its ask, so nobody could tell whether it fetched, linted or tested). The
-// puller hands every ask's run a phase reporter in its context; RunAsk and a module's own step bodies call Phase as they
-// move (fetch and merge, a level's digest, lint, a level's tests), and each phase is logged with the ask's id and its
-// time since the start, and written to the ask's running step key (delivery.Step.Phase), so its asker and the delivery
-// view read where it stands from the bus.
-
-type phaseKey struct{}
-
-// Phase says that the ask whose run ctx belongs to entered phase; nothing outside an ask's run (a tool called by hand).
-func Phase(ctx context.Context, phase string) {
-	if r, ok := ctx.Value(phaseKey{}).(*phases); ok && r != nil {
-		r.enter(strings.TrimSpace(phase))
-	}
-}
-
-// phases is one running ask's reporter: it writes the step key again with each new phase until the step ends.
-type phases struct {
-	mu     sync.Mutex
-	put    Put
-	key    string
-	step   delivery.Step
-	ended  bool
-	logf   func(format string, args ...any)
-	prefix string
-}
-
-func (r *phases) enter(phase string) {
-	if phase == "" {
-		return
-	}
-	r.mu.Lock()
-	defer r.mu.Unlock()
-	if r.ended || phase == r.step.Phase {
-		return
-	}
-	at := now().UTC()
-	r.step.Phase, r.step.PhaseAt = phase, at
-	if r.logf != nil {
-		r.logf("%s: %s, %s after its start", r.prefix, phase, at.Sub(r.step.Started).Round(time.Second))
-	}
-	if r.put == nil {
-		return
-	}
-	if err := write(r.put, r.key, r.step); err != nil && r.logf != nil {
-		r.logf("%s: the phase %s could not be written to %s: %v", r.prefix, phase, r.key, err)
-	}
-}
-
-// end stops the writes (the step's end is written after it) and answers the step with its last phase, for the end.
-func (r *phases) end() delivery.Step {
-	r.mu.Lock()
-	defer r.mu.Unlock()
-	r.ended = true
-	return r.step
-}

go/buildstep/programs.go

@@ -1,115 +0,0 @@
-package buildstep
-
-import (
-	"bytes"
-	"io"
-	"os"
-	"path/filepath"
-	"strings"
-)
-
-// Program is a changed file whose first bytes are an executable binary: a compiled program, which is build output and not
-// source (novox/hq issue 1577: `go build` in a module's folder writes one beside go.mod, and `git add -A` takes it).
-type Program struct {
-	Path string `json:"path"`
-	Kind string `json:"kind"` // ELF, Mach-O or PE
-	// Commit is set for a program a commit of the branch added and a later one removed (or replaced): the merge's tree is clean,
-	// but the merge commit carries the blob into the trunk's history for good. Empty for a program the merge's tree holds.
-	Commit string `json:"commit,omitempty"`
-}
-
-// ExecutableKind says what executable format the first bytes of a file are, or "" when they are none. A PE needs its header
-// ("PE\0\0" at the offset in bytes 0x3c) so a text starting with "MZ" is not one; a fat Mach-O (0xCAFEBABE) is told from a
-// Java class by its architecture count (bytes 4 to 7, fewer than 0x20; a class has its version there).
-func ExecutableKind(head []byte) string {
-	switch {
-	case bytes.HasPrefix(head, []byte("\x7fELF")):
-		return "ELF"
-	case bytes.HasPrefix(head, []byte("MZ")):
-		if len(head) >= 0x40 {
-			off := int(head[0x3c]) | int(head[0x3d])<<8 | int(head[0x3e])<<16 | int(head[0x3f])<<24
-			if off >= 0 && off+4 <= len(head) && bytes.Equal(head[off:off+4], []byte("PE\x00\x00")) {
-				return "PE"
-			}
-		}
-	case bytes.HasPrefix(head, []byte{0xcf, 0xfa, 0xed, 0xfe}), bytes.HasPrefix(head, []byte{0xce, 0xfa, 0xed, 0xfe}),
-		bytes.HasPrefix(head, []byte{0xfe, 0xed, 0xfa, 0xcf}), bytes.HasPrefix(head, []byte{0xfe, 0xed, 0xfa, 0xce}),
-		bytes.HasPrefix(head, []byte{0xca, 0xfe, 0xba, 0xbe}) && len(head) >= 8 && head[4] == 0 && head[5] == 0 && head[6] == 0 && head[7] < 0x20:
-		return "Mach-O"
-	}
-	return ""
-}
-
-// programHeadSize is how many bytes of a file are read to tell its format: enough for a PE header at its usual offsets.
-const programHeadSize = 0x100
-
-// historyPrograms names the compiled programs that a commit of base..head added or modified and the merge's tree no longer
-// holds at that path (those it holds are in final already): each with the commit that added it. git is the merge's git runner.
-func historyPrograms(git func(args ...string) (string, error), base, head string, final []Program) ([]Program, error) {
-	revs, err := git("rev-list", "--no-merges", "--reverse", base+".."+head)
-	if err != nil {
-		return nil, err
-	}
-	held := map[string]bool{}
-	for _, p := range final {
-		held[p.Path] = true
-	}
-	out, seen := []Program{}, map[string]bool{}
-	for _, c := range strings.Fields(revs) {
-		raw, err := git("diff-tree", "-r", "-z", "--no-commit-id", "--no-renames", "--root", "--diff-filter=AM", c)
-		if err != nil {
-			return nil, err
-		}
-		f := strings.Split(raw, "\x00")
-		for i := 0; i+1 < len(f); i += 2 {
-			meta := strings.Fields(strings.TrimPrefix(f[i], ":"))
-			if len(meta) < 4 || (meta[1] != "100644" && meta[1] != "100755") || held[f[i+1]] || seen[meta[3]] {
-				continue
-			}
-			seen[meta[3]] = true
-			blob, err := git("cat-file", "blob", meta[3])
-			if err != nil {
-				return nil, err
-			}
-			head := []byte(blob)
-			if len(head) > programHeadSize {
-				head = head[:programHeadSize]
-			}
-			if k := ExecutableKind(head); k != "" {
-				out = append(out, Program{Path: f[i+1], Kind: k, Commit: c})
-			}
-		}
-	}
-	return out, nil
-}
-
-// programsIn reads the output of `git diff --raw -z --no-renames --diff-filter=AM` (":<old mode> <new mode> <old sha> <new
-// sha> <status>\0<path>\0" per file) and names each added or modified regular file of the tree dir that is a compiled
-// program, from its first bytes read locally. A symlink (mode 120000) and a submodule (160000) are not read. It never
-// answers nil, so a caller can tell no programs from none reported.
-func programsIn(dir, raw string) []Program {
-	out := []Program{}
-	f := strings.Split(raw, "\x00")
-	for i := 0; i+1 < len(f); i += 2 {
-		meta := strings.Fields(strings.TrimPrefix(f[i], ":"))
-		if len(meta) < 2 || (meta[1] != "100644" && meta[1] != "100755") {
-			continue
-		}
-		p := f[i+1]
-		full := filepath.Join(dir, filepath.FromSlash(p))
-		if st, err := os.Lstat(full); err != nil || !st.Mode().IsRegular() {
-			continue
-		}
-		fh, err := os.Open(full)
-		if err != nil {
-			continue
-		}
-		head := make([]byte, programHeadSize)
-		n, _ := io.ReadFull(fh, head)
-		fh.Close()
-		if k := ExecutableKind(head[:n]); k != "" {
-			out = append(out, Program{Path: p, Kind: k})
-		}
-	}
-	return out
-}

go/buildstep/programs_test.go

@@ -1,72 +0,0 @@
-package buildstep
-
-import (
-	"os"
-	"path/filepath"
-	"reflect"
-	"testing"
-)
-
-func pe(offset int, magic string) []byte {
-	b := make([]byte, 0x100)
-	copy(b, "MZ")
-	b[0x3c] = byte(offset)
-	copy(b[offset:], magic)
-	return b
-}
-
-func TestExecutableKindTellsProgramsFromText(t *testing.T) { // issue 1577
-	for _, c := range []struct {
-		name string
-		head []byte
-		want string
-	}{
-		{"elf", []byte("\x7fELF\x02\x01\x01"), "ELF"},
-		{"mach-o 64", []byte{0xcf, 0xfa, 0xed, 0xfe, 7, 0, 0, 1}, "Mach-O"},
-		{"mach-o 32 big", []byte{0xfe, 0xed, 0xfa, 0xce, 0, 0, 0, 7}, "Mach-O"},
-		{"fat mach-o", []byte{0xca, 0xfe, 0xba, 0xbe, 0, 0, 0, 2}, "Mach-O"},
-		{"java class", []byte{0xca, 0xfe, 0xba, 0xbe, 0, 0, 0, 0x34}, ""},
-		{"pe", pe(0x80, "PE\x00\x00"), "PE"},
-		{"mz text", []byte("MZ is a text file starting with two letters"), ""},
-		{"mz without a pe header", pe(0x80, "XX\x00\x00"), ""},
-		{"text", []byte("package main"), ""},
-		{"empty", nil, ""},
-	} {
-		if got := ExecutableKind(c.head); got != c.want {
-			t.Errorf("%s: kind = %q, want %q", c.name, got, c.want)
-		}
-	}
-}
-
-func TestProgramsInNamesTheAddedAndModifiedRegularFilesThatArePrograms(t *testing.T) { // issue 1577
-	dir := t.TempDir()
-	write := func(name string, b []byte) {
-		if err := os.MkdirAll(filepath.Dir(filepath.Join(dir, name)), 0o755); err != nil {
-			t.Fatal(err)
-		}
-		if err := os.WriteFile(filepath.Join(dir, name), b, 0o755); err != nil {
-			t.Fatal(err)
-		}
-	}
-	write("m/prog", []byte("\x7fELF\x02\x01"))
-	write("m/notes", []byte("plain text"))
-	write("m/mac", []byte{0xcf, 0xfa, 0xed, 0xfe, 7, 0, 0, 1})
-	if err := os.Symlink("prog", filepath.Join(dir, "m/link")); err != nil {
-		t.Fatal(err)
-	}
-	line := func(mode, path string) string { return ":000000 " + mode + " 0000 1111 A\x00" + path + "\x00" }
-	for _, c := range []struct {
-		name, raw string
-		want      []Program
-	}{
-		{"none", "", []Program{}},
-		{"a program and a text", line("100755", "m/prog") + line("100644", "m/notes"), []Program{{"m/prog", "ELF", ""}}},
-		{"two programs", line("100644", "m/prog") + line("100755", "m/mac"), []Program{{"m/prog", "ELF", ""}, {"m/mac", "Mach-O", ""}}},
-		{"a symlink and a submodule are not read", line("120000", "m/link") + line("160000", "m/sub"), []Program{}},
-		{"a path the tree lacks", line("100644", "m/gone"), []Program{}},
-	} {
-		if got := programsIn(dir, c.raw); !reflect.DeepEqual(got, c.want) {
-			t.Errorf("%s: programs = %v, want %v", c.name, got, c.want)
-		}
-	}
-}

go/buildstep/pull.go

@@ -1,688 +0,0 @@
-package buildstep
-
-import (
-	"context"
-	"encoding/json"
-	"errors"
-	"fmt"
-	"sort"
-	"strings"
-	"sync"
-	"time"
-
-	stdio "git.novox.be/novox/mesh-sdk/go"
-	"git.novox.be/novox/mesh-sdk/go/delivery"
-)
-
-// **The pull loop the build modules share** (novox/hq ADR 0525 §4-§6, ADR 0536 §4; issue 1887). A build module on a node
-// whose build capacity is above zero pulls the asks of its language's seat: from the delivery worker first, then check,
-// then recheck, holding at most its capacity at once. Each ask runs as a step under the ask's own id, so its end is the
-// key <node>.<ask id> in the module's steps state, which the asker watches; the ask is acknowledged when that end is
-// written, kept alive while it runs by an in-progress signal, and redelivered by the stream to another node if this one
-// stops. No part keeps a timer for an ask: the pull's own wait and the stream's acknowledgement wait are the bus's.
-
-// Pulled is one ask a source handed over, with what decides its fate on the bus.
-type Pulled struct {
-	// Kind is the worker it came from, filled by the puller.
-	Kind string
-	Data []byte
-	// Delivered is how many times the bus has handed it over, this time included.
-	Delivered uint64
-	// Ack ends it: it is never delivered again. InProgress tells the bus it is still being worked, restarting its
-	// acknowledgement wait. Nak hands it back to be delivered again at once (to this node or another). Term drops it.
-	Ack, InProgress, Nak, Term func() error
-}
-
-// AskSource is where a puller takes asks from: the seat's workers on the bus (JetStreamAsks) or a test double
-// (FakeAsks).
-type AskSource interface {
-	// Next takes one ask of kind: with wait 0 only one already waiting, else waiting for one at most wait. It answers
-	// nil and no error when none came.
-	Next(ctx context.Context, kind string, wait time.Duration) (*Pulled, error)
-}
-
-// Defaults of a Puller.
-var (
-	// DefaultPullWait is how long one pull of the delivery worker waits for an ask while every worker is empty: the
-	// pull's own wait (as process.Consume's), after which the check and recheck workers are looked at again.
-	DefaultPullWait = 5 * time.Second
-	// DefaultHeartbeat is how often a running ask tells the bus it is still being worked; under the seat worker's
-	// acknowledgement wait of 60 s (mesh-controller internal/broker HolderConsumerFor).
-	DefaultHeartbeat = 20 * time.Second
-)
-
-// Puller pulls a build seat's asks and runs them.
-type Puller struct {
-	Source   AskSource
-	Language string // the seat's language: delivery.AskGo, AskNode or AskImage
-	Node     string // the node this holder runs on, the first part of its step keys
-	Put      Put    // writes the module's steps state
-	// Capacity is how many asks the node runs at once; read before every pull, so a change takes effect at the next
-	// one. 0 pulls nothing.
-	Capacity func() int
-	// Run runs one ask's job; a *Refusal ends its step refused. Its result is the step's result.
-	Run func(ctx context.Context, ask delivery.StepAsk) (any, error)
-	// PullWait and Heartbeat default to DefaultPullWait and DefaultHeartbeat.
-	PullWait  time.Duration
-	Heartbeat time.Duration
-	Logf      func(format string, args ...any)
-	// Load reads one key of the state the node's pause is kept in (nil and no error when it is absent). When set, Pull
-	// reads the node's pause key (delivery.PauseKey) before it pulls, and Pause and Resume write it with PausePut, so a
-	// pause outlives a restart.
-	Load func(key string) ([]byte, error)
-	// PausePut writes the node's pause key: the module's pauses state (delivery.PausesState), which has no age, so a
-	// pause never ends by itself while the steps state drops its old keys. Put when nil.
-	PausePut Put
-	// WatchConfig, when set, follows the module's config value `capacity` (CapacitySetting) as mesh-config resolves it
-	// for this node, and wakes the puller on each change (watchCapacity): WatchConfigServed in a module, a test's own
-	// double. Until it hands a value the puller judges by Capacity.
-	WatchConfig func(key string, handle func(stdio.ProvisionChange) error) error
-	// CoresPerStep is what one ask of this module needs, read at every judgement (NodeCoresPerStep); with it the capacity
-	// judged by is bounded by the node's build slice: min(the configured capacity, floor(the quota's cores / CoresPerStep))
-	// (EffectiveCapacity). Nil bounds nothing by the CPU. Quota reads the quota (Quota when nil; a test's own).
-	CoresPerStep func() float64
-	Quota        func() (percent int, from string)
-	// BuildHours is the node's build window, read at every judgement (NodeBuildHours); with WatchConfig set the value
-	// mesh-config resolves for `build-hours` takes its place once handed. Outside the window the capacity judged by is 0:
-	// steps running finish, no new one is taken; the puller wakes at the window's next edge. Nil builds at any hour.
-	BuildHours func() (*BuildWindow, string)
-	// Has says whether this node has a need an ask names (delivery.AskNeeds, issue 890). An ask needing what it lacks is
-	// declined: its step ends refused as declined (delivery.StepDeclined), the message is dropped for its asker to put
-	// again, and the worker it came from is not looked at again until the next pull's wait, so a node lacking the need
-	// does not take the asker's next copy at once. Nil has nothing.
-	Has func(need string) bool
-
-	mu      sync.Mutex
-	inHand  int
-	running map[string]RunningAsk
-	paused  bool
-	wake    chan struct{}
-	once    sync.Once
-	// watched is the capacity the config watch handed last, used in place of Capacity once hasWatched.
-	watched    int
-	hasWatched bool
-	// hours is the build window the config watch handed last, and hoursFault why its value cannot be read; used in place
-	// of BuildHours once hasHours.
-	hours      *BuildWindow
-	hoursFault string
-	hasHours   bool
-	// judged is the capacity said last (log and capacity.<node>), so a change is said once.
-	judged     delivery.Capacity
-	hasJudged  bool
-	capWritten bool
-	capFault   string
-	// declined are the kinds whose worker handed an ask this node declined, left out of the pulls without a wait until
-	// the next pull's wait ends.
-	declined map[string]bool
-}
-
-func (p *Puller) init() {
-	p.once.Do(func() { p.wake = make(chan struct{}, 1) })
-}
-
-func (p *Puller) logf(format string, args ...any) {
-	if p.Logf != nil {
-		p.Logf(format, args...)
-	}
-}
-
-// Wake makes a waiting puller look again: after a capacity change, a resume, or a step's end.
-func (p *Puller) Wake() {
-	p.init()
-	select {
-	case p.wake <- struct{}{}:
-	default:
-	}
-}
-
-// Pause stops the puller taking asks; the asks it holds run to their end. by names who paused it. With Load set the
-// pause is written on the node's pause key first, and an error there leaves the puller as it was.
-func (p *Puller) Pause(by string) error { return p.setPaused(true, by) }
-
-// Resume lets the puller take asks again, written as Pause's is.
-func (p *Puller) Resume(by string) error { return p.setPaused(false, by) }
-
-func (p *Puller) setPaused(paused bool, by string) error {
-	if p.Load != nil {
-		key, err := delivery.PauseKey(p.Node)
-		if err != nil {
-			return err
-		}
-		raw, err := delivery.EncodePause(delivery.Pause{Paused: paused, By: by, At: now()})
-		if err != nil {
-			return err
-		}
-		put := p.PausePut
-		if put == nil {
-			put = p.Put
-		}
-		if _, err := put(key, json.RawMessage(raw)); err != nil {
-			return fmt.Errorf("buildstep: writing the pause of %s: %w", p.Node, err)
-		}
-	}
-	p.mu.Lock()
-	p.paused = paused
-	p.mu.Unlock()
-	p.Wake()
-	return nil
-}
-
-// restore reads the node's pause key, when Load is set.
-func (p *Puller) restore() error {
-	if p.Load == nil {
-		return nil
-	}
-	key, err := delivery.PauseKey(p.Node)
-	if err != nil {
-		return err
-	}
-	raw, err := p.Load(key)
-	if err != nil {
-		return fmt.Errorf("buildstep: reading the pause of %s: %w", p.Node, err)
-	}
-	if raw == nil {
-		return nil
-	}
-	v, err := delivery.DecodePause(raw)
-	if err != nil {
-		return fmt.Errorf("buildstep: the pause of %s: %w", p.Node, err)
-	}
-	p.mu.Lock()
-	p.paused = v.Paused
-	p.mu.Unlock()
-	return nil
-}
-
-// Paused says whether the puller takes no asks.
-func (p *Puller) Paused() bool {
-	p.mu.Lock()
-	defer p.mu.Unlock()
-	return p.paused
-}
-
-// InHand is how many asks run now.
-func (p *Puller) InHand() int {
-	p.mu.Lock()
-	defer p.mu.Unlock()
-	return p.inHand
-}
-
-// RunningAsk is an ask a puller runs now, as its seat's current verb says it.
-type RunningAsk struct {
-	ID      string    `json:"id"`
-	Kind    string    `json:"kind"`
-	Module  string    `json:"module,omitempty"`
-	Started time.Time `json:"started"`
-}
-
-// Running are the asks the puller runs now, oldest first.
-func (p *Puller) Running() []RunningAsk {
-	p.mu.Lock()
-	defer p.mu.Unlock()
-	out := make([]RunningAsk, 0, len(p.running))
-	for _, r := range p.running {
-		out = append(out, r)
-	}
-	sort.Slice(out, func(i, j int) bool { return out[i].Started.Before(out[j].Started) })
-	return out
-}
-
-// room says whether the puller may take one more ask now.
-func (p *Puller) room() bool {
-	ok, _, _ := p.roomNow()
-	return ok
-}
-
-// roomNow is room, with the capacity and the asks in hand it was judged on.
-func (p *Puller) roomNow() (ok bool, capacity, inHand int) {
-	capacity = p.CapacityDetail().Effective
-	p.mu.Lock()
-	defer p.mu.Unlock()
-	return !p.paused && p.inHand < capacity, capacity, p.inHand
-}
-
-// CapacityNow is the capacity the puller judges by (CapacityDetail's Effective).
-func (p *Puller) CapacityNow() int {
-	return p.CapacityDetail().Effective
-}
-
-// CapacityDetail is the capacity the puller judges by now and why: the configured one (the config watch's last value,
-// else Capacity), bounded by the node's build slice when CoresPerStep is set (EffectiveCapacity), its quota read now. A
-// change from what it said last is logged and written to `capacity.<node>` of the pauses state (PausePut), so the
-// delivery view says it too.
-func (p *Puller) CapacityDetail() delivery.Capacity {
-	p.mu.Lock()
-	watched, has := p.watched, p.hasWatched
-	p.mu.Unlock()
-	configured, from := 0, "the settings file"
-	switch {
-	case has:
-		configured, from = watched, "mesh-config, as the config watch handed it"
-	case p.Capacity != nil:
-		configured = p.Capacity()
-	}
-	var c delivery.Capacity
-	if p.CoresPerStep == nil {
-		c = delivery.Capacity{Configured: configured, Effective: configured, QuotaFrom: "not judged: the module names no cores a step needs",
-			Why: fmt.Sprintf("its configured capacity %d", configured)}
-	} else {
-		quota := p.Quota
-		if quota == nil {
-			quota = Quota
-		}
-		percent, qfrom := quota()
-		c = EffectiveCapacity(configured, percent, qfrom, p.CoresPerStep())
-	}
-	c.ConfiguredFrom = from
-	w, fault := p.window()
-	if fault != "" {
-		c.BuildHoursFault = fault
-		c.Why = fmt.Sprintf("%s; at any hour, because its build hours cannot be read: %s", c.Why, fault)
-	}
-	if w != nil {
-		at := now()
-		zone, _ := at.Zone()
-		c.BuildHours = w.String() + " " + zone
-		if !w.Open(at) && c.Effective > 0 {
-			c.OutsideHours = true
-			c.Why = fmt.Sprintf("0, outside its build hours %s until %s (otherwise %s)", c.BuildHours, w.NextEdge(at).Format("15:04"), c.Why)
-			c.Effective = 0
-		} else if c.Effective > 0 {
-			c.Why = fmt.Sprintf("%s; within its build hours %s until %s", c.Why, c.BuildHours, w.NextEdge(at).Format("15:04"))
-		}
-	}
-	p.sayCapacity(c)
-	return c
-}
-
-// window is the node's build window now (the config watch's last value, else BuildHours, else none), and why its value
-// cannot be read when it cannot.
-func (p *Puller) window() (*BuildWindow, string) {
-	p.mu.Lock()
-	w, fault, has := p.hours, p.hoursFault, p.hasHours
-	p.mu.Unlock()
-	if has {
-		return w, fault
-	}
-	if p.BuildHours != nil {
-		return p.BuildHours()
-	}
-	return nil, ""
-}
-
-// untilEdge is how long until the build window's next edge, and false when the node has no window.
-func (p *Puller) untilEdge() (time.Duration, bool) {
-	w, _ := p.window()
-	if w == nil {
-		return 0, false
-	}
-	at := now()
-	return w.NextEdge(at).Sub(at), true
-}
-
-// sayCapacity logs c when it differs from what was said last, and writes it to the node's capacity key until a write
-// lands (a failed write is tried again at the next judgement, its error said once).
-func (p *Puller) sayCapacity(c delivery.Capacity) {
-	p.mu.Lock()
-	same := p.hasJudged && p.judged.Effective == c.Effective && p.judged.Configured == c.Configured && p.judged.ByCPU == c.ByCPU &&
-		p.judged.CoresPerStep == c.CoresPerStep && p.judged.QuotaCores == c.QuotaCores && p.judged.OutsideHours == c.OutsideHours &&
-		p.judged.BuildHours == c.BuildHours && p.judged.BuildHoursFault == c.BuildHoursFault
-	if !same {
-		p.judged, p.hasJudged, p.capWritten = c, true, false
-	}
-	write := !p.capWritten && p.PausePut != nil
-	p.mu.Unlock()
-	if !same {
-		p.logf("the %s build capacity of %s is %s (configured from %s)", p.Language, p.Node, c.Why, c.ConfiguredFrom)
-	}
-	if !write {
-		return
-	}
-	key, err := delivery.CapacityKey(p.Node)
-	if err != nil {
-		return
-	}
-	c.At = now()
-	raw, err := delivery.EncodeCapacity(c)
-	if err == nil {
-		_, err = p.PausePut(key, json.RawMessage(raw))
-	}
-	p.mu.Lock()
-	defer p.mu.Unlock()
-	if err == nil {
-		p.capWritten, p.capFault = true, ""
-		return
-	}
-	if err.Error() != p.capFault {
-		p.capFault = err.Error()
-		p.logf("the %s build capacity of %s could not be written to %s (tried again at the next judgement): %v", p.Language, p.Node, key, err)
-	}
-}
-
-// Pull takes and runs asks until ctx ends. An ask still running then is neither ended nor acknowledged: the stream
-// delivers it again, to another node or to this one restarted.
-func (p *Puller) Pull(ctx context.Context) error {
-	p.init()
-	if p.Source == nil || p.Put == nil || p.Run == nil {
-		return errors.New("buildstep: a puller needs its source, its steps' put and its run")
-	}
-	if err := p.restore(); err != nil {
-		// An unreadable pause degrades to not paused, said once: a puller that stops silently is the worse failure, and a
-		// node kept from building is held by its capacity (0), not by a pause.
-		p.logf("the pause of %s cannot be read: %v; pulling as not paused", p.Node, err)
-	}
-	go p.watchCapacity() // WatchConfigServed waits for Serve, which a module starts after its pull
-	go p.watchHours()
-	wait := p.PullWait
-	if wait <= 0 {
-		wait = DefaultPullWait
-	}
-	for {
-		if err := ctx.Err(); err != nil {
-			return err
-		}
-		if ok, capacity, inHand := p.roomNow(); !ok {
-			// Parked until something wakes it: a capacity change (the config watch), a resume, or a step's end. Every
-			// park logs once, so a puller that sits idle says why (issue 1887).
-			p.logf("the %s puller on %s parks: %d of capacity %d in hand, paused %v", p.Language, p.Node, inHand, capacity, p.Paused())
-			var edge <-chan time.Time // the build window's next edge, when the node has one: one timer, not a poll
-			stop := func() bool { return false }
-			if d, ok := p.untilEdge(); ok {
-				t := time.NewTimer(d + time.Second)
-				edge, stop = t.C, t.Stop
-			}
-			select {
-			case <-ctx.Done():
-				stop()
-				return ctx.Err()
-			case <-p.wake:
-			case <-edge:
-			}
-			stop()
-			_, capacity, inHand = p.roomNow()
-			p.logf("the %s puller on %s wakes: %d of capacity %d in hand, paused %v", p.Language, p.Node, inHand, capacity, p.Paused())
-			continue
-		}
-		pullWait := wait
-		if d, ok := p.untilEdge(); ok && d < pullWait {
-			pullWait = d // a pull does not wait past the window's close
-		}
-		msg, err := p.next(ctx, pullWait)
-		if err != nil {
-			if ctx.Err() != nil {
-				return ctx.Err()
-			}
-			p.logf("the %s asks cannot be pulled: %v", p.Language, err)
-			select { // the pull's own wait before the next try, as an empty pull's
-			case <-ctx.Done():
-				return ctx.Err()
-			case <-p.wake:
-			case <-time.After(wait):
-			}
-			continue
-		}
-		if msg == nil {
-			continue
-		}
-		p.take(ctx, msg)
-	}
-}
-
-// next is one ask from the workers in their order: one already waiting on delivery, check or recheck, and when none
-// waits, a pull of the delivery worker that waits for one.
-//
-// A kind whose worker handed an ask this node declined is left out until that wait ended (issue 890): the pull's own
-// wait, no timer of its own.
-func (p *Puller) next(ctx context.Context, wait time.Duration) (*Pulled, error) {
-	p.mu.Lock()
-	declined := p.declined
-	p.mu.Unlock()
-	for _, kind := range delivery.AskKinds {
-		if declined[kind] {
-			continue
-		}
-		msg, err := p.Source.Next(ctx, kind, 0)
-		if err != nil || msg != nil {
-			return withKind(msg, kind), err
-		}
-	}
-	msg, err := p.Source.Next(ctx, delivery.AskDelivery, wait)
-	p.mu.Lock()
-	p.declined = nil
-	p.mu.Unlock()
-	return withKind(msg, delivery.AskDelivery), err
-}
-
-// decline ends the step of an ask this node lacks a need of, refused as declined with what it lacks, and drops the
-// message: the asker puts the ask again under a new id (issue 890). A message whose decline cannot be written is handed
-// back, as one whose start cannot be.
-func (p *Puller) decline(msg *Pulled, ask delivery.StepAsk, lacks []string) {
-	step, key, err := begin(p.Put, p.Node, ask.Kind+" ask", ask.ID, AskWhat(ask))
-	if err == nil {
-		why := Refuse("the ask %s needs %s, and %s lacks %s: it is left to a node that has it", ask.ID,
-			strings.Join(ask.Needs, ", "), p.Node, strings.Join(lacks, ", "))
-		step.Ended = now().UTC()
-		step.State, step.Reason = delivery.StepRefused, why.Error()
-		step.Result, err = json.Marshal(delivery.StepDeclined{Declined: true, Needs: ask.Needs, Lacks: lacks})
-		if err == nil {
-			err = writeEnd(p.Put, key, step)
-		}
-	}
-	if err != nil {
-		p.logf("the ask %s cannot be declined on %s, so it is given back: %v", ask.ID, p.Node, err)
-		_ = msg.Nak()
-		return
-	}
-	p.logf("the ask %s is declined on %s: it needs %s, and this node lacks %s", ask.ID, p.Node, strings.Join(ask.Needs, ", "), strings.Join(lacks, ", "))
-	_ = msg.Term()
-	p.mu.Lock()
-	if p.declined == nil {
-		p.declined = map[string]bool{}
-	}
-	p.declined[msg.Kind] = true
-	p.mu.Unlock()
-}
-
-func withKind(msg *Pulled, kind string) *Pulled {
-	if msg != nil {
-		msg.Kind = kind
-	}
-	return msg
-}
-
-// take starts one ask: it decodes it, refuses one that is not of this seat, and runs it as a step under its own id.
-func (p *Puller) take(ctx context.Context, msg *Pulled) {
-	kind := msg.Kind
-	ask, err := delivery.DecodeStepAsk(msg.Data)
-	if err == nil && (ask.Language != p.Language || (kind != "" && ask.Kind != kind)) {
-		err = fmt.Errorf("the ask %s is a %s ask of %s, pulled from the %s %s worker", ask.ID, ask.Kind, ask.Language, p.Language, kind)
-	}
-	if err != nil {
-		// An ask that is not one runs nowhere: delivering it again would only fail again.
-		p.logf("an ask dropped: %v", err)
-		_ = msg.Term()
-		return
-	}
-	if lacks := delivery.Lacks(ask.Needs, p.Has); len(lacks) > 0 {
-		p.decline(msg, ask, lacks)
-		return
-	}
-	step, key, err := begin(p.Put, p.Node, ask.Kind+" ask", ask.ID, AskWhat(ask))
-	if err != nil {
-		p.logf("the ask %s cannot start on %s: %v", ask.ID, p.Node, err)
-		_ = msg.Nak()
-		return
-	}
-	if msg.Delivered > delivery.AskRuns {
-		// Run AskRuns times and never ended: each run took its node down or died with it. It is run no more, and said
-		// (issue 1907): the asker's key fails with why.
-		why := fmt.Errorf("the ask was taken %d times and no run of it ended: each took its build node down or died with it, so it is run no more (poison)", msg.Delivered-1)
-		p.logf("the ask %s is ended on %s: %v", ask.ID, p.Node, why)
-		_ = finish(p.Put, key, step, nil, why, p.Logf) // run no more either way: the asker's bound says it then
-		_ = msg.Term()
-		return
-	}
-	module := ""
-	if ask.Build != nil {
-		module = ask.Build.Module
-	}
-	p.mu.Lock()
-	p.inHand++
-	if p.running == nil {
-		p.running = map[string]RunningAsk{}
-	}
-	p.running[ask.ID] = RunningAsk{ID: ask.ID, Kind: ask.Kind, Module: module, Started: step.Started}
-	p.mu.Unlock()
-	p.logf("the %s ask %s starts on %s: %s", ask.Kind, ask.ID, p.Node, step.What)
-	go p.run(ctx, msg, ask, key, step)
-}
-
-func (p *Puller) run(ctx context.Context, msg *Pulled, ask delivery.StepAsk, key string, step delivery.Step) {
-	defer func() {
-		p.mu.Lock()
-		p.inHand--
-		delete(p.running, ask.ID)
-		p.mu.Unlock()
-		p.Wake()
-	}()
-	beat := p.Heartbeat
-	if beat <= 0 {
-		beat = DefaultHeartbeat
-	}
-	done := make(chan struct{})
-	go func() {
-		t := time.NewTicker(beat)
-		defer t.Stop()
-		for {
-			select {
-			case <-done:
-				return
-			case <-t.C:
-				if msg.InProgress != nil {
-					_ = msg.InProgress()
-				}
-			}
-		}
-	}()
-	ph := &phases{put: p.Put, key: key, step: step, logf: p.Logf, prefix: fmt.Sprintf("the %s ask %s on %s", ask.Kind, ask.ID, p.Node)}
-	result, err := protect(ctx, func(ctx context.Context) (any, error) {
-		return p.Run(context.WithValue(ctx, phaseKey{}, ph), ask)
-	})
-	step = ph.end() // its end keeps the phase it ended in
-	close(done)
-	if ctx.Err() != nil {
-		// The process stops: the ask is neither ended nor acknowledged here, so the stream gives it to a node that runs.
-		return
-	}
-	if ferr := finish(p.Put, key, step, result, err, p.Logf); ferr != nil {
-		// No end was written: the ask is not acknowledged as done, so the stream gives it again and a run that can
-		// write its end (or the poison rule, issue 1907) ends it where its asker sees it (issue 1930).
-		p.logf("the ask %s ran on %s and no end of it could be written, so it is given back: %v", ask.ID, p.Node, ferr)
-		_ = msg.Nak()
-		return
-	}
-	outcome := "passed"
-	if err != nil {
-		outcome = "did not pass: " + err.Error()
-		if len(outcome) > 300 {
-			outcome = outcome[:300] + "..."
-		}
-	}
-	p.logf("the %s ask %s ended on %s after %s, in its phase %q; %s", ask.Kind, ask.ID, p.Node,
-		now().Sub(step.Started).Round(time.Second), step.Phase, outcome)
-	if aerr := msg.Ack(); aerr != nil {
-		p.logf("the ask %s ended on %s and its acknowledgement failed: %v", ask.ID, p.Node, aerr)
-	}
-}
-
-// watchCapacity follows the module's config value `capacity` when WatchConfig is set (issue 1887, 2026-10-25: g14's
-// puller started at capacity 0 sat parked with capacity 2 set, because nothing woke it to read its settings file
-// again). The value comes as mesh-config resolved it for this node, the event of the change itself: the runtime hands
-// the value now and then each change its machine's provisioner client says moved, so nothing polls, and the puller does
-// not wait for the node-engine to fill its settings file again. Each value handed is kept, used in place of Capacity,
-// and wakes the puller. A watch that cannot start leaves the puller on Capacity, said once.
-func (p *Puller) watchCapacity() {
-	if p.WatchConfig == nil {
-		return
-	}
-	err := p.WatchConfig(CapacitySetting, func(c stdio.ProvisionChange) error {
-		n, why := p.capacityFrom(c)
-		p.mu.Lock()
-		before, had := p.watched, p.hasWatched
-		p.watched, p.hasWatched = n, true
-		p.mu.Unlock()
-		switch {
-		case why != "":
-			p.logf("the %s puller on %s pulls nothing: %s", p.Language, p.Node, why)
-		case !had || before != n:
-			p.logf("the %s build capacity of %s is %d, as mesh-config resolved it", p.Language, p.Node, n)
-		}
-		p.Wake()
-		return nil
-	})
-	if err != nil {
-		p.logf("the %s build capacity of %s cannot be followed on the bus, so it is read from the settings file when the "+
-			"puller wakes: %v", p.Language, p.Node, err)
-	}
-}
-
-// watchHours follows the module's config value `build-hours` when WatchConfig and BuildHours are set, as watchCapacity
-// follows `capacity`: each value handed is kept, used in place of BuildHours, and wakes the puller. A value that cannot
-// be read is no window, said; a watch that cannot start leaves the puller on BuildHours, said once.
-func (p *Puller) watchHours() {
-	if p.WatchConfig == nil || p.BuildHours == nil {
-		return
-	}
-	err := p.WatchConfig(BuildHoursSetting, func(c stdio.ProvisionChange) error {
-		setting := ""
-		var w *BuildWindow
-		var why string
-		switch {
-		case c.Refused != "":
-			why = "its build hours are no longer answered: " + c.Refused
-		case len(c.Value) > 0 && string(c.Value) != "null" && json.Unmarshal(c.Value, &setting) != nil:
-			why = fmt.Sprintf("the setting %s %s is not a string", BuildHoursSetting, c.Value)
-		default:
-			var err error
-			if w, err = ParseBuildHours(setting, p.Node); err != nil {
-				why = err.Error()
-			}
-		}
-		p.mu.Lock()
-		p.hours, p.hoursFault, p.hasHours = w, why, true
-		p.mu.Unlock()
-		if why != "" {
-			p.logf("the %s puller on %s builds at any hour: %s", p.Language, p.Node, why)
-		}
-		p.Wake()
-		return nil
-	})
-	if err != nil {
-		p.logf("the %s build hours of %s cannot be followed on the bus, so they are read from the settings file: %v", p.Language, p.Node, err)
-	}
-}
-
-// WatchConfigServed is stdio.WatchConfig once Serve has the runtime's channel (stdio.Served): a build module starts its
-// pull before it serves, and a watch asked before that would be refused.
-func WatchConfigServed(key string, handle func(stdio.ProvisionChange) error) error {
-	<-stdio.Served()
-	return stdio.WatchConfig(key, handle)
-}
-
-// capacityFrom is the node's capacity in one value the watch handed, and why it is 0 when it cannot be read.
-func (p *Puller) capacityFrom(c stdio.ProvisionChange) (int, string) {
-	if c.Refused != "" {
-		return 0, "its capacity is no longer answered: " + c.Refused
-	}
-	setting := ""
-	if len(c.Value) > 0 && string(c.Value) != "null" {
-		if err := json.Unmarshal(c.Value, &setting); err != nil {
-			return 0, fmt.Sprintf("its capacity %s is not a string", c.Value)
-		}
-	}
-	n, err := capacityOf(setting, p.Node)
-	if err != nil {
-		return 0, err.Error()
-	}
-	return n, ""
-}

go/buildstep/pull_bus.go

@@ -1,102 +0,0 @@
-package buildstep
-
-import (
-	"context"
-	"fmt"
-	"sync"
-	"time"
-
-	"github.com/nats-io/nats.go/jetstream"
-
-	"git.novox.be/novox/mesh-sdk/go/delivery"
-)
-
-// JetStreamAsks is a build seat's workers on the bus: the shared pull consumer of each kind on the seat's stream
-// (delivery.AskStream, AskWorker), which the broker makes when the seat is declared; a holder only binds them.
-type JetStreamAsks struct {
-	JS       jetstream.JetStream
-	Language string
-
-	mu   sync.Mutex
-	cons map[string]jetstream.Consumer
-}
-
-func (s *JetStreamAsks) consumer(ctx context.Context, kind string) (jetstream.Consumer, error) {
-	s.mu.Lock()
-	defer s.mu.Unlock()
-	if c, ok := s.cons[kind]; ok {
-		return c, nil
-	}
-	stream, err := delivery.AskStream(s.Language)
-	if err != nil {
-		return nil, err
-	}
-	worker, err := delivery.AskWorker(s.Language, kind)
-	if err != nil {
-		return nil, err
-	}
-	c, err := s.JS.Consumer(ctx, stream, worker)
-	if err != nil {
-		return nil, fmt.Errorf("binding the %s worker %s on %s: %w", kind, worker, stream, err)
-	}
-	if s.cons == nil {
-		s.cons = map[string]jetstream.Consumer{}
-	}
-	s.cons[kind] = c
-	return c, nil
-}
-
-// Next is AskSource's: a fetch of one with no wait when wait is 0, else one that waits at most wait.
-func (s *JetStreamAsks) Next(ctx context.Context, kind string, wait time.Duration) (*Pulled, error) {
-	c, err := s.consumer(ctx, kind)
-	if err != nil {
-		return nil, err
-	}
-	var batch jetstream.MessageBatch
-	if wait <= 0 {
-		batch, err = c.FetchNoWait(1)
-	} else {
-		batch, err = c.Fetch(1, jetstream.FetchMaxWait(wait))
-	}
-	if err != nil {
-		return nil, err
-	}
-	select {
-	case msg, ok := <-batch.Messages():
-		if !ok {
-			return nil, batch.Error()
-		}
-		var delivered uint64 = 1
-		if meta, err := msg.Metadata(); err == nil && meta != nil {
-			delivered = meta.NumDelivered
-		}
-		return &Pulled{Data: append([]byte(nil), msg.Data()...), Delivered: delivered,
-			Ack: msg.Ack, InProgress: msg.InProgress, Nak: msg.Nak, Term: msg.Term}, nil
-	case <-ctx.Done():
-		return nil, ctx.Err()
-	}
-}
-
-// DeclareAskWorkers makes language's seat stream and its three workers on a bus with no broker: a test's (the build
-// modules' integration tests start one). On the mesh the broker declares them from the seat, as it declares every
-// seat's stream (mesh-controller internal/broker SeatStreams); a holder never does.
-func DeclareAskWorkers(ctx context.Context, js jetstream.JetStream, language string, ackWait time.Duration) error {
-	stream, err := delivery.AskStream(language)
-	if err != nil {
-		return err
-	}
-	seat, _ := delivery.BuildSeat(language)
-	if _, err := js.CreateOrUpdateStream(ctx, jetstream.StreamConfig{Name: stream, Subjects: []string{"mesh.seat." + seat + ".accept.>"},
-		Retention: jetstream.WorkQueuePolicy}); err != nil {
-		return fmt.Errorf("the stream %s: %w", stream, err)
-	}
-	for _, kind := range delivery.AskKinds {
-		worker, _ := delivery.AskWorker(language, kind)
-		subject, _ := delivery.AskSubject(language, kind)
-		if _, err := js.CreateOrUpdateConsumer(ctx, stream, jetstream.ConsumerConfig{Durable: worker, FilterSubject: subject,
-			AckPolicy: jetstream.AckExplicitPolicy, AckWait: ackWait, MaxDeliver: 5}); err != nil {
-			return fmt.Errorf("the worker %s: %w", worker, err)
-		}
-	}
-	return nil
-}

go/buildstep/pull_capacity_test.go

@@ -1,39 +0,0 @@
-package buildstep
-
-import (
-	"encoding/json"
-	"sync"
-	"testing"
-
-	stdio "git.novox.be/novox/mesh-sdk/go"
-)
-
-// configWatch is a double of stdio.WatchConfig: it hands the value now at the start, as the runtime does, and a test
-// hands each change after with set.
-type configWatch struct {
-	mu     sync.Mutex
-	value  string
-	handle func(stdio.ProvisionChange) error
-	asked  string
-}
-
-func (w *configWatch) watch(key string, handle func(stdio.ProvisionChange) error) error {
-	w.mu.Lock()
-	w.asked, w.handle = key, handle
-	value := w.value
-	w.mu.Unlock()
-	return handle(stdio.ProvisionChange{Kind: "config", Key: key, Value: json.RawMessage(`"` + value + `"`)})
-}
-
-func (w *configWatch) set(t *testing.T, value string) {
-	t.Helper()
-	w.mu.Lock()
-	handle, key := w.handle, w.asked
-	w.mu.Unlock()
-	if handle == nil {
-		t.Fatal("the puller watches no config value")
-	}
-	if err := handle(stdio.ProvisionChange{Kind: "config", Key: key, Value: json.RawMessage(`"` + value + `"`)}); err != nil {
-		t.Fatal(err)
-	}
-}

go/buildstep/pull_fake.go

@@ -1,113 +0,0 @@
-package buildstep
-
-import (
-	"context"
-	"sync"
-	"time"
-
-	"git.novox.be/novox/mesh-sdk/go/delivery"
-)
-
-// FakeAsks is a test double of a seat's workers for the build modules' unit tests: Publish puts an ask on a kind's
-// worker, Next hands them out in their order, and the fates the puller gives them are counted. Safe for concurrent use.
-type FakeAsks struct {
-	mu      sync.Mutex
-	waiting map[string][][]byte
-	added   chan struct{}
-	// Acked, Termed and Naked are the asks' ids or data by fate, InProgress how many heartbeats were given.
-	Acked, Termed, Naked []string
-	InProgress           int
-	// Delivered, when set, is the delivery count every ask handed over says (1 when 0): a test of a poisoned ask sets it.
-	Delivered uint64
-}
-
-// NewFakeAsks is an empty double.
-func NewFakeAsks() *FakeAsks {
-	return &FakeAsks{waiting: map[string][][]byte{}, added: make(chan struct{}, 1)}
-}
-
-// Publish puts an encoded ask on kind's worker.
-func (f *FakeAsks) Publish(kind string, data []byte) {
-	f.mu.Lock()
-	f.waiting[kind] = append(f.waiting[kind], data)
-	f.mu.Unlock()
-	select {
-	case f.added <- struct{}{}:
-	default:
-	}
-}
-
-// PublishAsk encodes a and puts it on its kind's worker.
-func (f *FakeAsks) PublishAsk(a delivery.StepAsk) error {
-	raw, err := delivery.EncodeStepAsk(a)
-	if err != nil {
-		return err
-	}
-	f.Publish(a.Kind, raw)
-	return nil
-}
-
-// Waiting is how many asks wait on kind's worker.
-func (f *FakeAsks) Waiting(kind string) int {
-	f.mu.Lock()
-	defer f.mu.Unlock()
-	return len(f.waiting[kind])
-}
-
-// Fates is a copy of the acked, termed and naked lists.
-func (f *FakeAsks) Fates() (acked, termed, naked []string) {
-	f.mu.Lock()
-	defer f.mu.Unlock()
-	return append([]string(nil), f.Acked...), append([]string(nil), f.Termed...), append([]string(nil), f.Naked...)
-}
-
-// Next is AskSource's.
-func (f *FakeAsks) Next(ctx context.Context, kind string, wait time.Duration) (*Pulled, error) {
-	var deadline <-chan time.Time
-	if wait > 0 {
-		t := time.NewTimer(wait)
-		defer t.Stop()
-		deadline = t.C
-	}
-	for {
-		f.mu.Lock()
-		if q := f.waiting[kind]; len(q) > 0 {
-			data := q[0]
-			f.waiting[kind] = q[1:]
-			f.mu.Unlock()
-			return f.pulled(data), nil
-		}
-		f.mu.Unlock()
-		if wait <= 0 {
-			return nil, nil
-		}
-		select {
-		case <-ctx.Done():
-			return nil, ctx.Err()
-		case <-deadline:
-			return nil, nil
-		case <-f.added:
-		}
-	}
-}
-
-func (f *FakeAsks) pulled(data []byte) *Pulled {
-	id := string(data)
-	if a, err := delivery.DecodeStepAsk(data); err == nil {
-		id = a.ID
-	}
-	fate := func(list *[]string) func() error {
-		return func() error {
-			f.mu.Lock()
-			*list = append(*list, id)
-			f.mu.Unlock()
-			return nil
-		}
-	}
-	delivered := f.Delivered
-	if delivered == 0 {
-		delivered = 1
-	}
-	return &Pulled{Data: data, Delivered: delivered, Ack: fate(&f.Acked), Nak: fate(&f.Naked), Term: fate(&f.Termed),
-		InProgress: func() error { f.mu.Lock(); f.InProgress++; f.mu.Unlock(); return nil }}
-}

go/buildstep/pull_integration_test.go

@@ -1,144 +0,0 @@
-//go:build integration
-
-package buildstep
-
-import (
-	"context"
-	"strings"
-	"sync"
-	"testing"
-	"time"
-
-	"github.com/nats-io/nats.go"
-	"github.com/nats-io/nats.go/jetstream"
-
-	"git.novox.be/novox/mesh-sdk/go/delivery"
-	"git.novox.be/novox/mesh-sdk/go/testbus"
-)
-
-func askBus(t *testing.T, ackWait time.Duration) jetstream.JetStream {
-	t.Helper()
-	nc, err := nats.Connect(testbus.URL(t))
-	if err != nil {
-		t.Fatal(err)
-	}
-	t.Cleanup(nc.Close)
-	js, err := jetstream.New(nc)
-	if err != nil {
-		t.Fatal(err)
-	}
-	if err := DeclareAskWorkers(context.Background(), js, delivery.AskGo, ackWait); err != nil {
-		t.Fatal(err)
-	}
-	return js
-}
-
-func publishAsk(t *testing.T, js jetstream.JetStream, a delivery.StepAsk) {
-	t.Helper()
-	raw, err := delivery.EncodeStepAsk(a)
-	if err != nil {
-		t.Fatal(err)
-	}
-	subject, _ := delivery.AskSubject(a.Language, a.Kind)
-	if _, err := js.Publish(context.Background(), subject, raw); err != nil {
-		t.Fatal(err)
-	}
-}
-
-// 1887/A2a, 1887/AC-order, 1887/AC-pull on the real server: a check ask published before a delivery ask runs after it;
-// with capacity 2 and three asks two run, the third waits in the stream and starts when one ends.
-func TestPullOrderAndCapacityOnTheBus(t *testing.T) {
-	js := askBus(t, 30*time.Second)
-	check, first, second := testAsk(delivery.AskCheck), testAsk(delivery.AskDelivery), testAsk(delivery.AskDelivery)
-	publishAsk(t, js, check)
-	publishAsk(t, js, first)
-	publishAsk(t, js, second)
-	release := make(chan struct{})
-	var mu sync.Mutex
-	var order []string
-	st := newSteps()
-	p := &Puller{Source: &JetStreamAsks{JS: js, Language: delivery.AskGo}, Language: delivery.AskGo, Node: "shanks", Put: st.put,
-		Capacity: func() int { return 2 }, PullWait: 200 * time.Millisecond,
-		Run: func(ctx context.Context, a delivery.StepAsk) (any, error) {
-			mu.Lock()
-			order = append(order, a.ID)
-			mu.Unlock()
-			<-release
-			return nil, nil
-		}}
-	ctx, cancel := context.WithCancel(context.Background())
-	defer cancel()
-	go p.Pull(ctx)
-	waitFor(t, "two in hand", func() bool { return p.InHand() == 2 })
-	time.Sleep(500 * time.Millisecond)
-	mu.Lock()
-	if len(order) != 2 || order[0] != first.ID || order[1] != second.ID {
-		t.Fatalf("ran %v, want the two delivery asks %s %s first", order, first.ID, second.ID)
-	}
-	mu.Unlock()
-	release <- struct{}{}
-	waitFor(t, "the check taken", func() bool { mu.Lock(); defer mu.Unlock(); return len(order) == 3 })
-	close(release)
-	waitFor(t, "every step ended", func() bool {
-		for _, a := range []delivery.StepAsk{check, first, second} {
-			key, _ := delivery.AskStepKey("shanks", a.ID)
-			if s, ok := st.get(key); !ok || s.State != delivery.StepPassed {
-				return false
-			}
-		}
-		return true
-	})
-	info, err := js.Stream(ctx, "SEAT_NODE_BUILD_GO")
-	if err != nil {
-		t.Fatal(err)
-	}
-	waitFor(t, "the stream empty (every ask acknowledged)", func() bool {
-		si, err := info.Info(ctx)
-		return err == nil && si.State.Msgs == 0
-	})
-}
-
-// 1887/A2c, ADR 0525 §6: a killed puller's ask is redelivered by the stream's acknowledgement wait to the other node,
-// whose step key names the reference.
-func TestPullRedeliversAKilledPullersAsk(t *testing.T) {
-	js := askBus(t, 2*time.Second)
-	a := testAsk(delivery.AskDelivery)
-	publishAsk(t, js, a)
-	st := newSteps()
-	taken := make(chan struct{})
-	dying := &Puller{Source: &JetStreamAsks{JS: js, Language: delivery.AskGo}, Language: delivery.AskGo, Node: "ace", Put: st.put,
-		Capacity: func() int { return 1 }, PullWait: 200 * time.Millisecond, Heartbeat: time.Hour,
-		Run: func(ctx context.Context, a delivery.StepAsk) (any, error) {
-			close(taken)
-			<-ctx.Done()
-			return nil, ctx.Err()
-		}}
-	kill, killed := context.WithCancel(context.Background())
-	go dying.Pull(kill)
-	<-taken
-	killed()
-	other := &Puller{Source: &JetStreamAsks{JS: js, Language: delivery.AskGo}, Language: delivery.AskGo, Node: "shanks", Put: st.put,
-		Capacity: func() int { return 1 }, PullWait: 200 * time.Millisecond,
-		Run: func(ctx context.Context, a delivery.StepAsk) (any, error) {
-			return delivery.BuildAnswer{Artifacts: []delivery.AskBuilt{{Artifact: "bundle", Digest: "sha256:00", Reference: "artifact-store://x"}}}, nil
-		}}
-	ctx, cancel := context.WithCancel(context.Background())
-	defer cancel()
-	go other.Pull(ctx)
-	key, _ := delivery.AskStepKey("shanks", a.ID)
-	deadline := time.Now().Add(10 * time.Second)
-	for {
-		if s, ok := st.get(key); ok && s.State == delivery.StepPassed {
-			if want := `artifact-store://x`; !contains(string(s.Result), want) {
-				t.Fatalf("the step's result %s names no %s", s.Result, want)
-			}
-			return
-		}
-		if time.Now().After(deadline) {
-			t.Fatalf("the killed puller's ask was not taken by shanks within 10 s")
-		}
-		time.Sleep(20 * time.Millisecond)
-	}
-}
-
-func contains(s, sub string) bool { return strings.Contains(s, sub) }

go/buildstep/pull_seat.go

@@ -1,44 +0,0 @@
-package buildstep
-
-import (
-	"context"
-	"time"
-
-	stdio "git.novox.be/novox/mesh-sdk/go"
-	"git.novox.be/novox/mesh-sdk/go/delivery"
-)
-
-// SeatAsks is a build seat's workers as a tools bundle reaches them: through its runtime's seat pull and settle
-// (stdio.SeatPull, SeatSettle; issue 1887 A11), one message per pull, only from the workers the module's membership
-// lists.
-type SeatAsks struct {
-	Language string
-	// Pull and Settle are stdio.SeatPull and stdio.SeatSettle when nil; a test gives its own.
-	Pull   func(worker string, wait time.Duration) (*stdio.Pulled, error)
-	Settle func(id, fate string) error
-}
-
-// Next is AskSource's.
-func (s SeatAsks) Next(ctx context.Context, kind string, wait time.Duration) (*Pulled, error) {
-	pull, settle := s.Pull, s.Settle
-	if pull == nil {
-		pull = stdio.SeatPull
-	}
-	if settle == nil {
-		settle = stdio.SeatSettle
-	}
-	worker, err := delivery.AskWorker(s.Language, kind)
-	if err != nil {
-		return nil, err
-	}
-	if err := ctx.Err(); err != nil {
-		return nil, err
-	}
-	p, err := pull(worker, wait)
-	if err != nil || p == nil {
-		return nil, err
-	}
-	fate := func(f string) func() error { return func() error { return settle(p.ID, f) } }
-	return &Pulled{Data: p.Body, Delivered: p.Delivered, Ack: fate(stdio.SettleAck), InProgress: fate(stdio.SettleProgress),
-		Nak: fate(stdio.SettleNak), Term: fate(stdio.SettleTerm)}, nil
-}

go/buildstep/pull_seat_test.go

@@ -1,40 +0,0 @@
-package buildstep
-
-import (
-	"context"
-	"testing"
-	"time"
-
-	stdio "git.novox.be/novox/mesh-sdk/go"
-	"git.novox.be/novox/mesh-sdk/go/delivery"
-)
-
-// 1887/A11: a bundle's source pulls the kind's worker by its seat's name and settles each ask by the runtime's id.
-func TestSeatAsksPullsTheKindsWorkerAndSettlesByID(t *testing.T) {
-	var pulled []string
-	var settled []string
-	src := SeatAsks{Language: delivery.AskGo,
-		Pull: func(worker string, wait time.Duration) (*stdio.Pulled, error) {
-			pulled = append(pulled, worker)
-			if worker != "SEAT_NODE_BUILD_GO_CHECK_worker" {
-				return nil, nil
-			}
-			return &stdio.Pulled{ID: "p9", Worker: worker, Body: []byte(`{"v":1}`), Delivered: 2}, nil
-		},
-		Settle: func(id, fate string) error { settled = append(settled, id+" "+fate); return nil }}
-	if p, err := src.Next(context.Background(), delivery.AskDelivery, 0); err != nil || p != nil {
-		t.Fatalf("delivery = %+v, %v", p, err)
-	}
-	p, err := src.Next(context.Background(), delivery.AskCheck, time.Second)
-	if err != nil || p == nil || string(p.Data) != `{"v":1}` || p.Delivered != 2 {
-		t.Fatalf("check = %+v, %v", p, err)
-	}
-	_ = p.InProgress()
-	_ = p.Ack()
-	if len(pulled) != 2 || pulled[0] != "SEAT_NODE_BUILD_GO_DELIVERY_worker" {
-		t.Errorf("pulled %v", pulled)
-	}
-	if len(settled) != 2 || settled[0] != "p9 progress" || settled[1] != "p9 ack" {
-		t.Errorf("settled %v", settled)
-	}
-}

go/buildstep/pull_test.go

@@ -1,438 +0,0 @@
-package buildstep
-
-import (
-	"context"
-	"encoding/json"
-	"errors"
-	"fmt"
-	"strings"
-	"sync"
-	"sync/atomic"
-	"testing"
-	"time"
-
-	stdio "git.novox.be/novox/mesh-sdk/go"
-	"git.novox.be/novox/mesh-sdk/go/delivery"
-)
-
-// steps records a steps state's puts: the last value of each key.
-type steps struct {
-	mu   sync.Mutex
-	keys map[string]delivery.Step
-}
-
-func newSteps() *steps { return &steps{keys: map[string]delivery.Step{}} }
-
-func (s *steps) put(key string, value any) (uint64, error) {
-	raw, _ := value.(json.RawMessage)
-	st, err := delivery.DecodeStep(raw)
-	if err != nil {
-		return 0, err
-	}
-	s.mu.Lock()
-	s.keys[key] = st
-	s.mu.Unlock()
-	return 1, nil
-}
-
-func (s *steps) get(key string) (delivery.Step, bool) {
-	s.mu.Lock()
-	defer s.mu.Unlock()
-	st, ok := s.keys[key]
-	return st, ok
-}
-
-func testAsk(kind string) delivery.StepAsk {
-	id := NewID()
-	a := delivery.StepAsk{ID: id, Kind: kind, Language: delivery.AskGo, Asker: "mesh-delivery-builder", At: time.Now()}
-	fetch := map[string]any{"repository": "novox/x", "commit": "0123456789abcdef0123456789abcdef01234567"}
-	if kind == delivery.AskDelivery {
-		b := buildJobFixture
-		b.Fetch = fetch
-		a.Build = &b
-	} else {
-		a.Check = &delivery.CheckJob{Fetch: fetch, Levels: []string{delivery.LevelUnit}}
-	}
-	return a
-}
-
-var buildJobFixture = delivery.BuildJob{Module: "m", Path: ".", Artifacts: []delivery.AskArtifact{{Artifact: "bundle"}}}
-
-func waitFor(t *testing.T, what string, cond func() bool) {
-	t.Helper()
-	deadline := time.Now().Add(2 * time.Second)
-	for !cond() {
-		if time.Now().After(deadline) {
-			t.Fatalf("waited 2 s for %s", what)
-		}
-		time.Sleep(time.Millisecond)
-	}
-}
-
-// 1887/A2a: given a check ask published before a delivery ask and one slot, the delivery ask runs first.
-func TestPullTakesDeliveryBeforeCheck(t *testing.T) {
-	src, st := NewFakeAsks(), newSteps()
-	check, recheck, deliver := testAsk(delivery.AskCheck), testAsk(delivery.AskRecheck), testAsk(delivery.AskDelivery)
-	for _, a := range []delivery.StepAsk{recheck, check, deliver} {
-		if err := src.PublishAsk(a); err != nil {
-			t.Fatal(err)
-		}
-	}
-	var mu sync.Mutex
-	var order []string
-	p := &Puller{Source: src, Language: delivery.AskGo, Node: "shanks", Put: st.put, Capacity: func() int { return 1 },
-		PullWait: 10 * time.Millisecond, Run: func(ctx context.Context, a delivery.StepAsk) (any, error) {
-			mu.Lock()
-			order = append(order, a.Kind)
-			mu.Unlock()
-			return map[string]string{"ran": a.ID}, nil
-		}}
-	ctx, cancel := context.WithCancel(context.Background())
-	defer cancel()
-	go p.Pull(ctx)
-	waitFor(t, "three asks acked", func() bool { a, _, _ := src.Fates(); return len(a) == 3 })
-	mu.Lock()
-	defer mu.Unlock()
-	if want := []string{delivery.AskDelivery, delivery.AskCheck, delivery.AskRecheck}; len(order) != 3 || order[0] != want[0] || order[1] != want[1] || order[2] != want[2] {
-		t.Fatalf("order = %v, want %v", order, want)
-	}
-	key, _ := delivery.AskStepKey("shanks", deliver.ID)
-	s, ok := st.get(key)
-	if !ok || s.State != delivery.StepPassed || string(s.Result) != `{"ran":"`+deliver.ID+`"}` {
-		t.Fatalf("the step %s = %+v (%v)", key, s, ok)
-	}
-}
-
-// 1887/A2a, 1887/AC-pull: given capacity 2 and three asks waiting, two run and the third waits, and it starts when
-// one ends, with no timer. Issue 1806's follow-up: the 2 is the CPU's, a configured 3 bounded by a 12-core slice at 6
-// cores a step, said once in capacity.<node>; and issue 1890: a run's phase is written to its step key and logged with
-// its ask id, and its end keeps the last phase.
-func TestPullHoldsAtMostItsCapacity(t *testing.T) {
-	src, st := NewFakeAsks(), newSteps()
-	asks := []delivery.StepAsk{}
-	for i := 0; i < 3; i++ {
-		a := testAsk(delivery.AskDelivery)
-		asks = append(asks, a)
-		_ = src.PublishAsk(a)
-	}
-	release := make(chan struct{})
-	var mu sync.Mutex
-	started := 0
-	var said []string
-	capacities := map[string][]byte{}
-	quota := 1200
-	p := &Puller{Source: src, Language: delivery.AskGo, Node: "shanks", Put: st.put, Capacity: func() int { return 3 },
-		CoresPerStep: func() float64 { return 6 },
-		Quota:        func() (int, string) { mu.Lock(); defer mu.Unlock(); return quota, "a test's slice" },
-		PausePut: func(key string, v any) (uint64, error) {
-			mu.Lock()
-			capacities[key] = v.(json.RawMessage)
-			mu.Unlock()
-			return 1, nil
-		},
-		Logf:     func(f string, a ...any) { mu.Lock(); said = append(said, fmt.Sprintf(f, a...)); mu.Unlock() },
-		PullWait: 10 * time.Millisecond, Run: func(ctx context.Context, a delivery.StepAsk) (any, error) {
-			mu.Lock()
-			started++
-			mu.Unlock()
-			Phase(ctx, "unit: tests of 3 packages")
-			<-release
-			return nil, nil
-		}}
-	ctx, cancel := context.WithCancel(context.Background())
-	defer cancel()
-	go p.Pull(ctx)
-	waitFor(t, "two in hand", func() bool { return p.InHand() == 2 })
-	time.Sleep(30 * time.Millisecond) // three pull waits: the third must still wait
-	if p.InHand() != 2 || src.Waiting(delivery.AskDelivery) != 1 {
-		t.Fatalf("in hand %d, waiting %d; want 2 and 1", p.InHand(), src.Waiting(delivery.AskDelivery))
-	}
-	c := p.CapacityDetail()
-	if c.Effective != 2 || c.Configured != 3 || c.ByCPU != 2 || c.QuotaCores != 12 || !strings.Contains(c.Why, "bounded by the CPU") {
-		t.Fatalf("the capacity judged by = %+v, want 2 of a configured 3 bounded by 12 cores / 6", c)
-	}
-	mu.Lock()
-	raw := capacities["capacity.shanks"]
-	capLines := 0
-	for _, l := range said {
-		if strings.Contains(l, "build capacity of shanks is 2, bounded by the CPU") {
-			capLines++
-		}
-	}
-	mu.Unlock()
-	if got, err := delivery.DecodeCapacity(raw); err != nil || got.Effective != 2 || capLines != 1 {
-		t.Fatalf("capacity.shanks = %s (%v), said %d times; want effective 2, said once", raw, err, capLines)
-	}
-	waitFor(t, "a phase on the step key", func() bool {
-		key, _ := delivery.AskStepKey("shanks", p.Running()[0].ID)
-		s, _ := st.get(key)
-		return s.State == delivery.StepRunning && s.Phase == "unit: tests of 3 packages" && !s.PhaseAt.IsZero()
-	})
-	release <- struct{}{}
-	waitFor(t, "the third taken", func() bool { return src.Waiting(delivery.AskDelivery) == 0 })
-	// Taken from the source comes a moment before its run starts: wait for the start, not only the take.
-	waitFor(t, "the third started", func() bool { mu.Lock(); defer mu.Unlock(); return started == 3 })
-	close(release)
-	waitFor(t, "all acked", func() bool { a, _, _ := src.Fates(); return len(a) == 3 })
-	for _, a := range asks {
-		key, _ := delivery.AskStepKey("shanks", a.ID)
-		if s, _ := st.get(key); s.State != delivery.StepPassed || s.Phase != "unit: tests of 3 packages" {
-			t.Errorf("the end of %s = %+v, want passed in its last phase", a.ID, s)
-		}
-	}
-	mu.Lock()
-	logged := strings.Join(said, "\n")
-	quota = 600 // the cap lowered: one step at 6 cores, followed at the next judgement
-	mu.Unlock()
-	if !strings.Contains(logged, "the delivery ask "+asks[0].ID+" on shanks: unit: tests of 3 packages") {
-		t.Errorf("no journal line names the ask's phase: %s", logged)
-	}
-	if c := p.CapacityDetail(); c.Effective != 1 {
-		t.Errorf("after the quota fell to 6 cores, capacity %+v, want 1", c)
-	}
-}
-
-// An ask that is not one, or not this seat's, is dropped and runs nowhere. And issue 890/AC1: a check ask needing
-// node-build-node is declined on a node that lacks it (its step refused as declined, naming what it lacks, the message
-// dropped for the asker to put again), and runs on a node that has it.
-func TestPullDropsWhatIsNoAsk(t *testing.T) {
-	src, st := NewFakeAsks(), newSteps()
-	src.Publish(delivery.AskDelivery, []byte(`{"v":1}`))
-	other := testAsk(delivery.AskDelivery)
-	other.Language = delivery.AskNode
-	_ = src.PublishAsk(other)
-	placed := testAsk(delivery.AskCheck)
-	placed.Needs = []string{delivery.NeedNodeBuildNode}
-	if err := src.PublishAsk(placed); err != nil {
-		t.Fatal(err)
-	}
-	ran := false
-	p := &Puller{Source: src, Language: delivery.AskGo, Node: "ace", Put: st.put, Capacity: func() int { return 1 },
-		PullWait: 10 * time.Millisecond, Run: func(ctx context.Context, a delivery.StepAsk) (any, error) { ran = true; return nil, nil }}
-	ctx, cancel := context.WithCancel(context.Background())
-	defer cancel()
-	go p.Pull(ctx)
-	waitFor(t, "three termed", func() bool { _, tm, _ := src.Fates(); return len(tm) == 3 })
-	if ran {
-		t.Fatal("a wrong or a declined ask ran")
-	}
-	key, _ := delivery.AskStepKey("ace", placed.ID)
-	s, _ := st.get(key)
-	if d, ok := delivery.DeclinedOf(s); !ok || len(d.Lacks) != 1 || d.Lacks[0] != delivery.NeedNodeBuildNode || !strings.Contains(s.Reason, "lacks node-build-node") {
-		t.Fatalf("the declined step = %+v", s)
-	}
-	has, hasSteps := NewFakeAsks(), newSteps()
-	_ = has.PublishAsk(placed)
-	q := &Puller{Source: has, Language: delivery.AskGo, Node: "g14", Put: hasSteps.put, Capacity: func() int { return 1 },
-		PullWait: 10 * time.Millisecond, Has: func(n string) bool { return n == delivery.NeedNodeBuildNode },
-		Run: func(ctx context.Context, a delivery.StepAsk) (any, error) { return nil, nil }}
-	go q.Pull(ctx)
-	waitFor(t, "the placed ask acked where its need is met", func() bool { a, _, _ := has.Fates(); return len(a) == 1 })
-}
-
-// load reads the recorded steps state's raw values: the pause key is not a step, so it is kept apart.
-type kv struct {
-	mu   sync.Mutex
-	vals map[string][]byte
-}
-
-func (k *kv) put(key string, value any) (uint64, error) {
-	raw, _ := value.(json.RawMessage)
-	k.mu.Lock()
-	defer k.mu.Unlock()
-	if k.vals == nil {
-		k.vals = map[string][]byte{}
-	}
-	k.vals[key] = append([]byte(nil), raw...)
-	return 1, nil
-}
-
-func (k *kv) load(key string) ([]byte, error) {
-	k.mu.Lock()
-	defer k.mu.Unlock()
-	return k.vals[key], nil
-}
-
-// 1887/A2b, 1887/AC-zero, 1887/AC-wake: at capacity 0 the puller takes nothing; a capacity raised takes effect at the
-// next pull, or, with the config watch (g14 idle at capacity 2, 2026-10-25), at once when the value moves, with no
-// pause, resume or step end to wake it; a refused value pulls nothing, and a watch that cannot start leaves the
-// settings file's capacity.
-func TestPullAtCapacityZeroTakesNothing(t *testing.T) {
-	t.Run("settings file", func(t *testing.T) {
-		src, st := NewFakeAsks(), &kv{}
-		_ = src.PublishAsk(testAsk(delivery.AskDelivery))
-		var mu sync.Mutex
-		capacity := 0
-		p := &Puller{Source: src, Language: delivery.AskGo, Node: "novox", Put: st.put, PullWait: 10 * time.Millisecond,
-			Capacity: func() int { mu.Lock(); defer mu.Unlock(); return capacity },
-			Run:      func(ctx context.Context, a delivery.StepAsk) (any, error) { return nil, nil }}
-		ctx, cancel := context.WithCancel(context.Background())
-		defer cancel()
-		go p.Pull(ctx)
-		time.Sleep(50 * time.Millisecond)
-		if src.Waiting(delivery.AskDelivery) != 1 {
-			t.Fatal("a node at capacity 0 took an ask")
-		}
-		mu.Lock()
-		capacity = 1
-		mu.Unlock()
-		p.Wake()
-		waitFor(t, "the ask taken at capacity 1", func() bool { a, _, _ := src.Fates(); return len(a) == 1 })
-	})
-	t.Run("config watch wakes", func(t *testing.T) {
-		src, st := NewFakeAsks(), newSteps()
-		_ = src.PublishAsk(testAsk(delivery.AskDelivery))
-		w := &configWatch{value: "shanks=3,g14=0"}
-		p := &Puller{Source: src, Language: delivery.AskGo, Node: "g14", Put: st.put, PullWait: 10 * time.Millisecond,
-			Capacity:    func() int { return 0 }, // the settings file, not refilled yet
-			WatchConfig: w.watch,
-			Run:         func(ctx context.Context, a delivery.StepAsk) (any, error) { return nil, nil }}
-		ctx, cancel := context.WithCancel(context.Background())
-		defer cancel()
-		go p.Pull(ctx)
-		waitFor(t, "the watch of the capacity", func() bool { w.mu.Lock(); defer w.mu.Unlock(); return w.handle != nil })
-		time.Sleep(30 * time.Millisecond)
-		if src.Waiting(delivery.AskDelivery) != 1 {
-			t.Fatal("a node at capacity 0 took an ask")
-		}
-		if w.asked != CapacitySetting {
-			t.Fatalf("the puller watches %q, want %q", w.asked, CapacitySetting)
-		}
-		w.set(t, "shanks=3,g14=2")
-		waitFor(t, "the ask taken once the capacity moved to 2", func() bool { a, _, _ := src.Fates(); return len(a) == 1 })
-	})
-	for _, c := range []struct {
-		name  string
-		watch func(string, func(stdio.ProvisionChange) error) error
-		room  bool
-	}{
-		{"refused value leaves no room", func(key string, handle func(stdio.ProvisionChange) error) error {
-			return handle(stdio.ProvisionChange{Kind: "config", Key: key, Refused: "the module is no longer on g14"})
-		}, false},
-		{"watch that cannot start keeps the settings file", func(string, func(stdio.ProvisionChange) error) error {
-			return errors.New("no runtime")
-		}, true},
-	} {
-		t.Run(c.name, func(t *testing.T) {
-			p := &Puller{Source: NewFakeAsks(), Language: delivery.AskGo, Node: "g14", Put: newSteps().put,
-				Capacity: func() int { return 1 }, WatchConfig: c.watch,
-				Run: func(ctx context.Context, a delivery.StepAsk) (any, error) { return nil, nil }}
-			p.watchCapacity()
-			if p.room() != c.room {
-				t.Fatalf("room = %v, want %v", p.room(), c.room)
-			}
-		})
-	}
-}
-
-// 1887/A2b: a paused puller takes nothing, its pause is kept on the pause key, and a puller started again on that state
-// stays paused until resumed.
-func TestPullPauseOutlivesARestart(t *testing.T) {
-	src, st, steps := NewFakeAsks(), &kv{}, &kv{}
-	run := func(ctx context.Context, a delivery.StepAsk) (any, error) { return nil, nil }
-	p := &Puller{Source: src, Language: delivery.AskGo, Node: "shanks", Put: steps.put, PausePut: st.put, Load: st.load,
-		PullWait: 10 * time.Millisecond, Capacity: func() int { return 2 }, Run: run}
-	if err := p.Pause("the operator"); err != nil {
-		t.Fatal(err)
-	}
-	key, _ := delivery.PauseKey("shanks")
-	raw, _ := st.load(key)
-	if v, err := delivery.DecodePause(raw); err != nil || !v.Paused || v.By != "the operator" {
-		t.Fatalf("the pause key holds %s (%v)", raw, err)
-	}
-	if raw, _ := steps.load(key); raw != nil {
-		t.Fatalf("the pause was written in the steps state, whose keys age out: %s", raw)
-	}
-	// The restart: a new puller on the same state.
-	again := &Puller{Source: src, Language: delivery.AskGo, Node: "shanks", Put: steps.put, PausePut: st.put, Load: st.load,
-		PullWait: 10 * time.Millisecond, Capacity: func() int { return 2 }, Run: run}
-	_ = src.PublishAsk(testAsk(delivery.AskDelivery))
-	ctx, cancel := context.WithCancel(context.Background())
-	defer cancel()
-	go again.Pull(ctx)
-	time.Sleep(50 * time.Millisecond)
-	if !again.Paused() || src.Waiting(delivery.AskDelivery) != 1 {
-		t.Fatalf("restarted: paused %v, waiting %d; want paused and 1", again.Paused(), src.Waiting(delivery.AskDelivery))
-	}
-	if err := again.Resume("the operator"); err != nil {
-		t.Fatal(err)
-	}
-	waitFor(t, "the ask taken after the resume", func() bool { a, _, _ := src.Fates(); return len(a) == 1 })
-
-	t.Run("a pause that cannot be read is said and pulled as not paused", func(t *testing.T) {
-		src := NewFakeAsks()
-		var said atomic.Value
-		p := &Puller{Source: src, Language: delivery.AskGo, Node: "shanks", Put: steps.put, PausePut: st.put,
-			Load:     func(string) ([]byte, error) { return nil, errors.New("no runtime yet") },
-			PullWait: 10 * time.Millisecond, Capacity: func() int { return 2 }, Run: run,
-			Logf: func(f string, a ...any) {
-				if m := fmt.Sprintf(f, a...); strings.Contains(m, "cannot be read") {
-					said.Store(m)
-				}
-			}}
-		_ = src.PublishAsk(testAsk(delivery.AskDelivery))
-		ctx, cancel := context.WithCancel(context.Background())
-		defer cancel()
-		go p.Pull(ctx)
-		waitFor(t, "the ask taken", func() bool { a, _, _ := src.Fates(); return len(a) == 1 })
-		if m, _ := said.Load().(string); !strings.Contains(m, "pulling as not paused") {
-			t.Fatalf("the unreadable pause was not said: %q", m)
-		}
-	})
-}
-
-// 1887/A2c: a long step tells the bus it is still being worked; a holder that stops mid-step neither ends nor
-// acknowledges its ask, so the stream gives it to another node.
-func TestPullHeartbeatAndStop(t *testing.T) {
-	src, st := NewFakeAsks(), newSteps()
-	a := testAsk(delivery.AskDelivery)
-	_ = src.PublishAsk(a)
-	running := make(chan struct{})
-	p := &Puller{Source: src, Language: delivery.AskGo, Node: "shanks", Put: st.put, Capacity: func() int { return 1 },
-		PullWait: 10 * time.Millisecond, Heartbeat: 5 * time.Millisecond,
-		Run: func(ctx context.Context, a delivery.StepAsk) (any, error) {
-			close(running)
-			<-ctx.Done()
-			return nil, ctx.Err()
-		}}
-	ctx, cancel := context.WithCancel(context.Background())
-	stopped := make(chan struct{})
-	go func() { p.Pull(ctx); close(stopped) }()
-	<-running
-	waitFor(t, "two heartbeats", func() bool { src.mu.Lock(); defer src.mu.Unlock(); return src.InProgress >= 2 })
-	cancel()
-	<-stopped
-	waitFor(t, "the step's goroutine gone", func() bool { return p.InHand() == 0 })
-	acked, termed, naked := src.Fates()
-	if len(acked)+len(termed)+len(naked) != 0 {
-		t.Fatalf("a stopped holder gave its ask a fate: acked %v termed %v naked %v", acked, termed, naked)
-	}
-	key, _ := delivery.AskStepKey("shanks", a.ID)
-	if s, ok := st.get(key); !ok || s.State != delivery.StepRunning {
-		t.Fatalf("the step %s = %+v, want left running", key, s)
-	}
-}
-
-// 1907: an ask taken past AskRuns (each run took its node down) is run no more: its step ends failed saying why, so the
-// asker's key fails, and it is ended on the stream, not offered to another node.
-func TestAPoisonedAskIsSaidAndRunNoMore(t *testing.T) {
-	src, st := NewFakeAsks(), newSteps()
-	src.Delivered = delivery.AskRuns + 1
-	a := testAsk(delivery.AskDelivery)
-	_ = src.PublishAsk(a)
-	ran := false
-	p := &Puller{Source: src, Language: delivery.AskGo, Node: "shanks", Put: st.put, Capacity: func() int { return 1 },
-		PullWait: 10 * time.Millisecond, Run: func(ctx context.Context, a delivery.StepAsk) (any, error) { ran = true; return nil, nil }}
-	ctx, cancel := context.WithCancel(context.Background())
-	defer cancel()
-	go p.Pull(ctx)
-	waitFor(t, "the ask termed", func() bool { _, tm, _ := src.Fates(); return len(tm) == 1 })
-	key, _ := delivery.AskStepKey("shanks", a.ID)
-	s, ok := st.get(key)
-	if ran || !ok || s.State != delivery.StepFailed || !strings.Contains(s.Reason, "taken 3 times") || !strings.Contains(s.Reason, "poison") {
-		t.Fatalf("ran %v, step %+v", ran, s)
-	}
-	if acked, _, naked := src.Fates(); len(acked)+len(naked) != 0 {
-		t.Errorf("acked %v naked %v, want it termed alone", acked, naked)
-	}
-}

go/buildstep/refusal.go

@@ -1,18 +0,0 @@
-package buildstep
-
-import "fmt"
-
-// Refusal is a step that is not run on purpose, as against one that failed: the toolchain installed is not the
-// recipe's, the integration level's postgres major is not the one it is built for (novox/hq ADR 0469 §1, ADR 0470
-// §4; issue 1473). A step's run returns one and the runner ends the step refused with its text.
-type Refusal struct {
-	// Text is the reason, in words the operator reads.
-	Text string
-	// Want is the version the recipe asks for and Have the one found; either may be empty.
-	Want, Have string
-}
-
-func (r *Refusal) Error() string { return r.Text }
-
-// Refuse is a Refusal with its text formatted.
-func Refuse(format string, args ...any) *Refusal { return &Refusal{Text: fmt.Sprintf(format, args...)} }

go/buildstep/request.go

@@ -1,115 +0,0 @@
-package buildstep
-
-import (
-	"fmt"
-	"path"
-	"regexp"
-	"strings"
-)
-
-var (
-	requestCommitOK     = regexp.MustCompile(`^[0-9a-f]{40}$`)
-	requestRepositoryOK = regexp.MustCompile(`^[A-Za-z0-9][A-Za-z0-9._-]*/[A-Za-z0-9][A-Za-z0-9._-]*$`)
-)
-
-// FetchRequest is what a build module's fetch tool is asked: the repository and the full commit, the pull request's
-// ref when only its head carries the commit, the trunk commit to merge onto for a merge preview, and, for a build of a
-// module whose every artifact names its paths, that module's directory and its named paths (novox/hq ADR 0499 clause 4).
-//
-// **The paths come from the builder, not from a manifest** (ADR 0495 clause 1; the lead's decision L8 of R4e): the
-// builder fills Dir and Paths from the indexer's Module value (Path, and KeptInputs2.Paths' keys), and the build module
-// gives the build and test steps a workspace holding those paths, the manifest and its lock files. A request without
-// them builds from the module's directory, as before.
-type FetchRequest struct {
-	Repository string   `json:"repository"`
-	Commit     string   `json:"commit"`
-	Ref        string   `json:"ref,omitempty"`
-	Base       string   `json:"base,omitempty"`
-	Dir        string   `json:"dir,omitempty"`
-	Paths      []string `json:"paths,omitempty"`
-}
-
-// FetchRequestProperties are the JSON schema properties of FetchRequest's dir and paths, for a fetch tool's Input.
-func FetchRequestProperties() map[string]any {
-	return map[string]any{
-		"dir": map[string]any{"type": "string", "description": "the module's directory in the repository (\".\" for its root), with paths"},
-		"paths": map[string]any{"type": "array", "items": map[string]any{"type": "string"},
-			"description": "the paths the module names, relative to dir, from the indexer's kept inputs: the build sees only these, the manifest and its lock files"},
-	}
-}
-
-// Args is r as a tool call's arguments.
-func (r FetchRequest) Args() map[string]any {
-	args := map[string]any{"repository": r.Repository, "commit": r.Commit}
-	for k, v := range map[string]string{"ref": r.Ref, "base": r.Base, "dir": r.Dir} {
-		if v != "" {
-			args[k] = v
-		}
-	}
-	if len(r.Paths) > 0 {
-		args["paths"] = append([]string(nil), r.Paths...)
-	}
-	return args
-}
-
-// ParseFetchRequest reads a fetch tool's arguments; arguments it does not know (a build module's own) are left to the
-// caller. It refuses a repository that is not <owner>/<name>, a commit or a base that is not 40 hex digits, paths with no
-// module directory or a directory with no path, a directory leaving the repository and a path leaving the directory,
-// naming each.
-func ParseFetchRequest(args map[string]any) (FetchRequest, error) {
-	var r FetchRequest
-	r.Repository, _ = args["repository"].(string)
-	r.Commit, _ = args["commit"].(string)
-	r.Ref, _ = args["ref"].(string)
-	r.Base, _ = args["base"].(string)
-	r.Dir, _ = args["dir"].(string)
-	switch v := args["paths"].(type) {
-	case nil:
-	case []string:
-		r.Paths = append([]string(nil), v...)
-	case []any:
-		for _, p := range v {
-			s, ok := p.(string)
-			if !ok {
-				return FetchRequest{}, fmt.Errorf("paths is a list of strings")
-			}
-			r.Paths = append(r.Paths, s)
-		}
-	default:
-		return FetchRequest{}, fmt.Errorf("paths is a list of strings")
-	}
-	return r, r.Check()
-}
-
-// Check is what ParseFetchRequest refuses.
-func (r FetchRequest) Check() error {
-	if !requestRepositoryOK.MatchString(r.Repository) || strings.Contains(r.Repository, "..") {
-		return fmt.Errorf("%q is not a repository, <owner>/<name>", r.Repository)
-	}
-	if !requestCommitOK.MatchString(r.Commit) {
-		return fmt.Errorf("%q is not a full commit (40 hex digits)", r.Commit)
-	}
-	if r.Base != "" && !requestCommitOK.MatchString(r.Base) {
-		return fmt.Errorf("%q is not a trunk commit (40 hex digits)", r.Base)
-	}
-	switch {
-	case len(r.Paths) > 0 && r.Dir == "":
-		return fmt.Errorf("the request names paths and names no module directory (dir) they are relative to")
-	case len(r.Paths) == 0 && r.Dir != "":
-		return fmt.Errorf("the request names a module directory and no path")
-	}
-	if r.Dir != "" && (outside(r.Dir) || strings.HasPrefix(r.Dir, "/")) {
-		return fmt.Errorf("the module directory %q leaves the repository", r.Dir)
-	}
-	for _, p := range r.Paths {
-		if p == "" || strings.HasPrefix(p, "/") || outside(p) || path.Clean(p) == "." {
-			return fmt.Errorf("the path %q leaves the module's directory or is not a path in it", p)
-		}
-	}
-	return nil
-}
-
-func outside(p string) bool {
-	c := path.Clean(p)
-	return c == ".." || strings.HasPrefix(c, "../")
-}

go/buildstep/request_test.go

@@ -1,57 +0,0 @@
-package buildstep
-
-import (
-	"reflect"
-	"strings"
-	"testing"
-)
-
-// A build's fetch is handed the paths of a module that names them (novox/hq ADR 0499 clause 4): the builder fills them
-// from the indexer's kept inputs and the build module reads them from the call, never from the manifest (ADR 0495
-// clause 1). The request survives the trip through a tool call's arguments.
-func TestAFetchRequestCarriesTheNamedPathsThroughTheToolCall(t *testing.T) {
-	req := FetchRequest{Repository: "novox/mesh-sdk", Commit: strings.Repeat("a", 40), Ref: "refs/pull/7/head",
-		Dir: ".", Paths: []string{"package.json", "src"}}
-	args := req.Args()
-	// A tool call's arguments arrive as JSON: lists of any.
-	args["paths"] = []any{"package.json", "src"}
-	got, err := ParseFetchRequest(args)
-	if err != nil {
-		t.Fatal(err)
-	}
-	if !reflect.DeepEqual(got, req) {
-		t.Fatalf("got %+v, want %+v", got, req)
-	}
-	plain, err := ParseFetchRequest(map[string]any{"repository": "novox/x", "commit": strings.Repeat("b", 40),
-		"base": strings.Repeat("c", 40), "beside": []any{}})
-	if err != nil || plain.Paths != nil || plain.Base != strings.Repeat("c", 40) {
-		t.Fatalf("a request without paths: %+v, %v", plain, err)
-	}
-
-	ok := map[string]any{"repository": "novox/x", "commit": strings.Repeat("b", 40)}
-	for _, c := range []struct {
-		set  map[string]any
-		says string
-	}{
-		{map[string]any{"repository": "novox"}, "is not a repository"},
-		{map[string]any{"repository": "novox/../x"}, "is not a repository"},
-		{map[string]any{"commit": "abc"}, "is not a full commit"},
-		{map[string]any{"base": "abc"}, "is not a trunk commit"},
-		{map[string]any{"paths": []any{"src"}}, "names no module directory"},
-		{map[string]any{"dir": "modules/a", "paths": []any{"../b"}}, "leaves the module's directory"},
-		{map[string]any{"dir": "../a", "paths": []any{"src"}}, "leaves the repository"},
-		{map[string]any{"dir": "modules/a", "paths": []any{3}}, "paths is a list of strings"},
-		{map[string]any{"dir": "modules/a"}, "names a module directory and no path"},
-	} {
-		args := map[string]any{}
-		for k, v := range ok {
-			args[k] = v
-		}
-		for k, v := range c.set {
-			args[k] = v
-		}
-		if _, err := ParseFetchRequest(args); err == nil || !strings.Contains(err.Error(), c.says) {
-			t.Errorf("%v: %v, wanted a refusal saying %q", c.set, err, c.says)
-		}
-	}
-}

go/buildstep/seat_tools.go

@@ -1,39 +0,0 @@
-package buildstep
-
-import (
-	stdio "git.novox.be/novox/mesh-sdk/go"
-)
-
-// SeatTools are a build seat's verbs on one node, as its holder serves them (novox/hq ADR 0525 §10; mesh-sdk catalogue
-// buildSeatVerbs): `<seat>.current` (what the node runs, its capacity, whether it is paused), `<seat>.pause` and
-// `<seat>.resume`, the pause kept on the node's pause key by the puller. what names the asks in the descriptions ("Go").
-func SeatTools(seat, what string, p *Puller) []stdio.Tool {
-	verb := func(name, description string, run func() (any, error)) stdio.Tool {
-		return stdio.Tool{Name: seat + "." + name, Description: description,
-			Input: map[string]any{"type": "object", "properties": map[string]any{}},
-			Run:   func(map[string]any) (any, error) { return run() }}
-	}
-	current := func() (any, error) {
-		c := p.CapacityDetail()
-		return map[string]any{"node": p.Node, "capacity": c.Effective, "capacity_why": c.Why, "capacity_detail": c,
-			"running": p.Running(), "paused": p.Paused()}, nil
-	}
-	return []stdio.Tool{
-		verb("current", "The "+what+" asks this node runs now (each one's id, kind and when it started), its build capacity (the configured one, "+
-			"bounded by the cores its node's build slice gives over the cores a step needs) and why, "+
-			"and whether it is paused.", current),
-		verb("pause", "Take no new "+what+" ask on this node until resumed; an ask running here ends in its place. Kept "+
-			"across a restart (the node's pause key).", func() (any, error) {
-			if err := p.Pause("the seat's pause verb"); err != nil {
-				return nil, err
-			}
-			return current()
-		}),
-		verb("resume", "Take "+what+" asks again on this node.", func() (any, error) {
-			if err := p.Resume("the seat's resume verb"); err != nil {
-				return nil, err
-			}
-			return current()
-		}),
-	}
-}

go/buildstep/seat_tools_test.go

@@ -1,52 +0,0 @@
-package buildstep
-
-import (
-	"context"
-	"testing"
-	"time"
-
-	"git.novox.be/novox/mesh-sdk/go/delivery"
-)
-
-// 1887/A9a, ADR 0525 §10: a build seat's verbs are <seat>.current, .pause and .resume; current names the ask running,
-// pause stops the puller taking asks, resume lets it take them again.
-func TestSeatToolsCurrentPauseResume(t *testing.T) {
-	src, st := NewFakeAsks(), newSteps()
-	release := make(chan struct{})
-	p := &Puller{Source: src, Language: delivery.AskGo, Node: "shanks", Put: st.put, Capacity: func() int { return 1 },
-		PullWait: 10 * time.Millisecond, Run: func(ctx context.Context, a delivery.StepAsk) (any, error) { <-release; return nil, nil }}
-	tools := map[string]func(map[string]any) (any, error){}
-	for _, tool := range SeatTools("node-build-go", "Go", p) {
-		tools[tool.Name] = tool.Run
-	}
-	for _, name := range []string{"node-build-go.current", "node-build-go.pause", "node-build-go.resume"} {
-		if tools[name] == nil {
-			t.Fatalf("no %s", name)
-		}
-	}
-	a := testAsk(delivery.AskDelivery)
-	_ = src.PublishAsk(a)
-	ctx, cancel := context.WithCancel(context.Background())
-	defer cancel()
-	go p.Pull(ctx)
-	waitFor(t, "the ask running", func() bool { return p.InHand() == 1 })
-	out, _ := tools["node-build-go.current"](nil)
-	cur := out.(map[string]any)
-	running := cur["running"].([]RunningAsk)
-	if len(running) != 1 || running[0].ID != a.ID || running[0].Module != "m" || cur["capacity"] != 1 || cur["paused"] != false {
-		t.Fatalf("current = %+v", cur)
-	}
-	if out, err := tools["node-build-go.pause"](nil); err != nil || out.(map[string]any)["paused"] != true {
-		t.Fatalf("pause = %v, %v", out, err)
-	}
-	close(release)
-	_ = src.PublishAsk(testAsk(delivery.AskDelivery))
-	time.Sleep(50 * time.Millisecond)
-	if src.Waiting(delivery.AskDelivery) != 1 {
-		t.Fatal("a paused node took an ask")
-	}
-	if _, err := tools["node-build-go.resume"](nil); err != nil {
-		t.Fatal(err)
-	}
-	waitFor(t, "the ask taken after the resume", func() bool { return src.Waiting(delivery.AskDelivery) == 0 })
-}

go/buildstep/stale.go

@@ -1,272 +0,0 @@
-package buildstep
-
-import (
-	"context"
-	"encoding/json"
-	"errors"
-	"fmt"
-	"strings"
-	"time"
-
-	stdio "git.novox.be/novox/mesh-sdk/go"
-	"git.novox.be/novox/mesh-sdk/go/delivery"
-)
-
-// **A step left running** (novox/hq issue 1890, note 5). A build module that stops while a step runs leaves its key in
-// state running for good: nothing else writes that key's end, and the stream's redelivery only rewrites it when the same
-// ask comes back. At its start a module ends the steps its node left running before the process began (EndStale), and
-// its step-end tool ends one by hand (EndOne).
-
-// RestartReason is why a step a previous process left running is ended.
-const RestartReason = "the build module restarted while it ran"
-
-// Boot is when this process began. A step started at or after it belongs to this process, which may still run it, so
-// EndOne refuses it.
-var Boot = time.Now()
-
-// Scan reads and writes a steps state with its revisions: its keys, a key's stored value and revision (nil and 0 for
-// none), and a write that lands only while the key is still at the revision read (KeptState.Update), failing with
-// stdio.ErrChanged when another writer was first.
-type Scan struct {
-	Keys   func() ([]string, error)
-	Get    func(key string) (json.RawMessage, uint64, error)
-	Update func(key string, value any, revision uint64) (uint64, error)
-}
-
-// ScanOf is the Scan of a state the process keeps.
-func ScanOf(s stdio.KeptState) Scan {
-	return Scan{Keys: s.Keys, Update: s.Update, Get: func(key string) (json.RawMessage, uint64, error) {
-		e, err := s.Get(key)
-		if err != nil || e == nil {
-			return nil, 0, err
-		}
-		return e.Value, e.Revision, nil
-	}}
-}
-
-// isAsk says a step is a pulled ask's: its key is <node>.<ask id> and its tool is "<kind> ask" (a hand-started step
-// has the tool's name). An ask's key is the stream's to settle, never a restart's: the puller leaves an ask it was
-// running unacknowledged so the stream redelivers it, and the asker's wait takes the first end it reads on the key.
-// Only once the asker's bound has passed (delivery.StepBound) is the key nobody's, and then it is ended.
-func isAsk(key string, s delivery.Step) bool {
-	_, _, err := delivery.ParseAskStepKey(key)
-	return err == nil && strings.HasSuffix(s.Tool, " ask")
-}
-
-// AskWhat says what an ask is, in one line: its kind, and its repository, head and levels, or its module and
-// fingerprint.
-func AskWhat(a delivery.StepAsk) string {
-	short := func(s string) string {
-		if len(s) > 12 {
-			return s[:12]
-		}
-		return s
-	}
-	str := func(m map[string]any, k string) string { v, _ := m[k].(string); return v }
-	parts := []string{a.Kind + " ask"}
-	switch {
-	case a.Check != nil:
-		parts = append(parts, str(a.Check.Fetch, "repository")+"@"+short(str(a.Check.Fetch, "commit")), "levels "+strings.Join(a.Check.Levels, ","))
-		if a.Check.Run != "" {
-			parts = append(parts, "run "+a.Check.Run)
-		}
-	case a.Build != nil:
-		parts = append(parts, "module "+a.Build.Module)
-		if r := str(a.Build.Fetch, "repository"); r != "" {
-			parts = append(parts, r+"@"+short(str(a.Build.Fetch, "commit")))
-		}
-		if a.Build.FP != "" {
-			parts = append(parts, "fp "+short(a.Build.FP))
-		}
-	case a.Compose != nil:
-		parts = append(parts, "compose", str(a.Compose.Fetch, "repository")+"@"+short(str(a.Compose.Fetch, "commit")))
-	}
-	return strings.Join(parts, ", ")
-}
-
-// endRunning writes step ended failed with why, only while its key is still at revision.
-func endRunning(scan Scan, key string, step delivery.Step, revision uint64, why string) error {
-	step.State, step.Reason, step.Ended, step.Result = delivery.StepFailed, why, now().UTC(), nil
-	raw, err := delivery.EncodeStep(step)
-	if err != nil {
-		return err
-	}
-	_, err = scan.Update(key, json.RawMessage(raw), revision)
-	return err
-}
-
-// EndStale ends this node's steps that are running and started before `before` (the start of this process) as failed
-// with RestartReason, and answers their ids. Only keys of node are read; a value that is no step is left alone. A step
-// of a pulled ask is left to the stream's redelivery (isAsk) until its start is older than delivery.StepBound: its asker
-// stopped waiting then, whether the stream gave it to another node or gave it up, and it is ended as failed, "past the
-// step bound: its asker stopped waiting at <time>". A key written by another writer since it was read
-// (a redelivered ask's start, a real end) is skipped.
-func EndStale(scan Scan, node string, before time.Time, logf func(string, ...any)) ([]string, error) {
-	keys, err := scan.Keys()
-	if err != nil {
-		return nil, fmt.Errorf("buildstep: listing the steps of %s: %w", node, err)
-	}
-	var ended []string
-	for _, k := range keys {
-		n, _, perr := delivery.ParseStepKey(k)
-		if perr != nil || n != node {
-			continue
-		}
-		raw, rev, err := scan.Get(k)
-		if err != nil {
-			return ended, fmt.Errorf("buildstep: reading the step %s: %w", k, err)
-		}
-		if len(raw) == 0 {
-			continue
-		}
-		step, err := delivery.DecodeStep(raw)
-		if err != nil || step.State != delivery.StepRunning {
-			continue
-		}
-		why := RestartReason
-		if isAsk(k, step) {
-			if !step.Started.Add(delivery.StepBound).Before(now()) {
-				continue
-			}
-			why = "past the step bound: its asker stopped waiting at " + step.Started.Add(delivery.StepBound).UTC().Format("2006-01-02T15:04:05Z")
-		} else if !step.Started.Before(before) {
-			continue
-		}
-		if err := endRunning(scan, k, step, rev, why); err != nil {
-			if errors.Is(err, stdio.ErrChanged) {
-				continue
-			}
-			return ended, fmt.Errorf("buildstep: ending the step %s: %w", k, err)
-		}
-		if logf != nil {
-			logf("the step %s (%s) was left running and is ended: %s", k, step.Tool, why)
-		}
-		ended = append(ended, step.ID)
-	}
-	return ended, nil
-}
-
-// EndOne ends this node's running step id (or the key <node>.<id>) as failed with why. A step that is not running is
-// refused, and so is one started since this process began (Boot: it may still run, whether a pulled ask or a step a
-// tool started), one live reports as held, and one whose key changed since it was read.
-func EndOne(scan Scan, node, id, why string, live func(id string) bool) (delivery.Step, error) {
-	id = strings.TrimSpace(id)
-	if n, rest, ok := strings.Cut(id, "."); ok {
-		if n != node {
-			return delivery.Step{}, fmt.Errorf("the step %q is of node %q, this module runs on %q", id, n, node)
-		}
-		id = rest
-	}
-	if strings.TrimSpace(why) == "" {
-		return delivery.Step{}, fmt.Errorf("say why the step is ended (why)")
-	}
-	key, err := delivery.StepKey(node, id)
-	if err != nil {
-		return delivery.Step{}, err
-	}
-	raw, rev, err := scan.Get(key)
-	if err != nil {
-		return delivery.Step{}, err
-	}
-	if len(raw) == 0 {
-		return delivery.Step{}, fmt.Errorf("no step %s in the steps state", key)
-	}
-	step, err := delivery.DecodeStep(raw)
-	if err != nil {
-		return delivery.Step{}, err
-	}
-	if step.State != delivery.StepRunning {
-		return delivery.Step{}, fmt.Errorf("the step %s is %s, not running", key, step.State)
-	}
-	if !step.Started.Before(Boot) || (live != nil && live(id)) {
-		return delivery.Step{}, fmt.Errorf("the step %s was started by this process and may run now; only a step a previous process left is ended", key)
-	}
-	if err := endRunning(scan, key, step, rev, why); err != nil {
-		if errors.Is(err, stdio.ErrChanged) {
-			return delivery.Step{}, fmt.Errorf("the step %s changed while it was being ended; read it again", key)
-		}
-		return delivery.Step{}, err
-	}
-	step.State, step.Reason = delivery.StepFailed, why
-	return step, nil
-}
-
-// StepEndTool is the module's step-end tool, named name (build_go_step_end): it ends one step left running, with a
-// reason, refusing one this process started. p may be nil.
-func StepEndTool(name string, node string, scan Scan, p *Puller) stdio.Tool {
-	return stdio.Tool{Name: name,
-		Description: "End one step of this machine that is stuck in state running (for instance left by a restart of the module) " +
-			"as failed, with the reason given; its asker then sees it over, so ending an ask still in its stream fails its asker. " +
-			"A step not running, or one this process started, is refused. " +
-			"id is the step id or the key <node>.<id>.",
-		Input: map[string]any{"type": "object", "required": []string{"id", "why"}, "properties": map[string]any{
-			"id":  map[string]any{"type": "string", "description": "the step id, or the key <node>.<id>"},
-			"why": map[string]any{"type": "string", "description": "why it is ended; it becomes the step's reason"}}},
-		Run: func(args map[string]any) (any, error) {
-			id, _ := args["id"].(string)
-			why, _ := args["why"].(string)
-			var live func(string) bool
-			if p != nil {
-				live = func(id string) bool {
-					for _, r := range p.Running() {
-						if r.ID == id {
-							return true
-						}
-					}
-					return false
-				}
-			}
-			return EndOne(scan, node, id, why, live)
-		}}
-}
-
-// StaleAttempts and StaleRetry bound EndStaleAtStart's tries: the steps state is readable once the runtime serves.
-var (
-	StaleAttempts = 6
-	StaleRetry    = 5 * time.Second
-)
-
-// EndStaleAtStart is what a build module runs once at its start, in a goroutine: it waits for the runtime to serve,
-// then ends this node's steps left running before `before` (EndStale), trying again when the state cannot be read yet.
-// A step this process starts is never one of them: it starts after `before`.
-func EndStaleAtStart(ctx context.Context, scan Scan, node string, before time.Time, logf func(string, ...any)) {
-	select {
-	case <-ctx.Done():
-		return
-	case <-stdio.Served():
-	}
-	for attempt := 1; ; attempt++ {
-		ended, err := EndStale(scan, node, before, logf)
-		if err == nil {
-			if logf != nil {
-				logf("%d steps of %s left running by a previous process ended", len(ended), node)
-			}
-			return
-		}
-		if logf != nil {
-			logf("ending the steps left running (try %d of %d): %v", attempt, StaleAttempts, err)
-		}
-		if attempt >= StaleAttempts {
-			return
-		}
-		select {
-		case <-ctx.Done():
-			return
-		case <-time.After(StaleRetry):
-		}
-	}
-}
-
-// EndStaleRound is EndStale as the module's periodic round runs it: at once, and only when the runtime serves (a round
-// before that is skipped, the start's EndStaleAtStart and the next round cover it). It ends the steps a previous
-// process left and the asks past delivery.StepBound.
-func EndStaleRound(scan Scan, node string, logf func(string, ...any)) {
-	select {
-	case <-stdio.Served():
-	default:
-		return
-	}
-	if _, err := EndStale(scan, node, Boot, logf); err != nil && logf != nil {
-		logf("ending the steps left running: %v", err)
-	}
-}

go/buildstep/stale_test.go

@@ -1,131 +0,0 @@
-package buildstep
-
-import (
-	"encoding/json"
-	stdio "git.novox.be/novox/mesh-sdk/go"
-	"strings"
-	"testing"
-	"time"
-
-	"git.novox.be/novox/mesh-sdk/go/delivery"
-)
-
-// scanOf is the steps a keys double holds, last value per key, its revision the count of its puts; a write through
-// Update lands only at the revision read, as the state's does. race, when set, runs once before the next Update's check.
-func scanOf(k *keys, race func(key string)) Scan {
-	return Scan{
-		Keys: func() ([]string, error) {
-			k.mu.Lock()
-			defer k.mu.Unlock()
-			var out []string
-			for key := range k.puts {
-				out = append(out, key)
-			}
-			return out, nil
-		},
-		Get: func(key string) (json.RawMessage, uint64, error) {
-			k.mu.Lock()
-			defer k.mu.Unlock()
-			s, ok := k.puts[key]
-			if !ok {
-				return nil, 0, nil
-			}
-			raw, err := delivery.EncodeStep(s[len(s)-1])
-			return raw, uint64(len(s)), err
-		},
-		Update: func(key string, value any, revision uint64) (uint64, error) {
-			if race != nil {
-				race(key)
-			}
-			k.mu.Lock()
-			n := uint64(len(k.puts[key]))
-			k.mu.Unlock()
-			if n != revision {
-				return 0, stdio.ErrChanged
-			}
-			return k.put(key, value)
-		},
-	}
-}
-
-// 1890: EndStale ends only this node's hand-started steps left running before the process began and the asks past the
-// step bound (a younger ask is the stream's to redeliver), and never a key written meanwhile; EndOne ends one by hand, never one this process started.
-func TestEndStaleAndEndOne(t *testing.T) {
-	k := newKeys()
-	boot := time.Now()
-	oldBoot := Boot
-	Boot = boot
-	defer func() { Boot = oldBoot }()
-	put := func(node, id, tool, state string, started time.Time) {
-		key, _ := delivery.StepKey(node, id)
-		_, _ = k.put(key, json.RawMessage(mustStep(t, delivery.Step{ID: id, Tool: tool, Node: node, State: state, Started: started})))
-	}
-	put("ace", "old1", "build_go_fetch", delivery.StepRunning, boot.Add(-time.Hour))
-	put("ace", "mjk3l9x0abcdef", "check ask", delivery.StepRunning, boot.Add(-time.Hour))
-	put("ace", "mjk3l9x0abcdee", "check ask", delivery.StepRunning, time.Now().Add(-5*time.Minute))
-	put("ace", "raced1", "build_go_test", delivery.StepRunning, boot.Add(-time.Hour))
-	put("ace", "new1", "build_go_fetch", delivery.StepRunning, boot.Add(time.Second))
-	put("ace", "done1", "build_go_fetch", delivery.StepPassed, boot.Add(-time.Hour))
-	put("g14", "other1", "build_go_fetch", delivery.StepRunning, boot.Add(-time.Hour))
-	// raced1 is ended by its own run between the read and the write.
-	raced := false
-	scan := scanOf(k, func(key string) {
-		if key == "ace.raced1" && !raced {
-			raced = true
-			put("ace", "raced1", "build_go_test", delivery.StepPassed, boot.Add(-time.Hour))
-		}
-	})
-	ended, err := EndStale(scan, "ace", boot, nil)
-	if err != nil || len(ended) != 2 || ended[0] == ended[1] {
-		t.Fatalf("ended %v, %v", ended, err)
-	}
-	if s := k.last("ace.old1"); s.State != delivery.StepFailed || s.Reason != RestartReason || s.Ended.IsZero() {
-		t.Errorf("old1 = %+v", s)
-	}
-	if s := k.last("ace.mjk3l9x0abcdef"); s.State != delivery.StepFailed || !strings.HasPrefix(s.Reason, "past the step bound: its asker stopped waiting at ") {
-		t.Errorf("the old ask = %+v", s)
-	}
-	for key, state := range map[string]string{"ace.mjk3l9x0abcdee": delivery.StepRunning, "ace.raced1": delivery.StepPassed, "ace.new1": delivery.StepRunning, "ace.done1": delivery.StepPassed, "g14.other1": delivery.StepRunning} {
-		if s := k.last(key); s.State != state {
-			t.Errorf("%s = %s, want %s", key, s.State, state)
-		}
-	}
-	// EndOne: refuses without why, a held step, one started by this process (a pulled ask or a step tool's), a step not
-	// running and another node's; ends a step a previous process left.
-	for _, c := range []struct{ id, why string }{{"old1", ""}, {"new1", "stuck"}, {"done1", "x"}, {"g14.other1", "x"}} {
-		if _, err := EndOne(scan, "ace", c.id, c.why, nil); err == nil {
-			t.Errorf("ended %s with why %q", c.id, c.why)
-		}
-	}
-	put("ace", "old2", "build_go_fetch", delivery.StepRunning, boot.Add(-time.Hour))
-	if _, err := EndOne(scan, "ace", "old2", "x", func(string) bool { return true }); err == nil {
-		t.Error("ended a held step")
-	}
-	if _, err := EndOne(scan, "ace", "ace.old2", "stuck for good", nil); err != nil {
-		t.Fatal(err)
-	}
-	if s := k.last("ace.old2"); s.State != delivery.StepFailed || s.Reason != "stuck for good" {
-		t.Errorf("old2 = %+v", s)
-	}
-}
-
-func mustStep(t *testing.T, s delivery.Step) []byte {
-	t.Helper()
-	raw, err := delivery.EncodeStep(s)
-	if err != nil {
-		t.Fatal(err)
-	}
-	return raw
-}
-
-// 1890: AskWhat names the repository, head and levels of a check ask and the module of a build ask.
-func TestAskWhat(t *testing.T) {
-	check := delivery.StepAsk{Kind: "check", Check: &delivery.CheckJob{Fetch: map[string]any{"repository": "novox/mesh-sdk", "commit": "0123456789abcdef0123"}, Levels: []string{"unit", "integration"}}}
-	if got, want := AskWhat(check), "check ask, novox/mesh-sdk@0123456789ab, levels unit,integration"; got != want {
-		t.Errorf("check = %q", got)
-	}
-	build := delivery.StepAsk{Kind: "delivery", Build: &delivery.BuildJob{Module: "mesh-x", FP: "abcdef0123456789"}}
-	if got, want := AskWhat(build), "delivery ask, module mesh-x, fp abcdef012345"; got != want {
-		t.Errorf("build = %q", got)
-	}
-}

go/buildstep/step.go

@@ -1,146 +0,0 @@
-// Package buildstep is what both build modules share: the runner of a long step that answers a tool call at once
-// and ends on its key in the module's `steps` state (novox/hq ADR 0469 §2; issue 1471), the toolchain guard
-// (issue 1473) and the fetch of one commit over SSH (issue 1474).
-package buildstep
-
-import (
-	"context"
-	"crypto/rand"
-	"encoding/hex"
-	"encoding/json"
-	"errors"
-	"fmt"
-	"log"
-	"strconv"
-	"time"
-
-	"git.novox.be/novox/mesh-sdk/go/delivery"
-)
-
-// Put writes one key of a state: stdio.State(delivery.StepsState).Put's shape (go/state.go).
-type Put func(key string, value any) (uint64, error)
-
-// EndAttempts and EndRetry bound how a step's end is written: a write that fails is tried again, since the end
-// is the only way the step's reader learns it is over.
-var (
-	EndAttempts = 5
-	EndRetry    = 2 * time.Second
-)
-
-var now = time.Now
-
-// NewID is a step id: the time in milliseconds in base 36 and six random hex digits, lower-case letters and
-// digits only, so it is one key token and differs between two steps of one node even in one millisecond.
-func NewID() string {
-	var b [3]byte
-	_, _ = rand.Read(b[:])
-	return strconv.FormatInt(now().UnixMilli(), 36) + hex.EncodeToString(b[:])
-}
-
-// Start begins a step of tool on node and answers its id at once: the key <node>.<id> holds state running when
-// Start returns. run is then called in a goroutine of its own, under ctx (the process's, not the tool call's: the
-// call is cut at 30 s, the step is not). When it returns, the key is written passed with run's result, failed with
-// the error's text, or refused when the error is a *Refusal; a panic in run ends the step failed, naming it, and
-// the process goes on. If the running write fails, nothing was started and Start answers the error.
-func Start(ctx context.Context, put Put, node, tool string, run func(ctx context.Context) (result any, err error)) (string, error) {
-	step, key, err := begin(put, node, tool, NewID(), "")
-	if err != nil {
-		return "", err
-	}
-	go end(ctx, put, key, step, run)
-	return step.ID, nil
-}
-
-// begin writes the step running under id.
-func begin(put Put, node, tool, id, what string) (delivery.Step, string, error) {
-	step := delivery.Step{ID: id, Tool: tool, Node: node, State: delivery.StepRunning, Started: now().UTC(), What: what}
-	key, err := delivery.StepKey(node, step.ID)
-	if err != nil {
-		return delivery.Step{}, "", err
-	}
-	if err := write(put, key, step); err != nil {
-		return delivery.Step{}, "", fmt.Errorf("buildstep: writing the running step %s: %w", key, err)
-	}
-	return step, key, nil
-}
-
-// end runs run and writes the step's end.
-func end(ctx context.Context, put Put, key string, step delivery.Step, run func(ctx context.Context) (any, error)) {
-	result, err := protect(ctx, run)
-	_ = finish(put, key, step, result, err, log.Printf) // finish says a refused end itself
-}
-
-// finish writes the step's end from run's result or error: passed, failed or refused (a *Refusal). A write that fails is
-// tried EndAttempts times. When the whole end is refused every time (a result the state will not take: issue 1930), the
-// refusal is logged and a small failed end without the result is written instead, naming the write's error, so the
-// step's reader learns it is over and why. finish answers an error only when no end could be written at all, and then
-// the step's ask is not acknowledged as done.
-func finish(put Put, key string, step delivery.Step, result any, err error, logf func(format string, args ...any)) error {
-	step.Ended = now().UTC()
-	switch ref := (*Refusal)(nil); {
-	case err == nil:
-		step.State = delivery.StepPassed
-		if result != nil {
-			raw, merr := json.Marshal(result)
-			if merr != nil {
-				step.State, step.Reason = delivery.StepFailed, "the result is not JSON: "+merr.Error()
-			} else {
-				step.Result = raw
-			}
-		}
-	case errors.As(err, &ref):
-		step.State, step.Reason = delivery.StepRefused, err.Error()
-	default:
-		step.State, step.Reason = delivery.StepFailed, err.Error()
-	}
-	werr := writeEnd(put, key, step)
-	if werr == nil {
-		return nil
-	}
-	if logf != nil {
-		logf("the end of the step %s (%s) could not be written in %d tries: %v", key, step.State, EndAttempts, werr)
-	}
-	ended := step.State
-	why := fmt.Sprintf("the step ended %s, and its end could not be written: %v", ended, werr)
-	if step.Reason != "" {
-		why = fmt.Sprintf("the step ended %s (%s), and its end could not be written: %v", ended, step.Reason, werr)
-	}
-	step.State, step.Reason, step.Result = delivery.StepFailed, why, nil
-	if ferr := writeEnd(put, key, step); ferr != nil {
-		if logf != nil {
-			logf("the failed end of the step %s could not be written either: %v", key, ferr)
-		}
-		return fmt.Errorf("buildstep: no end of the step %s could be written: %w", key, ferr)
-	}
-	return nil
-}
-
-// writeEnd writes the step's end, trying EndAttempts times.
-func writeEnd(put Put, key string, step delivery.Step) error {
-	for attempt := 1; ; attempt++ {
-		werr := write(put, key, step)
-		if werr == nil || attempt >= EndAttempts {
-			return werr
-		}
-		time.Sleep(EndRetry)
-	}
-}
-
-// protect is run with a panic turned into the error that ends the step.
-func protect(ctx context.Context, run func(ctx context.Context) (any, error)) (result any, err error) {
-	defer func() {
-		if p := recover(); p != nil {
-			result, err = nil, fmt.Errorf("the step panicked: %v", p)
-		}
-	}()
-	return run(ctx)
-}
-
-func write(put Put, key string, step delivery.Step) error {
-	raw, err := delivery.EncodeStep(step)
-	if err != nil {
-		return err
-	}
-	_, err = put(key, json.RawMessage(raw))
-	return err
-}

go/buildstep/step_test.go

@@ -1,154 +0,0 @@
-package buildstep
-
-import (
-	"context"
-	"encoding/json"
-	"errors"
-	"sync"
-	"testing"
-	"time"
-
-	"git.novox.be/novox/mesh-sdk/go/delivery"
-)
-
-// keys is a steps state in memory: every value put, in order, per key, and a signal for each end.
-type keys struct {
-	mu    sync.Mutex
-	puts  map[string][]delivery.Step
-	ended chan string
-}
-
-func newKeys() *keys { return &keys{puts: map[string][]delivery.Step{}, ended: make(chan string, 16)} }
-
-func (k *keys) put(key string, value any) (uint64, error) {
-	step, err := delivery.DecodeStep(value.(json.RawMessage))
-	if err != nil {
-		return 0, err
-	}
-	k.mu.Lock()
-	k.puts[key] = append(k.puts[key], step)
-	n := uint64(len(k.puts[key]))
-	k.mu.Unlock()
-	if step.State != delivery.StepRunning {
-		k.ended <- key
-	}
-	return n, nil
-}
-
-func (k *keys) last(key string) delivery.Step {
-	k.mu.Lock()
-	defer k.mu.Unlock()
-	s := k.puts[key]
-	return s[len(s)-1]
-}
-
-func (k *keys) waitEnd(t *testing.T) string {
-	t.Helper()
-	select {
-	case key := <-k.ended:
-		return key
-	case <-time.After(3 * time.Second):
-		t.Fatal("the step never ended on its key")
-		return ""
-	}
-}
-
-// 1471/AC1: a run that blocks: Start answers an id within 100 ms and the key holds running.
-func TestStartAnswersAtOnceWithTheStepRunning(t *testing.T) {
-	k := newKeys()
-	release := make(chan struct{})
-	defer close(release)
-	began := time.Now()
-	id, err := Start(context.Background(), k.put, "ace", "fetch", func(ctx context.Context) (any, error) {
-		<-release
-		return nil, nil
-	})
-	if err != nil {
-		t.Fatal(err)
-	}
-	if d := time.Since(began); d > 100*time.Millisecond {
-		t.Errorf("Start took %v", d)
-	}
-	s := k.last("ace." + id)
-	if s.State != delivery.StepRunning || s.Tool != "fetch" || s.Node != "ace" || s.ID != id || s.Started.IsZero() {
-		t.Errorf("step = %+v", s)
-	}
-}
-
-// 1471/AC2 and 1473/AC4: a result, an error and a Refusal end the step passed, failed and refused.
-func TestStepEndsPassedFailedOrRefusedOnItsKey(t *testing.T) {
-	for _, c := range []struct {
-		name   string
-		run    func(context.Context) (any, error)
-		state  string
-		reason string
-		result string
-	}{
-		{"result", func(context.Context) (any, error) { return map[string]string{"sha": "abc"}, nil }, delivery.StepPassed, "", `{"sha":"abc"}`},
-		{"error", func(context.Context) (any, error) { return nil, errors.New("exit 2") }, delivery.StepFailed, "exit 2", ""},
-		{"refusal", func(context.Context) (any, error) {
-			return nil, &Refusal{Text: "go 1.27.1 installed, the recipe builds with go 1.27.0", Want: "1.27.0", Have: "1.27.1"}
-		}, delivery.StepRefused, "go 1.27.1 installed, the recipe builds with go 1.27.0", ""},
-	} {
-		t.Run(c.name, func(t *testing.T) {
-			k := newKeys()
-			id, err := Start(context.Background(), k.put, "ace", "test", c.run)
-			if err != nil {
-				t.Fatal(err)
-			}
-			if got := k.waitEnd(t); got != "ace."+id {
-				t.Fatalf("ended key %q", got)
-			}
-			s := k.last("ace." + id)
-			if s.State != c.state || s.Reason != c.reason || string(s.Result) != c.result || s.Ended.IsZero() {
-				t.Errorf("step = %+v", s)
-			}
-		})
-	}
-}
-
-// 1471/AC3: a panic in run ends the step failed, naming it, and the test process goes on.
-func TestAPanicEndsTheStepFailed(t *testing.T) {
-	k := newKeys()
-	id, _ := Start(context.Background(), k.put, "ace", "build", func(context.Context) (any, error) { panic("boom") })
-	k.waitEnd(t)
-	s := k.last("ace." + id)
-	if s.State != delivery.StepFailed || s.Reason != "the step panicked: boom" {
-		t.Errorf("step = %+v", s)
-	}
-}
-
-// 1471/AC5: ids made in one and the same millisecond differ, and each is one key token. The clock is fixed
-// while no step runs, so no goroutine reads it meanwhile.
-func TestTwoIDsInOneMillisecondDiffer(t *testing.T) {
-	was := now
-	defer func() { now = was }()
-	at := time.Date(2026, 10, 20, 12, 0, 0, 0, time.UTC)
-	now = func() time.Time { return at }
-	seen := map[string]bool{}
-	for i := 0; i < 50; i++ {
-		id := NewID()
-		if seen[id] {
-			t.Fatalf("id %q handed out twice", id)
-		}
-		seen[id] = true
-		if _, err := delivery.StepKey("ace", id); err != nil {
-			t.Errorf("id %q: %v", id, err)
-		}
-	}
-}
-
-// A first write that fails starts nothing.
-func TestStartAnswersTheErrorWhenTheRunningWriteFails(t *testing.T) {
-	ran := make(chan struct{}, 1)
-	_, err := Start(context.Background(), func(string, any) (uint64, error) { return 0, errors.New("no grant") }, "ace", "fetch",
-		func(context.Context) (any, error) { ran <- struct{}{}; return nil, nil })
-	if err == nil {
-		t.Fatal("Start answered no error")
-	}
-	select {
-	case <-ran:
-		t.Error("run was called")
-	case <-time.After(50 * time.Millisecond):
-	}
-}

go/buildstep/testdata/isolated-probe/main.go

@@ -1,49 +0,0 @@
-// The probe a run step's isolation is proved with (novox/hq ADR 0448; issue 1309, S19): run inside the step, it says
-// on stdout every way it reached what a step must not, and "shut off" when it reached none. Its arguments: the files
-// it must not read (the forge key, a bus login), a TCP address and a unix socket of the machine it must not reach, a
-// name it must not resolve, and a cache file it writes, which must be unchanged after the step.
-package main
-
-import (
-	"fmt"
-	"net"
-	"os"
-	"time"
-)
-
-func main() {
-	if len(os.Args) != 7 {
-		fmt.Println("usage: probe <key> <login> <tcp address> <unix socket> <name> <cache file>")
-		os.Exit(2)
-	}
-	key, login, tcp, socket, name, cache := os.Args[1], os.Args[2], os.Args[3], os.Args[4], os.Args[5], os.Args[6]
-	reached := 0
-	say := func(f string, a ...any) { reached++; fmt.Printf(f+"\n", a...) }
-	for _, f := range []string{key, login} {
-		if _, err := os.ReadFile(f); err == nil {
-			say("read %s", f)
-		}
-	}
-	if c, err := net.DialTimeout("tcp", tcp, 2*time.Second); err == nil {
-		c.Close()
-		say("reached %s", tcp)
-	}
-	if c, err := net.DialTimeout("unix", socket, 2*time.Second); err == nil {
-		c.Close()
-		say("reached %s", socket)
-	}
-	if addrs, err := net.LookupHost(name); err == nil {
-		say("resolved %s to %v", name, addrs)
-	}
-	if home, err := os.UserHomeDir(); err == nil {
-		if entries, err := os.ReadDir(home); err == nil && len(entries) > 0 {
-			say("the home %s holds %d entries", home, len(entries))
-		}
-	}
-	if err := os.WriteFile(cache, []byte("written by the step\n"), 0o644); err != nil {
-		say("could not write the cache under its throwaway layer: %v", err)
-	}
-	if reached == 0 {
-		fmt.Println("shut off")
-	}
-}

go/buildstep/trees.go

@@ -1,123 +0,0 @@
-package buildstep
-
-import (
-	"context"
-	"crypto/sha256"
-	"encoding/hex"
-	"fmt"
-	"os"
-	"path"
-	"path/filepath"
-	"strings"
-
-	"git.novox.be/novox/mesh-sdk/go/catalogue"
-	"git.novox.be/novox/mesh-sdk/go/delivery"
-	"git.novox.be/novox/mesh-sdk/go/forgekey"
-)
-
-// ModuleTree is what a merge holds of one module directory: its tree id, the sha256 of its module.json and the sha256
-// of each lock file it has (go.sum, package-lock.json), from which the checker and the indexer take the module's inputs
-// (novox/hq ADR 0484 clause 3).
-type ModuleTree struct {
-	Tree     string            `json:"tree"`
-	Manifest string            `json:"manifest"`
-	Locks    map[string]string `json:"locks,omitempty"`
-	// Paths are, of a module whose every artifact names its paths, each named path's git object id at the commit; Tree
-	// is then their delivery.NamedTree with Manifest (novox/hq ADR 0499 clause 2). Absent otherwise.
-	Paths map[string]string `json:"paths,omitempty"`
-}
-
-var lockFiles = []string{"go.sum", "package-lock.json"}
-
-// ModuleTrees are the trees, in commit, of every directory of the workspace dir that holds a module.json, by directory
-// (the repository's root is "."); for a module whose every artifact names its paths, the named tree of those paths and
-// their objects (novox/hq ADR 0499 clause 2). The workspace is at commit, so the manifests and the lock files are read from it. env is
-// the environment git runs with (nil for none). Both build modules' fetch steps answer it for a merge.
-func ModuleTrees(ctx context.Context, run forgekey.Runner, env []string, dir, commit string) (map[string]ModuleTree, error) {
-	r := run(ctx, env, "git", "-C", dir, "ls-files", "--", "module.json", "*/module.json")
-	if r.Status != 0 || r.Err != "" {
-		return nil, fmt.Errorf("git ls-files: %s", forgekey.Said(r.Err+"\n"+r.Stderr))
-	}
-	trees := map[string]ModuleTree{}
-	for _, l := range strings.Split(r.Stdout, "\n") {
-		if l = strings.TrimSpace(l); l == "" {
-			continue
-		}
-		mdir := filepath.ToSlash(filepath.Dir(l))
-		spec := commit + ":" + mdir
-		if mdir == "." {
-			spec = commit + "^{tree}"
-		}
-		t := run(ctx, env, "git", "-C", dir, "rev-parse", spec)
-		if t.Status != 0 || t.Err != "" {
-			return nil, fmt.Errorf("git rev-parse %s: %s", spec, forgekey.Said(t.Err+"\n"+t.Stderr))
-		}
-		mt := ModuleTree{Tree: strings.TrimSpace(t.Stdout)}
-		raw, err := os.ReadFile(filepath.Join(dir, filepath.FromSlash(l)))
-		if err != nil {
-			return nil, err
-		}
-		mt.Manifest = sha256Hex(raw)
-		if err := narrow(ctx, run, env, dir, commit, mdir, raw, &mt); err != nil {
-			return nil, err
-		}
-		for _, lock := range lockFiles {
-			if raw, err := os.ReadFile(filepath.Join(dir, filepath.FromSlash(mdir), lock)); err == nil {
-				if mt.Locks == nil {
-					mt.Locks = map[string]string{}
-				}
-				mt.Locks[lock] = sha256Hex(raw)
-			}
-		}
-		trees[mdir] = mt
-	}
-	return trees, nil
-}
-
-// narrow sets mt's Paths and its named Tree when the module's manifest names paths on every artifact (novox/hq ADR 0499
-// clause 2): one `git ls-tree -z` gives each named path's object at commit. The merge preview reads the manifest here, as
-// the indexer does, with catalogue.ParseManifestForInputs (issue 1751), and no other build step reads paths from one (ADR 0495 clause 1). A manifest that does not parse
-// is not narrowed: the indexer gives it none. A named path absent at commit fails, naming the module and the path.
-func narrow(ctx context.Context, run forgekey.Runner, env []string, dir, commit, mdir string, raw []byte, mt *ModuleTree) error {
-	m, err := catalogue.ParseManifestForInputs(raw)
-	if err != nil {
-		return nil
-	}
-	paths, every := m.NamedPaths()
-	if !every {
-		return nil
-	}
-	full := make([]string, len(paths))
-	for i, p := range paths {
-		full[i] = path.Join(mdir, p)
-	}
-	r := run(ctx, env, "git", append([]string{"-C", dir, "ls-tree", "-z", commit, "--"}, full...)...)
-	if r.Status != 0 || r.Err != "" {
-		return fmt.Errorf("git ls-tree %s of the module %s: %s", commit, mdir, forgekey.Said(r.Err+"\n"+r.Stderr))
-	}
-	objects := map[string]string{}
-	for _, l := range strings.Split(r.Stdout, "\x00") {
-		meta, name, ok := strings.Cut(l, "\t")
-		fields := strings.Fields(meta)
-		if !ok || len(fields) != 3 {
-			continue
-		}
-		objects[name] = fields[2]
-	}
-	mt.Paths = map[string]string{}
-	for i, p := range paths {
-		object := objects[full[i]]
-		if object == "" {
-			return fmt.Errorf("the module %s names the path %q, which is not in %s", mdir, p, commit)
-		}
-		mt.Paths[p] = object
-	}
-	named, err := delivery.NamedTree(mt.Manifest, mt.Paths)
-	if err != nil {
-		return fmt.Errorf("the module %s: %w", mdir, err)
-	}
-	mt.Tree = named
-	return nil
-}
-
-func sha256Hex(b []byte) string { h := sha256.Sum256(b); return hex.EncodeToString(h[:]) }

go/buildstep/trees_integration_test.go

@@ -1,63 +0,0 @@
-//go:build integration
-
-package buildstep
-
-import (
-	"context"
-	"strings"
-	"testing"
-
-	"git.novox.be/novox/mesh-sdk/go/forgekey"
-)
-
-// On a real repository shaped like mesh-sdk (novox/hq ADR 0499 clauses 2 and 6), a commit touching only the Go package
-// leaves the TypeScript package's tree value equal, and a commit touching its source changes it; a module that names no
-// path keeps its directory's tree id.
-func TestAGoOnlyCommitLeavesTheNamedTreeEqualOnRealGit(t *testing.T) {
-	repo := t.TempDir()
-	realGit(t, repo, "init", "-q", "-b", "main")
-	writeFile(t, repo, "module.json", `{"module":"mesh-sdk","version":"1","build":{"artifacts":[`+
-		`{"name":"lib","kind":"package","language":"typescript","paths":["src","test","package.json","package-lock.json","tsconfig.json"]}]}}`)
-	writeFile(t, repo, "src/index.ts", "export const a = 1\n")
-	writeFile(t, repo, "test/a.test.ts", "// a\n")
-	writeFile(t, repo, "package.json", "{}\n")
-	writeFile(t, repo, "package-lock.json", "{}\n")
-	writeFile(t, repo, "tsconfig.json", "{}\n")
-	writeFile(t, repo, "go/delivery/x.go", "package delivery\n")
-	writeFile(t, repo, "other/module.json", `{"module":"other","version":"1"}`)
-	writeFile(t, repo, "other/a.txt", "a\n")
-	commit := func(msg string) string {
-		realGit(t, repo, "add", "-A")
-		realGit(t, repo, "commit", "-q", "-m", msg)
-		return realGit(t, repo, "rev-parse", "HEAD")
-	}
-	trees := func(c string) map[string]ModuleTree {
-		got, err := ModuleTrees(context.Background(), forgekey.ExecRunner, nil, repo, c)
-		if err != nil {
-			t.Fatal(err)
-		}
-		return got
-	}
-	first := trees(commit("first"))
-	if !strings.HasPrefix(first["."].Tree, "named:") || len(first["."].Paths) != 5 {
-		t.Fatalf("the root module was not narrowed: %+v", first["."])
-	}
-	if want := realGit(t, repo, "rev-parse", "HEAD:other"); first["other"].Tree != want || first["other"].Paths != nil {
-		t.Fatalf("a module naming no path: %+v, want its directory's tree %s", first["other"], want)
-	}
-
-	writeFile(t, repo, "go/delivery/x.go", "package delivery\n\nconst B = 2\n")
-	goOnly := trees(commit("go only"))
-	if goOnly["."].Tree != first["."].Tree {
-		t.Fatalf("a Go-only commit changed the TypeScript package's tree: %s, was %s", goOnly["."].Tree, first["."].Tree)
-	}
-
-	writeFile(t, repo, "src/index.ts", "export const a = 2\n")
-	src := trees(commit("src"))
-	if src["."].Tree == first["."].Tree {
-		t.Fatal("a commit to src/ left the TypeScript package's tree equal")
-	}
-	if src["."].Paths["src"] != realGit(t, repo, "rev-parse", "HEAD:src") {
-		t.Fatalf("the object of src is %s, git says %s", src["."].Paths["src"], realGit(t, repo, "rev-parse", "HEAD:src"))
-	}
-}

go/buildstep/trees_named_test.go

@@ -1,113 +0,0 @@
-package buildstep
-
-import (
-	"context"
-	"strings"
-	"testing"
-
-	"git.novox.be/novox/mesh-sdk/go/catalogue"
-	"git.novox.be/novox/mesh-sdk/go/delivery"
-	"git.novox.be/novox/mesh-sdk/go/forgekey"
-)
-
-// A module whose every artifact names its paths takes its tree from them (novox/hq ADR 0499 clause 2): ModuleTrees asks
-// git for each named path's object at the commit, keeps them in Paths and answers their delivery.NamedTree as Tree; a
-// module naming none keeps its directory's tree, as before.
-func TestModuleTreesNarrowsAModuleWhoseArtifactsNameTheirPaths(t *testing.T) {
-	root := t.TempDir()
-	sdk := `{"module":"mesh-sdk","version":"1","build":{"artifacts":[{"name":"lib","kind":"package","language":"typescript","paths":["src","package.json"]}]}}`
-	writeTreeFile(t, root, "module.json", sdk)
-	writeTreeFile(t, root, "modules/b/module.json", `{"module":"b","version":"1"}`)
-	merge := strings.Repeat("c", 40)
-	var lsTree []string
-	run := func(ctx context.Context, env []string, name string, args ...string) forgekey.Ran {
-		switch args[2] {
-		case "ls-files":
-			return forgekey.Ran{Stdout: "module.json\nmodules/b/module.json\n"}
-		case "rev-parse":
-			return forgekey.Ran{Stdout: "tree-of-" + args[3] + "\n"}
-		case "ls-tree":
-			lsTree = append(lsTree, strings.Join(args[4:], " "))
-			return forgekey.Ran{Stdout: "100644 blob " + strings.Repeat("b", 40) + "\tpackage.json\x00" +
-				"040000 tree " + strings.Repeat("a", 40) + "\tsrc\x00"}
-		}
-		return forgekey.Ran{Status: 1, Stderr: "unexpected " + args[2]}
-	}
-	got, err := ModuleTrees(context.Background(), run, nil, root, merge)
-	if err != nil {
-		t.Fatal(err)
-	}
-	paths := map[string]string{"src": strings.Repeat("a", 40), "package.json": strings.Repeat("b", 40)}
-	want, _ := delivery.NamedTree(hexOf(sdk), paths)
-	if g := got["."]; g.Tree != want || len(g.Paths) != 2 || g.Paths["src"] != paths["src"] || g.Paths["package.json"] != paths["package.json"] {
-		t.Fatalf("the root module = %+v, want tree %s and paths %v", g, want, paths)
-	}
-	if len(lsTree) != 1 || lsTree[0] != merge+" -- package.json src" {
-		t.Fatalf("git ls-tree ran as %v", lsTree)
-	}
-	if g := got["modules/b"]; g.Tree != "tree-of-"+merge+":modules/b" || g.Paths != nil {
-		t.Fatalf("a module naming no path was narrowed: %+v", g)
-	}
-}
-
-// A named path absent at the commit fails the answer, naming the module and the path: a tree computed without it would
-// pin a build source that does not exist.
-func TestModuleTreesFailsNamingANamedPathAbsentAtTheCommit(t *testing.T) {
-	root := t.TempDir()
-	writeTreeFile(t, root, "modules/a/module.json", `{"module":"a","version":"1","build":{"artifacts":[{"name":"lib","kind":"package","language":"typescript","paths":["src","gone"]}]}}`)
-	run := func(ctx context.Context, env []string, name string, args ...string) forgekey.Ran {
-		switch args[2] {
-		case "ls-files":
-			return forgekey.Ran{Stdout: "modules/a/module.json\n"}
-		case "rev-parse":
-			return forgekey.Ran{Stdout: "t\n"}
-		case "ls-tree":
-			if strings.Join(args[4:], " ") != strings.Repeat("c", 40)+" -- modules/a/gone modules/a/src" {
-				return forgekey.Ran{Status: 1, Stderr: "wrong arguments " + strings.Join(args[3:], " ")}
-			}
-			return forgekey.Ran{Stdout: "040000 tree " + strings.Repeat("a", 40) + "\tmodules/a/src\x00"}
-		}
-		return forgekey.Ran{Status: 1}
-	}
-	_, err := ModuleTrees(context.Background(), run, nil, root, strings.Repeat("c", 40))
-	if err == nil || !strings.Contains(err.Error(), `"gone"`) || !strings.Contains(err.Error(), "modules/a") {
-		t.Fatalf("an absent named path gave %v", err)
-	}
-}
-
-// A manifest whose config value falls back to a predefined key is narrowed here as the indexer narrows it: both read it
-// with catalogue.ParseManifestForInputs (issue 1751), so a build module holding no published list computes the same
-// tree (ADR 0499 clause 2).
-func TestModuleTreesNarrowsAManifestFallingBackToAPredefinedKey(t *testing.T) {
-	was := catalogue.ReplacePublished(nil) // the build modules' case: no published list
-	defer catalogue.ReplacePublished(was)
-	root := t.TempDir()
-	raw := `{"module":"xterm","version":"1","config":{"size":{"type":"number","description":"The text size.","predefined":"font-size","default":12,"runtime":true}},` +
-		`"build":{"artifacts":[{"name":"lib","kind":"package","language":"typescript","paths":["src"]}]}}`
-	if _, err := catalogue.ParseManifest([]byte(raw)); err == nil {
-		t.Fatal("ParseManifest reads the manifest with no list; the test proves nothing")
-	}
-	if _, err := catalogue.ParseManifestForInputs([]byte(raw)); err != nil {
-		t.Fatalf("the indexer's read refuses the manifest: %v", err)
-	}
-	writeTreeFile(t, root, "module.json", raw)
-	run := func(ctx context.Context, env []string, name string, args ...string) forgekey.Ran {
-		switch args[2] {
-		case "ls-files":
-			return forgekey.Ran{Stdout: "module.json\n"}
-		case "rev-parse":
-			return forgekey.Ran{Stdout: "whole\n"}
-		case "ls-tree":
-			return forgekey.Ran{Stdout: "040000 tree " + strings.Repeat("a", 40) + "\tsrc\x00"}
-		}
-		return forgekey.Ran{Status: 1}
-	}
-	got, err := ModuleTrees(context.Background(), run, nil, root, strings.Repeat("c", 40))
-	if err != nil {
-		t.Fatal(err)
-	}
-	want, _ := delivery.NamedTree(hexOf(raw), map[string]string{"src": strings.Repeat("a", 40)})
-	if g := got["."]; g.Tree != want || g.Paths["src"] == "" {
-		t.Fatalf("the module = %+v, want the named tree %s", g, want)
-	}
-}

go/buildstep/trees_test.go

@@ -1,93 +0,0 @@
-package buildstep
-
-import (
-	"context"
-	"crypto/sha256"
-	"encoding/hex"
-	"os"
-	"path/filepath"
-	"reflect"
-	"strings"
-	"testing"
-
-	"git.novox.be/novox/mesh-sdk/go/forgekey"
-)
-
-func hexOf(s string) string { h := sha256.Sum256([]byte(s)); return hex.EncodeToString(h[:]) }
-
-func writeTreeFile(t *testing.T, root, name, content string) {
-	t.Helper()
-	p := filepath.Join(root, filepath.FromSlash(name))
-	if err := os.MkdirAll(filepath.Dir(p), 0o755); err != nil {
-		t.Fatal(err)
-	}
-	if err := os.WriteFile(p, []byte(content), 0o644); err != nil {
-		t.Fatal(err)
-	}
-}
-
-// ModuleTrees answers, for each directory holding a module.json (the root as "."), the tree id git gives, the sha256 of
-// module.json and of each lock file present, and reads them from the workspace.
-func TestModuleTreesAnswersTreeManifestAndLocksPerModuleDirectory(t *testing.T) {
-	root := t.TempDir()
-	writeTreeFile(t, root, "module.json", `{"root":1}`)
-	writeTreeFile(t, root, "go.sum", "rootsum")
-	writeTreeFile(t, root, "modules/a/module.json", `{"a":1}`)
-	writeTreeFile(t, root, "modules/a/go.sum", "asum")
-	writeTreeFile(t, root, "modules/a/package-lock.json", "alock")
-	writeTreeFile(t, root, "modules/b/module.json", `{"b":1}`)
-	merge := strings.Repeat("c", 40)
-	var calls []string
-	var envs [][]string
-	run := func(ctx context.Context, env []string, name string, args ...string) forgekey.Ran {
-		calls = append(calls, name+" "+strings.Join(args[2:], " "))
-		envs = append(envs, env)
-		switch args[2] {
-		case "ls-files":
-			return forgekey.Ran{Stdout: "module.json\nmodules/a/module.json\nmodules/b/module.json\n"}
-		case "rev-parse":
-			return forgekey.Ran{Stdout: "tree-of-" + args[3] + "\n"}
-		}
-		return forgekey.Ran{Status: 1, Stderr: "unexpected"}
-	}
-	got, err := ModuleTrees(context.Background(), run, []string{"X=1"}, root, merge)
-	if err != nil {
-		t.Fatal(err)
-	}
-	want := map[string]ModuleTree{
-		".":         {Tree: "tree-of-" + merge + "^{tree}", Manifest: hexOf(`{"root":1}`), Locks: map[string]string{"go.sum": hexOf("rootsum")}},
-		"modules/a": {Tree: "tree-of-" + merge + ":modules/a", Manifest: hexOf(`{"a":1}`), Locks: map[string]string{"go.sum": hexOf("asum"), "package-lock.json": hexOf("alock")}},
-		"modules/b": {Tree: "tree-of-" + merge + ":modules/b", Manifest: hexOf(`{"b":1}`)},
-	}
-	if !reflect.DeepEqual(got, want) {
-		t.Errorf("trees = %+v\nwant %+v", got, want)
-	}
-	if got["modules/b"].Locks != nil {
-		t.Error("a module with no lock file carries a lock map")
-	}
-	for _, e := range envs {
-		if len(e) != 1 || e[0] != "X=1" {
-			t.Errorf("git ran with env %v, want the one given", e)
-		}
-	}
-}
-
-func TestModuleTreesFailsNamingTheGitCommandOrTheUnreadableManifest(t *testing.T) {
-	root := t.TempDir()
-	fail := func(on string) forgekey.Runner {
-		return func(ctx context.Context, env []string, name string, args ...string) forgekey.Ran {
-			if args[2] == on {
-				return forgekey.Ran{Status: 128, Stderr: "fatal: no\n"}
-			}
-			return forgekey.Ran{Stdout: "modules/a/module.json\n"}
-		}
-	}
-	for _, on := range []string{"ls-files", "rev-parse"} {
-		if _, err := ModuleTrees(context.Background(), fail(on), nil, root, sha); err == nil || !strings.Contains(err.Error(), on) || !strings.Contains(err.Error(), "fatal: no") {
-			t.Errorf("%s failing: %v", on, err)
-		}
-	}
-	if _, err := ModuleTrees(context.Background(), fail("none"), nil, root, sha); err == nil {
-		t.Error("a module.json that is not in the workspace was read")
-	}
-}

go/buildstep/workspaces.go

@@ -1,160 +0,0 @@
-package buildstep
-
-// A build module's room to work and its workspaces (novox/hq issue 1839, ADR 0509): a step is refused while the
-// filesystem it writes to has less free than the floor, and a workspace is removed when its caller releases it, or,
-// unheld, once its last use is past a bound (a lost caller's), never while a running step holds it.
-
-import (
-	"fmt"
-	"os"
-	"path/filepath"
-	"regexp"
-	"sort"
-	"sync"
-	"syscall"
-	"time"
-)
-
-// FreeSpaceFloor is the free space a build module needs on its work and cache filesystems to take a step: the floor
-// build-agent keeps (mesh-controller internal/builder/floor.go, issue 1834).
-const FreeSpaceFloor uint64 = 20 << 30
-
-// UnheldBound is how long a workspace no step holds is kept after its last use, when its caller never released it
-// (ADR 0509: a lost caller's workspace goes after two hours).
-const UnheldBound = 2 * time.Hour
-
-// FreeBytes reads the bytes an unprivileged writer can still use on the filesystem holding path.
-func FreeBytes(path string) (uint64, error) {
-	var s syscall.Statfs_t
-	if err := syscall.Statfs(path, &s); err != nil {
-		return 0, err
-	}
-	return s.Bavail * uint64(s.Bsize), nil
-}
-
-// Floor refuses a step while a filesystem it writes to has less free than Bytes. A zero Bytes checks nothing.
-type Floor struct {
-	// Node is named in the refusal.
-	Node  string
-	Bytes uint64
-	// Free reads a path's free bytes; FreeBytes when nil. A test answers for a disk it does not have.
-	Free func(path string) (uint64, error)
-}
-
-// Check answers a *Refusal, "refused: <node> has N GiB free under the floor of F GiB (on <path>)", when any path's
-// filesystem has less free than the floor, or its free space cannot be read; nil otherwise. A path not made yet is
-// read at its nearest folder that is; an empty path is skipped.
-func (f Floor) Check(paths ...string) error {
-	if f.Bytes == 0 {
-		return nil
-	}
-	free := f.Free
-	if free == nil {
-		free = FreeBytes
-	}
-	for _, p := range paths {
-		if p == "" {
-			continue
-		}
-		at := p
-		for {
-			if _, err := os.Stat(at); err == nil || filepath.Dir(at) == at {
-				break
-			}
-			at = filepath.Dir(at)
-		}
-		n, err := free(at)
-		if err != nil {
-			return &Refusal{Text: fmt.Sprintf("refused: the free space of %s on %s cannot be read: %v", p, f.Node, err)}
-		}
-		if n < f.Bytes {
-			return &Refusal{Text: fmt.Sprintf("refused: %s has %d GiB free under the floor of %d GiB (on %s)", f.Node, n>>30, f.Bytes>>30, p),
-				Want: fmt.Sprintf("%d GiB", f.Bytes>>30), Have: fmt.Sprintf("%d GiB", n>>30)}
-		}
-	}
-	return nil
-}
-
-var workspaceID = regexp.MustCompile(`^[a-z0-9]+$`)
-
-// Workspaces are a build module's workspaces, each <Dir>/<id>, and which of them running steps hold.
-type Workspaces struct {
-	Dir string
-
-	mu   sync.Mutex
-	held map[string]int
-}
-
-// Hold marks the workspace held by a running step until the answered func is called; both mark it used now, so the
-// sweep counts its bound from the step's end. An id that is not a workspace's holds nothing.
-func (w *Workspaces) Hold(id string) func() {
-	if !workspaceID.MatchString(id) {
-		return func() {}
-	}
-	w.mu.Lock()
-	if w.held == nil {
-		w.held = map[string]int{}
-	}
-	w.held[id]++
-	w.mu.Unlock()
-	w.touch(id)
-	var once sync.Once
-	return func() {
-		once.Do(func() {
-			w.touch(id)
-			w.mu.Lock()
-			if w.held[id]--; w.held[id] <= 0 {
-				delete(w.held, id)
-			}
-			w.mu.Unlock()
-		})
-	}
-}
-
-func (w *Workspaces) touch(id string) {
-	now := time.Now()
-	_ = os.Chtimes(filepath.Join(w.Dir, id), now, now) // a workspace not made yet has nothing to mark
-}
-
-// Release removes the workspace at once: its caller's chain of steps has ended. One already gone is no error; one a
-// running step holds is refused and kept; an id that is not a workspace's is refused.
-func (w *Workspaces) Release(id string) error {
-	if !workspaceID.MatchString(id) {
-		return fmt.Errorf("%q is not a workspace id", id)
-	}
-	w.mu.Lock()
-	defer w.mu.Unlock()
-	if w.held[id] > 0 {
-		return fmt.Errorf("the workspace %s is held by a running step", id)
-	}
-	if err := os.RemoveAll(filepath.Join(w.Dir, id)); err != nil {
-		return fmt.Errorf("the workspace %s could not be removed: %w", id, err)
-	}
-	return nil
-}
-
-// Sweep removes every workspace no step holds whose last use is older than bound, and answers the ids it removed,
-// sorted. It is the safety net for a caller that never released its workspace.
-func (w *Workspaces) Sweep(now time.Time, bound time.Duration) []string {
-	entries, err := os.ReadDir(w.Dir)
-	if err != nil {
-		return nil
-	}
-	removed := []string{}
-	w.mu.Lock()
-	defer w.mu.Unlock()
-	for _, e := range entries {
-		if !e.IsDir() || !workspaceID.MatchString(e.Name()) || w.held[e.Name()] > 0 {
-			continue
-		}
-		info, err := e.Info()
-		if err != nil || now.Sub(info.ModTime()) < bound {
-			continue
-		}
-		if os.RemoveAll(filepath.Join(w.Dir, e.Name())) == nil {
-			removed = append(removed, e.Name())
-		}
-	}
-	sort.Strings(removed)
-	return removed
-}

go/buildstep/workspaces_test.go

@@ -1,113 +0,0 @@
-package buildstep
-
-import (
-	"errors"
-	"os"
-	"path/filepath"
-	"testing"
-	"time"
-)
-
-// 1839/AC1: a filesystem under the floor refuses the step, naming the node, what is free and the floor.
-func TestAFilesystemUnderTheFloorRefusesNamingNodeFreeAndFloor(t *testing.T) {
-	dir := t.TempDir()
-	f := Floor{Node: "ace", Bytes: 20 << 30, Free: func(string) (uint64, error) { return 4<<30 + 5, nil }}
-	err := f.Check(dir)
-	var ref *Refusal
-	if !errors.As(err, &ref) {
-		t.Fatalf("Check = %v, want a *Refusal", err)
-	}
-	if want := "refused: ace has 4 GiB free under the floor of 20 GiB (on " + dir + ")"; err.Error() != want {
-		t.Errorf("Check = %q, want %q", err, want)
-	}
-}
-
-// 1839/AC1: at or above the floor, and with no floor set, nothing is refused.
-func TestAtTheFloorOrWithNoFloorNothingIsRefused(t *testing.T) {
-	dir := t.TempDir()
-	if err := (Floor{Node: "ace", Bytes: 20 << 30, Free: func(string) (uint64, error) { return 20 << 30, nil }}).Check(dir); err != nil {
-		t.Errorf("at the floor: %v", err)
-	}
-	if err := (Floor{Node: "ace", Free: func(string) (uint64, error) { return 0, nil }}).Check(dir); err != nil {
-		t.Errorf("no floor: %v", err)
-	}
-}
-
-// 1839/AC1: a path not made yet is read at its nearest folder that is; a free space that cannot be read is a refusal.
-func TestAPathNotMadeIsReadAtItsParentAndAnUnreadableOneRefuses(t *testing.T) {
-	dir := t.TempDir()
-	var read string
-	f := Floor{Node: "ace", Bytes: 1, Free: func(p string) (uint64, error) { read = p; return 2, nil }}
-	if err := f.Check(filepath.Join(dir, "not", "made")); err != nil || read != dir {
-		t.Errorf("Check = %v, read %q, want nil and %q", err, read, dir)
-	}
-	f.Free = func(string) (uint64, error) { return 0, errors.New("statfs: boom") }
-	var ref *Refusal
-	if err := f.Check(dir); !errors.As(err, &ref) {
-		t.Errorf("Check = %v, want a refusal", err)
-	}
-}
-
-func makeWorkspace(t *testing.T, w *Workspaces, id string, age time.Duration) string {
-	t.Helper()
-	p := filepath.Join(w.Dir, id)
-	if err := os.MkdirAll(filepath.Join(p, "tree"), 0o700); err != nil {
-		t.Fatal(err)
-	}
-	at := time.Now().Add(-age)
-	if err := os.Chtimes(p, at, at); err != nil {
-		t.Fatal(err)
-	}
-	return p
-}
-
-func gone(p string) bool { _, err := os.Stat(p); return os.IsNotExist(err) }
-
-// 1839/AC2: a released workspace is gone at once; one already gone is no error; one a running step holds is refused
-// and kept; an id that is not a workspace's is refused.
-func TestReleaseRemovesAWorkspaceAtOnce(t *testing.T) {
-	w := &Workspaces{Dir: t.TempDir()}
-	p := makeWorkspace(t, w, "abc1", 0)
-	if err := w.Release("abc1"); err != nil || !gone(p) {
-		t.Fatalf("Release = %v, gone %v", err, gone(p))
-	}
-	if err := w.Release("abc1"); err != nil {
-		t.Errorf("a second release = %v, want nil", err)
-	}
-	held := makeWorkspace(t, w, "abc2", 0)
-	done := w.Hold("abc2")
-	if err := w.Release("abc2"); err == nil || gone(held) {
-		t.Errorf("Release of a held workspace = %v, gone %v; want refused and kept", err, gone(held))
-	}
-	done()
-	if err := w.Release("abc2"); err != nil || !gone(held) {
-		t.Errorf("Release after the hold ended = %v, gone %v", err, gone(held))
-	}
-	if err := w.Release("../etc"); err == nil {
-		t.Errorf("Release of ../etc answered nil")
-	}
-}
-
-// 1839/AC3: the sweep removes a workspace no step holds whose last use is past the bound, and keeps a held one and a
-// recent one; a hold ending counts as a use.
-func TestSweepRemovesUnheldWorkspacesPastTheBound(t *testing.T) {
-	w := &Workspaces{Dir: t.TempDir()}
-	old := makeWorkspace(t, w, "old1", 3*time.Hour)
-	heldOld := makeWorkspace(t, w, "held1", 3*time.Hour)
-	recent := makeWorkspace(t, w, "new1", time.Minute)
-	if err := os.WriteFile(filepath.Join(w.Dir, "not-a-workspace.txt"), nil, 0o600); err != nil {
-		t.Fatal(err)
-	}
-	done := w.Hold("held1")
-	removed := w.Sweep(time.Now(), 2*time.Hour)
-	if !gone(old) || gone(heldOld) || gone(recent) {
-		t.Errorf("after the sweep: old gone %v, held kept %v, recent kept %v", gone(old), !gone(heldOld), !gone(recent))
-	}
-	if len(removed) != 1 || removed[0] != "old1" {
-		t.Errorf("Sweep answered %v, want [old1]", removed)
-	}
-	done()
-	if w.Sweep(time.Now(), 2*time.Hour); gone(heldOld) {
-		t.Errorf("a workspace whose hold just ended was swept: its end is a use")
-	}
-}

go/bus_waits_for_serve_test.go

@@ -0,0 +1,81 @@
+package stdio
+
+import (
+	"io"
+	"testing"
+	"time"
+)
+
+// A bus function called before Serve waits for Serve and proceeds (issue 1966): a module that starts a goroutine
+// before stdio.Serve and calls the bus there is no longer refused. It is refused only when the process never serves.
+// The test drives the wait itself: serveWait is the test's own timer channel, no row sleeps on a clock.
+func subBusFunctionsWaitForServe(t *testing.T) {
+	const refusal = "before Serve: a bundle reaches the bus through the runtime that launched it"
+	for _, tc := range []struct {
+		name   string
+		serve  string // "first": before the call; "during": while the call waits; "never"
+		wantOK bool
+	}{
+		{"a call before Serve completes after Serve", "during", true},
+		{"a call whose wait ends before Serve is refused", "never", false},
+		{"a call after Serve is as before", "first", true},
+	} {
+		t.Run(tc.name, func(t *testing.T) {
+			servesAlone(t)
+			expire := make(chan time.Time)
+			oldAfter := serveTimer
+			serveTimer = func() (<-chan time.Time, func()) { return expire, func() {} }
+			t.Cleanup(func() { serveTimer = oldAfter })
+
+			inR, inW := io.Pipe()
+			outR, outW := io.Pipe()
+			stopped := make(chan struct{})
+			serve := func() {
+				go func() { _ = ServeOn("m", nil, inR, outW); close(stopped) }()
+			}
+			t.Cleanup(func() { _ = inW.Close(); go func() { _, _ = io.Copy(io.Discard, outR) }() })
+
+			type result struct {
+				c   *channel
+				err error
+			}
+			done := make(chan result, 1)
+			if tc.serve == "first" {
+				serve()
+				<-Served()
+				c, err := live()
+				done <- result{c, err}
+			} else {
+				go func() { c, err := live(); done <- result{c, err} }()
+				select {
+				case r := <-done:
+					t.Fatalf("live() returned before Serve and before its wait ended: %v", r.err)
+				default:
+				}
+				if tc.serve == "during" {
+					serve()
+				} else {
+					expire <- time.Time{}
+				}
+			}
+			r := <-done
+			if tc.wantOK != (r.err == nil && r.c != nil) {
+				t.Fatalf("live() = %v, %v; want ok=%v", r.c, r.err, tc.wantOK)
+			}
+			if !tc.wantOK && r.err.Error() != refusal {
+				t.Fatalf("refusal words changed: %v", r.err)
+			}
+			if tc.serve != "never" {
+				_ = inW.Close()
+				<-stopped
+			}
+		})
+	}
+}
+
+// TestBusFunctionsWaitForServe runs the tests of this package that were merged to keep the module within its test budget (design 47 G §419), each as a subtest.
+func TestBusFunctionsWaitForServe(t *testing.T) {
+	t.Run("BusFunctionsWaitForServe", subBusFunctionsWaitForServe)
+	t.Run("ACapabilityWordIsReadOnceAndNamedWhenNotStated", subACapabilityWordIsReadOnceAndNamedWhenNotStated)
+	t.Run("ABundleAsksAnAcknowledgedPublishAndASubscriptionForNewMessages", subABundleAsksAnAcknowledgedPublishAndASubscriptionForNewMessages)
+}

go/busarchive/archive.go

@@ -0,0 +1,162 @@
+package busarchive
+
+import (
+	"archive/tar"
+	"crypto/sha256"
+	"encoding/hex"
+	"encoding/json"
+	"errors"
+	"fmt"
+	"io"
+	"os"
+	"path/filepath"
+)
+
+// Archive is a snapshot read back: its manifest, and each file beside it unpacked into a scratch
+// directory of its own, removed by Close.
+type Archive struct {
+	Manifest Manifest
+	dir      string
+	files    map[string]string
+}
+
+// ReadArchive unpacks a snapshot. Only the files the manifest names are kept, and only under names
+// that are one stream's directory: an archive is data, and a path in it is never trusted to say where
+// on the machine a file goes.
+func ReadArchive(r io.Reader, scratch string) (*Archive, error) {
+	dir, err := os.MkdirTemp(scratch, "mesh-nats-restore-*")
+	if err != nil {
+		return nil, err
+	}
+	a := &Archive{dir: dir, files: map[string]string{}}
+	tr := tar.NewReader(r)
+	first := true
+	for {
+		hdr, err := tr.Next()
+		if err == io.EOF {
+			break
+		}
+		if err != nil {
+			a.Close()
+			return nil, fmt.Errorf("the archive does not read: %w", err)
+		}
+		if first {
+			if hdr.Name != ManifestName {
+				a.Close()
+				return nil, fmt.Errorf("the archive starts with %q, not its manifest: it is not a snapshot of the bus", hdr.Name)
+			}
+			raw, err := io.ReadAll(io.LimitReader(tr, 64<<20))
+			if err != nil {
+				a.Close()
+				return nil, err
+			}
+			if err := json.Unmarshal(raw, &a.Manifest); err != nil {
+				a.Close()
+				return nil, fmt.Errorf("its manifest: %w", err)
+			}
+			if a.Manifest.Format != 1 {
+				a.Close()
+				return nil, fmt.Errorf("its manifest is format %d; this program reads format 1", a.Manifest.Format)
+			}
+			first = false
+			continue
+		}
+		if !a.named(hdr.Name) {
+			a.Close()
+			return nil, fmt.Errorf("the archive holds %q, which its manifest does not name", hdr.Name)
+		}
+		local := filepath.Join(dir, fmt.Sprintf("%04d", len(a.files)))
+		f, err := os.OpenFile(local, os.O_CREATE|os.O_EXCL|os.O_WRONLY, 0o600)
+		if err != nil {
+			a.Close()
+			return nil, err
+		}
+		_, err = io.Copy(f, tr)
+		f.Close()
+		if err != nil {
+			a.Close()
+			return nil, err
+		}
+		a.files[hdr.Name] = local
+	}
+	if first {
+		a.Close()
+		return nil, errors.New("the archive is empty")
+	}
+	for _, s := range a.Manifest.Streams {
+		if !ValidName(s.Name) || s.Meta != "streams/"+s.Name+"/backup.json" || s.Archive != "streams/"+s.Name+"/stream.tar.s2" {
+			a.Close()
+			return nil, fmt.Errorf("the manifest names a stream %q at paths that are not its own", s.Name)
+		}
+	}
+	return a, nil
+}
+
+func (a *Archive) named(name string) bool {
+	for _, s := range a.Manifest.Streams {
+		if name == s.Meta || name == s.Archive {
+			return true
+		}
+	}
+	return false
+}
+
+// Close removes the unpacked files.
+func (a *Archive) Close() { os.RemoveAll(a.dir) }
+
+// Verify holds every file to the manifest's size and checksum, and reads every stream's archive to
+// its end.
+func (a *Archive) Verify() error {
+	for _, s := range a.Manifest.Streams {
+		for _, f := range []struct{ name, sum string }{{s.Meta, s.MetaSHA256}, {s.Archive, s.ArchiveSHA256}} {
+			local, ok := a.files[f.name]
+			if !ok {
+				return fmt.Errorf("%s is named in the manifest and missing from the archive", f.name)
+			}
+			got, size, err := sha256Of(local)
+			if err != nil {
+				return err
+			}
+			if got != f.sum {
+				return fmt.Errorf("%s does not match the checksum its manifest gives", f.name)
+			}
+			if f.name == s.Archive && size != s.ArchiveBytes {
+				return fmt.Errorf("%s is %d bytes; its manifest says %d", f.name, size, s.ArchiveBytes)
+			}
+		}
+		af, err := os.Open(a.files[s.Archive])
+		if err != nil {
+			return err
+		}
+		err = ReadsThrough(af)
+		af.Close()
+		if err != nil {
+			return fmt.Errorf("%s does not read: %w", s.Archive, err)
+		}
+	}
+	return nil
+}
+
+func sha256Of(path string) (string, int64, error) {
+	f, err := os.Open(path)
+	if err != nil {
+		return "", 0, err
+	}
+	defer f.Close()
+	h := sha256.New()
+	n, err := io.Copy(h, f)
+	if err != nil {
+		return "", 0, err
+	}
+	return hex.EncodeToString(h.Sum(nil)), n, nil
+}
+
+// Open is one stream's meta and archive.
+func (a *Archive) Open(s StreamEntry) (meta []byte, archive *os.File, err error) {
+	meta, err = os.ReadFile(a.files[s.Meta])
+	if err != nil {
+		return nil, nil, err
+	}
+	archive, err = os.Open(a.files[s.Archive])
+	return meta, archive, err
+}

go/busarchive/types.go

@@ -0,0 +1,86 @@
+// Package busarchive is the bus's snapshot archive: its manifest, reading one back and holding it to
+// its checksums. The snapshot program (cmd/mesh-nats-snapshot) writes and restores with it and the bus's
+// tool nats_snapshot_verify (cmd/nats-tools) checks with it, so the two never differ on what a good
+// snapshot is.
+package busarchive
+
+import (
+	"archive/tar"
+	"io"
+	"strings"
+	"time"
+
+	"github.com/klauspost/compress/s2"
+)
+
+// Manifest is the first entry of an archive: what was taken, when, how long it took, and the checksum
+// of every file beside it. It is what `verify` and `restore` hold the archive to.
+type Manifest struct {
+	Format   int       `json:"format"`
+	Server   string    `json:"server_version"`
+	Started  time.Time `json:"started"`
+	Finished time.Time `json:"finished"`
+	Seconds  float64   `json:"seconds"`
+	// Messages and StreamBytes are the streams' own totals at their snapshots; ArchiveBytes what the
+	// archives take, compressed.
+	Messages     uint64        `json:"messages"`
+	StreamBytes  int64         `json:"stream_bytes"`
+	ArchiveBytes int64         `json:"archive_bytes"`
+	Streams      []StreamEntry `json:"streams"`
+	// Skipped are streams that hold nothing across a restart (memory storage), said rather than
+	// silently left out.
+	Skipped []Skipped `json:"skipped,omitempty"`
+}
+
+// StreamEntry is one stream as it was snapshotted.
+type StreamEntry struct {
+	Name      string   `json:"name"`
+	Subjects  []string `json:"subjects,omitempty"`
+	Retention string   `json:"retention,omitempty"`
+	Messages  uint64   `json:"messages"`
+	Bytes     uint64   `json:"bytes"`
+	FirstSeq  uint64   `json:"first_seq"`
+	LastSeq   uint64   `json:"last_seq"`
+	Deleted   int      `json:"deleted,omitempty"`
+	Consumers int      `json:"consumers"`
+	// Meta is the server's own description of the stream (its configuration and state), in the
+	// shape the restore API and the nats CLI take back: backup.json.
+	Meta       string `json:"meta"`
+	MetaSHA256 string `json:"meta_sha256"`
+	// Archive is the server's snapshot of the stream, as the server sent it: stream.tar.s2.
+	Archive       string  `json:"archive"`
+	ArchiveBytes  int64   `json:"archive_bytes"`
+	ArchiveSHA256 string  `json:"archive_sha256"`
+	Seconds       float64 `json:"seconds"`
+}
+
+// Skipped is a stream not snapshotted, and why.
+type Skipped struct {
+	Name string `json:"name"`
+	Why  string `json:"why"`
+}
+
+// ManifestName is the archive's first entry.
+const ManifestName = "manifest.json"
+
+// ReadsThrough is whether a stream's archive decompresses and lists to its end.
+func ReadsThrough(r io.Reader) error {
+	tr := tar.NewReader(s2.NewReader(r))
+	for {
+		_, err := tr.Next()
+		if err == io.EOF {
+			return nil
+		}
+		if err != nil {
+			return err
+		}
+		if _, err := io.Copy(io.Discard, tr); err != nil {
+			return err
+		}
+	}
+}
+
+// ValidName is a stream name that is one safe path component.
+func ValidName(name string) bool {
+	return name != "" && name != "." && name != ".." && !strings.ContainsAny(name, "/\\\x00 *>")
+}

go/busarchive/verifyfile.go

@@ -0,0 +1,109 @@
+package busarchive
+
+import (
+	"errors"
+	"fmt"
+	"io/fs"
+	"os"
+	"path/filepath"
+	"strings"
+	"time"
+)
+
+// StreamReport is one stream of a verified snapshot.
+type StreamReport struct {
+	Name    string `json:"name"`
+	LastSeq uint64 `json:"last_seq"`
+}
+
+// Report is the answer of VerifyFile: which file was held to its manifest, and whether it passed.
+type Report struct {
+	File     string         `json:"file"`
+	Modified time.Time      `json:"modified"`
+	Size     int64          `json:"size"`
+	Taken    *time.Time     `json:"taken,omitempty"`
+	Streams  []StreamReport `json:"streams"`
+	Skipped  []Skipped      `json:"skipped,omitempty"`
+	Passed   bool           `json:"passed"`
+	// Fault is the first thing wrong, empty when the snapshot passed.
+	Fault string `json:"fault,omitempty"`
+}
+
+// VerifyFile verifies one snapshot inside dir: the file called name, or the newest *.tar when name is
+// empty. Nothing outside dir is read and nothing is written there; a snapshot that fails is an answer
+// (Passed false, the first Fault), and only a directory without a snapshot is an error.
+func VerifyFile(dir, name string) (*Report, error) {
+	path, info, err := pick(dir, name)
+	if err != nil {
+		return nil, err
+	}
+	r := &Report{File: filepath.Base(path), Modified: info.ModTime().UTC(), Size: info.Size(), Streams: []StreamReport{}}
+	f, err := os.Open(path)
+	if err != nil {
+		r.Fault = err.Error()
+		return r, nil
+	}
+	defer f.Close()
+	a, err := ReadArchive(f, "")
+	if err != nil {
+		r.Fault = err.Error()
+		return r, nil
+	}
+	defer a.Close()
+	taken := a.Manifest.Finished
+	r.Taken = &taken
+	r.Skipped = a.Manifest.Skipped
+	for _, s := range a.Manifest.Streams {
+		r.Streams = append(r.Streams, StreamReport{Name: s.Name, LastSeq: s.LastSeq})
+	}
+	if err := a.Verify(); err != nil {
+		r.Fault = err.Error()
+		return r, nil
+	}
+	r.Passed = true
+	return r, nil
+}
+
+// pick names the regular file to verify, and nothing outside dir: a name is one path component, and a
+// symbolic link is not followed out of the directory.
+func pick(dir, name string) (string, fs.FileInfo, error) {
+	if dir == "" {
+		return "", nil, errors.New("the snapshots directory is not set")
+	}
+	if name != "" {
+		if name != filepath.Base(name) || name == "." || name == ".." || strings.ContainsRune(name, 0) {
+			return "", nil, fmt.Errorf("%q is not a file name inside the snapshots directory", name)
+		}
+		p := filepath.Join(dir, name)
+		info, err := os.Lstat(p)
+		if err != nil {
+			return "", nil, fmt.Errorf("no snapshot %s in the snapshots directory: %w", name, err)
+		}
+		if !info.Mode().IsRegular() {
+			return "", nil, fmt.Errorf("%s is not a regular file", name)
+		}
+		return p, info, nil
+	}
+	entries, err := os.ReadDir(dir)
+	if err != nil {
+		return "", nil, fmt.Errorf("the snapshots directory does not read: %w", err)
+	}
+	var best string
+	var bestInfo fs.FileInfo
+	for _, e := range entries {
+		if !strings.HasSuffix(e.Name(), ".tar") {
+			continue
+		}
+		info, err := e.Info()
+		if err != nil || !info.Mode().IsRegular() {
+			continue
+		}
+		if bestInfo == nil || info.ModTime().After(bestInfo.ModTime()) {
+			best, bestInfo = e.Name(), info
+		}
+	}
+	if bestInfo == nil {
+		return "", nil, errors.New("the snapshots directory holds no .tar snapshot")
+	}
+	return filepath.Join(dir, best), bestInfo, nil
+}

go/busarchive/verifyfile_test.go

@@ -0,0 +1,182 @@
+package busarchive
+
+import (
+	"archive/tar"
+	"bytes"
+	"crypto/sha256"
+	"encoding/hex"
+	"encoding/json"
+	"os"
+	"path/filepath"
+	"strings"
+	"testing"
+	"time"
+
+	"github.com/klauspost/compress/s2"
+)
+
+func sum(b []byte) string { h := sha256.Sum256(b); return hex.EncodeToString(h[:]) }
+
+// streamArchive is a stream's archive as the server sends it: a tar of one file, s2-compressed.
+func streamArchive(t *testing.T) []byte {
+	t.Helper()
+	var raw bytes.Buffer
+	tw := tar.NewWriter(&raw)
+	body := []byte(strings.Repeat("a message of the stream\n", 50))
+	if err := tw.WriteHeader(&tar.Header{Name: "msgs.blk", Mode: 0o600, Size: int64(len(body))}); err != nil {
+		t.Fatal(err)
+	}
+	tw.Write(body)
+	tw.Close()
+	var out bytes.Buffer
+	w := s2.NewWriter(&out)
+	w.Write(raw.Bytes())
+	w.Close()
+	return out.Bytes()
+}
+
+// snapshotTar builds a snapshot of two streams; the mutations change what the manifest says or what is
+// stored, so each fault is made in the one place it is found.
+func snapshotTar(t *testing.T, mutate func(m *Manifest, files map[string][]byte)) []byte {
+	t.Helper()
+	files := map[string][]byte{}
+	m := Manifest{Format: 1, Server: "2.11.17", Finished: time.Date(2026, 10, 22, 3, 0, 0, 0, time.UTC)}
+	for i, name := range []string{"EVENTS", "KV_conditions"} {
+		meta := []byte(`{"config":{"name":"` + name + `"}}`)
+		arc := streamArchive(t)
+		e := StreamEntry{Name: name, LastSeq: uint64(10 * (i + 1)),
+			Meta: "streams/" + name + "/backup.json", MetaSHA256: sum(meta),
+			Archive: "streams/" + name + "/stream.tar.s2", ArchiveBytes: int64(len(arc)), ArchiveSHA256: sum(arc)}
+		m.Streams = append(m.Streams, e)
+		files[e.Meta], files[e.Archive] = meta, arc
+	}
+	if mutate != nil {
+		mutate(&m, files)
+	}
+	var out bytes.Buffer
+	tw := tar.NewWriter(&out)
+	put := func(name string, b []byte) {
+		if err := tw.WriteHeader(&tar.Header{Name: name, Mode: 0o600, Size: int64(len(b))}); err != nil {
+			t.Fatal(err)
+		}
+		tw.Write(b)
+	}
+	raw, _ := json.Marshal(m)
+	put(ManifestName, raw)
+	for _, s := range m.Streams {
+		put(s.Meta, files[s.Meta])
+		put(s.Archive, files[s.Archive])
+	}
+	tw.Close()
+	return out.Bytes()
+}
+
+func put(t *testing.T, dir, name string, b []byte, at time.Time) {
+	t.Helper()
+	p := filepath.Join(dir, name)
+	if err := os.WriteFile(p, b, 0o600); err != nil {
+		t.Fatal(err)
+	}
+	os.Chtimes(p, at, at)
+}
+
+func subAGoodSnapshotPassesAndSaysItsStreams(t *testing.T) {
+	dir := t.TempDir()
+	good := snapshotTar(t, nil)
+	put(t, dir, "bus.tar", good, time.Now())
+	r, err := VerifyFile(dir, "")
+	if err != nil {
+		t.Fatal(err)
+	}
+	if !r.Passed || r.Fault != "" || r.File != "bus.tar" || r.Size != int64(len(good)) {
+		t.Fatalf("%+v", r)
+	}
+	if r.Taken == nil || !r.Taken.Equal(time.Date(2026, 10, 22, 3, 0, 0, 0, time.UTC)) {
+		t.Errorf("taken %v", r.Taken)
+	}
+	if len(r.Streams) != 2 || r.Streams[0] != (StreamReport{"EVENTS", 10}) || r.Streams[1] != (StreamReport{"KV_conditions", 20}) {
+		t.Errorf("streams %+v", r.Streams)
+	}
+}
+
+func subACorruptedChecksumFailsNamingTheFile(t *testing.T) {
+	dir := t.TempDir()
+	put(t, dir, "bus.tar", snapshotTar(t, func(m *Manifest, files map[string][]byte) {
+		m.Streams[1].ArchiveSHA256 = sum([]byte("something else"))
+	}), time.Now())
+	r, err := VerifyFile(dir, "bus.tar")
+	if err != nil {
+		t.Fatal(err)
+	}
+	if r.Passed || !strings.Contains(r.Fault, "streams/KV_conditions/stream.tar.s2") || !strings.Contains(r.Fault, "checksum") {
+		t.Fatalf("%+v", r)
+	}
+	if len(r.Streams) != 2 {
+		t.Errorf("a failed snapshot still says its streams: %+v", r.Streams)
+	}
+}
+
+func subATruncatedSnapshotFails(t *testing.T) {
+	dir := t.TempDir()
+	good := snapshotTar(t, nil)
+	put(t, dir, "bus.tar", good[:len(good)*2/3], time.Now())
+	r, err := VerifyFile(dir, "")
+	if err != nil {
+		t.Fatal(err)
+	}
+	if r.Passed || r.Fault == "" {
+		t.Fatalf("a truncated snapshot passed: %+v", r)
+	}
+}
+
+func subAnArchiveThatDoesNotReadToItsEndFailsEvenWithMatchingChecksums(t *testing.T) {
+	dir := t.TempDir()
+	put(t, dir, "bus.tar", snapshotTar(t, func(m *Manifest, files map[string][]byte) {
+		bad := []byte("not an s2 stream at all")
+		s := &m.Streams[0]
+		files[s.Archive] = bad
+		s.ArchiveSHA256, s.ArchiveBytes = sum(bad), int64(len(bad))
+	}), time.Now())
+	r, _ := VerifyFile(dir, "")
+	if r.Passed || !strings.Contains(r.Fault, "does not read") {
+		t.Fatalf("%+v", r)
+	}
+}
+
+func subTheNewestTarIsVerifiedAndOnlyInsideTheDirectory(t *testing.T) {
+	dir := t.TempDir()
+	now := time.Now()
+	put(t, dir, "old.tar", []byte("junk"), now.Add(-48*time.Hour))
+	put(t, dir, "bus.tar", snapshotTar(t, nil), now)
+	put(t, dir, "bus.tar.partial", []byte("half"), now.Add(time.Hour))
+	r, err := VerifyFile(dir, "")
+	if err != nil || r.File != "bus.tar" || !r.Passed {
+		t.Fatalf("%+v %v", r, err)
+	}
+	if r, _ := VerifyFile(dir, "old.tar"); r.Passed || r.File != "old.tar" {
+		t.Errorf("a named file is the one checked: %+v", r)
+	}
+	outside := t.TempDir()
+	put(t, outside, "x.tar", snapshotTar(t, nil), now)
+	for _, name := range []string{"../" + filepath.Base(outside) + "/x.tar", outside + "/x.tar", ".."} {
+		if _, err := VerifyFile(dir, name); err == nil {
+			t.Errorf("%q was read", name)
+		}
+	}
+	os.Symlink(filepath.Join(outside, "x.tar"), filepath.Join(dir, "link.tar"))
+	if _, err := VerifyFile(dir, "link.tar"); err == nil {
+		t.Error("a symbolic link out of the directory was followed")
+	}
+	if _, err := VerifyFile(t.TempDir(), ""); err == nil {
+		t.Error("an empty directory is not a snapshot")
+	}
+}
+
+// TestAGoodSnapshotPassesAndSaysItsStreams runs the tests of this package that were merged to keep the module within its test budget (design 47 G §419), each as a subtest.
+func TestAGoodSnapshotPassesAndSaysItsStreams(t *testing.T) {
+	t.Run("AGoodSnapshotPassesAndSaysItsStreams", subAGoodSnapshotPassesAndSaysItsStreams)
+	t.Run("ACorruptedChecksumFailsNamingTheFile", subACorruptedChecksumFailsNamingTheFile)
+	t.Run("ATruncatedSnapshotFails", subATruncatedSnapshotFails)
+	t.Run("AnArchiveThatDoesNotReadToItsEndFailsEvenWithMatchingChecksums", subAnArchiveThatDoesNotReadToItsEndFailsEvenWithMatchingChecksums)
+	t.Run("TheNewestTarIsVerifiedAndOnlyInsideTheDirectory", subTheNewestTarIsVerifiedAndOnlyInsideTheDirectory)
+}

go/buscalls/answer.go

@@ -0,0 +1,50 @@
+package buscalls
+
+import "encoding/json"
+
+// Unwrap reads a tool's answer whatever wraps it on its way from the tool runner (the lead's ruling 2026-11-04 13:12:
+// one reading, not a copy per module): a JSON string holding the answer; the protocol's content list, whose first
+// text is the answer and whose isError says it failed; the {output, ok, answer} form; the tool runner's {result,
+// error} envelope, whose error is the call's. It answers the answer itself, the words said with it (the output, the
+// error, or the answer's own text), and whether the tool says it succeeded. A bare answer is itself, succeeded.
+func Unwrap(raw json.RawMessage) (answer json.RawMessage, said string, ok bool) {
+	var s string
+	if json.Unmarshal(raw, &s) == nil {
+		return Unwrap(json.RawMessage(s))
+	}
+	var m map[string]json.RawMessage
+	if json.Unmarshal(raw, &m) != nil {
+		return raw, string(raw), true
+	}
+	if content, has := m["content"]; has {
+		var items []struct {
+			Text string `json:"text"`
+		}
+		var e struct {
+			IsError bool `json:"isError"`
+		}
+		_ = json.Unmarshal(raw, &e)
+		if json.Unmarshal(content, &items) == nil && len(items) > 0 {
+			inner, out, ok := Unwrap(json.RawMessage(items[0].Text))
+			return inner, out, ok && !e.IsError
+		}
+	}
+	var v struct {
+		Output string          `json:"output"`
+		OK     *bool           `json:"ok"`
+		Answer json.RawMessage `json:"answer"`
+		Result json.RawMessage `json:"result"`
+		Error  string          `json:"error"`
+	}
+	if json.Unmarshal(raw, &v) == nil {
+		switch {
+		case v.OK != nil:
+			return v.Answer, v.Output, *v.OK
+		case v.Error != "":
+			return nil, v.Error, false
+		case len(v.Result) > 0:
+			return Unwrap(v.Result)
+		}
+	}
+	return raw, string(raw), true
+}

go/buscalls/buscalls.go

@@ -0,0 +1,497 @@
+// Package buscalls is the contract of the calls a bundle makes on its own bus state through the tool runner, over the
+// bundle's pipe (novox/hq ADR 0595 §9, ADR 0597 §10, design 25 § 12.5): the object store's, a stream's read-back and
+// fill, a work queue's size and dead letters, and the ledger's. Each call names an entry by the local name its module
+// asks for it by in `requires`; the tool runner serves it from the module's membership's bindings, its own entries
+// only. Only the shapes and the method names are here: what the tool runner refuses, and why, is its own.
+//
+// It is a package of its own, imported only by the modules that use these calls and by the tool runner, so a change
+// here rebuilds those and not the module library's importers (ADR 0595 §9). It imports nothing of mesh-sdk.
+package buscalls
+
+import (
+	"encoding/json"
+	"fmt"
+	"strings"
+	"time"
+)
+
+// MetaCall is where in a `tools/call`'s `_meta` the tool runner hands a bundle the id of the tool call in flight: the id
+// ApplyRequest.Call names, so the runner stamps the caller it proved for that call as the operation's author (novox/hq
+// ADR 0597 §7). The runner writes `_meta`; a caller writes only `arguments`, so no caller can name another call.
+const MetaCall = "mesh/call"
+
+// The methods a bundle asks the tool runner, one per call.
+const (
+	ObjectsPut    = "mesh/objects.put"
+	ObjectsGet    = "mesh/objects.get"
+	ObjectsList   = "mesh/objects.list"
+	ObjectsDelete = "mesh/objects.delete"
+	ObjectsInfo   = "mesh/objects.info"
+	ObjectsWatch  = "mesh/objects.watch"
+	// ObjectsSentGet reads an object of a sender's store of sent objects by the reference a reply or an event carried
+	// (design 47 G §347, §407), served under the standing grant the grants part derives from the manifests; the answer is
+	// ObjectData.
+	ObjectsSentGet = "mesh/objects.sent-get"
+	// ObjectsPutChunk and ObjectsGetChunk are the put session's and the get session's calls (design 47 G §518, §345, §490),
+	// under the capability word put-sessions (stdio.CapPutSessions): a value larger than ChunkBytes is put as chunks in order,
+	// each answered before the next, and a get that answers ObjectsChunked is read chunk by chunk.
+	ObjectsPutChunk = "mesh/objects.put-chunk"
+	ObjectsGetChunk = "mesh/objects.get-chunk"
+
+	StreamRead = "mesh/stream.read"
+	StreamFill = "mesh/stream.fill"
+	// StreamPublish says one event on the module's own bound stream (A-42).
+	StreamPublish = "mesh/stream.publish"
+
+	WorkQueueSize = "mesh/workqueue.size"
+	WorkQueueDead = "mesh/workqueue.dead"
+
+	LedgerApply   = "mesh/ledger.apply"
+	LedgerGet     = "mesh/ledger.get"
+	LedgerHistory = "mesh/ledger.history"
+	LedgerWatch   = "mesh/ledger.watch"
+	LedgerQuery   = "mesh/ledger.query"
+	// LedgerFill is one ledger's history's fill against its cap, asked with a LedgerRequest and answered as a Fill
+	// (design 47 G §462, §587); LedgerRemove removes one instance, asked with a LedgerRemoveRequest and answered as
+	// LedgerRemoved. Both are under the capability word LedgerUpkeepCalls.
+	LedgerFill   = "mesh/ledger.fill"
+	LedgerRemove = "mesh/ledger.remove"
+	// The ledger's repairs, which the tool runner also serves as tools of every module owning a ledger, its own
+	// ledgers only (design 25 § 12.5).
+	LedgerRebuild  = "mesh/ledger.rebuild"
+	LedgerReindex  = "mesh/ledger.reindex"
+	LedgerSnapshot = "mesh/ledger.snapshot"
+	LedgerLag      = "mesh/ledger.lag"
+)
+
+// The capability words of the families this package's calls belong to (design 47 G §488, §622): a tool runner states a
+// word once it answers the family, and a bundle fails at once, naming the word and its node, on a call whose word is not
+// stated. Which calls each word covers is the tool runner's (§462).
+const (
+	BusStateCalls     = "bus-state-calls"
+	LedgerCalls       = "ledger-calls"
+	LedgerUpkeepCalls = "ledger-upkeep-calls"
+	SentObjectsCalls  = "sent-objects-calls"
+	// StreamPublishWord is the family of StreamPublish alone, the word a module asks for in `capabilities` before it
+	// says an event on its own bound stream (design 42 zfs-owns-zfs, A-44).
+	StreamPublishWord = "stream-publish"
+)
+
+// The methods the tool runner sends the bundle for a watch it asked, each naming the watch by its id, as `mesh/log`
+// does for a log.
+const (
+	ObjectsWatched = "mesh/objects"
+	LedgerWatched  = "mesh/ledger"
+)
+
+// Fill is how much an entry holds against its cap: its messages (or objects), its bytes and its cap in bytes.
+type Fill struct {
+	Count    uint64 `json:"count"`
+	Bytes    uint64 `json:"bytes"`
+	MaxBytes uint64 `json:"max_bytes"`
+}
+
+// Done is the answer of a call that answers nothing but that it was done.
+type Done struct{}
+
+// --- the object store
+
+// ObjectsPutRequest stores one object whole under its name, replacing one of that name.
+type ObjectsPutRequest struct {
+	Objects     string `json:"objects"`
+	Name        string `json:"name"`
+	Data        []byte `json:"data"`
+	Description string `json:"description,omitempty"`
+}
+
+// ChunkBytes is the size of one chunk of a put or get session, and so the largest value one call puts or gets (design 47 G
+// §518, A-21): it fits under the bus's default maximum payload, whatever the bus sets it to.
+const ChunkBytes = 512 << 10
+
+// ObjectsPutChunkRequest is one chunk of a put session (design 47 G §518, A-21): the object `name` in the store `objects`,
+// `call` the bundle's id for this put, `seq` from 1 and one more each chunk, `last` true on the last chunk alone, and the
+// chunk's bytes; the first chunk also carries the put's `description` (A-25).
+type ObjectsPutChunkRequest struct {
+	Objects string `json:"objects"`
+	Name    string `json:"name"`
+	Call    string `json:"call"`
+	Seq     uint32 `json:"seq"`
+	Last    bool   `json:"last,omitempty"`
+	Data    []byte `json:"data"`
+	// Description is the put's, carried on the first chunk alone (design 47 G A-25).
+	Description string `json:"description,omitempty"`
+}
+
+// ObjectsChunkTaken is the answer to a chunk that is not the last: the sequence taken, or the reason it was not.
+type ObjectsChunkTaken struct {
+	Seq   uint32 `json:"seq"`
+	Error string `json:"error,omitempty"`
+}
+
+// ObjectsChunked is the answer of a get of a value over one chunk (design 47 G §490, §518, §620): the count of chunks (or
+// true, for a sent object), the whole size, its `sha256:` digest and the session's `call`. Its Chunked is absent from the
+// answer of a value read in one call.
+type ObjectsChunked struct {
+	Chunked json.RawMessage `json:"chunked"`
+	Size    uint64          `json:"size"`
+	Digest  string          `json:"digest"`
+	Call    string          `json:"call"`
+}
+
+// ObjectsGetChunkRequest asks one chunk of a get session by its call and sequence.
+type ObjectsGetChunkRequest struct {
+	Call string `json:"call"`
+	Seq  uint32 `json:"seq"`
+}
+
+// ObjectsChunk is a get session's chunk: the sequence, whether it is the last, its bytes, or the reason it is none.
+type ObjectsChunk struct {
+	Seq   uint32 `json:"seq"`
+	Last  bool   `json:"last"`
+	Data  []byte `json:"data"`
+	Error string `json:"error,omitempty"`
+}
+
+// ObjectsNameRequest names one object of an object store: get, delete.
+type ObjectsNameRequest struct {
+	Objects string `json:"objects"`
+	Name    string `json:"name"`
+}
+
+// ObjectsRequest names an object store: list, info.
+type ObjectsRequest struct {
+	Objects string `json:"objects"`
+}
+
+// ObjectsWatchRequest asks the tool runner to send every object stored or deleted, as ObjectsChange under the watch's id.
+type ObjectsWatchRequest struct {
+	Objects string `json:"objects"`
+	Watch   string `json:"watch"`
+}
+
+// ObjectInfo is one object as its store holds it: put's answer, and each of list's.
+type ObjectInfo struct {
+	Name        string    `json:"name"`
+	Size        uint64    `json:"size"`
+	Chunks      uint32    `json:"chunks"`
+	Digest      string    `json:"digest"`
+	Description string    `json:"description,omitempty"`
+	Modified    time.Time `json:"modified"`
+	Deleted     bool      `json:"deleted,omitempty"`
+}
+
+// ObjectsSentGetRequest names one sent object by the reference that carried it (stateobjects.Ref's fields, which this
+// package does not import): the sender's store, the object's name, and its size and digest, which the reader checks.
+type ObjectsSentGetRequest struct {
+	Store  string `json:"store"`
+	Object string `json:"object"`
+	Size   int64  `json:"size"`
+	Digest string `json:"sha256"`
+}
+
+// ObjectData is get's answer: the object's info and its bytes.
+type ObjectData struct {
+	Info ObjectInfo `json:"info"`
+	Data []byte     `json:"data"`
+}
+
+// ObjectsListed is list's answer: every object the store holds.
+type ObjectsListed struct {
+	Objects []ObjectInfo `json:"objects"`
+}
+
+// ObjectsChange is one object stored or deleted, sent under ObjectsWatched; Current says it was there when the watch
+// began.
+type ObjectsChange struct {
+	Watch   string     `json:"watch"`
+	Object  ObjectInfo `json:"object"`
+	Current bool       `json:"current"`
+}
+
+// --- a stream
+
+// StreamReadRequest reads a module's own stream from a sequence on, at most Limit messages, Subjects narrowing it.
+type StreamReadRequest struct {
+	Stream   string `json:"stream"`
+	From     uint64 `json:"from"`
+	Subjects string `json:"subjects,omitempty"`
+	Limit    int    `json:"limit,omitempty"`
+}
+
+// StreamRequest names a stream: fill.
+type StreamRequest struct {
+	Stream string `json:"stream"`
+}
+
+// StreamMessage is one message of a stream.
+type StreamMessage struct {
+	Sequence uint64          `json:"sequence"`
+	Subject  string          `json:"subject"`
+	Body     json.RawMessage `json:"body"`
+	At       time.Time       `json:"at"`
+}
+
+// StreamPage is read's answer: the messages in order, the sequence to read on from (0 when nothing follows) and the
+// stream's last sequence when it was read.
+type StreamPage struct {
+	Messages []StreamMessage `json:"messages"`
+	Next     uint64          `json:"next"`
+	Last     uint64          `json:"last"`
+}
+
+// StreamPublishRequest says one event on a module's own stream, by the stream's local name: the tool runner publishes
+// Body on the binding's subject plus "." plus Event, acknowledged, with ID as the message id (design 42 zfs-owns-zfs, A-42).
+type StreamPublishRequest struct {
+	Stream string          `json:"stream"`
+	Event  string          `json:"event"`
+	Body   json.RawMessage `json:"body"`
+	ID     string          `json:"id,omitempty"`
+}
+
+// StreamPublished is publish's answer: the sequence the stream acknowledged the event at.
+type StreamPublished struct {
+	Sequence uint64 `json:"sequence"`
+}
+
+// StreamFilled is fill's answer: the stream's fill and its first and last sequence.
+type StreamFilled struct {
+	Fill
+	First uint64 `json:"first"`
+	Last  uint64 `json:"last"`
+}
+
+// --- a work queue
+
+// WorkQueueRequest names a work queue: size.
+type WorkQueueRequest struct {
+	Queue string `json:"queue"`
+}
+
+// WorkQueueDeadRequest asks a work queue's dead letters, at most Limit of them.
+type WorkQueueDeadRequest struct {
+	Queue string `json:"queue"`
+	Limit int    `json:"limit,omitempty"`
+}
+
+// WorkQueueSized is size's answer: the messages waiting to be taken, against the queue's cap.
+type WorkQueueSized struct {
+	Fill
+}
+
+// DeadLetter is one message delivered as often as its queue allows and never settled.
+type DeadLetter struct {
+	Sequence   uint64          `json:"sequence"`
+	Subject    string          `json:"subject"`
+	Deliveries int             `json:"deliveries"`
+	Body       json.RawMessage `json:"body,omitempty"`
+	At         time.Time       `json:"at"`
+}
+
+// WorkQueueDeadLetters is dead's answer.
+type WorkQueueDeadLetters struct {
+	Dead []DeadLetter `json:"dead"`
+}
+
+// --- the ledger (ADR 0597)
+
+// ApplyRequest applies one operation to one instance of a ledger. Call is the id of the tool call the operation
+// serves, as the tool runner handed it under MetaCall, whose caller the tool runner proved and stamps as the author
+// (ADR 0597 §7); empty, the operation carries the owning module's account alone. An author the bundle writes into Body
+// is never taken as the author.
+type ApplyRequest struct {
+	Ledger    string          `json:"ledger"`
+	Instance  string          `json:"instance"`
+	Operation string          `json:"operation"`
+	Body      json.RawMessage `json:"body,omitempty"`
+	Call      string          `json:"call,omitempty"`
+}
+
+// Applied is apply's answer: the operation was taken, with its sequence in the instance's history; StateBehind says
+// the state could not follow because its bucket is full, and catches up at the next apply after room is made (ADR
+// 0597 §6).
+type Applied struct {
+	Taken       bool   `json:"taken"`
+	Sequence    uint64 `json:"sequence"`
+	StateBehind bool   `json:"state_behind,omitempty"`
+}
+
+// Author is who an operation is by, as `apply` stamped it (ADR 0597 §7): the owning module's account, and the caller
+// of the tool call it served, as the tool runner proved it.
+type Author struct {
+	Account string `json:"account"`
+	Caller  string `json:"caller,omitempty"`
+}
+
+// InstanceRequest names one instance of a ledger: get, snapshot.
+type InstanceRequest struct {
+	Ledger   string `json:"ledger"`
+	Instance string `json:"instance"`
+}
+
+// InstanceState is get's answer: the instance's state and the sequence of the last operation it holds.
+type InstanceState struct {
+	Instance string          `json:"instance"`
+	State    json.RawMessage `json:"state"`
+	Sequence uint64          `json:"sequence"`
+}
+
+// HistoryRequest reads an instance's operations from a sequence on, at most Limit of them.
+type HistoryRequest struct {
+	Ledger   string `json:"ledger"`
+	Instance string `json:"instance"`
+	From     uint64 `json:"from,omitempty"`
+	Limit    int    `json:"limit,omitempty"`
+}
+
+// Operation is one operation as the history keeps it.
+type Operation struct {
+	Sequence  uint64          `json:"sequence"`
+	Instance  string          `json:"instance"`
+	Operation string          `json:"operation"`
+	Body      json.RawMessage `json:"body,omitempty"`
+	Author    Author          `json:"author"`
+	At        time.Time       `json:"at"`
+}
+
+// HistoryPage is history's answer: the operations oldest first, the sequence to read on from (0 when nothing
+// follows) and the instance's last sequence when it was read.
+type HistoryPage struct {
+	Operations []Operation `json:"operations"`
+	Next       uint64      `json:"next"`
+	Last       uint64      `json:"last"`
+}
+
+// LedgerWatchRequest asks the tool runner to send every change of the instances Instances names (an instance, with
+// `*` for one name and `>` for the rest) as InstanceChange under the watch's id: the current states first.
+type LedgerWatchRequest struct {
+	Ledger    string `json:"ledger"`
+	Instances string `json:"instances"`
+	Watch     string `json:"watch"`
+}
+
+// InstanceChange is one instance's new state, sent under LedgerWatched; Current says it was the state when the watch
+// began.
+type InstanceChange struct {
+	Watch    string          `json:"watch"`
+	Instance string          `json:"instance"`
+	State    json.RawMessage `json:"state"`
+	Sequence uint64          `json:"sequence"`
+	Current  bool            `json:"current"`
+}
+
+// QueryRequest reads a declared index of a ledger: the entries whose key Key names (a key, with `*` for one name and
+// `>` for the rest; empty is every key), at most Limit of them.
+type QueryRequest struct {
+	Ledger string `json:"ledger"`
+	Index  string `json:"index"`
+	Key    string `json:"key,omitempty"`
+	Limit  int    `json:"limit,omitempty"`
+}
+
+// IndexEntry is the value of one key of a declared index (IndexKey): the instance it points at, and the sequence of
+// the operation it was written from. The owner's watcher and the tool runner's reindex both write it so.
+type IndexEntry struct {
+	Instance string `json:"instance"`
+	Sequence uint64 `json:"sequence"`
+}
+
+// IndexKey is the key of an instance in a declared index: the values of the index's fields, in its order, then the
+// parts of the instance's path, all joined by ".". Each value and each path part is encoded (keyToken): every byte
+// outside [A-Za-z0-9_-] is written "=" and two upper-case hex digits ("." is "=2E", " " is "=20", "=" is "=3D"), so two
+// different keys never meet and every part is a token the bus takes. `17950.listing.a17` is the key of price 17950
+// and instance `listing/a17`. The owner's watcher and the tool runner's reindex both write it, so a reindex leaves the
+// index as the watcher keeps it.
+func IndexKey(fields []string, instance string) string {
+	parts := make([]string, 0, len(fields)+2)
+	for _, f := range fields {
+		parts = append(parts, keyToken(f))
+	}
+	for _, p := range strings.Split(instance, "/") {
+		parts = append(parts, keyToken(p))
+	}
+	return strings.Join(parts, ".")
+}
+
+// keyToken is v with every byte outside [A-Za-z0-9_-] written "=" and two upper-case hex digits (IndexKey).
+func keyToken(v string) string {
+	var b strings.Builder
+	for i := 0; i < len(v); i++ {
+		c := v[i]
+		if c >= 'a' && c <= 'z' || c >= 'A' && c <= 'Z' || c >= '0' && c <= '9' || c == '_' || c == '-' {
+			b.WriteByte(c)
+			continue
+		}
+		fmt.Fprintf(&b, "=%02X", c)
+	}
+	return b.String()
+}
+
+// QueryAnswer is query's answer.
+type QueryAnswer struct {
+	Entries []IndexEntry `json:"entries"`
+}
+
+// RebuildFrom is what a rebuild derives the state from: the history, or the snapshot and the operations after it.
+const (
+	RebuildFromHistory  = "history"
+	RebuildFromSnapshot = "snapshot"
+)
+
+// RebuildRequest derives an instance's state again (every instance's when Instance is empty), From the history or the
+// snapshot.
+type RebuildRequest struct {
+	Ledger   string `json:"ledger"`
+	Instance string `json:"instance,omitempty"`
+	From     string `json:"from,omitempty"`
+}
+
+// ReindexRequest builds a declared index again from the history.
+type ReindexRequest struct {
+	Ledger string `json:"ledger"`
+	Index  string `json:"index"`
+}
+
+// LedgerRequest names a ledger: lag, fill.
+type LedgerRequest struct {
+	Ledger string `json:"ledger"`
+}
+
+// LedgerRemoveRequest names one instance of a ledger to remove from its history, its state and its indexes (design 47 G
+// §587).
+type LedgerRemoveRequest struct {
+	Ledger   string `json:"ledger"`
+	Instance string `json:"instance"`
+}
+
+// LedgerRemoved is remove's answer: the instance, the operations removed and the bytes the history held less after it;
+// an instance the ledger does not hold answers 0 and 0, so a removal said twice changes nothing.
+type LedgerRemoved struct {
+	Instance   string `json:"instance"`
+	Operations uint64 `json:"operations"`
+	Bytes      uint64 `json:"bytes"`
+}
+
+// Repaired is the answer of rebuild, reindex and snapshot: how many instances (or index entries) it wrote.
+type Repaired struct {
+	Written int `json:"written"`
+}
+
+// InstanceLag is one instance whose state or snapshot is behind its history: the sequences each holds.
+type InstanceLag struct {
+	Instance string `json:"instance"`
+	History  uint64 `json:"history"`
+	State    uint64 `json:"state"`
+	Snapshot uint64 `json:"snapshot"`
+}
+
+// IndexLag is how far one declared index is behind the history.
+type IndexLag struct {
+	Index  string `json:"index"`
+	Behind uint64 `json:"behind"`
+}
+
+// Lagged is lag's answer: every instance and index behind its history; none when nothing is behind.
+type Lagged struct {
+	Instances []InstanceLag `json:"instances,omitempty"`
+	Indexes   []IndexLag    `json:"indexes,omitempty"`
+}

go/buscalls/buscalls_test.go

@@ -0,0 +1,21 @@
+package buscalls
+
+import (
+	"encoding/json"
+	"testing"
+)
+
+// A-42: stream.publish is a method of its own, beside read and fill, and its request and answer keep their field names.
+func TestStreamPublishIsAMethodWithItsShapes(t *testing.T) {
+	if StreamPublish != "mesh/stream.publish" || StreamPublish == StreamRead || StreamPublish == StreamFill {
+		t.Fatalf("method %q", StreamPublish)
+	}
+	b, _ := json.Marshal(StreamPublishRequest{Stream: "events", Event: "scrub.requested", Body: json.RawMessage(`{"a":1}`), ID: "x"})
+	if string(b) != `{"stream":"events","event":"scrub.requested","body":{"a":1},"id":"x"}` {
+		t.Errorf("request %s", b)
+	}
+	a, _ := json.Marshal(StreamPublished{Sequence: 7})
+	if string(a) != `{"sequence":7}` {
+		t.Errorf("answer %s", a)
+	}
+}

go/buscalls/seatchunks.go

@@ -0,0 +1,155 @@
+package buscalls
+
+import (
+	"encoding/json"
+	"errors"
+	"fmt"
+	"io"
+	"strconv"
+	"time"
+
+	"github.com/nats-io/nats.go"
+)
+
+// SeatChunks is the send of one seat verb's answer file in chunks (design 47 G §681, A-64, A-139), a verb whose seat
+// definition says `chunks: true`: the holder's process sends the nth chunk on mesh.seat.<seat>.chunk.<verb>.<call>.<n>,
+// and the caller acknowledges it on mesh.seat.<seat>.ack.<verb>.<call>.<n> within SeatAckWithin before the next is sent.
+// `call` is the 128 random bits the caller chose. The holder sends with it and the caller receives with it: one form.
+type SeatChunks struct {
+	Seat, Verb, Call string
+}
+
+// SeatChunkBytes is at most what one chunk carries: 512 KiB.
+const SeatChunkBytes = 512 << 10
+
+// SeatAckWithin is how long the holder waits for a chunk's acknowledgement, and so how long a caller waits for the next chunk.
+const SeatAckWithin = 30 * time.Second
+
+// SeatChunk is the body of one chunk: its number from 1, how many there are, and its bytes.
+type SeatChunk struct {
+	N    int64  `json:"n"`
+	Of   int64  `json:"of"`
+	Data []byte `json:"data"`
+}
+
+// Chunk is the subject of the nth chunk.
+func (c SeatChunks) Chunk(n int64) string {
+	return "mesh.seat." + c.Seat + ".chunk." + c.Verb + "." + c.Call + "." + strconv.FormatInt(n, 10)
+}
+
+// Ack is the subject the nth chunk is acknowledged on.
+func (c SeatChunks) Ack(n int64) string {
+	return "mesh.seat." + c.Seat + ".ack." + c.Verb + "." + c.Call + "." + strconv.FormatInt(n, 10)
+}
+
+// Chunks is every chunk subject of this call: what a caller subscribes to before it asks the verb.
+func (c SeatChunks) Chunks() string {
+	return "mesh.seat." + c.Seat + ".chunk." + c.Verb + "." + c.Call + ".*"
+}
+
+// SeatAcks is every acknowledgement of a verb's sends: what the holder subscribes to.
+func SeatAcks(seat, verb string) string {
+	return "mesh.seat." + seat + ".ack." + verb + ".*.*"
+}
+
+// ErrSeatChunkMissed is a chunk that did not come within its bound: the holder ended the send.
+var ErrSeatChunkMissed = errors.New("a chunk did not come within its bound, so the send ended")
+
+// Receive reads `of` chunks in order, writes each one's bytes to w and acknowledges it before the next is sent. next
+// yields the subject and body of the next chunk heard on Chunks(), or ErrSeatChunkMissed at its bound (SeatAckWithin);
+// ack publishes on a subject. A chunk out of order, of another count or on another subject ends the receive, and so the
+// send, since it is never acknowledged. It answers the bytes written.
+func (c SeatChunks) Receive(of int64, next func() (subject string, body []byte, err error), ack func(subject string) error, w io.Writer) (int64, error) {
+	var written int64
+	for n := int64(1); n <= of; n++ {
+		subject, body, err := next()
+		if err != nil {
+			return written, fmt.Errorf("chunk %d of %d: %w", n, of, err)
+		}
+		if subject != c.Chunk(n) {
+			return written, fmt.Errorf("chunk %d of %d came on %s, not %s", n, of, subject, c.Chunk(n))
+		}
+		var ch SeatChunk
+		if err := json.Unmarshal(body, &ch); err != nil {
+			return written, fmt.Errorf("chunk %d of %d does not read: %w", n, of, err)
+		}
+		if ch.N != n || ch.Of != of {
+			return written, fmt.Errorf("chunk %d of %d says it is %d of %d", n, of, ch.N, ch.Of)
+		}
+		k, err := w.Write(ch.Data)
+		written += int64(k)
+		if err != nil {
+			return written, fmt.Errorf("chunk %d of %d cannot be written: %w", n, of, err)
+		}
+		if err := ack(c.Ack(n)); err != nil {
+			return written, fmt.Errorf("chunk %d of %d cannot be acknowledged: %w", n, of, err)
+		}
+	}
+	return written, nil
+}
+
+// ChunkLine is the core connection as a send of chunks reaches it, which a *nats.Conn is: a chunk is published on its subject and
+// kept on no stream, and the acknowledgements are subscribed to, since the caller asks each as a request.
+type ChunkLine interface {
+	Publish(subject string, data []byte) error
+	Subscribe(subject string, cb nats.MsgHandler) (*nats.Subscription, error)
+}
+
+// Send sends body in chunks of at most SeatChunkBytes, the holder's side of Receive (design 47 G §681, A-139, A-237): it subscribes
+// to the verb's acknowledgements (SeatAcks), answers each as the request it is, publishes the nth chunk on Chunk(n) only once the
+// n-1th is acknowledged on Ack(n-1), and ends the subscription when the send ends. An acknowledgement that does not come within
+// `within` (SeatAckWithin where the caller has no other bound) ends the send with ErrSeatChunkMissed, and logf says where. Another
+// call's acknowledgements are skipped. It blocks until the send ends, so a verb answers its chunk count first and runs it after.
+func (c SeatChunks) Send(line ChunkLine, body []byte, within time.Duration, logf func(string, ...any)) error {
+	if logf == nil {
+		logf = func(string, ...any) {}
+	}
+	acks := make(chan string, 1)
+	sub, err := line.Subscribe(SeatAcks(c.Seat, c.Verb), func(m *nats.Msg) {
+		if m.Reply != "" {
+			_ = m.Respond([]byte("{}"))
+		}
+		select {
+		case acks <- m.Subject:
+		default:
+		}
+	})
+	if err != nil {
+		return fmt.Errorf("the acknowledgements cannot be heard, so no chunk is sent: %w", err)
+	}
+	defer func() { _ = sub.Unsubscribe() }()
+	total := int64((len(body) + SeatChunkBytes - 1) / SeatChunkBytes)
+	for n := int64(1); n <= total; n++ {
+		from := (n - 1) * SeatChunkBytes
+		to := min(int64(len(body)), from+SeatChunkBytes)
+		data, err := json.Marshal(SeatChunk{N: n, Of: total, Data: body[from:to]})
+		if err != nil {
+			return err
+		}
+		if err := line.Publish(c.Chunk(n), data); err != nil {
+			logf("the send %s of %s ends at chunk %d of %d: %v", c.Call, c.Verb, n, total, err)
+			return fmt.Errorf("chunk %d of %d: %w", n, total, err)
+		}
+		if !c.acknowledged(acks, c.Ack(n), within) {
+			logf("the send %s of %s ends at chunk %d of %d: no acknowledgement within %s", c.Call, c.Verb, n, total, within)
+			return fmt.Errorf("chunk %d of %d: %w", n, total, ErrSeatChunkMissed)
+		}
+	}
+	return nil
+}
+
+// acknowledged waits within for the acknowledgement on subject, skipping another call's.
+func (c SeatChunks) acknowledged(acks <-chan string, subject string, within time.Duration) bool {
+	timer := time.NewTimer(within)
+	defer timer.Stop()
+	for {
+		select {
+		case got := <-acks:
+			if got == subject {
+				return true
+			}
+		case <-timer.C:
+			return false
+		}
+	}
+}

go/buscalls/seatchunks_test.go

@@ -0,0 +1,72 @@
+package buscalls
+
+import (
+	"bytes"
+	"encoding/json"
+	"errors"
+	"strings"
+	"testing"
+)
+
+// TestSeatChunksReceive: the chunks of a send are written in order and each acknowledged before the next; a missed,
+// misplaced or miscounted chunk ends the receive unacknowledged (design 47 G §681, A-139).
+func TestSeatChunksReceive(t *testing.T) {
+	c := SeatChunks{Seat: "mesh-broker", Verb: "snapshot-get", Call: "0123456789abcdef0123456789abcdef"}
+	if c.Chunk(2) != "mesh.seat.mesh-broker.chunk.snapshot-get.0123456789abcdef0123456789abcdef.2" ||
+		c.Ack(2) != "mesh.seat.mesh-broker.ack.snapshot-get.0123456789abcdef0123456789abcdef.2" ||
+		c.Chunks() != "mesh.seat.mesh-broker.chunk.snapshot-get.0123456789abcdef0123456789abcdef.*" ||
+		SeatAcks("mesh-broker", "snapshot-get") != "mesh.seat.mesh-broker.ack.snapshot-get.*.*" {
+		t.Fatalf("subjects: %s %s %s", c.Chunk(2), c.Ack(2), c.Chunks())
+	}
+	type sent struct {
+		subject string
+		body    SeatChunk
+		missed  bool
+	}
+	good := []sent{{subject: c.Chunk(1), body: SeatChunk{N: 1, Of: 3, Data: []byte("ab")}},
+		{subject: c.Chunk(2), body: SeatChunk{N: 2, Of: 3, Data: []byte("cd")}},
+		{subject: c.Chunk(3), body: SeatChunk{N: 3, Of: 3, Data: []byte("e")}}}
+	for _, tc := range []struct {
+		name  string
+		sends []sent
+		want  string
+		acks  int
+		err   string
+	}{
+		{name: "three chunks", sends: good, want: "abcde", acks: 3},
+		{name: "a missed chunk", sends: append(good[:1:1], sent{missed: true}), want: "ab", acks: 1, err: "chunk 2 of 3"},
+		{name: "out of order", sends: []sent{good[1]}, acks: 0, err: "came on"},
+		{name: "another count", sends: []sent{{subject: c.Chunk(1), body: SeatChunk{N: 1, Of: 2, Data: []byte("x")}}}, err: "says it is 1 of 2"},
+	} {
+		t.Run(tc.name, func(t *testing.T) {
+			i, acks := 0, 0
+			next := func() (string, []byte, error) {
+				if i >= len(tc.sends) || tc.sends[i].missed {
+					return "", nil, ErrSeatChunkMissed
+				}
+				s := tc.sends[i]
+				i++
+				body, _ := json.Marshal(s.body)
+				return s.subject, body, nil
+			}
+			ack := func(subject string) error {
+				acks++
+				if subject != c.Ack(int64(acks)) {
+					t.Fatalf("ack %d on %s", acks, subject)
+				}
+				return nil
+			}
+			var out bytes.Buffer
+			n, err := c.Receive(3, next, ack, &out)
+			if tc.err == "" && err != nil || tc.err != "" && (err == nil || !strings.Contains(err.Error(), tc.err)) {
+				t.Fatalf("err %v, want %q", err, tc.err)
+			}
+			if tc.name == "a missed chunk" && !errors.Is(err, ErrSeatChunkMissed) {
+				t.Fatalf("a missed chunk is not ErrSeatChunkMissed: %v", err)
+			}
+			if out.String() != tc.want || n != int64(len(tc.want)) || acks != tc.acks {
+				t.Fatalf("wrote %q (%d), %d acks; want %q, %d acks", out.String(), n, acks, tc.want, tc.acks)
+			}
+		})
+	}
+}

go/buscalls/seatsend_test.go

@@ -0,0 +1,94 @@
+package buscalls
+
+import (
+	"bytes"
+	"encoding/json"
+	"strings"
+	"sync"
+	"testing"
+	"time"
+
+	"github.com/nats-io/nats.go"
+)
+
+// lineMem is a core connection in memory: what Send publishes is kept, and when ackOf says so the chunk is acknowledged as the
+// caller does, with a request on the ack subject, whose reply Send must give.
+type lineMem struct {
+	mu      sync.Mutex
+	handler nats.MsgHandler
+	subject string
+	chunks  map[string][]byte
+	order   []string
+	ackOf   func(n int64) (string, bool)
+}
+
+func (l *lineMem) Subscribe(subject string, cb nats.MsgHandler) (*nats.Subscription, error) {
+	l.mu.Lock()
+	defer l.mu.Unlock()
+	l.handler, l.subject = cb, subject
+	return nil, nil
+}
+
+func (l *lineMem) Publish(subject string, data []byte) error {
+	l.mu.Lock()
+	l.chunks[subject] = data
+	l.order = append(l.order, subject)
+	h := l.handler
+	l.mu.Unlock()
+	var c SeatChunk
+	_ = json.Unmarshal(data, &c)
+	if sub, ok := l.ackOf(c.N); ok {
+		go h(&nats.Msg{Subject: sub, Reply: "_INBOX.x", Sub: nil})
+	}
+	return nil
+}
+
+// TestSeatChunksSend: the bytes go in chunks of at most SeatChunkBytes, each published only after the one before is
+// acknowledged, and the receive of the same form reads them back; an acknowledgement missed or of another call ends the
+// send (design 47 G §681, A-237, A-139).
+func TestSeatChunksSend(t *testing.T) {
+	c := SeatChunks{Seat: "mesh-catalog", Verb: "input", Call: "0123456789abcdef"}
+	body := bytes.Repeat([]byte("x"), 2*SeatChunkBytes+5)
+	for _, tc := range []struct {
+		name  string
+		ackOf func(int64) (string, bool)
+		err   string
+		sent  int
+	}{
+		{name: "every chunk acknowledged", ackOf: func(n int64) (string, bool) { return c.Ack(n), true }, sent: 3},
+		{name: "no acknowledgement", ackOf: func(int64) (string, bool) { return "", false }, err: "chunk 1 of 3", sent: 1},
+		{name: "another call's acknowledgement", ackOf: func(n int64) (string, bool) {
+			return SeatChunks{Seat: "mesh-catalog", Verb: "input", Call: "fedcba9876543210"}.Ack(n), true
+		}, err: "chunk 1 of 3", sent: 1},
+	} {
+		t.Run(tc.name, func(t *testing.T) {
+			l := &lineMem{chunks: map[string][]byte{}, ackOf: tc.ackOf}
+			err := c.Send(l, body, time.Millisecond*50, func(string, ...any) {})
+			if tc.err == "" && err != nil || tc.err != "" && (err == nil || !strings.Contains(err.Error(), tc.err)) {
+				t.Fatalf("err %v, want %q", err, tc.err)
+			}
+			if len(l.order) != tc.sent {
+				t.Fatalf("%d chunks sent, want %d", len(l.order), tc.sent)
+			}
+			if l.subject != SeatAcks("mesh-catalog", "input") {
+				t.Fatalf("acknowledgements heard on %q", l.subject)
+			}
+			if tc.err != "" {
+				return
+			}
+			var got bytes.Buffer
+			i := 0
+			_, err = c.Receive(3, func() (string, []byte, error) {
+				s := l.order[i]
+				i++
+				return s, l.chunks[s], nil
+			}, func(string) error { return nil }, &got)
+			if err != nil || !bytes.Equal(got.Bytes(), body) {
+				t.Fatalf("received %d bytes, %v", got.Len(), err)
+			}
+		})
+	}
+	if err := c.Send(&lineMem{chunks: map[string][]byte{}}, nil, time.Second, nil); err != nil {
+		t.Errorf("no bytes: %v", err)
+	}
+}