Let a directory say how it reacts to files it does not know, and move out what a move-out directory does not know (issue 1024, ADR 0422)

A directory or archive resource carries `unknown` (move-out, module, program) and `knows`. For move-out under a home, every look moves each path the declaration does not know into ~/.local/state/mesh-moved/<module>/<time>/, the list written before each move, without following a link, a young path waiting, a socket or pipe left and reported, nothing made when nothing moved, and another file system refused. Reviewed in two rounds.

internal/declaration/declaration.go

@@ -124,6 +124,60 @@ type Directory struct {
 	// Owner is the user this belongs to, by name. Absent means root, which is what everything
 	// managed was until users existed.
 	Owner string `json:"owner,omitempty"`
+	// Unknown says how the directory treats a path inside it that nothing declared (issue 1024, novox/hq ADR 0422):
+	// move-out, module or program. Empty means not said, and nothing moves.
+	Unknown string `json:"unknown,omitempty"`
+	// Knows names paths relative to Path that are not declared but belong here; a trailing "/" names a folder and
+	// everything in it.
+	Knows []string `json:"knows,omitempty"`
+}
+
+// How a directory or archive treats what it did not write (issue 1024, ADR 0422).
+const (
+	UnknownMoveOut = "move-out"
+	UnknownModule  = "module"
+	UnknownProgram = "program"
+)
+
+// checkUnknown judges the unknown and knows fields of a directory or an archive.
+func checkUnknown(where, kind, unknown string, knows []string) []string {
+	var problems []string
+	switch unknown {
+	case "", UnknownMoveOut, UnknownModule, UnknownProgram:
+	default:
+		problems = append(problems, fmt.Sprintf(
+			"%s: a %s's unknown is %q; it is %q, %q or %q (issue 1024)", where, kind, unknown,
+			UnknownMoveOut, UnknownModule, UnknownProgram))
+	}
+	if len(knows) > 0 && unknown == "" {
+		problems = append(problems, where+": knows is given without unknown, and says nothing without it")
+	}
+	seen := map[string]bool{}
+	for _, k := range knows {
+		switch {
+		case k == "":
+			problems = append(problems, where+": knows holds an empty entry")
+			continue
+		case strings.HasPrefix(k, "/"):
+			problems = append(problems, fmt.Sprintf("%s: knows entry %q is absolute; it is relative to the path", where, k))
+			continue
+		}
+		bad := false
+		for _, c := range strings.Split(strings.TrimSuffix(k, "/"), "/") {
+			if c == "" || c == "." || c == ".." {
+				bad = true
+			}
+		}
+		if bad {
+			problems = append(problems, fmt.Sprintf("%s: knows entry %q holds an empty, . or .. component", where, k))
+			continue
+		}
+		if seen[k] {
+			problems = append(problems, fmt.Sprintf("%s: knows entry %q is repeated", where, k))
+		}
+		seen[k] = true
+	}
+	return problems
 }
 
 func (d *Directory) Identity() string { return d.ID }
@@ -141,6 +195,7 @@ func (d *Directory) validate(where string, _ bool) []string {
 	if len(mode) == 4 && mode[0] == '2' {
 		mode = "0" + mode[1:]
 	}
+	problems = append(problems, checkUnknown(where, "directory", d.Unknown, d.Knows)...)
 	return append(problems, checkMode(where, mode)...)
 }
 
@@ -696,6 +751,9 @@ type Archive struct {
 	Path string `json:"path"`
 	// Owner is the user the unpacked files belong to. Absent means root.
 	Owner string `json:"owner,omitempty"`
+	// Unknown and Knows are as a directory's (issue 1024, ADR 0422).
+	Unknown string   `json:"unknown,omitempty"`
+	Knows   []string `json:"knows,omitempty"`
 }
 
 func (a *Archive) Identity() string { return a.ID }
@@ -716,6 +774,7 @@ func (a *Archive) validate(where string, _ bool) []string {
 		problems = append(problems, where+
 			": an archive is pinned by digest, as sha256:<64 hex characters>")
 	}
+	problems = append(problems, checkUnknown(where, "archive", a.Unknown, a.Knows)...)
 	return problems
 }