mesh-delivery-sdk: buildstep and composer move in from mesh-sdk, seat-neutral: the step layout of the part build-step, the case's verdicts and placements as raw JSON (D-8, D-9, ADR 0635 §4; issue 1966)

sdk/buildstep/capacity.go

@@ -0,0 +1,7 @@
+package buildstep
+
+// CapacitySetting is the build modules' setting of the node's build capacity (novox/hq ADR 0525 §5, ADR 0567 §12): how
+// many asks the node takes at once, an integer config value set on each node's layer of mesh-config. No repository names
+// a node: each build module declares it with the default 0, which pulls nothing, and the controller (or mesh-config)
+// lays the node's value into the module's settings file.
+const CapacitySetting = "capacity"

sdk/buildstep/doc.go

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

sdk/buildstep/failure.go

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

sdk/buildstep/helpers.go

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

sdk/buildstep/launchers.go

@@ -0,0 +1,14 @@
+package buildstep
+
+import "git.novox.be/novox/mesh-sdk/go/catalogue"
+
+// LauncherSuffix is what a TypeScript entrypoint's launcher is called beside it: index.js is started as
+// index.serve.mjs (novox/hq ADR 0193), an ES module by its own extension whatever the bundle's package.json says.
+const LauncherSuffix = catalogue.LauncherSuffix
+
+// Launchers are the launchers a bundle's build writes, by entrypoint, relative to the bundle's root
+// (catalogue.Launchers): the one rule mesh-build-node, build-agent, the controller and a node taking in a build share
+// (R4e, issue 1126), so the name a build writes is the name a reader expects.
+func Launchers(language string, entrypoints []string) map[string]string {
+	return catalogue.Launchers(language, entrypoints)
+}

sdk/buildstep/launchers_test.go

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

sdk/buildstep/request.go

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

sdk/buildstep/request_test.go

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

sdk/buildstep/stale.go

