apply: a run-once container is a step the host runs to completion (ADR 0052)

A module can declare state but not a step that runs at first boot. This adds
`run-once: true` to the container shape: the host runs it in the foreground,
requires it to exit 0, and records that it did — as the digest of the
declaration, so a re-apply does not re-run it unless the declaration changed.

Because the declaration is applied in order and a failed run-once step gates the
apply the way a failed action does, whatever is declared after the step starts
only once it has completed. That is how "before the broker starts" is enforced,
with no dependency graph the host must resolve (ADR 0005): the step is declared
first, and the container that needs it is never reached until it is done.

No new host shape and no arbitrary host command — a run-once container is
strictly less powerful than an action. Validation refuses run-once with
restart-on (contradictory lifecycles). Six unit tests; go test ./... green.

Claude-Session: https://claude.ai/code/session_01LrgweAeERJYBg88c5cKDzF

internal/apply/apply.go

@@ -189,7 +189,16 @@ func Apply(
 			// to do with a file on the other side of the declaration, and stopping there is what
 			// made one broken module hold a whole machine hostage
 			// (novox/hq 04-ISSUES/011).
-			if resource.Kind() == declaration.TypeAction {
+			// A run-once container is a step with the same purpose as an action: to make
+			// something true *before* the next thing needs it (novox/hq ADR 0052). A broker whose
+			// dynsec store was not seeded must not be started, so a run-once step that did not
+			// complete gates what follows exactly as a failed action does — that is the whole of
+			// how "before that container starts" is enforced, since the step is declared before it.
+			gates := resource.Kind() == declaration.TypeAction
+			if c, ok := resource.(*declaration.Container); ok && c.RunOnce {
+				gates = true
+			}
+			if gates {
 				failed.Done = report
 				failed.Others = len(failures) - 1
 				failed.Gated = true
@@ -241,7 +250,7 @@ func applyOne(ctx context.Context, sys system.System, r declaration.Resource, ru
 	case *declaration.Package:
 		return applyPackage(ctx, sys, res, run)
 	case *declaration.Container:
-		return applyContainer(ctx, res, run, changed)
+		return applyContainer(ctx, res, run, changed, previous)
 	case *declaration.User:
 		return applyUser(ctx, sys, res, run)
 	case *declaration.Archive:
@@ -929,7 +938,7 @@ func applyNetwork(ctx context.Context, r *declaration.Network, run Runner) (Outc
 	return out, nil
 }
 
-func applyContainer(ctx context.Context, r *declaration.Container, run Runner, changed map[string]bool) (Outcome, error) {
+func applyContainer(ctx context.Context, r *declaration.Container, run Runner, changed map[string]bool, previous store.Applied) (Outcome, error) {
 	out := begin(r)
 	want := containerSpec(r)
 
@@ -938,6 +947,10 @@ func applyContainer(ctx context.Context, r *declaration.Container, run Runner, c
 		return out, fmt.Errorf("%w, so nothing can be said about %q", err, r.Name)
 	}
 
+	if r.RunOnce {
+		return applyRunOnce(ctx, r, run, cri, want, previous)
+	}
+
 	before, err := containerState(ctx, r.Name, run)
 	existed := err == nil
 
@@ -1019,6 +1032,79 @@ func applyContainer(ctx context.Context, r *declaration.Container, run Runner, c
 	return out, nil
 }
 
+// applyRunOnce runs a container to completion, once, and requires it to exit 0 (novox/hq ADR 0052).
+//
+// It is a step, not a service: the module's own code seeding a store, migrating a schema or
+// gating on health, under the module's own account (ADR 0047), before the container that depends
+// on it. Three things make it a step rather than an ordinary container:
+//
+//   - It is run in the foreground, so the runtime returns the container's exit code. A non-zero
+//     exit is an error here, and — because a run-once step gates the apply the way a failed action
+//     does — that error stops everything the declaration places after it. That is how "before the
+//     broker starts" is enforced: the step is declared first, and the broker is never reached
+//     until it has completed.
+//   - Its record of having happened is the digest of its declaration, recorded by the caller only
+//     after it exits 0 (ADR 0018). The step leaves nothing running to inspect, so the persisted
+//     digest — not a live container — is the marker. A re-apply whose declaration digest already
+//     matches does nothing; a changed declaration re-runs it.
+//   - It writes a seed only if it is absent and never reconciles it, so what a running program
+//     grows in that seed afterward is never wiped (04-ISSUES/035). The host's marker keeps the
+//     step from re-running; the step's own code keeps it from clobbering on the pass it does run.
+func applyRunOnce(ctx context.Context, r *declaration.Container, run Runner, cri, want string, previous store.Applied) (Outcome, error) {
+	out := begin(r)
+
+	// Already completed for this exact declaration. The marker is the store, because a run-once
+	// step leaves nothing running to ask.
+	if previous.Wrote != "" && previous.Wrote == want {
+		out.Action = "unchanged"
+		out.Detail = "run-once step already completed for this declaration"
+		out.wrote = want
+		return out, nil
+	}
+
+	// A container by this name from a previous, different declaration must not linger and be
+	// mistaken for this run. Removing a name that is not there is the state we want, so its error
+	// is ignored.
+	_, _ = run(ctx, cri, "rm", "-f", r.Name)
+
+	// Run in the foreground so the runtime waits for the container and hands back its exit code.
+	// No --detach and no --restart: a step that is restarted is not a step.
+	args := []string{"run", "--name", r.Name}
+	for _, file := range r.EnvFile {
+		args = append(args, "--env-file", file)
+	}
+	if r.Network != "" {
+		args = append(args, "--network", r.Network)
+	}
+	args = append(args, "--label", specLabel+"="+want, "--label", idLabel+"="+r.ID)
+	for _, k := range sortedKeys(r.Env) {
+		args = append(args, "--env", k+"="+r.Env[k])
+	}
+	for _, v := range r.Volumes {
+		args = append(args, "--volume", v)
+	}
+	for _, h := range r.Hosts {
+		args = append(args, "--add-host", h)
+	}
+	args = append(args, r.Image)
+	args = append(args, r.Args...)
+
+	if _, err := run(ctx, cri, args...); err != nil {
+		// A non-zero exit or a runtime that could not start it. Either way the step did not make
+		// the machine ready, so the apply must not go on to the container that needs it.
+		return out, fmt.Errorf("run-once step %s did not complete: %w", r.Name, err)
+	}
+
+	// It completed. Remove the exited container so a later apply is not confused by a stopped one;
+	// the record that it ran is the digest below, which the caller persists after the fact.
+	_, _ = run(ctx, cri, "rm", "-f", r.Name)
+
+	out.Action = "created"
+	out.Detail = "run-once step completed"
+	out.wrote = want
+	return out, nil
+}
+
 // restartedBy is which of the named resources changed this pass — the reason a container or service
 // must be brought back rather than left as it is (novox/hq 04-ISSUES/009).
 func restartedBy(restartOn []string, changed map[string]bool) []string {