Merge pull request 'No change to a machine takes effect unseen (hq ADR 0217)' (#50) from feat/no-change-takes-effect-unseen into main

internal/catalogue/verbs.go

@@ -168,11 +168,14 @@ var ControllerVerbs = []Verb{
 		Input: schema(map[string]string{"plan": "one walk's id", "limit": "how many ended walks beside the open ones (default 50)"},
 			nil)},
 	{Name: "plan", Description: "What one machine would run, and why: the declaration the mesh would send it — " +
-		"or, with files, the files it would be given.",
+		"or, with files, the files it would be given; or, with diff, what a push would change there against what " +
+		"it was last sent: resources added, removed and changed, a container's changed fields (it is recreated), " +
+		"and any mount whose directory on the machine would move (novox/hq ADR 0217).",
 		Input: schema(map[string]string{
 			"node":  "the machine's name",
 			"files": "\"true\": the files this machine would be given, instead of the declaration as JSON",
-		}, []string{"node"}, "files")},
+			"diff":  "\"true\": what a push would change on this machine, against what it was last sent; not with files",
+		}, []string{"node"}, "files", "diff")},
 	{Name: "assign", Description: "Put a module on a machine. Refused with the mesh's own words when it cannot resolve there, " +
 		"or when a seat its resources are applied through is held by nothing on the machine (novox/hq ADR 0207).",
 		Input: schema(map[string]string{"node": "the machine's name",
@@ -194,9 +197,12 @@ var ControllerVerbs = []Verb{
 		"WHOLE mesh — every machine that is behind — and the answer says so first; behind says that outright. " +
 		"Answers at once that it is running, with a call id: `calls` with that id says what it sent " +
 		"(a push can reload the bus, which then refuses any answer still to come). A push by hand is a repair, " +
-		"and says why: recorded in the hand-act log (novox/hq to-be 45 §7).",
+		"and says why: recorded in the hand-act log (novox/hq to-be 45 §7). A machine whose push would give a " +
+		"running module's data another directory is held and named, the others sent (novox/hq ADR 0217): read " +
+		"`plan` with diff, and name the machine with move to send it.",
 		Input: schema(map[string]string{
 			"node":   "the machine's name; without it, every machine that is behind",
+			"move":   "with node: the modules whose data may move with this push, comma-separated (optional)",
 			"behind": "\"true\": every machine that is behind, the whole mesh — the same as naming none, said outright; not with node",
 			"why":    "why this is pushed by hand: recorded in the hand-act log",
 			"cause":  "the cause in a word, or a condition's kind — the word a second push for the same reason uses (optional)",
@@ -222,15 +228,20 @@ var ControllerVerbs = []Verb{
 			"node":   "the machine that runs the module",
 			"module": "the module's name",
 		}, []string{"node", "module"})},
-	{Name: "settings", Description: "Set what an assignment is configured with: a module's settings for the whole mesh, " +
-		"or for one machine. Replaces that layer whole — what it does not name, it no longer sets — and takes effect " +
-		"at the next push. With clear, removes the layer and the module is back to what its definition says.",
+	{Name: "settings", Description: "Read or set what an assignment is configured with: a module's settings for the whole " +
+		"mesh, or for one machine. Without values or clear, answers the layer as it stands — read it before setting it; " +
+		"with history, the layers it replaced. Setting replaces that layer whole and answers each key it adds (+), " +
+		"changes (~) and removes (-); a set that would remove a key is refused unless replace says it is meant " +
+		"(novox/hq ADR 0217). Takes effect at the next push. With clear, removes the layer and the module is back to " +
+		"what its definition says; a cleared or replaced layer is kept in the history.",
 		Input: schema(map[string]string{
-			"module": "the module's name",
-			"values": "the settings as a JSON object, for set",
-			"node":   "one machine; the whole mesh when absent",
-			"clear":  "\"true\" to remove the layer instead of setting it; not with values",
-		}, []string{"module"}, "clear")},
+			"module":  "the module's name",
+			"values":  "the settings as a JSON object, for set",
+			"node":    "one machine; the whole mesh when absent",
+			"clear":   "\"true\" to remove the layer instead of setting it; not with values",
+			"replace": "\"true\": with values, the set is meant to remove the keys the layer had and it does not name",
+			"history": "\"true\": without values or clear, the layers this one replaced, the latest first",
+		}, []string{"module"}, "clear", "replace", "history")},
 	{Name: "command", Description: "Run one command line of the controller's own, as you would type it at its " +
 		"shell — `node account g14 jochen`, `node show ace`, `module list` — and answer what it printed. The " +
 		"generic verb beside the named ones (novox/hq ADR 0154): everything the binary can do, without a verb " +