@@ -0,0 +1,329 @@
+package buildstep
+
+import (
+	"context"
+	"encoding/json"
+	"errors"
+	"fmt"
+	"os"
+	"strconv"
+	"strings"
+	"time"
+
+	stdio "git.novox.be/novox/mesh-sdk/go"
+)
+
+// RestartReason is why a step a previous process left running is ended.
+const RestartReason = "the build module restarted while it ran"
+
+// Boot is when this process began. A step with no owner (written by an older build) started at or after it is taken
+// for this process's, which may still run it, so EndOne refuses it.
+var Boot = time.Now()
+
+// Owner is this process as a step's owner (Step.Owner): `<boot id>.<pid>.<start>`, the node's boot id
+// (/proc/sys/kernel/random/boot_id), the pid and Boot in milliseconds, base 36. The start keeps two processes apart
+// that a reboot or a pid namespace gave the same pid. A running step whose owner is another is a previous process's.
+var Owner = ownerOf(bootID, os.Getpid(), Boot)
+
+// bootID is the node's boot id as Owner holds it; noBootID when it could not be read, which EndStaleAtStart says once.
+var bootID = readBootID()
+
+const noBootID = "no-boot-id"
+
+func ownerOf(bootID string, pid int, start time.Time) string {
+	return bootID + "." + strconv.Itoa(pid) + "." + strconv.FormatInt(start.UnixMilli(), 36)
+}
+
+// readBootID is the node's boot id, or noBootID where it cannot be read (the pid and the start then tell the processes
+// apart).
+func readBootID() string {
+	b, err := os.ReadFile("/proc/sys/kernel/random/boot_id")
+	if id := strings.TrimSpace(string(b)); err == nil && id != "" {
+		return id
+	}
+	return noBootID
+}
+
+// Scan reads and writes a steps state with its revisions: its keys, a key's stored value and revision (nil and 0 for
+// none), a write that lands only while the key is still at the revision read (KeptState.Update), and a delete of a key
+// still at the revision read; both fail with stdio.ErrChanged when another writer was first.
+type Scan struct {
+	Keys   func() ([]string, error)
+	Get    func(key string) (json.RawMessage, uint64, error)
+	Update func(key string, value any, revision uint64) (uint64, error)
+	Delete func(key string, revision uint64) error
+}
+
+// ScanOf is the Scan of a state the process keeps.
+//
+// Its Delete reads the key again and deletes it only while it is still at the revision read: the runtime's
+// mesh/state.delete takes no revision yet, so a write landing between that read and the delete (a few milliseconds) is
+// deleted with it. For a step key that is a redelivered ask begun on this node in that moment: its running key leaves
+// the steps state until its run writes its end, which its asker still reads (a watch takes puts only).
+func ScanOf(s stdio.KeptState) Scan {
+	get := func(key string) (json.RawMessage, uint64, error) {
+		e, err := s.Get(key)
+		if err != nil || e == nil {
+			return nil, 0, err
+		}
+		return e.Value, e.Revision, nil
+	}
+	return Scan{Keys: s.Keys, Update: s.Update, Get: get, Delete: func(key string, revision uint64) error {
+		_, rev, err := get(key)
+		if err != nil {
+			return err
+		}
+		if rev != revision {
+			return stdio.ErrChanged
+		}
+		return s.Delete(key)
+	}}
+}
+
+// isAsk says a step is a pulled ask's: its key is <node>.<ask id> and its tool is "<kind> ask" (a hand-started step
+// has the tool's name). An ask's key is the stream's to settle, never a restart's: the puller leaves an ask it was
+// running unacknowledged so the stream redelivers it, and the asker's wait takes the first end it reads on the key.
+// A key a gone process owns is deleted, never ended (EndStale); one with no owner is ended only once the asker's bound
+// has passed (StepBound), when it is nobody's.
+func isAsk(key string, s Step) bool {
+	_, _, err := ParseAskStepKey(key)
+	return err == nil && strings.HasSuffix(s.Tool, " ask")
+}
+
+// AskWhat says what an ask is, in one line: its kind, and its repository, head and levels, or its module and
+// fingerprint.
+func AskWhat(a Ask) string {
+	short := func(s string) string {
+		if len(s) > 12 {
+			return s[:12]
+		}
+		return s
+	}
+	str := func(m map[string]any, k string) string { v, _ := m[k].(string); return v }
+	parts := []string{a.Kind + " ask"}
+	switch {
+	case a.Check != nil:
+		parts = append(parts, str(a.Check.Fetch, "repository")+"@"+short(str(a.Check.Fetch, "commit")), "levels "+strings.Join(a.Check.Levels, ","))
+		if a.Check.Run != "" {
+			parts = append(parts, "run "+a.Check.Run)
+		}
+	case a.Build != nil:
+		parts = append(parts, "module "+a.Build.Module)
+		if r := str(a.Build.Fetch, "repository"); r != "" {
+			parts = append(parts, r+"@"+short(str(a.Build.Fetch, "commit")))
+		}
+		if a.Build.FP != "" {
+			parts = append(parts, "fp "+short(a.Build.FP))
+		}
+	case a.Compose != nil:
+		parts = append(parts, "compose", str(a.Compose.Fetch, "repository")+"@"+short(str(a.Compose.Fetch, "commit")))
+	}
+	return strings.Join(parts, ", ")
+}
+
+// endRunning writes step ended failed with why, only while its key is still at revision.
+func endRunning(scan Scan, key string, step Step, revision uint64, why string) error {
+	step.State, step.Reason, step.Ended, step.Result = StepFailed, why, now().UTC(), nil
+	raw, err := EncodeStep(step)
+	if err != nil {
+		return err
+	}
+	_, err = scan.Update(key, json.RawMessage(raw), revision)
+	return err
+}
+
+// EndStale ends this node's running steps that no process of this module runs any more, and answers their ids. Only keys
+// of node are read; a value that is no step is left alone.
+//   - A hand-started step with an owner (Step.Owner) that is not this process (Owner) is ended failed with
+//     RestartReason at once, whatever its age: its process is gone and nothing redelivers it, so nothing else would
+//     write its end (issue 1890, note 21).
+//   - A pulled ask's step with an owner that is not this process is deleted, not ended (novox/hq ADR 0525 §6): the
+//     stream redelivers an ask whose node stopped (the puller neither ends nor acknowledges one at its stop), and its
+//     asker takes the first end it reads, so an end written here would fail a check the redelivery would still run. Its
+//     asker's watch takes puts only and keeps waiting for the redelivery's key, its bound the backstop; the stale running
+//     key leaves the steps state, and with it the delivery view's and the checker's count of what runs (note 21: it
+//     held one of a build node's two slots).
+//   - A step owned by this process is left: it may run now. A redelivered ask begun on this node is owned by it.
+//   - A step with no owner (written by an older build) keeps the earlier rule: a hand-started step started before
+//     `before` (the start of this process) is ended; a pulled ask is left to the stream's redelivery (isAsk) until its
+//     start is older than StepBound, and then ended "past the step bound: its asker stopped waiting at <time>".
+//
+// Each end and delete is logged, naming the step, its owner and why. A key written by another writer since it was read
+// (a redelivered ask's start, a real end) is skipped.
+func EndStale(scan Scan, node string, before time.Time, logf func(string, ...any)) ([]string, error) {
+	keys, err := scan.Keys()
+	if err != nil {
+		return nil, fmt.Errorf("buildstep: listing the steps of %s: %w", node, err)
+	}
+	var ended []string
+	for _, k := range keys {
+		n, _, perr := ParseStepKey(k)
+		if perr != nil || n != node {
+			continue
+		}
+		raw, rev, err := scan.Get(k)
+		if err != nil {
+			return ended, fmt.Errorf("buildstep: reading the step %s: %w", k, err)
+		}
+		if len(raw) == 0 {
+			continue
+		}
+		step, err := DecodeStep(raw)
+		if err != nil || step.State != StepRunning {
+			continue
+		}
+		why, said := staleWhy(k, step, before)
+		if why == "" {
+			continue
+		}
+		done := "ended"
+		if step.Owner != "" && isAsk(k, step) {
+			done = "deleted, left to the stream's redelivery"
+			if scan.Delete == nil {
+				err = fmt.Errorf("the steps state takes no delete")
+			} else {
+				err = scan.Delete(k, rev)
+			}
+		} else {
+			err = endRunning(scan, k, step, rev, why)
+		}
+		if err != nil {
+			if errors.Is(err, stdio.ErrChanged) {
+				continue
+			}
+			return ended, fmt.Errorf("buildstep: ending the step %s: %w", k, err)
+		}
+		if logf != nil {
+			logf("the step %s (%s, started %s) was left running and is %s: %s; %s", k, step.Tool,
+				step.Started.UTC().Format(time.RFC3339), done, why, said)
+		}
+		ended = append(ended, step.ID)
+	}
+	return ended, nil
+}
+
+// staleWhy is why a running step is ended (or, for an ask with an owner, deleted) by EndStale and what the log says of
+// its owner, or "" to leave it.
+func staleWhy(key string, step Step, before time.Time) (why, said string) {
+	switch {
+	case step.Owner == Owner:
+		return "", ""
+	case step.Owner != "":
+		return RestartReason, "its owner " + step.Owner + " is not this process " + Owner
+	case isAsk(key, step):
+		if !step.Started.Add(StepBound).Before(now()) {
+			return "", ""
+		}
+		return "past the step bound: its asker stopped waiting at " + step.Started.Add(StepBound).UTC().Format("2006-01-02T15:04:05Z"),
+			"it names no owner (an older build wrote it)"
+	case step.Started.Before(before):
+		return RestartReason, "it names no owner (an older build wrote it) and started before this process"
+	}
+	return "", ""
+}
+
+// EndOne ends this node's running step id (or the key <node>.<id>) as failed with why. A step that is not running is
+// refused, and so is one this process owns (Owner; for a step with no owner, one started since Boot: it may still run,
+// whether a pulled ask or a step a tool started), one live reports as held, and one whose key changed since it was read.
+func EndOne(scan Scan, node, id, why string, live func(id string) bool) (Step, error) {
+	id = strings.TrimSpace(id)
+	if n, rest, ok := strings.Cut(id, "."); ok {
+		if n != node {
+			return Step{}, fmt.Errorf("the step %q is of node %q, this module runs on %q", id, n, node)
+		}
+		id = rest
+	}
+	if strings.TrimSpace(why) == "" {
+		return Step{}, fmt.Errorf("say why the step is ended (why)")
+	}
+	key, err := StepKey(node, id)
+	if err != nil {
+		return Step{}, err
+	}
+	raw, rev, err := scan.Get(key)
+	if err != nil {
+		return Step{}, err
+	}
+	if len(raw) == 0 {
+		return Step{}, fmt.Errorf("no step %s in the steps state", key)
+	}
+	step, err := DecodeStep(raw)
+	if err != nil {
+		return Step{}, err
+	}
+	if step.State != StepRunning {
+		return Step{}, fmt.Errorf("the step %s is %s, not running", key, step.State)
+	}
+	if step.Owner == Owner || (step.Owner == "" && !step.Started.Before(Boot)) || (live != nil && live(id)) {
+		return Step{}, fmt.Errorf("the step %s was started by this process and may run now; only a step a previous process left is ended", key)
+	}
+	if err := endRunning(scan, key, step, rev, why); err != nil {
+		if errors.Is(err, stdio.ErrChanged) {
+			return Step{}, fmt.Errorf("the step %s changed while it was being ended; read it again", key)
+		}
+		return Step{}, err
+	}
+	step.State, step.Reason = StepFailed, why
+	return step, nil
+}
+
+// StaleAttempts and StaleRetry bound EndStaleAtStart's tries: the steps state is readable once the runtime serves.
+var (
+	StaleAttempts = 6
+	StaleRetry    = 5 * time.Second
+)
+
+// StaleServed is what EndStaleAtStart waits for before it reads the steps state: the runtime serving (stdio.Served).
+// The conformance kit's left-running case (conformance.LeftRunning) hands it a closed channel, to run a module's own
+// start sweep in its test.
+var StaleServed = stdio.Served
+
+// EndStaleAtStart is what a build module runs once at its start, in a goroutine: it waits for the runtime to serve,
+// then ends this node's steps a previous process left running (EndStale), trying again when the state cannot be read
+// yet. A step names its owner, so `before` (the start of this process) matters only for a step with no owner, written
+// by an older build: such a step started before it is a previous process's. When the node's boot id cannot be read it
+// says so once: Owner then tells processes apart by their pid and start only.
+func EndStaleAtStart(ctx context.Context, scan Scan, node string, before time.Time, logf func(string, ...any)) {
+	select {
+	case <-ctx.Done():
+		return
+	case <-StaleServed():
+	}
+	if bootID == noBootID && logf != nil {
+		logf("the boot id of %s cannot be read (/proc/sys/kernel/random/boot_id): its steps' owner is %s, told apart by pid and start only", node, Owner)
+	}
+	for attempt := 1; ; attempt++ {
+		ended, err := EndStale(scan, node, before, logf)
+		if err == nil {
+			if logf != nil {
+				logf("%d steps of %s left running by a previous process ended", len(ended), node)
+			}
+			return
+		}
+		if logf != nil {
+			logf("ending the steps left running (try %d of %d): %v", attempt, StaleAttempts, err)
+		}
+		if attempt >= StaleAttempts {
+			return
+		}
+		select {
+		case <-ctx.Done():
+			return
+		case <-time.After(StaleRetry):
+		}
+	}
+}
+
+// EndStaleRound is EndStale as the module's periodic round runs it: at once, and only when the runtime serves (a round
+// before that is skipped, the start's EndStaleAtStart and the next round cover it). It ends the steps a previous
+// process left and the asks past StepBound.
+func EndStaleRound(scan Scan, node string, logf func(string, ...any)) {
+	select {
+	case <-stdio.Served():
+	default:
+		return
+	}
+	if _, err := EndStale(scan, node, Boot, logf); err != nil && logf != nil {
+		logf("ending the steps left running: %v", err)
+	}
+}

