Tests put back the package state they set, so a loaded check machine trips no leaked bound

The check of release sdk1 failed on TestStatePutWritesAKeyWhole: TestACallIsAskedAgainOnlyWhenItReachedNoOne
left busretry's Bound at 50 ms, and on a loaded machine the state test's first pause overran it. Second failure
of the kind "tests leave package-level state set".

Quick fix: restore busretry's waits in the one test and lengthen the state test's bound.
Thorough fix (chosen, the kind met twice): busretry.Waits sets the waits and returns their restore, used as
t.Cleanup(busretry.Waits(...)) by every test that sets them, each with a bound of seconds where it waits to
succeed; and servesAlone gives every test that serves its own runtime channel and Served, put back after it,
instead of tests clearing the channel an earlier one left. A scan of every test assignment to a package-level
variable found no other unrestored one.

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

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/asks/asks.go

@@ -571,3 +571,8 @@ type ProofAnswer struct {
 	Accepted bool   `json:"accepted"`
 	Words    string `json:"words"`
 }
+
+// EngineAsker is the asker name a node's engine asks the operator under (novox/hq ADR 0563 §3, which changes ADR 0259
+// §2 to admit a node's engine as an asker): `node-engine-<node>`, the last token of the by-caller subjects granted to that
+// node's engine account alone, so no engine acts on another node's warrant.
+func EngineAsker(node string) string { return "node-engine-" + node }

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 +1,7 @@
 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.
+// CapacitySetting is the build modules' setting of the node's build capacity (novox/hq ADR 0525 §5, ADR 0567 §12): how
+// many asks the node takes at once, an integer config value set on each node's layer of mesh-config. No repository names
+// a node: each build module declares it with the default 0, which pulls nothing, and the controller (or mesh-config)
+// lays the node's value 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/doc.go

@@ -0,0 +1,5 @@
+// Package buildstep is the contract of a build step every delivery part reads (novox/hq ADR 0593 §1): a step's id, the
+// fetch request, a step a previous process left running and its end, a failure's words, a module tree's shape, the
+// capacity setting and the launchers' names. The runner the build modules share is the Go build module's own package
+// (mesh-catalog modules/mesh-build-go/buildstep), which imports this one.
+package buildstep

go/buildstep/failure.go

@@ -0,0 +1,141 @@
+package buildstep
+
+import (
+	"fmt"
+	"strings"
+
+	"git.novox.be/novox/mesh-sdk/go/sdkversion"
+)
+
+// Failure is one test that failed, or a package or file that failed with no test to name (a build that failed, a test
+// program that panicked, a test file that did not load). The JSON names are the ones mesh-build-go and the checker have
+// always used; File is new and an older reader ignores it.
+type Failure struct {
+	// Package is the Go package's import path, or the TypeScript package's directory in the workspace.
+	Package string `json:"package"`
+	// Test names the failing test, or the tests that were running when the program stopped; "" when none can be named.
+	Test string `json:"test,omitempty"`
+	// File is where the failing test is (a Go test's file and line is in its Cause; node names the test's file:line:col).
+	File string `json:"file,omitempty"`
+	// Cause is the one line that says why: the assertion's or the error's first line, a "panic:" line, a build's first
+	// error, or words saying how the program stopped. **Never empty, and never a passing line** (PassingLine).
+	Cause string `json:"cause,omitempty"`
+	// Output is the failing test's own output, its last lines up to OutputBytes, Cause first: an older checker reads
+	// only its first line.
+	Output string `json:"output,omitempty"`
+}
+
+// OutputBytes is the most a failure keeps of its output, and LineBytes the most of one line: four kilobytes holds a long
+// assertion message and stays far under a bus message's or a verdict's bound.
+const (
+	OutputBytes = 4096
+	LineBytes   = 1024
+)
+
+// By names a build module and the SDK it was built with, for a result's "by": the checker names it when a failure hides
+// its cause ("the build module hid the failure (<by>)").
+func By(module string) string {
+	return module + " with mesh-sdk " + sdkversion.Version()
+}
+
+// PassingLine says a line is a test runner's word for a test or a package that passed: node's '✔', TAP's "ok N" (at any
+// indent), go test's "ok  \t<pkg>", "PASS" and "--- PASS". A line of a test's own that starts "ok " is none of these. Such a line is never a failure's cause, nor part of a failure's output.
+func PassingLine(l string) bool {
+	if strings.HasPrefix(l, "ok  \t") { // go test's package line, at column 0
+		return true
+	}
+	t := strings.TrimSpace(l)
+	switch {
+	case t == "PASS", strings.HasPrefix(t, "✔"), strings.HasPrefix(t, "--- PASS"):
+		return true
+	}
+	return tapOk(t)
+}
+
+// Hidden says how a failure hides why it failed, or "" when it does not: it has no cause, or its cause is a passing line.
+// The checker says it loudly (issue 1901): a build module that sends such a failure does not keep the contract.
+func Hidden(f Failure) string {
+	c := strings.TrimSpace(f.Cause)
+	switch {
+	case c == "":
+		return "it sent no cause"
+	case PassingLine(c):
+		return fmt.Sprintf("its cause is a passing line (%q)", CutLine(c))
+	}
+	return ""
+}
+
+// Clip joins the last lines of a failure's output that fit OutputBytes, each cut to LineBytes, and says how many earlier
+// lines it left out. **Its first line is the cause**, put ahead when the kept lines do not start with it, or, with no
+// cause and lines left out, the first non-empty line, then the marker: an older checker reads only the first line.
+// Passing lines are dropped.
+func Clip(lines []string, cause string) string {
+	own := make([]string, 0, len(lines))
+	for _, l := range lines {
+		if !PassingLine(l) {
+			own = append(own, l)
+		}
+	}
+	lines = own
+	size, from := 0, len(lines)
+	for from > 0 {
+		n := len(CutLine(lines[from-1])) + 1
+		if size+n > OutputBytes && from < len(lines) {
+			break
+		}
+		size += n
+		from--
+	}
+	kept := make([]string, 0, len(lines)-from+2)
+	head := strings.TrimSpace(cause)
+	for i := 0; head == "" && i < from; i++ {
+		head = strings.TrimSpace(lines[i])
+	}
+	if head != "" && (from > 0 || len(lines) == 0 || strings.TrimSpace(lines[from]) != head) {
+		kept = append(kept, CutLine(head))
+	}
+	if from > 0 {
+		kept = append(kept, fmt.Sprintf("... (%d earlier lines)", from))
+	}
+	for _, l := range lines[from:] {
+		kept = append(kept, CutLine(l))
+	}
+	return strings.Join(kept, "\n")
+}
+
+// CutLine cuts a line to LineBytes, on a character boundary.
+func CutLine(l string) string {
+	if len(l) <= LineBytes {
+		return l
+	}
+	return strings.ToValidUTF8(l[:LineBytes], "") + "..."
+}
+
+// ConsoleFailure is the failure of a command that is no test runner (go vet, gofmt, tsc, a build script): its cause is the
+// first line that names an error (tsc's "error TS", go vet's "file.go:12:3: ..."), else the first line that is not a
+// heading ("# <package>", npm's "> script"), and its output the command's lines without passing ones.
+func ConsoleFailure(pkg, test, out string) Failure {
+	var lines []string
+	for _, l := range strings.Split(strings.ReplaceAll(stripANSI(out), "\r\n", "\n"), "\n") {
+		if t := strings.TrimSpace(l); t != "" && !PassingLine(t) {
+			lines = append(lines, strings.TrimRight(l, " \t"))
+		}
+	}
+	cause := ""
+	for _, l := range lines {
+		if t := strings.TrimSpace(l); strings.Contains(t, "error") || strings.Contains(t, "Error") || goPosition.MatchString(t) {
+			cause = t
+			break
+		}
+	}
+	for _, l := range lines {
+		if t := strings.TrimSpace(l); cause == "" && !strings.HasPrefix(t, "# ") && !strings.HasPrefix(t, "> ") && !strings.HasPrefix(t, "npm ") {
+			cause = t
+		}
+	}
+	if cause == "" {
+		cause = test + " failed and wrote nothing that says why"
+	}
+	cause = CutLine(cause)
+	return Failure{Package: pkg, Test: test, Cause: cause, Output: Clip(lines, cause)}
+}

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/helpers.go

@@ -0,0 +1,19 @@
+package buildstep
+
+import (
+	"regexp"
+	"strings"
+)
+
+// goPosition matches a line that starts with a Go file's position, as go vet and the compiler write an error.
+var goPosition = regexp.MustCompile(`^\S+\.go:\d+(:\d+)?: `)
+
+var ansiEscape = regexp.MustCompile("\x1b\\[[0-9;]*m")
+
+func stripANSI(s string) string { return ansiEscape.ReplaceAllString(s, "") }
+
+// tapOk says a line is a passing test's "ok N - name", indented or not.
+func tapOk(l string) bool {
+	rest, ok := strings.CutPrefix(strings.TrimSpace(l), "ok ")
+	return ok && rest != "" && rest[0] >= '0' && rest[0] <= '9'
+}

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.go

@@ -1,24 +1,14 @@
 package buildstep
 
-import "strings"
+import "git.novox.be/novox/mesh-sdk/go/catalogue"
 
 // LauncherSuffix is what a TypeScript entrypoint's launcher is called beside it: index.js is started as
 // index.serve.mjs (novox/hq ADR 0193), an ES module by its own extension whatever the bundle's package.json says.
-const LauncherSuffix = ".serve.mjs"
+const LauncherSuffix = catalogue.LauncherSuffix
 
-// Launchers are the launchers a bundle's build writes, by entrypoint, relative to the bundle's root: for TypeScript
-// every entrypoint `x.js` is started by `x.serve.mjs` beside it; an entrypoint that is not JavaScript and every other
-// language, whose build is already executable, get none. The one rule mesh-build-node, build-agent and the controller
-// share (R4e), so the name a build writes is the name a reader expects.
+// Launchers are the launchers a bundle's build writes, by entrypoint, relative to the bundle's root
+// (catalogue.Launchers): the one rule mesh-build-node, build-agent, the controller and a node taking in a build share
+// (R4e, issue 1126), so the name a build writes is the name a reader expects.
 func Launchers(language string, entrypoints []string) map[string]string {
-	out := map[string]string{}
-	if language != "typescript" {
-		return out
-	}
-	for _, entry := range entrypoints {
-		if strings.HasSuffix(entry, ".js") {
-			out[entry] = strings.TrimSuffix(entry, ".js") + LauncherSuffix
-		}
-	}
-	return out
+	return catalogue.Launchers(language, entrypoints)
 }

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

@@ -2,9 +2,12 @@ package buildstep
 
 import (
 	"fmt"
+	"maps"
 	"path"
 	"regexp"
 	"strings"
+
+	"git.novox.be/novox/mesh-sdk/go/delivery"
 )
 
 var (
@@ -27,6 +30,10 @@ type FetchRequest struct {
 	Base       string   `json:"base,omitempty"`
 	Dir        string   `json:"dir,omitempty"`
 	Paths      []string `json:"paths,omitempty"`
+	// Packages are the version of each mesh package the build or the check builds against (delivery.StepAsk.Packages,
+	// novox/hq ADR 0573 §2, §4): the build module writes each into the workspace's go.mod and go.sum, whatever version
+	// the repository names, checksum-verified, and names them in its log.
+	Packages delivery.PackageVersions `json:"packages,omitempty"`
 }
 
 // FetchRequestProperties are the JSON schema properties of FetchRequest's dir and paths, for a fetch tool's Input.
@@ -35,6 +42,8 @@ func FetchRequestProperties() 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"},
+		"packages": map[string]any{"type": "object", "additionalProperties": map[string]any{"type": "string"},
+			"description": "optional: the version (a full commit) of each mesh package to build against, by its module path, whatever version go.mod names (novox/hq ADR 0573 §2); the builder and the checker fill it"},
 	}
 }
 
@@ -49,6 +58,12 @@ func (r FetchRequest) Args() map[string]any {
 	if len(r.Paths) > 0 {
 		args["paths"] = append([]string(nil), r.Paths...)
 	}
+	if len(r.Packages) > 0 {
+		args["packages"] = map[string]any{}
+		for p, v := range r.Packages {
+			args["packages"].(map[string]any)[p] = v
+		}
+	}
 	return args
 }
 
@@ -78,9 +93,42 @@ func ParseFetchRequest(args map[string]any) (FetchRequest, error) {
 	default:
 		return FetchRequest{}, fmt.Errorf("paths is a list of strings")
 	}
+	packages, err := PackagesArg(args["packages"])
+	if err != nil {
+		return FetchRequest{}, err
+	}
+	r.Packages = packages
 	return r, r.Check()
 }
 
