@promptctl/cc-candybar 1.29.0 → 1.31.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@promptctl/cc-candybar",
-  "version": "1.29.0",
+  "version": "1.31.0",
   "description": "Statusline renderer for Claude Code — a JSON5-configurable DSL with daemon-cached data sources, byte-clean palette-aware composition, and OSC8 click verbs.",
   "type": "module",
   "main": "./dist/index.mjs",
@@ -91,9 +91,9 @@
     "mobx": "^6.15.0"
   },
   "optionalDependencies": {
-    "@promptctl/cc-candybar-darwin-arm64": "1.29.0",
-    "@promptctl/cc-candybar-darwin-x64": "1.29.0",
-    "@promptctl/cc-candybar-linux-x64": "1.29.0",
-    "@promptctl/cc-candybar-linux-arm64": "1.29.0"
+    "@promptctl/cc-candybar-darwin-arm64": "1.31.0",
+    "@promptctl/cc-candybar-darwin-x64": "1.31.0",
+    "@promptctl/cc-candybar-linux-x64": "1.31.0",
+    "@promptctl/cc-candybar-linux-arm64": "1.31.0"
   }
 }

package/schema/cc-candybar.schema.json

@@ -1321,6 +1321,49 @@
             ],
             "additionalProperties": false
           },
+          {
+            "type": "object",
+            "properties": {
+              "persist": {
+                "type": "string"
+              },
+              "removeSegment": {
+                "type": "string"
+              }
+            },
+            "required": [
+              "persist",
+              "removeSegment"
+            ],
+            "additionalProperties": false
+          },
+          {
+            "type": "object",
+            "properties": {
+              "persist": {
+                "type": "string"
+              },
+              "insertSegment": {
+                "type": "string"
+              },
+              "anchor": {
+                "type": "string"
+              },
+              "relation": {
+                "enum": [
+                  "before",
+                  "after"
+                ]
+              }
+            },
+            "required": [
+              "persist",
+              "insertSegment",
+              "anchor",
+              "relation"
+            ],
+            "additionalProperties": false
+          },
           {
             "type": "object",
             "properties": {
@@ -1356,6 +1399,30 @@
               "reset"
             ],
             "additionalProperties": false
+          },
+          {
+            "type": "object",
+            "properties": {
+              "undo": {
+                "const": true
+              }
+            },
+            "required": [
+              "undo"
+            ],
+            "additionalProperties": false
+          },
+          {
+            "type": "object",
+            "properties": {
+              "redo": {
+                "const": true
+              }
+            },
+            "required": [
+              "redo"
+            ],
+            "additionalProperties": false
           }
         ]
       }

package/src/click/wire.ts

@@ -66,6 +66,26 @@ export const VERB_STEP_CONFIG = "step-config";
 // config-overrides key, restoring the user-file/bundled-default value on the
 // next reload. Args: `[sessionId, key]`.
 export const VERB_RESET_CONFIG = "reset-config";
+// [LAW:one-type-per-behavior] brandon-layout-edit-2gc.1's structural-edit
+// verb — a THIRD write semantic beside set-config's plain overwrite and
+// step-config's numeric read-modify-write: read the current op-token LIST at
+// `key` (a "presets.<name>.rootOps" config-overrides target), append the
+// validated `op` token, write the whole list back. Args: `[sessionId, key,
+// op]` — `op` is one opaque token from src/config/layout-ops.ts's codec, the
+// SAME shape a `persist … to` literal's value would be, gated the SAME way
+// (validateConfigWrite) — only the write's SHAPE (append vs. overwrite)
+// differs, which is exactly why this is its own verb rather than another
+// VERB_SET_CONFIG value.
+export const VERB_APPLY_LAYOUT_OP = "apply-layout-op";
+// [LAW:one-source-of-truth] brandon-layout-edit-2gc.2's global history step
+// over the config-overrides layer — the fine-grained sibling of
+// VERB_RESET_CONFIG's coarse "clear one key". Args: `[sessionId]` — there is
+// no key: the history is ONE stack over every persist/reset write ever made
+// to the overrides file (config-overrides-store.ts), not a per-key log. An
+// empty stack is a loud BAD_REQUEST surfaced through click.error like any
+// other verb failure, never a silent no-op.
+export const VERB_UNDO = "undo";
+export const VERB_REDO = "redo";
 
 // [LAW:types-are-the-program] An effect to EMIT: a verb plus its raw (unencoded)
 // positional args. The wire owns all encoding — callers never percent-encode.