sdk/buildstep/stale_test.go

@@ -0,0 +1,167 @@
+package buildstep
+
+import (
+	"encoding/json"
+	"fmt"
+	"strings"
+	"testing"
+	"time"
+
+	stdio "git.novox.be/novox/mesh-sdk/go"
+)
+
+// scanOf is the steps a keys double holds, last value per key, its revision the count of its puts; a write through
+// Update lands only at the revision read, as the state's does. race, when set, runs once before the next Update's check.
+func scanOf(k *keys, race func(key string)) Scan {
+	return Scan{
+		Keys: func() ([]string, error) {
+			k.mu.Lock()
+			defer k.mu.Unlock()
+			var out []string
+			for key := range k.puts {
+				out = append(out, key)
+			}
+			return out, nil
+		},
+		Get: func(key string) (json.RawMessage, uint64, error) {
+			k.mu.Lock()
+			defer k.mu.Unlock()
+			s, ok := k.puts[key]
+			if !ok {
+				return nil, 0, nil
+			}
+			raw, err := EncodeStep(s[len(s)-1])
+			return raw, uint64(len(s)), err
+		},
+		Delete: func(key string, revision uint64) error {
+			k.mu.Lock()
+			defer k.mu.Unlock()
+			if uint64(len(k.puts[key])) != revision {
+				return stdio.ErrChanged
+			}
+			delete(k.puts, key)
+			return nil
+		},
+		Update: func(key string, value any, revision uint64) (uint64, error) {
+			if race != nil {
+				race(key)
+			}
+			k.mu.Lock()
+			n := uint64(len(k.puts[key]))
+			k.mu.Unlock()
+			if n != revision {
+				return 0, stdio.ErrChanged
+			}
+			return k.put(key, value)
+		},
+	}
+}
+
+// 1890 and 1890/AC6: EndStale ends this node's hand-started running steps of another owner at once, whatever their age,
+// and deletes its asks of another owner (the stream redelivers them, ADR 0525 §6); of
+// the steps with no owner (an older build's), the hand-started ones left running before the process began and the asks
+// past the step bound (a younger ask is the stream's to redeliver); never a step this process owns or a key written
+// meanwhile. EndOne ends one by hand, never one this process owns or started.
+func TestEndStaleAndEndOne(t *testing.T) {
+	k := newKeys()
+	boot := time.Now()
+	oldBoot := Boot
+	Boot = boot
+	defer func() { Boot = oldBoot }()
+	gone := ownerOf("b00t", 4242, boot.Add(-time.Hour))
+	put := func(node, id, tool, state string, started time.Time, owner string) {
+		key, _ := StepKey(node, id)
+		_, _ = k.put(key, json.RawMessage(mustStep(t, Step{ID: id, Tool: tool, Node: node, State: state, Started: started, Owner: owner})))
+	}
+	put("ace", "old1", "build_go_fetch", StepRunning, boot.Add(-time.Hour), "")
+	put("ace", "mjk3l9x0abcdef", "check ask", StepRunning, boot.Add(-time.Hour), "")
+	put("ace", "mjk3l9x0abcdee", "check ask", StepRunning, time.Now().Add(-5*time.Minute), "")
+	put("ace", "mjk3l9x0abcded", "check ask", StepRunning, time.Now().Add(-5*time.Minute), gone) // note 21's ghost
+	put("ace", "gone2", "build_go_test", StepRunning, boot.Add(time.Second), gone)
+	put("ace", "mine1", "check ask", StepRunning, boot.Add(-time.Hour), Owner)
+	put("ace", "raced1", "build_go_test", StepRunning, boot.Add(-time.Hour), "")
+	put("ace", "new1", "build_go_fetch", StepRunning, boot.Add(time.Second), "")
+	put("ace", "done1", "build_go_fetch", StepPassed, boot.Add(-time.Hour), gone)
+	put("g14", "other1", "build_go_fetch", StepRunning, boot.Add(-time.Hour), gone)
+	// raced1 is ended by its own run between the read and the write.
+	raced := false
+	scan := scanOf(k, func(key string) {
+		if key == "ace.raced1" && !raced {
+			raced = true
+			put("ace", "raced1", "build_go_test", StepPassed, boot.Add(-time.Hour), "")
+		}
+	})
+	var said []string
+	ended, err := EndStale(scan, "ace", boot, func(f string, a ...any) { said = append(said, fmt.Sprintf(f, a...)) })
+	if err != nil || len(ended) != 4 {
+		t.Fatalf("ended %v, %v", ended, err)
+	}
+	if _, held := k.puts["ace.mjk3l9x0abcded"]; held {
+		t.Errorf("the ghost ask's key is still held: %+v", k.last("ace.mjk3l9x0abcded"))
+	}
+	for _, key := range []string{"ace.old1", "ace.gone2"} {
+		if s := k.last(key); s.State != StepFailed || s.Reason != RestartReason || s.Ended.IsZero() {
+			t.Errorf("%s = %+v", key, s)
+		}
+	}
+	if s := k.last("ace.mjk3l9x0abcdef"); s.State != StepFailed || !strings.HasPrefix(s.Reason, "past the step bound: its asker stopped waiting at ") {
+		t.Errorf("the old ask = %+v", s)
+	}
+	if log := strings.Join(said, "\n"); !strings.Contains(log, "ace.mjk3l9x0abcded") || !strings.Contains(log, "deleted, left to the stream's redelivery") || !strings.Contains(log, "its owner "+gone+" is not this process "+Owner) {
+		t.Errorf("the log does not name the ghost and its owner:\n%s", log)
+	}
+	for key, state := range map[string]string{"ace.mjk3l9x0abcdee": StepRunning, "ace.mine1": StepRunning, "ace.raced1": StepPassed,
+		"ace.new1": StepRunning, "ace.done1": StepPassed, "g14.other1": StepRunning} {
+		if s := k.last(key); s.State != state {
+			t.Errorf("%s = %s, want %s", key, s.State, state)
+		}
+	}
+	// EndOne: refuses without why, a held step, one this process owns or (with no owner) started, a step not running and
+	// another node's; ends a step a previous process left.
+	for _, c := range []struct{ id, why string }{{"old1", ""}, {"new1", "stuck"}, {"mine1", "stuck"}, {"done1", "x"}, {"g14.other1", "x"}} {
+		if _, err := EndOne(scan, "ace", c.id, c.why, nil); err == nil {
+			t.Errorf("ended %s with why %q", c.id, c.why)
+		}
+	}
+	put("ace", "old2", "build_go_fetch", StepRunning, boot.Add(time.Second), gone)
+	if _, err := EndOne(scan, "ace", "old2", "x", func(string) bool { return true }); err == nil {
+		t.Error("ended a held step")
+	}
+	if _, err := EndOne(scan, "ace", "ace.old2", "stuck for good", nil); err != nil {
+		t.Fatal(err)
+	}
+	if s := k.last("ace.old2"); s.State != StepFailed || s.Reason != "stuck for good" || s.Owner != gone {
+		t.Errorf("old2 = %+v", s)
+	}
+	if a, b := ownerOf("b", 1, boot), ownerOf("b", 1, boot.Add(time.Second)); a == b {
+		t.Errorf("two starts of one pid share the owner %q", a)
+	}
+}
+
+func mustStep(t *testing.T, s Step) []byte {
+	t.Helper()
+	raw, err := EncodeStep(s)
+	if err != nil {
+		t.Fatal(err)
+	}
+	return raw
+}
+
+// 1890: AskWhat names the repository, head and levels of a check ask and the module of a build ask.
+func TestAskWhat(t *testing.T) {
+	var check, build Ask
+	for raw, into := range map[string]*Ask{
+		`{"kind":"check","check":{"fetch":{"repository":"novox/mesh-sdk","commit":"0123456789abcdef0123"},"levels":["unit","integration"]}}`: &check,
+		`{"kind":"delivery","build":{"module":"mesh-x","fp":"abcdef0123456789"}}`:                                                            &build,
+	} {
+		if err := json.Unmarshal([]byte(raw), into); err != nil {
+			t.Fatal(err)
+		}
+	}
+	if got, want := AskWhat(check), "check ask, novox/mesh-sdk@0123456789ab, levels unit,integration"; got != want {
+		t.Errorf("check = %q", got)
+	}
+	if got, want := AskWhat(build), "delivery ask, module mesh-x, fp abcdef012345"; got != want {
+		t.Errorf("build = %q", got)
+	}
+}

