A version prepares its state before it runs

The mesh derives the preparation from the module's own resource instead of each module hand-writing
a step beside it (novox/hq ADR 0135). A manifest says one word — `prepares` — and the mesh runs that
module's own program in its preparation mode, in the module's own context: the same image, the same
environment, the same mounts, because it is the same code. A published port and a fixed address are
taken away rather than copied, since the version being replaced still holds them.

One word for every kind of module: a Go binary receives `prepare` as its argument, a bundle receives
it through the runtime whose entry takes the same word. The control plane answers it like anything
else — its own schema stops being a special case, and its hand-written step is gone.

internal/catalogue/declaration.go

@@ -623,6 +623,9 @@ func (r Resolution) compose(with Rendering, owner map[string]string) ([]map[stri
 		// one of them as its environment without saying so (ADR 0086, issue 041).
 		secretFiles := secretFilesOf(resources)
 
+		// Which of this module's resources its preparation runs before, if it prepares anything.
+		prepareBefore := preparationTarget(m)
+
 		for _, unsettled := range resources {
 			resource, err := ApplySettings(unsettled, with.Settings[m.Module])
 			if err != nil {
@@ -708,6 +711,18 @@ func (r Resolution) compose(with Rendering, owner map[string]string) ([]map[stri
 			if renamed := reflectsRenamed(m.Module, resource["reload-on"]); renamed != nil {
 				copied["reload-on"] = renamed
 			}
+			// **A version prepares its state before it runs** (novox/hq ADR 0135). Derived from the
+			// module's own resource rather than declared beside it: what prepares the state is the
+			// module's own code, so what it is given has to be what that code is given — and a
+			// second resource written by hand is a second copy to drift from the first. Placed
+			// immediately before it, because a run-once step stops everything the declaration
+			// places after it (ADR 0052), which is how a version whose preparation failed does not
+			// serve.
+			if prepareBefore != "" && fmt.Sprint(resource["id"]) == prepareBefore {
+				step := prepared(copied)
+				owner[fmt.Sprint(step["id"])] = m.Module
+				out = append(out, step)
+			}
 			owner[fmt.Sprint(copied["id"])] = m.Module
 			out = append(out, copied)
 		}
@@ -1610,3 +1625,73 @@ func atMachinePort(serves map[string]any, module string, ports map[string]map[in
 func AtPublishedPort(values map[string]any, module string, published map[int]int) map[string]any {
 	return atMachinePort(values, module, map[string]map[int]int{module: published})
 }
+
+// PreparationArgument is how the mesh asks a module to prepare its state: one word, to the module's
+// own program, whatever that program is (novox/hq ADR 0135).
+//
+// **One word for every kind of module.** A module built as a Go binary receives it as its argument;
+// one built as a bundle receives it through the runtime, whose entry takes the same word. So the
+// mesh has one way of asking and a module has one way of answering, and neither learns the other's
+// shape.
+const PreparationArgument = "prepare"
+
+// preparationTarget is the resource a module's preparation runs before: its own workload.
+//
+// The first container carrying an artifact this module built, and not itself a step — that is the
+// thing that runs the module's code, and therefore the thing whose state must be ready. Empty when
+// the module prepares nothing, or when nothing it declares could run its code.
+//
+// **A module with two own workloads gates the first of them.** Five modules in the catalogue declare
+// more than one container of their own, none of them preparing anything today. If one ever does and
+// its second workload shares the state, the gate is in front of the first — stated here because the
+// alternative is a field asking an author to restate what the mesh can see.
+func preparationTarget(m Manifest) string {
+	if !m.Prepares {
+		return ""
+	}
+	for _, r := range m.Resources {
+		if fmt.Sprint(r["type"]) != "container" || !ownArtifact(r, m.Module) {
+			continue
+		}
+		if once, _ := r["run-once"].(bool); once {
+			continue
+		}
+		return fmt.Sprint(r["id"])
+	}
+	return ""
+}
+
+// ownArtifact is whether a resource runs something this module built, in either spelling a manifest
+// may be in: naming the artifact, before a build resolved it, or carrying the reference a build
+// recorded — this mesh's own store, under this module's name.
+func ownArtifact(resource map[string]any, module string) bool {
+	if named, _ := resource["artifact"].(string); named != "" {
+		return true
+	}
+	image, _ := resource["image"].(string)
+	return strings.HasPrefix(image, ArtifactStoreScheme+module+"/")
+}
+
+// prepared is the module's own resource as the step that prepares its state: the same image, the same
+// context, run to completion with the mesh's preparation argument.
+//
+// Three things are taken away rather than copied, each because the step runs while the version it
+// prepares for is still running. A published port cannot be bound twice, and a step that tried would
+// fail for a reason that has nothing to do with the state. A fixed address cannot be held twice, for
+// the same reason. And a cadence is what a step is the opposite of: a container runs once and gates,
+// or on a schedule, or stays up, never two (ADR 0053).
+func prepared(from map[string]any) map[string]any {
+	step := map[string]any{}
+	for k, v := range from {
+		step[k] = v
+	}
+	step["id"] = fmt.Sprint(from["id"]) + ".prepare"
+	step["name"] = fmt.Sprint(from["name"]) + "-prepare"
+	step["run-once"] = true
+	step["args"] = []any{PreparationArgument}
+	delete(step, "ports")
+	delete(step, "ip")
+	delete(step, "schedule")
+	delete(step, "reload-on")
+	return step
+}