Merge remote-tracking branch 'origin/main' into feat/files-through-the-store-files-verbs

A declaration is one bus message and the control node's passed the limit by 2 KB. The size is checked at every send
against the connection's own limit, with a condition from 90% and a message naming size and limit when over; the
export, 138 KB compact of 165 KB indented, is sent compact.

cmd/mesh-controller/batches.go

@@ -3,6 +3,7 @@ package main
 import (
 	"context"
 	"encoding/json"
+	"errors"
 	"fmt"
 	"os"
 	"slices"
@@ -170,6 +171,21 @@ func (f mergeFacts) plans() bool {
 	return len(f.from) > 0 || len(f.packaging) > 0 || len(f.later) > 0 || f.owed
 }
 
+// heldMerge marks a failure to act on a merge, whatever it was, as "not now": the announcement is held on the bus and
+// handed over again, so the merge joins the next batch, never taken (issue 1583, after 921). The bus acknowledges it
+// only when hearMerge answers without ErrTryAgain, and a merge heard once is not announced again: the bus answering
+// "jetstream not enabled", a bucket missing for a moment or a store read cut short each lost the merge when only an
+// outage of a known kind (notNow) was held. The delay between hands-over is bounded (link.MergeRedeliverAfter).
+func heldMerge(err error) error {
+	if err == nil {
+		return nil
+	}
+	if errors.Is(err, link.ErrTryAgain) {
+		return err
+	}
+	return fmt.Errorf("%w: the merge is not kept yet: %w", link.ErrTryAgain, err)
+}
+
 // hearMerge puts a merge the forge announced into the batch that answers it, at the moment it was heard,
 // and cuts what is due.
 func (f following) hearMerge(ctx context.Context, m link.SourceMoved, now time.Time) error {
@@ -180,7 +196,7 @@ func (f following) hearMerge(ctx context.Context, m link.SourceMoved, now time.T
 	inv := f.open.inventory
 	repository := m.Owner + "/" + m.Repo
 	if kept, known, err := inv.MergeOf(ctx, repository, m.Commit); err != nil {
-		return notNow(err)
+		return heldMerge(err)
 	} else if known {
 		fmt.Printf("%s merged into %s (%.8s) was heard before; %s answers it\n", repository, m.Base, m.Commit,
 			orWords(kept.Plan, "a walk of its own commit, once the walks before it end"))
@@ -188,15 +204,15 @@ func (f following) hearMerge(ctx context.Context, m link.SourceMoved, now time.T
 	}
 	entries, err := inv.Catalogued(ctx)
 	if err != nil {
-		return notNow(err)
+		return heldMerge(err)
 	}
 	read, err := readForPlanning(ctx, inv)
 	if err != nil {
-		return notNow(err)
+		return heldMerge(err)
 	}
 	facts, err := factsOfMerge(ctx, inv, m, now, entries, read)
 	if err != nil {
-		return notNow(err)
+		return heldMerge(err)
 	}
 	merged, touches := facts.merged, facts.touches
 	if !facts.plans() {
@@ -210,26 +226,28 @@ func (f following) hearMerge(ctx context.Context, m link.SourceMoved, now time.T
 		}
 		if already == 0 {
 			if done, err := f.firstBuilds(ctx, m, entries, read, now); err != nil || done {
-				return err
+				return heldMerge(err)
 			}
 		}
 		fmt.Print(nothingReadsIt(repository, m))
 		return nil
 	}
+	// **A module the merge adds is asked for now** (novox/hq issue 1617), not when the batch is cut.
+	askNewModulesAtHearing(ctx, inv, m, entries, read, facts.from)
 	// **Its delivery group's word, before the plans are held** (ADR 0306 decision 2): a slow answer holds up no walk.
 	own := ownPath(touches)
 	waits, holding, err := groupWaitHolding(ctx, inv, m, deliverySeatHeld(entries))
 	if err != nil {
-		return notNow(err)
+		return heldMerge(err)
 	}
 	release, err := inv.HoldPlans(ctx, true)
 	if err != nil {
-		return notNow(err)
+		return heldMerge(err)
 	}
 	defer release()
 	// Again under the hold: a controller handing over may have kept it since.
 	if _, known, err := inv.MergeOf(ctx, repository, m.Commit); err != nil || known {
-		return notNow(err)
+		return heldMerge(err)
 	}
 	var moves []string
 	for _, e := range touches {
@@ -248,11 +266,11 @@ func (f following) hearMerge(ctx context.Context, m link.SourceMoved, now time.T
 	// word** (decided during the build, 2026-10-10): batched together, the catalogue's deliveries would start
 	// with the controller's and skip their turn. Each kind has a batch of its own.
 	if p, ok, err := answeredByALaterMerge(ctx, inv, heard, touches, own, deliverySeatHeld(entries)); err != nil {
-		return notNow(err)
+		return heldMerge(err)
 	} else if ok {
 		heard.Plan = p.ID
 		if _, err := inv.AddMerge(ctx, heard); err != nil {
-			return notNow(err)
+			return heldMerge(err)
 		}
 		if p.Batch() {
 			if err := keepBatch(ctx, inv, &p, now, ""); err != nil {
@@ -268,11 +286,11 @@ func (f following) hearMerge(ctx context.Context, m link.SourceMoved, now time.T
 
 	batch, why, err := batchToJoin(ctx, inv, heard, entries, read, now, own, waits)
 	if err != nil {
-		return notNow(err)
+		return heldMerge(err)
 	}
 	heard.Plan = batch.ID
 	if added, err := inv.AddMerge(ctx, heard); err != nil || !added {
-		return notNow(err)
+		return heldMerge(err)
 	}
 	holdFor(&batch, m.Head, waits, holding, own, now)
 	if err := keepBatch(ctx, inv, &batch, now, ""); err != nil {

cmd/mesh-controller/compose_sdk.go

@@ -366,7 +366,7 @@ func sayFound(ctx context.Context, d compose.Declared) {
 
 // sendableOf is a composed declaration as the controller's sends know it.
 func sendableOf(d compose.Declared) sendable {
-	out := sendable{Resources: d.Resources, Sequence: d.Sequence, Epoch: d.Epoch, Generation: d.Generation,
+	out := sendable{Resources: compactKept(d.Resources), Sequence: d.Sequence, Epoch: d.Epoch, Generation: d.Generation,
 		ReadsModules: d.ReadsModules, moduleOf: d.ModuleOf, buildIDs: d.BuildIDs, modules: d.Modules,
 		localNetwork: d.LocalNetwork, Received: d.Received, Mesh: d.Mesh, BusUsers: d.BusUsers,
 		LeftOut: d.LeftOut, leftOutWhy: d.LeftOutWhy, withheld: d.Withheld, unbound: d.Unbound, foreseen: d.Foreseen,

cmd/mesh-controller/container_groups_test.go

@@ -0,0 +1,65 @@
+package main
+
+import (
+	"io"
+	"os"
+	"strings"
+	"testing"
+
+	"git.novox.be/novox/mesh-sdk/go/catalogue"
+)
+
+// Issue 1638 (novox/hq ADR 0480 clause 7), taken in with mesh-sdk's container `groups`: the controller sends a container's
+// groups only to a node-engine that reports the capability container-groups, and holds the module on any other, naming it.
+
+const n8nWithAGroup = `{"module":"n8n","version":"1",
+  "config":{"media-gid":{"type":"number","minimum":1,"required":true,"description":"the group that owns the media library"}},
+  "resources":[{"id":"server","type":"container","name":"n8n",
+    "image":"n8nio/n8n@sha256:4846eb2f4b874ab04cde7fc1e249d2ddaec66e9aea64439beb2972cfea88e3c0",
+    "groups":["${config:media-gid}"]}]}`
+
+// printedBy runs reportUnhostable and returns what it printed.
+func printedBy(t *testing.T, node string, plan catalogue.Resolution) string {
+	t.Helper()
+	stdout := os.Stdout
+	r, w, err := os.Pipe()
+	if err != nil {
+		t.Fatal(err)
+	}
+	os.Stdout = w
+	reportUnhostable(node, plan)
+	w.Close()
+	os.Stdout = stdout
+	out, _ := io.ReadAll(r)
+	return string(out)
+}
+
+// 1638/AC1: a node that reports the capability gets the module; one that does not has it held, the capability named.
+func TestAModuleWithGroupsIsHeldOnANodeThatDoesNotReportTheCapability(t *testing.T) {
+	m, err := catalogue.ParseManifest([]byte(n8nWithAGroup))
+	if err != nil {
+		t.Fatal(err)
+	}
+	shelf := catalogue.Shelf{"n8n": m}
+	reads := catalogue.Node{Name: "ace", Capabilities: map[string]bool{"container-runtime": true, "container-groups": true}}
+	old := catalogue.Node{Name: "g14", Capabilities: map[string]bool{"container-runtime": true}}
+
+	got, err := catalogue.Resolve(shelf, []string{"n8n"}, reads, catalogue.World{})
+	if err != nil || len(got.Unhostable) != 0 || len(got.Modules) != 1 {
+		t.Fatalf("a node that reads groups: %v, held %+v", err, got.Unhostable)
+	}
+	if out := printedBy(t, "ace", got); out != "" {
+		t.Errorf("a node that reads groups was told: %q", out)
+	}
+
+	got, err = catalogue.Resolve(shelf, []string{"n8n"}, old, catalogue.World{})
+	if err != nil {
+		t.Fatal(err)
+	}
+	if len(got.Modules) != 0 || len(got.Unhostable) != 1 {
+		t.Fatalf("n8n was sent to a node that does not report container-groups: hosted %d, held %+v", len(got.Modules), got.Unhostable)
+	}
+	if out := printedBy(t, "g14", got); !strings.Contains(out, "n8n") || !strings.Contains(out, "container-groups") {
+		t.Errorf("the hold does not name the module and the capability: %q", out)
+	}
+}

cmd/mesh-controller/declaration_room.go

@@ -0,0 +1,96 @@
+package main
+
+import (
+	"bytes"
+	"context"
+	"encoding/json"
+	"fmt"
+	"strings"
+
+	"github.com/novox/mesh-controller/internal/conditions"
+	"github.com/novox/mesh-controller/internal/link"
+)
+
+// **A declaration is one bus message, and the bus's largest message is a cliff** (novox/hq issue 1689). On 2026-10-21
+// the control node's declaration passed it by 2 KB and nothing reached that node until two assignments were undone.
+// So the size is measured at every send: a warning condition from 90% of the limit, urgent over it, cleared when
+// the declaration is back under 90%. The limit is the connection's own, not a constant.
+
+// kindDeclarationNearLimit is a declaration at or near the bus's largest message.
+const kindDeclarationNearLimit = "declaration-near-limit"
+
+// declarationRoomSource is the condition's source: the sends.
+const declarationRoomSource = "sends"
+
+func declarationRoomObservation(node string, size, limit int64) conditions.Observation {
+	o := conditions.Observation{Scope: conditions.ScopeMachine, ID: node, Kind: kindDeclarationNearLimit,
+		Token: kindDeclarationNearLimit, Machine: node, Severity: conditions.Warning, Source: declarationRoomSource}
+	if size > limit {
+		o.Severity = conditions.Urgent
+	}
+	o.Summary = fmt.Sprintf("%s's declaration is %d bytes on the wire, %d%% of the bus's largest message of %d bytes",
+		node, size, size*100/limit, limit)
+	if size > limit {
+		o.Summary += ": over it, so it cannot be sent"
+	}
+	return o
+}
+
+func init() {
+	link.DeclarationMeasured = func(ctx context.Context, node string, size, limit int64) {
+		settleDeclarationRoom(ctx, conditionsFrom, node, size, limit)
+	}
+}
+
+// settleDeclarationRoom raises or clears the condition of a declaration's size. A nil keeper (a tool, not the
+// serving controller) says nothing.
+func settleDeclarationRoom(ctx context.Context, keeper *conditions.Keeper, node string, size, limit int64) {
+	if keeper == nil || limit <= 0 {
+		return
+	}
+	obs := declarationRoomObservation(node, size, limit)
+	if float64(size) < link.NearTheLimit*float64(limit) {
+		if _, err := keeper.Clear(ctx, obs.Key(), fmt.Sprintf("%s's declaration is %d bytes, under the limit's margin", node, size)); err != nil {
+			fmt.Printf("the condition %s could not be cleared: %v\n", obs.Key(), err)
+		}
+		return
+	}
+	fmt.Printf("NEAR THE LIMIT: %s\n", obs.Summary)
+	if _, err := keeper.Observe(ctx, obs); err != nil {
+		fmt.Printf("the condition %s could not be raised: %v\n", obs.Key(), err)
+	}
+}
+
+// compactKept writes the vault's export compact. The composition (the SDK's keptFile) writes it indented, and its 334
+// sealed secrets were 164,763 bytes of it against 138,474 compact: a fifth of the declaration's room, in whitespace,
+// base64-encoded again on the wire. Every reader parses JSON, so the spacing is nobody's. A resource that is not
+// the export, or whose content is not JSON, is left as it is. The resources are copied, never changed in place.
+func compactKept(resources []map[string]any) []map[string]any {
+	out := make([]map[string]any, len(resources))
+	for i, r := range resources {
+		out[i] = r
+		id, _ := r["id"].(string)
+		path, _ := r["path"].(string)
+		content, ok := r["content"].(string)
+		if !ok || (id != "kept" && !strings.HasSuffix(id, ".kept")) || !strings.HasSuffix(path, "/export.json") {
+			continue
+		}
+		var dst bytes.Buffer
+		if json.Compact(&dst, []byte(content)) != nil {
+			continue
+		}
+		if strings.HasSuffix(content, "\n") {
+			dst.WriteByte('\n')
+		}
+		if dst.String() == content {
+			continue
+		}
+		c := make(map[string]any, len(r))
+		for k, v := range r {
+			c[k] = v
+		}
+		c["content"] = dst.String()
+		out[i] = c
+	}
+	return out
+}

cmd/mesh-controller/declaration_room_test.go

@@ -0,0 +1,71 @@
+package main
+
+import (
+	"strings"
+	"testing"
+	"time"
+
+	"github.com/novox/mesh-controller/internal/conditions"
+)
+
+// The vault's export is sent compact (issue 1689): same document, no indentation, one rewrite.
+func TestTheVaultsExportIsSentCompactAndNothingElseIsTouched(t *testing.T) {
+	indented := "{\n  \"export\": 1,\n  \"kept\": [\n    {\n      \"name\": \"a\"\n    }\n  ]\n}\n"
+	other := "{\n  \"x\": 1\n}\n"
+	in := []map[string]any{
+		{"id": "mesh-vault.kept", "type": "file", "path": "/srv/vault/export.json", "mode": "0600", "content": indented},
+		{"id": "mesh-vault.config", "type": "file", "path": "/srv/vault/config.json", "content": other},
+		{"id": "other.kept", "type": "file", "path": "/srv/other/notes.json", "content": other},
+	}
+	out := compactKept(in)
+	want := "{\"export\":1,\"kept\":[{\"name\":\"a\"}]}\n"
+	if out[0]["content"] != want || out[0]["mode"] != "0600" || out[0]["path"] != "/srv/vault/export.json" {
+		t.Fatalf("the export is %q (%v), expected %q with its mode and path kept", out[0]["content"], out[0], want)
+	}
+	if out[1]["content"] != other || out[2]["content"] != other {
+		t.Fatalf("a file that is not the export was rewritten: %v %v", out[1], out[2])
+	}
+	if in[0]["content"] != indented {
+		t.Fatalf("the composed resource was changed in place")
+	}
+	if again := compactKept(out); again[0]["content"] != want {
+		t.Fatalf("compacting twice changed it: %q", again[0]["content"])
+	}
+}
+
+// From 90% of the bus's largest message the declaration is a warning; over it, urgent; back under 90%, cleared.
+func TestADeclarationNearTheBusLimitRaisesAConditionAndClearsWhenSmaller(t *testing.T) {
+	store := conditions.NewInMemory()
+	k := conditions.NewKeeper(t.Context(), conditions.Options{Store: store, History: store,
+		Teller: &conditions.Told{}, Now: func() time.Time { return time.Date(2026, 10, 21, 14, 0, 0, 0, time.UTC) }})
+	t.Cleanup(func() { k.Close(t.Context()) })
+	const limit = 1000
+	key := declarationRoomObservation("novox", 0, limit).Key()
+	read := func() (conditions.Condition, bool) {
+		t.Helper()
+		c, found, err := conditions.ReadOne(t.Context(), store, key)
+		if err != nil {
+			t.Fatal(err)
+		}
+		return c, found
+	}
+
+	settleDeclarationRoom(t.Context(), k, "novox", 899, limit)
+	if _, found := read(); found {
+		t.Fatal("a declaration at 89.9% raised a condition")
+	}
+	settleDeclarationRoom(t.Context(), k, "novox", 900, limit)
+	c, found := read()
+	if !found || c.Severity != conditions.Warning || !strings.Contains(c.Summary, "900 bytes") ||
+		!strings.Contains(c.Summary, "1000") || c.Subject.Machine != "novox" {
+		t.Fatalf("at 90%% the condition is %v %+v", found, c)
+	}
+	settleDeclarationRoom(t.Context(), k, "novox", 1001, limit)
+	if c, _ := read(); c.Severity != conditions.Urgent {
+		t.Fatalf("over the limit the condition is %q, expected urgent", c.Severity)
+	}
+	settleDeclarationRoom(t.Context(), k, "novox", 850, limit)
+	if _, found := read(); found {
+		t.Fatal("the condition stayed after the declaration fell under 90%")
+	}
+}

cmd/mesh-controller/loop_own_consumers_test.go

@@ -0,0 +1,86 @@
+package main
+
+import (
+	"strings"
+	"testing"
+	"time"
+
+	"github.com/novox/mesh-controller/internal/broker"
+)
+
+// holding reports one message held by each named consumer (stream/name), nothing by the rest.
+func holdingOne(names ...string) func(broker.Consumer) (uint64, error) {
+	return func(c broker.Consumer) (uint64, error) {
+		for _, n := range names {
+			if n == c.Stream+"/"+c.Name {
+				return 1, nil
+			}
+		}
+		return 0, nil
+	}
+}
+
+func deafObservations(now time.Time, held func(broker.Consumer) (uint64, error)) (string, int) {
+	f := calm(now)
+	loop, err := readLoop(now.Add(-loopDeafAfter-time.Minute), loopConsumers(), held)
+	if err != nil {
+		panic(err)
+	}
+	f.loop = loop
+	obs := watchLoop(f)
+	if len(obs) == 0 {
+		return "", 0
+	}
+	return obs[0].Said, len(obs)
+}
+
+// 1063/AC1: a check in flight on a builder is not the controller's event loop being deaf.
+func TestDeafLookIgnoresCheckWorkers(t *testing.T) {
+	now := time.Now()
+	for _, w := range broker.CheckWorkers() {
+		if said, n := deafObservations(now, holdingOne(w.Stream+"/"+w.Name)); n != 0 {
+			t.Fatalf("%s holding one message raised controller-deaf: %s", w.Name, said)
+		}
+	}
+}
+
+// 1063/AC2: a message held by one of the controller's own consumers is still deaf, naming its stream.
+func TestDeafLookStillCountsOwnConsumers(t *testing.T) {
+	now := time.Now()
+	for _, c := range loopConsumers() {
+		said, n := deafObservations(now, holdingOne(c.Stream+"/"+c.Name))
+		if n != 1 || !strings.Contains(said, "1 on "+c.Stream) {
+			t.Fatalf("%s/%s holding one message: %d observation(s), said %q", c.Stream, c.Name, n, said)
+		}
+	}
+}
+
+// 1063/AC3: the list is the controller's consumers and none of the check workers.
+func TestDeafLookReadsExactlyTheControllersOwnConsumers(t *testing.T) {
+	workers := map[string]bool{}
+	for _, w := range broker.CheckWorkers() {
+		workers[w.Stream+"/"+w.Name] = true
+	}
+	want := map[string]bool{}
+	for _, c := range broker.MeshConsumers() {
+		if !workers[c.Stream+"/"+c.Name] {
+			want[c.Stream+"/"+c.Name] = true
+		}
+	}
+	got := map[string]bool{}
+	for _, c := range loopConsumers() {
+		k := c.Stream + "/" + c.Name
+		if workers[k] {
+			t.Errorf("the deaf look reads the check worker %s", k)
+		}
+		got[k] = true
+	}
+	if len(got) != len(want) {
+		t.Fatalf("deaf look reads %v, want %v", got, want)
+	}
+	for k := range want {
+		if !got[k] {
+			t.Errorf("the deaf look does not read %s", k)
+		}
+	}
+}

cmd/mesh-controller/merge_bus_error_integration_test.go

@@ -0,0 +1,75 @@
+//go:build integration
+
+package main
+
+import (
+	"context"
+	"errors"
+	"sync/atomic"
+	"testing"
+	"time"
+
+	"github.com/nats-io/nats.go"
+
+	"github.com/novox/mesh-controller/internal/chain"
+	"github.com/novox/mesh-controller/internal/link"
+)
+
+// withoutJetStream is a bucket whose reads fail the way a bus answers while its streams are away.
+type withoutJetStream struct {
+	chain.Backend
+	away atomic.Bool
+}
+
+func (w *withoutJetStream) Get(ctx context.Context, key string) (chain.Entry, bool, error) {
+	if w.away.Load() {
+		return chain.Entry{}, false, nats.ErrJetStreamNotEnabled
+	}
+	return w.Backend.Get(ctx, key)
+}
+
+func (w *withoutJetStream) Keys(ctx context.Context) ([]string, error) {
+	if w.away.Load() {
+		return nil, nats.ErrJetStreamNotEnabled
+	}
+	return w.Backend.Keys(ctx)
+}
+
+func (w *withoutJetStream) Watch(ctx context.Context) (<-chan chain.Entry, error) {
+	if w.away.Load() {
+		return nil, nats.ErrJetStreamNotEnabled
+	}
+	return w.Backend.Watch(ctx)
+}
+
+func (w *withoutJetStream) WatchFiltered(ctx context.Context, filter string) (<-chan chain.Entry, error) {
+	if w.away.Load() {
+		return nil, nats.ErrJetStreamNotEnabled
+	}
+	return w.Backend.WatchFiltered(ctx, filter)
+}
+
+// **A merge heard while the bus answers "jetstream not enabled" is held, recorded nowhere, and recorded when handed
+// over again** (issue 1583, mesh-catalog #404): hearMerge answers ErrTryAgain, so the bus does not acknowledge the
+// announcement, and the merge joins a batch when the bus is back.
+func TestAMergeHeardWhileTheBusHasNoJetStreamIsHeldAndRecordedWhenHandedOverAgain(t *testing.T) {
+	open := windowed(t)
+	everyHeadWaits(t)
+	asksWithPaths(t)
+	ctx := t.Context()
+	assignments := &withoutJetStream{Backend: chain.NewMemory()}
+	open.inventory.UseChain(chain.New(chain.NewMemory(), chain.NewMemory(), assignments, func(context.Context) error { return nil }))
+	merge := catalogueMerge("cat2bbbbbbbb", "app", t0)
+
+	assignments.away.Store(true)
+	err := (following{open: open}).hearMerge(ctx, merge, t0.Add(time.Second))
+	if !errors.Is(err, link.ErrTryAgain) {
+		t.Fatalf("a merge heard while the bus had no jetstream answered %v, which the bus takes as done", err)
+	}
+
+	assignments.away.Store(false)
+	hear(t, open, merge, t0.Add(10*time.Second))
+	if _, bs := walks(t, open); len(bs) != 1 {
+		t.Fatalf("the merge handed over again made %d batch(es)", len(bs))
+	}
+}

cmd/mesh-controller/merge_bus_error_test.go

@@ -0,0 +1,33 @@
+package main
+
+import (
+	"errors"
+	"testing"
+
+	"github.com/nats-io/nats.go"
+
+	"github.com/novox/mesh-controller/internal/link"
+)
+
+// **A merge the controller cannot act on is held, whatever the error** (issue 1583, after 921): the bus acknowledges an
+// announcement only when hearMerge answers without ErrTryAgain, and a merge heard once is not announced again. The bus
+// answering "jetstream not enabled" (mesh-catalog #404, 2026-10-21) is no outage of a kind notNow knows, and took the merge.
+func TestAMergeThatFailsOnAnyErrorIsHeldAndNotTaken(t *testing.T) {
+	for name, cause := range map[string]error{
+		"jetstream not enabled": nats.ErrJetStreamNotEnabled,
+		"a bucket missing":      errors.New("the bucket mesh-controller_builds is not on the bus"),
+		"no responders":         nats.ErrNoResponders,
+	} {
+		held := heldMerge(cause)
+		if !errors.Is(held, link.ErrTryAgain) || !errors.Is(held, cause) {
+			t.Errorf("%s answers %v, which the bus takes as done", name, held)
+		}
+	}
+	if heldMerge(nil) != nil {
+		t.Error("a merge that was heard answers an error")
+	}
+	already := link.ErrTryAgain
+	if heldMerge(already) != already {
+		t.Error("a merge already held is wrapped again")
+	}
+}

cmd/mesh-controller/new_module_asked_once_test.go

@@ -0,0 +1,37 @@
+package main
+
+import (
+	"reflect"
+	"testing"
+	"time"
+
+	"github.com/novox/mesh-controller/internal/inventory"
+)
+
+// 1617/AC2 (unit): a new module whose first build a merge's hearing asked is not asked again when its batch is cut,
+// and one whose ask failed, was never handed over or is long lost is.
+func TestAModuleWhoseBuildIsComingIsNotAskedAgain(t *testing.T) {
+	now := time.Date(2026, 10, 21, 12, 0, 0, 0, time.UTC)
+	source := buildSource{Repository: "http://forge/novox/mesh-catalog.git", Seat: "git"}
+	asked := func(path string, mod func(*inventory.RequestOutcome)) inventory.RequestOutcome {
+		r := inventory.RequestOutcome{BuildRequest: inventory.BuildRequest{ID: "b-" + path, Repository: source.Repository,
+			Seat: "git", Path: path, For: "merge", At: now.Add(-3 * time.Minute)}}
+		if mod != nil {
+			mod(&r)
+		}
+		return r
+	}
+	requests := []inventory.RequestOutcome{
+		asked("modules/go", nil),
+		asked("modules/failed", func(r *inventory.RequestOutcome) { r.Heard, r.Failed = true, "no module.json" }),
+		asked("modules/notasked", func(r *inventory.RequestOutcome) { r.NotAsked = "the bus is silent" }),
+		asked("modules/lost", func(r *inventory.RequestOutcome) { r.At = now.Add(-2 * time.Hour) }),
+		asked("modules/byhand", func(r *inventory.RequestOutcome) { r.For = "build" }),
+	}
+	got := unaskedDirs([]string{"modules/go", "modules/failed", "modules/notasked", "modules/lost", "modules/byhand",
+		"modules/nodejs"}, requests, source, now)
+	want := []string{"modules/failed", "modules/notasked", "modules/lost", "modules/byhand", "modules/nodejs"}
+	if !reflect.DeepEqual(got, want) {
+		t.Fatalf("asked again %v, want %v", got, want)
+	}
+}

cmd/mesh-controller/new_module_on_merge_test.go

@@ -4,19 +4,25 @@ package main
 
 import (
 	"context"
+	"sync"
 	"testing"
+	"time"
 
 	"git.novox.be/novox/mesh-sdk/go/catalogue"
 	"github.com/novox/mesh-controller/internal/inventory"
 	"github.com/novox/mesh-controller/internal/link"
 )
 
-// asksWithPaths records every build a merge asks for, as repository, path and ref.
+// asksWithPaths records every build a merge asks for, as repository, path and ref. The merge window's goroutine and
+// the test's own may ask at once, so the record is written under a lock (issue 1543).
 func asksWithPaths(t *testing.T) *[][3]string {
 	t.Helper()
 	var asked [][3]string
+	var mu sync.Mutex
 	was := askABuild
 	askABuild = func(_ context.Context, source buildSource, path, ref string) (string, error) {
+		mu.Lock()
+		defer mu.Unlock()
 		asked = append(asked, [3]string{source.Repository, path, ref})
 		return "b-" + path, nil
 	}
@@ -94,3 +100,38 @@ func TestAMergeBuildsItsNewModuleBesideItsPlan(t *testing.T) {
 		t.Fatalf("a merge adding no module asked for %v", *asked)
 	}
 }
+
+// 1617/AC1 (integration): a merge adding a module to a repository the mesh builds modules from, heard while a batch of
+// that repository is still assembling (its window running), asks the module's first build when it is heard, so the
+// module is registered while the batch waits; cutting the batch asks it no second time (1617/AC2).
+func TestAMergeAddingAModuleAsksItsBuildBeforeItsBatchIsCut(t *testing.T) {
+	open := windowed(t)
+	groupsWaiting(t, "pr/c1")
+	asked := asksWithPaths(t)
+	catalog := func(commit string, made time.Time, paths ...string) link.SourceMoved {
+		return link.SourceMoved{Owner: "novox", Repo: "mesh-catalog", Base: "main", Commit: commit,
+			Head: "pr/" + commit, MergedAt: made.Format(time.RFC3339Nano), Paths: paths}
+	}
+	hear(t, open, catalog("c1", t0, "modules/app/index.ts"), t0)
+	if len(*asked) != 0 {
+		t.Fatalf("a merge adding no module asked %v", *asked)
+	}
+	hear(t, open, lone(catalog("c2", t0.Add(10*time.Second), "modules/go/packages.json", "modules/go/module.json")), t0.Add(10*time.Second))
+	if ws, bs := walks(t, open); len(ws) != 0 || len(bs) != 1 {
+		t.Fatalf("the batch should still be assembling: %d walk(s), %d batch(es)", len(ws), len(bs))
+	}
+	want := [3]string{"novox/mesh-catalog", "modules/go", "main"}
+	if len(*asked) != 1 || (*asked)[0] != want {
+		t.Fatalf("heard with its batch assembling, the merge asked %v, not %v", *asked, want)
+	}
+	cutAt(t, open, t0.Add(10*time.Second+90*time.Second))
+	n := 0
+	for _, a := range *asked {
+		if a[1] == "modules/go" {
+			n++
+		}
+	}
+	if n != 1 {
+		t.Fatalf("modules/go was asked %d times: %v", n, *asked)
+	}
+}

cmd/mesh-controller/outcome_off_the_loop_test.go

@@ -0,0 +1,198 @@
+package main
+
+import (
+	"context"
+	"strings"
+	"testing"
+	"time"
+
+	"github.com/novox/mesh-controller/internal/inventory"
+)
+
+// heldElsewhere is the plans held by another act for longer than any test runs: waiting for them ends only with the
+// context, and a look that does not wait is told at once that they are busy.
+func heldElsewhere(ctx context.Context, wait bool) (func(), error) {
+	if !wait {
+		return nil, inventory.ErrPlansBusy
+	}
+	<-ctx.Done()
+	return nil, inventory.ErrPlansBusy
+}
+
+// 1708/AC1: given the plans held by another act, when the event loop takes a build's outcome, then it returns at
+// once, without waiting the plans' two minutes (on 2026-10-21 at 14:20:45 nodered's outcome held the loop until
+// 14:22:45, and the operator was told the controller stopped listening).
+func TestAnOutcomeDoesNotWaitForThePlansAnotherActHolds(t *testing.T) {
+	ctx, cancel := context.WithTimeout(t.Context(), 3*time.Second)
+	defer cancel()
+	start := time.Now()
+	release, err := holdPlansForOutcome(ctx, heldElsewhere)
+	if took := time.Since(start); took > time.Second {
+		t.Fatalf("taking an outcome waited %s for plans another act holds; the event loop takes nothing meanwhile", took)
+	}
+	if err == nil || release != nil {
+		t.Fatalf("plans another act holds were said to be held: release %v, err %v", release != nil, err)
+	}
+}
+
+// 1708/AC4: given the plans free, when the event loop takes a build's outcome, then it holds them and marks the plan
+// from the outcome directly, as before.
+func TestAnOutcomeHoldsThePlansWhenTheyAreFree(t *testing.T) {
+	let := false
+	release, err := holdPlansForOutcome(t.Context(), func(context.Context, bool) (func(), error) {
+		return func() { let = true }, nil
+	})
+	if err != nil || release == nil {
+		t.Fatalf("free plans were not held: %v", err)
+	}
+	release()
+	if !let {
+		t.Fatal("the hold given was not the one taken")
+	}
+}
+
+// withLooker installs a looker that is never run, and answers it, so a test can read whether a look was asked.
+func withLooker(t *testing.T) *looker {
+	t.Helper()
+	l := newLooker(func(context.Context) bool { return false })
+	lookerMu.Lock()
+	before := theLooker
+	theLooker = l
+	lookerMu.Unlock()
+	t.Cleanup(func() {
+		lookerMu.Lock()
+		theLooker = before
+		lookerMu.Unlock()
+	})
+	return l
+}
+
+// 1708/AC2: given an outcome left to the build records because the plans were held, when it is left, then the look
+// at the plans is asked for, so the records settle it once the holder lets go rather than at the next event.
+func TestAnOutcomeLeftToTheRecordsAsksForTheLook(t *testing.T) {
+	l := withLooker(t)
+	leaveToRecords("nodered", "build-1708-ac2", "", "", inventory.ErrPlansBusy)
+	select {
+	case <-l.signal:
+	default:
+		t.Fatal("an outcome left to the build records asked for no look: the plan waits for whatever event comes next")
+	}
+}
+
+// 1708/AC3: given an outcome left to the records that said what the build did (ADR 0350 §4), when the look settles
+// the plan from the build records by that build's id, then the module keeps those words, once.
+func TestTheRecordsSettleAnOutcomeWithWhatTheBuildDid(t *testing.T) {
+	withLooker(t)
+	asked := time.Date(2026, 10, 21, 12, 15, 0, 0, time.UTC)
+	plan := func() inventory.Plan {
+		return inventory.Plan{ID: "plan-1708", Tiers: [][]string{{"nodered"}},
+			Modules: map[string]*inventory.PlanModule{"nodered": {State: "asked", AskedAt: &asked, Build: "build-1708-ac3"}}}
+	}
+	byID := map[string]inventory.Build{"build-1708-ac3": {ID: "build-1708-ac3", Module: "nodered", Commit: "4efac366",
+		At: asked.Add(5 * time.Minute)}}
+	leaveToRecords("nodered", "build-1708-ac3", "reused from build-1708-check", "", inventory.ErrPlansBusy)
+
+	p := plan()
+	if !settleFromRecords(&p, p.Tiers[0], nil, byID) || p.Modules["nodered"].State != "built" {
+		t.Fatalf("the records did not settle the outcome: %+v", p.Modules["nodered"])
+	}
+	if got := p.Modules["nodered"].Made; got != "reused from build-1708-check" {
+		t.Fatalf("settled from the records, the module says %q of what its build did, not the outcome's words", got)
+	}
+	again := plan()
+	settleFromRecords(&again, again.Tiers[0], nil, byID)
+	if got := again.Modules["nodered"].Made; got != "" {
+		t.Fatalf("an outcome's words were kept for a second settle: %q", got)
+	}
+}
+
+// 1708/AC5: given a serving controller (its look at the plans running), when an outcome was taken into the plans,
+// then moving them (a release's sends, which may retry for minutes) is left to the look, off the event loop
+// (2026-10-21 14:28:40 to 14:32:10: the loop sent okioki's release to g14 after mesh-delivery-builder's outcome).
+func TestAnOutcomeLeavesMovingThePlansToTheLook(t *testing.T) {
+	l := withLooker(t)
+	moved := false
+	advanceAfterOutcome(func() { moved = true })
+	if moved {
+		t.Fatal("the plans were moved on the event loop after an outcome, where a send that retries holds every message")
+	}
+	select {
+	case <-l.signal:
+	default:
+		t.Fatal("the look was not asked to move the plans after an outcome")
+	}
+}
+
+// 1708/AC5: given no look running (a command, which has no event loop), when an outcome was taken, then the plans are
+// moved at once, as before.
+func TestAnOutcomeMovesThePlansWhereNoLookRuns(t *testing.T) {
+	lookerMu.Lock()
+	before := theLooker
+	theLooker = nil
+	lookerMu.Unlock()
+	t.Cleanup(func() {
+		lookerMu.Lock()
+		theLooker = before
+		lookerMu.Unlock()
+	})
+	moved := false
+	advanceAfterOutcome(func() { moved = true })
+	if !moved {
+		t.Fatal("with no look running, an outcome left the plans unmoved")
+	}
+}
+
+// 1708/AC6: given a registration the mesh refused (its build recorded as worked, the outcome failed), left to the
+// records because the plans were held, when the look settles the plan from the records, then the module and the plan
+// are failed, never built: settled as built, the tier would be sent the version from before (reviewer-1708@shanks).
+func TestARefusedRegistrationLeftToTheRecordsFailsThePlan(t *testing.T) {
+	withLooker(t)
+	asked := time.Date(2026, 10, 21, 12, 15, 0, 0, time.UTC)
+	p := inventory.Plan{ID: "plan-1708-ac6", State: inventory.PlanBuilding, Tiers: [][]string{{"nodered"}},
+		Modules: map[string]*inventory.PlanModule{"nodered": {State: "asked", AskedAt: &asked, Build: "build-1708-ac6"}}}
+	byID := map[string]inventory.Build{"build-1708-ac6": {ID: "build-1708-ac6", Module: "nodered", Commit: "4efac366",
+		At: asked.Add(5 * time.Minute)}}
+	leaveToRecords("nodered", "build-1708-ac6", "", "the mesh does not register it: a port is taken", inventory.ErrPlansBusy)
+
+	overlayRefusals(nil, byID, refusalsKeptFor([]string{"build-1708-ac6"}))
+	settleFromRecords(&p, p.Tiers[0], nil, byID)
+	if s := p.Modules["nodered"]; s.State != "failed" || p.State != inventory.PlanFailed {
+		t.Fatalf("a refused registration left to the records settled as %q, the plan %q", s.State, p.State)
+	}
+	if !strings.Contains(p.Modules["nodered"].Why, "a port is taken") {
+		t.Fatalf("the refusal's words were lost: %q", p.Modules["nodered"].Why)
+	}
+}
+
+// 1708/AC6: a refusal kept in the store (a controller replaced before the settle) fails the record as one kept in
+// the process does.
+func TestARefusalFromTheStoreFailsTheRecord(t *testing.T) {
+	recorded := map[string][]inventory.Build{"nodered": {{ID: "b-store", Module: "nodered"}, {ID: "b-other", Module: "nodered"}}}
+	byID := map[string]inventory.Build{"b-store": {ID: "b-store", Module: "nodered"}}
+	overlayRefusals(recorded, byID, map[string]string{"b-store": "not registered"})
+	if recorded["nodered"][0].Worked() || byID["b-store"].Worked() {
+		t.Fatal("a build whose registration was refused still reads as worked")
+	}
+	if !recorded["nodered"][1].Worked() {
+		t.Fatal("a build nobody refused was failed")
+	}
+}
+
+// 1708/AC7: given the records settle a module as deleted at its source, or fail the plan, when the look settles, then
+// it does what taking the outcome directly does: the deleted module is named to be forgotten, and the plan's failure
+// is said (reviewer-1708@shanks).
+func TestSettlingFromTheRecordsDoesWhatTakingTheOutcomeDoes(t *testing.T) {
+	p := inventory.Plan{State: inventory.PlanFailed, Modules: map[string]*inventory.PlanModule{
+		"gone": {State: planDeleted}, "x": {State: "failed"}, "y": {State: "built"}}}
+	before := map[string]string{"gone": "asked", "x": "asked", "y": "built"}
+	deleted, failed := settledEffects(before, &p, inventory.PlanBuilding)
+	if len(deleted) != 1 || deleted[0] != "gone" {
+		t.Fatalf("the module the records found deleted is not forgotten: %v", deleted)
+	}
+	if !failed {
+		t.Fatal("the plan the records failed is not said as failed")
+	}
+	if d, f := settledEffects(map[string]string{"gone": planDeleted}, &p, inventory.PlanFailed); len(d) != 0 || f {
+		t.Fatalf("what was deleted or failed before the settle is acted on again: %v %v", d, f)
+	}
+}

cmd/mesh-controller/plain_words.go

@@ -195,6 +195,21 @@ var plainWordings = map[string]func(conditions.Observation) words{
 				"there yet is sealed by the controller until the vault holds it.", m, m),
 			Resolved: "Resolved: the vault gave " + m + " the core's credentials"}
 	}),
+	kindDeclarationNearLimit: worded(func(o conditions.Observation) words {
+		m := machineOr(o, "a machine")
+		if o.Severity == conditions.Urgent {
+			return words{Headline: m + " cannot be sent its instructions",
+				Needs: "make the instructions for " + m + " smaller, for example by taking a module off it.",
+				Explanation: fmt.Sprintf("The instructions for %s have grown past the largest message the bus takes, so "+
+					"nothing new reaches %s until they are smaller.", m, m),
+				Resolved: "Resolved: the instructions for " + m + " fit the bus again"}
+		}
+		return words{Headline: "The instructions for " + m + " are nearly too big",
+			Needs: "do not add more to " + m + " until this is dealt with; the details give the size.",
+			Explanation: fmt.Sprintf("The instructions for %s are close to the largest message the bus takes. "+
+				"One more module or secret may stop anything new from reaching %s.", m, m),
+			Resolved: "Resolved: the instructions for " + m + " have room again"}
+	}),
 	kindCoreDowngrade: worded(func(o conditions.Observation) words {
 		m := machineOr(o, "a machine")
 		component := idPart(o, 0)
@@ -951,6 +966,10 @@ func stalledWords(l stalledLine, o conditions.Observation) (headline, explanatio
 			needs, actions = "release it, or stop it, "+FromMeshMCPServer, []conditions.Action{release, stop}
 		case "ready", "checked":
 			needs = "merge its pull request, or close it."
+		case "stopped":
+			// Already stopped: mesh-delivery.stop refuses it, so neither offer nor ask it (novox/hq issue 1581).
+			// What ends it is the stalled line's own word, such as a later merge that delivers its modules.
+			needs = stoppedNeeds(l)
 		default:
 			needs, actions = "stop it "+FromMeshMCPServer, []conditions.Action{stop}
 		}
@@ -960,6 +979,17 @@ func stalledWords(l stalledLine, o conditions.Observation) (headline, explanatio
 		fmt.Sprintf("Delivery of %s is no longer %s", name, held), needs, actions
 }
 
+// stoppedNeeds is what ends a delivery that is already stopped, from the stalled line's healer words ("none: a
+// merge that delivers its modules ends it — the operator's"): the part that says what ends it.
+func stoppedNeeds(l stalledLine) string {
+	ends := strings.TrimSpace(strings.TrimPrefix(l.H2, "none:"))
+	ends, _, _ = strings.Cut(ends, " — ")
+	if ends == "" {
+		ends = "a later merge that delivers its modules ends it"
+	}
+	return "nothing to stop, it is stopped already: " + ends + "."
+}
+
 // unansweredWords are the plain words of a pull request's head whose merge check was asked and has not answered
 // within its bound (novox/hq issue 438): mesh-delivery holds no delivery of it, so there is nothing to stop, release
 // or close, and no action is offered. The operator's acts are a new commit, which asks the check again, or a look

cmd/mesh-controller/plain_words_test.go

@@ -498,3 +498,24 @@ func TestAnUnansweredMergeCheckOnAReadyOrRejectedDeliveryOffersARecheck(t *testi
 		t.Fatalf("a line with no delivery held says to %q", o.Needs)
 	}
 }
+
+// **A delivery already stopped is not asked to be stopped** (novox/hq issue 1581): mesh-delivery.stop refuses a
+// stopped delivery, so the condition offers no Stop and says what ends it, in the stalled line's own words. Any
+// other held state keeps its Stop.
+func TestAStoppedDeliveryIsNotAskedToBeStopped(t *testing.T) {
+	l := stalledLine{ID: "novox/mesh-catalog@2f6086120c46", State: "stopped", For: "12h19m36s",
+		H2:   "none: a merge that delivers its modules ends it — the operator's",
+		Says: "a merged change never reached the machines"}
+	_, _, _, needs, actions := stalledWords(l, conditions.Observation{Resolver: conditions.ResolverOperator})
+	if len(actions) != 0 {
+		t.Fatalf("a stopped delivery offers %v, want no action", actions)
+	}
+	if strings.Contains(needs, "stop it") || !strings.Contains(needs, "a merge that delivers its modules ends it") {
+		t.Fatalf("needs = %q, want what ends it and no ask to stop", needs)
+	}
+	l.State = "failing"
+	_, _, _, needs, actions = stalledWords(l, conditions.Observation{Resolver: conditions.ResolverOperator})
+	if len(actions) != 1 || actions[0].Label != "Stop" || !strings.HasPrefix(needs, "stop it") {
+		t.Fatalf("another held state changed: needs %q, actions %v", needs, actions)
+	}
+}

cmd/mesh-controller/plan_looks.go

@@ -136,6 +136,18 @@ func askToLook() {
 	}
 }
 
+// askedToLook asks the serving controller's look at the plans, and says whether there was one to ask.
+func askedToLook() bool {
+	lookerMu.RLock()
+	l := theLooker
+	lookerMu.RUnlock()
+	if l == nil {
+		return false
+	}
+	l.ask()
+	return true
+}
+
 // startPlanLooks starts the look at the open plans, and asks for the first: the controller took the lease, and a
 // plan left by a replaced controller resumes from there (ADR 0406 §6). It replaces the rollout's 30 second ticker.
 // It answers a channel that is closed once the look has returned after the context ended, for a test that restores what

cmd/mesh-controller/release_plan.go

@@ -625,16 +625,124 @@ func planBuilt(ctx context.Context, open *stores, module, commit, failed string,
 	planBuiltSaying(ctx, open, module, commit, failed, asked, id, "")
 }
 
+// holdPlansForOutcome is how an outcome taken on the event loop holds the plans: **without waiting for them**
+// (novox/hq issue 1708). The loop takes one message at a time, and the plans' holder may keep them for minutes while
+// it sends machines their declarations; an outcome that waited its turn (up to inventory.HoldWaitFor, two minutes)
+// held every report, build and merge behind it for as long, and the watchdog said the controller stopped listening
+// (2026-10-21 14:20:45 to 14:22:45). Busy, the outcome is left to the build records, where it already is, and the
+// look settles the plan from them (leaveToRecords).
+func holdPlansForOutcome(ctx context.Context, hold func(context.Context, bool) (func(), error)) (func(), error) {
+	return hold(ctx, false)
+}
+
+// leaveToRecords says an outcome was not taken into the plans, which settle it from the build records (novox/hq issue
+// 214). When another act holds the plans it asks for the look, which waits for them off the event loop and settles
+// the plan from the records once they are let go (issue 1708); what the build did is kept for that settle by the
+// build's id, so the walk's module says it as it would have (ADR 0350 §4).
+func leaveToRecords(module, id, made, failed string, err error) {
+	fmt.Printf("plans: %s's outcome is left to the build records: %v\n", module, err)
+	if !errors.Is(err, inventory.ErrPlansBusy) {
+		return
+	}
+	keepMadeFor(id, made, time.Now())
+	// A refused outcome (failed, its build recorded as worked) is kept as refused, or the records settle it built.
+	keepRefusalFor(id, failed, time.Now())
+	askToLook()
+}
+
+// refusalsKeptFor is the refusals kept in this process for these builds (keepRefusalFor), by id.
+func refusalsKeptFor(ids []string) map[string]string {
+	out := map[string]string{}
+	refusedLeftMu.Lock()
+	defer refusedLeftMu.Unlock()
+	for _, id := range ids {
+		if k, ok := refusedLeft[id]; ok {
+			out[id] = k.made
+		}
+	}
+	return out
+}
+
+// refusedLeft is why each outcome left to the records was refused, by the build's id: kept in the process beside the
+// store's record (RecordRefused), so a store that did not take it still fails the plan while this controller serves.
+var (
+	refusedLeftMu sync.Mutex
+	refusedLeft   = map[string]madeKept{}
+)
+
+// keepRefusalFor keeps why an outcome left to the records was refused, forgetting refusals older than madeLeftFor.
+func keepRefusalFor(id, why string, now time.Time) {
+	if id == "" || why == "" {
+		return
+	}
+	refusedLeftMu.Lock()
+	defer refusedLeftMu.Unlock()
+	for k, v := range refusedLeft {
+		if now.Sub(v.at) > madeLeftFor {
+			delete(refusedLeft, k)
+		}
+	}
+	refusedLeft[id] = madeKept{made: why, at: now}
+}
+
+// madeLeft is what each build left to the records did, by the build's id, until a settle takes it: kept in the
+// process, so a controller replaced before the settle loses only these words, never the outcome.
+var (
+	madeLeftMu sync.Mutex
+	madeLeft   = map[string]madeKept{}
+)
+
+type madeKept struct {
+	made string
+	at   time.Time
+}
+
+// madeLeftFor is how long words nobody settled are kept: a plan that ended or moved on never asks for them.
+const madeLeftFor = time.Hour
+
+// keepMadeFor keeps what a build left to the records did for the settle that takes it, forgetting words older than
+// madeLeftFor.
+func keepMadeFor(id, made string, now time.Time) {
+	if id == "" || made == "" {
+		return
+	}
+	madeLeftMu.Lock()
+	defer madeLeftMu.Unlock()
+	for k, v := range madeLeft {
+		if now.Sub(v.at) > madeLeftFor {
+			delete(madeLeft, k)
+		}
+	}
+	madeLeft[id] = madeKept{made: made, at: now}
+}
+
+// takeMadeOf is what the build of this id did, if its outcome was left to the records with words; taken once.
+func takeMadeOf(id string) string {
+	madeLeftMu.Lock()
+	defer madeLeftMu.Unlock()
+	k, ok := madeLeft[id]
+	if !ok {
+		return ""
+	}
+	delete(madeLeft, id)
+	return k.made
+}
+
 // planBuiltSaying is planBuilt keeping what the build did — "reused from <check build>" or "built: <why>" (novox/hq
 // ADR 0350 §4) — on the module of the walk it answers.
 func planBuiltSaying(ctx context.Context, open *stores, module, commit, failed string, asked time.Time, id, made string) {
 	inv := open.inventory
-	// One controller works the plans at a time (novox/hq issue 213); an outcome waits its turn rather
-	// than write over what the holder is about to save. Not taken, it is still in the build records,
-	// which the holder settles the plan from (issue 214).
-	release, err := inv.HoldPlans(ctx, true)
+	// One controller works the plans at a time (novox/hq issue 213). Not taken, the outcome is still in the build
+	// records, which the holder settles the plan from (issue 214).
+	release, err := holdPlansForOutcome(ctx, inv.HoldPlans)
 	if err != nil {
-		fmt.Printf("plans: %s's outcome is left to the build records: %v\n", module, err)
+		if failed != "" && id != "" && errors.Is(err, inventory.ErrPlansBusy) {
+			// In the store too, so a controller replaced before the look settles still fails the plan (issue 1708).
+			if err := inv.RecordRefused(ctx, id, module, failed); err != nil {
+				fmt.Printf("plans: %s's refusal could not be kept in the store, only in this controller: %v\n", module, err)
+			}
+		}
+		leaveToRecords(module, id, made, failed, err)
 		return
 	}
 	defer release()
@@ -696,7 +804,19 @@ func planBuiltSaying(ctx context.Context, open *stores, module, commit, failed s
 			fmt.Printf("%s: %s; the tiers after it are not asked\n", p.ID, p.Note)
 		}
 	}
-	advanceHeld(ctx, open)
+	advanceAfterOutcome(func() { advanceHeld(ctx, open) })
+}
+
+// advanceAfterOutcome moves the plans after an outcome was taken into them: **in the serving controller, by asking
+// the look** (novox/hq issue 1708). The outcome is taken on the event loop, and moving the plans may send machines
+// their declarations, a release's send retried for minutes among them; done here it held every report, build and
+// merge behind it (2026-10-21 14:28:40 to 14:32:10). The look runs off the loop, holding the plans itself. Where no
+// look runs (a command, which has no event loop) the plans are moved at once, as before.
+func advanceAfterOutcome(advance func()) {
+	if askedToLook() {
+		return
+	}
+	advance()
 }
 
 // startedBeside is the id of a started walk open beside this one that it is related to — a merge's walk past
@@ -921,7 +1041,17 @@ func advanceOnce(ctx context.Context, open *stores, p *inventory.Plan,
 	if err != nil {
 		return false, err
 	}
+	before, was := statesOf(p), p.State
 	if settleFromRecords(p, tier, recorded, byID) {
+		// As taking the outcome directly does (planBuiltSaying): a module deleted at its source is forgotten, and a
+		// failed plan says what it built and never sent (issue 1708).
+		deleted, failed := settledEffects(before, p, was)
+		for _, m := range deleted {
+			forgetDeleted(ctx, inv, m, p)
+		}
+		if failed {
+			sayUnsent(p, rollsOut)
+		}
 		return true, nil
 	}
 	// Asked: wait for every build.
@@ -2479,9 +2609,81 @@ func recordsOfAsked(ctx context.Context, inv *inventory.Inventory, p *inventory.
 			}
 		}
 	}
+	refused, err := refusalsOf(ctx, inv, recorded, byID)
+	if err != nil {
+		return nil, nil, err
+	}
+	overlayRefusals(recorded, byID, refused)
 	return recorded, byID, nil
 }
 
+// overlayRefusals marks failed every build record whose registration the mesh refused (novox/hq issue 1708): the record
+// keeps the builder's words, which worked, and settled from it as it is the refused build would be built and sent.
+func overlayRefusals(recorded map[string][]inventory.Build, byID map[string]inventory.Build, refused map[string]string) {
+	if len(refused) == 0 {
+		return
+	}
+	fail := func(b *inventory.Build) {
+		if why, ok := refused[b.ID]; ok && b.Worked() {
+			b.Failed = why
+		}
+	}
+	for m := range recorded {
+		for i := range recorded[m] {
+			fail(&recorded[m][i])
+		}
+	}
+	for id, b := range byID {
+		fail(&b)
+		byID[id] = b
+	}
+}
+
+// refusalsOf is every refusal kept for the builds these records name, in the store and in this process.
+func refusalsOf(ctx context.Context, inv *inventory.Inventory, recorded map[string][]inventory.Build,
+	byID map[string]inventory.Build) (map[string]string, error) {
+	var ids []string
+	for _, bs := range recorded {
+		for _, b := range bs {
+			ids = append(ids, b.ID)
+		}
+	}
+	for id := range byID {
+		ids = append(ids, id)
+	}
+	refused, err := inv.RefusedOf(ctx, ids)
+	if err != nil {
+		return nil, fmt.Errorf("the refused registrations cannot be read: %w", err)
+	}
+	for id, why := range refusalsKeptFor(ids) {
+		refused[id] = why
+	}
+	return refused, nil
+}
+
+// settledEffects is what settling from the records did that needs more than the plan: the modules it found deleted
+// at their source, and whether it failed the plan.
+func settledEffects(before map[string]string, p *inventory.Plan, was string) (deleted []string, failed bool) {
+	for m, s := range p.Modules {
+		if s != nil && s.State == planDeleted && before[m] != planDeleted {
+			deleted = append(deleted, m)
+		}
+	}
+	sort.Strings(deleted)
+	return deleted, p.State == inventory.PlanFailed && was != inventory.PlanFailed
+}
+
+// statesOf is each module's state in a plan, for settledEffects.
+func statesOf(p *inventory.Plan) map[string]string {
+	out := map[string]string{}
+	for m, s := range p.Modules {
+		if s != nil {
+			out[m] = s.State
+		}
+	}
+	return out
+}
+
 // settleFromRecords marks every module of the tier still `asked` built — or failed — from a build
 // recorded after it was asked, and says whether it changed anything (novox/hq 04-ISSUES/214).
 // Newest first, as Builds answers: the first record after the ask is the outcome of that ask.
@@ -2531,6 +2733,10 @@ func settleFromRecords(p *inventory.Plan, tier []string, recorded map[string][]i
 			s.State = "built"
 			s.BuiltAt = &at
 			s.Commit = outcome.Commit
+			// What the build did, when its outcome was left to the records with words (issue 1708).
+			if made := takeMadeOf(outcome.ID); made != "" {
+				s.Made = made
+			}
 		} else {
 			s.State = "failed"
 			s.Why = outcome.Failed

cmd/mesh-controller/seats_test.go

@@ -93,3 +93,27 @@ func TestTheSeatsListingShowsEachSeatsPaths(t *testing.T) {
 		}
 	}
 }
+
+// 1718/AC2: a manifest claiming node-files that serves upload and download passes the controller's module
+// check, judged by the mesh-sdk it vendors; a verb outside the contract is still refused.
+func TestAFilesHolderServingUploadAndDownloadCanHoldTheSeat(t *testing.T) {
+	seat, ok := catalogue.SeatNamed(catalogue.FilesSeat)
+	if !ok {
+		t.Fatal("node-files is not a seat")
+	}
+	serves := []string{"upload", "download"}
+	for _, v := range seat.Serves {
+		if v.Name != "upload" && v.Name != "download" {
+			serves = append(serves, v.Name)
+		}
+	}
+	holder := catalogue.Manifest{Module: "mesh-files", Version: "1", Claims: []catalogue.Claim{{
+		Name: catalogue.FilesSeat, Scope: catalogue.ScopeNode, Serves: serves}}}
+	if err := catalogue.CanHold(holder, seat); err != nil { // 1718/AC2
+		t.Fatalf("a holder serving upload and download is refused: %v", err)
+	}
+	holder.Claims[0].Serves = append(append([]string{}, serves...), "teleport")
+	if err := catalogue.CanHold(holder, seat); err == nil || !strings.Contains(err.Error(), "does not promise") {
+		t.Fatalf("a verb outside the contract must be refused with 'does not promise': %v", err)
+	}
+}

cmd/mesh-controller/shares_test.go

@@ -0,0 +1,104 @@
+package main
+
+import (
+	"bytes"
+	"crypto/ecdh"
+	"crypto/rand"
+	"encoding/base64"
+	"encoding/json"
+	"os"
+	"path/filepath"
+	"strings"
+	"testing"
+
+	"git.novox.be/novox/mesh-sdk/go/catalogue"
+	"git.novox.be/novox/mesh-sdk/go/compose"
+	"git.novox.be/novox/mesh-sdk/go/overlay"
+)
+
+// Issue 1593 (novox/hq ADR 0468 §8): `shares` on a requirement of s3-bucket, taken in with mesh-sdk 465beb4. The fixture's
+// shape is mesh-sdk's go/catalogue/bucket_shares_test.go (issue 1591) and go/compose/resolve_test.go theObjectsMesh.
+
+const filesRequiringShares = `{"module":"files","version":"1","requires":[
+	{"name":"s3-bucket","shares":[{"to":"seat:node-files","methods":["put"]}]}]}`
+
+func aKey(t *testing.T) string {
+	t.Helper()
+	k, err := ecdh.X25519().GenerateKey(rand.Reader)
+	if err != nil {
+		t.Fatal(err)
+	}
+	return base64.StdEncoding.EncodeToString(k.PublicKey().Bytes())
+}
+
+// 1593/AC1 unit: composing the provider's machine, the file it receives for the consumer carries the shares.
+func TestTheProvidersMachineReceivesTheSharesOfAnS3BucketRequirement(t *testing.T) {
+	var overlayModule catalogue.Manifest
+	raw, err := json.Marshal(overlay.Manifest())
+	if err != nil {
+		t.Fatal(err)
+	}
+	if err := json.Unmarshal(raw, &overlayModule); err != nil {
+		t.Fatal(err)
+	}
+	consumer, err := catalogue.ParseManifest([]byte(filesRequiringShares))
+	if err != nil {
+		t.Fatal(err)
+	}
+	provider := catalogue.Manifest{Module: "objects", Version: "1",
+		Provides: []catalogue.Offer{{Name: "s3-bucket", Scope: catalogue.ScopeMesh,
+			Identity: &catalogue.OfferIdentity{Max: 20, In: "an S3 access key"}}},
+		Receives: map[string]string{"s3-bucket": "/var/lib/mesh/objects/mesh.json"}}
+	in := compose.Input{
+		Catalogue: map[string]catalogue.Manifest{overlay.Name: overlayModule, "objects": provider, "files": consumer},
+		Issued: []compose.Issued{{Provision: "s3-bucket", Consumer: "laptop", ConsumerModule: "files",
+			Provider: "anchor", ForProvider: "sealed-to-anchor"}},
+	}
+	for i, name := range []string{"anchor", "laptop"} {
+		assigned := []string{overlay.Name, "objects"}
+		if name == "laptop" {
+			assigned = []string{overlay.Name, "files"}
+		}
+		in.Nodes = append(in.Nodes, compose.Node{Name: name, SealingKey: name + "-key", Assigned: assigned,
+			Place: compose.Place{Key: aKey(t), Endpoint: name + ".example:51820", Site: "here", Hub: name == "anchor",
+				Address: []string{"10.77.0.1", "10.77.0.2"}[i]},
+			Capabilities: map[string]bool{"container-runtime": true, "wireguard": true, "systemd": true}})
+	}
+	rendered, err := compose.Render(in, "anchor", compose.Foreseeing)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if len(rendered.Rendering.Grants) != 1 {
+		t.Fatalf("grants are %+v", rendered.Rendering.Grants)
+	}
+	got, err := json.Marshal(rendered.Rendering.Grants[0].Values["shares"])
+	if err != nil {
+		t.Fatal(err)
+	}
+	if want := `[{"methods":["put"],"to":"seat:node-files"}]`; string(got) != want {
+		t.Fatalf("the provider's grant for the consumer carries shares %s, want %s", got, want)
+	}
+}
+
+// 1593/AC2 unit: the module check accepts a manifest with shares and refuses an unknown method, citing ADR 0468 §8.
+func TestModuleCheckAcceptsSharesAndRefusesAnUnknownMethod(t *testing.T) {
+	dir := t.TempDir()
+	write := func(name, body string) string {
+		p := filepath.Join(dir, name+".json")
+		if err := os.WriteFile(p, []byte(body), 0o600); err != nil {
+			t.Fatal(err)
+		}
+		return p
+	}
+	var out bytes.Buffer
+	if err := moduleCheckFor([]string{write("files", filesRequiringShares)}, 6, &out); err != nil {
+		t.Fatalf("a manifest with shares was refused: %v\n%s", err, out.String())
+	}
+	out.Reset()
+	bad := write("bad", `{"module":"bad","version":"1","requires":[
+		{"name":"s3-bucket","shares":[{"to":"seat:node-files","methods":["delete"]}]}]}`)
+	err := moduleCheckFor([]string{bad}, 6, &out)
+	if err == nil || !strings.Contains(out.String(), "ADR 0468 §8") {
+		t.Fatalf("an unknown method passed or the refusal does not cite the ADR: %v\n%s", err, out.String())
+	}
+}

cmd/mesh-controller/upgrades.go

@@ -415,7 +415,59 @@ func askNewModules(ctx context.Context, inv *inventory.Inventory, m link.SourceM
 	if len(added) == 0 || len(from) == 0 {
 		return nil
 	}
-	return askBuilds(ctx, inv, m, buildSource{Repository: from[0].Source.Repository, Seat: from[0].Source.Seat}, added)
+	source := buildSource{Repository: from[0].Source.Repository, Seat: from[0].Source.Seat}
+	// Asked once (novox/hq issue 1617): a module is asked when its merge is heard, and again here when the batch is cut.
+	var requests []inventory.RequestOutcome
+	for _, dir := range added {
+		if got, err := inv.RequestsNamed(ctx, inventory.BuildRequest{Repository: source.Repository, Path: dir}.Name()); err == nil {
+			requests = append(requests, got...)
+		}
+	}
+	return askBuilds(ctx, inv, m, source, unaskedDirs(added, requests, source, time.Now()))
+}
+
+// askedInFlightFor is how long a merge's build request stands as the build coming for its module: past it, a lost one
+// is asked again.
+const askedInFlightFor = time.Hour
+
+// unaskedDirs are the directories of a new module no build of a merge is on its way for: a kept request of the same
+// repository and directory, asked for a merge and handed over, whose outcome has not come and is not given up on,
+// is the build coming (novox/hq issue 1617).
+func unaskedDirs(added []string, requests []inventory.RequestOutcome, source buildSource, now time.Time) []string {
+	var out []string
+	for _, dir := range added {
+		path := dir
+		if path == "." {
+			path = ""
+		}
+		coming := false
+		for _, r := range requests {
+			if r.For == "merge" && r.Repository == source.Repository && strings.Trim(r.Path, "/") == path &&
+				r.NotAsked == "" && r.OutcomeUnknown == "" && !r.Heard && now.Sub(r.At) < askedInFlightFor {
+				coming = true
+				break
+			}
+		}
+		if !coming {
+			out = append(out, dir)
+		}
+	}
+	return out
+}
+
+// askNewModulesAtHearing asks the first build of the modules a merge adds to a repository the mesh builds modules from,
+// when the merge is heard, not when its batch is cut (novox/hq issue 1617): a batch waits out its window and the walk
+// before it, and a module added by a merge delivered meanwhile could not be assigned. Outside the batch and its plan.
+func askNewModulesAtHearing(ctx context.Context, inv *inventory.Inventory, m link.SourceMoved, entries []inventory.Entry,
+	read map[string][]inventory.ReadRepository, from []inventory.Entry) {
+	if len(from) == 0 {
+		return
+	}
+	_, added, _ := touchedBy(from, entries, m, read)
+	if asked := askNewModules(ctx, inv, m, from, added); len(asked) > 0 {
+		fmt.Printf("%s/%s merged into %s (%.8s) adds %s: the first build is asked now, before its batch is cut\n",
+			m.Owner, m.Repo, m.Base, m.Commit, strings.Join(asked, ", "))
+	}
 }
 
 // askBuilds asks the first build of each directory of a merge's repository, as askNewModules does, from the source given.

cmd/mesh-controller/watchdogs.go

@@ -621,21 +621,35 @@ func p90(took []time.Duration) time.Duration {
 	return sorted[int(0.9*float64(len(sorted)-1))]
 }
 
+// loopConsumers are the controller's own consumers: the loop never takes from the build seat's check workers (issue 1063).
+func loopConsumers() []broker.Consumer { return broker.ControllerConsumers() }
+
 // gatherLoop is when the event loop last took a message and what its consumers hold.
 func (w *watchdogs) gatherLoop() (loopFacts, error) {
-	f := loopFacts{took: link.Loop.Last()}
 	if w.js == nil {
-		return f, errors.New("this controller is not on the bus")
+		return loopFacts{took: link.Loop.Last()}, errors.New("this controller is not on the bus")
 	}
-	var where []string
-	for _, c := range broker.MeshConsumers() {
+	return readLoop(link.Loop.Last(), loopConsumers(), func(c broker.Consumer) (uint64, error) {
 		info, err := w.js.Context().ConsumerInfo(c.Stream, c.Name)
+		if err != nil {
+			return 0, err
+		}
+		return info.NumPending + uint64(info.NumAckPending), nil
+	})
+}
+
+// readLoop sums what the given consumers hold, as held reads each.
+func readLoop(took time.Time, consumers []broker.Consumer, held func(broker.Consumer) (uint64, error)) (loopFacts, error) {
+	f := loopFacts{took: took}
+	var where []string
+	for _, c := range consumers {
+		n, err := held(c)
 		if err != nil {
 			return f, fmt.Errorf("the controller's consumer on %s cannot be read: %w", c.Stream, err)
 		}
-		if held := info.NumPending + uint64(info.NumAckPending); held > 0 {
-			f.pending += held
-			where = append(where, fmt.Sprintf("%d on %s", held, c.Stream))
+		if n > 0 {
+			f.pending += n
+			where = append(where, fmt.Sprintf("%d on %s", n, c.Stream))
 		}
 	}
 	f.where = fmt.Sprint(where)

go.mod

@@ -3,7 +3,7 @@ module github.com/novox/mesh-controller
 go 1.26.0
 
 require (
-	git.novox.be/novox/mesh-sdk/go v0.1.14-0.20261020085642-ab0c16ddad26
+	git.novox.be/novox/mesh-sdk/go v0.1.14-0.20261021144048-d4deecdb380b
 	github.com/jackc/pgx/v5 v5.10.0
 	github.com/nats-io/nats-server/v2 v2.11.17
 	github.com/nats-io/nats.go v1.54.0

go.sum

@@ -1,11 +1,7 @@
 git.novox.be/novox/mesh-host v0.0.0-20261018171808-9d9e3a46c4f5 h1:E5stfIeCN6uYgA9TCv+4K8JgaURg3zQppvUgJLaDMP4=
 git.novox.be/novox/mesh-host v0.0.0-20261018171808-9d9e3a46c4f5/go.mod h1:4wyoCr6IIIIarEUuROThWDj7DAvJvIidqMjWcpSnOwE=
-git.novox.be/novox/mesh-sdk/go v0.1.14-0.20261018184557-238440d6f8c4 h1:yYDxFRJoH59kiCoEulD+FBwctyf9CrtKIxlEAsVL39Q=
-git.novox.be/novox/mesh-sdk/go v0.1.14-0.20261018184557-238440d6f8c4/go.mod h1:GFuZUElBZ9A++mxgIKo97aXXo+kV0uJ/UkbhQPPIbrY=
-git.novox.be/novox/mesh-sdk/go v0.1.14-0.20261019091011-aa68b67389c9 h1:qHpN/fpTDqijfMVoepxUT6mPkfcydb4LiPKsIokv6iM=
-git.novox.be/novox/mesh-sdk/go v0.1.14-0.20261019091011-aa68b67389c9/go.mod h1:ouERNpZizzwZ0HLEtAypsY9FR20FyUgUYRni6J7kVCY=
-git.novox.be/novox/mesh-sdk/go v0.1.14-0.20261020085642-ab0c16ddad26 h1:oT1l3ZdjyF82MK14QMLKzoH2+iOFH/+UEYdlK3T2f7k=
-git.novox.be/novox/mesh-sdk/go v0.1.14-0.20261020085642-ab0c16ddad26/go.mod h1:ouERNpZizzwZ0HLEtAypsY9FR20FyUgUYRni6J7kVCY=
+git.novox.be/novox/mesh-sdk/go v0.1.14-0.20261021144048-d4deecdb380b h1:5UlQ8ytlHNgqlm5AbwJEnZwuf1EWUiNyXX2hcOV9Yro=
+git.novox.be/novox/mesh-sdk/go v0.1.14-0.20261021144048-d4deecdb380b/go.mod h1:ouERNpZizzwZ0HLEtAypsY9FR20FyUgUYRni6J7kVCY=
 github.com/antithesishq/antithesis-sdk-go v0.7.0-default-no-op h1:Z/MZK75wC/NSrkgqeNIa7jexam9uWzhLmFTSCPI/kn0=
 github.com/antithesishq/antithesis-sdk-go v0.7.0-default-no-op/go.mod h1:FQyySiasQQM8735Ddel3MRojmy4dA1IqCeyJ5jmPMbI=
 github.com/davecgh/go-spew v1.1.0/go.mod h1:J7Y8YcW2NihsgmVo/mv3lAwl/skON4iLHjSsI+c5H38=

internal/broker/streams.go

@@ -498,7 +498,14 @@ const EventsStream = "EVENTS"
 // held through a store restart — the exact message the stream exists to protect — some minutes
 // before the controller had finished deciding about it.
 func MeshConsumers() []Consumer {
-	return append([]Consumer{
+	return append(ControllerConsumers(), CheckWorkers()...)
+}
+
+// ControllerConsumers are the consumers the controller's own event loop takes from: MeshConsumers without the build
+// seat's check workers, which the builders take from and the loop never does (issue 1063). A consumer added to the
+// controller is counted here without a change elsewhere.
+func ControllerConsumers() []Consumer {
+	return []Consumer{
 		{
 			Name:           ControllerName,
 			Stream:         "CONTROL",
@@ -558,7 +565,7 @@ func MeshConsumers() []Consumer {
 			Why: "the controller copies each message a consumer gave up on into DEAD_LETTERS; no max-deliver, " +
 				"because a notice it gave up on would lose the message it is about",
 		},
-	}, CheckWorkers()...)
+	}
 }
 
 // NoticesConsumer is the controller's consumer on DEAD_LETTER_NOTICES (novox/hq issue 330).

internal/builder/archive_symlink_test.go

@@ -0,0 +1,149 @@
+package builder
+
+import (
+	"context"
+	"os"
+	"path/filepath"
+	"strings"
+	"testing"
+
+	"git.novox.be/novox/mesh-sdk/go/catalogue"
+)
+
+// A link as a parent of an archive's `from` must not lead the build out of the module: the repository
+// is somebody else's, and a build that followed it would pack, register and serve any directory the
+// build account can read (issue 1609).
+func TestAnArchiveWhoseFromGoesThroughALinkOutOfTheModuleIsRefused(t *testing.T) {
+	outside := t.TempDir()
+	if err := os.MkdirAll(filepath.Join(outside, "x"), 0o755); err != nil {
+		t.Fatal(err)
+	}
+	if err := os.WriteFile(filepath.Join(outside, "x", "secret"), []byte("s"), 0o644); err != nil {
+		t.Fatal(err)
+	}
+	tree := t.TempDir()
+	if err := os.Symlink(outside, filepath.Join(tree, "link")); err != nil {
+		t.Fatal(err)
+	}
+	r := &recorded{}
+	a := catalogue.Artifact{Name: "all", Kind: catalogue.ArtifactArchive, From: "link/x"}
+	_, err := one(context.Background(), nil, r, "m", tree, t.TempDir(), "c", "", a, nil, nil, "", Npmrc{}, nil,
+		nil, func(string, string, ...any) {})
+	if err == nil {
+		t.Fatal("an archive was packed through a link out of the module")
+	}
+	realOutside, _ := filepath.EvalSymlinks(filepath.Join(outside, "x"))
+	realTree, _ := filepath.EvalSymlinks(tree)
+	for _, want := range []string{realOutside, realTree, "link/x"} {
+		if !strings.Contains(err.Error(), want) {
+			t.Errorf("the refusal %q does not name %q", err, want)
+		}
+	}
+	if len(r.archives) != 0 {
+		t.Errorf("a refused archive left %d published", len(r.archives))
+	}
+}
+
+// A link that stays inside the module is still followed, and its archive keeps its digest.
+func TestAnArchiveWhoseFromGoesThroughALinkInsideTheModuleIsPacked(t *testing.T) {
+	tree := t.TempDir()
+	if err := os.MkdirAll(filepath.Join(tree, "real", "x"), 0o755); err != nil {
+		t.Fatal(err)
+	}
+	if err := os.WriteFile(filepath.Join(tree, "real", "x", "f"), []byte("f"), 0o644); err != nil {
+		t.Fatal(err)
+	}
+	if err := os.Symlink("real", filepath.Join(tree, "link")); err != nil {
+		t.Fatal(err)
+	}
+	r := &recorded{}
+	a := catalogue.Artifact{Name: "all", Kind: catalogue.ArtifactArchive, From: "link/x"}
+	if _, err := one(context.Background(), nil, r, "m", tree, t.TempDir(), "c", "", a, nil, nil, "", Npmrc{}, nil,
+		nil, func(string, string, ...any) {}); err != nil {
+		t.Fatal(err)
+	}
+}
+
+// A module directory that is itself a link out of the fetched tree is refused, naming both places.
+func TestAModuleDirectoryThatIsALinkOutOfTheRepositoryIsRefused(t *testing.T) {
+	outside := t.TempDir()
+	if err := os.WriteFile(filepath.Join(outside, ManifestName), []byte("{}"), 0o644); err != nil {
+		t.Fatal(err)
+	}
+	tree := t.TempDir()
+	if err := os.MkdirAll(filepath.Join(tree, "modules"), 0o755); err != nil {
+		t.Fatal(err)
+	}
+	if err := os.Symlink(outside, filepath.Join(tree, "modules", "evil")); err != nil {
+		t.Fatal(err)
+	}
+	_, err := inside(tree, "modules/evil")
+	if err == nil {
+		t.Fatal("a module directory behind a link out of the repository was accepted")
+	}
+	realOutside, _ := filepath.EvalSymlinks(outside)
+	realTree, _ := filepath.EvalSymlinks(tree)
+	for _, want := range []string{realOutside, realTree, "modules/evil"} {
+		if !strings.Contains(err.Error(), want) {
+			t.Errorf("the refusal %q does not name %q", err, want)
+		}
+	}
+	// A link that stays inside the repository, and a module directory not there, are left as they were.
+	if err := os.MkdirAll(filepath.Join(tree, "real"), 0o755); err != nil {
+		t.Fatal(err)
+	}
+	if err := os.Symlink("real", filepath.Join(tree, "modules", "fine")); err != nil {
+		t.Fatal(err)
+	}
+	if _, err := inside(tree, "modules/fine"); err != nil {
+		t.Errorf("a link inside the repository was refused: %v", err)
+	}
+	if _, err := inside(tree, "modules/none"); err != nil {
+		t.Errorf("an absent module directory was refused here: %v", err)
+	}
+}
+
+// A repository that commits `.mesh-build` as a link must not make a bundle's build write into, or pack,
+// a directory outside the module (issue 1609): the compile, the bundling and the pack each refuse it.
+func TestABundleWhoseOutputDirectoryIsALinkOutOfTheModuleIsRefused(t *testing.T) {
+	outside := t.TempDir()
+	if err := os.WriteFile(filepath.Join(outside, "secret"), []byte("s"), 0o644); err != nil {
+		t.Fatal(err)
+	}
+	tree := t.TempDir()
+	if err := os.Symlink(outside, filepath.Join(tree, ".mesh-build")); err != nil {
+		t.Fatal(err)
+	}
+	chain, err := ToolchainFor("go")
+	if err != nil {
+		t.Fatal(err)
+	}
+	a := catalogue.Artifact{Name: "b", Kind: catalogue.ArtifactBundle, Language: "go", From: "cmd/b"}
+	ran := false
+	run := func(context.Context, string, string, ...string) (string, error) { ran = true; return "", nil }
+	realOutside, _ := filepath.EvalSymlinks(outside)
+	realTree, _ := filepath.EvalSymlinks(tree)
+
+	check := func(what string, err error) {
+		t.Helper()
+		if err == nil {
+			t.Fatalf("%s went through a link out of the module", what)
+		}
+		for _, want := range []string{realOutside, realTree} {
+			if !strings.Contains(err.Error(), want) {
+				t.Errorf("%s: the refusal %q does not name %q", what, err, want)
+			}
+		}
+	}
+	_, err = compile(context.Background(), run, tree, chain, "base", a)
+	check("compile", err)
+	_, err = bundled(context.Background(), run, tree, chain, "base", a, nil)
+	check("bundled", err)
+	check("the pack", outsideTheModule(tree, filepath.Join(tree, Out(a.Name))))
+	if ran {
+		t.Error("a command ran for a refused bundle")
+	}
+	if entries, _ := os.ReadDir(outside); len(entries) != 1 {
+		t.Errorf("a refused bundle wrote into the directory outside: %d entries", len(entries))
+	}
+}

internal/builder/builder.go

@@ -943,6 +943,23 @@ func inside(tree, path string) (string, error) {
 		return "", fmt.Errorf(
 			"%q leaves the repository, and a build reads only its own tree", path)
 	}
+	// A link in the fetched tree must not lead the module out of it either (issue 1609): compare where
+	// both really are. A module directory that does not exist is left to the read of its manifest.
+	realTree, err := filepath.EvalSymlinks(tree)
+	if err != nil {
+		return "", err
+	}
+	realWithin, err := filepath.EvalSymlinks(within)
+	if errors.Is(err, os.ErrNotExist) {
+		return within, nil
+	}
+	if err != nil {
+		return "", err
+	}
+	if rel, err := filepath.Rel(realTree, realWithin); err != nil || rel == ".." || strings.HasPrefix(rel, ".."+string(filepath.Separator)) {
+		return "", fmt.Errorf("%q leads out of the repository through a link: it resolves to %s, and the repository is %s",
+			path, realWithin, realTree)
+	}
 	return within, nil
 }
 
@@ -1278,6 +1295,9 @@ func one(ctx context.Context, run Runner, publish Publisher,
 			}
 		}
 		say("bundle", "compiled, packing")
+		if err := outsideTheModule(tree, compiled); err != nil {
+			return catalogue.Built{}, fmt.Errorf("%s: packing %s failed: %w", module, a.Name, err)
+		}
 		body, err := pack(compiled)
 		if err != nil {
 			return catalogue.Built{}, fmt.Errorf("%s: packing %s failed: %w", module, a.Name, err)
@@ -1326,7 +1346,10 @@ func one(ctx context.Context, run Runner, publish Publisher,
 			}
 		} else {
 			src.ownHas(cleanEntry(a.From) + "/**")
-			body, err = pack(filepath.Join(tree, a.From))
+			var root string
+			if root, err = archiveRoot(tree, a); err == nil {
+				body, err = pack(root)
+			}
 		}
 		if err != nil {
 			return catalogue.Built{}, fmt.Errorf("%s: packing %s failed: %w", module, a.Name, err)
@@ -1343,6 +1366,57 @@ func one(ctx context.Context, run Runner, publish Publisher,
 		module, a.Name, a.Kind)
 }
 
+// archiveRoot is the directory an archive artifact is packed from, refused when a link in the fetched
+// tree leads out of the module. The repository is somebody else's: pack follows a link in a parent
+// component of `from`, so without this a committed link makes the build pack, register and serve any
+// directory the build account can read (issue 1609). Both are compared where they really are.
+func archiveRoot(tree string, a catalogue.Artifact) (string, error) {
+	root := filepath.Join(tree, a.From)
+	realTree, err := filepath.EvalSymlinks(tree)
+	if err != nil {
+		return "", err
+	}
+	realRoot, err := filepath.EvalSymlinks(root)
+	if err != nil {
+		return "", err
+	}
+	if rel, err := filepath.Rel(realTree, realRoot); err != nil || rel == ".." || strings.HasPrefix(rel, ".."+string(filepath.Separator)) {
+		return "", fmt.Errorf("the archive %s is taken from %q, which lies outside the module: it resolves to %s, and the module is %s",
+			a.Name, a.From, realRoot, realTree)
+	}
+	return root, nil
+}
+
+// outsideTheModule refuses a path that, once every link in it is followed, is not inside the module's
+// directory, naming where it really is and where the module is. For a path not there yet (an output
+// directory about to be made) the deepest part that exists is the one followed. A repository commits
+// its own links, so `.mesh-build` as a link would otherwise have a bundle's build write into, and pack,
+// any directory the build account can read (issue 1609).
+func outsideTheModule(tree, path string) error {
+	realTree, err := filepath.EvalSymlinks(tree)
+	if err != nil {
+		return err
+	}
+	real, rest := path, ""
+	for {
+		resolved, err := filepath.EvalSymlinks(real)
+		if err == nil {
+			real = filepath.Join(resolved, rest)
+			break
+		}
+		if !errors.Is(err, os.ErrNotExist) || filepath.Dir(real) == real {
+			return err
+		}
+		rest = filepath.Join(filepath.Base(real), rest)
+		real = filepath.Dir(real)
+	}
+	if rel, err := filepath.Rel(realTree, real); err != nil || rel == ".." || strings.HasPrefix(rel, ".."+string(filepath.Separator)) {
+		return fmt.Errorf("%s leads out of the module through a link: it resolves to %s, and the module is %s",
+			path, real, realTree)
+	}
+	return nil
+}
+
 // pack tars and gzips a directory.
 //
 // **Deterministically**: entries sorted, and no timestamps, uid, gid or original names carried
@@ -1646,6 +1720,9 @@ func compile(ctx context.Context, run Runner, tree string, chain Toolchain,
 	// a package in a third (ADR 0040). Compiling them all into one place would have them overwrite
 	// each other and then be packed together, so each bundle compiles and packs alone.
 	out := Out(a.Name)
+	if err := outsideTheModule(tree, filepath.Join(tree, out)); err != nil {
+		return "", err
+	}
 
 	// **The output directory exists before the compiler is told about it.** `tsc --outDir` makes
 	// one; `go build -o` writes a file into a directory and does not create it, failing with a
@@ -1972,6 +2049,9 @@ func bundled(ctx context.Context, run Runner, tree string, chain Toolchain, base
 	a catalogue.Artifact, launchers map[string]string) (string, error) {
 	const within = "/app/modules/module"
 	out, final := Out(a.Name), Out(a.Name)+bundledSuffix
+	if err := outsideTheModule(tree, filepath.Join(tree, final)); err != nil {
+		return "", err
+	}
 	if err := os.RemoveAll(filepath.Join(tree, final)); err != nil {
 		return "", err
 	}

internal/inventory/hold.go

@@ -100,8 +100,9 @@ var ErrPlansBusy = errors.New("another controller is working the plans")
 // returned function and by the session ending, so a controller that dies holding it holds nothing.
 //
 // wait false gives ErrPlansBusy at once when another holds them — the timer's way: the holder is
-// moving the plans already. wait true looks again every HoldPoll for up to HoldWaitFor — an
-// outcome's or a merge's way, which must be written.
+// moving the plans already; and a build outcome's on the event loop, which the build records keep
+// for the look to settle (novox/hq issue 1708). wait true looks again every HoldPoll for up to
+// HoldWaitFor — a merge's way, which must be written.
 func (i *Inventory) HoldPlans(ctx context.Context, wait bool) (func(), error) {
 	deadline := time.Now().Add(HoldWaitFor)
 	for {

internal/inventory/migrations/0107-a-refused-registration-is-kept.sql

@@ -0,0 +1,10 @@
+-- A build's outcome whose registration the mesh refused, by the build's id (novox/hq issue 1708). The build record says
+-- what the builder said, which worked; an outcome the event loop could not take into the plans (another act held them)
+-- is settled from the records by the look, and without this it would read the refused build as built. Kept in the
+-- store so a controller replaced before the settle still fails the plan.
+create table build_refused (
+    id     text primary key,
+    module text not null,
+    why    text not null,
+    at     timestamptz not null default now()
+);

internal/inventory/refused.go

@@ -0,0 +1,33 @@
+package inventory
+
+import "context"
+
+// RecordRefused keeps that the mesh refused to register a build's outcome, and why (novox/hq issue 1708): the build
+// record says the builder's words, which worked, and the look that settles a plan from the records reads this to fail
+// it instead. The first refusal of an id stands.
+func (i *Inventory) RecordRefused(ctx context.Context, id, module, why string) error {
+	_, err := i.store.Pool().Exec(ctx,
+		`insert into build_refused (id, module, why) values ($1, $2, $3) on conflict (id) do nothing`, id, module, why)
+	return err
+}
+
+// RefusedOf is why each of these builds' registration was refused, by id; a build not refused is absent.
+func (i *Inventory) RefusedOf(ctx context.Context, ids []string) (map[string]string, error) {
+	out := map[string]string{}
+	if len(ids) == 0 {
+		return out, nil
+	}
+	rows, err := i.store.Pool().Query(ctx, `select id, why from build_refused where id = any($1)`, ids)
+	if err != nil {
+		return nil, err
+	}
+	defer rows.Close()
+	for rows.Next() {
+		var id, why string
+		if err := rows.Scan(&id, &why); err != nil {
+			return nil, err
+		}
+		out[id] = why
+	}
+	return out, rows.Err()
+}

internal/inventory/refused_test.go

@@ -0,0 +1,28 @@
+//go:build integration
+
+package inventory
+
+import "testing"
+
+// novox/hq issue 1708 (1708/AC6): a refused registration is kept by its build's id, the first refusal standing, and
+// read back for the builds asked about only.
+func TestARefusedRegistrationIsKeptByItsBuild(t *testing.T) {
+	inv := ForTest(t)
+	ctx := t.Context()
+	if err := inv.RecordRefused(ctx, "build-1708-a", "nodered", "a port is taken"); err != nil {
+		t.Fatal(err)
+	}
+	if err := inv.RecordRefused(ctx, "build-1708-a", "nodered", "said again"); err != nil {
+		t.Fatalf("a refusal said twice was refused: %v", err)
+	}
+	got, err := inv.RefusedOf(ctx, []string{"build-1708-a", "build-1708-b"})
+	if err != nil {
+		t.Fatal(err)
+	}
+	if len(got) != 1 || got["build-1708-a"] != "a port is taken" {
+		t.Fatalf("the refusals read back are %v", got)
+	}
+	if none, err := inv.RefusedOf(ctx, nil); err != nil || len(none) != 0 {
+		t.Fatalf("no builds asked about answered %v %v", none, err)
+	}
+}

internal/link/bus.go

@@ -184,6 +184,14 @@ func (b OverNATS) PublishMembershipAfter(ctx context.Context, node, module strin
 	return nil
 }
 
+// MaxPayload is the largest message the connected server takes, as the server told this connection.
+func (b OverNATS) MaxPayload() int64 {
+	if b.Conn == nil {
+		return 0
+	}
+	return b.Conn.MaxPayload()
+}
+
 func (b OverNATS) PublishDeclaration(ctx context.Context, node string, body []byte) error {
 	_, err := b.JS.Publish(DeclareSubject(node), body, nats.Context(ctx))
 	if err != nil {

internal/link/declare.go

@@ -46,8 +46,41 @@ func Declare(ctx context.Context, bus Bus, signer Signer, node string,
 		return err
 	}
 
+	// **Measured before it is sent** (novox/hq issue 1689): the bare bus error said only "maximum payload
+	// exceeded", on 2026-10-21 for the control node's declaration, 2 KB over. The limit is the connection's own.
+	if limit := payloadLimitOf(bus); limit > 0 {
+		size := int64(len(body))
+		if DeclarationMeasured != nil {
+			DeclarationMeasured(ctx, node, size, limit)
+		}
+		if size > limit {
+			return fmt.Errorf("%s's declaration is %d bytes on the wire (%d bytes of declaration, signed and encoded), "+
+				"over the bus's largest message of %d bytes by %d: it cannot be sent (novox/hq issue 1689)",
+				node, size, len(declaration), limit, size-limit)
+		}
+	}
+
 	publish, cancel := context.WithTimeout(ctx, timeout)
 	defer cancel()
 
 	return bus.PublishDeclaration(publish, node, body)
 }
+
+// NearTheLimit is the share of the bus's largest message at which a declaration is said to be near it.
+const NearTheLimit = 0.9
+
+// DeclarationMeasured is told, at every send of a declaration, its size on the wire and the bus's largest message,
+// so the controller raises a condition when it nears the limit and clears it when it is back under (issue 1689).
+// Set by the controller; nil in a test or a tool.
+var DeclarationMeasured func(ctx context.Context, node string, size, limit int64)
+
+// payloadLimiter is a bus that knows its largest message.
+type payloadLimiter interface{ MaxPayload() int64 }
+
+// payloadLimitOf is the bus's largest message in bytes, or 0 when the bus does not say.
+func payloadLimitOf(bus Bus) int64 {
+	if l, ok := bus.(payloadLimiter); ok {
+		return l.MaxPayload()
+	}
+	return 0
+}

internal/link/declare_room_integration_test.go

@@ -0,0 +1,52 @@
+//go:build integration
+
+package link
+
+import (
+	"context"
+	"strings"
+	"testing"
+	"time"
+
+	"github.com/nats-io/nats.go"
+	"github.com/novox/mesh-controller/internal/testbus"
+)
+
+// Against a real bus whose largest message is small: the limit is read from the connection, the one that fits goes
+// through, the one over is refused by us with its size and the limit, not by the client's bare error (issue 1689).
+func TestADeclarationIsMeasuredAgainstTheRealBusLimit(t *testing.T) {
+	s := testbus.StartWithMaxPayload(t, 2048)
+	conn, err := nats.Connect(s.ClientURL())
+	if err != nil {
+		t.Fatal(err)
+	}
+	defer conn.Close()
+	js, err := conn.JetStream()
+	if err != nil {
+		t.Fatal(err)
+	}
+	if _, err := js.AddStream(&nats.StreamConfig{Name: "NODES", Subjects: []string{"mesh.node.*.declare"}}); err != nil {
+		t.Fatal(err)
+	}
+	bus := OverNATS{Conn: conn, JS: js}
+	if bus.MaxPayload() != 2048 {
+		t.Fatalf("the limit read from the connection is %d, expected 2048", bus.MaxPayload())
+	}
+	var told []int64
+	was := DeclarationMeasured
+	DeclarationMeasured = func(_ context.Context, _ string, size, limit int64) { told = append(told, size, limit) }
+	t.Cleanup(func() { DeclarationMeasured = was })
+
+	fits := []byte(`{"a":"` + strings.Repeat("x", 600) + `"}`)
+	if err := Declare(t.Context(), bus, fixedSigner{}, "novox", fits, 5*time.Second); err != nil {
+		t.Fatalf("a declaration under the limit: %v", err)
+	}
+	over := []byte(`{"a":"` + strings.Repeat("x", 1600) + `"}`)
+	err = Declare(t.Context(), bus, fixedSigner{}, "novox", over, 5*time.Second)
+	if err == nil || !strings.Contains(err.Error(), "2048 bytes") || strings.Contains(err.Error(), "maximum payload exceeded") {
+		t.Fatalf("a declaration over the limit: %v", err)
+	}
+	if len(told) != 4 || told[1] != 2048 || told[2] <= 2048 {
+		t.Fatalf("measured %v", told)
+	}
+}

internal/link/declare_room_test.go

@@ -0,0 +1,57 @@
+package link
+
+import (
+	"context"
+	"strings"
+	"testing"
+	"time"
+)
+
+type roomBus struct {
+	Bus
+	limit int64
+	sent  [][]byte
+}
+
+func (b *roomBus) MaxPayload() int64 { return b.limit }
+func (b *roomBus) PublishDeclaration(_ context.Context, _ string, body []byte) error {
+	b.sent = append(b.sent, body)
+	return nil
+}
+
+type fixedSigner struct{}
+
+func (fixedSigner) Sign(context.Context, []byte) ([]byte, error) { return []byte("sig"), nil }
+
+// A declaration is measured as it goes on the wire against the bus's own limit; one over it is refused saying size and
+// limit, and what the measure sees is told to whoever raises a condition (issue 1689).
+func TestADeclarationOverTheBusLimitIsRefusedSayingSizeAndLimit(t *testing.T) {
+	var seen []int64
+	was := DeclarationMeasured
+	DeclarationMeasured = func(_ context.Context, node string, size, limit int64) {
+		if node != "novox" || limit != 400 {
+			t.Errorf("measured %s against %d", node, limit)
+		}
+		seen = append(seen, size)
+	}
+	t.Cleanup(func() { DeclarationMeasured = was })
+
+	bus := &roomBus{limit: 400}
+	small := []byte(`{"a":"` + strings.Repeat("x", 100) + `"}`)
+	if err := Declare(t.Context(), bus, fixedSigner{}, "novox", small, time.Second); err != nil || len(bus.sent) != 1 {
+		t.Fatalf("a small declaration: %v, %d sent", err, len(bus.sent))
+	}
+	if int64(len(bus.sent[0])) != seen[0] {
+		t.Fatalf("measured %d bytes, sent %d", seen[0], len(bus.sent[0]))
+	}
+
+	big := []byte(`{"a":"` + strings.Repeat("x", 300) + `"}`)
+	err := Declare(t.Context(), bus, fixedSigner{}, "novox", big, time.Second)
+	if err == nil || !strings.Contains(err.Error(), "400 bytes") || !strings.Contains(err.Error(), "novox") ||
+		!strings.Contains(err.Error(), "over") || strings.Contains(err.Error(), "maximum payload exceeded") {
+		t.Fatalf("an oversize declaration: %v", err)
+	}
+	if len(bus.sent) != 1 || len(seen) != 2 || seen[1] <= 400 {
+		t.Fatalf("it was sent (%d) or not measured (%v)", len(bus.sent), seen)
+	}
+}

internal/testbus/testbus.go

@@ -56,10 +56,14 @@ var buses sync.Map
 
 // Start is a server with JetStream, for this test alone: on loopback, on a port the system chooses, its
 // store in the test's own directory.
-func Start(t testing.TB) *server.Server {
+func Start(t testing.TB) *server.Server { return StartWithMaxPayload(t, 0) }
+
+// StartWithMaxPayload is Start with the largest message the server takes set to maxPayload bytes; zero keeps the
+// server's default (1 MiB, as the mesh's bus has).
+func StartWithMaxPayload(t testing.TB, maxPayload int32) *server.Server {
 	t.Helper()
 	opts := &server.Options{Host: "127.0.0.1", Port: server.RANDOM_PORT, JetStream: true, StoreDir: t.TempDir(),
-		NoLog: true, NoSigs: true}
+		NoLog: true, NoSigs: true, MaxPayload: maxPayload}
 	s, err := server.NewServer(opts)
 	if err != nil {
 		t.Fatalf("a bus for this test could not be made: %v", err)

modules/route-proxy/go.mod

@@ -1,5 +1,5 @@
 module route-proxy
 
-go 1.25.0
+go 1.26.0
 
-require git.novox.be/novox/mesh-sdk/go v0.1.14-0.20261018003858-f185aedbf5d6
+require git.novox.be/novox/mesh-sdk/go v0.1.14-0.20261021114014-66e8fdaa62e2

modules/route-proxy/go.sum

@@ -1,4 +1,2 @@
-git.novox.be/novox/mesh-sdk/go v0.1.14-0.20261016174426-a4e7f480b3b0 h1:EK84so3Y8JdFT3BHrzj9cPQQrDUPa/d+IdOGnerlmEI=
-git.novox.be/novox/mesh-sdk/go v0.1.14-0.20261016174426-a4e7f480b3b0/go.mod h1:GFuZUElBZ9A++mxgIKo97aXXo+kV0uJ/UkbhQPPIbrY=
-git.novox.be/novox/mesh-sdk/go v0.1.14-0.20261018003858-f185aedbf5d6 h1:Sv1Qzix+U1RpaUkw5IbB0IJEyZ+FqgzHmbZrCZkcWf0=
-git.novox.be/novox/mesh-sdk/go v0.1.14-0.20261018003858-f185aedbf5d6/go.mod h1:GFuZUElBZ9A++mxgIKo97aXXo+kV0uJ/UkbhQPPIbrY=
+git.novox.be/novox/mesh-sdk/go v0.1.14-0.20261021114014-66e8fdaa62e2 h1:Cdl5N56QPfmFBoLHrDfvvyc5Q+PUnTjf3fgYD7imcco=
+git.novox.be/novox/mesh-sdk/go v0.1.14-0.20261021114014-66e8fdaa62e2/go.mod h1:ouERNpZizzwZ0HLEtAypsY9FR20FyUgUYRni6J7kVCY=

modules/route-proxy/vendor/git.novox.be/novox/mesh-sdk/go/README.md

@@ -17,3 +17,5 @@ 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.
+
+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.

modules/route-proxy/vendor/git.novox.be/novox/mesh-sdk/go/merge-check.sh

@@ -5,16 +5,127 @@
 # seat in the mesh's Go toolchain, its own container, because the SDK's merge-check.sh declares it
 # (`# mesh-check-also: go go/merge-check.sh`) — and by hand, from anywhere: `sh go/merge-check.sh`.
 #
-# Formatted, vetted, and its whole suite run: the stdio loop and the local protocol mesh-cli speaks to the
-# node-engine. Standard library only, so nothing is fetched.
+# Formatted, vetted (with and without the build tag `integration`), and run at two levels (novox/hq ADR 0391):
+#
+#   1. the unit level: `go test ./...` untagged, no bus or other process, timed and held to a bound
+#      (unit_bound below); over it the check fails and names the slowest tests (issue 895);
+#   2. the integration level: the whole suite with `-tags integration`, each test against a bus of its
+#      own (internal/testbus, which issue 1171 brings with the first test that needs a bus) so nothing is
+#      serialised. With no tagged test yet, the level runs the unit tests again and says their count.
+#
+# **A test that starts a bus or another process carries `//go:build integration`** as the first line of
+# its file; a file that held both kinds is two files (`<name>_integration_test.go` beside `<name>_test.go`).
+# Each level says its test count and its time.
+#
+# No dependency is committed (no vendor directory: .gitignore; the operator, 2026-10-19; issue 1304). Every dependency
+# is resolved by the version and checksum go.sum names (novox/hq ADR 0405 §5), from its public source: this binding
+# requires nothing of the mesh's own forge. `go mod verify` fails by module name when a downloaded dependency does not
+# match go.sum, and -mod=readonly fails a build whose go.sum lacks an entry instead of writing it. gofmt reads only
+# the binding's own files.
+#
+# Exit 0 is a pass; anything else fails `mesh/repo-check` with the last line printed.
 set -eu
 cd "$(dirname "$0")"
+# The toolchain the check runs in sets -mod=vendor; there is no vendor directory, so it is replaced.
+GOFLAGS="$(printf '%s' "${GOFLAGS:-}" | sed 's/-mod=[a-z]*//g') -mod=readonly"
+export GOFLAGS
+export GOPRIVATE=git.novox.be
 
-unformatted=$(gofmt -l .)
+# **The unit level's bound, in seconds** (issue 895): the slowest package's own test time of the untagged run,
+# the compile not counted. A run over it fails the check and names the slowest tests. The SDK's unit suite is
+# small (its slowest package measured well under a second on a quiet machine), so 2 s leaves room for a busier
+# build node without hiding a test that should carry `integration` instead.
+unit_bound=2
+
+# judge_unit_run says the unit level as `go test -v` reported it and fails when it was over the bound: $1 the
+# file holding the output of the untagged `go test -v` of every package (packages one after another, each
+# ending in its `ok <package> <time>` line), $2 the bound in seconds. Packages run side by side, so the
+# level's time is that of its slowest package; the five slowest tests of the run are named when it is over,
+# so that the bound is kept by making them cheap or by tagging them `integration`, and never by raising it
+# (issue 895).
+judge_unit_run() {
+	out=$1 bound=$2
+	awk '
+		/^--- (PASS|FAIL|SKIP): / {
+			name = $3; took = $4; gsub(/[()s]/, "", took)
+			pending[++n] = took "\t" name
+			if ($2 == "SKIP:") skipped++
+			next
+		}
+		/^(ok|FAIL)[ \t]/ && NF >= 3 && $3 ~ /^[0-9.]+s$/ {
+			t = $3; sub(/s$/, "", t)
+			for (i = 1; i <= n; i++) print "T\t" pending[i] "\t" $2
+			n = 0
+			print "P\t" t "\t" $2
+		}
+		END { print "S\t" skipped + 0 }
+	' "$out" >"$out.judged"
+	tests=$(grep -c '^T' "$out.judged" || true)
+	skipped=$(awk -F'\t' '$1 == "S" {print $2}' "$out.judged")
+	level=$(awk -F'\t' '$1 == "P" && $2 + 0 > m {m = $2 + 0} END {printf "%.2f", m}' "$out.judged")
+	echo "unit level: $tests tests ($skipped skipped), $level s (bound $bound s)"
+	if awk -v t="$level" -v b="$bound" 'BEGIN {exit !(t + 0 > b + 0)}'; then
+		echo "the unit level took $level s, over its bound of $bound s; the slowest tests:"
+		awk -F'\t' '$1 == "T" {print $2 "\t" $4 "\t" $3}' "$out.judged" | sort -t"$(printf '\t')" -k1,1 -nr | head -n 5 |
+			awk -F'\t' '{printf "  %s s  %s  %s\n", $1, $3, $2}'
+		echo "make them cheap (no wait, no process), or give their files //go:build integration if they start a bus or another process"
+		return 1
+	fi
+}
+# `sh go/merge-check.sh judge-unit-run <output> <bound>` runs only the judging of the unit level, on a
+# recorded output.
+if [ "${1:-}" = judge-unit-run ]; then
+	shift
+	judge_unit_run "$@"
+	exit
+fi
+
+if ! fetched=$(go mod download 2>&1); then
+	echo "FAILED: the dependencies cannot be fetched: $(printf '%s\n' "$fetched" | tail -n 1)"
+	exit 1
+fi
+if ! verified=$(go mod verify 2>&1); then
+	echo "FAILED: a dependency does not match go.sum: $verified"
+	exit 1
+fi
+
+unformatted=$(find . -name '*.go' -not -path './vendor/*' | xargs gofmt -l)
 if [ -n "$unformatted" ]; then
 	echo "not gofmt'd:"
 	echo "$unformatted"
 	exit 1
 fi
 go vet ./...
-go test -count=1 ./...
+# The files tagged `integration` are vetted too, or nothing would read them.
+go vet -tags integration ./...
+
+# NOT RACE-CHECKED here: the SDK's suite is small and carries no store or other shared state between
+# packages, so the race detector is not required of this check (novox/hq issue 1175); a module that needs
+# it asks for it in its own merge-check.sh.
+echo "NOT RACE-CHECKED: the Go binding's check runs without the race detector"
+
+work=$(mktemp -d)
+trap 'rm -rf "$work"' EXIT
+
+# The unit level first and alone: every package untagged, no bus or other process (judged above).
+status=0
+go test -count=1 -v ./... >"$work/unit.out" 2>&1 || status=$?
+if [ "$status" -ne 0 ]; then
+	grep -vE '^(=== |[[:space:]]*--- PASS)' "$work/unit.out"
+	echo "the unit level failed (go test exited $status)"
+	exit 1
+fi
+judge_unit_run "$work/unit.out" "$unit_bound"
+
+# The integration level: the whole suite with the tag, each test against its own bus (internal/testbus).
+integration_start=$(date +%s)
+status=0
+go test -tags integration -count=1 -v ./... >"$work/integration.out" 2>&1 || status=$?
+grep -vE '^(=== |[[:space:]]*--- PASS)' "$work/integration.out" || true
+tests=$(grep -cE '^--- (PASS|FAIL|SKIP): ' "$work/integration.out" || true)
+skipped=$(grep -cE '^--- SKIP: ' "$work/integration.out" || true)
+echo "integration level: $tests tests ($skipped skipped), $(($(date +%s) - integration_start)) s"
+if [ "$status" -ne 0 ]; then
+	echo "the integration level failed (go test exited $status)"
+	exit 1
+fi

modules/route-proxy/vendor/git.novox.be/novox/mesh-sdk/go/stdio.go

@@ -57,7 +57,11 @@ type message struct {
 // channel is the one conversation with the runtime: what this bundle writes, serialised, and what
 // it asked and waits for.
 type channel struct {
-	mu        sync.Mutex
+	mu sync.Mutex
+	// wmu orders the writes to the runtime and nothing else: a write waits on the pipe for as long as
+	// the runtime does not read, and mu must never wait with it, or the loop that reads the runtime's
+	// answers stops (issue 1286).
+	wmu       sync.Mutex
 	enc       *json.Encoder
 	next      int
 	waiting   map[string]chan message
@@ -90,8 +94,8 @@ type Envelope struct {
 
 func (c *channel) say(m map[string]any) {
 	m["jsonrpc"] = "2.0"
-	c.mu.Lock()
-	defer c.mu.Unlock()
+	c.wmu.Lock()
+	defer c.wmu.Unlock()
 	_ = c.enc.Encode(m)
 }
 
@@ -472,10 +476,15 @@ func matchFrom(p []string, pi int, k []string, ki int) bool {
 	return matchFrom(p, pi+1, k, ki+1)
 }
 
-// EmitOptions is the provenance an emitter may attach (ADR 0042).
+// EmitOptions is the provenance an emitter may attach (ADR 0042), and the message id it may choose.
 type EmitOptions struct {
 	CausationID string
 	Schema      string
+	// MessageID is the id this emit is sent under, as x-event-id (and, by the tool runner, as the bus's
+	// own Nats-Msg-Id): chosen by the emitter so a repeated publish inside the stream's duplicate window
+	// is kept to one, never generated once an id is given (novox/hq ADR 0436 clause 4). Empty is a random
+	// one, as on main.
+	MessageID string
 }
 
 // Emit asks the runtime to publish an event as this bundle's module, and returns once the bus has
@@ -495,8 +504,17 @@ func Emit(eventType string, body any, opts ...EmitOptions) error {
 	if node == "" {
 		node = "unknown"
 	}
+	id := ""
+	for _, o := range opts {
+		if o.MessageID != "" {
+			id = o.MessageID
+		}
+	}
+	if id == "" {
+		id = eventID()
+	}
 	headers := map[string]string{
-		"x-event-id": eventID(), "x-source": source, "x-node": node,
+		"x-event-id": id, "x-source": source, "x-node": node,
 		"x-time": time.Now().UTC().Format(time.RFC3339Nano), "content-type": "application/json",
 	}
 	for _, o := range opts {

modules/route-proxy/vendor/modules.txt

@@ -1,4 +1,4 @@
-# git.novox.be/novox/mesh-sdk/go v0.1.14-0.20261018003858-f185aedbf5d6
-## explicit; go 1.22
+# git.novox.be/novox/mesh-sdk/go v0.1.14-0.20261021114014-66e8fdaa62e2
+## explicit; go 1.26.0
 git.novox.be/novox/mesh-sdk/go
 git.novox.be/novox/mesh-sdk/go/provider

testdata/beside/CAPTURED

@@ -9,7 +9,7 @@ a second place to clean besides the catalogue itself.
 
 mesh-catalog  e0bc919d4945bb5f13f971f74643a0b714cf45da  modules/*/module.json, modules/nats/Dockerfile
 mesh-host     9d9e3a46c4f5943cfffb413d962ce48b75e2fd39  examples/foundation-first-node.lock
-mesh-sdk      ab0c16ddad260289006a40c5dc6fd4973e0b5e0b  conformance/events/module-event.json
+mesh-sdk      d4deecdb380b69358aae2fdaedcfcc06e1571d42  conformance/events/module-event.json
 
 To move them, from this repository's root, with the two repositories checked out beside it:
 

testdata/store-tests

@@ -167,3 +167,4 @@
 ./cmd/mesh-controller TestAMergeOnTheApproveIntoANewRepositoryAsksTheFirstBuildAndItsOutcomeRegistersTheModule
 ./cmd/mesh-controller TestTheApprovedFirstBuildPassesTheGuardOfAVerbAndIsQueued
 ./cmd/mesh-controller TestAPlanGoesOnWithoutAMachineAwayWhenItsTierIsSent
+./internal/inventory TestARefusedRegistrationIsKeptByItsBuild

vendor/git.novox.be/novox/mesh-sdk/go/catalogue/bucket_shares.go

@@ -0,0 +1,124 @@
+package catalogue
+
+import (
+	"encoding/json"
+	"fmt"
+	"regexp"
+	"sort"
+)
+
+// BucketShare is one entry of `shares` on a module's requirement of `s3-bucket` (novox/hq ADR 0468 §8): who else may
+// put or get in the consumer's bucket, and with which methods. Not the NFS shares of shares.go (ADR 0263).
+//
+//	"requires": [{"name": "s3-bucket", "shares": [{"to": "seat:node-files", "methods": ["put"]},
+//	                                             {"to": "print-and-scan", "methods": ["get"]}]}]
+//
+// `to` is a module name, or `seat:<seat name>`. `methods` is a non-empty subset of get and put, without a repeat.
+// Shares are allowed on `s3-bucket` only, and no two entries name the same `to`.
+type BucketShare struct {
+	To      string   `json:"to"`
+	Methods []string `json:"methods"`
+}
+
+// BucketRequirement is the requirement `shares` may be written on.
+const BucketRequirement = "s3-bucket"
+
+// RequireSharesKey is where a stored manifest keeps the shares of its requirements: beside `requires`, which stays a
+// plain list of names, for the reason OptionalRequiresKey is beside it. An older controller sets the unknown key
+// aside instead of failing the catalogue.
+const RequireSharesKey = "requires-shares"
+
+// SharesValue is the key of the value a consumer gives the provider of s3-bucket in its grant: the list of
+// {to, methods} sorted by `to`. A consumer's own `contributes` may not name it.
+const SharesValue = "shares"
+
+var shareTarget = regexp.MustCompile(`^(seat:)?[a-z0-9][a-z0-9-]*$`)
+
+// checkBucketShares refuses a malformed `shares` of one requirement, naming the entry and ADR 0468 §8.
+func checkBucketShares(requirement string, shares []BucketShare) error {
+	if len(shares) == 0 {
+		return nil
+	}
+	if requirement != BucketRequirement {
+		return fmt.Errorf("requires %s: `shares` is allowed on %s only (novox/hq ADR 0468 §8)", requirement, BucketRequirement)
+	}
+	seen := map[string]bool{}
+	for i, s := range shares {
+		at := fmt.Sprintf("requires %s: shares[%d] (to %q)", requirement, i, s.To)
+		if !shareTarget.MatchString(s.To) {
+			return fmt.Errorf("%s: `to` is a module name or seat:<seat name> (novox/hq ADR 0468 §8)", at)
+		}
+		if seen[s.To] {
+			return fmt.Errorf("%s: a second entry for the same `to` (novox/hq ADR 0468 §8)", at)
+		}
+		seen[s.To] = true
+		if len(s.Methods) == 0 {
+			return fmt.Errorf("%s: `methods` is empty; name get, put or both (novox/hq ADR 0468 §8)", at)
+		}
+		used := map[string]bool{}
+		for _, method := range s.Methods {
+			if method != "get" && method != "put" {
+				return fmt.Errorf("%s: method %q is not get or put (novox/hq ADR 0468 §8)", at, method)
+			}
+			if used[method] {
+				return fmt.Errorf("%s: method %q twice (novox/hq ADR 0468 §8)", at, method)
+			}
+			used[method] = true
+		}
+	}
+	return nil
+}
+
+// readRequireShares reads the stored form's side key.
+func readRequireShares(raw json.RawMessage) (map[string][]BucketShare, error) {
+	var out map[string][]BucketShare
+	if err := json.Unmarshal(raw, &out); err != nil {
+		return nil, fmt.Errorf("%s: an object of requirement to a list of {to, methods}: %w", RequireSharesKey, err)
+	}
+	for requirement, shares := range out {
+		if err := checkBucketShares(requirement, shares); err != nil {
+			return nil, err
+		}
+	}
+	return out, nil
+}
+
+// sortedShares is a requirement's shares as they are handed to the provider: sorted by `to` (a file whose lines move
+// looks changed), each entry's methods sorted, and a copy so the manifest is not reordered.
+func sortedShares(shares []BucketShare) []BucketShare {
+	out := make([]BucketShare, 0, len(shares))
+	for _, s := range shares {
+		methods := append([]string(nil), s.Methods...)
+		sort.Strings(methods)
+		out = append(out, BucketShare{To: s.To, Methods: methods})
+	}
+	sort.Slice(out, func(i, j int) bool { return out[i].To < out[j].To })
+	return out
+}
+
+// withShares adds this module's shares of the requirement to the values it gives the provider. A module whose own
+// `contributes` already names `shares` is refused: the field is the only way to say it (ADR 0468 §8).
+func withShares(m Manifest, requirement string, values map[string]any) (map[string]any, error) {
+	shares := m.RequireShares[requirement]
+	if _, named := values[SharesValue]; named && requirement == BucketRequirement {
+		return nil, fmt.Errorf("%s contributing to %s names `shares`; write it on its requirement instead (novox/hq ADR 0468 §8)",
+			m.Module, requirement)
+	}
+	if len(shares) == 0 {
+		return values, nil
+	}
+	out := make(map[string]any, len(values)+1)
+	for k, v := range values {
+		out[k] = v
+	}
+	listed := []any{}
+	for _, s := range sortedShares(shares) {
+		methods := []any{}
+		for _, method := range s.Methods {
+			methods = append(methods, method)
+		}
+		listed = append(listed, map[string]any{"to": s.To, "methods": methods})
+	}
+	out[SharesValue] = listed
+	return out, nil
+}

vendor/git.novox.be/novox/mesh-sdk/go/catalogue/declaration.go

@@ -1783,6 +1783,10 @@ func (r Resolution) contributions(settings SettingsBy, grants []Grant,
 			if err != nil {
 				return nil, err
 			}
+			// What the module shares of its bucket reaches the provider with the rest (novox/hq ADR 0468 §8).
+			if values, err = withShares(m, to, values); err != nil {
+				return nil, err
+			}
 			out[to] = append(out[to], Contribution{From: m.Module, Values: values})
 		}
 		// Several contributions to one requirement (ADR 0094's sibling for `contributes`): an
@@ -2169,11 +2173,19 @@ func (r Resolution) ContributionsFrom(requirement, module string, settings Setti
 			mine = append(mine, g.Values)
 		}
 	}
+	var asker Manifest
+	for _, m := range r.Modules {
+		if m.Module == module {
+			asker = m
+		}
+	}
 	if len(mine) == 1 {
+		// Its shares are already in, put there where its contribution was composed (contributions).
 		return mine[0], true, nil
 	}
 	if len(mine) > 1 {
-		return map[string]any{}, true, nil
+		values, err := withShares(asker, requirement, map[string]any{})
+		return values, err == nil, err
 	}
 	// It contributes no payload — but a require-only consumer of a parameterless provision (one whose
 	// `serves` names no consumer-supplied key: `redis-cache`, `amqp`) still ASKS for it and must be
@@ -2186,7 +2198,8 @@ func (r Resolution) ContributionsFrom(requirement, module string, settings Setti
 		}
 		for _, req := range m.Requires {
 			if req == requirement {
-				return map[string]any{}, true, nil
+				values, err := withShares(m, requirement, map[string]any{})
+				return values, err == nil, err
 			}
 		}
 	}

vendor/git.novox.be/novox/mesh-sdk/go/catalogue/files.go

@@ -74,6 +74,22 @@ func filesVerbs() []Verb {
 			map[string]string{"path": "an absolute path", "owner": "an account's name or number",
 				"group": "a group's name or number (optional)", "recursive": "\"true\": also everything under a directory"},
 			[]string{"path", "owner"}, []string{"group", "recursive"}, "chown", "chgrp"),
+		Verb{Name: "upload", Description: "Send one file of this node into a bucket of the object store, over a short signed link " +
+			"and never over the bus; answers the key (the file's SHA-256 when none is given), the size and the SHA-256. " +
+			"At most 100 MiB. A place a secret is kept, a known credential file, or a link to one is refused by name, " +
+			"before anything is sent. Read " + filesAsAccount + ".",
+			Input: schema(map[string]string{"path": "an absolute path to a file", "bucket": "the bucket the file goes into",
+				"key": "the object's key (optional; the file's SHA-256 when not given)"}, []string{"path", "bucket"})},
+		// download is a plain Verb, not through write(): write() types its optional arguments as true/false
+		// switches, which a hash and a reason are not (issue 1719).
+		Verb{Name: "download", Description: "Write one object of a bucket to a file of this node, over a short signed link and " +
+			"never over the bus; the old file goes to the node's trash. At most 100 MiB. The bytes must hash to sha256, or to " +
+			"the key when the key is a SHA-256; otherwise no file is written. Refuses a path a module owns " +
+			"unless override names a reason; done as the node's operator account, through sudo -n where its rights do not reach.",
+			Input: schema(map[string]string{"bucket": "the bucket", "key": "the object's key", "path": "an absolute path",
+				"sha256":   "the SHA-256 the bytes must have (optional; the key when that is a SHA-256)",
+				"reason":   "why the file is changed, for the audit trail",
+				"override": overrideWord}, []string{"bucket", "key", "path", "reason"})},
 		Verb{Name: "trash", Description: "What the node's trash holds: each deleted or replaced item with its id, " +
 			"original path and when it went.",
 			Input: schema(map[string]string{}, nil), Replaces: []string{"ls ~/.local/share/Trash"}},

vendor/git.novox.be/novox/mesh-sdk/go/catalogue/manifest.go

@@ -494,6 +494,9 @@ type Manifest struct {
 	// by UnmarshalJSON from the long form of a `requires` entry, {name, optional}, or from the stored
 	// form's `optional-requires` list; never written by hand.
 	OptionalRequires map[string]bool `json:"-"`
+	// RequireShares is who else may use the bucket a module requires, by requirement (BucketShare, novox/hq ADR 0468
+	// §8): filled from the long form's `shares`, or from the stored form's `requires-shares`; never written by hand.
+	RequireShares map[string][]BucketShare `json:"-"`
 
 	// Emits are the events this module publishes, named **locally**: `order.placed`, not a subject
 	// and not a routing key. The mesh derives where it lands (design 29 §1), so reorganising the
@@ -1538,8 +1541,9 @@ func (m *Manifest) UnmarshalJSON(raw []byte) error {
 		delete(keys, "contributes")
 	}
 	var optionalRequires map[string]bool
+	var requireShares map[string][]BucketShare
 	if requires, ok := keys["requires"]; ok && string(requires) != "null" {
-		names, optional, err := readRequires(requires)
+		names, optional, shares, err := readRequires(requires)
 		if err != nil {
 			return err
 		}
@@ -1549,6 +1553,23 @@ func (m *Manifest) UnmarshalJSON(raw []byte) error {
 		}
 		keys["requires"] = plainNames
 		optionalRequires = optional
+		requireShares = shares
+	}
+	// The stored form's shares (RequireSharesKey).
+	if stored, ok := keys[RequireSharesKey]; ok {
+		if string(stored) != "null" {
+			stood, err := readRequireShares(stored)
+			if err != nil {
+				return err
+			}
+			for requirement, shares := range stood {
+				if requireShares == nil {
+					requireShares = map[string][]BucketShare{}
+				}
+				requireShares[requirement] = shares
+			}
+		}
+		delete(keys, RequireSharesKey)
 	}
 	// The stored form: `requires` plain, and which are optional beside it (OptionalRequiresKey).
 	if stored, ok := keys[OptionalRequiresKey]; ok {
@@ -1599,6 +1620,7 @@ func (m *Manifest) UnmarshalJSON(raw []byte) error {
 	m.unknown = unknown
 	m.forms = forms
 	m.OptionalRequires = optionalRequires
+	m.RequireShares = requireShares
 	if len(plain) > 0 {
 		m.Secrets = plain
 	}
@@ -1611,6 +1633,21 @@ func (m *Manifest) UnmarshalJSON(raw []byte) error {
 	if len(contributesMany) > 0 {
 		m.ContributesMany = contributesMany
 	}
+	if err := m.checkSharesNotContributed(); err != nil {
+		return err
+	}
+	return nil
+}
+
+// checkSharesNotContributed refuses a module whose own `contributes` to s3-bucket names `shares` (ADR 0468 §8).
+func (m Manifest) checkSharesNotContributed() error {
+	if len(m.RequireShares[BucketRequirement]) == 0 {
+		return nil
+	}
+	if _, named := m.Contributes[BucketRequirement][SharesValue]; named {
+		return fmt.Errorf("contributes.%s names `shares` and so does its requirement; keep one, the requirement's (novox/hq ADR 0468 §8)",
+			BucketRequirement)
+	}
 	return nil
 }
 
@@ -1655,7 +1692,7 @@ func (m Manifest) marshalFields() ([]byte, error) {
 	if err != nil {
 		return nil, err
 	}
-	if len(m.SecretsMany) == 0 && len(m.ContributesMany) == 0 && len(m.OptionalRequires) == 0 {
+	if len(m.SecretsMany) == 0 && len(m.ContributesMany) == 0 && len(m.OptionalRequires) == 0 && len(m.RequireShares) == 0 {
 		return raw, nil
 	}
 	var keys map[string]json.RawMessage
@@ -1671,6 +1708,13 @@ func (m Manifest) marshalFields() ([]byte, error) {
 		}
 		keys[OptionalRequiresKey] = listed
 	}
+	if len(m.RequireShares) > 0 {
+		listed, err := json.Marshal(m.RequireShares)
+		if err != nil {
+			return nil, err
+		}
+		keys[RequireSharesKey] = listed
+	}
 	if len(m.ContributesMany) > 0 {
 		mergedContributes := map[string]any{}
 		for to, values := range m.Contributes {
@@ -2170,6 +2214,7 @@ func parseManifest(raw []byte, predefined PredefinedList) (Manifest, error) {
 	problems = append(problems, replacesProblems(m)...)
 	problems = append(problems, UnitSettingProblems(m)...)
 	problems = append(problems, OwnerSettingProblems(m)...)
+	problems = append(problems, GroupSettingProblems(m)...)
 	problems = append(problems, endpointNameProblems(m)...)
 	problems = append(problems, RouteProblems(m)...)
 	for _, port := range m.Guards {

vendor/git.novox.be/novox/mesh-sdk/go/catalogue/optional_requirements.go

@@ -32,17 +32,20 @@ const OnlyWhenBound = "only-when-bound"
 type requirementForm struct {
 	Name     string `json:"name"`
 	Optional bool   `json:"optional,omitempty"`
+	// Shares is who else may use the consumer's bucket (BucketShare, novox/hq ADR 0468 §8), on s3-bucket only.
+	Shares []BucketShare `json:"shares,omitempty"`
 }
 
 // readRequires reads `requires` in both of its forms — a bare name, or {name, optional} — into the
 // names and which of them are optional.
-func readRequires(raw json.RawMessage) ([]string, map[string]bool, error) {
+func readRequires(raw json.RawMessage) ([]string, map[string]bool, map[string][]BucketShare, error) {
 	var entries []json.RawMessage
 	if err := json.Unmarshal(raw, &entries); err != nil {
-		return nil, nil, fmt.Errorf("requires: a list of names, or of {name, optional}: %w", err)
+		return nil, nil, nil, fmt.Errorf("requires: a list of names, or of {name, optional}: %w", err)
 	}
 	var names []string
 	optional := map[string]bool{}
+	var shares map[string][]BucketShare
 	for i, e := range entries {
 		var plain string
 		if err := json.Unmarshal(e, &plain); err == nil {
@@ -53,12 +56,21 @@ func readRequires(raw json.RawMessage) ([]string, map[string]bool, error) {
 		dec := json.NewDecoder(bytes.NewReader(e))
 		dec.DisallowUnknownFields()
 		if err := dec.Decode(&full); err != nil {
-			return nil, nil, fmt.Errorf("requires[%d]: a name, or {name, optional} (novox/hq ADR 0330): %w", i, err)
+			return nil, nil, nil, fmt.Errorf("requires[%d]: a name, or {name, optional} (novox/hq ADR 0330): %w", i, err)
 		}
 		if strings.TrimSpace(full.Name) == "" {
-			return nil, nil, fmt.Errorf("requires[%d] names no requirement: {name, optional}", i)
+			return nil, nil, nil, fmt.Errorf("requires[%d] names no requirement: {name, optional}", i)
 		}
 		names = append(names, full.Name)
+		if err := checkBucketShares(full.Name, full.Shares); err != nil {
+			return nil, nil, nil, fmt.Errorf("requires[%d]: %w", i, err)
+		}
+		if len(full.Shares) > 0 {
+			if shares == nil {
+				shares = map[string][]BucketShare{}
+			}
+			shares[full.Name] = full.Shares
+		}
 		if full.Optional {
 			optional[full.Name] = true
 		}
@@ -66,7 +78,7 @@ func readRequires(raw json.RawMessage) ([]string, map[string]bool, error) {
 	if len(optional) == 0 {
 		optional = nil
 	}
-	return names, optional, nil
+	return names, optional, shares, nil
 }
 
 // OptionalRequiresKey is where a stored manifest keeps which of its requirements are optional: beside

vendor/git.novox.be/novox/mesh-sdk/go/catalogue/resolve.go

@@ -904,7 +904,7 @@ func isModule(catalogue map[string]Manifest, want string) bool {
 // machine can host the module as far as its capabilities go.
 func missingCapabilities(m Manifest, node Node) []string {
 	var missing []string
-	for _, c := range m.Capabilities {
+	for _, c := range append(append([]string(nil), m.Capabilities...), impliedCapabilities(m)...) {
 		if !node.Capabilities[c] {
 			missing = append(missing, c)
 		}
@@ -1457,3 +1457,20 @@ func packageNames(m map[string][]string) []string {
 	sort.Strings(names)
 	return names
 }
+
+// ContainerGroups is the capability a node-engine reports when it reads a container's `groups` and passes each as a
+// supplementary group (novox/hq ADR 0480 clause 7, issue 1638). An older engine refuses the key (strict decoding).
+const ContainerGroups = "container-groups"
+
+// impliedCapabilities are the capabilities a module needs for what its resources say, beyond those it declares: a
+// container that names groups needs an engine that reads them, so the module is left out of a machine whose report
+// lacks the capability, naming it, and the field is sent to no engine that would refuse it. None for a module whose
+// containers name no groups.
+func impliedCapabilities(m Manifest) []string {
+	for _, r := range m.Resources {
+		if fmt.Sprint(r["type"]) == "container" && len(groupsOf(r)) > 0 {
+			return []string{ContainerGroups}
+		}
+	}
+	return nil
+}

vendor/git.novox.be/novox/mesh-sdk/go/catalogue/seat_data.go

@@ -66,7 +66,8 @@ var capabilityName = regexp.MustCompile(`^[a-z0-9][a-z0-9-]*$`)
 // names an `if-capability` may give (novox/hq ADR 0255). A name nothing detects would leave its
 // contribution out on every machine, silently, so it is refused. A detector added there is added here.
 var KnownCapabilities = []string{
-	"battery", "container-runtime", "firewall", "graphical-session", "overlay", "package-manager",
+	"battery", "container-groups", "container-runtime", "file-references", "firewall", "graphical-session", "overlay",
+	"package-manager",
 	"power-meter", "privileged", "seat", "service-manager", "uplink-dhcpcd", "uplink-networkmanager",
 	"uplink-systemd-networkd", "user-namespaces", "virtualisation",
 }

vendor/git.novox.be/novox/mesh-sdk/go/catalogue/setting_into.go

@@ -85,6 +85,9 @@ func settingInto(resource map[string]any, layers []Layer, module string) error {
 	if fmt.Sprint(resource["type"]) == "directory" {
 		return settingIntoOwner(resource, layers, module)
 	}
+	if fmt.Sprint(resource["type"]) == "container" {
+		return settingIntoGroups(resource, layers, module)
+	}
 	if fmt.Sprint(resource["type"]) != "file" {
 		return nil
 	}
@@ -343,6 +346,12 @@ func settingKeysAskedOutsideOwners(m Manifest) map[string]bool {
 			if unit, ok := r["unit"].(string); ok {
 				note(unit)
 			}
+		case "container":
+			for _, g := range groupsOf(r) {
+				if s, ok := g.(string); ok {
+					note(s)
+				}
+			}
 		}
 	}
 	inValues := func(values map[string]any) {
@@ -365,3 +374,100 @@ func settingKeysAskedOutsideOwners(m Manifest) map[string]bool {
 	}
 	return used
 }
+
+// A container's supplementary groups may be an operator's value (novox/hq ADR 0480 clause 7, ADR 0348 §11, issue 1636):
+// n8n joins the media library's group, whose number is the machine's, never the definition's (ADR 0112 §1). Each
+// element of `groups` is a whole placeholder or a whole number; a placeholder is filled with the number the
+// config value holds, and the list reaches the node-engine as numbers.
+
+// groupSide is one element of a container's groups: a whole placeholder or a whole number.
+var groupSide = regexp.MustCompile(`^(?:\$\{setting:[a-z0-9][a-z0-9_.-]*\}|[0-9]+)$`)
+
+// groupsOf is a container resource's groups as the manifest wrote them (text or numbers), none when it names none.
+func groupsOf(r map[string]any) []any {
+	groups, _ := r["groups"].([]any)
+	return groups
+}
+
+// GroupSettingProblems refuses, where a manifest is read, a container whose groups hold anything but whole
+// placeholders and whole numbers, or a placeholder whose key the module neither declares nor asks for elsewhere.
+func GroupSettingProblems(m Manifest) []string {
+	var problems []string
+	for _, r := range m.Resources {
+		if fmt.Sprint(r["type"]) != "container" {
+			continue
+		}
+		for _, g := range groupsOf(r) {
+			s, isText := g.(string)
+			if !isText {
+				continue // a number: the declaration judges its value
+			}
+			if !groupSide.MatchString(s) {
+				problems = append(problems, fmt.Sprintf("%s: the container %v's group %q is not a whole "+
+					"${config:key} or a whole number: a supplementary group is a number, and nothing else is "+
+					"written into it (novox/hq ADR 0480 clause 7)", m.Module, r["id"], s))
+				continue
+			}
+			if m.Templated() {
+				continue
+			}
+			for _, key := range settingsUsed(s) {
+				if _, declared := m.Settings[key]; !declared && !m.DeclaresConfig() {
+					continue // the settings form judges its own keys
+				}
+				if _, declared := m.Settings[key]; !declared {
+					problems = append(problems, fmt.Sprintf("%s: the container %v's group says ${config:%s}, and the module "+
+						"declares no such value (novox/hq ADR 0348 §4)", m.Module, r["id"], key))
+				}
+			}
+		}
+	}
+	return problems
+}
+
+// settingIntoGroups fills ${setting:…} in a container's groups, refusing — with the key and why, the resource left as
+// it was — a key nothing sets and a value that is not a whole number above zero. A number is kept; the list that
+// results is numbers alone.
+func settingIntoGroups(resource map[string]any, layers []Layer, module string) error {
+	groups := groupsOf(resource)
+	if len(groups) == 0 {
+		return nil
+	}
+	filled := make([]any, 0, len(groups))
+	for _, g := range groups {
+		s, isText := g.(string)
+		if !isText {
+			if f, isNumber := g.(float64); isNumber && f == float64(int(f)) {
+				g = int(f) // a number the manifest wrote, as the numbers a placeholder gives
+			}
+			filled = append(filled, g)
+			continue
+		}
+		keys := settingsUsed(s)
+		if len(keys) != 1 || settingRef.ReplaceAllString(s, "") != "" {
+			filled = append(filled, g) // not a whole placeholder: the manifest check refuses it
+			continue
+		}
+		key := keys[0]
+		value, set := settingValue(layers, key)
+		if !set {
+			return &UnsetSettingError{Module: module, Setting: key,
+				where: fmt.Sprintf("a container %v whose groups", resource["id"]), setToday: orNoSettings(layers),
+				said: fmt.Sprintf(
+					"%s has a container %v whose groups say ${setting:%s}, and nothing sets %q for it — an operator's "+
+						"value is the assignment's, never the definition's (novox/hq ADR 0112): "+
+						"`settings set %s <file>` with {%q: …}%s",
+					module, resource["id"], key, key, module, key, orNoSettings(layers))}
+		}
+		v := plainly(value)
+		id, whole := wholeID(v)
+		if !whole || id == 0 {
+			return fmt.Errorf("%s: the setting %q is %q, which cannot be a group of the container %v: a supplementary "+
+				"group is a whole number above zero, never a name or other text (novox/hq ADR 0480 clause 7, ADR 0328 §15)",
+				module, key, v, resource["id"])
+		}
+		filled = append(filled, int(id))
+	}
+	resource["groups"] = filled
+	return nil
+}

vendor/git.novox.be/novox/mesh-sdk/go/catalogue/unconsumed_placeholder.go

@@ -56,7 +56,7 @@ type filler struct {
 // seatInto, machineInto and contributionsInto. A pass that comes to read another field adds it here,
 // or the sweep refuses the placeholder it would have filled.
 var fillers = []filler{
-	{namespace: "setting", patterns: []*regexp.Regexp{settingRef}, fields: map[string][]string{"file": {"content"}, "service": {"unit"}, "directory": {"owner"}}},
+	{namespace: "setting", patterns: []*regexp.Regexp{settingRef}, fields: map[string][]string{"file": {"content"}, "service": {"unit"}, "directory": {"owner"}, "container": {"groups"}}},
 	{namespace: "dir", patterns: []*regexp.Regexp{dirRef}, fields: map[string][]string{"*": {"path", "content", "volumes", "env", "env-file"}}},
 	{namespace: "access", patterns: []*regexp.Regexp{accessRef}, fields: map[string][]string{"*": {"path", "content", "volumes", "env", "env-file"}}},
 	{namespace: "secret", patterns: []*regexp.Regexp{placeholder}, fields: map[string][]string{"file": {"content"}},

vendor/git.novox.be/novox/mesh-sdk/go/declaration/declaration.go

@@ -324,6 +324,15 @@ type File struct {
 	// depend on a field somewhere else.
 	Bytes string `json:"bytes,omitempty"`
 
+	// Digest and Size say the content is not carried but fetched: a file over FileReferenceThreshold travels as
+	// the sha256 digest of its content, "sha256:<64 hex>", and its size in bytes, in place of Content or Bytes
+	// (novox/hq ADR 0486 §1). The node-engine fetches the object of that name from FileBucket, checks what it
+	// received against Digest and Size, and only then writes the file. Exclusive with Content, Sealed, Bytes,
+	// VaultSealed and Secrets; sent only to an engine that reports FileReferencesCapability, as an older engine
+	// refuses a field it does not know, whole.
+	Digest string `json:"digest,omitempty"`
+	Size   int64  `json:"size,omitempty"`
+
 	// Owner is the user this belongs to, by name. Absent means root.
 	Owner string `json:"owner,omitempty"`
 
@@ -465,6 +474,10 @@ func (f *File) validate(where string, _ bool) []string {
 			problems = append(problems, where+": a file the vault sealed whole has no holes for secrets")
 		}
 	}
+	problems = append(problems, f.checkReference(where)...)
+	if f.Digest != "" || f.Size != 0 {
+		said = append(said, "digest")
+	}
 	if len(said) > 1 {
 		sort.Strings(said)
 		problems = append(problems, where+
@@ -1454,6 +1467,14 @@ type Container struct {
 	// container runs as its image says. Its key is `identity`, the manifest's word; the field is not, because
 	// a resource's Identity is its id.
 	RunAs *ContainerIdentity `json:"identity,omitempty"`
+
+	// Groups are the supplementary groups the container's process joins, as numbers, each passed to the runtime
+	// as a group to add (novox/hq ADR 0480 clause 7, issue 1636): n8n writes the media library through the
+	// library's group, which a stock image knows nothing of. Each is above zero and below the kernel's "no group"
+	// (ADR 0328 §15: never root). Part of the spec, so a change recreates the container. Absent: none are added.
+	// An older node-engine refuses the key (strict decoding), so the controller sends it only to a node that
+	// reports it reads it.
+	Groups []int64 `json:"groups,omitempty"`
 }
 
 // The ways an image is told who to run as (novox/hq ADR 0325 §2).
@@ -1521,6 +1542,30 @@ func (i *ContainerIdentity) problems(where string, env map[string]string) []stri
 	return problems
 }
 
+// groupProblems refuses a supplementary group that is root's or below it, the kernel's "no group" number, or a
+// number named twice (novox/hq ADR 0480 clause 7, ADR 0328 §15).
+func (c *Container) groupProblems(where string) []string {
+	var problems []string
+	seen := map[int64]bool{}
+	for _, g := range c.Groups {
+		switch {
+		case g == 0:
+			problems = append(problems, fmt.Sprintf("%s: container %s adds group 0, and the mesh never makes or keeps anything "+
+				"as root: a supplementary group is never root's (novox/hq ADR 0328 §15)", where, c.Name))
+		case g < 0:
+			problems = append(problems, fmt.Sprintf("%s: container %s adds group %d, below zero: a group is a whole number "+
+				"above zero", where, c.Name, g))
+		case g >= 1<<32-1:
+			problems = append(problems, fmt.Sprintf("%s: container %s adds group %d, which is the kernel's \"no group\" "+
+				"number or beyond it", where, c.Name, g))
+		case seen[g]:
+			problems = append(problems, fmt.Sprintf("%s: container %s adds group %d twice", where, c.Name, g))
+		}
+		seen[g] = true
+	}
+	return problems
+}
+
 func (c *Container) Identity() string { return c.ID }
 func (c *Container) Kind() Type       { return TypeContainer }
 func (c *Container) Target() string   { return c.Name }
@@ -1603,6 +1648,7 @@ func (c *Container) validate(where string, _ bool) []string {
 			"runs and exits, and joins nothing afterwards")
 	}
 	problems = append(problems, c.RunAs.problems(where+": container "+c.Name, c.Env)...)
+	problems = append(problems, c.groupProblems(where)...)
 	return append(problems, checkImage(where, c.Image)...)
 }
 

vendor/git.novox.be/novox/mesh-sdk/go/declaration/filereference.go

@@ -0,0 +1,125 @@
+package declaration
+
+import (
+	"crypto/sha256"
+	"encoding/base64"
+	"encoding/hex"
+	"fmt"
+	"regexp"
+)
+
+// The three names of a file travelling by digest (novox/hq ADR 0486 §1, §2, §5), shared by the node-engine that
+// reads them and the controller that writes them.
+const (
+	// FileReferenceThreshold is the size above which a file travels by digest: a file of this many bytes or fewer
+	// stays in the declaration as it is.
+	FileReferenceThreshold = 64 * 1024
+	// FileBucket is the object bucket of the bus that holds the contents, each under the hex of its sha256 digest
+	// (ObjectName). The controller alone writes it; a node-engine reads an object by name.
+	FileBucket = "declaration-files"
+	// FileReferencesCapability is what a node-engine reports when it reads a file given as a digest and size.
+	FileReferencesCapability = "file-references"
+)
+
+var digestForm = regexp.MustCompile(`^sha256:[0-9a-f]{64}$`)
+
+// DigestOf is the digest a reference names for a content: "sha256:<64 lower-case hex>".
+func DigestOf(content []byte) string {
+	sum := sha256.Sum256(content)
+	return "sha256:" + hex.EncodeToString(sum[:])
+}
+
+// ObjectName is the name of the object holding the content a digest names: the hex without its "sha256:" prefix.
+func ObjectName(digest string) (string, error) {
+	if !digestForm.MatchString(digest) {
+		return "", fmt.Errorf("digest %q is not sha256:<64 lower-case hex characters>", digest)
+	}
+	return digest[len("sha256:"):], nil
+}
+
+// IsReference reports whether the file gives its content as a digest and size instead of carrying it.
+func (f *File) IsReference() bool { return f.Digest != "" }
+
+// checkReference judges the digest and size, and what a reference may not be given with.
+func (f *File) checkReference(where string) []string {
+	if f.Digest == "" && f.Size == 0 {
+		return nil
+	}
+	var problems []string
+	if !digestForm.MatchString(f.Digest) {
+		problems = append(problems, fmt.Sprintf("%s: digest %q; a file by reference names its content as "+
+			"sha256:<64 lower-case hex characters>", where, f.Digest))
+	}
+	if f.Size <= 0 {
+		problems = append(problems, fmt.Sprintf("%s: size %d; a file by reference states its size in bytes, "+
+			"more than zero", where, f.Size))
+	}
+	if f.Content != "" || f.Bytes != "" || f.Sealed != "" || f.VaultSealed != nil || len(f.Secrets) > 0 {
+		problems = append(problems, where+": a file by reference carries its content in the object its digest "+
+			"names, so it says no content, bytes, sealed, vault-sealed or secrets")
+	}
+	if f.Into != "" {
+		problems = append(problems, where+": a file by reference is written whole; a file written into says its "+
+			"part in content")
+	}
+	return problems
+}
+
+// Body is the bytes the file's content stands for: its content, or its bytes decoded.
+func (f *File) Body() ([]byte, error) {
+	if f.Bytes == "" {
+		return []byte(f.Content), nil
+	}
+	b, err := base64.StdEncoding.DecodeString(f.Bytes)
+	if err != nil {
+		return nil, fmt.Errorf("file %s: bytes are not base64: %w", f.ID, err)
+	}
+	return b, nil
+}
+
+// TravelsByDigest reports whether the controller may put this file's content in the bucket: it is plain content
+// or bytes (not sealed, not filled with secrets, not written into another file) of more than FileReferenceThreshold
+// bytes.
+func (f *File) TravelsByDigest() bool {
+	if f.IsReference() || f.Sealed != "" || f.VaultSealed != nil || len(f.Secrets) > 0 || f.Into != "" {
+		return false
+	}
+	if f.Bytes != "" {
+		// DecodedLen counts padding, so the exact length is taken off the decoded bytes.
+		body, err := f.Body()
+		return err == nil && len(body) > FileReferenceThreshold
+	}
+	return len(f.Content) > FileReferenceThreshold
+}
+
+// AsReference is the file as it is sent to an engine that reports FileReferencesCapability: a copy with the digest
+// and size in place of the content, and the content the controller puts into the bucket under ObjectName(digest).
+// A file that does not travel by digest is refused, not passed through, so a caller cannot send a small file empty.
+func (f *File) AsReference() (File, []byte, error) {
+	if !f.TravelsByDigest() {
+		return File{}, nil, fmt.Errorf("file %s does not travel by digest", f.ID)
+	}
+	body, err := f.Body()
+	if err != nil {
+		return File{}, nil, err
+	}
+	ref := *f
+	ref.Content, ref.Bytes = "", ""
+	ref.Digest, ref.Size = DigestOf(body), int64(len(body))
+	return ref, body, nil
+}
+
+// Verify checks what was fetched against the digest and size the file names; the node-engine writes the file only
+// after it returns nil. A mismatch is the apply's failure, never a partial apply (ADR 0486 §1).
+func (f *File) Verify(body []byte) error {
+	if !f.IsReference() {
+		return fmt.Errorf("file %s is not given by reference", f.ID)
+	}
+	if int64(len(body)) != f.Size {
+		return fmt.Errorf("file %s: the object is %d bytes and the declaration says %d", f.ID, len(body), f.Size)
+	}
+	if got := DigestOf(body); got != f.Digest {
+		return fmt.Errorf("file %s: the object hashes to %s and the declaration names %s", f.ID, got, f.Digest)
+	}
+	return nil
+}

vendor/git.novox.be/novox/mesh-sdk/go/delivery/buildrecord.go

@@ -20,6 +20,16 @@ type BuildRecord struct {
 	At                time.Time     `json:"at,omitzero"`
 	SourceFingerprint string        `json:"source-fingerprint,omitempty"`
 	SourceInputs      *SourceInputs `json:"source-inputs,omitempty"`
+	// Made is what the build made (Build.Made, records.go:110); the digest is the tail of an artifact's Reference.
+	Made []Artifact `json:"made,omitempty"`
+}
+
+// Artifact is one thing a build made: mesh-controller internal/chain/records.go Artifact, json keys name, kind and
+// reference, nothing else (novox/hq ADR 0478 clause 8).
+type Artifact struct {
+	Name      string `json:"name"`
+	Kind      string `json:"kind"`
+	Reference string `json:"reference"`
 }
 
 // BuildsBucket is the bucket the builds are kept in: mesh-controller internal/broker/controller_buckets.go:101,

vendor/git.novox.be/novox/mesh-sdk/go/delivery/source.go

@@ -377,15 +377,46 @@ func (c Candidate) check() error {
 // Manifest, the digest of the module's manifest, the key of the manifests bucket. A value written before has none of
 // the three, and a reader of today's shape ignores them.
 type Module struct {
-	V          int    `json:"v"`
-	FP         string `json:"fp,omitempty"`
-	None       string `json:"none,omitempty"`
-	FP2        string `json:"fp2,omitempty"`
-	None2      string `json:"none2,omitempty"`
-	Manifest   string `json:"manifest,omitempty"`
-	Src        uint64 `json:"src,omitempty"`
-	Repository string `json:"repository"`
-	Commit     string `json:"commit"`
+	V        int    `json:"v"`
+	FP       string `json:"fp,omitempty"`
+	None     string `json:"none,omitempty"`
+	FP2      string `json:"fp2,omitempty"`
+	None2    string `json:"none2,omitempty"`
+	Manifest string `json:"manifest,omitempty"`
+	// Inputs2 are the new-form inputs the merge gave the module, kept so the indexer computes FP2 again when a build
+	// module's toolchain versions appear, with no merge (novox/hq ADR 0465 clause 2). It needs Manifest.
+	Inputs2    *KeptInputs2 `json:"inputs2,omitempty"`
+	Src        uint64       `json:"src,omitempty"`
+	Repository string       `json:"repository"`
+	Commit     string       `json:"commit"`
+	// Path is the module's directory in its repository, trimmed of slashes, and RootPath (".") when its manifest is the
+	// repository's root (novox/hq ADR 0478 clause 9, issue 1615): the build tools need it. Empty means not known: a value
+	// written before the indexer learned paths has none.
+	Path string `json:"path,omitempty"`
+	// Toolchains are the toolchains FP2 was computed with, by language (go, typescript): the version installed and the
+	// build module's recipe version the build nodes agreed on then (novox/hq ADR 0477 clause 2, ADR 0478 clause 3). A builder
+	// builds the fingerprint only with these. Empty when FP2 is empty or the module has no toolchain; a value written
+	// before has none (issue 1615).
+	Toolchains map[string]ToolchainUsed `json:"toolchains,omitempty"`
+}
+
+// RootPath is Module.Path of a module whose manifest is its repository's root.
+const RootPath = "."
+
+// KeptInputs2 are SourceInputs2 without the module's name (the key has it) and without toolchains (those come from
+// the build modules' toolchain keys when the fingerprint is computed): what a Module keeps of a merge.
+type KeptInputs2 struct {
+	Tree     string            `json:"tree"`
+	Bases    []string          `json:"bases,omitempty"`
+	Builder  string            `json:"builder,omitempty"`
+	Contexts map[string]string `json:"contexts,omitempty"`
+	Locks    map[string]string `json:"locks,omitempty"`
+}
+
+// With is the full inputs of module m: the kept ones and the given toolchains.
+func (k KeptInputs2) With(module string, toolchains map[string]Toolchain2) SourceInputs2 {
+	return SourceInputs2{Module: module, Tree: k.Tree, Bases: k.Bases, Builder: k.Builder, Contexts: k.Contexts,
+		Locks: k.Locks, Toolchains: toolchains}
 }
 
 func (m Module) check() error {
@@ -399,6 +430,14 @@ func (m Module) check() error {
 	case m.FP2 != "" && m.None2 != "":
 		return fmt.Errorf("delivery: a module has both fp2 and none2")
 	}
+	for language, t := range m.Toolchains {
+		if t.Version == "" || t.Recipe == "" {
+			return fmt.Errorf("delivery: the module's toolchain of %q needs its version and its recipe version", language)
+		}
+	}
+	if m.Inputs2 != nil && m.Manifest == "" {
+		return fmt.Errorf("delivery: a module keeps new-form inputs but has no manifest digest")
+	}
 	return checkNewForm(m.FP2, m.Manifest)
 }
 
@@ -421,9 +460,14 @@ type Forge struct {
 	Merge      string            `json:"merge,omitempty"`
 	Trees      map[string]string `json:"trees,omitempty"`
 	Root       string            `json:"root,omitempty"`
-	Act        string            `json:"act,omitempty"`
-	Words      string            `json:"words,omitempty"`
-	Open       []OpenPull        `json:"open,omitempty"`
+	// Manifests are the module.json bytes, exact, of each module directory: of the merge's trees on a merged message,
+	// of Dirs at the head on a pull message. Locks are, of each such directory, its lock files' hex sha256 by path
+	// relative to it (novox/hq ADR 0465 clause 1). Older writers send neither.
+	Manifests map[string]string            `json:"manifests,omitempty"`
+	Locks     map[string]map[string]string `json:"locks,omitempty"`
+	Act       string                       `json:"act,omitempty"`
+	Words     string                       `json:"words,omitempty"`
+	Open      []OpenPull                   `json:"open,omitempty"`
 }
 
 func (f Forge) check() error {
@@ -455,6 +499,13 @@ func (f Forge) check() error {
 		if len(f.Dirs) > 0 && !f.DirsKnown {
 			return fmt.Errorf("delivery: a pull message with module directories must say it knows them (dirs-known)")
 		}
+		dirs := map[string]bool{}
+		for _, d := range f.Dirs {
+			dirs[d] = true
+		}
+		if err := f.checkInputs(func(d string) bool { return dirs[d] }, "its module directories"); err != nil {
+			return err
+		}
 	case ForgeMerged:
 		if len(f.Dirs) > 0 || f.DirsKnown {
 			return fmt.Errorf("delivery: a merged message carries no module directories")
@@ -479,10 +530,16 @@ func (f Forge) check() error {
 				return fmt.Errorf("delivery: a merged message's tree of the directory %q is empty", dir)
 			}
 		}
+		if err := f.checkInputs(func(d string) bool { _, ok := f.Trees[d]; return ok }, "its trees"); err != nil {
+			return err
+		}
 	case ForgeRefused:
 		if len(f.Dirs) > 0 || f.DirsKnown {
 			return fmt.Errorf("delivery: a refused message carries no module directories")
 		}
+		if len(f.Manifests) > 0 || len(f.Locks) > 0 {
+			return fmt.Errorf("delivery: a refused message carries no manifests or lock hashes")
+		}
 		if f.Act == "" {
 			return fmt.Errorf("delivery: a refused message needs the act it answers")
 		}
@@ -493,11 +550,35 @@ func (f Forge) check() error {
 	return nil
 }
 
+// checkInputs refuses a manifest or a lock hash of a directory that known does not know (of is what it knows them
+// by), an empty manifest and an empty lock path or hash, naming the directory.
+func (f Forge) checkInputs(known func(dir string) bool, of string) error {
+	for dir, m := range f.Manifests {
+		if !known(dir) {
+			return fmt.Errorf("delivery: the manifest of the directory %q is not of %s", dir, of)
+		}
+		if m == "" {
+			return fmt.Errorf("delivery: the manifest of the directory %q is empty", dir)
+		}
+	}
+	for dir, locks := range f.Locks {
+		if !known(dir) {
+			return fmt.Errorf("delivery: the lock hashes of the directory %q are not of %s", dir, of)
+		}
+		for path, hash := range locks {
+			if path == "" || hash == "" {
+				return fmt.Errorf("delivery: the lock %q of the directory %q has an empty path or hash", path, dir)
+			}
+		}
+	}
+	return nil
+}
+
 // checkOpen refuses an open message that names a repository, a branch, a head or anything of the other kinds, or
 // an open pull request that is not `<owner>/<name>` and a number.
 func (f Forge) checkOpen() error {
 	if f.Repository != "" || f.Branch != "" || f.Number != 0 || f.Head != "" || f.Action != "" || len(f.Dirs) > 0 || f.DirsKnown ||
-		f.Merge != "" || len(f.Trees) > 0 || f.Root != "" || f.Act != "" || f.Words != "" {
+		f.Merge != "" || len(f.Trees) > 0 || len(f.Manifests) > 0 || len(f.Locks) > 0 || f.Root != "" || f.Act != "" || f.Words != "" {
 		return fmt.Errorf("delivery: an open message carries only the open pull requests it names")
 	}
 	for _, p := range f.Open {
@@ -603,7 +684,7 @@ func SameSource(a, b Source) bool { return reflect.DeepEqual(a, b) }
 func SameCandidate(a, b Candidate) bool { return reflect.DeepEqual(a, b) }
 
 // SameModule says whether two modules are the same value.
-func SameModule(a, b Module) bool { return a == b }
+func SameModule(a, b Module) bool { return reflect.DeepEqual(a, b) }
 
 // SameForge says whether two forge messages are the same value.
 func SameForge(a, b Forge) bool { return reflect.DeepEqual(a, b) }

vendor/git.novox.be/novox/mesh-sdk/go/delivery/steps.go

@@ -0,0 +1,116 @@
+package delivery
+
+import (
+	"encoding/json"
+	"fmt"
+	"regexp"
+	"strings"
+	"time"
+)
+
+// StepsState is the name of the state a build module keeps its long steps in; its bucket is `<module>_steps`, built
+// by StepsBucket (novox/hq ADR 0469 clause 2; issue 1471). A tool call is cut at 30 s, so a fetch, a test level or a
+// build answers at once with a step id and writes its progress and its end to the key `<node>.<step id>`.
+const StepsState = "steps"
+
+// StepsBucket is the bucket of a build module's steps.
+func StepsBucket(module string) string { return module + "_" + StepsState }
+
+// The states of a step. A step ends in passed, failed or refused; its key is written for each of them, and that
+// write is the event the step's reader waits on.
+const (
+	StepRunning = "running"
+	StepPassed  = "passed"
+	StepFailed  = "failed"
+	StepRefused = "refused"
+)
+
+var stepIDOK = regexp.MustCompile(`^[a-z0-9]+$`)
+
+func checkStepID(id string) error {
+	if !stepIDOK.MatchString(id) {
+		return fmt.Errorf("delivery: the step id %q is not lower-case letters and digits", id)
+	}
+	return nil
+}
+
+// StepKey is the key of a node's step: `<node>.<id>`. It refuses a node that is not a name and an id that is not
+// lower-case letters and digits (one key token, never a dot).
+func StepKey(node, id string) (string, error) {
+	if err := checkName("node", node); err != nil {
+		return "", err
+	}
+	if err := checkStepID(id); err != nil {
+		return "", err
+	}
+	return node + "." + id, nil
+}
+
+// ParseStepKey is the inverse of StepKey.
+func ParseStepKey(key string) (node, id string, err error) {
+	node, id, ok := strings.Cut(key, ".")
+	if !ok {
+		return "", "", fmt.Errorf("delivery: %q is not a step key, <node>.<id>", key)
+	}
+	if _, err := StepKey(node, id); err != nil {
+		return "", "", fmt.Errorf("delivery: %q is not a step key: %w", key, err)
+	}
+	return node, id, nil
+}
+
+// Step is the value of a steps key: which tool runs on which node, how far it is, when it started and ended (UTC, as
+// the toolchains' At), why it was refused or failed, and what it returned.
+type Step struct {
+	V       int             `json:"v"`
+	ID      string          `json:"id"`
+	Tool    string          `json:"tool"`
+	Node    string          `json:"node"`
+	State   string          `json:"state"`
+	Started time.Time       `json:"started"`
+	Ended   time.Time       `json:"ended,omitzero"`
+	Reason  string          `json:"reason,omitempty"`
+	Result  json.RawMessage `json:"result,omitempty"`
+}
+
+func (s Step) check() error {
+	if err := checkStepID(s.ID); err != nil {
+		return err
+	}
+	if err := checkName("node", s.Node); err != nil {
+		return err
+	}
+	if s.Tool == "" {
+		return fmt.Errorf("delivery: a step needs its tool")
+	}
+	switch s.State {
+	case StepRunning, StepPassed, StepFailed, StepRefused:
+	default:
+		return fmt.Errorf("delivery: the step state %q is not running, passed, failed or refused", s.State)
+	}
+	if len(s.Result) > 0 && !json.Valid(s.Result) {
+		return fmt.Errorf("delivery: the step's result is not JSON")
+	}
+	return nil
+}
+
+// EncodeStep is s as JSON at Version; it refuses an id that is not one key token, a node that is not a name, an empty
+// tool, a state outside the four and a result that is not JSON.
+func EncodeStep(s Step) ([]byte, error) {
+	if err := s.check(); err != nil {
+		return nil, err
+	}
+	s.V = Version
+	return json.Marshal(s)
+}
+
+// DecodeStep reads a steps value; it refuses an unknown version (ErrUnknownVersion) and what EncodeStep refuses.
+func DecodeStep(data []byte) (Step, error) {
+	var s Step
+	if err := decode(data, &s); err != nil {
+		return Step{}, err
+	}
+	if err := s.check(); err != nil {
+		return Step{}, err
+	}
+	return s, nil
+}

vendor/git.novox.be/novox/mesh-sdk/go/delivery/toolchains.go

@@ -0,0 +1,127 @@
+package delivery
+
+import (
+	"encoding/json"
+	"fmt"
+	"sort"
+	"strings"
+	"time"
+)
+
+// ToolchainsState is the name of the state a build module keeps its toolchains in; its bucket is
+// `<module>_toolchains`, built as the SDK names a module's state, by ToolchainsBucket (novox/hq ADR 0465 clause 2).
+const ToolchainsState = "toolchains"
+
+// ToolchainsBucket is the bucket of a build module's toolchains.
+func ToolchainsBucket(module string) string { return module + "_" + ToolchainsState }
+
+// ToolchainNoReport is the reason AgreedToolchain gives when no node has reported a language's toolchain.
+const ToolchainNoReport = "toolchain not yet reported"
+
+func checkToolchainLanguage(language string) error {
+	switch language {
+	case "go", "typescript":
+		return nil
+	}
+	return fmt.Errorf("delivery: the toolchain language %q is not go or typescript", language)
+}
+
+// ToolchainKey is the key of a node's toolchain of one language: `<node>.<language>`. It refuses a node that is not a
+// name and a language other than go or typescript.
+func ToolchainKey(node, language string) (string, error) {
+	if err := checkName("node", node); err != nil {
+		return "", err
+	}
+	if err := checkToolchainLanguage(language); err != nil {
+		return "", err
+	}
+	return node + "." + language, nil
+}
+
+// ParseToolchainKey is the inverse of ToolchainKey.
+func ParseToolchainKey(key string) (node, language string, err error) {
+	node, language, ok := strings.Cut(key, ".")
+	if !ok {
+		return "", "", fmt.Errorf("delivery: %q is not a toolchain key, <node>.<language>", key)
+	}
+	if _, err := ToolchainKey(node, language); err != nil {
+		return "", "", fmt.Errorf("delivery: %q is not a toolchain key: %w", key, err)
+	}
+	return node, language, nil
+}
+
+// Toolchain is the value of a toolchains key: the version of the language's toolchain installed on the node and the
+// build module's recipe version, and when the module saw them.
+type Toolchain struct {
+	V        int       `json:"v"`
+	Language string    `json:"language"`
+	Version  string    `json:"version"`
+	Recipe   string    `json:"recipe"`
+	At       time.Time `json:"at"`
+}
+
+func (t Toolchain) check() error {
+	if err := checkToolchainLanguage(t.Language); err != nil {
+		return err
+	}
+	if t.Version == "" || t.Recipe == "" {
+		return fmt.Errorf("delivery: a %s toolchain needs its version and its recipe", t.Language)
+	}
+	return nil
+}
+
+// EncodeToolchain is t as JSON at Version; it refuses a language other than go or typescript and an empty version or
+// recipe.
+func EncodeToolchain(t Toolchain) ([]byte, error) {
+	if err := t.check(); err != nil {
+		return nil, err
+	}
+	t.V = Version
+	return json.Marshal(t)
+}
+
+// DecodeToolchain reads a toolchains value; it refuses an unknown version (ErrUnknownVersion) and what EncodeToolchain
+// refuses.
+func DecodeToolchain(data []byte) (Toolchain, error) {
+	var t Toolchain
+	if err := decode(data, &t); err != nil {
+		return Toolchain{}, err
+	}
+	if err := t.check(); err != nil {
+		return Toolchain{}, err
+	}
+	return t, nil
+}
+
+// NodeToolchain is one node's entry of a language, as read from the toolchains bucket.
+type NodeToolchain struct {
+	Node string
+	Toolchain
+}
+
+// AgreedToolchain is the one Toolchain2 every node's entry of a language agrees on, or none and why: "toolchain not
+// yet reported" with no entries, and "builders disagree" naming each differing version and recipe with the nodes
+// reporting it when two differ (novox/hq ADR 0405 clause 2). The answer does not depend on the entries' order. The
+// entries must all be of one language.
+func AgreedToolchain(entries []NodeToolchain) (tc Toolchain2, none string) {
+	if len(entries) == 0 {
+		return Toolchain2{}, ToolchainNoReport
+	}
+	groups := map[Toolchain2][]string{}
+	for _, e := range entries {
+		k := Toolchain2{Language: e.Language, Version: e.Version, Recipe: e.Recipe}
+		groups[k] = append(groups[k], e.Node)
+	}
+	if len(groups) == 1 {
+		for k := range groups {
+			return k, ""
+		}
+	}
+	parts := make([]string, 0, len(groups))
+	for k, nodes := range groups {
+		sort.Strings(nodes)
+		parts = append(parts, fmt.Sprintf("%s recipe %s on %s", k.Version, k.Recipe, strings.Join(nodes, ", ")))
+	}
+	sort.Strings(parts)
+	return Toolchain2{}, "builders disagree: " + strings.Join(parts, "; ")
+}

vendor/modules.txt

@@ -1,4 +1,4 @@
-# git.novox.be/novox/mesh-sdk/go v0.1.14-0.20261020085642-ab0c16ddad26
+# git.novox.be/novox/mesh-sdk/go v0.1.14-0.20261021144048-d4deecdb380b
 ## explicit; go 1.26.0
 git.novox.be/novox/mesh-sdk/go/asks
 git.novox.be/novox/mesh-sdk/go/catalogue