sdk/buildstep/step.go

@@ -0,0 +1,22 @@
+// Package buildstep is what both build modules share: the runner of a long step that answers a tool call at once
+// and ends on its key in the module's `steps` state (novox/hq ADR 0469 §2; issue 1471), the toolchain guard
+// (issue 1473), the fetch of one commit over SSH (issue 1474), and the failure contract of a test level with the parsers
+// of go test -json and node --test's TAP that fill it (failure.go, issue 1901; its conformance kit is package conformance).
+package buildstep
+
+import (
+	"crypto/rand"
+	"encoding/hex"
+	"strconv"
+	"time"
+)
+
+var now = time.Now
+
+// NewID is a step id: the time in milliseconds in base 36 and six random hex digits, lower-case letters and
+// digits only, so it is one key token and differs between two steps of one node even in one millisecond.
+func NewID() string {
+	var b [3]byte
+	_, _ = rand.Read(b[:])
+	return strconv.FormatInt(now().UnixMilli(), 36) + hex.EncodeToString(b[:])
+}

sdk/buildstep/step_test.go

@@ -0,0 +1,70 @@
+package buildstep
+
+import (
+	"encoding/json"
+	"sync"
+	"testing"
+	"time"
+)
+
+// keys is a steps state in memory: every value put, in order, per key, and a signal for each end.
+type keys struct {
+	mu    sync.Mutex
+	puts  map[string][]Step
+	ended chan string
+}
+
+func newKeys() *keys { return &keys{puts: map[string][]Step{}, ended: make(chan string, 16)} }
+
+func (k *keys) put(key string, value any) (uint64, error) {
+	step, err := DecodeStep(value.(json.RawMessage))
+	if err != nil {
+		return 0, err
+	}
+	k.mu.Lock()
+	k.puts[key] = append(k.puts[key], step)
+	n := uint64(len(k.puts[key]))
+	k.mu.Unlock()
+	if step.State != StepRunning {
+		k.ended <- key
+	}
+	return n, nil
+}
+
+func (k *keys) last(key string) Step {
+	k.mu.Lock()
+	defer k.mu.Unlock()
+	s := k.puts[key]
+	return s[len(s)-1]
+}
+
+func (k *keys) waitEnd(t *testing.T) string {
+	t.Helper()
+	select {
+	case key := <-k.ended:
+		return key
+	case <-time.After(3 * time.Second):
+		t.Fatal("the step never ended on its key")
+		return ""
+	}
+}
+
+// 1471/AC5: ids made in one and the same millisecond differ, and each is one key token. The clock is fixed
+// while no step runs, so no goroutine reads it meanwhile.
+func TestTwoIDsInOneMillisecondDiffer(t *testing.T) {
+	was := now
+	defer func() { now = was }()
+	at := time.Date(2026, 10, 20, 12, 0, 0, 0, time.UTC)
+	now = func() time.Time { return at }
+	seen := map[string]bool{}
+	for i := 0; i < 50; i++ {
+		id := NewID()
+		if seen[id] {
+			t.Fatalf("id %q handed out twice", id)
+		}
+		seen[id] = true
+		if _, err := StepKey("ace", id); err != nil {
+			t.Errorf("id %q: %v", id, err)
+		}
+	}
+}

