Merge pull request 'Say what a person's push recreates before it is sent (hq ADR 0245)' (#123) from feat/a-push-says-what-it-recreates into main

cmd/mesh-controller/push.go

@@ -587,6 +587,9 @@ func pushCommand(ctx context.Context, args []string) error {
 	})
 
 	defer release()
+	// **What it recreates, said before it is sent** (novox/hq ADR 0245): a person's push moves every
+	// module whose build changed, and recreates what changed in it — a gated send said so, a push did not.
+	sayWhatAPushRecreates(ctx, open, sending, os.Stdout)
 	// Each machine's memberships first, then the declarations (novox/hq issue 249, ADR 0160): a push
 	// is the one most operators run, and on 2026-10-01 it was the one path that issued none.
 	bus := overTheBus{open: open, server: server, signer: ident}

cmd/mesh-controller/push_recreates_test.go

@@ -0,0 +1,84 @@
+package main
+
+import (
+	"bytes"
+	"strings"
+	"testing"
+	"time"
+
+	"github.com/novox/mesh-controller/internal/catalogue"
+	"github.com/novox/mesh-controller/internal/link"
+)
+
+// The live case of 2026-10-07, 20:27 UTC: a person's `push` of one machine moved mail to a new build whose
+// automx container had a new image, and recreated it; the push's answer said nothing of it. The push now
+// says, per machine, every module it moves and what that recreates — before it is sent. A module whose
+// build did not change, and one new to the machine, are not moves.
+func TestAPushSaysWhatItRecreates(t *testing.T) {
+	open := aMesh(t)
+	ctx := t.Context()
+	inv := open.inventory
+	start := time.Now().Add(-time.Hour)
+	image := func(c string) string { return "registry.invalid:5000/mailu/x@sha256:" + strings.Repeat(c, 64) }
+	for _, b := range []link.BuildResult{
+		aContainerBuild(t, "mailu", "c74f407a", catalogue.PolicyRecord, start,
+			map[string][2]string{"smtp": {image("a"), ""}, "automx": {image("c"), ""}}),
+		aContainerBuild(t, "postgres", "c1111111", "", start.Add(time.Second),
+			map[string][2]string{"server": {image("e"), ""}}),
+	} {
+		if _, _, err := takeIn(ctx, inv, b); err != nil {
+			t.Fatal(err)
+		}
+	}
+	for _, m := range []string{"mailu", "postgres"} {
+		if _, err := inv.Assign(ctx, "anchor", m); err != nil {
+			t.Fatal(err)
+		}
+	}
+	if err := inv.RecordSent(ctx, nodeID(t, open, "anchor"), "d-anchor",
+		map[string]string{"mailu": "c74f407a", "postgres": "c1111111"}); err != nil {
+		t.Fatal(err)
+	}
+	// Mail's new build: automx's image changes, smtp's does not.
+	if _, _, err := takeIn(ctx, inv, aContainerBuild(t, "mailu", "1ab84e69", catalogue.PolicyRecord,
+		start.Add(time.Minute), map[string][2]string{"smtp": {image("a"), ""}, "automx": {image("d"), ""}})); err != nil {
+		t.Fatal(err)
+	}
+
+	// Composed as a person's push composes it.
+	plan, settings, err := planFor(ctx, open, "anchor")
+	if err != nil {
+		t.Fatal(err)
+	}
+	gens, err := generators(ctx, open)
+	if err != nil {
+		t.Fatal(err)
+	}
+	declared, err := declarationWith(ctx, open, "anchor", plan, settings, gens, Allocating)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if declared.Builds["mailu"] != "1ab84e69" {
+		t.Fatalf("a person's push carries mail at %q", declared.Builds["mailu"])
+	}
+
+	var said bytes.Buffer
+	sayWhatAPushRecreates(ctx, open, []readyNode{{node: "anchor", declared: declared}}, &said)
+	out := said.String()
+	for _, want := range []string{"anchor moves 1 module(s)", "mailu", "c74f407a → 1ab84e69",
+		"recreates 1 of mailu's 2 container(s) (with a new image: automx)"} {
+		if !strings.Contains(out, want) {
+			t.Fatalf("the push says %q; it does not say %q", out, want)
+		}
+	}
+	if strings.Contains(out, "postgres") {
+		t.Fatalf("a module whose build did not change is said to move: %q", out)
+	}
+
+	// A machine never sent anything before has no moves to say.
+	said.Reset()
+	sayWhatAPushRecreates(ctx, open, []readyNode{{node: "laptop", declared: declared}}, &said)
+	if said.Len() != 0 {
+		t.Fatalf("a machine with no last send is said to move: %q", said.String())
+	}
+}

cmd/mesh-controller/release.go

@@ -5,6 +5,7 @@ import (
 	"errors"
 	"flag"
 	"fmt"
+	"io"
 	"slices"
 	"sort"
 	"strings"
@@ -694,6 +695,56 @@ func sayRecreations(ctx context.Context, open *stores, moves []inventory.Carried
 	}
 }
 
+// sayWhatAPushRecreates says, per machine a push is about to send, every module the send moves and what
+// the move recreates (novox/hq ADR 0245) — the same words a gated send keeps on its plan. A person's push
+// carries every module's new build, whatever its policy and whether or not a gate saw it, so it is the
+// send that most needs to say so: on 2026-10-07 a `push` of one machine moved mail to a new build and
+// recreated one of its containers with a new image, and the answer said nothing about it. A machine whose
+// last send's builds are not known is not said, and neither is a failure to read: the push goes on.
+func sayWhatAPushRecreates(ctx context.Context, open *stores, sending []readyNode, w io.Writer) {
+	if len(sending) == 0 {
+		return
+	}
+	f, err := readMoveFacts(ctx, open.inventory)
+	if err != nil {
+		return
+	}
+	for _, r := range sending {
+		sent, known, err := open.inventory.SentBuilds(ctx, r.node)
+		if err != nil || !known {
+			continue
+		}
+		moves := pushMoves(f, r.node, r.declared.Builds, sent)
+		if len(moves) == 0 {
+			continue
+		}
+		sayRecreations(ctx, open, moves)
+		fmt.Fprintf(w, "%s moves %d module(s):\n", r.node, len(moves))
+		for _, mv := range moves {
+			said := mv.Recreates
+			if said == "" {
+				said = "recreates none of its containers, or what it ran is not in the records"
+			}
+			fmt.Fprintf(w, "  %-28s %s → %s: %s\n", mv.Module, short(mv.From), short(mv.To), said)
+		}
+	}
+}
+
+// pushMoves is what a send carrying these builds moves on a machine last sent `sent`: every module it ran
+// before at a build not identical to the one it is now sent. A module new to the machine is not a move.
+func pushMoves(f moveFacts, node string, carries, sent map[string]string) []inventory.CarriedMove {
+	var out []inventory.CarriedMove
+	for m, to := range carries {
+		was, ran := sent[m]
+		if !ran || was == "" || to == "" || f.identical(m, was, to) {
+			continue
+		}
+		out = append(out, inventory.CarriedMove{Module: m, Node: node, From: was, To: to})
+	}
+	sort.Slice(out, func(i, j int) bool { return out[i].Module < out[j].Module })
+	return out
+}
+
 // recreationsSaid is every recreation a send's moves say, joined: what a plan's note carries.
 func recreationsSaid(moves []inventory.CarriedMove) string {
 	var said []string