package/src/config/action.ts

@@ -43,7 +43,24 @@ export type { OptionDomain } from "./option-domain.js";
 // overrides layer (never the hand-authored config file). `reset` clears one
 // persisted override — the gated undo `persist` needs, since a machine-owned
 // write with no way back would be a one-way ratchet.
-export const ACTION_KEYS = ["set", "persist", "copy", "open", "reset"] as const;
+//
+// [LAW:one-source-of-truth] `undo`/`redo` (brandon-layout-edit-2gc.2) are
+// `reset`'s FINE-GRAINED siblings: `reset` clears one named key outright
+// (the coarse "forget this override" case); `undo`/`redo` step ONE GLOBAL
+// history of every `persist`/`reset` write ever made to the overrides layer
+// — every key, not just structural layout edits — back and forth. Neither
+// carries a key: the history is a single stack over the whole overrides
+// file (config-overrides-store.ts owns it), so the action is a bare marker,
+// like `int: true` is for a set-int cursor.
+export const ACTION_KEYS = [
+  "set",
+  "persist",
+  "copy",
+  "open",
+  "reset",
+  "undo",
+  "redo",
+] as const;
 export type ActionKey = (typeof ACTION_KEYS)[number];
 
 // [LAW:types-are-the-program] An ActionDecl is the click effect a named action
@@ -75,6 +92,22 @@ export type ActionKey = (typeof ACTION_KEYS)[number];
 //                         -> allow-list {members}
 //   copy                — copy templated text to the clipboard -> no gate
 //   open                — open a templated target in the editor -> no gate
+//   undo                — step the config-overrides layer's GLOBAL history one
+//                         entry back (any persist/reset write, not just a
+//                         layout op) -> no gate, no key: there is nothing a
+//                         template could smuggle, since the value restored is
+//                         whatever the daemon's own history recorded, never
+//                         wire input
+//   redo                — the inverse of undo: re-apply the most recently
+//                         undone entry -> no gate, no key
+//   removeSegment       — (persist only) remove the named segment from the
+//                         preset-root the `persist` key addresses
+//                         (`presets.<name>.rootOps`) -> allow-list {one op
+//                         token — see src/config/layout-ops.ts}
+//   insertSegment +
+//     anchor + relation  — (persist only) insert a named segment before/after
+//                         an existing one, same key shape -> allow-list {one
+//                         op token}
 //
 // [LAW:one-source-of-truth] `set` writes SessionState and `persist` writes
 // the config-overrides layer, so only those two derive a validator (through
@@ -87,6 +120,15 @@ export type ActionKey = (typeof ACTION_KEYS)[number];
 // arms verbatim (to/from/min-max-by/cycle) MINUS `int`: an unbounded page
 // cursor is a UI-only paging concept (a picker's own navigation state) with
 // no meaning as a persisted config default.
+//
+// [LAW:locality-or-seam] `removeSegment`/`insertSegment` are `persist`-ONLY
+// (brandon-layout-edit-2gc.1) — a structural edit is always a durable,
+// machine-owned write by design (the ticket's own instruction: reuse 71o's
+// writer, land in the SAME overrides layer), so there is no SessionState
+// twin. Every operation is fully literal at config-author time — the
+// segment names and relation are DATA the loader proves at load, not a
+// runtime picker — so each declared action has exactly one legal request,
+// gated the same one-member-allow-list way a literal `to` already is.
 export type ActionDecl =
   | { readonly set: string; readonly to: string }
   | { readonly set: string; readonly from: OptionDomain }
@@ -107,9 +149,18 @@ export type ActionDecl =
       readonly by: number;
     }
   | { readonly persist: string; readonly cycle: readonly string[] }
+  | { readonly persist: string; readonly removeSegment: string }
+  | {
+      readonly persist: string;
+      readonly insertSegment: string;
+      readonly anchor: string;
+      readonly relation: "before" | "after";
+    }
   | { readonly copy: string }
   | { readonly open: string }
-  | { readonly reset: string };
+  | { readonly reset: string }
+  | { readonly undo: true }
+  | { readonly redo: true };
 
 // [LAW:dataflow-not-control-flow] Does this action write a SessionState key? A
 // `set` action composes a set-state click URL whose first segment is session.id;