sdk/buildstep/steps.go

@@ -0,0 +1,189 @@
+package buildstep
+
+import (
+	"encoding/json"
+	"errors"
+	"fmt"
+	"regexp"
+	"strings"
+	"time"
+)
+
+// The layouts this package reads and writes are the part `build-step`'s, shared by the three build seats'
+// contracts in mesh-delivery-contracts (novox/hq ADR 0634 §6): this package imports no seat's contract, so the Go,
+// image and Node build modules each use it with their own seat's, and the layout is held equal by the part's
+// fixtures (a step's value decodes in both).
+
+// Version is the layout version of a step value; a reader refuses another.
+const Version = 1
+
+// ErrUnknownVersion is what DecodeStep returns for a value whose version is missing or not Version.
+var ErrUnknownVersion = errors.New("buildstep: unknown value version")
+
+// The states of a step.
+const (
+	StepRunning = "running"
+	StepPassed  = "passed"
+	StepFailed  = "failed"
+	StepRefused = "refused"
+)
+
+// StepBound is how long an asker waits for one ask's step once a build node took it (30 minutes): past it the asker
+// has stopped waiting, so a key still running is nobody's.
+const StepBound = 30 * time.Minute
+
+// Step is one value of a build module's `steps` state.
+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"`
+	What    string          `json:"what,omitempty"`
+	Phase   string          `json:"phase,omitempty"`
+	PhaseAt time.Time       `json:"phase-at,omitzero"`
+	Owner   string          `json:"owner,omitempty"`
+}
+
+var (
+	nameOK   = regexp.MustCompile(`^[-/_=a-zA-Z0-9]+$`)
+	stepIDOK = regexp.MustCompile(`^[a-z0-9]+$`)
+	askIDOK  = regexp.MustCompile(`^[0-9a-z]{8,9}[0-9a-f]{6}$`)
+)
+
+func checkNode(node string) error {
+	if node == "" || !nameOK.MatchString(node) {
+		return fmt.Errorf("buildstep: the node name %q is empty or holds a dot, a wildcard, whitespace or a character a key refuses", node)
+	}
+	return nil
+}
+
+// StepKey is the key of a step in the steps state: `<node>.<id>`.
+func StepKey(node, id string) (string, error) {
+	if err := checkNode(node); err != nil {
+		return "", err
+	}
+	if !stepIDOK.MatchString(id) {
+		return "", fmt.Errorf("buildstep: the step id %q is not lower-case letters and digits", id)
+	}
+	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("buildstep: %q is not a step key, <node>.<id>", key)
+	}
+	if _, err := StepKey(node, id); err != nil {
+		return "", "", fmt.Errorf("buildstep: %q is not a step key: %w", key, err)
+	}
+	return node, id, nil
+}
+
+// ParseAskStepKey is ParseStepKey for the key of a pulled ask's step, whose id is the ask's (base-36 milliseconds
+// and six hex digits).
+func ParseAskStepKey(key string) (node, askID string, err error) {
+	node, askID, err = ParseStepKey(key)
+	if err != nil {
+		return "", "", err
+	}
+	if !askIDOK.MatchString(askID) {
+		return "", "", fmt.Errorf("buildstep: %q is not an ask's step key: %q is not an ask id", key, askID)
+	}
+	return node, askID, nil
+}
+
+func (s Step) check() error {
+	if _, err := StepKey(s.Node, s.ID); err != nil {
+		return err
+	}
+	if s.Tool == "" {
+		return fmt.Errorf("buildstep: a step needs its tool")
+	}
+	switch s.State {
+	case StepRunning, StepPassed, StepFailed, StepRefused:
+	default:
+		return fmt.Errorf("buildstep: 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("buildstep: the step's result is not JSON")
+	}
+	return nil
+}
+
+// EncodeStep is a step as its value, refusing one that is not whole.
+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 probe struct {
+		V *int `json:"v"`
+	}
+	if err := json.Unmarshal(data, &probe); err != nil {
+		return Step{}, fmt.Errorf("buildstep: value is not JSON: %w", err)
+	}
+	if probe.V == nil || *probe.V != Version {
+		return Step{}, fmt.Errorf("%w: this reader reads %d", ErrUnknownVersion, Version)
+	}
+	var s Step
+	if err := json.Unmarshal(data, &s); err != nil {
+		return Step{}, fmt.Errorf("buildstep: value does not fit its shape: %w", err)
+	}
+	if err := s.check(); err != nil {
+		return Step{}, err
+	}
+	return s, nil
+}
+
+var (
+	askCommitOK = regexp.MustCompile(`^[0-9a-f]{40}$`)
+	// PackageSemver is a Go semantic version as a delivery group's check names a tagged version (`v0.1.15-feat-x.2`).
+	PackageSemver = regexp.MustCompile(`^v(0|[1-9][0-9]*)\.(0|[1-9][0-9]*)\.(0|[1-9][0-9]*)(-[0-9A-Za-z-]+(\.[0-9A-Za-z-]+)*)?$`)
+)
+
+// PackageVersions are the versions of the mesh packages a build or a check builds against, by package (a Go module's
+// path): each a full commit or a Go semantic version.
+type PackageVersions map[string]string
+
+// Check refuses a package that is no module path or a version that is neither a full commit nor a Go semantic
+// version, naming it.
+func (p PackageVersions) Check() error {
+	for pkg, version := range p {
+		if pkg == "" || strings.ContainsAny(pkg, " \t\n@") || strings.HasPrefix(pkg, "/") {
+			return fmt.Errorf("buildstep: the package %q is no module path", pkg)
+		}
+		if !askCommitOK.MatchString(version) && !PackageSemver.MatchString(version) {
+			return fmt.Errorf("buildstep: the package %s names the version %q, which is neither a full commit nor a Go semantic version (v0.1.15-feat-x.2)", pkg, version)
+		}
+	}
+	return nil
+}
+
+// Ask is the part of a build seat's ask that AskWhat reads: the layout is the part's `StepAsk`.
+type Ask struct {
+	Kind  string `json:"kind"`
+	Build *struct {
+		Module string         `json:"module"`
+		FP     string         `json:"fp"`
+		Fetch  map[string]any `json:"fetch"`
+	} `json:"build"`
+	Check *struct {
+		Fetch  map[string]any `json:"fetch"`
+		Levels []string       `json:"levels"`
+		Run    string         `json:"run"`
+	} `json:"check"`
+	Compose *struct {
+		Fetch map[string]any `json:"fetch"`
+	} `json:"compose"`
+}

