Say who owns a placed file at runtime, and which files the provisioner fills

The provisioner (ADR 0349 §5) needs each file it places to say whether it is
owned, a seed or managed, and the node-engine needs to know which paths it
fills. The words map onto today's forms (drift written back, create-once,
into), so no write changes; the reader accepts the fields and states
OwnershipContract before any controller sends them. Issue 667.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

internal/declaration/declaration.go

@@ -237,8 +237,45 @@ type File struct {
 
 	// Owner is the user this belongs to, by name. Absent means root.
 	Owner string `json:"owner,omitempty"`
+
+	// OwnerAtRuntime says who owns the file once it is placed (novox/hq ADR 0349 §5): "owned", the mesh's
+	// whole, written back whenever it differs; "seed", written once and then the program's; or "managed",
+	// only its named keys or its marked block the mesh's, the program keeping the rest.
+	//
+	// **Three words for what the forms above already do.** Owned is an ordinary file, seed is create-once
+	// and managed is a file written into, so the word changes no write: a file that says it is applied
+	// exactly as its old form is, and one that does not say is owned by its old form (Ownership). The word
+	// is what the provisioner's files say of themselves, which the old forms only implied. Seed is enough
+	// alone; managed still needs `into`, which says the format. A word that contradicts the form is refused.
+	OwnerAtRuntime string `json:"owner-at-runtime,omitempty"`
 }
 
+// The words a file says who owns it at runtime with (novox/hq ADR 0349 §5).
+const (
+	RuntimeOwned   = "owned"
+	RuntimeSeed    = "seed"
+	RuntimeManaged = "managed"
+)
+
+// Ownership is who owns the file at runtime: the word it says, or the one its old form implies — a file
+// written into is managed, one created once is a seed, and any other is owned.
+func (f *File) Ownership() string {
+	switch {
+	case f.OwnerAtRuntime != "":
+		return f.OwnerAtRuntime
+	case f.Into != "":
+		return RuntimeManaged
+	case f.CreateOnce:
+		return RuntimeSeed
+	default:
+		return RuntimeOwned
+	}
+}
+
+// Seeded reports whether the file is written only when absent: created once, by create-once or by the
+// word seed.
+func (f *File) Seeded() bool { return f.CreateOnce || f.OwnerAtRuntime == RuntimeSeed }
+
 // Secret reports whether this file arrived sealed, which is what decides both that it must be
 // opened before writing and that its contents must never appear in a report.
 func (f *File) Secret() bool { return f.Sealed != "" }
@@ -320,6 +357,7 @@ func (f *File) validate(where string, _ bool) []string {
 				"secrets or create-once")
 		}
 	}