@@ -131,3 +182,14 @@ export function actionBindsPersist(a: ActionDecl): boolean {
 export function actionBindsReset(a: ActionDecl): boolean {
   return "reset" in a;
 }
+
+// [LAW:dataflow-not-control-flow] Does this action step the config-overrides
+// history? `undo`/`redo` carry session.id on the wire too — same reason as
+// `reset`: an empty stack is a loud, session-scoped click.error, not a
+// silent no-op (the ticket's own done-gate).
+export function actionBindsUndo(a: ActionDecl): boolean {
+  return "undo" in a;
+}
+export function actionBindsRedo(a: ActionDecl): boolean {
+  return "redo" in a;
+}

package/src/config/layout-ops.ts

@@ -0,0 +1,156 @@
+// [LAW:one-type-per-behavior] The seam brandon-layout-edit-2gc.1 opens: a
+// bounded, statically-enumerable vocabulary for mutating a LayoutNode tree —
+// remove the segment named X, insert a named segment before/after an
+// existing one. No third LayoutNode kind, no free-form tree editing: a
+// segment's own NAME is the stable position (dsl-types.ts already makes it
+// one — SegmentNode.name is a ref into `segments`, unaffected by a sibling
+// being added or removed elsewhere in the tree), so there is no sibling-index
+// to invalidate when a prior op lands.
+//
+// [LAW:no-ambient-temporal-coupling] A position is never a fact frozen at
+// declaration or click time — `removeSegment`/`insertSegment` always walk
+// the CURRENT tree handed to them. The daemon (src/daemon/cache/render.ts)
+// replays the accumulated op log against the live merged config on every
+// reload, so a later, unrelated config edit is what the next replay sees,
+// never a stale snapshot.
+//
+// [LAW:no-silent-failure] exception: a target/anchor absent from the tree is
+// a documented NO-OP, not a thrown error — mirroring
+// src/config/loader/merge.ts's applySegmentPaletteOverrides, the identical
+// failure shape one layer up. A validated action can only ever name a
+// segment the config declares (loader/cross-ref.ts checks this at config
+// load), so a miss here only happens after a LATER edit (to the bundled
+// default, the user's config, or an earlier op in the same accumulated list)
+// removed the segment — there is nothing left to apply the op to, and
+// bricking the whole render over a stale op would be worse than dropping it.
+
+import type { LayoutNode, SegmentNode } from "./dsl-types.js";
+
+// [LAW:types-are-the-program] The two operations brandon-layout-edit-2gc.1
+// ships. Both address position by NAME, never by index. A future op (e.g.
+// "move") is a new arm here, not a new node kind or a new codec.
+export type LayoutOp =
+  | { readonly op: "remove"; readonly target: string }
+  | {
+      readonly op: "insert";
+      readonly segment: string;
+      readonly anchor: string;
+      readonly relation: "before" | "after";
+    };
+
+// [LAW:single-enforcer] THE codec for a LayoutOp crossing the click wire and
+// the config-overrides file as one opaque string. `:` is the delimiter
+// (loader/actions.ts's segmentNameSpec rejects `:` and `/` in every name an
+// op can carry, so decode is unambiguous — a plain split, no escaping).
+// Encode and decode live together so the format cannot drift between the
+// validator gate (config-validators.ts, which encodes the ONE token a
+// declared action allows), the render side (which emits that same token),
+// and the daemon (which decodes it back).
+export function encodeLayoutOp(op: LayoutOp): string {
+  return op.op === "remove"
+    ? `remove:${op.target}`
+    : `insert:${op.segment}:${op.anchor}:${op.relation}`;
+}
+
+// [LAW:parse-dont-validate] Returns the typed op, or null for anything that
+// doesn't decode — the boundary a caller stamps before trusting the shape.
+// Reached only from data this process did not itself just encode (a
+// hand-edited or previous-version config-overrides.json), never from a
+// value produced by encodeLayoutOp in the same click.
+export function decodeLayoutOp(token: string): LayoutOp | null {
+  const parts = token.split(":");
+  if (parts[0] === "remove" && parts.length === 2 && parts[1]) {
+    return { op: "remove", target: parts[1] };
+  }
+  if (
+    parts[0] === "insert" &&
+    parts.length === 4 &&
+    parts[1] &&
+    parts[2] &&
+    (parts[3] === "before" || parts[3] === "after")
+  ) {
+    return {
+      op: "insert",
+      segment: parts[1],
+      anchor: parts[2],
+      relation: parts[3],
+    };
+  }
+  return null;
+}
+
+// [LAW:dataflow-not-control-flow] Ops are DATA folded over the tree in
+// order — replaying zero ops is the identity fold, replaying N is the same
+// reduce for every N. No branch on "are there ops to apply."
+export function applyLayoutOps(
+  root: LayoutNode,
+  ops: readonly LayoutOp[],
+): LayoutNode {
+  return ops.reduce(applyOne, root);
+}
+
+function applyOne(root: LayoutNode, op: LayoutOp): LayoutNode {
+  return op.op === "remove"
+    ? removeSegment(root, op.target)
+    : insertSegment(root, op.segment, op.anchor, op.relation);
+}
+
+// [LAW:types-are-the-program] Total and non-throwing: every LayoutNode maps
+// to a LayoutNode, whether or not `target` is present. Acts on the FIRST
+// segment found named `target`, in walkNodes' canonical pre-order — a
+// deterministic, documented tie-break for the edge case of a duplicate name,
+// never an ambiguous or thrown outcome. `done` is a closure-local flag (fresh
+// per call, never shared across calls) that stops the search the instant a
+// match is spliced out, so an EARLIER sibling's match always wins over a
+// LATER one — exactly walkNodes' visit order, not merely "this container's
+// own children before its descendants" (a subtly different, wrong order a
+// single-pass children-array scan would produce). An absent target returns
+// the identical root reference.
+function removeSegment(root: LayoutNode, target: string): LayoutNode {
+  let done = false;
+  function walk(node: LayoutNode): LayoutNode {
+    if (done || node.kind === "segment") return node;
+    const children: LayoutNode[] = [];
+    for (const child of node.children) {
+      if (!done && child.kind === "segment" && child.name === target) {
+        done = true;
+        continue;
+      }
+      children.push(walk(child));
+    }
+    return { ...node, children };
+  }
+  const result = walk(root);
+  return done ? result : root;
+}
+
+// [LAW:types-are-the-program] Splices a new `{ kind: "segment", name:
+// segment }` node immediately before/after the FIRST node found named
+// `anchor`, in walkNodes' canonical pre-order (see removeSegment's `done`
+// note — the same closure-local stop-at-first-match shape). Total and
+// non-throwing: an absent anchor returns the identical root reference.
+function insertSegment(
+  root: LayoutNode,
+  segment: string,
+  anchor: string,
+  relation: "before" | "after",
+): LayoutNode {
+  let done = false;
+  function walk(node: LayoutNode): LayoutNode {
+    if (done || node.kind === "segment") return node;
+    const children: LayoutNode[] = [];
+    for (const child of node.children) {
+      if (!done && child.kind === "segment" && child.name === anchor) {
+        done = true;
+        const inserted: SegmentNode = { kind: "segment", name: segment };
+        if (relation === "before") children.push(inserted, child);
+        else children.push(child, inserted);
+        continue;
+      }
+      children.push(walk(child));
+    }
+    return { ...node, children };
+  }
+  const result = walk(root);
+  return done ? result : root;
+}

package/src/config/loader/actions.ts

@@ -145,6 +145,8 @@ const ACTION_ARMS: Record<ActionKey, ArmParse<ActionDecl>> = {
   copy: templateArm("copy"),
   open: templateArm("open"),
   reset: resetArm,
+  undo: markerArm("undo"),
+  redo: markerArm("redo"),
 };
 
 // [LAW:one-source-of-truth] A copy/open action emits the closed single-key
@@ -170,6 +172,8 @@ function actionDeclJson(): JsonNode {
       templateArmJson("copy"),
       templateArmJson("open"),
       templateArmJson("reset"),
+      markerArmJson("undo"),
+      markerArmJson("redo"),
     ],
   };
 }