sdk/buildstep/trees.go

@@ -0,0 +1,15 @@
+package buildstep
+
+// ModuleTree is what a merge holds of one module directory, as a build module's preview answers it (novox/hq ADR 0484
+// clause 3, as ADR 0593 §2 changes it): its git tree id, the sha256 of its module.json, the sha256 of each lock file it
+// has (go.sum, package-lock.json), and, of a module whose every artifact names its paths, each named path's git object
+// id at the commit. The indexer alone computes from them (the named tree, the fingerprint); the build module's runner
+// (mesh-build-go's buildstep.ModuleTrees) fills them.
+type ModuleTree struct {
+	Tree     string            `json:"tree"`
+	Manifest string            `json:"manifest"`
+	Locks    map[string]string `json:"locks,omitempty"`
+	Paths    map[string]string `json:"paths,omitempty"`
+	// Packages are no longer filled (ADR 0593 §2): kept so a preview written before still decodes.
+	Packages []string `json:"packages,omitempty"`
+}

sdk/composer/composer.go

@@ -0,0 +1,209 @@
+// Package composer is the shape of a composition over a plain request (novox/hq ADR 0482 clause 4, issue 1621, as ADR
+// 0593 §7 changes it): the request the command mesh-compose reads and the verdict it answers. The command and the
+// composer that runs it are the node-engine's (mesh-host cmd/mesh-compose), built from its repository at a group's
+// head, so a change to its composition code is judged by that code.
+//
+// **It reads its request and nothing else.** No bus, store, network, file or environment: the manifests come inside the
+// request (raw, as their repository holds them), the rest of the mesh is a compose.Input, and the answer is a value.
+// A manifest named only by its digest in the delivery indexer's bucket is filled before the run by Fill, by whoever
+// holds the bus (the Go build module's compose job); Run refuses a digest left unfilled.
+package composer
+
+import (
+	"encoding/json"
+	"errors"
+	"fmt"
+	"slices"
+
+	"git.novox.be/novox/mesh-sdk/go/catalogue"
+)
+
+// Version is the version of a Request and of a Verdict; a reader refuses another.
+const Version = 1
+
+// Package is the import path of the command, which a compose job builds at a commit of the node-engine's repository
+// (novox/hq ADR 0593 §7).
+const Package = "github.com/novox/mesh-host/cmd/mesh-compose"
+
+// The depths of a composition.
+const (
+	// DepthResolve resolves each machine's set over the rest of the mesh (compose.Resolve): what the assigner judges
+	// while the facts snapshot is not on the bus (issue 1461).
+	DepthResolve = "resolve"
+	// DepthCompose composes each machine's whole declaration and runs the node-engine's validator over it
+	// (compose.Compose).
+	DepthCompose = "compose"
+)
+
+// Request is everything one run composes: the rest of the mesh, one or more cases of manifests composed over it, and
+// the machines composed in each case.
+type Request struct {
+	V int `json:"v"`
+	// Input is the composition's input without its catalogue (and without each node's kept manifests): the cases give
+	// those. A Catalogue or Kept it holds is ignored. It is the node-engine's composition input as JSON, which only the
+	// composer decodes (novox/hq ADR 0593 §7), so this shape imports no composition.
+	Input json.RawMessage `json:"input"`
+	// Cases are composed one after the other over Input, each with its own manifests; their names are unique.
+	Cases []Case `json:"cases"`
+	// Machines are the nodes composed in every case; none means the manifests are only read.
+	Machines []string `json:"machines,omitempty"`
+	// Depth is DepthResolve or DepthCompose; empty is DepthCompose.
+	Depth string `json:"depth,omitempty"`
+	// HoldingsFromClaims adds to Input's holdings every seat an assigned module claims, held on its node (the
+	// assigner's input, which has no holdings of record).
+	HoldingsFromClaims bool `json:"holdings_from_claims,omitempty"`
+	// Declarations asks each composed machine's declared paths (DepthCompose only).
+	Declarations bool `json:"declarations,omitempty"`
+	// Predefined is the list of predefined keys at the catalogue's root (predefined.json, novox/hq ADR 0348 §7). No
+	// longer read: the composer judges no manifest (novox/hq ADR 0578 §5), the indexer's judge does, and its verdicts
+	// come in each case's Verdicts. Kept so an asker that still sends it is read.
+	Predefined catalogue.PredefinedList `json:"predefined,omitempty"`
+	// Packages are the known packages a manifest's `packages` may name, each by its name in its own ecosystem (design 32:
+	// a Go package's go.mod module path, a TypeScript package's package.json name), for the indexer's judge (novox/hq ADR
+	// 0578 §5, ADR 0606 §4); the composer does not read them. Nil is no list at hand, and the judge judges no name; an
+	// empty list is a list, and every name is unknown to it.
+	Packages []string `json:"packages,omitzero"`
+}
+
+// Case is one catalogue composed: every module's manifest by name, and per node the manifests kept at the build it runs.
+//
+// Placements are, by node, the placement the case composes that node with in place of what Input says of it: a change's
+// own placement files, so a check composes a catalogue pull request's placement (issue 1126, frombus.Placed); a null
+// placement leaves nothing placed on the node. A case without them composes Input's.
+//
+// Verdicts are, by module, as raw JSON (this package is seat-neutral, novox/hq ADR 0635 §4; the node-engine's composer decodes the
+// mesh-catalog seat's manifest verdict, and Placements the mesh-module-assigner seat's placement), the indexer's judge's verdict on its manifest in Manifests (novox/hq ADR 0578 §5), put in by
+// the assigner or the checker that runs the composer: a refused one is held, composed as its stub so what it offers
+// still shapes the rest, and named in the case's verdict. A module without one is accepted (the mesh-catalog seat's ManifestVerdict, taken by its readers).
+type Case struct {
+	Name       string                         `json:"name"`
+	Manifests  map[string]Manifest            `json:"manifests"`
+	Verdicts   map[string]json.RawMessage     `json:"verdicts,omitempty"`
+	Kept       map[string]map[string]Manifest `json:"kept,omitempty"`
+	Placements map[string]json.RawMessage     `json:"placements,omitempty"`
+}
+
+// Manifest is a module's manifest as its repository holds it (Raw, the bytes), or the digest the delivery indexer keeps
+// it under (Digest), which Fill replaces by the bytes. On the wire it is the manifest itself, or {"digest": "..."}.
+type Manifest struct {
+	Raw    json.RawMessage
+	Digest string
+}
+
+// MarshalJSON writes the raw manifest, or {"digest": ...} when only the digest is known.
+func (m Manifest) MarshalJSON() ([]byte, error) {
+	if len(m.Raw) > 0 {
+		return m.Raw, nil
+	}
+	return json.Marshal(map[string]string{"digest": m.Digest})
+}
+
+// UnmarshalJSON reads {"digest": "..."} (an object with that one key) as a digest, and any other value as the raw
+// manifest.
+func (m *Manifest) UnmarshalJSON(raw []byte) error {
+	var probe map[string]json.RawMessage
+	if json.Unmarshal(raw, &probe) == nil && len(probe) == 1 {
+		if d, ok := probe["digest"]; ok {
+			var digest string
+			if err := json.Unmarshal(d, &digest); err != nil {
+				return fmt.Errorf("a manifest's digest is not a string: %w", err)
+			}
+			*m = Manifest{Digest: digest}
+			return nil
+		}
+	}
+	*m = Manifest{Raw: slices.Clone(raw)}
+	return nil
+}
+
+// Verdict is what one run answers: the mesh-sdk the command was built with, and each case's verdict in the order asked.
+type Verdict struct {
+	V     int           `json:"v"`
+	SDK   string        `json:"sdk"`
+	Cases []CaseVerdict `json:"cases"`
+}
+
+// CaseVerdict is one case's: every manifest read or refused, every machine composed or not.
+type CaseVerdict struct {
+	Name      string                  `json:"name"`
+	Manifests map[string]ManifestRead `json:"manifests"`
+	Machines  map[string]Machine      `json:"machines,omitempty"`
+}
+
+// ManifestRead is one manifest as this mesh-sdk reads it: accepted, or refused with why: the indexer's verdict
+// (Case.Verdicts) or bytes that do not decode. A field the decoder does not know is set aside, named in SetAside, and
+// the manifest still accepted (novox/hq ADR 0578 §6).
+type ManifestRead struct {
+	Accepted bool   `json:"accepted"`
+	Refused  string `json:"refused,omitempty"`
+	SetAside string `json:"set_aside,omitempty"`
+}
+
+// Machine is one machine composed: whether it composes (resolves, at DepthResolve), why not, the node-engine
+// validator's problems and the composition's refusals (DepthCompose), and its declared paths when asked. NotJudged says,
+// in words, why the composer did not judge the machine (an older node-engine's input that does not say how it composes,
+// novox/hq ADR 0593 §9): the machine is then neither composed nor refused, and a reader decides by this field alone,
+// never by the words of Reason.
+type Machine struct {
+	Composes  bool     `json:"composes"`
+	NotJudged string   `json:"not_judged,omitempty"`
+	Reason    string   `json:"reason,omitempty"`
+	Problems  []string `json:"problems,omitempty"`
+	Refusals  []string `json:"refusals,omitempty"`
+	Declared  []Path   `json:"declared,omitempty"`
+}
+
+// Path is one path a declaration puts on the machine, with its kind (the resource's type), owner, group and mode as
+// declared, and the module it is of.
+type Path struct {
+	Path   string `json:"path"`
+	Kind   string `json:"kind"`
+	Owner  string `json:"owner,omitempty"`
+	Group  string `json:"group,omitempty"`
+	Mode   string `json:"mode,omitempty"`
+	Module string `json:"module,omitempty"`
+}
+
+// ErrUnfilled is a manifest named by a digest that nobody replaced by its bytes.
+var ErrUnfilled = errors.New("composer: a manifest is named by its digest and was not filled")
+
+// Decode reads a request; it refuses one that is not JSON or of another version.
+func Decode(data []byte) (Request, error) {
+	var r Request
+	if err := json.Unmarshal(data, &r); err != nil {
+		return Request{}, fmt.Errorf("composer: the request is not JSON of its shape: %w", err)
+	}
+	if r.V != Version {
+		return Request{}, fmt.Errorf("composer: a request of version %d, this composer reads %d", r.V, Version)
+	}
+	return r, nil
+}
+
+// Fill replaces every manifest named by its digest by the bytes get answers for that digest; a digest get cannot answer
+// stops it, named.
+func Fill(r *Request, get func(digest string) ([]byte, error)) error {
+	fill := func(m map[string]Manifest) error {
+		for name, man := range m {
+			if len(man.Raw) > 0 {
+				continue
+			}
+			raw, err := get(man.Digest)
+			if err != nil {
+				return fmt.Errorf("composer: the manifest of %s (digest %s): %w", name, man.Digest, err)
+			}
+			m[name] = Manifest{Raw: raw}
+		}
+		return nil
+	}
+	for _, c := range r.Cases {
+		if err := fill(c.Manifests); err != nil {
+			return err
+		}
+		for _, kept := range c.Kept {
+			if err := fill(kept); err != nil {
+				return err
+			}
+		}
+	}
+	return nil
+}

