@promptctl/cc-candybar 1.36.0 → 1.38.0

package/src/config/loader/actions.ts

@@ -20,6 +20,7 @@
 
 import {
   ACTION_KEYS,
+  PERSIST_WHEN,
   type ActionDecl,
   type ActionKey,
   type OptionDomain,
@@ -103,6 +104,16 @@ function validateActionDecl(
     );
     return null;
   }
+  // [LAW:dataflow-not-control-flow] A dual-destination action
+  // (candybar-settings-ui-aok.3) carries BOTH `set` and `persist`, so it
+  // cannot be reached through the exactly-one-of eliminator below —
+  // `persistWhen` is its own discriminator, and its presence selects the arm
+  // exactly as the presence of `set` selects that one. The dual arm owns its
+  // own siblings (the two destination keys plus its value source), like every
+  // other arm here.
+  if (PERSIST_WHEN in raw) {
+    return valueSourceAction(ctx, path, raw, "dual", DUAL_ARMS);
+  }
   const present = (ACTION_KEYS as readonly string[]).filter((k) => k in raw);
   if (present.length !== 1) {
     issue(
@@ -124,24 +135,9 @@ function validateActionDecl(
 // sibling. The present key indexes this map — the eliminator never branches on
 // the key name.
 const ACTION_ARMS: Record<ActionKey, ArmParse<ActionDecl>> = {
-  set: (ctx, path, raw) =>
-    valueSourceAction(
-      ctx,
-      path,
-      raw,
-      "set",
-      SET_ARMS,
-      "the SessionState key to write",
-    ),
+  set: (ctx, path, raw) => valueSourceAction(ctx, path, raw, "set", SET_ARMS),
   persist: (ctx, path, raw) =>
-    valueSourceAction(
-      ctx,
-      path,
-      raw,
-      "persist",
-      PERSIST_ARMS,
-      "the config globals field to write",
-    ),
+    valueSourceAction(ctx, path, raw, "persist", PERSIST_ARMS),
   copy: templateArm("copy"),
   open: templateArm("open"),
   reset: resetArm,
@@ -169,6 +165,7 @@ function actionDeclJson(): JsonNode {
     anyOf: [
       ...SET_ARMS.map((arm) => arm.json),
       ...PERSIST_ARMS.map((arm) => arm.json),
+      ...DUAL_ARMS.map((arm) => arm.json),
       templateArmJson("copy"),
       templateArmJson("open"),
       templateArmJson("reset"),
@@ -305,37 +302,100 @@ function slashFreeString(
   return v;
 }
 
-// [LAW:dataflow-not-control-flow] The discriminator key ("set" or "persist")
-// is validated once for every value source (it is shared across all arms of
-// that discriminator), before the source is detected — so a bad key and an
-// ambiguous source both surface in one pass. It is therefore NOT a field of
+// [LAW:types-are-the-program] Which KEYS a value-source action carries beside
+// its value source, as data — one for a single-destination `set`/`persist`,
+// three for a `dual` (both destination keys plus the selector naming which is
+// written). Every consumer below (the key validation, the unknown-key
+// allow-list, the emitted JSON schema, the reconstructed member) reads this
+// one table, so adding the dual arm never meant a second dispatcher: the
+// discriminator stopped being ONE key and became a LIST of them, and the
+// existing machinery folds over the list [LAW:dataflow-not-control-flow].
+type Discriminator = "set" | "persist" | "dual";
+
+const DISCRIMINATOR_KEYS: Readonly<
+  Record<Discriminator, ReadonlyArray<readonly [string, string]>>
+> = {
+  set: [["set", "the SessionState key to write"]],
+  persist: [["persist", "the config globals field to write"]],
+  dual: [
+    ["set", "the SessionState key written while persistWhen is off"],
+    ["persist", "the config globals field written while persistWhen is on"],
+    [
+      PERSIST_WHEN,
+      "the SessionState key whose boolean value chooses the destination",
+    ],
+  ],
+};
+
+// [LAW:dataflow-not-control-flow] The discriminator keys are validated once
+// for every value source (they are shared across all arms of that
+// discriminator), before the source is detected — so a bad key and an
+// ambiguous source both surface in one pass. They are therefore NOT fields of
 // any arm's `fields` map; the arm parses only the value-source payload, and
-// the dispatcher re-attaches the discriminator.
-function validateValueSourceKey(
+// the dispatcher re-attaches them.
+//
+// [LAW:no-silent-failure] Returns null when ANY key fails, after reporting
+// every one of them — the caller threads that null exactly as it threads a
+// failed payload, so a partly-valid dual never reconstructs into a member
+// missing a destination.
+function validateDiscriminatorKeys(
   ctx: ValidateCtx,
   path: string,
   raw: Record<string, unknown>,
-  discriminator: "set" | "persist",
-  keyNoun: string,
-): string | null {
-  return slashFreeString(
-    ctx,
-    path,
-    discriminator,
-    raw,
-    `${discriminator} key must be non-empty (${keyNoun})`,
-    (v) => `${discriminator} key "${v}" contains "/" — keys must be slash-free`,
-  );
+  discriminator: Discriminator,
+): Record<string, string> | null {
+  const out: Record<string, string> = {};
+  const keys = DISCRIMINATOR_KEYS[discriminator];
+  let ok = true;
+  for (const [key, noun] of keys) {
+    // [LAW:no-silent-failure] An ABSENT key gets the shape, not a type
+    // mismatch. A single-destination arm cannot reach this (its key is the
+    // discriminator that selected the arm), so this only ever fires on a dual
+    // that named one destination and not the other — where "persist must be a
+    // string, got undefined" describes the symptom and teaches nothing, and
+    // the author needs to be told the three keys travel together.
+    if (!(key in raw)) {
+      issue(
+        ctx,
+        path,
+        `${key} is required here (${noun}) — a dual-destination action declares ${keys
+          .map(([k]) => k)
+          .join(", ")} together, plus one value source`,
+      );
+      ok = false;
+      continue;
+    }
+    const value = slashFreeString(
+      ctx,
+      path,
+      key,
+      raw,
+      `${key} key must be non-empty (${noun})`,
+      (v) => `${key} key "${v}" contains "/" — keys must be slash-free`,
+    );
+    if (value === null) {
+      ok = false;
+      continue;
+    }
+    out[key] = value;
+  }
+  // [LAW:no-silent-failure] Every failing key is reported before returning, so
+  // an author who omits two of a dual's three keys sees both in one pass —
+  // matching every other multi-issue check in this file, and matching what the
+  // comment above promises.
+  return ok ? out : null;
 }
 
 // [LAW:one-source-of-truth] The wire verb name a discriminator's writes
 // travel over — `set-state` for `set` (SessionState), `set-config` for
-// `persist` (the config-overrides layer). Threaded into the shared field
-// specs below so their "cannot be delivered on the X wire" messages name
-// the wire the value actually crosses, and the field/value noun ("set
+// `persist` (the config-overrides layer), and BOTH for a dual, whose one
+// value crosses whichever wire the selector names. Threaded into the shared
+// field specs below so their "cannot be delivered on the X wire" messages
+// name the wire the value actually crosses, and the field/value noun ("set
 // value" / "persist value") names the actual action kind, not always `set`.
-function wireName(discriminator: "set" | "persist"): string {
-  return discriminator === "set" ? "set-state" : "set-config";
+function wireName(discriminator: Discriminator): string {
+  if (discriminator === "set") return "set-state";
+  return discriminator === "persist" ? "set-config" : "set-state/set-config";
 }
 
 // [LAW:types-are-the-program] Each value source's payload as a field map — the
@@ -366,6 +426,15 @@ const INT_FIELDS: FieldSpecMap<{ int: true }> = { int: intMarkerSpec() };
 const CYCLE_FIELDS_SET: FieldSpecMap<{ cycle: readonly string[] }> = {
   cycle: cycleSpec("set"),
 };
+const TO_FIELDS_DUAL: FieldSpecMap<{ to: string }> = {
+  to: setLiteralSpec("dual"),
+};
+const FROM_FIELDS_DUAL: FieldSpecMap<{ from: OptionDomain }> = {
+  from: fromSpec("dual"),
+};
+const CYCLE_FIELDS_DUAL: FieldSpecMap<{ cycle: readonly string[] }> = {
+  cycle: cycleSpec("dual"),
+};
 const CYCLE_FIELDS_PERSIST: FieldSpecMap<{ cycle: readonly string[] }> = {
   cycle: cycleSpec("persist"),
 };
@@ -466,13 +535,14 @@ interface ValueSourceArm {
 // discriminator (the field no sibling arm carries) here; omit it when the
 // field set already is disjoint from every sibling, as it is everywhere else.
 function valueSourceArm<P extends object>(
-  discriminator: "set" | "persist",
+  discriminator: Discriminator,
   fieldMap: FieldSpecMap<P>,
   checks: ReadonlyArray<Refinement<P>> = [],
   detectKeys?: readonly string[],
 ): ValueSourceArm {
   const fullKeys = Object.keys(fieldMap);
   const detect = detectKeys ?? fullKeys;
+  const keys = DISCRIMINATOR_KEYS[discriminator].map(([k]) => k);
   const inner: ArmParse<P> = (ctx, path, raw) =>
     fields(ctx, fieldMap, path, raw);
   const source = objectJson(fieldMap) as {
@@ -481,12 +551,15 @@ function valueSourceArm<P extends object>(
   };
   return {
     detect,
-    allowed: [discriminator, ...fullKeys],
+    allowed: [...keys, ...fullKeys],
     label: fullKeys.join("/"),
     json: {
       type: "object",
-      properties: { [discriminator]: { type: "string" }, ...source.properties },
-      required: [discriminator, ...(source.required ?? [])],
+      properties: {
+        ...Object.fromEntries(keys.map((k) => [k, { type: "string" }])),
+        ...source.properties,
+      },
+      required: [...keys, ...(source.required ?? [])],
       additionalProperties: false,
     },
     parse: (checks.length
@@ -531,12 +604,25 @@ const PERSIST_ARMS: readonly ValueSourceArm[] = [
   ),
 ];
 
+// [LAW:one-type-per-behavior] A dual declares any value source BOTH
+// destinations share — `set` minus `int` (a page cursor has no durable
+// meaning), which is also `persist` minus its structural-edit arms (those are
+// persist-only by design, so they have no destination to choose between).
+// The field maps are the SET ones with dual wording, so a dual's value obeys
+// exactly the shape a `set` and a `persist` of that source each obey.
+const DUAL_ARMS: readonly ValueSourceArm[] = [
+  valueSourceArm("dual", TO_FIELDS_DUAL),
+  valueSourceArm("dual", FROM_FIELDS_DUAL),
+  valueSourceArm("dual", BOUNDED_FIELDS, [minLessThanMax, byNonZero]),
+  valueSourceArm("dual", CYCLE_FIELDS_DUAL),
+];
+
 // [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[] {
+function valueSourceClauses(discriminator: Discriminator): 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)`,
@@ -555,7 +641,7 @@ function valueSourceClauses(discriminator: "set" | "persist"): string[] {
   return clauses;
 }
 
-function VALUE_SOURCE_MESSAGE(discriminator: "set" | "persist"): string {
+function VALUE_SOURCE_MESSAGE(discriminator: Discriminator): string {
   const clauses = valueSourceClauses(discriminator);
   const last = clauses[clauses.length - 1]!;
   const list =
@@ -576,17 +662,10 @@ function valueSourceAction(
   ctx: ValidateCtx,
   path: string,
   raw: Record<string, unknown>,
-  discriminator: "set" | "persist",
+  discriminator: Discriminator,
   arms: readonly ValueSourceArm[],
-  keyNoun: string,
 ): ActionDecl | null {
-  const stateKey = validateValueSourceKey(
-    ctx,
-    path,
-    raw,
-    discriminator,
-    keyNoun,
-  );
+  const keys = validateDiscriminatorKeys(ctx, path, raw, discriminator);
 
   const present = arms.filter((arm) => arm.detect.some((k) => k in raw));
   if (present.length !== 1) {
@@ -613,9 +692,9 @@ function valueSourceAction(
   }
 
   const payload = arm.parse(ctx, path, raw);
-  return stateKey === null || payload === null
+  return keys === null || payload === null
     ? null
-    : ({ [discriminator]: stateKey, ...payload } as unknown as ActionDecl);
+    : ({ ...keys, ...payload } as unknown as ActionDecl);
 }
 
 // [LAW:no-silent-fallbacks] A literal `to` and the discriminator key share
@@ -624,7 +703,7 @@ function valueSourceAction(
 // arm's, the shape is the shared enforcer's. Built once per discriminator
 // (see TO_FIELDS_SET/TO_FIELDS_PERSIST) so a `persist` action's message names
 // "persist value" and the set-config wire, never `set`'s wording.
-function setLiteralSpec(discriminator: "set" | "persist"): FieldSpec<string> {
+function setLiteralSpec(discriminator: Discriminator): FieldSpec<string> {
   const wire = wireName(discriminator);
   return {
     required: true,
@@ -654,7 +733,7 @@ function setLiteralSpec(discriminator: "set" | "persist"): FieldSpec<string> {
 // symmetric to how a layout node's segment ref or a `{{ action }}` ref
 // resolves post-merge. Built once per discriminator, same reason as
 // setLiteralSpec.
-function fromSpec(discriminator: "set" | "persist"): FieldSpec<OptionDomain> {
+function fromSpec(discriminator: Discriminator): FieldSpec<OptionDomain> {
   const wire = wireName(discriminator);
   return {
     required: true,
@@ -733,9 +812,7 @@ function fromSpec(discriminator: "set" | "persist"): FieldSpec<OptionDomain> {
 // duplicated member is ambiguous). Members double as the derived allow-list
 // gate, so a member this spec admits is a value the wire delivers, by
 // construction. Built once per discriminator, same reason as setLiteralSpec.
-function cycleSpec(
-  discriminator: "set" | "persist",
-): FieldSpec<readonly string[]> {
+function cycleSpec(discriminator: Discriminator): FieldSpec<readonly string[]> {
   const wire = wireName(discriminator);
   return {
     required: true,

package/src/config/loader/cross-ref.ts

@@ -19,6 +19,8 @@ import {
   actionBindsRedo,
   actionBindsReset,
   actionBindsSet,
+  actionIsDual,
+  PERSIST_WHEN,
   actionBindsUndo,
   type ActionDecl,
 } from "../action.js";
@@ -160,6 +162,30 @@ export function validateCrossReferences(
       });
     }
   }
+  // [LAW:no-silent-failure] A dual action's `persistWhen` must name a key some
+  // `state` variable declares. The structural pass proves only that it is a
+  // deliverable wire key; whether it RESOLVES is a cross-ref concern, exactly
+  // as `from`'s domain is above.
+  //
+  // Without this, a typo loads perfectly cleanly and then does nothing
+  // forever: compileDual falls back to the raw key name, activeDestination
+  // reads it, finds nothing, and `parseSessionBoolean` answers null — which
+  // means "session". So the checkbox the author wired to the real key flips a
+  // value no control reads, the destination never changes, and there is no
+  // error anywhere to explain why. A silently-permanent session write is the
+  // worst possible shape for this failure, since it looks exactly like
+  // working software.
+  for (const [name, a] of Object.entries(cfg.actions)) {
+    if (!actionIsDual(a)) continue;
+    const selector = a[PERSIST_WHEN];
+    if (!declaresStateKey(cfg, selector)) {
+      ctx.issues.push({
+        path: `actions.${name}.${PERSIST_WHEN}`,
+        message: `actions.${name} ${PERSIST_WHEN}: "${selector}" is not a declared state key — a dual action's selector must name a { kind: "state", key: "${selector}" } variable, or the destination can never change`,
+        line: findKeyLine(ctx.source, ["actions", name, PERSIST_WHEN]),
+      });
+    }
+  }
   // [LAW:no-silent-failure] A `persist`/`reset` target must name a REAL
   // Globals field OR a declared segment's `palette` (candybar-config-engine-
   // 71o.6 — `segments.<name>.palette`, parsed by the one shared authority in
@@ -537,17 +563,29 @@ function checkPresetRootOpsTarget(
   }
 }
 
+// [LAW:one-source-of-truth] Every `state` variable a config declares, in BOTH
+// scopes — global `variables` and each segment's own `vars`. A segment-local
+// state variable is fully legitimate: src/dsl/render.ts's stateKeyToVar
+// registers them (as `<segment>.<var>`) and it is the map a dual's selector is
+// resolved through at render, so a load-time check that scanned only the
+// global scope would reject configs that work.
+function stateVars(cfg: DslConfig): VariableDecl[] {
+  return [
+    ...Object.values(cfg.variables),
+    ...Object.values(cfg.segments).flatMap((seg) =>
+      Object.values(seg.vars ?? {}),
+    ),
+  ].filter((v) => v.kind === "state");
+}
+
 function hasStateKind(cfg: DslConfig): boolean {
-  for (const v of Object.values(cfg.variables)) {
-    if (v.kind === "state") return true;
-  }
-  for (const seg of Object.values(cfg.segments)) {
-    if (!seg.vars) continue;
-    for (const v of Object.values(seg.vars)) {
-      if (v.kind === "state") return true;
-    }
-  }
-  return false;
+  return stateVars(cfg).length > 0;
+}
+
+// Does any declared `state` variable hold this key? The question a dual's
+// `persistWhen` selector has to answer, asked over the same two scopes.
+function declaresStateKey(cfg: DslConfig, key: string): boolean {
+  return stateVars(cfg).some((v) => v.kind === "state" && v.key === key);
 }
 
 // [LAW:dataflow-not-control-flow] A config emits a set-state, set-config,

package/src/config/loader/globals.ts

@@ -7,6 +7,8 @@ import { type Globals } from "../dsl-types.js";
 import {
   CHARSETS,
   COLOR_COMPATIBILITIES,
+  DEFAULT_PADDING,
+  PADDING_RANGE,
   STRIP_STYLES,
   type ColorCompatibility,
 } from "../../themes/policy.js";
@@ -84,7 +86,11 @@ const GLOBALS_FIELDS: FieldSpecMap<Globals> = {
   // drive an unbounded `" ".repeat` allocation in the daemon
   // [LAW:no-silent-failure] — an absurd value is a loud load error, not a
   // silently-huge render.
-  padding: optionalIntSpec({ min: 0, max: 16 }),
+  // [LAW:one-source-of-truth] The bound comes from PADDING_RANGE, the same
+  // literal the bundled default's stepper actions bound clicks by and the
+  // session-half parse admits values from — so the file, the click, and the
+  // session pick cannot end up honouring three different ranges.
+  padding: optionalIntSpec(PADDING_RANGE),
   // [LAW:types-are-the-program] Closed enum like `style`: the joiner glyph
   // vocabularies pickJoiner can render — validates by membership, emits a
   // JSON-Schema `enum` from the same CHARSETS literal.
@@ -188,3 +194,42 @@ export function isGlobalsField(key: string): key is keyof Globals {
 export function listGlobalsFieldNames(): readonly string[] {
   return [...GLOBALS_FIELD_NAMES];
 }
+
+// [LAW:types-are-the-program] Every NUMERIC globals field with the value that
+// renders when a config declares none, typed TOTAL over those fields — so
+// adding a numeric globals field without a floor is a COMPILE error, not a
+// silent seed-from-`min` (the bug this table exists to prevent, recurring for
+// the new field). It lives here rather than beside DEFAULT_PADDING in
+// themes/policy.ts because it must name `Globals`, and policy.ts is the leaf
+// dsl-types imports FROM — a table that needs both belongs on this side of
+// that edge [LAW:one-way-deps].
+// The direction matters: `NonNullable<Globals[K]> extends number` asks "is this
+// field's type a number", which is what the totality claim needs. The mirror
+// (`number extends …`) happens to agree for a field declared as plain `number`
+// — the two are symmetric there — but silently drops a field typed as a
+// literal union (`zoom?: 1 | 2 | 3`), which is a perfectly ordinary way to
+// declare a bounded numeric setting and exactly the case this guard exists for.
+type NumericGlobalsField = {
+  [K in keyof Globals]-?: NonNullable<Globals[K]> extends number ? K : never;
+}[keyof Globals];
+
+const NUMERIC_GLOBALS_FLOORS: Readonly<Record<NumericGlobalsField, number>> = {
+  padding: DEFAULT_PADDING,
+};
+
+// [LAW:single-enforcer] THE seed for a bounded stepper over a globals field:
+// what the bar renders with no write of any kind — the config's own value, or
+// the field's floor when it declares none. Both write gates read it (the
+// SessionState one through stateKeySeeds, the config-overrides one through
+// configKeySeeds), so a session stepper and its durable twin can never start
+// from different numbers, and neither can silently start from `min`.
+export function numericGlobalsSeeds(
+  globals: Globals,
+): ReadonlyMap<string, number> {
+  const seeds = new Map<string, number>();
+  for (const [field, floor] of Object.entries(NUMERIC_GLOBALS_FLOORS)) {
+    const declared = globals[field as keyof Globals];
+    seeds.set(field, typeof declared === "number" ? declared : floor);
+  }
+  return seeds;
+}

package/src/config/presets.ts

@@ -168,9 +168,14 @@ export function presetGlobals(config: DslConfig, name: string): Globals {
 // that is a typo in a file the author can see and fix — but a value that
 // only exists because the overrides layer supplied it gets the SAME
 // treatment a stale SessionState pick already gets from effectivePresetName:
-// collapse to the floor, visibly, never throw. Dropping the field here (so
-// it never reaches validateConfig) is what makes that collapse happen for
-// this layer too, instead of a fatal error replacing the whole bar.
+// an undeclared name is not a pick at all, so the resolution moves on to the
+// next rung of the precedence chain — visibly, never a throw. (For a stale
+// SESSION pick that next rung is the config's own `globals.preset`, and only
+// then the floor; for the field dropped here it is whatever the config file
+// itself declares. Same rule, different starting rung —
+// see effectiveGlobal in themes/policy.ts.) Dropping the field here (so it
+// never reaches validateConfig) is what applies that rule to this layer too,
+// instead of a fatal error replacing the whole bar.
 export function sanitizePersistedPresetOverride(
   globalsOverride: Partial<Globals>,
   declaredPresets: Readonly<Record<string, PresetDecl>>,