A run-once step names what it reads and runs again when it changed (novox/hq ADR 0099, issue 077)

internal/declaration/declaration.go

@@ -678,7 +678,8 @@ type Container struct {
 	// env, volumes — does not include a mounted file's *content*, so a settings change that
 	// re-renders that file is invisible to the ordinary spec diff. This closes that: the host
 	// recreates the container when one of these resources changed this pass, even if the spec
-	// matches.
+	// matches. On a run-once step it means *run again*: a step that fetches a fact from a provider
+	// names the binding it reads, and is run again when the provider moved (novox/hq ADR 0099).
 	RestartOn []string `json:"restart-on,omitempty"`
 
 	// RunOnce marks a container the host runs to completion rather than leaves running: a step,
@@ -713,13 +714,9 @@ func (c *Container) validate(where string, _ bool) []string {
 	if c.Name == "" {
 		problems = append(problems, where+": a container needs a name")
 	}
-	// restart-on brings a *running* container back when a file it read changed; a run-once step
-	// does not stay running to be brought back. Declaring both asks for two contradictory
-	// lifecycles at once, so it is refused rather than silently resolved to one of them.
-	if c.RunOnce && len(c.RestartOn) > 0 {
-		problems = append(problems, where+": a run-once container cannot also declare restart-on; "+
-			"it runs to completion rather than staying running to be restarted")
-	}
+	// A run-once step may name what it reads under restart-on. For a step the word means *run
+	// again*: what a container reads is part of its digest, so a step whose named resource changed
+	// is a different step and runs again (novox/hq ADR 0099). Not refused.
 	// A container runs once and gates, on a cadence, or stays up — never two of these
 	// (novox/hq ADR 0053). run-once and schedule are the two "runs to completion" lifecycles and
 	// contradict each other, and a scheduled step does not stay running to be brought back by