sdk/composer/composer_test.go

@@ -0,0 +1,58 @@
+package composer
+
+import (
+	"encoding/json"
+	"errors"
+	"strings"
+	"testing"
+)
+
+const demo = `{"module": "demo", "version": "1", "claims": [{"name": "node-files"}]}`
+
+// A manifest named by its digest goes on the wire as {"digest": ...}, and Fill puts the bytes the indexer keeps in its
+// place; a raw manifest goes as itself.
+func TestAManifestIsItsBytesOrItsDigest(t *testing.T) {
+	r := Request{V: Version, Cases: []Case{{Name: "change", Manifests: map[string]Manifest{
+		"demo": {Digest: "d1"}, "raw": {Raw: json.RawMessage(`{"module":"raw","version":"1"}`)}},
+		Kept: map[string]map[string]Manifest{"laptop": {"demo": {Digest: "d1"}}}}}}
+	wire, err := json.Marshal(r)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if !strings.Contains(string(wire), `"demo":{"digest":"d1"}`) || !strings.Contains(string(wire), `"raw":{"module":"raw","version":"1"}`) {
+		t.Fatalf("on the wire: %s", wire)
+	}
+	back, err := Decode(wire)
+	if err != nil {
+		t.Fatal(err)
+	}
+	asked := 0
+	if err := Fill(&back, func(d string) ([]byte, error) {
+		asked++
+		if d != "d1" {
+			return nil, errors.New("no such digest")
+		}
+		return []byte(demo), nil
+	}); err != nil {
+		t.Fatal(err)
+	}
+	if asked != 2 || string(back.Cases[0].Manifests["demo"].Raw) != demo || string(back.Cases[0].Kept["laptop"]["demo"].Raw) != demo {
+		t.Fatalf("filled %d times: %+v", asked, back.Cases[0])
+	}
+	// The known packages: none is no list (not on the wire), an empty list is a list, and a list reads back whole.
+	for _, known := range [][]string{nil, {}, {"git.novox.be/novox/mesh-sdk", "@novox/mesh-sdk"}} {
+		wire, err := json.Marshal(Request{V: Version, Packages: known})
+		if err != nil {
+			t.Fatal(err)
+		}
+		back, err := Decode(wire)
+		if err != nil || (back.Packages == nil) != (known == nil) || strings.Join(back.Packages, ",") != strings.Join(known, ",") ||
+			known == nil && strings.Contains(string(wire), "packages") {
+			t.Errorf("the known packages %#v went as %s and read back %#v (%v)", known, wire, back.Packages, err)
+		}
+	}
+	bad := Request{V: Version, Cases: []Case{{Name: "c", Manifests: map[string]Manifest{"x": {Digest: "nope"}}}}}
+	if err := Fill(&bad, func(string) ([]byte, error) { return nil, errors.New("not there") }); err == nil || !strings.Contains(err.Error(), "nope") {
+		t.Fatalf("a digest the indexer does not hold: %v", err)
+	}
+}