@@ -228,6 +232,47 @@ function resetArm(
   return key === null ? null : { reset: key };
 }
 
+// [LAW:one-type-per-behavior] `undo`/`redo` are copy/open/reset's shape one
+// step further reduced: a single required key whose only legal VALUE is the
+// literal `true` (mirrors intMarkerSpec — a marker, not data), because there
+// is no key to name: the history they step is one global stack over the
+// whole overrides layer, not a per-target write. `function`, not a const
+// arrow, so ACTION_ARMS above (built before this declaration in source
+// order) can reference it directly via hoisting.
+function markerArm(key: "undo" | "redo"): ArmParse<ActionDecl> {
+  return (ctx, path, raw) => {
+    for (const k of Object.keys(raw)) {
+      if (k !== key)
+        issue(
+          ctx,
+          `${path}.${k}`,
+          `Unknown key "${k}" on a ${key} action. Expected only: ${key}`,
+        );
+    }
+    if (raw[key] !== true) {
+      issue(
+        ctx,
+        `${path}.${key}`,
+        `${key} must be the literal true (it takes no key — it steps the ONE global history over the whole overrides layer), got ${describeValue(raw[key])}`,
+      );
+      return null;
+    }
+    return { [key]: true } as unknown as ActionDecl;
+  };
+}
+
+// [LAW:one-source-of-truth] Mirrors templateArmJson's shape one level
+// narrower: the value schema is `const: true`, not `type: string` — a
+// marker action carries no data, on the wire or in the schema.
+function markerArmJson(key: "undo" | "redo"): JsonNode {
+  return {
+    type: "object",
+    properties: { [key]: { const: true } },
+    required: [key],
+    additionalProperties: false,
+  };
+}
+
 // ─── The `set` value-source sub-union ────────────────────────────────────────
 
 // [LAW:single-enforcer] A set-state URL path segment must be a non-empty,
