Merge pull request 'The controller composes one tool runtime per node: its principal, the bundles, its process, and the gate (hq ADR 0175, to-be 38 WP2)' (#223) from feat/the-operators-machine into main

internal/catalogue/build.go

@@ -67,6 +67,31 @@ func (m Manifest) Resolve(built []Built) (Manifest, error) {
 	out := m
 	out.Build = nil
 	out.Resources = nil
+	// What the build compiled, kept on the resolved manifest (novox/hq ADR 0175): a tools bundle is
+	// named by no resource of the module's own — the node's runtime loads it — so this is the only
+	// place the mesh would otherwise not have it. In artifact order, so two resolutions of one
+	// build compare equal.
+	out.Bundles = nil
+	if m.Build != nil {
+		for _, a := range m.Build.Artifacts {
+			if a.Kind != ArtifactBundle {
+				continue
+			}
+			made := by[a.Name]
+			// What the runtime loads: what the artifact said, else every entrypoint of a module
+			// that declares tools, else nothing (the field's own rule; see Artifact.Loads).
+			loads := append([]string(nil), a.Loads...)
+			if a.Loads == nil && len(m.Tools) > 0 {
+				loads = append([]string(nil), a.Entrypoints...)
+			}
+			out.Bundles = append(out.Bundles, Bundle{
+				Name: a.Name, Source: made.Reference, Digest: made.Digest,
+				Language: a.Language, Entrypoints: append([]string(nil), a.Entrypoints...),
+				Loads: loads,
+			})
+		}
+		sort.Slice(out.Bundles, func(i, j int) bool { return out.Bundles[i].Name < out.Bundles[j].Name })
+	}
 	for _, r := range m.Resources {
 		named, _ := r["artifact"].(string)
 		if named == "" {
@@ -191,6 +216,20 @@ func (b *Build) problems(module string) []string {
 					"%s: %q is a bundle and says no language, so nothing can choose a compiler "+
 						"for it", module, a.Name))
 			}
+			// What the runtime loads is among what was compiled (ADR 0175): a name here that is
+			// not an entrypoint is a file the bundle does not contain, and the runtime would
+			// fail to import it on every machine rather than here.
+			for _, load := range a.Loads {
+				found := false
+				for _, e := range a.Entrypoints {
+					found = found || e == load
+				}
+				if !found {
+					problems = append(problems, fmt.Sprintf(
+						"%s: %q says the runtime loads %q, which is not among its entrypoints — "+
+							"what is loaded is compiled, so it is named there too", module, a.Name, load))
+				}
+			}
 			// **A system, for a language that compiles to a binary** (novox/hq ADR 0142). A binary
 			// is pinned to one operating system at link time so a host refuses to touch a machine
 			// it was not built for (novox/hq ADR 0005); an artifact that says nothing would be

internal/catalogue/declaration.go

@@ -512,6 +512,13 @@ func (r Resolution) compose(with Rendering, owner map[string]string,
 				"id": NeedID(name), "type": "file", "path": m.OwnSecrets[name].Path, "sealed": sealed,
 			}))
 		}
+		// This module's tools bundles, where the machine runs the node's tool runtime (novox/hq
+		// ADR 0175, to-be 38 WP2). Mesh-computed like everything above it, and before the module's
+		// own resources for the same reason: the runtime's process names the files inside these
+		// and is restarted when one changes, so they are on the machine before it is.
+		if r.runtimeHere() {
+			first = append(first, bundleArchives(m)...)
+		}
 		// Operator-owned paths this module is granted use of (novox/hq ADR 0051). Written before
 		// the module's own resources, and so before the container that mounts them: the host must
 		// find each present — refusing clearly if the operator has not provided it — before it
@@ -885,6 +892,17 @@ func (r Resolution) compose(with Rendering, owner map[string]string,
 			out = append(out, fact)
 		}
 	}