+// PackagesArg reads a tool call's packages argument, an object of strings (as JSON gives it) or the map an ask gives;
+// nil for none.
+func PackagesArg(v any) (delivery.PackageVersions, error) {
+	out := delivery.PackageVersions{}
+	switch v := v.(type) {
+	case nil:
+		return nil, nil
+	case delivery.PackageVersions:
+		maps.Copy(out, v)
+	case map[string]string:
+		maps.Copy(out, v)
+	case map[string]any:
+		for p, version := range v {
+			s, ok := version.(string)
+			if !ok {
+				return nil, fmt.Errorf("packages is an object of versions (strings), by package")
+			}
+			out[p] = s
+		}
+	default:
+		return nil, fmt.Errorf("packages is an object of versions (strings), by package")
+	}
+	if len(out) == 0 {
+		return nil, nil
+	}
+	return out, out.Check()
+}
+
 // Check is what ParseFetchRequest refuses.
 func (r FetchRequest) Check() error {
 	if !requestRepositoryOK.MatchString(r.Repository) || strings.Contains(r.Repository, "..") {

go/buildstep/request_test.go

@@ -10,11 +10,15 @@ import (
 // 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) {
+	// And the versions of the mesh packages to build against (novox/hq ADR 0573 §2; issue 1585 S4).
 	req := FetchRequest{Repository: "novox/mesh-sdk", Commit: strings.Repeat("a", 40), Ref: "refs/pull/7/head",
-		Dir: ".", Paths: []string{"package.json", "src"}}
+		Dir: ".", Paths: []string{"package.json", "src"}, Packages: map[string]string{"git.novox.be/novox/mesh-sdk/go": strings.Repeat("d", 40)}}
 	args := req.Args()
-	// A tool call's arguments arrive as JSON: lists of any.
+	// A tool call's arguments arrive as JSON: lists of any, objects of any.
 	args["paths"] = []any{"package.json", "src"}
+	if p, ok := args["packages"].(map[string]any); !ok || p["git.novox.be/novox/mesh-sdk/go"] != strings.Repeat("d", 40) {
+		t.Fatalf("the packages are not in the call's arguments: %v", args["packages"])
+	}
 	got, err := ParseFetchRequest(args)
 	if err != nil {
 		t.Fatal(err)
@@ -42,6 +46,9 @@ func TestAFetchRequestCarriesTheNamedPathsThroughTheToolCall(t *testing.T) {
 		{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"},
+		{map[string]any{"packages": map[string]any{"git.novox.be/novox/mesh-sdk/go": "v0.1.7"}}, "no full commit"},
+		{map[string]any{"packages": map[string]any{"a b": strings.Repeat("d", 40)}}, "no module path"},
+		{map[string]any{"packages": []any{"x"}}, "packages is an object"},
 	} {
 		args := map[string]any{}
 		for k, v := range ok {

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

@@ -5,6 +5,8 @@ import (
 	"encoding/json"
 	"errors"
 	"fmt"
+	"os"
+	"strconv"
 	"strings"
 	"time"
 
@@ -12,42 +14,78 @@ import (
 	"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.
+// Boot is when this process began. A step with no owner (written by an older build) started at or after it is taken
+// for this process's, which may still run it, so EndOne refuses it.
 var Boot = time.Now()
 
+// Owner is this process as a step's owner (delivery.Step.Owner): `<boot id>.<pid>.<start>`, the node's boot id
+// (/proc/sys/kernel/random/boot_id), the pid and Boot in milliseconds, base 36. The start keeps two processes apart
+// that a reboot or a pid namespace gave the same pid. A running step whose owner is another is a previous process's.
+var Owner = ownerOf(bootID, os.Getpid(), Boot)
+
+// bootID is the node's boot id as Owner holds it; noBootID when it could not be read, which EndStaleAtStart says once.
+var bootID = readBootID()
+
+const noBootID = "no-boot-id"
+
+func ownerOf(bootID string, pid int, start time.Time) string {
+	return bootID + "." + strconv.Itoa(pid) + "." + strconv.FormatInt(start.UnixMilli(), 36)
+}
+
+// readBootID is the node's boot id, or noBootID where it cannot be read (the pid and the start then tell the processes
+// apart).
+func readBootID() string {
+	b, err := os.ReadFile("/proc/sys/kernel/random/boot_id")
+	if id := strings.TrimSpace(string(b)); err == nil && id != "" {
+		return id
+	}
+	return noBootID
+}
+
 // 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.
+// none), a write that lands only while the key is still at the revision read (KeptState.Update), and a delete of a key
+// still at the revision read; both fail 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)
+	Delete func(key string, revision uint64) error
 }
 
 // ScanOf is the Scan of a state the process keeps.
+//
+// Its Delete reads the key again and deletes it only while it is still at the revision read: the runtime's
+// mesh/state.delete takes no revision yet, so a write landing between that read and the delete (a few milliseconds) is
+// deleted with it. For a step key that is a redelivered ask begun on this node in that moment: its running key leaves
+// the steps state until its run writes its end, which its asker still reads (a watch takes puts only).
 func ScanOf(s stdio.KeptState) Scan {
-	return Scan{Keys: s.Keys, Update: s.Update, Get: func(key string) (json.RawMessage, uint64, error) {
+	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
+	}
+	return Scan{Keys: s.Keys, Update: s.Update, Get: get, Delete: func(key string, revision uint64) error {
+		_, rev, err := get(key)
+		if err != nil {
+			return err
+		}
+		if rev != revision {
+			return stdio.ErrChanged
+		}
+		return s.Delete(key)
 	}}
 }
 
 // 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.
+// A key a gone process owns is deleted, never ended (EndStale); one with no owner is ended only once the asker's bound
+// has passed (delivery.StepBound), when it is nobody's.
 func isAsk(key string, s delivery.Step) bool {
 	_, _, err := delivery.ParseAskStepKey(key)
 	return err == nil && strings.HasSuffix(s.Tool, " ask")
@@ -95,11 +133,23 @@ func endRunning(scan Scan, key string, step delivery.Step, revision uint64, why
 	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
+// EndStale ends this node's running steps that no process of this module runs any more, and answers their ids. Only keys
+// of node are read; a value that is no step is left alone.
+//   - A hand-started step with an owner (delivery.Step.Owner) that is not this process (Owner) is ended failed with
+//     RestartReason at once, whatever its age: its process is gone and nothing redelivers it, so nothing else would
+//     write its end (issue 1890, note 21).
+//   - A pulled ask's step with an owner that is not this process is deleted, not ended (novox/hq ADR 0525 §6): the
+//     stream redelivers an ask whose node stopped (the puller neither ends nor acknowledges one at its stop), and its
+//     asker takes the first end it reads, so an end written here would fail a check the redelivery would still run. Its
+//     asker's watch takes puts only and keeps waiting for the redelivery's key, its bound the backstop; the stale running
+//     key leaves the steps state, and with it the delivery view's and the checker's count of what runs (note 21: it
+//     held one of a build node's two slots).
+//   - A step owned by this process is left: it may run now. A redelivered ask begun on this node is owned by it.
+//   - A step with no owner (written by an older build) keeps the earlier rule: a hand-started step started before
+//     `before` (the start of this process) is ended; a pulled ask is left to the stream's redelivery (isAsk) until its
+//     start is older than delivery.StepBound, and then ended "past the step bound: its asker stopped waiting at <time>".
+//
+// Each end and delete is logged, naming the step, its owner and why. 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()
@@ -123,32 +173,59 @@ func EndStale(scan Scan, node string, before time.Time, logf func(string, ...any
 		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) {
+		why, said := staleWhy(k, step, before)
+		if why == "" {
 			continue
 		}
-		if err := endRunning(scan, k, step, rev, why); err != nil {
+		done := "ended"
+		if step.Owner != "" && isAsk(k, step) {
+			done = "deleted, left to the stream's redelivery"
+			if scan.Delete == nil {
+				err = fmt.Errorf("the steps state takes no delete")
+			} else {
+				err = scan.Delete(k, rev)
+			}
+		} else {
+			err = endRunning(scan, k, step, rev, why)
+		}
+		if 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)
+			logf("the step %s (%s, started %s) was left running and is %s: %s; %s", k, step.Tool,
+				step.Started.UTC().Format(time.RFC3339), done, why, said)
 		}
 		ended = append(ended, step.ID)
 	}
 	return ended, nil
 }
 
+// staleWhy is why a running step is ended (or, for an ask with an owner, deleted) by EndStale and what the log says of
+// its owner, or "" to leave it.
+func staleWhy(key string, step delivery.Step, before time.Time) (why, said string) {
+	switch {
+	case step.Owner == Owner:
+		return "", ""
+	case step.Owner != "":
+		return RestartReason, "its owner " + step.Owner + " is not this process " + Owner
+	case isAsk(key, step):
+		if !step.Started.Add(delivery.StepBound).Before(now()) {
+			return "", ""
+		}
+		return "past the step bound: its asker stopped waiting at " + step.Started.Add(delivery.StepBound).UTC().Format("2006-01-02T15:04:05Z"),
+			"it names no owner (an older build wrote it)"
+	case step.Started.Before(before):
+		return RestartReason, "it names no owner (an older build wrote it) and started before this process"
+	}
+	return "", ""
+}
+
 // 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.
+// refused, and so is one this process owns (Owner; for a step with no owner, one started since 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 {
@@ -178,7 +255,7 @@ func EndOne(scan Scan, node, id, why string, live func(id string) bool) (deliver
 	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)) {
+	if step.Owner == Owner || (step.Owner == "" && !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 {
@@ -191,49 +268,30 @@ func EndOne(scan Scan, node, id, why string, live func(id string) bool) (deliver
 	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
 )
 
+// StaleServed is what EndStaleAtStart waits for before it reads the steps state: the runtime serving (stdio.Served).
+// The conformance kit's left-running case (conformance.LeftRunning) hands it a closed channel, to run a module's own
+// start sweep in its test.
+var StaleServed = stdio.Served
+
 // 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`.
+// then ends this node's steps a previous process left running (EndStale), trying again when the state cannot be read
+// yet. A step names its owner, so `before` (the start of this process) matters only for a step with no owner, written
+// by an older build: such a step started before it is a previous process's. When the node's boot id cannot be read it
+// says so once: Owner then tells processes apart by their pid and start only.
 func EndStaleAtStart(ctx context.Context, scan Scan, node string, before time.Time, logf func(string, ...any)) {
 	select {
 	case <-ctx.Done():
 		return
-	case <-stdio.Served():
+	case <-StaleServed():
+	}
+	if bootID == noBootID && logf != nil {
+		logf("the boot id of %s cannot be read (/proc/sys/kernel/random/boot_id): its steps' owner is %s, told apart by pid and start only", node, Owner)
 	}
 	for attempt := 1; ; attempt++ {
 		ended, err := EndStale(scan, node, before, logf)

go/buildstep/stale_test.go

@@ -2,11 +2,13 @@ package buildstep
 
 import (
 	"encoding/json"
-	stdio "git.novox.be/novox/mesh-sdk/go"
+	"fmt"
 	"strings"
 	"testing"
 	"time"
 
+	stdio "git.novox.be/novox/mesh-sdk/go"
+
 	"git.novox.be/novox/mesh-sdk/go/delivery"
 )
 
@@ -33,6 +35,15 @@ func scanOf(k *keys, race func(key string)) Scan {
 			raw, err := delivery.EncodeStep(s[len(s)-1])
 			return raw, uint64(len(s)), err
 		},
+		Delete: func(key string, revision uint64) error {
+			k.mu.Lock()
+			defer k.mu.Unlock()
+			if uint64(len(k.puts[key])) != revision {
+				return stdio.ErrChanged
+			}
+			delete(k.puts, key)
+			return nil
+		},
 		Update: func(key string, value any, revision uint64) (uint64, error) {
 			if race != nil {
 				race(key)
@@ -48,65 +59,85 @@ func scanOf(k *keys, race func(key string)) Scan {
 	}
 }
 
-// 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.
+// 1890 and 1890/AC6: EndStale ends this node's hand-started running steps of another owner at once, whatever their age,
+// and deletes its asks of another owner (the stream redelivers them, ADR 0525 §6); of
+// the steps with no owner (an older build's), the hand-started ones left running before the process began and the asks
+// past the step bound (a younger ask is the stream's to redeliver); never a step this process owns or a key written
+// meanwhile. EndOne ends one by hand, never one this process owns or 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) {
+	gone := ownerOf("b00t", 4242, boot.Add(-time.Hour))
+	put := func(node, id, tool, state string, started time.Time, owner string) {
 		key, _ := delivery.StepKey(node, id)
-		_, _ = k.put(key, json.RawMessage(mustStep(t, delivery.Step{ID: id, Tool: tool, Node: node, State: state, Started: started})))
+		_, _ = k.put(key, json.RawMessage(mustStep(t, delivery.Step{ID: id, Tool: tool, Node: node, State: state, Started: started, Owner: owner})))
 	}
-	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))
+	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", "mjk3l9x0abcded", "check ask", delivery.StepRunning, time.Now().Add(-5*time.Minute), gone) // note 21's ghost
+	put("ace", "gone2", "build_go_test", delivery.StepRunning, boot.Add(time.Second), gone)
+	put("ace", "mine1", "check ask", delivery.StepRunning, boot.Add(-time.Hour), Owner)
+	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), gone)
+	put("g14", "other1", "build_go_fetch", delivery.StepRunning, boot.Add(-time.Hour), gone)
 	// 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))
+			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] {
+	var said []string
+	ended, err := EndStale(scan, "ace", boot, func(f string, a ...any) { said = append(said, fmt.Sprintf(f, a...)) })
+	if err != nil || len(ended) != 4 {
 		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 _, held := k.puts["ace.mjk3l9x0abcded"]; held {
+		t.Errorf("the ghost ask's key is still held: %+v", k.last("ace.mjk3l9x0abcded"))
+	}
+	for _, key := range []string{"ace.old1", "ace.gone2"} {
+		if s := k.last(key); s.State != delivery.StepFailed || s.Reason != RestartReason || s.Ended.IsZero() {
+			t.Errorf("%s = %+v", key, 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 log := strings.Join(said, "\n"); !strings.Contains(log, "ace.mjk3l9x0abcded") || !strings.Contains(log, "deleted, left to the stream's redelivery") || !strings.Contains(log, "its owner "+gone+" is not this process "+Owner) {
+		t.Errorf("the log does not name the ghost and its owner:\n%s", log)
+	}
+	for key, state := range map[string]string{"ace.mjk3l9x0abcdee": delivery.StepRunning, "ace.mine1": 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"}} {
+	// EndOne: refuses without why, a held step, one this process owns or (with no owner) started, 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"}, {"mine1", "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))
+	put("ace", "old2", "build_go_fetch", delivery.StepRunning, boot.Add(time.Second), gone)
 	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" {
+	if s := k.last("ace.old2"); s.State != delivery.StepFailed || s.Reason != "stuck for good" || s.Owner != gone {
 		t.Errorf("old2 = %+v", s)
 	}
+	if a, b := ownerOf("b", 1, boot), ownerOf("b", 1, boot.Add(time.Second)); a == b {
+		t.Errorf("two starts of one pid share the owner %q", a)
+	}
 }
 
 func mustStep(t *testing.T, s delivery.Step) []byte {

go/buildstep/step.go

@@ -1,30 +1,14 @@
 // 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).
+// (issue 1473), the fetch of one commit over SSH (issue 1474), and the failure contract of a test level with the parsers
+// of go test -json and node --test's TAP that fill it (failure.go, issue 1901; its conformance kit is package conformance).
 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
@@ -36,111 +20,3 @@ func NewID() string {
 	_, _ = 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,9 +1,7 @@
 package buildstep
 
 import (
-	"context"
 	"encoding/json"
-	"errors"
 	"sync"
 	"testing"
 	"time"
@@ -53,71 +51,6 @@ func (k *keys) waitEnd(t *testing.T) string {
 	}
 }
 
-// 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) {
@@ -137,18 +70,3 @@ func TestTwoIDsInOneMillisecondDiffer(t *testing.T) {
 		}
 	}
 }
-
-// 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 +1,15 @@
 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).
+// ModuleTree is what a merge holds of one module directory, as a build module's preview answers it (novox/hq ADR 0484
+// clause 3, as ADR 0593 §2 changes it): its git tree id, the sha256 of its module.json, the sha256 of each lock file it
+// has (go.sum, package-lock.json), and, of a module whose every artifact names its paths, each named path's git object
+// id at the commit. The indexer alone computes from them (the named tree, the fingerprint); the build module's runner
+// (mesh-build-go's buildstep.ModuleTrees) fills them.
 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"`
+	Paths    map[string]string `json:"paths,omitempty"`
+	// Packages are no longer filled (ADR 0593 §2): kept so a preview written before still decodes.
+	Packages []string `json:"packages,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/buscompose/accounts.go

@@ -0,0 +1,169 @@
+package buscompose
+
+import (
+	"encoding/json"
+	"fmt"
+	"slices"
+	"strings"
+	"time"
+)
+
+// AccountsState is the grants part's state of wanted accounts, by bus user.
+const AccountsState = "accounts"
+
+// GrantsAccounts is that state as a reader names it (`<owner>.<name>`).
+const GrantsAccounts = GrantsModule + "." + AccountsState
+
+// AccountIssuedEvent is what the vault says when it minted an account: AccountIssued, never a value or a hash.
+const AccountIssuedEvent = "account-issued"
+
+// AccountIssuedSubject is where it says it, as the runtime addresses mesh-vault's events.
+const AccountIssuedSubject = "mesh.mod." + VaultSeat + ".event." + AccountIssuedEvent
+
+// ClaimedSeat is one seat a module claims, as its runtime needs it (the controller's seatClaimed): the name, the scope (a
+// node-scoped seat's verb carries the machine) and the verbs the runtime serves for it.
+type ClaimedSeat struct {
+	Seat   string   `json:"seat"`
+	Scope  string   `json:"scope"`
+	Serves []string `json:"serves,omitempty"`
+}
+
+// WantedAccount is one key of the grants part's state `accounts`: an account the mesh needs, without its password.
+type WantedAccount struct {
+	User string `json:"user"`
+	// Kind is KindModule (KindNodeTools for the runtime, named as a module is), KindProcess or KindProvisioner.
+	Kind   Kind   `json:"kind"`
+	Node   string `json:"node"`
+	Module string `json:"module"`
+	// Process is a KindProcess account's process id.
+	Process string `json:"process,omitempty"`
+	// URL is the bus's address as that node reaches it, `nats://<host>:<port>`; Fingerprint the bus certificate's.
+	URL         string `json:"url"`
+	Fingerprint string `json:"fingerprint,omitempty"`
+	// Claims are a module's claims with the verbs each seat promises: none for a process or a provisioner client.
+	Claims []ClaimedSeat `json:"claims,omitempty"`
+	// At is when the grants part wrote the key: not compared (Same).
+	At time.Time `json:"at"`
+}
+
+// mintedKinds are the kinds of account the vault mints (ADR 0561 §1).
+var mintedKinds = []Kind{KindModule, KindNodeTools, KindProcess, KindProvisioner}
+
+// principal is the account as the composer names it.
+func (w WantedAccount) principal() Principal {
+	return Principal{Kind: w.Kind, Node: w.Node, Module: w.Module, Process: w.Process}
+}
+
+// Valid says why w is not an account the vault may mint, or nil: a kind it mints, every name a subject token, the user
+// the one the composer derives from them, and an address to reach the bus at.
+func (w WantedAccount) Valid() error {
+	if !slices.Contains(mintedKinds, w.Kind) {
+		return fmt.Errorf("%s is a %s account, which the vault never mints (ADR 0561 §4)", w.User, w.Kind)
+	}
+	for what, v := range map[string]string{"node": w.Node, "module": w.Module} {
+		if !safeSubject.MatchString(v) {
+			return fmt.Errorf("%s: the %s %q is not a name the mesh writes", w.User, what, v)
+		}
+	}
+	if w.Kind == KindProcess && !safeSubject.MatchString(w.Process) {
+		return fmt.Errorf("%s: the process %q is not a name the mesh writes", w.User, w.Process)
+	}
+	if w.Kind != KindProcess && w.Process != "" {
+		return fmt.Errorf("%s: only a process's account names a process", w.User)
+	}
+	if want := w.principal().Username(); w.User != want {
+		return fmt.Errorf("%s is not the user of a %s account of %s on %s (that is %s)", w.User, w.Kind, w.Module, w.Node, want)
+	}
+	if !strings.HasPrefix(w.URL, "nats://") || len(w.URL) == len("nats://") {
+		return fmt.Errorf("%s names no bus address (url, nats://<host>:<port>)", w.User)
+	}
+	if len(w.Claims) > 0 && w.Kind != KindModule && w.Kind != KindNodeTools {
+		return fmt.Errorf("%s: a %s account holds no seat, so it carries no claims", w.User, w.Kind)
+	}
+	return nil
+}
+
+// Same says whether two wanted accounts want the same account: every field but when it was written.
+func (w WantedAccount) Same(o WantedAccount) bool {
+	a, b := w, o
+	a.At, b.At = time.Time{}, time.Time{}
+	ra, _ := json.Marshal(a)
+	rb, _ := json.Marshal(b)
+	return string(ra) == string(rb)
+}
+
+// OwnSecret is the module's own secret the account is held in: `broker`, `broker-<process id>` or `provisioner-broker`
+// (the controller's names, ADR 0436 §2, ADR 0349 §11).
+func (w WantedAccount) OwnSecret() string {
+	switch w.Kind {
+	case KindProcess:
+		return "broker-" + w.Process
+	case KindProvisioner:
+		return "provisioner-broker"
+	}
+	return "broker"
+}
+
+// ReadWantedAccount reads the key user of the state: refused when it is not a valid wanted account of that user.
+func ReadWantedAccount(user string, raw []byte) (WantedAccount, error) {
+	var w WantedAccount
+	if err := json.Unmarshal(raw, &w); err != nil {
+		return WantedAccount{}, fmt.Errorf("%s %s is not a wanted account: %w", GrantsAccounts, user, err)
+	}
+	if w.User != user {
+		return WantedAccount{}, fmt.Errorf("%s %s names the user %q", GrantsAccounts, user, w.User)
+	}
+	return w, w.Valid()
+}
+
+// AccountIssued is the vault's account-issued: which account it minted, and its generation. Never a value or a hash.
+type AccountIssued struct {
+	User       string    `json:"user"`
+	Kind       Kind      `json:"kind"`
+	Node       string    `json:"node"`
+	Module     string    `json:"module"`
+	Process    string    `json:"process,omitempty"`
+	Generation int       `json:"generation"`
+	At         time.Time `json:"at"`
+}
+
+// HeldCredential is the value the account's holder reads, exactly as the controller builds it today (issueWith,
+// sealProcess and sealProvisionerClient): a module's `{url, fingerprint, node, module, user, password, claims}`, a
+// process's without claims, a provisioner client's without module or claims; an empty fingerprint or claims left out.
+func HeldCredential(w WantedAccount, password string) ([]byte, error) {
+	if err := w.Valid(); err != nil {
+		return nil, err
+	}
+	if password == "" {
+		return nil, fmt.Errorf("%s: an account is held with its password", w.User)
+	}
+	switch w.Kind {
+	case KindProcess:
+		return json.Marshal(struct {
+			URL         string `json:"url"`
+			Fingerprint string `json:"fingerprint,omitempty"`
+			Node        string `json:"node"`
+			Module      string `json:"module"`
+			User        string `json:"user"`
+			Password    string `json:"password"`
+		}{URL: w.URL, Fingerprint: w.Fingerprint, Node: w.Node, Module: w.Module, User: w.User, Password: password})
+	case KindProvisioner:
+		return json.Marshal(struct {
+			URL         string `json:"url"`
+			Fingerprint string `json:"fingerprint,omitempty"`
+			Node        string `json:"node"`
+			User        string `json:"user"`
+			Password    string `json:"password"`
+		}{URL: w.URL, Fingerprint: w.Fingerprint, Node: w.Node, User: w.User, Password: password})
+	}
+	return json.Marshal(struct {
+		URL         string        `json:"url"`
+		Fingerprint string        `json:"fingerprint,omitempty"`
+		Node        string        `json:"node"`
+		Module      string        `json:"module"`
+		User        string        `json:"user"`
+		Password    string        `json:"password"`
+		Claims      []ClaimedSeat `json:"claims,omitempty"`
+	}{URL: w.URL, Fingerprint: w.Fingerprint, Node: w.Node, Module: w.Module, User: w.User, Password: password,
+		Claims: w.Claims})
+}

go/buscompose/agreement.go

@@ -1,125 +0,0 @@
-package buscompose
-
-import (
-	"fmt"
-	"sort"
-	"strings"
-)
-
-// Do the emitters and the consumers of a catalogue agree?
-//
-// **The check that was missing** (novox/hq 04-ISSUES/127). Every manifest was individually
-// well-formed and every derivation individually correct, and no cross-module subscription in the
-// mesh matched anything: a consumer's declaration derived into a namespace nobody publishes to.
-// Nothing failed, because a subscription that matches nothing is not an error — it is silence.
-//
-// The comparison has to be over the whole catalogue, because the two halves live in different
-// manifests, and it cannot simply demand that every consumed event have a live emitter: a module
-// may be installed long before the one whose events it wants. So the rule is narrower and still
-// catches this: **where the emitter is present, it must emit what the consumer asked for.**
-
-// AConsumer is one module's interest in another's events, as this check needs it.
-type AConsumer struct {
-	Module   string
-	Consumes []string
-}
-
-// AnEmitter is one module's events.
-type AnEmitter struct {
-	Module string
-	Emits  []string
-}
-
-// Disagreements are the consumed events whose emitter is in the catalogue and does not emit them.
-//
-// Returned as sentences rather than as structs: every one of them is read by a person deciding
-// whether a manifest or a catalogue is wrong, and a pair of names without the reason is a puzzle.
-func Disagreements(emitters []AnEmitter, consumers []AConsumer, seats []DeclaredSeat) []string {
-	emits := map[string]map[string]bool{}
-	for _, e := range emitters {
-		if emits[e.Module] == nil {
-			emits[e.Module] = map[string]bool{}
-		}
-		for _, name := range e.Emits {
-			emits[e.Module][name] = true
-		}
-	}
-	// A seat's events are published by its holder under the seat's name, so a consumer naming the
-	// seat is naming something real even though no module declares it as its own.
-	for _, s := range seats {
-		if len(s.Emits) == 0 {
-			continue
-		}
-		if emits[s.Name] == nil {
-			emits[s.Name] = map[string]bool{}
-		}
-		for _, name := range s.Emits {
-			emits[s.Name][name] = true
-		}
-	}
-
-	var out []string
-	for _, c := range consumers {
-		for _, pattern := range c.Consumes {
-			emitter, event, named := strings.Cut(pattern, ".")
-			// Every event from everyone, or every event from one module: both are deliberate and
-			// neither names a particular event to check.
-			if !named || emitter == "*" || emitter == catalogueTheRest || event == catalogueTheRest {
-				continue
-			}
-			known, present := emits[emitter]
-			if !present {
-				// Not installed here, which is ordinary: a module lives in its own repository and
-				// may be registered later. Nothing to compare, so nothing to say.
-				continue
-			}
-			if matchesAny(event, known) {
-				continue
-			}
-			out = append(out, fmt.Sprintf(
-				"%s consumes %q and %s emits %s — so that subscription would match nothing, and "+
-					"nothing would report it",
-				c.Module, pattern, emitter, listOf(known)))
-		}
-	}
-	sort.Strings(out)
-	return out
-}
-
-// matchesAny says whether one of an emitter's event names satisfies a consumer's pattern.
-func matchesAny(pattern string, emitted map[string]bool) bool {
-	want := strings.Split(pattern, ".")
-	for name := range emitted {
-		if matches(want, strings.Split(name, ".")) {
-			return true
-		}
-	}
-	return false
-}
-
-func matches(pattern, name []string) bool {
-	for i, part := range pattern {
-		if part == catalogueTheRest {
-			return i < len(name)
-		}
-		if i >= len(name) {
-			return false
-		}
-		if part != "*" && part != name[i] {
-			return false
-		}
-	}
-	return len(pattern) == len(name)
-}
-
-func listOf(names map[string]bool) string {
-	if len(names) == 0 {
-		return "nothing"
-	}
-	out := make([]string, 0, len(names))
-	for n := range names {
-		out = append(out, n)
-	}
-	sort.Strings(out)
-	return strings.Join(out, ", ")
-}

go/buscompose/announced.go

@@ -1,97 +0,0 @@
-package buscompose
-
-import (
-	"sort"
-	"strings"
-
-	"git.novox.be/novox/mesh-sdk/go/announce"
-)
-
-// Who may read a module's state is what the module announced (novox/hq ADR 0495 clauses 2 and 3, ADR 0513 §3; issue
-// 1790). A module says on the bus which states it keeps and which others may read (announce.Subject); the controller
-// keeps the last word of each (announce.KeptBucket) and grants a reader's `reads: <owner>.<name>` only when the owner
-// announced that state readable. An owner that has announced nothing yet is read as before, from the reader's `reads`
-// (the transition, until every module announces), and is named as not yet announced.
-
-// StatesAnnouncedBucket is the controller's bucket of the last announcement of each module (announce.KeptBucket).
-const StatesAnnouncedBucket = announce.KeptBucket
-
-// controllerReadable are the controller's states others may read: the record mirrors (the packages each node declares
-// among them, which the pacman module reads, ADR 0507 §5), the chain's buckets, and the grants issued and the
-// compositions' digests, which the assigner reads (ADR 0528 clause 2, ADR 0539 clause 6).
-var controllerReadable = []string{MirrorAssignments, MirrorDeclaredConfig, MirrorPredefined, ChainBuilds, ChainRollouts,
-	MirrorDeclaredPackages, ControllerGrants, ControllerComposed}
-
-// ControllerAnnouncement is what the controller announces it keeps (ADR 0495 clause 2): every bucket of its own by its local
-// name, the ones others may read marked readable. It announces itself, as any module does from its code.
-func ControllerAnnouncement(node string) announce.States {
-	s := announce.States{Module: ControllerSeat, Node: node}
-	readable := map[string]bool{}
-	for _, n := range controllerReadable {
-		readable[n] = true
-	}
-	for _, bucket := range ControllerBuckets() {
-		local, mine := strings.CutPrefix(bucket, ControllerSeat+"_")
-		if !mine {
-			continue
-		}
-		s.States = append(s.States, announce.State{Name: local, Readable: readable[local]})
-	}
-	sort.Slice(s.States, func(i, j int) bool { return s.States[i].Name < s.States[j].Name })
-	return s
-}
-
-// ReadsAnnounced splits a reader's `reads` (`<owner>.<name>`) by what each owner announced: granted when the owner
-// announced the state readable, or announced nothing yet (the transition); refused when the owner announced and did
-// not announce that state readable.
-func ReadsAnnounced(reads []string, announced map[string]announce.States) (granted, refused []string) {
-	return ReadsAnnouncedBy("", reads, announced)
-}
-
-// ReadsAnnouncedBy is ReadsAnnounced for one reader module, which also honours the readers an owner named for a state
-// (announce.State.Readers) and the composer's named readers (NamedReaders, ADR 0547 clause 9): a read named for other
-// modules is refused. An empty reader is judged by the readable mark alone.
-func ReadsAnnouncedBy(reader string, reads []string, announced map[string]announce.States) (granted, refused []string) {
-	for _, r := range reads {
-		owner, name, ok := strings.Cut(r, ".")
-		s, said := announced[owner]
-		switch {
-		case reader != "" && !ReaderMay(reader, r):
-			refused = append(refused, r)
-		case reader != "" && ok && said && s.Keeps(name):
-			if s.ReadableBy(name, reader) {
-				granted = append(granted, r)
-			} else {
-				refused = append(refused, r)
-			}
-		case !ok || !said || s.Readable(name):
-			granted = append(granted, r)
-		default:
-			refused = append(refused, r)
-		}
-	}
-	return granted, refused
-}
-
-// NotAnnounced are the owners some module reads the state of and that have announced nothing yet, sorted: read from the
-// readers' `reads` as before, until they announce.
-func NotAnnounced(r Records) []string {
-	seen := map[string]bool{}
-	var out []string
-	for _, ds := range r.Assigned {
-		for _, d := range ds {
-			for _, read := range append(append([]string(nil), d.Reads...), d.ReadsRefused...) {
-				owner, _, ok := strings.Cut(read, ".")
-				if !ok || seen[owner] {
-					continue
-				}
-				if _, said := r.Announced[owner]; !said {
-					seen[owner] = true
-					out = append(out, owner)
-				}
-			}
-		}
-	}
-	sort.Strings(out)
-	return out
-}

go/buscompose/buildbacklog.go

@@ -1,47 +0,0 @@
-package buscompose
-
-import "git.novox.be/novox/mesh-sdk/go/delivery"
-
-// The view alone reads the build seats' queues (novox/hq ADR 0525 §2, issue 1887 A8a): the shared workers' counts and the
-// oldest waiting ask, to show the backlog. It may not publish an ask: only the builder and the checker ask, by their seat use.
-// The watchman is granted nothing here: a waiting ask has no pulse, a taken one is read from the build module's steps (issue
-// 1908). Nothing is a wildcard over a stream or a worker.
-const (
-	// ViewModule is the module of the delivery view (mesh-delivery-view).
-	ViewModule = "mesh-delivery-view"
-	// BuilderModule is the module of the builder (mesh-delivery-builder).
-	BuilderModule = "mesh-delivery-builder"
-)
-
-// BuildAskReads are the API subjects the builder requests when it takes over, at its start, a key naming an ask (issue
-// 1910): each build seat's stream's information and its messages by sequence, to tell whether the ask is on its stream.
-// Reads only: no consumer, no pull, no acknowledgement; the builder puts its asks by its seat use, as before.
-func BuildAskReads() []string {
-	var out []string
-	for _, lang := range delivery.AskLanguages {
-		if stream, err := delivery.AskStream(lang); err == nil {
-			out = append(out, "$JS.API.STREAM.INFO."+stream, "$JS.API.STREAM.MSG.GET."+stream)
-		}
-	}
-	return out
-}
-
-// BuildBacklogReads are the API subjects the view requests: the information of each build seat's stream and of each of its
-// shared workers (delivery.AskStream, delivery.AskWorker), and the message of the stream by sequence. Reads only: no
-// message is pulled, none acknowledged, none published.
-func BuildBacklogReads() []string {
-	var out []string
-	for _, lang := range delivery.AskLanguages {
-		stream, err := delivery.AskStream(lang)
-		if err != nil {
-			continue
-		}
-		out = append(out, "$JS.API.STREAM.INFO."+stream, "$JS.API.STREAM.MSG.GET."+stream)
-		for _, kind := range delivery.AskKinds {
-			if w, err := delivery.AskWorker(lang, kind); err == nil {
-				out = append(out, "$JS.API.CONSUMER.INFO."+stream+"."+w)
-			}
-		}
-	}
-	return out
-}

go/buscompose/buscompose_test.go

@@ -1,255 +0,0 @@
-package buscompose
-
-import (
-	"encoding/json"
-	"os"
-	"path/filepath"
-	"reflect"
-	"regexp"
-	"slices"
-	"strings"
-	"testing"
-)
-
-// Defends issue 1377 and novox/hq ADR 0547 §5: this is the controller's bus composer copied, and it composes byte for
-// byte what the controller's composes. testdata/controller-user-lists.json was written by the controller's own
-// internal/broker (mesh-controller branch fix/1945-mesh-grants-publishes-memberships, and fix/1790-grants-create-buckets for the grants part creating declared streams), lists and memberships, from fixtures_test.go compiled there unchanged; composed.conf is the
-// controller's golden of the whole server configuration. A row that differs is the copy drifting from the controller,
-// which is a fault while both compose (until the controller loses its lease, ADR 0547 §13), but for the grants the copy
-// gives beyond it on purpose (beyondTheControllers): the copy grants every user everything the controller's grants, and
-// only those more.
-// createdAdvisory is one subscription to a bucket's creation in a composed list, as stateCreatedHeard composes it.
-var createdAdvisory = regexp.MustCompile(`"\$JS\.EVENT\.ADVISORY\.STREAM\.CREATED\.KV_[^"]*", `)
-
-// beyondTheControllers is what the copy grants beyond the controller's on purpose (novox/hq ADR 0547 §2, ADR 0555 §3,
-// issue 1126), by user: a node's account reads every node's own facts, `<node>.node` of the have bucket where the node's
-// record rides, and what it composes its own modules from (NodeComposeReads). After the take-over (ADR 0547 §8) the
-// grants part's list is the one the bus loads; a hand-back loads the controller's, which lacks these reads, and the nodes
-// keep applying without composing their own until the next take-over. Each principal's hearing of its buckets' creation
-// (issue 1790) is the other row beyond, matched by createdAdvisory.
-func beyondTheControllers(user string) map[string]bool {
-	out := map[string]bool{}
-	node, ok := strings.CutPrefix(user, "node.")
-	if !ok {
-		return out
-	}
-	for _, s := range append(readGrants("node-engine_have", "*.node"), NodeComposeReads(node)...) {
-		out[s] = true
-	}
-	return out
-}
-
-// mayBeyondTheControllers is what the copy may grant beyond the controller's where the records allow it, and need not
-// where they do not: a node's ask of the vault's `own` while the vault serves it (issue 1126, ADR 0550 §5).
-func mayBeyondTheControllers(user string) map[string]bool {
-	if _, ok := strings.CutPrefix(user, "node."); !ok {
-		return nil
-	}
-	return map[string]bool{VaultOwnCall(Principal{Kind: KindNode, Node: strings.TrimPrefix(user, "node.")}): true,
-		VaultSecretChanged: true}
-}
-
-// quotedToken is a quoted token of a composed list.
-var quotedToken = regexp.MustCompile(`"[^"]*"`)
-
-// grantsByUser splits a composed list into the text outside its users and each user's quoted tokens (its name, its
-// password's hash, every subject it may publish or subscribe to), by user.
-func grantsByUser(list string) (string, map[string]map[string]bool) {
-	var outside strings.Builder
-	users := map[string]map[string]bool{}
-	user := ""
-	for _, line := range strings.SplitAfter(list, "\n") {
-		trimmed := strings.TrimSpace(line)
-		if name, ok := strings.CutPrefix(trimmed, `{ user: "`); ok {
-			user, _, _ = strings.Cut(name, `"`)
-			users[user] = map[string]bool{}
-		} else if user != "" && trimmed == "]" {
-			user = ""
-		}
-		if user == "" {
-			outside.WriteString(line)
-			continue
-		}
-		for _, q := range quotedToken.FindAllString(line, -1) {
-			users[user][strings.Trim(q, `"`)] = true
-		}
-	}
-	return outside.String(), users
-}
-
-// grantsAsTheControllers fails t unless the copy's list is the controller's, user for user, but for the grants it
-// names on purpose (beyondTheControllers, the creation advisories): every grant of the controller's is the copy's, and
-// the copy's beyond them are exactly those, every one of them there.
-func grantsAsTheControllers(t *testing.T, got, want string) {
-	t.Helper()
-	gotOutside, gotUsers := grantsByUser(got)
-	wantOutside, wantUsers := grantsByUser(want)
-	if gotOutside != wantOutside {
-		t.Errorf("the list differs from the controller's outside its users:\n%s", gotOutside)
-	}
-	for user, was := range wantUsers {
-		now, ok := gotUsers[user]
-		if !ok {
-			t.Errorf("the copy has no user %s", user)
-			continue
-		}
-		intended := beyondTheControllers(user)
-		for g := range was {
-			if !now[g] {
-				t.Errorf("%s: the copy does not grant %s, which the controller's does", user, g)
-			}
-		}
-		for g := range now {
-			if !was[g] && !intended[g] && !mayBeyondTheControllers(user)[g] && !createdAdvisory.MatchString(`"`+g+`", `) {
-				t.Errorf("%s: the copy grants %s beyond the controller's, and no decision names it", user, g)
-			}
-		}
-		for g := range intended {
-			if !now[g] {
-				t.Errorf("%s: the copy does not grant %s, which a node composing its own modules reads", user, g)
-			}
-		}
-	}
-	for user := range gotUsers {
-		if _, ok := wantUsers[user]; !ok {
-			t.Errorf("the copy has a user %s the controller's has not", user)
-		}
-	}
-}
-
-func TestTheCopiedComposerComposesAsTheControllers(t *testing.T) {
-	raw, err := os.ReadFile(filepath.Join("testdata", "controller-user-lists.json"))
-	if err != nil {
-		t.Fatal(err)
-	}
-	var want []struct {
-		Name, List  string
-		Missing     []string
-		Err         string
-		Memberships json.RawMessage
-	}
-	if err := json.Unmarshal(raw, &want); err != nil {
-		t.Fatal(err)
-	}
-	fixtures := UserListFixtures()
-	if len(want) != len(fixtures) {
-		t.Fatalf("%d fixtures, %d lists the controller composed", len(fixtures), len(want))
-	}
-	for i, f := range fixtures {
-		t.Run(f.Name, func(t *testing.T) {
-			if want[i].Name != f.Name {
-				t.Fatalf("fixture %q against the controller's %q", f.Name, want[i].Name)
-			}
-			list, missing, err := ComposedFor(f)
-			got := ""
-			if err != nil {
-				got = err.Error()
-			}
-			if got != want[i].Err {
-				t.Fatalf("error %q, the controller's %q", got, want[i].Err)
-			}
-			if strings.Join(missing, ",") != strings.Join(want[i].Missing, ",") {
-				t.Errorf("left out %v, the controller %v", missing, want[i].Missing)
-			}
-			// The one row the copy composes beyond the controller's, on purpose (novox/hq issue 1790, 2026-10-26, after
-			// the take-over of ADR 0547 milestone 2): each principal hears its own and read buckets created, so a state
-			// missing at its start is bound when it appears. The controller's composer is frozen and its list no longer
-			// loaded; while it is not, this row is left out of the comparison and nothing else.
-			grantsAsTheControllers(t, list, want[i].List)
-			// And every membership the records issue, as the controller's MembershipFor makes it (ADR 0547 §5): the
-			// grants part publishes them.
-			raw, err := json.Marshal(MembershipsFor(f))
-			if err != nil {
-				t.Fatal(err)
-			}
-			var gotM, wasM any
-			if err := json.Unmarshal(raw, &gotM); err != nil {
-				t.Fatal(err)
-			}
-			if err := json.Unmarshal(want[i].Memberships, &wasM); err != nil {
-				t.Fatal(err)
-			}
-			if !reflect.DeepEqual(gotM, wasM) {
-				t.Errorf("the memberships differ from the controller's:\n%s", raw)
-			}
-		})
-	}
-	// An asker on a seat pulled by kind hears what that seat's workers gave up on, and no other stream's dead letters
-	// (novox/hq issue 734: a check ask given up during a bus reload left its try running for ever).
-	t.Run("an asker reads its seat's dead letters", func(t *testing.T) {
-		build := Seat{Name: "node-build-go", Scope: "node", Accepts: []string{"delivery", "check", "recheck"}, PulledByKind: true}
-		perms, err := PermissionsFor(Principal{Kind: KindModule, Node: "one", Module: "mesh-delivery-checker", Uses: []Seat{build}})
-		if err != nil {
-			t.Fatal(err)
-		}
-		for subject, want := range map[string]bool{
-			"$JS.API.CONSUMER.CREATE.DEAD_LETTERS.x1.mesh.events.dead.SEAT_NODE_BUILD_GO.>":      true,
-			"$JS.API.CONSUMER.CREATE.DEAD_LETTERS.x1.mesh.events.dead.SEAT_NODE_BUILD_GO.w.next": true,
-			"$JS.API.CONSUMER.DELETE.DEAD_LETTERS.x1":                                            true,
-			"$JS.API.CONSUMER.MSG.NEXT.DEAD_LETTERS.x1":                                          true,
-			"$JS.API.CONSUMER.CREATE.DEAD_LETTERS.x1.mesh.events.dead.EVENTS.>":                  false,
-			"$JS.API.CONSUMER.CREATE.DEAD_LETTERS.x1":                                            false,
-			"$JS.API.STREAM.PURGE.DEAD_LETTERS":                                                  false,
-			"$JS.FC.DEAD_LETTERS.x1":                                                             false,
-		} {
-			if got := MayPublish(perms, subject); got != want {
-				t.Errorf("may publish %s: %v, want %v", subject, got, want)
-			}
-		}
-		plain, err := PermissionsFor(Principal{Kind: KindModule, Node: "one", Module: "shop",
-			Uses: []Seat{{Name: "telegram-sender", Accepts: []string{"send"}}}})
-		if err != nil {
-			t.Fatal(err)
-		}
-		if MayPublish(plain, "$JS.API.CONSUMER.DELETE.DEAD_LETTERS.x1") {
-			t.Error("a user of a seat not pulled by kind reads DEAD_LETTERS")
-		}
-	})
-	// Issue 1126 (ADR 0550 §5): a node's engine asks the vault's `own` in its own name while the vault serves it, and no
-	// other node's.
-	t.Run("a node asks the vault its own secrets", func(t *testing.T) {
-		one := Principal{Kind: KindNode, Node: "one", AsksItsOwnSecrets: true}
-		perms, err := PermissionsFor(one)
-		if err != nil {
-			t.Fatal(err)
-		}
-		if !MayPublish(perms, VaultOwnCall(one)) || MayPublish(perms, VaultOwnCall(Principal{Kind: KindNode, Node: "two"})) {
-			t.Errorf("node one asks own as %v, and as two %v", MayPublish(perms, VaultOwnCall(one)),
-				MayPublish(perms, VaultOwnCall(Principal{Kind: KindNode, Node: "two"})))
-		}
-		if plain, _ := PermissionsFor(Principal{Kind: KindNode, Node: "one"}); MayPublish(plain, VaultOwnCall(one)) {
-			t.Error("a node asks own while the vault does not serve it")
-		}
-		if !slices.Contains(perms.Subscribe, VaultSecretChanged) {
-			t.Errorf("node one does not hear the vault's secret-changed: %v", perms.Subscribe)
-		}
-	})
-	t.Run("the controller's golden server configuration", func(t *testing.T) {
-		seat := Seat{Name: "telegram-sender", Accepts: []string{"send"}, Emits: []string{"delivered", "failed"}}
-		got, err := Compose(
-			Server{ClientPort: 4222, MonitoringPort: 8222, StoreDir: "/data",
-				TLSCert: "/tls/tls.crt", TLSKey: "/tls/tls.key", TLSCA: "/tls/ca.crt"},
-			[]Principal{
-				{Kind: KindController, PasswordHash: "$2a$11$cccccccccccccccccccccc"},
-				{Kind: KindEnrolment, Node: "one", PasswordHash: "$2a$11$eeeeeeeeeeeeeeeeeeeeee"},
-				{Kind: KindNode, Node: "one", PasswordHash: "$2a$11$nnnnnnnnnnnnnnnnnnnnnn"},
-				{Kind: KindModule, Node: "one", Module: "telegram", Holds: []Seat{seat},
-					Serves: []string{"status"}, PasswordHash: "$2a$11$tttttttttttttttttttttt"},
-				{Kind: KindModule, Node: "two", Module: "shop", Uses: []Seat{seat},
-					Emits: []string{"order.placed"}, PasswordHash: "$2a$11$ssssssssssssssssssssss"},
-				{Kind: KindModule, Node: "two", Module: "audit",
-					Consumes: []string{"shop.order.placed"}, PasswordHash: "$2a$11$aaaaaaaaaaaaaaaaaaaaaa"},
-				{Kind: KindModule, Node: "one", Module: WatchmanModule, PasswordHash: "$2a$11$wwwwwwwwwwwwwwwwwwwwww"},
-				{Kind: KindModule, Node: "one", Module: "nats", SnapshotsTheBus: true,
-					Serves: []string{"nats_streams"}, PasswordHash: "$2a$11$bbbbbbbbbbbbbbbbbbbbbb"},
-			})
-		if err != nil {
-			t.Fatal(err)
-		}
-		want, err := os.ReadFile(filepath.Join("testdata", "composed.conf"))
-		if err != nil {
-			t.Fatal(err)
-		}
-		grantsAsTheControllers(t, got, string(want))
-	})
-}

go/buscompose/callers.go

@@ -1,117 +0,0 @@
-package buscompose
-
-import (
-	"regexp"
-	"strings"
-)
-
-// A tool call names its caller (novox/hq issue 365, by ADR 0259 §3's precedent for asks).
-//
-//	mesh.mod.<module>.call.<tool>[.<node>].<caller>
-//	mesh.seat.<seat>.call.<verb>[.<node>].<caller>
-//
-// The last token is the bus user that published the call, and each user is granted these subjects with its own
-// name there and no other — the caller is a fact the server enforces, and the tool runtime hands it to the
-// module from the subject a call arrived on (mesh-tools node-tools internal/bus caller.go holds the same shape).
-//
-// **A kind of its own, `call`, not the `tool` subject with a token appended.** Every grant to call a tool is a
-// wildcard over the `tool` kind — `.tool.<t>.*` for the instance on any machine, `mesh.mod.*.tool.>` for every
-// tool — and either would match a `tool` subject with any caller appended, so a caller could name another.
-// Under `call` nothing is granted but the caller-named subjects. No stream's filter covers it: a tool call is
-// never persisted (design 25 §3).
-//
-// **Derived from the `tool` grants, in one place** (callerNamed): wherever a principal may call or answer a
-// tool, it may call it in its own name, or answer it naming any caller — so no kind of principal is left
-// unable to call in its own name, and a new grant to call is one in both shapes by construction.
-//
-// The `tool` grants stay beside these for one release, so every caller and every runtime moves without a gap:
-// their retirement is hq issue 464.
-const CallKind = "call"
-
-var userName = regexp.MustCompile(`^[A-Za-z0-9_-]+(\.[A-Za-z0-9_-]+)*$`)
-
-// CallerToken is a bus user's name as the last token of a call it publishes: each dot written `~`, which no part
-// of a user's name may hold (safeSubject), so the token names that user and no other. "" for a name that is not
-// a user's.
-func CallerToken(user string) string {
-	if !userName.MatchString(user) {
-		return ""
-	}
-	return strings.ReplaceAll(user, ".", "~")
-}
-
-// toolGrant splits a grant on the `tool` kind — `mesh.mod.<m>.tool.<rest>` or `mesh.seat.<s>.tool.<rest>`, any
-// part possibly a wildcard — at the kind; ok is false for any other subject.
-func toolGrant(subject string) (head, rest string, ok bool) {
-	parts := strings.SplitN(subject, ".", 5)
-	if len(parts) != 5 || parts[0] != "mesh" || (parts[1] != "mod" && parts[1] != "seat") || parts[3] != "tool" ||
-		parts[2] == "" || parts[4] == "" {
-		return "", "", false
-	}
-	return parts[0] + "." + parts[1] + "." + parts[2], parts[4], true
-}
-
-// CalledSubject is where a call to a tool subject goes naming its caller; "" when the subject is not a tool's
-// or the user is not a bus user.
-func CalledSubject(subject, user string) string {
-	head, rest, ok := toolGrant(subject)
-	token := CallerToken(user)
-	if !ok || token == "" || strings.ContainsAny(rest, "*>") {
-		return ""
-	}
-	return head + "." + CallKind + "." + rest + "." + token
-}
-
-// CalledPattern is what a holder answering a tool subject also subscribes, to hear the calls that name their
-// caller: the same address under the `call` kind, any caller last. "" for a subject that is not a tool's.
-func CalledPattern(subject string) string {
-	head, rest, ok := toolGrant(subject)
-	if !ok || strings.ContainsAny(rest, "*>") {
-		return ""
-	}
-	return head + "." + CallKind + "." + rest + ".*"
-}
-
-// calledPublish is a grant to call on the `tool` kind, as the same grant in the caller's own name: its last
-// token the caller's, and nothing that reaches past it. A `>` is every tail a call carries — the tool alone or
-// the tool and the machine — so it becomes both, each ending in the caller.
-func calledPublish(grant, token string) []string {
-	head, rest, ok := toolGrant(grant)
-	if !ok || token == "" {
-		return nil
-	}
-	base := head + "." + CallKind + "."
-	switch {
-	case rest == ">":
-		return []string{base + "*." + token, base + "*.*." + token}
-	case strings.HasSuffix(rest, ".>"):
-		return []string{base + strings.TrimSuffix(rest, ">") + "*." + token}
-	}
-	return []string{base + rest + "." + token}
-}
-
-// calledSubscribe is a grant to answer on the `tool` kind, as the same grant for the calls naming any caller.
-func calledSubscribe(grant string) []string {
-	head, rest, ok := toolGrant(grant)
-	if !ok {
-		return nil
-	}
-	base := head + "." + CallKind + "."
-	if strings.HasSuffix(rest, ">") {
-		return []string{base + rest}
-	}
-	return []string{base + rest + ".*"}
-}
-
-// callerNamed adds, beside a principal's grants on the `tool` kind, the same grants under `call`: to publish in
-// its own name, to subscribe naming anybody.
-func callerNamed(user string, pub, sub []string) ([]string, []string) {
-	token := CallerToken(user)
-	for _, g := range pub {
-		pub = append(pub, calledPublish(g, token)...)
-	}
-	for _, g := range sub {
-		sub = append(sub, calledSubscribe(g)...)
-	}
-	return unique(pub), unique(sub)
-}

go/buscompose/cancelled.go

@@ -1,11 +0,0 @@
-package buscompose
-
-import "strings"
-
-// A seat's cancelled set (novox/hq ADR 0219) is a bucket the mesh no longer raises or grants (R4g, ADR 0525 clause 6): the
-// controller asks no work queue, so nothing is cancelled. A bus that still holds one is not reported as state nothing declares.
-
-// IsCancelledSet says a bucket is a seat's cancelled set rather than a module's state.
-func IsCancelledSet(bucket string) bool {
-	return strings.HasPrefix(bucket, "SEAT_") && strings.HasSuffix(bucket, "_cancelled")
-}

go/buscompose/composed.go

@@ -1,196 +0,0 @@
-package buscompose
-
-import (
-	"context"
-	"fmt"
-
-	"git.novox.be/novox/mesh-sdk/go/delivery"
-	"github.com/nats-io/nats.go/jetstream"
-)
-
-// The compositions' buckets (novox/hq ADR 0539 clauses 2 and 4): one per node, `composed-<node>`, holding that node's
-// compositions, which only that node's node-engine reads, since a composition can carry a sealed value (ADR 0488 §2's
-// reason); and `mesh-controller_composed`, holding each composition's digest and the judgement of its move, which the
-// assigner reads. The controller writes both, by compare-and-set while it holds the lease; each keeps five revisions
-// of a key. The names and layouts are mesh-sdk's (delivery.ComposedBucketFor, ControllerComposedBucket, ComposedKey).
-
-// ControllerComposed is the local name of the compositions' digests, as a reader names it in `reads` after
-// `mesh-controller.`: delivery.ControllerComposedBucket.
-const ControllerComposed = "composed"
-
-// ComposedValueBytes is the most a composition may hold: a file over 64 KiB travels by digest, so a module's
-// composition is far smaller; just under the server's largest message, which also carries the subject and headers.
-const ComposedValueBytes = 1<<20 - 8<<10
-
-// ComposedBucketBytes is a node's composition bucket's size: five revisions of every module's compositions of the node.
-const ComposedBucketBytes = 256 << 20
-
-// ComposedDigestsBytes is the size of the bucket of digests: a value of a few hundred bytes per node, module and
-// fingerprint kept.
-const ComposedDigestsBytes = 64 << 20
-
-// ComposedConfig is a node's composition bucket as the controller asserts it.
-func ComposedConfig(node string) (jetstream.KeyValueConfig, error) {
-	bucket, err := delivery.ComposedBucketFor(node)
-	if err != nil {
-		return jetstream.KeyValueConfig{}, err
-	}
-	return jetstream.KeyValueConfig{
-		Bucket: bucket,
-		Description: "the compositions of " + node + " (novox/hq ADR 0539): each module's resources for this node at one " +
-			"fingerprint, and the node's own, signed; written by the controller alone, read by this node's node-engine " +
-			"alone; deleted when outside the module's five newest fingerprints and named by no want",
-		History:      delivery.ComposedHistory,
-		MaxValueSize: ComposedValueBytes,
-		MaxBytes:     ComposedBucketBytes,
-		Storage:      jetstream.FileStorage,
-	}, nil
-}
-
-// ComposedDigestsConfig is the bucket of the compositions' digests as the controller asserts it.
-func ComposedDigestsConfig() jetstream.KeyValueConfig {
-	return jetstream.KeyValueConfig{
-		Bucket: delivery.ControllerComposedBucket,
-		Description: "each composition's digest and the judgement of its move from what the node runs (novox/hq ADR 0539 " +
-			"clauses 2 and 14): written by the controller alone, read by the assigner",
-		History:      delivery.ControllerComposedHistory,
-		MaxValueSize: 4 << 10,
-		MaxBytes:     ComposedDigestsBytes,
-		Storage:      jetstream.FileStorage,
-	}
-}
-
-// EnsureComposed creates the bucket of digests and each named node's composition bucket if absent and brings their
-// options to match. An update, never a delete.
-func EnsureComposed(ctx context.Context, js jetstream.JetStream, nodes ...string) error {
-	if _, err := js.CreateOrUpdateKeyValue(ctx, ComposedDigestsConfig()); err != nil {
-		return fmt.Errorf("asserting bucket %s: %w", delivery.ControllerComposedBucket, err)
-	}
-	for _, node := range nodes {
-		cfg, err := ComposedConfig(node)
-		if err != nil {
-			return err
-		}
-		if _, err := js.CreateOrUpdateKeyValue(ctx, cfg); err != nil {
-			return fmt.Errorf("asserting bucket %s: %w", cfg.Bucket, err)
-		}
-	}
-	return nil
-}
-
-// ComposedWrites is what the controller publishes to write a node's compositions: the bucket's own subjects.
-func ComposedWrites(node string) (string, error) {
-	bucket, err := delivery.ComposedBucketFor(node)
-	if err != nil {
-		return "", err
-	}
-	return "$KV." + bucket + ".>", nil
-}
-
-// ComposedReads is what a node's node-engine publishes to follow its wants and compositions (ADR 0539 clauses 1, 2 and
-// 9): every key of its own composition bucket, and its own wants (`want.<node>.<module>` and `want.<node>.node`) in the
-// assigner's bucket; nothing of another node's, nor the bucket of digests.
-func ComposedReads(node string) ([]string, error) {
-	bucket, err := delivery.ComposedBucketFor(node)
-	if err != nil {
-		return nil, err
-	}
-	if !safeSubject.MatchString(node) {
-		return nil, fmt.Errorf("%q cannot be part of a subject: a permission is a subject pattern, and this would widen it", node)
-	}
-	return append(readGrants(bucket, ""), readGrants(delivery.AssignerWantsBucket, "want."+node+".>")...), nil
-}
-
-// VerbsTheNodeAgentAsks are the seat verbs a node's node-engine calls of its own machine while it applies a want (ADR
-// 0539 clause 16, ADR 0429 §14): its backup holder backs a data module up before it moves, and says when it was. Asked
-// of its own machine only, `mesh.seat.<seat>.tool.<verb>.<node>`.
-var VerbsTheNodeAgentAsks = []SeatVerb{{Seat: "node-backup", Verb: "now"}, {Seat: "node-backup", Verb: "backed-up"}}
-
-// NodeAgentAsks are the subjects of VerbsTheNodeAgentAsks for one node.
-func NodeAgentAsks(node string) ([]string, error) {
-	if !safeSubject.MatchString(node) {
-		return nil, fmt.Errorf("%q cannot be part of a subject: a permission is a subject pattern, and this would widen it", node)
-	}
-	var out []string
-	for _, v := range VerbsTheNodeAgentAsks {
-		out = append(out, "mesh.seat."+v.Seat+".tool."+v.Verb+"."+node)
-	}
-	return out, nil
-}
-
-// NodeAgentHears are the events a node's node-engine subscribes while it applies a want: the backup holder's word that a
-// backup is taken (`backed-up`), from whichever module holds node-backup on its machine (restic today).
-var NodeAgentHears = []string{"mesh.mod." + BackupHolderModule + ".event.backed-up"}
-
-// BackupHolderModule is the module that holds node-backup on every node, restic: the one whose word a node-engine hears.
-// A second holder of the seat is a change of this grant.
-const BackupHolderModule = "restic"
-
-// administers says a person may invoke every tool (`*`): the operator.
-func administers(invokes []string) bool {
-	for _, i := range invokes {
-		if i == "*" {
-			return true
-		}
-	}
-	return false
-}
-
-// HandPathWrites is what the operator's account publishes for release 6's hand path (ADR 0539 clauses 2 and 10): a want
-// of any node, written and read back, in the assigner's bucket; each named node's compositions; the digests; and each
-// node's object bucket for a file over 64 KiB, whose put reads an object's metadata and purges a replaced one's chunks.
-func HandPathWrites(nodes []string) ([]string, error) {
-	out := append([]string{"$KV." + delivery.AssignerWantsBucket + ".want.>"}, readGrants(delivery.AssignerWantsBucket, "want.>")...)
-	out = append(out, "$KV."+delivery.ControllerComposedBucket+".>")
-	out = append(out, readGrants(delivery.ControllerComposedBucket, "")...)
-	for _, node := range nodes {
-		w, err := ComposedWrites(node)
-		if err != nil {
-			return nil, err
-		}
-		bucket, _ := delivery.ComposedBucketFor(node)
-		out = append(out, w)
-		out = append(out, readGrants(bucket, "")...)
-		files, err := DeclarationFilesWrites(node)
-		if err != nil {
-			return nil, err
-		}
-		stream := "OBJ_" + DeclarationFilesBucket + node
-		out = append(out, files, "$JS.API.STREAM.INFO."+stream, "$JS.API.DIRECT.GET."+stream+".>",
-			"$JS.API.STREAM.MSG.GET."+stream, "$JS.API.STREAM.PURGE."+stream)
-	}
-	return out, nil
-}
-
-// DeclarationsStream is the stream of each node's last declaration, `mesh.node.<node>.declare` (issue 107). Release 6
-// sends none (ADR 0539 clauses 5 and 11): the stream is kept, with each node's consumer, only so a node away during the
-// switch finds its last declaration and with it the new node-engine; the controller deletes it once every node's have
-// names the new node-engine, and from then on neither asserts it nor any node's consumer on it; nor makes it again once
-// it is gone from the bus for any reason, since a stream made anew would hold no node's last declaration (issue 1945).
-const DeclarationsStream = "NODES"
-
-// RaiseAfterDeclarations is Raise once the declarations' stream is retired: the mesh's streams and consumers but the
-// declarations' stream, and no node's consumer of a declaration.
-func RaiseAfterDeclarations(r Raiser) error {
-	for _, s := range MeshStreams() {
-		if s.Name == DeclarationsStream {
-			continue
-		}
-		if err := r.EnsureStream(s); err != nil {
-			return fmt.Errorf("asserting stream %s: %w", s.Name, err)
-		}
-	}
-	return AssertMeshConsumers(r)
-}
-
-// TakeInConsumer is the durable consumer the controller takes done keys in from, on the stream of each of TakeInBuckets
-// (novox/hq ADR 0544 §1).
-const TakeInConsumer = "mesh-controller-take-in"
-
-// TakeInBuckets are the buckets the take-in consumes: the indexer's modules (each module's trunk value) and the builder's
-// builds (each build's key).
-var TakeInBuckets = []string{delivery.ModulesBucket, delivery.BuilderBuildsBucket}
-
-// ConfigFollowConsumer is the durable consumer the controller follows mesh-config's resolved values with, on that
-// bucket's stream (novox/hq ADR 0545).
-const ConfigFollowConsumer = "mesh-controller-config-follow"

go/buscompose/controller_buckets.go

@@ -1,247 +0,0 @@
-package buscompose
-
-import (
-	"context"
-	"fmt"
-	"time"
-
-	"git.novox.be/novox/mesh-sdk/go/delivery"
-	"github.com/nats-io/nats.go/jetstream"
-)
-
-// The controller's own key-value buckets (novox/hq to-be 45 §1, §6, §7).
-//
-// **What the controller must remember across its own restart, it keeps on the bus.** A call's
-// outcome lived in the memory of the process that served it (novox/hq issue 265), so a controller
-// replaced while a push ran answered "no such call" for the one thing its caller had been told to
-// ask about. The bus already outlives the controller and is the shape ADR 0201 gives a module's
-// current state: one value per key, written by one owner, read by anybody granted it. These are the
-// controller's, written by it alone — the writers table of to-be 45 §1 — and asserted on every start
-// like the streams, so a bus raised from nothing has them before the first call is served.
-
-// CallsBucket keeps every call of the mesh's own verbs and what came of it; HandActsBucket every act
-// a person did by hand, with why; ConditionsBucket every condition open now (to-be 45 §2), one key
-// each, and ConditionHistoryBucket every transition of one — raised, changed, silenced, cleared —
-// for ninety days.
-//
-// **The history is a bucket of its own** because its keys expire and an open condition's must not:
-// a bucket has one age for every key, and a condition open longer than the history is kept would
-// otherwise vanish from the store while still true.
-var (
-	CallsBucket            = BucketName(ControllerSeat, "calls")
-	HandActsBucket         = BucketName(ControllerSeat, "hand-acts")
-	ConditionsBucket       = BucketName(ControllerSeat, "conditions")
-	ConditionHistoryBucket = BucketName(ControllerSeat, "condition-history")
-	// LeaseBucket holds the controller's lease (to-be 45 §6): one key, `holder`, which the instance
-	// allowed to act writes by compare-and-set and renews; its revision when taken is the epoch.
-	LeaseBucket = BucketName(ControllerSeat, "lease")
-	// AskedBucket keeps what the controller asked the operator about its conditions (novox/hq ADR 0259):
-	// each ask by its id, its options and the actions they stand for, how it ended and whether the
-	// controller acted on its warrant — so a restart neither asks twice nor acts twice.
-	AskedBucket = BucketName(ControllerSeat, "asked")
-	// DeliveryMergesBucket holds the merges mesh-delivery announced it made, each with the ask whose Approve it merged
-	// on (novox/hq ADR 0420 §7, issue 1025): per merge a key `<owner>/<repo>/<number>/<head sha>` holding the
-	// announcement, kept DeliveryMergesKeptFor. What lets the build of a moved module register it from its new
-	// repository: the controller reads the ask's warrant from the router and accepts only the operator's Approve of
-	// those heads. Written by the controller alone, from the announcement, when it holds the lease.
-	DeliveryMergesBucket = BucketName(ControllerSeat, "delivery-merges")
-)
-
-// DeliveryMergesKeptFor is how long a merge mesh-delivery announced is kept: a week, as the events are.
-const DeliveryMergesKeptFor = 7 * 24 * time.Hour
-
-// The controller's record mirrors (novox/hq ADR 0289, design 54, design 57 package F3): a bucket per kind of
-// record, one key per record, written from the store by the lease holder only when the record changed, with
-// one event on the controller's seat per write. Read by whatever names them in `reads` as
-// `mesh-controller.<mirror>` (ADR 0201 §1), written by nobody else. **No secret in either** (ADR 0201): an
-// assignment's value names its module and node; a module's declared config is what its manifest, which is
-// public, declares.
-//
-// AssignmentsBucket holds which module is assigned to which node, keyed `<node>.<module>`; and
-// DeclaredConfigBucket each registered module's config declarations as its manifest holds them, keyed by
-// the module: what mesh-config resolves a config value from (ADR 0348 clauses 2 and 4); and PredefinedBucket the
-// list of predefined keys the mesh published (the newest trunk build's of the catalogue, ADR 0348 §7), one key
-// `list`: what mesh-config publishes as mesh-config_predefined (design 57 K3, issue 662).
-var (
-	AssignmentsBucket    = BucketName(ControllerSeat, MirrorAssignments)
-	DeclaredConfigBucket = BucketName(ControllerSeat, MirrorDeclaredConfig)
-	PredefinedBucket     = BucketName(ControllerSeat, MirrorPredefined)
-	// DeclaredPackagesBucket holds, keyed by the node, each package the modules assigned to it declare, present or absent,
-	// with the declaring modules: what the pacman module's verbs read to say a package is declared (ADR 0507 §5).
-	DeclaredPackagesBucket = BucketName(ControllerSeat, MirrorDeclaredPackages)
-)
-
-// The mirrors' local names, as a reader names them in `reads` after `mesh-controller.`.
-const (
-	MirrorAssignments    = "assignments"
-	MirrorDeclaredConfig = "declared-config"
-	MirrorPredefined     = "predefined"
-	// MirrorDeclaredPackages is the local name of the packages each node's modules declare (ADR 0507 §5, issue 1840/S3).
-	MirrorDeclaredPackages = "declared-packages"
-)
-
-// The chain's buckets (novox/hq ADR 0408, issue 1089): builds, rollouts and assignments are one chain kept on the bus
-// alone, one bucket each, one key per record, written by the lease holder by compare-and-set. The assignments bucket is
-// AssignmentsBucket above, which keeps its name and its readers (ADR 0408 §3). Nothing is removed from them (§4), they keep
-// ChainHistory earlier revisions of every key (§5), and a value is never cut (§6).
-var (
-	BuildsBucket   = BucketName(ControllerSeat, ChainBuilds)
-	RolloutsBucket = BucketName(ControllerSeat, ChainRollouts)
-)
-
-// **The assignments bucket keeps the marker age (MirrorMarkerTTL) it was made with as a mirror.** A stream that allows
-// messages an age cannot be made to disallow them (the server refuses the update: "message TTL status can not be
-// disabled", nats-server stream.go), so asserting the bucket without the age would fail the controller's start on a
-// mesh that has the bucket. The chain never purges or removes a key (ADR 0408 §4), so no marker is ever written and the
-// age ends nothing; it is kept only so the stream's configuration stays one the server accepts.
-//
-// The chain buckets' local names, as a reader names them in `reads` after `mesh-controller.`.
-const (
-	ChainBuilds   = "builds"
-	ChainRollouts = "rollouts"
-)
-
-// The chain buckets' bounds. ChainHistory is the bus's largest history (ADR 0408 §5). A value is at most ChainValueBytes,
-// just under the server's largest message of a mebibyte, which also carries the subject and the headers (ADR 0408 §6):
-// the controller writes none larger and the move refuses to. The buckets' size is the arithmetic of the survey of
-// issue 981: 8585 builds of 1 to 40 KB, 1049 rollouts of about 2 KB a revision and 64 revisions, so 512 MiB for the two
-// that grow, and the assignments, 285 of under a kilobyte, 64 MiB.
-const (
-	ChainHistory         = 64
-	ChainValueBytes      = 1<<20 - 8<<10
-	ChainBuildsBytes     = 512 << 20
-	ChainRolloutsBytes   = 512 << 20
-	ChainAssignmentBytes = 64 << 20
-)
-
-// GrantsBucket holds, keyed `<module>.<fingerprint hex>`, each fingerprint of a module whose bus credential the controller
-// has issued (novox/hq ADR 0528 clause 2, ADR 0429 §6 rule 6, issue 1394): written by the controller alone once the bus's
-// user list composed with the module's manifest at that fingerprint was sent to the bus's machine; read by the assigner,
-// whose sixth rule moves a node's want to a fingerprint only once its grant exists. The name and layout are mesh-sdk's
-// (delivery.ControllerGrantsBucket, ControllerGrantKey).
-var GrantsBucket = BucketName(ControllerSeat, ControllerGrants)
-
-// ControllerGrants is the grants bucket's local name, as a reader names it in `reads` after `mesh-controller.`.
-const ControllerGrants = "grants"
-
-// ChainBuckets are the three buckets of the chain: builds, rollouts and assignments.
-func ChainBuckets() []string { return []string{BuildsBucket, RolloutsBucket, AssignmentsBucket} }
-
-// MirrorsWrittenByAnother are the controller's mirrors whose writer is not the controller, each with its reason: the rule
-// that a mirror is written by the controller alone (TestTheMirrorsListAndTheWritersTableAgree) has these exceptions and no
-// other.
-var MirrorsWrittenByAnother = map[string]string{}
-
-// The mirrors' caps (design 54 §5): one value per key, no age, 64 KiB a value, 64 MiB a bucket.
-const (
-	MirrorValueBytes = 64 << 10
-	MirrorBytes      = 64 << 20
-	// MirrorMarkerTTL is the longest a purge's marker is kept (design 54 §2): the bucket allows a
-	// per-message age for it, and the writer gives each marker a day.
-	MirrorMarkerTTL = 24 * time.Hour
-)
-
-// PlanStateBuckets are the buckets of the plans' state that release 6 deletes (novox/hq ADR 0539 clause 13): the merge
-// window's clock, the silent sends' waits and the building plans' hold. The controller deletes each at its first start
-// and says it once (composed_start.go); none is asserted, granted or written any more.
-var PlanStateBuckets = []string{BucketName(ControllerSeat, "merge-window"), BucketName(ControllerSeat, "rollout-silent"),
-	BucketName(ControllerSeat, "plans-building")}
-
-// AskedKeptFor is how long an ask is kept after it was made: a month, as the router keeps its own.
-const AskedKeptFor = 30 * 24 * time.Hour
-
-// LeaseTTL is how long the lease's key lives unrenewed (to-be 45 §6): fifteen seconds, renewed
-// every five. The bucket's age, so the bus forgets a holder that stopped renewing.
-const LeaseTTL = 15 * time.Second
-
-// The bounds to-be 45 §6 sets for calls: the last thousand, or fourteen days, whichever is fewer.
-// A call is two keys — its record, and its answer apart so a listing does not read every answer —
-// so the stream holds twice as many messages as it keeps calls.
-const (
-	KeptCallsDurably = 1000
-	CallsKeptFor     = 14 * 24 * time.Hour
-	// CallAnswerBytes is the most of one answer kept: a whole declaration is far smaller, and an
-	// answer larger is cut and says so.
-	CallAnswerBytes = 64 << 10
-	// HandActsKeptFor is as long as a condition's history (to-be 45 §2): an act by hand is read
-	// back beside what it addressed.
-	HandActsKeptFor = 90 * 24 * time.Hour
-	// ConditionHistoryKeptFor is how long a condition's transitions are kept (to-be 45 §2).
-	ConditionHistoryKeptFor = 90 * 24 * time.Hour
-)
-
-// IsControllerBucket says a bucket is the controller's own, not a module's state nothing declares.
-func IsControllerBucket(bucket string) bool {
-	return bucket == CallsBucket || bucket == HandActsBucket || bucket == ConditionsBucket ||
-		bucket == ConditionHistoryBucket || bucket == LeaseBucket || bucket == AskedBucket ||
-		bucket == AssignmentsBucket || bucket == DeclaredConfigBucket || bucket == PredefinedBucket ||
-		bucket == DeclaredPackagesBucket ||
-		bucket == DeliveryMergesBucket || bucket == BuildsBucket || bucket == RolloutsBucket ||
-		bucket == delivery.HaveBucket || bucket == StatesAnnouncedBucket ||
-		bucket == GrantsBucket || bucket == delivery.ControllerComposedBucket
-}
-
-// ControllerBuckets are the controller's own buckets, in the order they are asserted.
-func ControllerBuckets() []string {
-	return []string{LeaseBucket, CallsBucket, HandActsBucket, ConditionsBucket, ConditionHistoryBucket, AskedBucket,
-		AssignmentsBucket, DeclaredConfigBucket, PredefinedBucket, DeclaredPackagesBucket,
-		DeliveryMergesBucket, BuildsBucket, RolloutsBucket, delivery.HaveBucket, StatesAnnouncedBucket, GrantsBucket,
-		delivery.ControllerComposedBucket}
-}
-
-// ControllerBucketsAsserter is what raising the controller's buckets needs of a connection.
-type ControllerBucketsAsserter interface {
-	EnsureControllerBuckets() error
-}
-
-// chainBucket is the options of a bucket of the chain: sixty-four revisions of each key, no age, a value up to
-// ChainValueBytes, on disk.
-func chainBucket(bucket, why string, bytes int64, markers time.Duration) jetstream.KeyValueConfig {
-	return jetstream.KeyValueConfig{
-		Bucket:         bucket,
-		Description:    why,
-		History:        ChainHistory,
-		MaxValueSize:   ChainValueBytes,
-		MaxBytes:       bytes,
-		Storage:        jetstream.FileStorage,
-		LimitMarkerTTL: markers,
-	}
-}
-
-// EnsureLeaseBucket creates the lease's bucket if absent and brings its options to match (to-be 45
-// §6). **Before the lease is taken, by any candidate**: it is the lease's own precondition, and asserting
-// a bucket that exists changes nothing. File storage, so its revisions — the epochs — outlive a restart of
-// the bus; one raised again from nothing is moved past the highest epoch issued when the lease is taken.
-func EnsureLeaseBucket(ctx context.Context, js jetstream.JetStream) error {
-	if _, err := js.CreateOrUpdateKeyValue(ctx, jetstream.KeyValueConfig{
-		Bucket: LeaseBucket,
-		Description: "the controller's lease (novox/hq to-be 45 §6): the key `holder`, written by compare-and-set " +
-			"by the one controller instance that may act and renewed every five seconds; its revision when taken " +
-			"is the epoch every declaration and plan write carries",
-		History:      1,
-		TTL:          LeaseTTL,
-		MaxValueSize: 4 << 10,
-		MaxBytes:     1 << 20,
-		Storage:      jetstream.FileStorage,
-	}); err != nil {
-		return fmt.Errorf("asserting bucket %s: %w", LeaseBucket, err)
-	}
-	return nil
-}
-
-// HaveBucketConfig is the options of the have bucket (novox/hq ADR 0429 §1): delivery.HaveHistory revisions of each
-// key, no age, 64 MiB on disk like the assignments. A module's have is JSON of about 500 bytes, but a node's own key
-// carries its whole facts (its profile among them), several kilobytes on a desktop: a value is as large as the chain's
-// buckets take, since a value is never cut (novox/hq ADR 0408 §6, issue 1162).
-func HaveBucketConfig() jetstream.KeyValueConfig {
-	return jetstream.KeyValueConfig{
-		Bucket: delivery.HaveBucket,
-		Description: "what each machine has of each module, one key `<node>.<module>` (and `<node>.node` for the machine's " +
-			"own facts) (novox/hq ADR 0429, design 47): written by each machine's node-engine under its own node's keys " +
-			"alone, never by the controller; read by the delivery view and the watchman",
-		History:      delivery.HaveHistory,
-		MaxValueSize: ChainValueBytes,
-		MaxBytes:     64 << 20,
-		Storage:      jetstream.FileStorage,
-	}
-}

go/buscompose/create.go

@@ -1,88 +0,0 @@
-package buscompose
-
-import (
-	"time"
-
-	"github.com/nats-io/nats.go/jetstream"
-)
-
-// The streams a manifest declares, as the server is asked to create them (novox/hq ADR 0547 §5, issue 1790): the
-// grants part creates each one the bus does not hold yet, with what the controller asserts at its start, so the two
-// make the same stream. Pure. Only a create is ever asked with these: a stream the bus holds is never updated by the
-// grants part (CreateStreamGrants grants no update).
-
-// BucketStreamConfig is a module's bucket as the stream the controller's CreateOrUpdateKeyValue makes of its options
-// (mesh-controller internal/broker BucketConfig, with no marker age held): the client library's key-value shape
-// (rollup, no delete, direct reads, discard new, a duplicate window of two minutes or the age when shorter) with the
-// mesh's caps, file storage and one replica.
-func BucketStreamConfig(b Bucket) jetstream.StreamConfig {
-	history := b.History
-	if history < 1 {
-		history = 1
-	}
-	age := time.Duration(b.TTLSeconds) * time.Second
-	dupes := 2 * time.Minute
-	if age > 0 && age < dupes {
-		dupes = age
-	}
-	cfg := jetstream.StreamConfig{
-		Name:              "KV_" + b.Bucket(),
-		Description:       b.Why(),
-		Subjects:          []string{"$KV." + b.Bucket() + ".>"},
-		MaxMsgsPerSubject: int64(history),
-		MaxBytes:          StateMaxBytes,
-		MaxAge:            age,
-		MaxMsgSize:        StateMaxValueBytes,
-		Storage:           jetstream.FileStorage,
-		Replicas:          1,
-		AllowRollup:       true,
-		DenyDelete:        true,
-		Duplicates:        dupes,
-		MaxMsgs:           -1,
-		MaxConsumers:      -1,
-		AllowDirect:       true,
-		Discard:           jetstream.DiscardNew,
-	}
-	if b.KeyTTL {
-		cfg.AllowMsgTTL, cfg.SubjectDeleteMarkerTTL = true, KeyTTLMarkerTTL
-	}
-	return cfg
-}
-
-// ModuleStreamConfig is a module's own stream as the controller asserts it (mesh-controller internal/broker
-// StreamConfigFor of ModuleStream.Stream).
-func ModuleStreamConfig(m ModuleStream) jetstream.StreamConfig {
-	s := m.Stream()
-	cfg := jetstream.StreamConfig{
-		Name:              s.Name,
-		Subjects:          s.Subjects,
-		Retention:         jetstream.LimitsPolicy,
-		MaxAge:            time.Duration(s.MaxAge) * time.Second,
-		MaxMsgsPerSubject: int64(s.MaxMsgsPerSubject),
-		Description:       s.Why,
-		AllowDirect:       s.Direct,
-		AllowMsgTTL:       s.AllowMsgTTL,
-	}
-	if s.Retention == RetentionWorkQueue {
-		cfg.Retention = jetstream.WorkQueuePolicy
-	}
-	if s.Restricted || s.WorkQueue {
-		cfg.Metadata = map[string]string{}
-		if s.Restricted {
-			cfg.Metadata[RestrictedMetadata] = "true"
-		}
-		if s.WorkQueue {
-			cfg.Metadata[WorkQueueMetadata] = "true"
-		}
-	}
-	if s.MaxBytes > 0 {
-		cfg.MaxBytes = s.MaxBytes
-	}
-	if s.DiscardNew {
-		cfg.Discard = jetstream.DiscardNew
-	}
-	if s.DuplicatesSeconds > 0 {
-		cfg.Duplicates = time.Duration(s.DuplicatesSeconds) * time.Second
-	}
-	return cfg
-}

go/buscompose/create_test.go

@@ -1,46 +0,0 @@
-package buscompose
-
-import (
-	"testing"
-	"time"
-
-	"github.com/nats-io/nats.go/jetstream"
-)
-
-// Defends issue 1790 (ADR 0547 §5): the grants part creates a declared bucket and stream as the controller asserts them.
-func TestDeclaredStreamsAreCreatedAsTheControllerAssertsThem(t *testing.T) {
-	plain := BucketStreamConfig(Bucket{Module: "mesh-vault", Name: "bus-accounts"})
-	keyed := BucketStreamConfig(Bucket{Module: "m", Name: "presence", History: 5, TTLSeconds: 60, KeyTTL: true})
-	queue := ModuleStreamConfig(ModuleStream{Module: "b", Name: "ASKS", Events: []string{"ask"}, MaxAgeDays: 7, MaxMiB: 32,
-		WorkQueue: true, Duplicates: 1})
-	for _, row := range []struct {
-		what      string
-		got, want any
-	}{
-		{"bucket name", plain.Name, "KV_mesh-vault_bus-accounts"},
-		{"bucket subjects", plain.Subjects[0], "$KV.mesh-vault_bus-accounts.>"},
-		{"bucket history defaults to one", plain.MaxMsgsPerSubject, int64(1)},
-		{"bucket cap", plain.MaxBytes, int64(StateMaxBytes)},
-		{"bucket value cap", plain.MaxMsgSize, int32(StateMaxValueBytes)},
-		{"bucket duplicate window", plain.Duplicates, 2 * time.Minute},
-		{"bucket discards new", plain.Discard, jetstream.DiscardNew},
-		{"bucket direct and rollup, no delete", plain.AllowDirect && plain.AllowRollup && plain.DenyDelete, true},
-		{"bucket without key ttl", plain.AllowMsgTTL, false},
-		{"history", keyed.MaxMsgsPerSubject, int64(5)},
-		{"age", keyed.MaxAge, time.Minute},
-		{"duplicate window under the age", keyed.Duplicates, time.Minute},
-		{"key ttl markers", keyed.SubjectDeleteMarkerTTL, KeyTTLMarkerTTL},
-		{"key ttl", keyed.AllowMsgTTL, true},
-		{"queue retention", queue.Retention, jetstream.WorkQueuePolicy},
-		{"queue subjects", queue.Subjects[0], "mesh.stream.b.event.ask"},
-		{"queue age", queue.MaxAge, 7 * 24 * time.Hour},
-		{"queue cap", queue.MaxBytes, int64(32 << 20)},
-		{"queue discards new", queue.Discard, jetstream.DiscardNew},
-		{"queue duplicates", queue.Duplicates, time.Hour},
-		{"queue metadata", queue.Metadata[WorkQueueMetadata] + queue.Metadata[RestrictedMetadata], "truetrue"},
-	} {
-		if row.got != row.want {
-			t.Errorf("%s: %v, want %v", row.what, row.got, row.want)
-		}
-	}
-}

go/buscompose/creates_streams_test.go

@@ -1,130 +0,0 @@
-package buscompose
-
-import "testing"
-
-// Defends issue 1790 and novox/hq ADR 0547 §5 (the operator, 2026-10-26 08:54): the grants part may create the stream
-// of each bucket, log and stream a placed module's manifest declares, by its own name, and read it back; nothing
-// wider, nothing updated or deleted, and no other principal so. Held byte-equal in the controller's copy. And ADR 0547
-// clause 7 (issue 1945, the operator's second exception): the grants part writes its own object bucket of sealed user
-// lists, and the node-engine of the node holding mesh-broker alone reads its one key and an object of it by name.
-func TestTheGrantsPartCreatesOnlyDeclaredStreams(t *testing.T) {
-	records := Records{
-		Nodes: []string{"novox", "ace"},
-		Assigned: map[string][]Declared{"ace": {{Module: "plex"}}, "novox": {
-			{Module: "nats", SnapshotsTheBus: true},
-			// mesh-sdk's copy alone (ADR 0547 clause 9, named readers): the vault's hashes are read by the grants part
-			// alone, whatever another module's reads say; the controller's copy grants any module that declares it.
-			{Module: "mesh-vault", State: []Bucket{{Module: "mesh-vault", Name: "bus-accounts"}}},
-			{Module: "spy", Serves: []string{"spy_x"}, Reads: []string{VaultBusAccounts}},
-			{Module: "mesh-delivery-builder",
-				State:   []Bucket{{Module: "mesh-delivery-builder", Name: "steps", History: 5}},
-				Logs:    []Log{{Module: "mesh-delivery-builder", Name: "builds"}},
-				Streams: []ModuleStream{{Module: "mesh-delivery-builder", Name: "BUILDASKS", Events: []string{"ask"}}}},
-			{Module: GrantsModule, State: []Bucket{{Module: GrantsModule, Name: "assertions"}}, Reads: []string{VaultBusAccounts}},
-			{Module: RuntimeModule},
-		}},
-	}
-	users, err := Users(records)
-	if err != nil {
-		t.Fatal(err)
-	}
-	perms := map[string]Permissions{}
-	for _, u := range users {
-		if u.Kind == KindNode || u.Kind == KindNodeTools {
-			p, err := PermissionsFor(u)
-			if err != nil {
-				t.Fatalf("%s: %v", u.Username(), err)
-			}
-			perms[u.Username()] = p
-			continue
-		}
-		if u.Kind != KindModule {
-			continue
-		}
-		p, err := PermissionsFor(u)
-		if err != nil {
-			t.Fatalf("%s: %v", u.Username(), err)
-		}
-		perms[u.Module] = p
-	}
-	for _, row := range []struct {
-		who, subject string
-		may          bool
-	}{
-		{GrantsModule, "$JS.API.STREAM.CREATE.KV_mesh-delivery-builder_steps", true},
-		{GrantsModule, "$JS.API.STREAM.INFO.KV_mesh-delivery-builder_steps", true},
-		{GrantsModule, "$JS.API.STREAM.CREATE.LOG_mesh-delivery-builder_builds", true},
-		{GrantsModule, "$JS.API.STREAM.CREATE.BUILDASKS", true},
-		{GrantsModule, "$JS.API.STREAM.CREATE.KV_mesh-grants_assertions", true},
-		{GrantsModule, "$JS.API.STREAM.UPDATE.KV_mesh-delivery-builder_steps", false},
-		{GrantsModule, "$JS.API.STREAM.DELETE.KV_mesh-delivery-builder_steps", false},
-		{GrantsModule, "$JS.API.STREAM.PURGE.KV_mesh-delivery-builder_steps", false},
-		{GrantsModule, "$JS.API.STREAM.CREATE.KV_mesh-delivery-builder_undeclared", false},
-		{GrantsModule, "$JS.API.STREAM.CREATE.EVENTS", false},
-		{GrantsModule, "$JS.API.STREAM.CREATE.ASSIGNMENTS", false},
-		{GrantsModule, "$JS.API.STREAM.INFO.EVENTS", false},
-		{"mesh-delivery-builder", "$JS.API.STREAM.CREATE.KV_mesh-delivery-builder_steps", false},
-		// The sealed user list (ADR 0547 clause 7): the grants part writes its own bucket and no other.
-		{GrantsModule, "$JS.API.STREAM.CREATE.OBJ_mesh-grants-user-list", true},
-		{GrantsModule, "$O.mesh-grants-user-list.C.abc", true},
-		{GrantsModule, "$JS.API.STREAM.PURGE.OBJ_mesh-grants-user-list", true},
-		{GrantsModule, "$O.declaration-files-novox.C.abc", false},
-		{GrantsModule, "$JS.API.STREAM.DELETE.OBJ_mesh-grants-user-list", false},
-		{"mesh-delivery-builder", "$O.mesh-grants-user-list.C.abc", false},
-		// The bus node's engine reads the one key and an object by name; nothing of the bucket's list, no write.
-		{"node.novox", "$JS.API.DIRECT.GET.KV_mesh-grants_user-list.$KV.mesh-grants_user-list.sealed", true},
-		{"node.novox", "$JS.API.CONSUMER.CREATE.KV_mesh-grants_user-list.abc.$KV.mesh-grants_user-list.sealed", true},
-		{"node.novox", "$JS.API.DIRECT.GET.OBJ_mesh-grants-user-list.$O.mesh-grants-user-list.M.abc", true},
-		{"node.novox", "$JS.API.CONSUMER.CREATE.OBJ_mesh-grants-user-list.abc.$O.mesh-grants-user-list.C.abc", true},
-		{"node.novox", "$JS.API.DIRECT.GET.KV_mesh-grants_user-list.$KV.mesh-grants_user-list.list", false},
-		{"node.novox", "$JS.API.STREAM.INFO.OBJ_mesh-grants-user-list", false},
-		{"node.novox", "$JS.API.STREAM.MSG.GET.OBJ_mesh-grants-user-list", false},
-		{"node.novox", "$O.mesh-grants-user-list.C.abc", false},
-		{"node.ace", "$JS.API.DIRECT.GET.KV_mesh-grants_user-list.$KV.mesh-grants_user-list.sealed", false},
-		{"node.ace", "$JS.API.DIRECT.GET.OBJ_mesh-grants-user-list.$O.mesh-grants-user-list.M.abc", false},
-		{GrantsModule, "$JS.API.DIRECT.GET.KV_mesh-vault_bus-accounts.$KV.mesh-vault_bus-accounts.x", true},
-		{"spy", "$JS.API.DIRECT.GET.KV_mesh-vault_bus-accounts.$KV.mesh-vault_bus-accounts.x", false},
-		{"novox.node-tools", "$JS.API.DIRECT.GET.KV_mesh-vault_bus-accounts.$KV.mesh-vault_bus-accounts.x", false},
-	} {
-		if got := MayPublish(perms[row.who], row.subject); got != row.may {
-			t.Errorf("%s may publish %s: %v, want %v", row.who, row.subject, got, row.may)
-		}
-	}
-	// Issue 1790 (2026-10-26): a module hears the bus create each bucket it may bind, its own and those it reads, so a
-	// state missing at its start is bound when it appears; no other bucket's, and no other advisory.
-	for _, row := range []struct {
-		who, subject string
-		may          bool
-	}{
-		{"mesh-delivery-builder", "$JS.EVENT.ADVISORY.STREAM.CREATED.KV_mesh-delivery-builder_steps", true},
-		{GrantsModule, "$JS.EVENT.ADVISORY.STREAM.CREATED.KV_mesh-vault_bus-accounts", true},
-		{"mesh-delivery-builder", "$JS.EVENT.ADVISORY.STREAM.CREATED.KV_mesh-grants_assertions", false},
-		{"mesh-delivery-builder", "$JS.EVENT.ADVISORY.STREAM.CREATED.LOG_mesh-delivery-builder_builds", false},
-		{"mesh-delivery-builder", "$JS.EVENT.ADVISORY.STREAM.DELETED.KV_mesh-delivery-builder_steps", false},
-	} {
-		if got := MaySubscribe(perms[row.who], row.subject); got != row.may {
-			t.Errorf("%s may hear %s: %v, want %v", row.who, row.subject, got, row.may)
-		}
-	}
-	// A name that is no plain token is never granted, and a module other than the grants part is never granted one.
-	if got := CreateStreamGrants([]string{"*", ">", "KV_a.b", "KV_a_b"}); len(got) != 2 {
-		t.Errorf("grants for wildcard names: %v", got)
-	}
-	other, err := PermissionsFor(Principal{Kind: KindModule, Node: "novox", Module: "shop", CreatesStreams: []string{"KV_shop_x"}})
-	if err != nil {
-		t.Fatal(err)
-	}
-	if MayPublish(other, "$JS.API.STREAM.CREATE.KV_shop_x") {
-		t.Error("a module other than the grants part was granted a create")
-	}
-	// The writers table refuses the grants part an update, and a create of a stream it was not given.
-	g := Principal{Kind: KindModule, Node: "novox", Module: GrantsModule, CreatesStreams: []string{"KV_a_b"}}
-	if err := CheckWriters(g, []string{"$JS.API.STREAM.CREATE.KV_a_b"}); err != nil {
-		t.Errorf("the declared create refused: %v", err)
-	}
-	for _, refused := range []string{"$JS.API.STREAM.UPDATE.KV_a_b", "$JS.API.STREAM.CREATE.KV_a_c", "$JS.API.STREAM.CREATE.*"} {
-		if CheckWriters(g, []string{refused}) == nil {
-			t.Errorf("%s was not refused", refused)
-		}
-	}
-}

go/buscompose/declaration_files.go

@@ -1,111 +1,8 @@
 package buscompose
 
 import (
-	"context"
-	"fmt"
-	"time"
-
 	"git.novox.be/novox/mesh-sdk/go/declaration"
-	"github.com/nats-io/nats.go/jetstream"
 )
 
-// The object buckets a declaration's large files travel in (novox/hq ADR 0486, issues 1696 and 1697): **one bucket for each
-// node**, `declaration-files-<node>`.
-//
-// **The controller alone writes them, and a node-engine reads an object by its name from its own bucket** (ADR 0486 §2): its
-// account may neither list the bucket nor write it, no account may touch another node's, and no other account has any access.
-// Why a bucket each: a subject pattern cannot tell a name from a wildcard. A grant of `...M.*` matches a publish to the literal
-// subject `...M.*` too (probed on nats-server 2.11.17 by the review of this issue: a node created a consumer filtered on
-// `$O.<bucket>.C.*` and read every object of the bucket), so in one shared bucket a node could read every other node's files.
-// With a bucket each, the same trick reads only the node's own files, which are the files of its own declaration.
-//
-// A bucket of the bus's object store is a stream, OBJ_<bucket>, whose messages are the objects' metadata
-// (`$O.<bucket>.M.<base64 of the name>`) and chunks (`$O.<bucket>.C.<nuid>`).
-
 // DeclarationFilesBucket is the prefix of the buckets' names, which mesh-sdk fixes for the node-engine and the controller alike.
 const DeclarationFilesBucket = declaration.FileBucketPrefix
-
-// DeclarationFilesBucketOf is the bucket a node's files are in: mesh-sdk's FileBucketFor, the one place the name is composed. A
-// node name it refuses (one that could carry a subject wildcard or separator into a grant) is an error, never a bucket.
-func DeclarationFilesBucketOf(node string) (string, error) { return declaration.FileBucketFor(node) }
-
-// DeclarationFilesStreamOf is the stream under a node's bucket: mesh-sdk's FileStreamFor.
-func DeclarationFilesStreamOf(node string) (string, error) { return declaration.FileStreamFor(node) }
-
-// DeclarationFilesMaxBytes is a bucket's size: the objects are immutable and regenerable, and one node's hold well under a hundred
-// megabytes.
-const DeclarationFilesMaxBytes = 1 << 30
-
-// DeclarationFilesKeptFor is how long an object stays after no node's latest declaration names it (ADR 0486 §3).
-const DeclarationFilesKeptFor = 24 * time.Hour
-
-// DeclarationFilesWrites is the one pattern the controller may publish to write a node's bucket: every object's metadata and
-// chunks. The server's API for the stream is the controller's `$JS.API.>`.
-func DeclarationFilesWrites(node string) (string, error) {
-	bucket, err := DeclarationFilesBucketOf(node)
-	if err != nil {
-		return "", err
-	}
-	return "$O." + bucket + ".>", nil
-}
-
-// DeclarationFilesReads is what a node-engine's account may publish to read an object of its own bucket by its name, and nothing
-// more. The set is the one node-engine's own call (mesh-host internal/link FileObject) makes, for B the node's bucket and S its
-// stream (issue 1697, notes 4 and 5):
-//
-//   - the object's metadata, by a direct get of the last message of the one subject that names it. **Only the suffixed
-//     form**: the bare `$JS.API.DIRECT.GET.S` takes a sequence number and would read any message of the stream.
-//   - the ordered consumer on that object's chunks: `$JS.API.CONSUMER.CREATE.S.<name>.$O.B.C.<nuid>`. **Not `S.>`**:
-//     a consumer filtered on `$O.B.M.>` would read every object's name.
-//   - the flow-control replies of that consumer, without which a large object stalls at the flow-control window.
-//   - the consumer's deletion, best effort: the consumer's inactivity threshold removes it if this is refused.
-//
-// **Never granted:** STREAM.INFO (a `subjects_filter` of `>` lists every name), STREAM.MSG.GET (any message by its sequence), a
-// publish to `$O.B.>` (a write), and any subject of another node's stream. A literal `*` in a subject matches the grant's `*`: it
-// reaches the objects of this node's own bucket and no other (above).
-func DeclarationFilesReads(node string) ([]string, error) {
-	bucket, err := DeclarationFilesBucketOf(node)
-	if err != nil {
-		return nil, err
-	}
-	stream, err := DeclarationFilesStreamOf(node)
-	if err != nil {
-		return nil, err
-	}
-	return []string{
-		"$JS.API.DIRECT.GET." + stream + ".$O." + bucket + ".M.*",
-		"$JS.API.CONSUMER.CREATE." + stream + ".*.$O." + bucket + ".C.*",
-		"$JS.API.CONSUMER.DELETE." + stream + ".*",
-		"$JS.FC." + stream + ".>",
-	}, nil
-}
-
-// EnsureDeclarationFiles is the same on a JetStream the caller holds.
-func EnsureDeclarationFiles(ctx context.Context, js jetstream.JetStream, nodes ...string) error {
-	for _, node := range nodes {
-		cfg, err := DeclarationFilesConfig(node)
-		if err != nil {
-			return err
-		}
-		if _, err := js.CreateOrUpdateObjectStore(ctx, cfg); err != nil {
-			return fmt.Errorf("asserting the object bucket %s: %w", cfg.Bucket, err)
-		}
-	}
-	return nil
-}
-
-// DeclarationFilesConfig is a node's bucket as the controller asserts it.
-func DeclarationFilesConfig(node string) (jetstream.ObjectStoreConfig, error) {
-	bucket, err := DeclarationFilesBucketOf(node)
-	if err != nil {
-		return jetstream.ObjectStoreConfig{}, err
-	}
-	return jetstream.ObjectStoreConfig{
-		Bucket: bucket,
-		Description: "the contents of the files over 64 KiB of the declaration of " + node + ", each under the hex of its sha256 " +
-			"digest (novox/hq ADR 0486): written by the controller alone, read by the node-engine of that node by name, removed " +
-			"a day after the node's latest declaration no longer names it",
-		MaxBytes: DeclarationFilesMaxBytes,
-		Storage:  jetstream.FileStorage,
-	}, nil
-}

go/buscompose/derived.go

@@ -1,21 +1,5 @@
 package buscompose
 
-import (
-	"fmt"
-	"sort"
-	"strings"
-)
-
-// Streams and consumers derived from what modules declare.
-//
-// The mesh's own four exist before any module does (streams.go). Everything here is the other
-// half: a seat's stream comes into being when the module declaring it is **registered**, and a
-// consumer when a module is **assigned** — which is why ADR 0116's task 1.4 had to be narrowed to
-// the foundation set. Neither has happened at genesis.
-//
-// All of it is a pure function of declarations. The controller is still the only writer; this is
-// only what it writes.
-
 // A Consumer is a durable subscription the controller creates on a module's behalf. A module
 // declares what it reacts to, never how delivery works, so it does not name these and cannot
 // misconfigure them.
@@ -68,290 +52,8 @@ type Consumer struct {
 	Resettable string
 }
 
-// seatStreamName is the stream holding a seat's inbound work. Named after the seat rather than
-// the module holding it, because the holder can change and the queued work must not care — which
-// is the whole reason a caller addresses a seat instead of a module.
-func seatStreamName(seat string) string { return "SEAT_" + upperSnake(seat) }
-
-// SeatStreams is one work queue per declared seat, created when the declaring module is
-// registered rather than when it is assigned.
-//
-// **The stream exists before anyone holds the seat, and that is the point.** Work queues until a
-// holder appears, so installing the telegram module a week after something started sending to it
-// flushes the backlog instead of having lost it. A stream created at assignment would make "the
-// holder is not here yet" mean "your messages are gone".
-func SeatStreams(seats []DeclaredSeat) []Stream {
-	sorted := append([]DeclaredSeat(nil), seats...)
-	sort.Slice(sorted, func(i, j int) bool { return sorted[i].Name < sorted[j].Name })
-
-	var out []Stream
-	for _, s := range sorted {
-		if len(s.Accepts) == 0 {
-			// A seat that only emits and serves needs no stream: its events ride EVENTS and its
-			// tools are core request/reply, which is never persisted.
-			continue
-		}
-		retain := s.RetainSeconds
-		if retain == 0 {
-			retain = 7 * 24 * 60 * 60
-		}
-		out = append(out, Stream{
-			Name:      seatStreamName(s.Name),
-			Subjects:  []string{"mesh.seat." + s.Name + ".accept.>"},
-			Retention: RetentionWorkQueue,
-			MaxAge:    retain,
-			Why: fmt.Sprintf("work submitted to the %s seat; one holder consumes it, and it "+
-				"queues while nobody does", s.Name),
-		})
-	}
-	return out
-}
-
-// A DeclaredSeat is a seat as the catalogue knows it. Mirrored here rather than imported so this
-// package stays free of the catalogue's own types — the same reason the host mirrors the
-// contracts instead of importing the sdk.
-type DeclaredSeat struct {
-	Name    string
-	Accepts []string
-	// Emits are the verbs the seat's holder publishes under the seat's own name. An event about a
-	// role belongs here rather than in the holder's namespace, because the name then outlives
-	// whoever fills it (novox/hq ADR 0121, 04-ISSUES/127).
-	Emits []string
-	// Serves are the verbs the holder answers, request and reply.
-	Serves        []string
-	RetainSeconds int
-	// PulledByKind is Seat's: a worker per accepted kind, derived from the holders' seat traffic, not here.
-	PulledByKind bool
-}
-
-// ConsumerFor is the durable consumer a module's declarations imply, or false when it subscribes
-// to nothing and needs none.
-//
-// One per module, with every consumed subject as a filter, because its ack permission is derived
-// from its name: a module with a consumer per event would need an ack permission per consumer,
-// and the permission list would stop being derivable from the declaration.
-func ConsumerFor(p Principal) (Consumer, bool) {
-	// A module that reacts to anything — a module's events or a role's (novox/hq ADR 0121). Watching
-	// a role was missing here, so the one module that does it got no consumer at all: it started,
-	// connected, and its graph stayed empty with nothing anywhere reporting why.
-	// And one that hears its own answers on a seat it uses (novox/hq ADR 0259 §3): an asker's warrants.
-	hearsItsOwn := len(SeatTrafficOf(p.Module, nil, p.Uses, nil).Subscribe) > 0
-	hearsAStream := false
-	for _, h := range p.Hears {
-		if len(h.Filters) > 0 {
-			hearsAStream = true
-		}
-	}
-	if p.Kind != KindModule || (len(p.Consumes) == 0 && len(p.Watches) == 0 && !hearsItsOwn && !hearsAStream) {
-		return Consumer{}, false
-	}
-	perms, err := PermissionsFor(p)
-	if err != nil {
-		return Consumer{}, false
-	}
-	// Events, wherever they live: a module's own namespace, and the namespace of any role it watches
-	// (novox/hq ADR 0121). Tool subjects and inboxes are subscribed directly and are not a consumer's
-	// business, which is why this is a filter and not the whole list.
-	var filters []string
-	for _, s := range perms.Subscribe {
-		// Not a module stream's, which its own consumer on that stream hears (novox/hq ADR 0363).
-		if strings.Contains(s, ".event.") && !strings.HasPrefix(s, moduleStreamPrefix) {
-			filters = append(filters, s)
-		}
-	}
-	// **A module that hears only a module's stream still has one here** (novox/hq ADR 0363 §7): what it
-	// gives up on there is delivered again under `mesh.again.<consumer>.` on EVENTS, and only this filters it.
-	if len(filters) == 0 && !hearsAStream {
-		return Consumer{}, false
-	}
-	sort.Strings(filters)
-	// And the events given up on and delivered again to this consumer alone (novox/hq issue 330).
-	filters = append(filters, AgainFilter(consumerDurable(p)))
-	return Consumer{
-		Name:           consumerDurable(p),
-		Stream:         consumerStream(p),
-		Filters:        filters,
-		AckWaitSeconds: 30,
-		MaxDeliver:     5,
-		// From now, as the controller's own consumers have been since issue 248: a module made on a stream that
-		// keeps a week replays none of it. What a part needs of the present it reads from its owner
-		// (novox/hq ADR 0443 §1, §3). A consumer that exists keeps its place whatever this says.
-		FromNow: true,
-		Why: "what " + p.Module + " declared it consumes; after max-deliver it gives an event up, and the " +
-			"controller keeps it in DEAD_LETTERS until a person delivers it again or drops it",
-	}, true
-}
-
 // ModuleConsumer is one module's durable consumer, with the module and node it is for.
 type ModuleConsumer struct {
 	Node, Module string
 	Consumer     Consumer
 }
-
-// ConsumersOf is every module's durable consumer the composed users imply: each module user's, and
-// each module a runtime carries — a carried module with no account of its own is no user (novox/hq
-// issue 195), and its consumer is still the controller's to make, since the runtime reads it on the
-// module's behalf (ADR 0198). One per module and node, whichever of the two named it first.
-func ConsumersOf(users []Principal) []ModuleConsumer {
-	var out []ModuleConsumer
-	seen := map[string]bool{}
-	add := func(p Principal) {
-		key := p.Node + "/" + p.Module
-		if seen[key] {
-			return
-		}
-		c, needed := ConsumerFor(p)
-		// **A module with a work-queue consumer of its own needs no other reason to be visited here**
-		// (novox/hq ADR 0436 §1, §2, §6): mesh-mail's sender consumes and watches nothing of its own, so
-		// ConsumerFor alone would have found nothing needed and skipped it before its one queue consumer
-		// was ever composed.
-		if !needed && len(p.Queues) == 0 {
-			return
-		}
-		seen[key] = true
-		if needed {
-			out = append(out, ModuleConsumer{Node: p.Node, Module: p.Module, Consumer: c})
-			// And one on each module stream it hears (novox/hq ADR 0363 §5).
-			for _, h := range p.Hears {
-				if len(h.Filters) == 0 {
-					continue
-				}
-				out = append(out, ModuleConsumer{Node: p.Node, Module: p.Module, Consumer: heardConsumer(p, h)})
-			}
-		}
-		// And the one durable consumer of each of its own work-queue streams, for the one process its
-		// bus.queues names (novox/hq ADR 0436 §1, §2, §6).
-		for _, q := range p.Queues {
-			out = append(out, ModuleConsumer{Node: p.Node, Module: p.Module, Consumer: QueueConsumer(p, q)})
-		}
-	}
-	for _, p := range users {
-		if p.Kind == KindModule {
-			add(p)
-		}
-	}
-	for _, p := range users {
-		if p.Kind != KindNodeTools {
-			continue
-		}
-		for _, d := range p.Carries {
-			// **A carried module's work-queue consumer is still the controller's to make** (novox/hq ADR
-			// 0436 §1, §2, §6), the same reason its ordinary consumer is (ADR 0198): mesh-mail has no
-			// account of its own (NoAccount) and is carried here, but its process does, and the consumer
-			// it reads through must exist and survive PruneHeard whether or not the module itself speaks.
-			add(Principal{Kind: KindModule, Node: p.Node, Module: d.Module, Emits: d.Emits,
-				Consumes: d.Consumes, Serves: d.Serves, Holds: d.Holds, Uses: d.Uses, Watches: d.Watches,
-				Streams: d.Streams, Hears: ComposedHears(d), Queues: d.Queues})
-		}
-	}
-	return out
-}
-
-// HolderConsumerFor is the worker a seat's holders share on that seat's work queue.
-//
-// **One worker for every holder, and each holder pulls one ask when it is idle** (novox/hq ADR
-// 0190). The seat is *authority* — who may be the telegram sender — and the worker is *delivery*,
-// kept separate so that relaxing one changes nothing about the other: a node-scoped seat has a
-// holder per machine, and all of them take from this one consumer, so the work is shared without
-// any holder knowing about the others. Pulled rather than pushed because a push consumer hands the
-// next ask to whichever subscriber the server picks, busy or not, and a pulled one is asked for by
-// a holder that has just become free. Which is also what ends the race issue 186 describes — asks
-// delivered behind the one being worked, expiring unacknowledged and dropped after the fifth
-// redelivery: nothing is delivered that nobody asked for. A long build keeps its own ask alive
-// (stillWorking); the ack wait is for a holder that died.
-func HolderConsumerFor(node, module string, seat DeclaredSeat) (Consumer, bool) {
-	if len(seat.Accepts) == 0 || seat.PulledByKind {
-		// A seat pulled by kind has a worker per kind, which its holders' seat traffic derives (SeatTrafficObjects): one
-		// worker filtered on every accept would overlap them on the work queue.
-		return Consumer{}, false
-	}
-	return Consumer{
-		Name:           "SEAT_" + upperSnake(seat.Name) + "_worker",
-		Stream:         seatStreamName(seat.Name),
-		Filters:        []string{"mesh.seat." + seat.Name + ".accept.>"},
-		AckWaitSeconds: 60,
-		MaxDeliver:     5,
-		// As many in flight as there are holders working, which pulling bounds by itself: a holder
-		// fetches one and fetches again only after it acknowledged. The server's default stands.
-		Why: fmt.Sprintf("%s on %s holds %s; every holder pulls one ask at a time from this worker "+
-			"and acknowledges after the work is done, so a crash mid-work redelivers rather than "+
-			"loses and an idle holder is the one that takes the next ask", module, node, seat.Name),
-	}, true
-}
-
-// NodeConsumer is the durable consumer a node reads its own declaration through.
-//
-// **Derived from a node existing, and created by the controller, because a host cannot create it.**
-// A host's account may subscribe its own declaration subject and publish its own ack subject, and
-// reaches no part of the JetStream API — which is correct (the controller is the only writer of
-// consumer definitions, design 25 §3) and means the consumer must be waiting before the host binds
-// to it. Named after the node, because the node's ack grant is `$JS.ACK.NODES.<node>.>` and a
-// consumer named anything else is one the host cannot acknowledge a delivery from.
-//
-// **No max-deliver, and a long ack wait.** A declaration is settled only after the node has applied
-// it and reported, which is minutes on a machine pulling images; and a declaration the mesh cannot
-// get a node to accept is not one to give up on, because the stream keeps only the newest per node
-// anyway — so there is exactly one message per node to redeliver, for as long as that node is away.
-func NodeConsumer(node string) Consumer {
-	return Consumer{
-		Name:           node,
-		Stream:         "NODES",
-		Filters:        []string{"mesh.node." + node + ".declare"},
-		Push:           true,
-		AckWaitSeconds: 300,
-		Why: "how " + node + " hears what it should be; last-per-subject, so a node that was away " +
-			"gets exactly the current declaration and nothing older",
-	}
-}
-
-// AssertNodeConsumers brings every known node's declaration consumer into being.
-//
-// Asserted on start as well as created at enrolment, for the reason the streams are: a mesh raised
-// from a restored backup, or one whose bus was recreated, has node records and no consumers, and a
-// node whose consumer is missing hears nothing while everything else about it looks correct.
-func AssertNodeConsumers(e Ensurer, nodes []string) error {
-	for _, n := range nodes {
-		if err := e.EnsureConsumer(NodeConsumer(n)); err != nil {
-			return fmt.Errorf("asserting how %s hears its declaration: %w", n, err)
-		}
-	}
-	return nil
-}
-
-// AllOverlaps reports subject filters claimed by more than one stream, across the mesh's own and
-// every derived one.
-//
-// NATS refuses an overlapping stream rather than merging it (verified against nats-server 2.10:
-// "subjects overlap with an existing stream"), so this is not a subtle divergence — it is a
-// registration that fails. Catching it here names both streams, before a half-applied mesh does.
-func AllOverlaps(seats []DeclaredSeat) []string {
-	all := append(MeshStreams(), SeatStreams(seats)...)
-	seen := map[string]string{}
-	var clashes []string
-	for _, s := range all {
-		for _, subject := range s.Subjects {
-			if first, ok := seen[subject]; ok {
-				clashes = append(clashes, fmt.Sprintf("%s and %s both claim %s", first, s.Name, subject))
-				continue
-			}
-			seen[subject] = s.Name
-		}
-	}
-	sort.Strings(clashes)
-	return clashes
-}
-
-// upperSnake makes a stream name from a seat name. NATS stream names may not contain a dot,
-// a space or a wildcard, and a hyphen is legal but reads badly beside the mesh's own.
-func upperSnake(s string) string {
-	out := []rune(s)
-	for i, r := range out {
-		switch {
-		case r >= 'a' && r <= 'z':
-			out[i] = r - 32
-		case r == '-' || r == '.':
-			out[i] = '_'
-		}
-	}
-	return string(out)
-}

go/buscompose/doc.go

@@ -1,12 +1,5 @@
-// Package buscompose is the bus's composer: who may say what on the bus, as the user list and the server configuration
-// the bus loads, derived from the mesh's records (Users, WithPasswords, ComposeAccounts, Compose), with the grants,
-// streams, state and logs it composes them from.
-//
-// **A copy of the controller's internal/broker, composer half** (issue 1377, novox/hq ADR 0547 §5), taken at
-// mesh-controller 7cd4d18b with the grants part's membership grant of f67d1553 (ADR 0547 §5) and its grant to create the streams manifests declare (issue 1790): the bus client (jetstream.go), the broker's address from the environment (broker.go, onnats.go
-// but its one constant) and the two methods on that client are left out; the lease's two subjects are copied in
-// (nats.go). The controller keeps its own copy, unchanged, until it loses its lease at ADR 0547's third milestone, so
-// for that time two composers state who may say what and must say the same: TestTheCopiedComposerComposesAsTheControllers
-// holds this copy to lists the controller's own code wrote from the same fixtures. A change to what is granted is made
-// here and, while the controller composes, in the controller's copy too, never in one alone.
+// Package buscompose is the bus's names and shapes every part reads (novox/hq ADR 0593 §1): the mesh's streams and
+// dead letters, a module's log, stream and buckets as the bus names them, the account a part asks for, a principal's
+// shape, and the grants part's memberships key. The composer of the bus's user list, which reads these and makes every
+// user's permissions, is the grants part's own (mesh-delivery modules/mesh-grants internal/buscompose).
 package buscompose

go/buscompose/engine.go

@@ -0,0 +1,12 @@
+package buscompose
+
+// EngineModule is the node-engine's manifest's module name, and EngineActsState its state the acts asked through the
+// node seat and its own asks are kept in (ADR 0563 §2, §3: "the engine's own state"): the bucket mesh-host_acts, keys
+// `<node>.act.<id>`, `<node>.open.<act>.<digest>` and `<node>.ask.<id>`, each written by that node's engine alone.
+const (
+	EngineModule    = "mesh-host"
+	EngineActsState = "acts"
+)
+
+// EngineActsBucket is that state's bucket.
+var EngineActsBucket = BucketName(EngineModule, EngineActsState)

go/buscompose/fixtures_test.go

@@ -1,119 +0,0 @@
-package buscompose
-
-// The fixtures the copied bus composer is held to (issue 1377, ADR 0547 §5): the same source is compiled into the
-// controller's internal/broker to write the expected lists, and into mesh-sdk's buscompose to compare against them.
-
-// UserListFixture is one mesh's records, and the hashes its accounts carry.
-type UserListFixture struct {
-	Name    string
-	Records Records
-	// Hashless are users given no hash, so they are left out and named.
-	Hashless []string
-}
-
-func fixtureTelegramSeat() Seat {
-	return Seat{Name: "telegram-sender", Accepts: []string{"send"}, Emits: []string{"delivered", "failed"}}
-}
-
-// UserListFixtures are the meshes, from the controller's own tests' records outward.
-func UserListFixtures() []UserListFixture {
-	return []UserListFixture{
-		{Name: "empty"},
-		{Name: "the controller's someRecords", Records: Records{
-			Nodes: []string{"two", "one"},
-			Assigned: map[string][]Declared{
-				"one": {{Module: "telegram", Serves: []string{"status"}}},
-				"two": {{Module: "shop", Emits: []string{"order.placed"}}},
-			},
-			Enrolling: []string{"three"},
-			People:    map[string][]string{"ada": {"mesh-catalog.catalog_tools"}},
-		}},
-		{Name: "seats, consumers, people and a hashless user", Hashless: []string{"two.audit"}, Records: Records{
-			Nodes: []string{"one", "two"},
-			Assigned: map[string][]Declared{
-				"one": {
-					{Module: "telegram", Holds: []Seat{fixtureTelegramSeat()}, Serves: []string{"status"}},
-					{Module: "nats", SnapshotsTheBus: true, Serves: []string{"nats_streams"}},
-					{Module: "mesh-watchman"},
-					{Module: "mesh-grants", Emits: []string{"membership-changed"}},
-				},
-				"two": {
-					{Module: "shop", Uses: []Seat{fixtureTelegramSeat()}, Emits: []string{"order.placed"}},
-					{Module: "audit", Consumes: []string{"shop.order.placed"}},
-				},
-			},
-			People:          map[string][]string{"ada": {"*"}, "bob": {"shop.status"}},
-			Interchangeable: map[string]bool{"shop": true},
-		}},
-		{Name: "state, logs, streams, queues and processes", Records: Records{
-			Nodes: []string{"ace", "novox"},
-			Assigned: map[string][]Declared{
-				"novox": {
-					{Module: "mesh-delivery-builder", Emits: []string{"built"},
-						State: []Bucket{{Module: "mesh-delivery-builder", Name: "steps", History: 5},
-							{Module: "mesh-delivery-builder", Name: "presence", PerMachine: true, KeyTTL: true, TTLSeconds: 60}},
-						Logs:    []Log{{Module: "mesh-delivery-builder", Name: "builds", MaxMiB: 64}},
-						Streams: []ModuleStream{{Module: "mesh-delivery-builder", Name: "asks", Events: []string{"ask"}, MaxAgeDays: 7, MaxMiB: 32, WorkQueue: true}},
-						Queues:  []QueueOwner{{Process: "worker", Stream: "asks", MaxDeliver: 5}},
-						Processes: []ProcessPrincipal{{Process: "worker", Emits: []string{"built"},
-							Queues: []QueueOwner{{Process: "worker", Stream: "asks", MaxDeliver: 5}},
-							State:  []string{"steps"}, Invokes: []string{"gitea.gitea_commit"}}},
-						Invokes: []string{"gitea.gitea_commit"},
-					},
-					{Module: "mesh-delivery-view", Reads: []string{"mesh-delivery-builder.steps"},
-						KeyedReads: []KeyedRead{{Read: "mesh-delivery-builder.presence", Key: "novox"}}},
-					// The grants part, which may create every stream declared here (ADR 0547 §5, issue 1790).
-					{Module: "mesh-grants", Emits: []string{"membership-changed"},
-						State: []Bucket{{Module: "mesh-grants", Name: "assertions", History: 5}}},
-				},
-				"ace": {
-					{Module: "plex", Serves: []string{"plex_status"}, Checks: []string{"plex.plex_status"}},
-					{Module: "silent", NoAccount: true},
-				},
-			},
-			RootFree: map[string]bool{"ace": true},
-		}},
-	}
-}
-
-// HashOf is the stand-in hash a fixture's user carries.
-func HashOf(user string) string {
-	h := "$2a$11$"
-	for len(h) < 29 {
-		h += user
-	}
-	return h[:29] + "fixturefixturefixturefixture00"
-}
-
-// ComposedFor is a fixture's user list as the composer writes it, and the users left out.
-func ComposedFor(f UserListFixture) (string, []string, error) {
-	users, err := Users(f.Records)
-	if err != nil {
-		return "", nil, err
-	}
-	hashes := map[string]string{}
-	skip := map[string]bool{}
-	for _, u := range f.Hashless {
-		skip[u] = true
-	}
-	for _, u := range users {
-		if !skip[u.Username()] {
-			hashes[u.Username()] = HashOf(u.Username())
-		}
-	}
-	filled, missing := WithPasswords(users, hashes)
-	list, err := ComposeAccounts(filled)
-	return list, missing, err
-}
-
-// MembershipsFor is every membership a fixture's records issue, by `<node>.<module>`, as the composer makes them.
-func MembershipsFor(f UserListFixture) map[string]Membership {
-	where := PlacementsOf(f.Records, f.Records.Interchangeable)
-	out := map[string]Membership{}
-	for node, ds := range f.Records.Assigned {
-		for _, d := range ds {
-			out[node+"."+d.Module] = MembershipFor(node, d, where)
-		}
-	}
-	return out
-}

go/buscompose/health_grants.go

@@ -0,0 +1,99 @@
+package buscompose
+
+import (
+	"fmt"
+	"slices"
+	"strings"
+
+	"git.novox.be/novox/mesh-sdk/go/catalogue"
+	"git.novox.be/novox/mesh-sdk/go/health"
+)
+
+// ControllerLeftoverConsumers are the ended controller's durable consumers left on the bus, one leftover of the module
+// mesh-delivery placed nowhere (issue 1126, milestone section 3), and mesh-catalog's of the controller's built-before,
+// which its manifest no longer consumes and no part composes; each `<stream>.<consumer>`.
+var ControllerLeftoverConsumers = []string{
+	"EVENTS." + ControllerName, "EVENTS." + MergesConsumerName, "EVENTS.novox_mesh-delivery", "EVENTS.novox_mesh-catalog",
+	"CONTROL." + ControllerName, DeadLetterNoticesStream + "." + ControllerName,
+}
+
+// ControllerLeftoverConsumersOn are ControllerLeftoverConsumers and, for each node given, the consumer the controller
+// made for the node's engine (`EVENTS.<node>_mesh-host`, of restic's backed-up): the engine hears that event without a
+// durable consumer, and the grants part composes none for it, so nothing reads it (issue 1126).
+func ControllerLeftoverConsumersOn(nodes []string) []string {
+	out := slices.Clone(ControllerLeftoverConsumers)
+	for _, n := range nodes {
+		if safeSubject.MatchString(n) {
+			out = append(out, "EVENTS."+n+"_"+EngineModule)
+		}
+	}
+	return out
+}
+
+// ControllerLeftoverBuckets are the ended controller's buckets, each by its local name (`KV_mesh-controller_<name>`).
+var ControllerLeftoverBuckets = []string{"asked", "assignments", "builds", "calls", "checks-running", "composed",
+	"condition-history", "conditions", "declared-config", "declared-packages", "delivery-merges", "grants", "hand-acts",
+	"lease", "predefined", "rollouts", "states-announced"}
+
+// ControllerLeftoverStreams are the ended controller's streams, by their names: CONTROL, ASSIGNMENTS, each of its buckets'
+// and, for each node given, the declaration files' object bucket the controller wrote (ADR 0486 §2).
+func ControllerLeftoverStreams(nodes []string) []string {
+	out := []string{"CONTROL", AssignmentsStream}
+	for _, b := range ControllerLeftoverBuckets {
+		out = append(out, "KV_"+BucketName(catalogue.EndedControllerName, b))
+	}
+	for _, n := range nodes {
+		if safeSubject.MatchString(n) {
+			out = append(out, "OBJ_"+DeclarationFilesBucket+n)
+		}
+	}
+	return out
+}
+
+// BusRemovalGrants are the whole authority of an account whose bus declares removals (ADR 0564 Limits 4, ADR 0590 clause
+// 6), each removal its grant: the node-engine's acts bucket read (STREAM.INFO with a subject filter lists what a removal
+// would take, so the tools read before they remove) and its keys removed, which nothing else may empty when it fills; and
+// the ended controller's leftovers, each consumer and each stream read and deleted by its name, for the nodes given (the
+// declaration files' object buckets). A removal outside the set is refused, as the indexer's judge refuses it in a
+// manifest (novox/hq ADR 0578 §1).
+func BusRemovalGrants(removes, nodes []string) ([]string, error) {
+	var out []string
+	for _, r := range removes {
+		switch r {
+		case catalogue.RemovesEngineActs:
+			out = append(out, "$JS.API.STREAM.INFO.KV_"+EngineActsBucket, "$KV."+EngineActsBucket+".>")
+		case catalogue.RemovesControllerLeftovers:
+			for _, c := range ControllerLeftoverConsumersOn(nodes) {
+				out = append(out, "$JS.API.CONSUMER.INFO."+c, "$JS.API.CONSUMER.DELETE."+c)
+			}
+			for _, s := range ControllerLeftoverStreams(nodes) {
+				out = append(out, "$JS.API.STREAM.INFO."+s, "$JS.API.STREAM.DELETE."+s)
+			}
+		default:
+			return nil, fmt.Errorf("a bus account removes %q, which is not one of %s (novox/hq ADR 0564 Limits 4, ADR 0590)", r,
+				strings.Join([]string{catalogue.RemovesEngineActs, catalogue.RemovesControllerLeftovers}, ", "))
+		}
+	}
+	return out, nil
+}
+
+// WatchmanHears are the core subjects the watchman subscribes, with no durable consumer (ADR 0564 clauses 4, 5 and
+// Limits 3, 11): the power seat's words (S1, ADR 0211), the providers' failing and recovered words (S8), each tool
+// runner's beat (S11), the self-check's checked (S10), a consumer deleted and the bus module's slow consumers and closed
+// connections (S9), the provisioner clients' reports (S21), the dead letters kept, and the lease write's events. Never the bus's API audit
+// (`$JS.EVENT.ADVISORY.API`): it carries every API call's request and answer in the account, the vault's hashes among
+// them (the lead, 2026-10-29).
+func WatchmanHears() []string {
+	return []string{
+		"mesh.mod.power.event.*",
+		"mesh.mod.*.event.provisioner.failing",
+		"mesh.mod.*.event.provisioner.recovered",
+		"mesh.control.*.tools-alive",
+		"mesh.seat.mesh-self-check.event." + health.EventChecked,
+		"$JS.EVENT.ADVISORY.CONSUMER.DELETED.>",
+		"mesh.mod.nats.event.bus.slow-consumer",
+		"mesh.mod.nats.event.bus.connection-closed",
+		ProvAppliedSubjects,
+		deadLetterPrefix + ">",
+	}
+}

go/buscompose/log.go

@@ -2,24 +2,11 @@ package buscompose
 
 import (
 	"fmt"
-	"sort"
-	"strings"
+	"time"
 
 	"github.com/nats-io/nats.go/jetstream"
 )
 
-// A module's log on the bus (novox/hq ADR 0297): its record of operations, each entry appended under
-// a key and kept as long as the log is.
-//
-// A log follows a bucket in every respect (ADR 0201): the module names it locally, the mesh derives
-// its stream and subjects, the controller creates it from the catalogue on every raise and from
-// registration, never a module, and **no path of the mesh removes one** — a log whose declaration
-// is gone is reported, as a bucket is. Unlike a bucket, a log is its owner's alone: no other module
-// reads it, so there is no read of a log to grant or issue.
-//
-// Pure, but for the stream's configuration, which is the server's own type so that what is tested
-// is exactly what is sent; jetstream.go is the part that asks a server.
-
 // The mesh's caps on a log: what an entry's value may weigh, what a message on the log's stream may
 // weigh — the value and its headers, which the server counts in a message's size, so a value of the
 // full size still fits with the expected-last-sequence header an append carries — and what a log holds
@@ -28,7 +15,6 @@ const (
 	LogMaxEntryBytes   = 256 * 1024
 	LogMaxMessageBytes = LogMaxEntryBytes + 4*1024
 	LogDefaultMiB      = 1024
-	LogMostMiB         = 8192
 )
 
 // A Log is one module's declared log as the bus holds it.
@@ -37,6 +23,8 @@ type Log struct {
 	Name   string
 	// MaxMiB is its cap in MiB; zero is LogDefaultMiB.
 	MaxMiB int
+	// MaxAgeDays is how long an entry is kept; zero is as long as the log (catalogue.LogDeclaration).
+	MaxAgeDays int
 }
 
 // LogStreamPrefix starts every log's stream name, which no other stream of the mesh's starts with.
@@ -74,7 +62,7 @@ func (l Log) Why() string {
 }
 
 // Config is the stream a log is, field by field as novox/hq ADR 0297 fixes it: a file stream kept by
-// limits, with no maximum age and no cap per key, whose message is an entry's value and 4 KiB of
+// limits, with no maximum age unless the log says one (ADR 0565 §10) and no cap per key, whose message is an entry's value and 4 KiB of
 // headers at most, that refuses a new entry when full rather than
 // drop an old one, and that refuses deleting an entry or purging it. Direct gets are allowed, which
 // is how the runtime reads it.
@@ -85,7 +73,7 @@ func (l Log) Config() jetstream.StreamConfig {
 		Subjects:          []string{l.Subject() + ".>"},
 		Storage:           jetstream.FileStorage,
 		Retention:         jetstream.LimitsPolicy,
-		MaxAge:            0,
+		MaxAge:            time.Duration(l.MaxAgeDays) * 24 * time.Hour,
 		MaxMsgs:           -1,
 		MaxMsgsPerSubject: -1,
 		MaxBytes:          l.MaxBytes(),
@@ -97,88 +85,3 @@ func (l Log) Config() jetstream.StreamConfig {
 		Replicas:          1,
 	}
 }
-
-// logsIssuedFor is every log a module's code may reach, as its membership lists them: its own.
-func logsIssuedFor(d Declared) []LogIssued {
-	var out []LogIssued
-	for _, l := range d.Logs {
-		if !safeSubject.MatchString(d.Module) || !safeSubject.MatchString(l.Name) {
-			continue
-		}
-		out = append(out, LogIssued{Name: l.Name, Stream: LogStreamName(d.Module, l.Name),
-			Subject: LogSubject(d.Module, l.Name), Writes: true})
-	}
-	return out
-}
-
-// logGrants is what a principal publishes to reach the logs its module keeps: for each, appending
-// under the log's subjects, binding to its stream, and reading it directly. Nothing more — the
-// runtime reads a log by direct gets alone and makes no consumer on it — and nothing of any other
-// module's log, because a log is its owner's alone. Replies come on the principal's inbox, as for a
-// bucket.
-func logGrants(module string, names []string) []string {
-	if !safeSubject.MatchString(module) {
-		return nil
-	}
-	var out []string
-	for _, name := range names {
-		if !safeSubject.MatchString(name) {
-			continue
-		}
-		stream := LogStreamName(module, name)
-		out = append(out,
-			LogSubject(module, name)+".>",
-			"$JS.API.STREAM.INFO."+stream,
-			"$JS.API.DIRECT.GET."+stream,
-			"$JS.API.DIRECT.GET."+stream+".>")
-	}
-	return out
-}
-
-// logNames is the local names of a module's logs.
-func logNames(logs []Log) []string {
-	out := make([]string, 0, len(logs))
-	for _, l := range logs {
-		out = append(out, l.Name)
-	}
-	return out
-}
-
-// A LogAsserter is the part of a JetStream connection log assertion needs. It has no way to remove a
-// log, by design: nothing the mesh runs asks for one.
-type LogAsserter interface {
-	// EnsureLog creates the log's stream if absent and brings its configuration to match if present,
-	// never deleting or recreating it.
-	EnsureLog(l Log) error
-	// LogStreams is every log stream on the server: every stream named with LogStreamPrefix.
-	LogStreams() ([]string, error)
-}
-
-// RaiseLogs asserts every declared log and answers the log streams on the server that nothing
-// declares any more.
-//
-// **Those are reported, never removed** (novox/hq ADR 0297 §2, ADR 0201 §15–16): a log is a module's
-// record, and a manifest edited, a module renamed or unassigned is an ordinary day's work that must
-// not take a record with it. Removing one is a person's act, outside the mesh.
-func RaiseLogs(a LogAsserter, logs []Log) (undeclared []string, err error) {
-	sorted := append([]Log(nil), logs...)
-	sort.Slice(sorted, func(i, j int) bool { return sorted[i].Stream() < sorted[j].Stream() })
-	declared := map[string]bool{}
-	for _, l := range sorted {
-		if err := a.EnsureLog(l); err != nil {
-			return nil, fmt.Errorf("asserting %s's log %q: %w", l.Module, l.Name, err)
-		}
-		declared[l.Stream()] = true
-	}
-	names, err := a.LogStreams()
-	if err != nil {
-		return nil, fmt.Errorf("listing the bus's logs: %w", err)
-	}
-	for _, n := range names {
-		if strings.HasPrefix(n, LogStreamPrefix) && !declared[n] {
-			undeclared = append(undeclared, n)
-		}
-	}
-	sort.Strings(undeclared)
-	return undeclared, nil
-}

go/buscompose/membership.go

@@ -1,178 +0,0 @@
-package buscompose
-
-import (
-	"slices"
-	"sort"
-	"strings"
-)
-
-// What the mesh issues an assignment to serve and to reach (novox/hq ADR 0160).
-//
-// A module's code names its tools and its events; **where they land is the mesh's to decide**, and
-// it decided it twice — once in the runtime, once here, by one rule compiled into both. Now the
-// controller composes a membership for every module on every machine and publishes it to a subject
-// only that assignment reads; the runtime serves exactly what the membership says, and the account's
-// grant is the same composition read the other way. The shape issued today is the shape the mesh
-// already had, so nothing moves when a membership first arrives; only who decides it moves.
-
-// Placements is where every module runs, for deciding which instance answers for the module.
-type Placements struct {
-	// Nodes is each module's machines.
-	Nodes map[string][]string
-	// Interchangeable is each module whose definition says its instances are the same anywhere,
-	// so the module's plain subject is issued to all of them in one queue.
-	Interchangeable map[string]bool
-	// Kinds is every kind held of a kinded bench, by whom and with what capabilities (ADR 0259 §5).
-	Kinds []KindHeld
-}
-
-// AnswersForTheModule says whether an instance of a module on one machine is issued the module's
-// plain subject: when it is the only instance, or when the definition says instances are
-// interchangeable. A stateful module on two machines gets only its machines' subjects, so a call
-// that names none reaches nothing rather than the wrong store.
-func (p Placements) AnswersForTheModule(module string) bool {
-	return len(p.Nodes[module]) <= 1 || p.Interchangeable[module]
-}
-
-// MembershipFor composes one assignment's membership from what it declared and where everything
-// runs. The subjects are the ones PermissionsFor grants, derived here once more only until the
-// grant itself is read from the membership — which is the next step, not this one.
-func MembershipFor(node string, d Declared, where Placements) Membership {
-	own := "mesh.mod." + d.Module
-	m := Membership{
-		Node: node, Module: d.Module,
-		Emits: own + ".event.{event}",
-		Tools: own + ".tool.tools",
-	}
-	// This machine's address always; the module's when this instance answers for the module.
-	m.Serves = append(m.Serves, Served{Subject: own + ".tool.{tool}." + node})
-	if where.AnswersForTheModule(d.Module) {
-		m.Serves = append(m.Serves, Served{Subject: own + ".tool.{tool}", Queue: "serve." + d.Module})
-	}
-	for _, s := range d.Holds {
-		if servedOnlyByTheController(s) {
-			continue // answered by the serving controller alone, never through a membership
-		}
-		for _, verb := range s.Serves {
-			m.Seats = append(m.Seats, SeatServed{Seat: s.Name, Verb: verb, Subject: seatToolSubject(s, verb, node)})
-		}
-	}
-	m.State = stateIssuedFor(d, node)
-	m.Logs = logsIssuedFor(d)
-	m.Streams = streamsIssuedFor(d)
-	m.Hears = HeardIssuedFor(node, d)
-	m.Waits = waitsIssuedFor(d)
-	t := SeatTrafficOf(d.Module, d.Holds, d.Uses, d.Watches)
-	for _, s := range append(append([]Seat{}, d.Uses...), d.Watches...) {
-		if !s.Kinded {
-			continue
-		}
-		for _, k := range where.Kinds {
-			if k.Seat == s.Name && !kindListed(t.Kinds, k) {
-				t.Kinds = append(t.Kinds, k)
-			}
-		}
-	}
-	if len(t.Publish)+len(t.Subscribe)+len(t.Answers)+len(t.Workers)+len(t.Records)+len(t.Kinds) > 0 {
-		m.SeatTraffic = &t
-	}
-	if len(d.Invokes) > 0 {
-		m.Reaches = map[string][]string{}
-		for _, t := range d.Invokes {
-			if t == "*" || strings.HasPrefix(t, "seat:") {
-				continue // every tool, or a role's: addressed by name, not resolved per instance
-			}
-			module, tool, ok := strings.Cut(t, ".")
-			if !ok {
-				continue
-			}
-			var reach []string
-			if where.AnswersForTheModule(module) {
-				reach = append(reach, "mesh.mod."+module+".tool."+tool)
-			}
-			nodes := append([]string{}, where.Nodes[module]...)
-			sort.Strings(nodes)
-			for _, n := range nodes {
-				reach = append(reach, "mesh.mod."+module+".tool."+tool+"."+n)
-			}
-			m.Reaches[t] = reach
-		}
-	}
-	return m
-}
-
-// PlacementsOf reads where everything runs from the records the bus's accounts are composed from.
-func PlacementsOf(r Records, interchangeable map[string]bool) Placements {
-	p := Placements{Nodes: map[string][]string{}, Interchangeable: interchangeable}
-	for node, declared := range r.Assigned {
-		for _, d := range declared {
-			p.Nodes[d.Module] = append(p.Nodes[d.Module], node)
-		}
-	}
-	for _, nodes := range p.Nodes {
-		sort.Strings(nodes)
-	}
-	// Where the router runs: a verified sender is believed only while its machine is root-free too. A router
-	// placed nowhere, or on more than one machine, frees nothing.
-	var routerNodes []string
-	for node, declared := range r.Assigned {
-		for _, d := range declared {
-			for _, s := range d.Holds {
-				if s.Name == routerSeat && !slices.Contains(routerNodes, node) {
-					routerNodes = append(routerNodes, node)
-				}
-			}
-		}
-	}
-	routerFree := len(routerNodes) == 1 && r.RootFree[routerNodes[0]]
-	for node, declared := range r.Assigned {
-		for _, d := range declared {
-			for _, s := range d.Holds {
-				if s.Kinded && s.Kind != "" {
-					p.Kinds = append(p.Kinds, KindHeld{Seat: s.Name, Kind: s.Kind, Module: d.Module, Node: node,
-						Capabilities: placedCapabilities(s.Capabilities, d.RunsAs, routerFree && r.RootFree[node])})
-				}
-			}
-		}
-	}
-	sort.Slice(p.Kinds, func(i, j int) bool {
-		a, b := p.Kinds[i], p.Kinds[j]
-		if a.Seat != b.Seat {
-			return a.Seat < b.Seat
-		}
-		if a.Kind != b.Kind {
-			return a.Kind < b.Kind
-		}
-		return a.Node < b.Node
-	})
-	return p
-}
-
-// routerSeat is the seat the router of asks holds (novox/hq ADR 0259 §3).
-const routerSeat = "operator-channel"
-
-// placedCapabilities is what a kind's claim promises, as far as its placement lets the router believe it
-// (novox/hq ADR 0259 §8): `verified-sender` only from a holder that runs as an account of its own, on a bus
-// account of its own — never one the machine's runtime carries as the operator's account — and only while
-// its machine and the router's were root-free when composed (rootFree; the review of 2026-10-09, H3). The
-// membership carrying it is composed at a push, so it can outlive a pass that later fails: the router asks
-// the controller's root-free verb again before it honours an approval, and that is the check that holds.
-func placedCapabilities(declared []string, runsAs string, rootFree bool) []string {
-	var out []string
-	for _, c := range declared {
-		if c == "verified-sender" && (runsAs == "" || !rootFree) {
-			continue
-		}
-		out = append(out, c)
-	}
-	return out
-}
-
-func kindListed(list []KindHeld, k KindHeld) bool {
-	for _, x := range list {
-		if x.Seat == k.Seat && x.Kind == k.Kind && x.Module == k.Module && x.Node == k.Node {
-			return true
-		}
-	}
-	return false
-}

go/buscompose/modstreams.go

@@ -3,18 +3,8 @@ package buscompose
 import (
 	"fmt"
 	"sort"
-	"strings"
 )
 
-// A module's own stream on the bus (novox/hq ADR 0363).
-//
-// A module declares a stream as it declares a log: named locally, created by the controller from the
-// catalogue on every raise and every send, never removed by the mesh. Its events are published on
-// `mesh.stream.<module>.event.<event>`, a subject space the shared EVENTS stream (`mesh.mod.*.event.>`)
-// does not take — the bus refuses two streams claiming one subject, so a module's stream cannot share
-// EVENTS' — and a consumer hears it through a durable consumer of its own on that stream, named as on
-// EVENTS. Pure; the controller's raise asserts what is composed here.
-
 // moduleStreamPrefix starts every subject a module's own stream takes.
 const moduleStreamPrefix = "mesh.stream."
 
@@ -24,20 +14,6 @@ func ModuleStreamSubject(module, event string) string {
 	return moduleStreamPrefix + module + ".event." + event
 }
 
-// OnAModuleStream says a subject is one a module's own stream takes.
-func OnAModuleStream(subject string) bool { return strings.HasPrefix(subject, moduleStreamPrefix) }
-
-// WirePattern is a local event pattern as the bus spells it: `**` is `>`.
-func WirePattern(local string) string {
-	parts := strings.Split(local, ".")
-	for i, p := range parts {
-		if p == "**" {
-			parts[i] = ">"
-		}
-	}
-	return strings.Join(parts, ".")
-}
-
 // A ModuleStream is one module's declared stream as the bus holds it.
 type ModuleStream struct {
 	Module string
@@ -108,7 +84,7 @@ func (s ModuleStream) Stream() Stream {
 
 // QueueOwner is the one process of a module that is the durable consumer of one of its own work-queue
 // streams (novox/hq ADR 0436 §1, §2, §6): named in that process's bus.queues, and checked at registration
-// to be the only one (catalogue.WorkQueueStreamProblems).
+// to be the only one (the indexer's judge, novox/hq ADR 0578 §1).
 type QueueOwner struct {
 	// Process is the process resource's id — its bus account's name, with the node and module (novox/hq ADR
 	// 0436 §2).
@@ -120,33 +96,6 @@ type QueueOwner struct {
 	MaxDeliver int
 }
 
-// QueueConsumer is the durable consumer the one process a module's bus.queues names is granted on its own
-// work-queue stream (novox/hq ADR 0436 §1, §2, §6): no filter, since it is the stream's only consumer —
-// unlike heardConsumer, which is one of possibly several hearing a module's ordinary stream.
-func QueueConsumer(p Principal, q QueueOwner) Consumer {
-	return Consumer{
-		Name:           p.Node + "_" + p.Module + "_" + q.Process,
-		Stream:         q.Stream,
-		AckWaitSeconds: 30,
-		MaxDeliver:     q.MaxDeliver,
-		Why: fmt.Sprintf("%s's process %s is the one consumer %s's bus.queues names for its work-queue "+
-			"stream %s (novox/hq ADR 0436 §6); after max-deliver %d it gives a message up, and the "+
-			"controller keeps it in %s, offered only drop", p.Module, q.Process, p.Module, q.Stream,
-			q.MaxDeliver, DeadLettersStream),
-	}
-}
-
-// ModuleStreams is every declared module stream as the controller asserts it, in name order.
-func ModuleStreams(declared []ModuleStream) []Stream {
-	sorted := append([]ModuleStream(nil), declared...)
-	sort.Slice(sorted, func(i, j int) bool { return sorted[i].Name < sorted[j].Name })
-	out := make([]Stream, 0, len(sorted))
-	for _, s := range sorted {
-		out = append(out, s.Stream())
-	}
-	return out
-}
-
 // Heard is a module's stream another module hears, and the subjects it hears of it: its `consumes`
 // within the stream and, for a restricted stream, within what the provider's trusted config value grants it
 // (ADR 0363 §5). Composed only with at least one subject.
@@ -158,186 +107,3 @@ type Heard struct {
 	// is heard only by a module on an account of its own (ADR 0376 §1, ComposedHears).
 	Restricted bool
 }
-
-// ComposedHears is what of a module's hearing the controller composes (novox/hq ADR 0376 §1): every stream it
-// hears, but a restricted one only for a module that runs in a runtime of its own on a bus account of its own
-// (`runs-as`, ADR 0259). **The tool runner never hears a restricted stream**: a module it carries reaches the bus
-// through the tool runner's account, which every agent session on that machine reaches the bus as too, so a
-// consumer, its grants or its bind word composed there would hand the stream to any session. A module that
-// declares no `runs-as` and keeps its own container credential gets none either: only `runs-as` is an account
-// the mesh keeps from agents.
-func ComposedHears(d Declared) []Heard {
-	if d.RunsAs != "" {
-		return d.Hears
-	}
-	var out []Heard
-	for _, h := range d.Hears {
-		if !h.Restricted {
-			out = append(out, h)
-		}
-	}
-	return out
-}
-
-// Withheld is a restricted stream a grant gives a module that the controller composes nothing for, because the
-// module has no account of its own (novox/hq ADR 0376 §2): said in `doctor` and in the controller's log, never
-// silent.
-type Withheld struct {
-	Node, Module, Stream, Emitter string
-}
-
-// Said is a withheld hearing in the operator's words: the module, the stream and the remedy.
-func (w Withheld) Said() string {
-	return fmt.Sprintf("%s on %s is granted part of %s's restricted stream %s, and hears none of it: it is carried "+
-		"by the machine's tool runner, whose bus account every agent session there shares, so nothing is composed "+
-		"for it. Declare runs-as in %s's manifest, so it runs as an account of its own (novox/hq ADR 0376)",
-		w.Module, w.Node, w.Emitter, w.Stream, w.Module)
-}
-
-// WithheldOf is every granted hearing of a restricted stream composed for nothing, by machine and module.
-func WithheldOf(r Records) []Withheld {
-	var out []Withheld
-	for _, node := range sortedCopy(r.Nodes) {
-		for _, d := range r.Assigned[node] {
-			if d.RunsAs != "" {
-				continue
-			}
-			for _, h := range d.Hears {
-				if h.Restricted && len(h.Filters) > 0 {
-					out = append(out, Withheld{Node: node, Module: d.Module, Stream: h.Stream, Emitter: h.Emitter})
-				}
-			}
-		}
-	}
-	return out
-}
-
-// heardConsumer is the durable consumer a module hears a module's stream through: named as its consumer
-// on EVENTS, on that stream, with the subjects it was granted as its filters.
-func heardConsumer(p Principal, h Heard) Consumer {
-	filters := append([]string(nil), h.Filters...)
-	sort.Strings(filters)
-	return Consumer{
-		Name:           consumerDurable(p),
-		Stream:         h.Stream,
-		Filters:        filters,
-		AckWaitSeconds: 30,
-		MaxDeliver:     5,
-		// From now, like a module's consumer on EVENTS (novox/hq ADR 0443 §1).
-		FromNow: true,
-		Why: "what " + p.Module + " consumes of " + h.Emitter + "'s stream " + h.Stream + " and is granted " +
-			"(novox/hq ADR 0363); after max-deliver it gives an event up, and the controller keeps it in " +
-			"DEAD_LETTERS until a person delivers it again or drops it",
-	}
-}
-
-// heardGrants are what a principal publishes to read and acknowledge the consumers it hears module streams
-// through: asking about each, pulling from it, acknowledging it — its own name on each stream, no other's.
-func heardGrants(p Principal, hears []Heard) []string {
-	var out []string
-	durable := consumerDurable(p)
-	for _, h := range hears {
-		if !safeSubject.MatchString(h.Stream) || len(h.Filters) == 0 {
-			continue
-		}
-		out = append(out,
-			"$JS.API.CONSUMER.INFO."+h.Stream+"."+durable,
-			"$JS.API.CONSUMER.MSG.NEXT."+h.Stream+"."+durable,
-			"$JS.ACK."+h.Stream+"."+durable+".>")
-	}
-	return out
-}
-
-// ownStreamGrants are the subjects a module publishes its own streams' events on, and no other's.
-func ownStreamGrants(module string, streams []ModuleStream) []string {
-	var out []string
-	for _, s := range streams {
-		if s.Module != module {
-			continue
-		}
-		out = append(out, s.Subjects()...)
-	}
-	return out
-}
-
-// streamsIssuedFor is every stream of its own a module's membership names.
-func streamsIssuedFor(d Declared) []StreamIssued {
-	var out []StreamIssued
-	for _, s := range d.Streams {
-		if s.Module != d.Module || !safeSubject.MatchString(d.Module) {
-			continue
-		}
-		out = append(out, StreamIssued{Stream: s.Name, Events: append([]string(nil), s.Events...),
-			Subject: ModuleStreamSubject(d.Module, "{event}")})
-	}
-	return out
-}
-
-// HeardIssuedFor is every module stream an assignment hears, as its membership names it.
-func HeardIssuedFor(node string, d Declared) []HeardIssued {
-	var out []HeardIssued
-	// A restricted stream's bind word only for a module of its own account (novox/hq ADR 0376 §1).
-	for _, h := range ComposedHears(d) {
-		if len(h.Filters) == 0 {
-			continue
-		}
-		out = append(out, HeardIssued{Stream: h.Stream, Consumer: node + "_" + d.Module})
-	}
-	sort.Slice(out, func(i, j int) bool { return out[i].Stream < out[j].Stream })
-	return out
-}
-
-// Pruner is the part of a JetStream connection that removes a module's consumer on a module's stream it
-// may no longer hear (ADR 0363 §6). Optional: what only records what it is asked to assert has none.
-type Pruner interface {
-	ConsumerNames(stream string) ([]string, error)
-	RemoveConsumer(stream, name string) error
-}
-
-// PruneHeard removes, from each module stream, every durable consumer the composition no longer asks for,
-// and answers what it removed as `<stream>/<consumer>`. A consumer that loses its grant loses what it reads
-// through, whatever its runtime still holds; a stream that does not exist yet has nothing to remove.
-func PruneHeard(p Pruner, streams []ModuleStream, wanted []Consumer) ([]string, error) {
-	keep := map[string]bool{}
-	for _, c := range wanted {
-		keep[c.Stream+"/"+c.Name] = true
-	}
-	var removed []string
-	for _, s := range streams {
-		names, err := p.ConsumerNames(s.Name)
-		if err != nil {
-			return removed, fmt.Errorf("listing the consumers on %s: %w", s.Name, err)
-		}
-		for _, n := range names {
-			if keep[s.Name+"/"+n] {
-				continue
-			}
-			if err := p.RemoveConsumer(s.Name, n); err != nil {
-				return removed, fmt.Errorf("removing %s's consumer on %s, which is no longer granted: %w", n, s.Name, err)
-			}
-			removed = append(removed, s.Name+"/"+n)
-		}
-	}
-	return removed, nil
-}
-
-// EnsureHeard asserts a consumer on a module's stream (ADR 0363 §5, §6). **On a restricted stream, a consumer
-// the bus will not bring to match is removed**: a pull consumer delivers to whoever pulls it, so one left with
-// its wider filters after a narrowing was refused would keep handing over what the grant no longer names,
-// whatever the user list now says. The next assertion makes it again with the granted filters. The refusal is
-// returned either way, saying what was done, so the send says it and raises it.
-func EnsureHeard(r Raiser, c Consumer, restricted bool) error {
-	err := r.EnsureConsumer(c)
-	if err == nil || !restricted {
-		return err
-	}
-	p, prunes := r.(Pruner)
-	if !prunes {
-		return fmt.Errorf("%w; it could not be removed here, and may still deliver more than it is granted", err)
-	}
-	if rerr := p.RemoveConsumer(c.Stream, c.Name); rerr != nil {
-		return fmt.Errorf("%w; REMOVING IT FAILED TOO, so it may still deliver more than it is granted: %v", err, rerr)
-	}
-	return fmt.Errorf("%w; REMOVED, so it delivers nothing it is no longer granted: the next assertion makes it "+
-		"again with its granted filters (novox/hq ADR 0363 §6)", err)
-}

go/buscompose/names_test.go

@@ -0,0 +1,21 @@
+package buscompose
+
+import (
+	"testing"
+
+	"git.novox.be/novox/mesh-sdk/go/membership"
+)
+
+// The names this package keeps for the grants part's composer (mesh-grants internal/buscompose, ADR 0593 §1) agree with
+// what the runtime reads: the memberships bucket, and a log's stream and subject.
+func TestTheBusNamesAgree(t *testing.T) {
+	if GrantsMembershipsBucket != membership.GrantsBucket {
+		t.Fatalf("the memberships bucket is %q here and %q in membership", GrantsMembershipsBucket, membership.GrantsBucket)
+	}
+	if MembershipKey("ace", "netcheck") != "ace.netcheck" {
+		t.Fatal("a membership's key is not <node>.<module>")
+	}
+	if LogStreamName("mesh-delivery-builder", "build-log") == "" || LogSubject("mesh-delivery-builder", "build-log") == "" {
+		t.Fatal("a log has no stream or subject")
+	}
+}

go/buscompose/onnats.go

@@ -1,5 +0,0 @@
-package buscompose
-
-// NATSVar names the environment variable that says the controller is on the bus (mesh-controller internal/broker
-// onnats.go); kept with the composer for the readiness it composes.
-const NATSVar = "MESH_BUS_NATS"

go/buscompose/process_grants.go

@@ -1,56 +0,0 @@
-package buscompose
-
-// The bus account of one process of a module that declares bus (novox/hq ADR 0436 §1, §2, §3, §5).
-//
-// **Never the module's own account's grants, never the tool runner's.** A process's authority is read
-// straight from its bus declaration — its emits, its queue's consumer, its state, whether it reads the
-// records of its module's own asks, and the tools and seat verbs it calls — and nothing else: it holds no
-// seat, serves no tool, hears no module stream, and answers nothing a caller asked (§3). Modelled on
-// provisionerGrants, the other kind of process account the mesh mints (ADR 0349 clauses 6 and 11).
-
-// processGrants is one process's whole authority: to publish, and to subscribe.
-func processGrants(p Principal) (pub, sub []string, err error) {
-	// 1. Its own events, under its module's own namespace — the same subjects the module's own principal
-	// would publish them on, had it declared them there instead (novox/hq ADR 0436 §1).
-	own := "mesh.mod." + p.Module
-	for _, e := range p.Emits {
-		pub = append(pub, own+".event."+e)
-	}
-
-	// 2. The one durable consumer of each work-queue stream its bus names (novox/hq ADR 0436 §1, §2, §6):
-	// asked about, pulled from and acknowledged, by the same name ConsumersOf composes the consumer under
-	// (QueueConsumer) — and no other stream's.
-	for _, q := range p.Queues {
-		consumer := p.Node + "_" + p.Module + "_" + q.Process
-		pub = append(pub,
-			"$JS.API.CONSUMER.INFO."+q.Stream+"."+consumer,
-			"$JS.API.CONSUMER.MSG.NEXT."+q.Stream+"."+consumer,
-			"$JS.ACK."+q.Stream+"."+consumer+".>")
-	}
-
-	// 3. Its module's own state, by the local names its bus names alone — never the whole of what the
-	// module keeps (novox/hq ADR 0436 §1), read and written as stateGrants gives any module's own bucket.
-	kept := stateAccess{Module: p.Module, Node: p.Node, Keeps: p.State}
-	pub = append(pub, stateGrants(kept)...)
-	// And it hears each of them created, so one not on the bus at its start is bound when it appears (novox/hq issue
-	// 1790; process.AwaitBucket).
-	sub = append(sub, stateCreatedHeard(kept)...)
-
-	// 4. The router's records of its module's own asks (novox/hq ADR 0436 §1, ADR 0259 §3): the same
-	// direct-get subjects a module's own principal reads for the seats its Uses names that keep them —
-	// read here from the one list, so the two cannot disagree.
-	if p.Asks {
-		pub = append(pub, SeatTrafficOf(p.Module, nil, p.Uses, nil).Records...)
-	}
-
-	// 5. The tools and seat verbs it calls (novox/hq ADR 0152, ADR 0436 §1): the same derivation a
-	// module's own principal's invokes takes, so `callerNamed` (applied to every non-controller principal)
-	// adds the caller-named `call` variants for it exactly as it would for a module.
-	invoked, err := invokedSubjects(p.Invokes)
-	if err != nil {
-		return nil, nil, err
-	}
-	pub = append(pub, invoked...)
-
-	return pub, sub, nil
-}

go/buscompose/provisioner.go

@@ -1,217 +0,0 @@
-package buscompose
-
-import (
-	"errors"
-	"fmt"
-	"git.novox.be/novox/mesh-sdk/go/delivery"
-	"strings"
-
-	"github.com/nats-io/nats.go"
-)
-
-// The provisioner client's own bus account (novox/hq ADR 0349 clauses 6 and 11, design 57 package P3).
-//
-// **Not the tool runner's account.** The client fills a machine's files and asks the vault for the secrets that
-// machine's declaration names; the vault hands a secret only to an account of its own, because a call under the
-// tool runner's account cannot be told from an agent's on that machine (ADR 0305 §3, §12). So each machine that
-// runs the client has a principal of its own, KindProvisioner, named for the machine, and granted what the client
-// does and nothing else: read its own machine's keys in each domain's bucket, write its own machine's keys of the
-// provisioner server's needs, applied and collections (design 57 P4), read the server's registry, say what it
-// applied on its own machine, and ask the vault in its own name.
-
-// NodeProvisionerSeat is the seat the provisioner client holds on every machine (ADR 0349 clause 3).
-const NodeProvisionerSeat = "node-provisioner"
-
-// ProvisionerSecret is the own secret of the module running the client that its bus account is delivered in, as
-// `broker` is a module's own (novox/hq issue 195): a module that claims NodeProvisionerSeat and declares no own
-// secret of this name has nowhere to read an account, and is given none.
-const ProvisionerSecret = "provisioner-broker"
-
-// ConfigResolvedBucket is the config domain's resolved values, keyed `<node>.<module>.<key>` (ADR 0348, research
-// 051): mesh-config's state `resolved`, written by mesh-config alone.
-var ConfigResolvedBucket = BucketName("mesh-config", "resolved")
-
-// ProvisionerReads are the domains' buckets a provisioner client reads its own machine's keys of, each keyed
-// `<node>.…` (research 051): placement, the controller's assignments mirror (`<node>.<module>`), whose value carries
-// the provisioner's plan of a module handed to it (inventory.Provisioning, design 57 P5); and config,
-// mesh-config's resolved values. **Named one by one**, as the controller's asks are: a domain that moves to the
-// provisioner adds its bucket here, and a bucket not named is one the client cannot read.
-var ProvisionerReads = []string{ConfigResolvedBucket}
-
-// ProvisionerReadsWhole are the buckets a provisioner client reads every key of: the controller's assignments mirror,
-// where a provider's consumers are bound to it in their own machines' plans, which the provider machine's client
-// reads to fill ${consumers:<provision>} with each one's credential (novox/hq ADR 0373, issue 679). It holds placement
-// and plans, never a secret's value; the client writes none of it.
-var ProvisionerReadsWhole = []string{AssignmentsBucket}
-
-// BoundState is a providing module's state of entries, one per consumer (mesh-sdk go/provider, issue 678): a
-// consumer's machine's client reads its own keys of it, `<node>.<module>.<provision>[.<local>]`, to fill
-// ${bound:<provision>:<key>} (issue 679).
-const BoundState = "bound"
-
-// ProvisionerServerModule is the module holding the seat mesh-provisioner once for the mesh (ADR 0349 clause 3,
-// design 57 P4), whose buckets the clients write their own machine's keys of.
-const ProvisionerServerModule = "mesh-provisioner"
-
-// The provisioner server's buckets (ADR 0349 clause 3): its state, created by the controller from its manifest
-// like any module's, and written by its own account whole.
-var (
-	// ProvisionerRegistryBucket is which domain answers which kind of placeholder, keyed by the kind; the
-	// server's alone, read whole by every client.
-	ProvisionerRegistryBucket = BucketName(ProvisionerServerModule, "registry")
-	// ProvisionerNeedsBucket is what each module on each machine needs, `<node>.<module>.<kind>.<name>`.
-	ProvisionerNeedsBucket = BucketName(ProvisionerServerModule, "needs")
-	// ProvisionerAppliedBucket is what is applied where, `<node>.<module>`.
-	ProvisionerAppliedBucket = BucketName(ProvisionerServerModule, "applied")
-	// ProvisionerCollectBucket is the items of every collection, `<node>.<collection>.<contributor>`.
-	ProvisionerCollectBucket = BucketName(ProvisionerServerModule, "collect")
-)
-
-// ProvisionerWrites are the server's buckets a client writes, and reads, its own machine's keys of (`<node>.>`)
-// and no other's: the needs it records, what it applied, and the items of the collections on its machine. A
-// client cannot write another machine's needs, or say another machine applied a file.
-var ProvisionerWrites = []string{ProvisionerNeedsBucket, ProvisionerAppliedBucket, ProvisionerCollectBucket}
-
-// VerbsTheProvisionerAsksTheVault are the vault's verbs a provisioner client asks in its own name (ADR 0349
-// clause 11): `get`, a secret its machine's declaration names, answered sealed to the asker's key. On the subject
-// that names its caller, so the vault knows which machine's client asks from the bus's word.
-var VerbsTheProvisionerAsksTheVault = []SeatVerb{{Seat: "mesh-vault", Verb: "get"}}
-
-// VaultSecretChangedSubject is where the vault says a secret it holds changed (`secret-changed`: which, by whom,
-// when, its generation; never a value, ADR 0349 clause 11), as link.EventSubject addresses mesh-vault's event. A
-// provisioner client listens to it so a rotated secret reaches its file without a new declaration (design 57 V4):
-// it asks the vault again, in its own name, for a secret its machine's declaration names.
-const VaultSecretChangedSubject = "mesh.mod.mesh-vault.event.secret-changed"
-
-// ProvisionerAppliedSubject is where a machine's client says what it applied for one module, applied or failed
-// with the reason (ADR 0349 clauses 4 and 15): `prov.applied.<node>.<module>`.
-func ProvisionerAppliedSubject(node, module string) string {
-	return "prov.applied." + node + "." + module
-}
-
-// ProvisionerAskSubject is where a machine's tool runner asks that machine's provisioner client for a config value
-// or a non-secret bound value of a module it carries, naming the module from the bundle that asks (novox/hq ADR
-// 0370 §1, §3, §4; issue 685): `prov.ask.<node>`, which the client subscribes and the tool runner's account of the
-// same machine alone may publish. The bus proves only that the tool runner asks; the module is the runtime's word,
-// so the client answers no secret here (ADR 0370 §2).
-func ProvisionerAskSubject(node string) string { return "prov.ask." + node }
-
-// ProvisionerChangedSubject is where a machine's client says that a value of one module it answers moved, so the
-// tool runner asks again for the module's code's watches (ADR 0349 §14, ADR 0370 §1): `prov.changed.<node>.<module>`,
-// carrying which value and never the value itself, heard by that machine's tool runner alone.
-func ProvisionerChangedSubject(node, module string) string {
-	return "prov.changed." + node + "." + module
-}
-
-// provisionerGrants is a provisioner client's whole authority: to publish, and to subscribe.
-func provisionerGrants(p Principal) (pub, sub []string, err error) {
-	if p.Node == "" {
-		// Refused rather than composed into `$KV.<bucket>..>`, a pattern no machine's keys are under, and a
-		// name every nameless client would share.
-		return nil, nil, errors.New("a provisioner client names no machine, so it would have no keys of its own " +
-			"to read and an account it shared with every other")
-	}
-	for _, bucket := range ProvisionerReads {
-		pub = append(pub, machineKeysRead(bucket, p.Node)...)
-	}
-	for _, bucket := range ProvisionerReadsWhole {
-		pub = append(pub, wholeBucketRead(bucket)...)
-	}
-	for _, bucket := range p.BoundBuckets {
-		module, name, ok := strings.Cut(bucket, "_")
-		if !ok || name != BoundState || !safeSubject.MatchString(module) || strings.Contains(module, "_") {
-			return nil, nil, fmt.Errorf("%q is not a provider's bucket of entries, <module>_%s", bucket, BoundState)
-		}
-		pub = append(pub, machineKeysRead(bucket, p.Node)...)
-	}
-	// The server's buckets (design 57 P4): its own machine's keys of the needs, the applied and the
-	// collections, read and written, `$KV.<bucket>.<node>.>` and nothing wider; and the registry, read whole,
-	// which says which domain answers which kind and is the same for every machine.
-	for _, bucket := range ProvisionerWrites {
-		pub = append(pub, machineKeysRead(bucket, p.Node)...)
-		pub = append(pub, "$KV."+bucket+"."+p.Node+".>")
-	}
-	pub = append(pub, wholeBucketRead(ProvisionerRegistryBucket)...)
-	// Its own node's own have, `<node>.node`, read and never written, and no other key of the bucket: it fills every
-	// module again when the node-engine moves to a new composition of the node's own (issue 1945), since an apply can
-	// leave a filled file as the composition had it.
-	pub = append(pub, readGrants(delivery.HaveBucket, p.Node+".node")...)
-	pub = append(pub, "prov.applied."+p.Node+".>")
-	token := CallerToken(p.Username())
-	if token == "" {
-		return nil, nil, fmt.Errorf("%q cannot name a caller", p.Username())
-	}
-	for _, v := range VerbsTheProvisionerAsksTheVault {
-		pub = append(pub, "mesh.seat."+v.Seat+"."+CallKind+"."+v.Verb+"."+token)
-	}
-	// What moved of a value it answers its own machine's tool runner (ADR 0370 §1), under its own machine's name.
-	pub = append(pub, "prov.changed."+p.Node+".>")
-	// Its own reply space, for the vault's answers and its reads' and watches' deliveries; what the vault says
-	// changed; and its own machine's tool runner asking it for a module's config and non-secret bound values (ADR
-	// 0370 §3), which it answers on the ask's reply and nowhere else.
-	return pub, []string{p.inbox(), VaultSecretChangedSubject, ProvisionerAskSubject(p.Node)}, nil
-}
-
-// machineKeysRead is reading every key of a bucket under one machine's name, `<node>.>`, and no other key: a
-// direct get of a key's own subject, and a consumer whose filter is under it — the server's create-with-filter
-// form, which it holds to the filter the subject names (as stateGrants does for one key, novox/hq ADR 0260).
-// Binding, deleting a consumer and flow control cannot be narrowed by key and read no value.
-func machineKeysRead(bucket, node string) []string {
-	stream := "KV_" + bucket
-	keys := "$KV." + bucket + "." + node + ".>"
-	return []string{
-		"$JS.API.STREAM.INFO." + stream,
-		"$JS.API.DIRECT.GET." + stream + "." + keys,
-		"$JS.API.CONSUMER.CREATE." + stream + ".*." + keys,
-		"$JS.API.CONSUMER.DELETE." + stream + ".>",
-		"$JS.FC." + stream + ".>",
-	}
-}
-
-// wholeBucketRead is reading every key of a bucket and writing none: what stateGrants grants a module for a
-// bucket it `reads`.
-func wholeBucketRead(bucket string) []string {
-	stream := "KV_" + bucket
-	return []string{
-		"$JS.API.STREAM.INFO." + stream,
-		"$JS.API.DIRECT.GET." + stream + ".>",
-		"$JS.API.CONSUMER.CREATE." + stream + ".>",
-		"$JS.API.CONSUMER.DELETE." + stream + ".>",
-		"$JS.FC." + stream + ".>",
-	}
-}
-
-// LastProvApplied is what a machine's provisioner client last said of one module's files, as it published it on
-// ProvisionerAppliedSubject and ProvAppliedStream keeps it (design 57 P6): false when it has said nothing of it in
-// the stream's week.
-func LastProvApplied(js nats.JetStreamContext, node, module string) ([]byte, bool, error) {
-	msg, err := js.GetLastMsg(ProvAppliedStream, ProvisionerAppliedSubject(node, module))
-	if errors.Is(err, nats.ErrMsgNotFound) {
-		return nil, false, nil
-	}
-	if err != nil {
-		return nil, false, fmt.Errorf("what %s's provisioner client said of %s cannot be read: %w", node, module, err)
-	}
-	return msg.Data, true, nil
-}
-
-// ProvAppliedReports is the newest word of every machine's provisioner client on every module it said one of, kept by
-// ProvAppliedStream, by subject (`prov.applied.<node>.<module>`).
-func ProvAppliedReports(js nats.JetStreamContext) (map[string][]byte, error) {
-	info, err := js.StreamInfo(ProvAppliedStream, &nats.StreamInfoRequest{SubjectsFilter: ProvAppliedSubjects})
-	if err != nil {
-		return nil, fmt.Errorf("the provisioner clients' reports cannot be listed: %w", err)
-	}
-	out := map[string][]byte{}
-	for subject := range info.State.Subjects {
-		msg, err := js.GetLastMsg(ProvAppliedStream, subject)
-		if errors.Is(err, nats.ErrMsgNotFound) {
-			continue // aged out between the two reads
-		}
-		if err != nil {
-			return nil, fmt.Errorf("the provisioner client's report on %s cannot be read: %w", subject, err)
-		}
-		out[subject] = msg.Data
-	}
-	return out, nil
-}

go/buscompose/raise.go

@@ -1,73 +0,0 @@
-package buscompose
-
-import "fmt"
-
-// Bringing the bus's own objects into being, in the one order that works.
-//
-// **Asserted on every start rather than created once at genesis.** A stream somebody deleted, a mesh
-// raised from a restored backup, or a bus whose data directory was replaced all have records and no
-// objects — and a node whose consumer is missing hears nothing while everything else about it looks
-// correct. Idempotence is the whole requirement, and the parts are already idempotent; this is the
-// order they have to be asked in.
-
-// Raiser is everything asserting the bus's objects needs of a connection to it.
-type Raiser interface {
-	Asserter
-	Ensurer
-}
-
-// Raise asserts the mesh's streams, the controller's own consumers, and one consumer per node.
-//
-// **The order is not a preference.** A consumer on a stream that does not exist is refused, and the
-// refusal names the stream rather than the order — so somebody reading it goes looking for a deleted
-// stream instead of a reversed pair of lines. Nodes last, because the one a node reads lives on a
-// stream the mesh's own set defines.
-func Raise(r Raiser, nodes []string) error {
-	if err := AssertMeshStreams(r); err != nil {
-		return err
-	}
-	if err := AssertMeshConsumers(r); err != nil {
-		return err
-	}
-	if err := AssertNodeConsumers(r, nodes); err != nil {
-		return err
-	}
-	return nil
-}
-
-// RaiseSeats asserts one work queue per declared seat, and the worker of whoever holds it.
-//
-// Separate from Raise because it is answered by a different question: the mesh's own objects exist
-// because the mesh does, and a seat's exist because a module declaring one was registered. Kept
-// beside it so the order is visible — a holder's worker needs the seat's stream, and a seat's stream
-// needs nothing.
-func RaiseSeats(r Raiser, seats []DeclaredSeat, holders map[string]Holder) error {
-	for _, s := range SeatStreams(seats) {
-		if err := r.EnsureStream(s); err != nil {
-			return fmt.Errorf("asserting the work queue for %s: %w", s.Name, err)
-		}
-	}
-	for _, s := range seats {
-		h, held := holders[s.Name]
-		if !held {
-			// **The stream exists and the consumer does not, on purpose.** Work queues until a
-			// holder appears, so installing the module a week after something started sending to it
-			// flushes the backlog instead of having lost it.
-			continue
-		}
-		c, needed := HolderConsumerFor(h.Node, h.Module, s)
-		if !needed {
-			continue
-		}
-		if err := r.EnsureConsumer(c); err != nil {
-			return fmt.Errorf("asserting how %s on %s works %s: %w", h.Module, h.Node, s.Name, err)
-		}
-	}
-	return nil
-}
-
-// Holder is which module on which machine holds a seat.
-type Holder struct {
-	Node   string
-	Module string
-}