+	problems = append(problems, f.checkOwnership(where)...)
 	var said []string
 	for name, value := range map[string]string{
 		"content": f.Content, "sealed": f.Sealed, "bytes": f.Bytes,
@@ -361,6 +399,42 @@ func (f *File) validate(where string, _ bool) []string {
 	return append(problems, checkMode(where, f.Mode)...)
 }
 
+// checkOwnership refuses a word that contradicts the file's form (novox/hq ADR 0349 §5): owned is a whole
+// file written back, so not created once nor written into; a seed is a whole file created once, so not
+// written into; managed is a file written into, which says its format. Managed and created once together
+// is already refused by the rule that a file written into is not created once.
+func (f *File) checkOwnership(where string) []string {
+	switch f.OwnerAtRuntime {
+	case "":
+	case RuntimeOwned:
+		var also []string
+		if f.CreateOnce {
+			also = append(also, "create-once")
+		}
+		if f.Into != "" {
+			also = append(also, "into")
+		}
+		if len(also) > 0 {
+			return []string{fmt.Sprintf("%s: owned at runtime is the mesh's whole file, written back whenever it "+
+				"differs, and this also says %s", where, strings.Join(also, " and "))}
+		}
+	case RuntimeSeed:
+		if f.Into != "" {
+			return []string{where + ": a seed is a whole file written once, and this says into; a file the " +
+				"program shares with the mesh is managed"}
+		}
+	case RuntimeManaged:
+		if f.Into == "" {
+			return []string{where + ": a managed file names the format its keys or block are written into, " +
+				"with into \"json\" or \"block\""}
+		}
+	default:
+		return []string{fmt.Sprintf("%s: owner-at-runtime %q; a placed file is %q, %q or %q, or omits it to be "+
+			"owned by its form", where, f.OwnerAtRuntime, RuntimeOwned, RuntimeSeed, RuntimeManaged)}
+	}
+	return nil
+}
+
 // User is a login on the machine.
 //
 // The thing that makes a shell, a chat client or a desktop expressible at all: each is a package
@@ -1565,6 +1639,52 @@ type Declaration struct {
 	// this is its home, whether the operator's warrant to take it was carried out, the sub-paths its modules ask for,
 	// and the tool runner's account to put in its group (§11). Absent is a controller older than ADR 0328.
 	Libraries []Library
+
+	// Filled is the paths of the files the provisioner fills on this machine (novox/hq ADR 0349 §4, §5): each a
+	// file this declaration declares, which says who owns it at runtime. The provisioner's client has the
+	// node-engine write only these. Absent is a controller that hands no file to the provisioner, and every
+	// file is written from the declaration as before.
+	Filled []string
+}
+
+// Fills reports whether the provisioner fills the file at path on this machine.
+func (d *Declaration) Fills(path string) bool { return slices.Contains(d.Filled, path) }
+
+// checkFilled refuses a filled path that is not a declared file saying who owns it at runtime, or that is named
+// twice or empty. Every file declared at the path must say it: the provisioner writes the path, and a file there
+// the mesh writes some other way would be a second writer of it (ADR 0349 §5).
+func checkFilled(filled []string, resources []Resource) []string {
+	var problems []string
+	files := map[string][]*File{}
+	for _, r := range resources {
+		if f, ok := r.(*File); ok {
+			files[f.Path] = append(files[f.Path], f)
+		}
+	}
+	seen := map[string]bool{}
+	for _, path := range filled {
+		switch {
+		case path == "":
+			problems = append(problems, "filled_files names a file with no path")
+			continue
+		case seen[path]:
+			problems = append(problems, fmt.Sprintf("filled_files names %q twice", path))
+			continue
+		}
+		seen[path] = true
+		if len(files[path]) == 0 {
+			problems = append(problems, fmt.Sprintf("filled_files names %q, and this declaration declares no "+
+				"file there", path))
+			continue
+		}
+		for _, f := range files[path] {
+			if f.OwnerAtRuntime == "" {
+				problems = append(problems, fmt.Sprintf("resource %q: the provisioner fills %q, and a file it "+
+					"fills says who owns it at runtime with owner-at-runtime", f.ID, path))
+			}
+		}
+	}
+	return problems
 }
 
 // Identity is one module's identity, as the controller allocated it (ADR 0328 §4): its user `mesh-<module>` with
@@ -1904,6 +2024,9 @@ type envelope struct {
 	// sends them only to a host whose health says link.LibraryContract.
 	Groups    []Group   `json:"groups,omitempty"`
 	Libraries []Library `json:"libraries,omitempty"`
+	// Filled is optional too (novox/hq ADR 0349 §5), as is a file's `owner-at-runtime`. **An older host refuses
+	// these keys**; a controller sends them only to a host whose health says link.OwnershipContract.
+	Filled []string `json:"filled_files,omitempty"`
 }
 
 func parse(raw []byte, allowActions bool) (*Declaration, error) {
@@ -1922,7 +2045,7 @@ func parse(raw []byte, allowActions bool) (*Declaration, error) {
 
 	d := &Declaration{Version: env.Version, For: env.For, Adoption: env.Adoption, Sequence: env.Sequence,
 		Epoch: env.Epoch, LeftOut: env.LeftOut, Generation: env.Generation, PutBack: env.PutBack,
-		Identities: env.Identities, Groups: env.Groups, Libraries: env.Libraries}
+		Identities: env.Identities, Groups: env.Groups, Libraries: env.Libraries, Filled: env.Filled}
 	problems := checkIdentities(env.Identities, env.Groups)
 	problems = append(problems, checkLibraries(env.Groups, env.Libraries)...)
 	if env.Generation < 0 {
@@ -2015,6 +2138,7 @@ func parse(raw []byte, allowActions bool) (*Declaration, error) {
 	problems = append(problems, checkWhileStopped(d.Resources)...)
 	problems = append(problems, checkAdoption(env.Adoption, d.Resources, allowActions)...)
 	problems = append(problems, checkReplaces(d.Resources)...)
+	problems = append(problems, checkFilled(env.Filled, d.Resources)...)
 	if env.Adoption == nil {
 		for _, r := range d.Resources {
 			if r.Kind() == TypeOpening {