+	// The node's tool runtime, last (novox/hq ADR 0175, to-be 38 WP2.3): one process loading every
+	// bundle delivered above and holding the credential sealed above, so both exist before it starts
+	// — the order written here is the order the machine applies.
+	if r.runtimeHere() {
+		process, err := r.runtimeProcess(with)
+		if err != nil {
+			return nil, err
+		}
+		owner[fmt.Sprint(process["id"])] = RuntimeModule
+		out = append(out, process)
+	}
 	if with.Adopted {
 		// First, before anything a module declares: what the mesh needs reachable, then its guard.
 		// The order a machine applies is the order written here.

internal/catalogue/manifest.go

@@ -572,6 +572,36 @@ type Manifest struct {
 	// a module that could ask for it could read every credential on the bus — and the claim on
 	// `mesh-broker` is what authorises it, checked from this manifest alone.
 	BusUsers string `json:"bus-users,omitempty"`
+
+	// Bundles are this module's compiled bundles as the build produced them: what each is called,
+	// where it is, what it hashes to, what language it is in and which files a tool runtime loads
+	// from it (novox/hq ADR 0175, to-be 38).
+	//
+	// **Derived, never written.** The manifest in a repository says `build.artifacts`; the manifest
+	// the mesh holds says what came out, the way a resource naming an artifact comes to name a
+	// digest. Kept here because a tools bundle is referenced by no resource of the module's own —
+	// the node's runtime loads it, and the runtime is composed by the mesh — so without this the
+	// resolved manifest would carry no trace of the one artifact the runtime needs. A repository
+	// manifest that writes this beside a build is refused: it would be stating the build's output
+	// by hand.
+	Bundles []Bundle `json:"bundles,omitempty"`
+}
+
+// Bundle is one compiled bundle after it exists, as the resolved manifest carries it.
+type Bundle struct {
+	Name string `json:"name"`
+	// Source is where a machine fetches it, kept without the store's address like every reference
+	// the mesh records (artifacts.go); Digest is what it must hash to.
+	Source string `json:"source"`
+	Digest string `json:"digest"`
+	// Language is what it was compiled from, which is what says how it is run.
+	Language string `json:"language,omitempty"`
+	// Entrypoints are the compiled files it was built around, relative to its root.
+	Entrypoints []string `json:"entrypoints,omitempty"`
+	// Loads are the entrypoints a node's tool runtime imports from it: what the artifact said, or
+	// every entrypoint for a module declaring tools that said nothing. Empty for a bundle that is
+	// run rather than loaded.
+	Loads []string `json:"loads,omitempty"`
 }
 
 // Build says how to produce this module's artifacts from its source.
@@ -708,6 +738,16 @@ type Artifact struct {
 	// somebody adds a helper. An empty list is a bundle that is run rather than loaded — a
 	// provisioner or a step, named by whatever runs it.
 	Entrypoints []string `json:"entrypoints,omitempty"`
+
+	// Loads are the entrypoints of this bundle the node's tool runtime loads (novox/hq ADR 0175,
+	// to-be 38): the module's tool code, each file registering its tools as it is imported. A
+	// subset of Entrypoints, for a bundle that also carries things that are RUN — a daemon, a
+	// step, a report — and must not have them imported into the runtime.
+	//
+	// Absent means every entrypoint, for a module that declares `tools`: a bundle holding the
+	// module's tools and nothing else is the ordinary case and should not have to say the same
+	// list twice. A module declaring no tools has nothing the runtime loads, whatever it compiles.
+	Loads []string `json:"loads,omitempty"`
 }
 
 // Kinds an artifact may be.
@@ -1333,6 +1373,15 @@ func ParseManifest(raw []byte) (Manifest, error) {
 	//
 	// Refused here because the alternative is a build that never returns, on a mesh new enough
 	// that nobody is watching it yet.
+	if m.Build != nil && len(m.Bundles) > 0 {
+		// The output of a build, written beside the build that produces it (ADR 0175). A resource
+		// naming a digest beside an `artifact` would be the same mistake, and is caught the same way:
+		// what the mesh derives, a repository does not state.
+		problems = append(problems, fmt.Sprintf(
+			"%s writes `bundles` beside its build. The mesh derives that from what the build "+
+				"produced; a manifest states `build.artifacts` and nothing about what came out",
+			m.Module))
+	}
 	if m.Build != nil && len(m.Build.Artifacts) > 0 {
 		for _, o := range m.Offers() {
 			if o != ArtifactStoreProvision {

internal/catalogue/runtime.go

@@ -0,0 +1,251 @@
+package catalogue
+
+import (
+	"fmt"
+	"sort"
+	"strings"
+)
+
+// The node's tool runtime, as the catalogue knows it (novox/hq ADR 0175, to-be 38).
+//
+// **One module is the runtime.** Where it is assigned, one process per machine serves every assigned
+// module's tools and every held seat's verbs, on the host side, from the bundles each module's build
+// produced — and no module needs a container to reach the bus with its tools. The name is a constant
+// rather than a manifest field because a rule turns on it: the composer places the runtime's process
+// where this module is, and registration refuses the old pattern once this module exists.
+
+// RuntimeModule is the module that is the node's tool runtime. Mirrored in the broker package,
+// which composes a principal of its own for it; the agreement test there holds the two to one string.
+const RuntimeModule = "node-tools"
+
+// BundleRoot is where a machine keeps the tools bundles the mesh delivers to it: under the mesh's
+// own directory, beside the daemons the host unpacks there, and never where a package manager also
+// writes. One directory per module, one per bundle beneath it, at a path that does not move with
+// the version — so the runtime's process names each entrypoint once and is restarted, not
+// recomposed, when a bundle changes.
+const BundleRoot = "/var/lib/mesh/bundles"
+
+// BundleID names the archive resource that delivers one of a module's bundles; prefixed with the
+// module like every resource of its own.
+func BundleID(bundle string) string { return "bundle-" + bundle }
+
+// BundlePath is where one module's bundle is unpacked on a machine.
+func BundlePath(module, bundle string) string { return BundleRoot + "/" + module + "/" + bundle }
+
+// runtimeHere says whether this node's set includes the runtime module, which is what decides
+// whether anything about tools changes on the machine (to-be 38 WP2): until the runtime is assigned,
+// a node is sent exactly what it was sent before, bundles included, because a bundle nothing loads
+// is bytes nobody reads.
+func (r Resolution) runtimeHere() bool {
+	for _, m := range r.Modules {
+		if m.Module == RuntimeModule {
+			return true
+		}
+	}
+	return false
+}
+
+// bundleArchives is one archive per tools bundle of a module — a bundle the runtime LOADS something
+// from — as the host fetches and unpacks any artifact (novox/hq ADR 0175 §3: a module brings its
+// tools as a bundle, delivered by the host like any artifact, never an image). A bundle it loads
+// nothing from is run rather than loaded: a daemon, a step, the runtime itself — delivered by the
+// process that runs it, and not again here.
+//
+// The source is the kept reference; the per-resource pass that follows routes it through the
+// artifact store as this network reaches it now, as it does every image and archive the mesh built.
+func bundleArchives(m Manifest) []map[string]any {
+	var out []map[string]any
+	for _, b := range m.Bundles {
+		if len(b.Loads) == 0 {
+			continue
+		}
+		out = append(out, map[string]any{
+			"id": BundleID(b.Name), "type": "archive",
+			"source": b.Source, "digest": b.Digest,
+			"path": BundlePath(m.Module, b.Name),
+		})
+	}
+	return out
+}
+
+// RuntimeProcessID names the one process the mesh composes for a machine's runtime; prefixed with
+// the runtime module like a resource of its own, because that module is what the host sees it as.
+func RuntimeProcessID() string { return "runtime" }
+
+// RuntimeToolModules is the variable the runtime reads the modules it serves from: one
+// `<module>=<entrypoint>` per file it loads, comma-separated — several entries may name one module.
+// RuntimeBrokerFile is where it reads the node's credential; RuntimeOperatorAccount and
+// RuntimeOperatorHome are the machine's operator account and home, handed to every tool's
+// environment (to-be 38 WP1), and absent on a machine with no account.
+const (
+	RuntimeToolModules     = "MESH_TOOL_MODULES"
+	RuntimeBrokerFile      = "MESH_BROKER_FILE"
+	RuntimeOperatorAccount = "MESH_OPERATOR_ACCOUNT"
+	RuntimeOperatorHome    = "MESH_OPERATOR_HOME"
+)
+
+// interpreterFor is how a bundle in a language is run: the program the host's unit starts, with the
+// bundle's entrypoint after it. The one thing the composer takes from a language, and said here
+// rather than in a manifest because the runtime's process is the mesh's to compose (to-be 38 WP3).
+func interpreterFor(language string) (string, error) {
+	switch language {
+	case "typescript":
+		return "node", nil
+	}
+	return "", fmt.Errorf(
+		"%s is written in %q, and the mesh knows no interpreter to run a %q bundle with",
+		RuntimeModule, language, language)
+}
+
+// runtimeProcess is the one process a machine runs the node's tool runtime as (novox/hq ADR 0175,
+// to-be 38 WP2.3): the runtime module's own bundle, run by its language's interpreter, told which
+// modules it serves and from which files, where its credential is, and who the machine's operator
+// is — and restarted when any bundle it loads or the credential it holds changes.
+//
+// Composed from the placed manifests, so the credential's path is where this node puts it. The
+// runtime runs as the operator's account when the machine has one, which is what lets a tool that
+// needs root escalate as the operator would (ADR 0175 §4); on a machine with no account it runs as
+// root, and the two operator words are not set.
+func (r Resolution) runtimeProcess(with Rendering) (map[string]any, error) {
+	var runtime *Manifest
+	for i := range r.Modules {
+		if r.Modules[i].Module == RuntimeModule {
+			runtime = &r.Modules[i]
+		}
+	}
+	if runtime == nil {
+		return nil, nil
+	}
+	if len(runtime.Bundles) != 1 {
+		return nil, fmt.Errorf(
+			"%s is assigned to %s and its build produced %d bundle(s); the runtime is one bundle "+
+				"the mesh runs, so the module declares exactly one (novox/hq to-be 38)",
+			RuntimeModule, r.Node, len(runtime.Bundles))
+	}
+	bundle := runtime.Bundles[0]
+	if len(bundle.Entrypoints) != 1 {
+		return nil, fmt.Errorf(
+			"%s's bundle %q names %d entrypoint(s); the runtime is run from one, so the module "+
+				"declares exactly one (novox/hq to-be 38)", RuntimeModule, bundle.Name, len(bundle.Entrypoints))
+	}
+	interpreter, err := interpreterFor(bundle.Language)
+	if err != nil {
+		return nil, err
+	}
+	credential, declared := runtime.OwnSecrets["broker"]
+	if !declared {
+		return nil, fmt.Errorf(
+			"%s declares no own secret named broker, and the node's credential is delivered there: "+
+				"a module that speaks on the bus declares \"own-secrets\": {\"broker\": <path>}",
+			RuntimeModule)
+	}
+
+	// What it serves, and from which files: every module on this machine that composes here, in
+	// name order, each bundle it loads from in the order the manifest gave. A module left out of
+	// the declaration — a filter on an adopted machine — is left out of this too, or the runtime
+	// would be told to load files that were never delivered.
+	var served []string
+	var restartOn []string
+	for _, m := range r.Modules {
+		if with.Adopted && m.Filtering != nil {
+			continue
+		}
+		for _, b := range m.Bundles {
+			if len(b.Loads) == 0 {
+				continue
+			}
+			for _, load := range b.Loads {
+				served = append(served, m.Module+"="+BundlePath(m.Module, b.Name)+"/"+load)
+			}
+			restartOn = append(restartOn, m.Module+"."+BundleID(b.Name))
+		}
+	}
+	sort.Strings(served)
+	restartOn = append(restartOn, RuntimeModule+"."+NeedID("broker"))
+	sort.Strings(restartOn)
+
+	env := map[string]string{
+		RuntimeToolModules: strings.Join(served, ","),
+		RuntimeBrokerFile:  credential.Path,
+	}
+	process := map[string]any{
+		"id": RuntimeModule + "." + RuntimeProcessID(), "type": "process", "name": RuntimeModule,
+		"source": bundle.Source, "digest": bundle.Digest,
+		"run":        []any{interpreter, bundle.Entrypoints[0]},
+		"env":        env,
+		"restart-on": toAny(restartOn),
+	}
+	if r.Account != "" {
+		env[RuntimeOperatorAccount] = r.Account
+		env[RuntimeOperatorHome] = accountHomeOf(r.Account, r.AccountHome)
+		process["user"] = r.Account
+	}
+	// Routed through the artifact store as this network reaches it now, like everything the mesh
+	// built; refused with the same words when there is no store to route through.
+	if err := artifactsInto(process, RuntimeModule, with); err != nil {
+		return nil, err
+	}
+	return process, nil
+}
+
+func toAny(in []string) []any {
+	out := make([]any, 0, len(in))
+	for _, s := range in {
+		out = append(out, s)
+	}
+	return out
+}
+
+// RuntimeImageModule and RuntimeImageArtifact name the image every per-module tool container was
+// built on: the tool runtime's own runtime image. With the runtime a module of its own, that image
+// stays the way a module's SERVICE may be built and stops being the way tools reach a node (ADR 0175).
+const (
+	RuntimeImageModule   = "mesh-tools"
+	RuntimeImageArtifact = "runtime"
+)
+
+// ToolContainerOnTheRuntime says why a manifest is the pattern ADR 0175 retires — a module whose tools
+// are served from a container built on the tool runtime's image — or nothing when it is not. Judged
+// from the manifest's own `build.on` when it is a repository manifest, and from what its build stood
+// on when it is a built one, because a resolved manifest carries no build. The gate itself is
+// registration's (to-be 38 WP2.4): once the runtime module is in the catalogue, this is refused.
+//
+// Three things must hold, and each alone is fine: declaring tools (a bundle does that); a container
+// (a module's service may well be one); building on the runtime's image (a service written against
+// the SDK may). All three is a container whose purpose is tools, which the runtime now serves.
+func ToolContainerOnTheRuntime(m Manifest, against []string) string {
+	if len(m.Tools) == 0 {
+		return ""
+	}
+	container := false
+	for _, r := range m.Resources {
+		if fmt.Sprint(r["type"]) == "container" {
+			container = true
+		}
+	}
+	if !container {
+		return ""
+	}
+	onTheRuntime := false
+	if m.Build != nil {
+		for _, on := range m.Build.On {
+			if on.Module == RuntimeImageModule && on.Artifact == RuntimeImageArtifact {
+				onTheRuntime = true
+			}
+		}
+	}
+	for _, ref := range against {
+		path, kept := InArtifactStore(Recorded(ref))
+		if kept && strings.HasPrefix(path, RuntimeImageModule+"/"+RuntimeImageArtifact+"@") {
+			onTheRuntime = true
+		}
+	}
+	if !onTheRuntime {
+		return ""
+	}
+	return fmt.Sprintf(
+		"%s declares tools and a container built on %s's %s image — a container whose purpose is "+
+			"serving tools. The node's tool runtime (%s) serves every module's tools from its bundle "+
+			"now (novox/hq ADR 0175, to-be 38); declare the tools as a bundle and drop the container",
+		m.Module, RuntimeImageModule, RuntimeImageArtifact, RuntimeModule)
+}

internal/catalogue/runtime_gate_test.go

@@ -0,0 +1,88 @@
+package catalogue
+
+import (
+	"strings"
+	"testing"
+)
+
+// The packet-filter manifest as it was the day the runtime was decided (novox/hq ADR 0175): tools,
+// served from a container built on the tool runtime's image, with NET_ADMIN so the container could
+// reach the filter. The exact pattern to-be 38 WP4 moves it off, and the one the gate refuses.
+const thePacketFilterAsItWas = `{
+  "module": "nftables",
+  "version": "1",
+  "capabilities": ["firewall", "container-runtime"],
+  "claims": [{"name": "node-packet-filter", "scope": "node", "serves": ["rules", "reload", "remove"]}],
+  "filtering": {"into": "/etc/nftables.conf"},
+  "resources": [
+    {"id": "mesh-state", "type": "directory", "mode": "0700", "place": "mesh"},
+    {"id": "package", "type": "package", "package": "nftables"},
+    {"id": "unit", "type": "file", "path": "/etc/systemd/system/mesh-filter.service",
+     "content": "[Unit]\nDescription=The mesh's packet filter\n[Service]\nType=oneshot\nExecStart=nft -f /etc/nftables.conf\n", "mode": "0644"},
+    {"id": "load", "type": "service", "unit": "mesh-filter.service", "state": "running", "boot": "enabled",
+     "restart-on": ["unit"], "reload-on": ["filtering"]},
+    {"id": "runtime", "type": "container", "name": "mesh-nftables", "network": "host",
+     "capabilities": ["NET_ADMIN"],
+     "volumes": ["${dir:mesh-state}/broker:/run/secrets/broker:ro", "/etc/nftables.conf:/etc/nftables.conf:ro"],
+     "env": {"MESH_BROKER_FILE": "/run/secrets/broker", "MESH_FILTER_FILE": "/etc/nftables.conf"},
+     "artifact": "runtime"}
+  ],
+  "tools": ["firewall_rules"],
+  "own-secrets": {"broker": "${dir:mesh-state}/broker"},
+  "build": {
+    "on": [
+      {"arg": "BUILD_BASE", "module": "mesh-tools", "artifact": "build"},
+      {"arg": "RUNTIME_BASE", "module": "mesh-tools", "artifact": "runtime"}
+    ],
+    "artifacts": [{"name": "runtime", "kind": "image", "from": "Dockerfile"}]
+  }
+}`
+
+func TestAToolContainerOnTheRuntimeImageIsNamedForWhatItIs(t *testing.T) {
+	m, err := ParseManifest([]byte(thePacketFilterAsItWas))
+	if err != nil {
+		t.Fatal(err)
+	}
+	// From the repository: the manifest says what it builds on.
+	why := ToolContainerOnTheRuntime(m, nil)
+	if why == "" {
+		t.Fatal("the packet filter's tool container was not recognised from its build")
+	}
+	for _, word := range []string{"nftables", "mesh-tools", "runtime", "ADR 0175", "bundle"} {
+		if !strings.Contains(why, word) {
+			t.Errorf("the refusal does not say %q: %s", word, why)
+		}
+	}
+
+	// Built: the manifest carries no build, and what it stood on says the same.
+	built, err := m.Resolve([]Built{{Name: "runtime", Kind: ArtifactImage,
+		Reference: ArtifactStoreScheme + "nftables/runtime@" + digest}})
+	if err != nil {
+		t.Fatal(err)
+	}
+	stoodOn := []string{"anchor.internal:5100/mesh-tools/build@" + digest, "anchor.internal:5100/mesh-tools/runtime@" + digest}
+	if ToolContainerOnTheRuntime(built, stoodOn) == "" {
+		t.Error("the packet filter's tool container was not recognised from what its build stood on")
+	}
+	if ToolContainerOnTheRuntime(built, nil) != "" {
+		t.Error("a built manifest with no record of its base was judged to be on the runtime")
+	}
+
+	// Each of the three alone is an ordinary module.
+	bundle := m
+	bundle.Resources = m.Resources[:len(m.Resources)-1]
+	if ToolContainerOnTheRuntime(bundle, nil) != "" {
+		t.Error("a module with tools and no container is the pattern the runtime serves, and was refused")
+	}
+	service := m
+	service.Tools = nil
+	if ToolContainerOnTheRuntime(service, nil) != "" {
+		t.Error("a service built against the SDK, declaring no tools, was refused")
+	}
+	elsewhere := m
+	elsewhere.Build = &Build{On: []BuildsOn{{Arg: "NODE_BASE", Image: "node@" + digest}},
+		Artifacts: m.Build.Artifacts}
+	if ToolContainerOnTheRuntime(elsewhere, nil) != "" {
+		t.Error("a tool container on a public base was refused as though it were on the runtime's")
+	}
+}

internal/catalogue/runtime_test.go

@@ -0,0 +1,204 @@
+package catalogue
+
+import (
+	"fmt"
+	"strings"
+	"testing"
+)
+
+// The node's tool runtime (novox/hq ADR 0175, to-be 38): where the runtime module is assigned, a
+// machine is sent every assigned module's tools bundle as an archive, and the runtime's own process
+// loading them. Where it is not, the machine is sent exactly what it was sent before.
+
+var bundleDigest = "sha256:" + strings.Repeat("b", 64)
+
+// aToolsModule is a module whose tools come as a compiled bundle and nothing else — the shape every
+// module takes once its tool container goes (to-be 38 WP4).
+func aToolsModule(t *testing.T, name string, entrypoints ...string) Manifest {
+	t.Helper()
+	m := Manifest{Module: name, Version: "1", Tools: []string{"status"},
+		Build: &Build{Artifacts: []Artifact{
+			{Name: "tools", Kind: ArtifactBundle, Language: "typescript", Entrypoints: entrypoints},
+		}}}
+	resolved, err := m.Resolve([]Built{{Name: "tools", Kind: ArtifactBundle,
+		Reference: ArtifactStoreScheme + name + "/tools/blobs/" + bundleDigest, Digest: bundleDigest}})
+	if err != nil {
+		t.Fatal(err)
+	}
+	return resolved
+}
+
+// theRuntime is the runtime module as the catalogue holds it: its own bundle, run rather than
+// loaded, and its broker secret to receive the node's credential in.
+func theRuntime(t *testing.T) Manifest {
+	t.Helper()
+	m := Manifest{Module: RuntimeModule, Version: "1",
+		OwnSecrets: OwnSecrets{"broker": {Path: "/var/lib/mesh/" + RuntimeModule + "/broker"}},
+		Build: &Build{Artifacts: []Artifact{{Name: "runtime", Kind: ArtifactBundle, Language: "typescript",
+			Entrypoints: []string{"src/main.js"}}}}}
+	resolved, err := m.Resolve([]Built{{Name: "runtime", Kind: ArtifactBundle,
+		Reference: ArtifactStoreScheme + RuntimeModule + "/runtime/blobs/" + bundleDigest, Digest: bundleDigest}})
+	if err != nil {
+		t.Fatal(err)
+	}
+	return resolved
+}
+
+func TestABuildsBundlesAreCarriedOnTheResolvedManifest(t *testing.T) {
+	m := aToolsModule(t, "nftables", "tools/index.js")
+	if len(m.Bundles) != 1 {
+		t.Fatalf("the resolved manifest carries %d bundle(s), not the one the build made", len(m.Bundles))
+	}
+	b := m.Bundles[0]
+	if b.Name != "tools" || b.Digest != bundleDigest || b.Language != "typescript" ||
+		b.Source != ArtifactStoreScheme+"nftables/tools/blobs/"+bundleDigest ||
+		len(b.Entrypoints) != 1 || b.Entrypoints[0] != "tools/index.js" {
+		t.Errorf("the bundle is carried as %+v", b)
+	}
+	// A repository manifest may not write what the build derives.
+	raw := `{"module":"x","version":"1","build":{"artifacts":[{"name":"t","kind":"bundle","language":"typescript"}]},` +
+		`"bundles":[{"name":"t","source":"s","digest":"` + bundleDigest + `"}]}`
+	if _, err := ParseManifest([]byte(raw)); err == nil || !strings.Contains(err.Error(), "bundles") {
+		t.Errorf("a manifest stating its build's output by hand was accepted: %v", err)
+	}
+}
+
+func TestEveryToolsBundleIsDeliveredWhereTheRuntimeRuns(t *testing.T) {
+	store := Rendering{ArtifactStore: "anchor.internal:5101",
+		Needed: map[string]map[string]string{RuntimeModule: {"broker": "sealed-credential"}}}
+	nftables := aToolsModule(t, "nftables", "tools/index.js")
+	zsh := aToolsModule(t, "zsh", "tools/index.js", "tools/more.js")
+
+	t.Run("with the runtime, one archive per tools bundle", func(t *testing.T) {
+		r := Resolution{Node: "anchor", Modules: []Manifest{nftables, zsh, theRuntime(t)}}
+		out, err := r.Declaration(store)
+		if err != nil {
+			t.Fatal(err)
+		}
+		archive := fileNamed(out, "nftables."+BundleID("tools"))
+		if archive == nil {
+			t.Fatalf("nftables' tools bundle was not delivered: %v", ids(out))
+		}
+		if archive["type"] != "archive" || archive["digest"] != bundleDigest ||
+			archive["path"] != BundleRoot+"/nftables/tools" {
+			t.Errorf("delivered as %v", archive)
+		}
+		if archive["source"] != "http://anchor.internal:5101/v2/nftables/tools/blobs/"+bundleDigest {
+			t.Errorf("fetched from %v, not through the store as this network reaches it", archive["source"])
+		}
+		if fileNamed(out, "zsh."+BundleID("tools")) == nil {
+			t.Errorf("zsh's tools bundle was not delivered: %v", ids(out))
+		}
+		// The runtime's own bundle is run, not loaded: its process delivers it, not an archive.
+		if fileNamed(out, RuntimeModule+"."+BundleID("runtime")) != nil {
+			t.Error("the runtime's own bundle was delivered as an archive beside its process")
+		}
+	})
+
+	t.Run("without the runtime, nothing changes", func(t *testing.T) {
+		r := Resolution{Node: "anchor", Modules: []Manifest{nftables, zsh}}
+		out, err := r.Declaration(store)
+		if err != nil {
+			t.Fatal(err)
+		}
+		for _, id := range ids(out) {
+			if strings.Contains(id, BundleID("")) {
+				t.Errorf("%s was delivered to a machine running no runtime to load it", id)
+			}
+		}
+	})
+}
+
+func ids(out []map[string]any) []string {
+	var names []string
+	for _, r := range out {
+		names = append(names, r["id"].(string))
+	}
+	return names
+}
+
+// One process per machine runs the runtime from its own bundle, told what it serves and from where,
+// where its credential is, and who the operator is — restarted when any of that changes.
+func TestTheMachineRunsOneRuntimeLoadingEveryDeliveredBundle(t *testing.T) {
+	with := Rendering{ArtifactStore: "anchor.internal:5101",
+		Needed: map[string]map[string]string{RuntimeModule: {"broker": "sealed-credential"}}}
+	nftables := aToolsModule(t, "nftables", "tools/index.js")
+	// A bundle carrying a daemon beside its tools says which files the runtime loads.
+	showcase := Manifest{Module: "showcase", Version: "1", Tools: []string{"greet"},
+		Build: &Build{Artifacts: []Artifact{{Name: "code", Kind: ArtifactBundle, Language: "typescript",
+			Entrypoints: []string{"daemon/index.js", "tools/index.js"}, Loads: []string{"tools/index.js"}}}}}
+	showcase, err := showcase.Resolve([]Built{{Name: "code", Kind: ArtifactBundle,
+		Reference: ArtifactStoreScheme + "showcase/code/blobs/" + bundleDigest, Digest: bundleDigest}})
+	if err != nil {
+		t.Fatal(err)
+	}
+
+	r := Resolution{Node: "anchor", Account: "ops", Modules: []Manifest{nftables, showcase, theRuntime(t)}}
+	out, err := r.Declaration(with)
+	if err != nil {
+		t.Fatal(err)
+	}
+	process := fileNamed(out, RuntimeModule+"."+RuntimeProcessID())
+	if process == nil {
+		t.Fatalf("no runtime process was composed: %v", ids(out))
+	}
+	if process["type"] != "process" || process["name"] != RuntimeModule || process["digest"] != bundleDigest ||
+		process["source"] != "http://anchor.internal:5101/v2/"+RuntimeModule+"/runtime/blobs/"+bundleDigest {
+		t.Errorf("the runtime's process is %v", process)
+	}
+	if fmt.Sprint(process["run"]) != "[node src/main.js]" {
+		t.Errorf("the runtime is run as %v; its bundle's one entrypoint, by its language's interpreter", process["run"])
+	}
+	env := process["env"].(map[string]string)
+	if env[RuntimeToolModules] != "nftables="+BundleRoot+"/nftables/tools/tools/index.js,"+
+		"showcase="+BundleRoot+"/showcase/code/tools/index.js" {
+		t.Errorf("the runtime is told to serve %q: every loaded file, by module, and nothing a bundle runs", env[RuntimeToolModules])
+	}
+	if env[RuntimeBrokerFile] != "/var/lib/mesh/"+RuntimeModule+"/broker" {
+		t.Errorf("the runtime reads its credential at %q, not where the module's own secret is placed", env[RuntimeBrokerFile])
+	}
+	if env[RuntimeOperatorAccount] != "ops" || env[RuntimeOperatorHome] != "/home/ops" || process["user"] != "ops" {
+		t.Errorf("the operator is not handed to the runtime: %v as %v", env, process["user"])
+	}
+	restarts := fmt.Sprint(process["restart-on"])
+	for _, want := range []string{"nftables." + BundleID("tools"), "showcase." + BundleID("code"), RuntimeModule + "." + NeedID("broker")} {
+		if !strings.Contains(restarts, want) {
+			t.Errorf("the runtime is not restarted when %s changes: %s", want, restarts)
+		}
+	}
+	// After every bundle and the credential, so both exist before it starts.
+	names := ids(out)
+	if names[len(names)-1] != RuntimeModule+"."+RuntimeProcessID() {
+		t.Errorf("the runtime's process is not last: %v", names)
+	}
+
+	t.Run("a machine with no account runs it as root without the operator words", func(t *testing.T) {
+		out, err := Resolution{Node: "anchor", Modules: []Manifest{nftables, theRuntime(t)}}.Declaration(with)
+		if err != nil {
+			t.Fatal(err)
+		}
+		process := fileNamed(out, RuntimeModule+"."+RuntimeProcessID())
+		env := process["env"].(map[string]string)
+		if _, set := env[RuntimeOperatorAccount]; set {
+			t.Error("an operator account was named on a machine that has none")
+		}
+		if _, set := process["user"]; set {
+			t.Error("a user was set on a machine with no account")
+		}
+	})
+
+	t.Run("a runtime module built wrong is refused by name", func(t *testing.T) {
+		two := Manifest{Module: RuntimeModule, Version: "1", OwnSecrets: OwnSecrets{"broker": {Path: "/b"}},
+			Build: &Build{Artifacts: []Artifact{{Name: "runtime", Kind: ArtifactBundle, Language: "typescript",
+				Entrypoints: []string{"a.js", "b.js"}}}}}
+		resolved, err := two.Resolve([]Built{{Name: "runtime", Kind: ArtifactBundle,
+			Reference: ArtifactStoreScheme + "x/runtime/blobs/" + bundleDigest, Digest: bundleDigest}})
+		if err != nil {
+			t.Fatal(err)
+		}
+		_, err = Resolution{Node: "anchor", Modules: []Manifest{resolved}}.Declaration(with)
+		if err == nil || !strings.Contains(err.Error(), "entrypoint") {
+			t.Errorf("a runtime bundle with two entrypoints was composed: %v", err)
+		}
+	})
+}