@@ -324,6 +369,25 @@ const CYCLE_FIELDS_SET: FieldSpecMap<{ cycle: readonly string[] }> = {
 const CYCLE_FIELDS_PERSIST: FieldSpecMap<{ cycle: readonly string[] }> = {
   cycle: cycleSpec("persist"),
 };
+// [LAW:one-type-per-behavior] brandon-layout-edit-2gc.1's two structural-edit
+// arms — PERSIST-only (see action.ts's ActionDecl doc comment for why there
+// is no `set` twin). Each field reuses layoutNameSpec: a segment/anchor name
+// must be non-empty and free of both `/` (the click wire's own segment
+// delimiter) and `:` (layout-ops.ts's op-token delimiter) — the SAME
+// wire-safety diligence slashFreeString already applies to `to`/`cycle`
+// members, one forbidden character wider.
+const REMOVE_SEGMENT_FIELDS: FieldSpecMap<{ removeSegment: string }> = {
+  removeSegment: layoutNameSpec("removeSegment"),
+};
+const INSERT_SEGMENT_FIELDS: FieldSpecMap<{
+  insertSegment: string;
+  anchor: string;
+  relation: "before" | "after";
+}> = {
+  insertSegment: layoutNameSpec("insertSegment"),
+  anchor: layoutNameSpec("anchor"),
+  relation: relationSpec(),
+};
 
 // [LAW:types-are-the-program] A bounded step is fully described by an integer
 // domain (min < max) and a non-zero integer increment (`by`; negative for a
@@ -418,16 +482,49 @@ const SET_ARMS: readonly ValueSourceArm[] = [
 
 // [LAW:one-type-per-behavior] `persist` mirrors `set` minus the `int` arm — a
 // page cursor is a UI-only paging concept with no meaning as a persisted
-// config default (see action.ts's ActionDecl comment).
+// config default (see action.ts's ActionDecl comment). `removeSegment`/
+// `insertSegment` are ADDITIONAL persist-only arms with no `set` counterpart.
 const PERSIST_ARMS: readonly ValueSourceArm[] = [
   valueSourceArm("persist", TO_FIELDS_PERSIST),
   valueSourceArm("persist", FROM_FIELDS_PERSIST),
   valueSourceArm("persist", BOUNDED_FIELDS, minLessThanMax, byNonZero),
   valueSourceArm("persist", CYCLE_FIELDS_PERSIST),
+  valueSourceArm("persist", REMOVE_SEGMENT_FIELDS),
+  valueSourceArm("persist", INSERT_SEGMENT_FIELDS),
 ];
 
-const VALUE_SOURCE_MESSAGE = (discriminator: "set" | "persist") =>
-  `a ${discriminator} action declares exactly one value source: "to" (a literal value), "from" (an option domain — a registered domain name like "themes"/"styles"/"looks", or an inline array of literal values), "min"/"max"/"by" (a bounded step)${discriminator === "set" ? `, "int" (an unbounded integer cursor)` : ""}, or "cycle" (an enumerated domain stepped in order)`;
+// [LAW:one-source-of-truth] The clause list, not the joined string, is the
+// data that varies per discriminator — the "or" belongs on the LAST clause
+// only, and which clause is last differs between `set` (ends at cycle) and
+// `persist` (ends at insertSegment), so building a list and joining it is
+// what keeps that placement correct without a second copy of the sentence.
+function valueSourceClauses(discriminator: "set" | "persist"): string[] {
+  const clauses = [
+    `"to" (a literal value)`,
+    `"from" (an option domain — a registered domain name like "themes"/"styles"/"looks", or an inline array of literal values)`,
+    `"min"/"max"/"by" (a bounded step)`,
+  ];
+  if (discriminator === "set")
+    clauses.push(`"int" (an unbounded integer cursor)`);
+  clauses.push(`"cycle" (an enumerated domain stepped in order)`);
+  if (discriminator === "persist") {
+    clauses.push(
+      `"removeSegment" (remove a named segment from the layout)`,
+      `"insertSegment"/"anchor"/"relation" (insert a named segment before/after an existing one)`,
+    );
+  }
+  return clauses;
+}
+
+function VALUE_SOURCE_MESSAGE(discriminator: "set" | "persist"): string {
+  const clauses = valueSourceClauses(discriminator);
+  const last = clauses[clauses.length - 1]!;
+  const list =
+    clauses.length === 1
+      ? last
+      : `${clauses.slice(0, -1).join(", ")}, or ${last}`;
+  return `a ${discriminator} action declares exactly one value source: ${list}`;
+}
 
 // [LAW:dataflow-not-control-flow] The set/persist sub-union eliminator:
 // validate the shared discriminator key, count which value sources are
@@ -681,6 +778,61 @@ function intMarkerSpec(): FieldSpec<true> {
   };
 }
 
+// [LAW:one-source-of-truth] A layout op's segment-name field (removeSegment /
+// insertSegment / anchor) is non-empty and free of BOTH wire-structural
+// characters: `/` (the click wire's own multi-arg segment delimiter, the
+// same restriction slashFreeString already enforces for `to`/`cycle`) and
+// `:` (layout-ops.ts's op-token delimiter — a name containing it would make
+// encodeLayoutOp's output ambiguous to decode). One spec, three callsites,
+// so the two-character restriction can't drift between them.
+function layoutNameSpec(field: string): FieldSpec<string> {
+  return {
+    required: true,
+    json: { type: "string" },
+    parse: (ctx, path, f, raw) => {
+      const v = requireString(ctx, path, raw, f);
+      if (v === null) return undefined;
+      const at = `${path}.${f}`;
+      if (v === "") {
+        issue(ctx, at, `${field} must be non-empty (a segment name)`);
+        return undefined;
+      }
+      if (v.includes("/") || v.includes(":")) {
+        issue(
+          ctx,
+          at,
+          `${field} "${v}" contains "/" or ":" — segment names in a layout op must be free of both (the click wire's own delimiter and layout-ops.ts's op-token delimiter)`,
+        );
+        return undefined;
+      }
+      return v;
+    },
+  };
+}
+
+// [LAW:types-are-the-program] `relation` is a closed two-value enum, not a
+// free string — a typo (`"befor"`) is a load error, never a click-time
+// surprise. Mirrors intMarkerSpec's "one legal literal" shape, widened to
+// two.
+function relationSpec(): FieldSpec<"before" | "after"> {
+  return {
+    required: true,
+    json: { enum: ["before", "after"] },
+    parse: (ctx, path, field, raw) => {
+      const v = raw[field];
+      if (v !== "before" && v !== "after") {
+        issue(
+          ctx,
+          `${path}.${field}`,
+          `relation must be "before" or "after", got ${describeValue(v)}`,
+        );
+        return undefined;
+      }
+      return v;
+    },
+  };
+}
+
 // [LAW:types-are-the-program] A required integer field — the field key (min / max
 // / by) comes from the map, the message names it. A non-integer or absent value
 // reports and fails the arm.