@promptctl/cc-candybar 1.18.0 → 1.19.0

package/src/config/loader/menu-synth.ts

@@ -3,80 +3,140 @@
 // trigger living inside an arbitrary user segment rather than a synthesized
 // toggle segment — so this emits exactly what group sugar does MINUS the segment
 // (the helper IS the trigger): one `state` var per menu state key (default
-// "closed") and one `cycle` action per (state key, member) under the reserved
-// `menus.` namespace. Both land in the raw sections so they merge over the
-// default and, crucially, so `deriveActionValidators(config.actions)` derives the
-// click gate from them through the ONE existing path — a menu toggle is gated
+// "closed"), one `cycle` action per (state key, member), AND — bn5.6 — the
+// picker body's page cursor (a `state` var + int action named by menuPageKey)
+// per state key, all under the reserved `menus.` namespace. Everything lands in
+// the raw sections so it merges over the default and, crucially, so
+// `deriveActionValidators(config.actions)` derives the click gates from them
+// through the ONE existing path — a menu toggle and its page cursor are gated
 // like every other set, no parallel verb. [LAW:single-enforcer]
 //
 // Runs in `parseDslConfig` after group synthesis and after every section parsed,
 // so the reserved-namespace collision check sees the fully-parsed user sections.
 //
 // [LAW:types-are-the-program] WHICH segments host a menu, and with WHAT apply
-// action + optional shared key, is read from the parsed AST (`referencedCalls`),
-// not a source-text scan — robust against whitespace, pipelines, and
-// `.menu`/"menu" lookalikes, and it yields each call's literal string arguments
-// so a menu's identity (member = apply name; key = optional shared key) is the
-// SAME fact the render helper reads from those same argument positions. A parse
-// failure here is treated as "no menu" because the authoritative parse error is
-// surfaced loudly by `registerDslConfig` when it compiles the same template (so
-// this pass never swallows a real error, it just declines to guess).
+// action + options, is read from the parsed AST (`referencedCalls` → `argExprs`
+// + `staticDictEntries`), not a source-text scan — robust against whitespace,
+// pipelines, and `.menu`/"menu" lookalikes, and it yields each call's literal
+// apply name and literal `(dict …)` options so a menu's identity (member =
+// apply name; key = the optional "key" option) is the SAME fact the render
+// helper reads from those same arguments. A parse failure here is treated as
+// "no menu" because the authoritative parse error is surfaced loudly by
+// `registerDslConfig` when it compiles the same template (so this pass never
+// swallows a real error, it just declines to guess).
 
-import { createEngine } from "@promptctl/go-template-js";
+import {
+  createEngine,
+  staticDictEntries,
+  type ReferencedCall,
+} from "@promptctl/go-template-js";
 import type { ActionDecl } from "../action.js";
 import type { Mutable, ValidateCtx } from "./validate-core.js";
 import {
-  MENU_CLOSED,
   MENU_NS,
   menuActionName,
   menuMember,
+  menuPageKey,
   menuStateKey,
+  parseMenuOptions,
+  type MenuOptions,
 } from "../menu-keys.js";
+import {
+  DISCLOSURE_CLOSED,
+  disclosureCycleAction,
+  disclosureStateVar,
+} from "../disclosure.js";
 import {
   walkNodes,
   type RawDslConfig,
   type VariableDecl,
 } from "../dsl-types.js";
 import { findKeyLine } from "./diagnostics.js";
+import { reservedNamespaceCollisions } from "./reserved-namespace.js";
 
 // [LAW:single-enforcer] The helper-name a `{{ menu … }}` call uses — the same
 // string the render FuncMap registers. A segment "hosts a menu" iff its template
 // references this function.
 const MENU_FUNC = "menu";
 
-// [LAW:types-are-the-program] The `{{ menu }}` argument positions, mirroring the
-// render helper's signature `menu apply page closeOnPick paged key`. Only the
-// apply name (identity member) and the optional shared key (accordion grouping)
-// affect synthesis; page/closeOnPick/paged are render-only and ignored here.
-const ARG_APPLY = 0;
-const ARG_KEY = 4;
+// [LAW:types-are-the-program] The `{{ menu }}` surface, mirroring the render
+// helper's signature `menu "apply" [(dict …)]`: the apply name (identity member,
+// a required string literal) and ONE optional trailing options dict —
+// closeOnPick / paged / key, all statically readable via `staticDictEntries`.
+// The removed positional tail (page-action string, bare bools, 5th-arg key) is
+// detected and rejected with a migration-pointing error, never silently
+// reinterpreted [LAW:no-silent-failure].
+const MIGRATION = `the positional tail ("pageAction" closeOnPick paged "key") was removed: the page cursor is now synthesized from the menu's identity, and rare knobs are named options in ONE trailing dict — write {{ menu "applyTheme" }} or {{ menu "applyTheme" (dict "closeOnPick" true "paged" false "key" "pickers") }} (defaults: closeOnPick false, paged true, no key)`;
+
+// [LAW:dataflow-not-control-flow] One total analysis of a `{{ menu }}` call site:
+// every reachable argument shape lands in exactly one arm — a usable identity
+// (apply + parsed options) or one load-error message (the tail after
+// `segment "<name>" has a {{ menu }} `). No shape falls through to render time.
+type MenuAnalysis =
+  | {
+      readonly kind: "ok";
+      readonly apply: string;
+      readonly options: MenuOptions;
+    }
+  | { readonly kind: "issue"; readonly message: string };
 
-// [LAW:types-are-the-program] One menu call's identity-bearing arguments. Each
-// arg has three states the synthesis must tell apart: a literal string (usable),
-// `null` (a slot present but non-literal — its value is eval-time, so it cannot
-// be gated at load → author error), and `undefined` (the slot was omitted). The
-// apply slot is required; the key slot is optional (undefined ⇒ independent menu).
-interface MenuCall {
-  readonly apply: string | null;
-  readonly key: string | null | undefined;
+function analyzeMenuCall(call: ReferencedCall): MenuAnalysis {
+  const issue = (message: string): MenuAnalysis => ({ kind: "issue", message });
+  const [applyArg, optsArg] = call.argExprs;
+  if (applyArg === undefined) {
+    return issue(
+      `with no arguments — it takes an apply-action name (e.g. {{ menu "applyTheme" }})`,
+    );
+  }
+  if (call.argExprs.length > 2) {
+    return issue(`with more than two arguments — ${MIGRATION}`);
+  }
+  if (applyArg.kind !== "literal" || typeof applyArg.value !== "string") {
+    return issue(
+      `whose apply action is not a string literal — a menu's identity is its apply-action name, which must be a literal so it can be gated at load (e.g. {{ menu "applyTheme" }})`,
+    );
+  }
+  if (
+    optsArg !== undefined &&
+    (optsArg.kind !== "call" || optsArg.name !== "dict")
+  ) {
+    // A literal (the old page-action string / positional bool), a dynamic value,
+    // or a non-dict call: none is an options dict — one migration error covers
+    // the whole family [LAW:one-type-per-behavior].
+    return issue(
+      `whose second argument is not an options (dict …) — ${MIGRATION}`,
+    );
+  }
+  const entries = optsArg === undefined ? {} : staticDictEntries(optsArg);
+  if (entries === null) {
+    return issue(
+      `whose options (dict …) is not fully literal — every option value must be a literal so the menu can be gated at load (a dynamic entry like (dict "key" .x) cannot)`,
+    );
+  }
+  try {
+    return {
+      kind: "ok",
+      apply: applyArg.value,
+      options: parseMenuOptions(entries),
+    };
+  } catch (e) {
+    return issue(`with invalid options — ${(e as Error).message}`);
+  }
 }
 
 // [LAW:no-defensive-null-guards] A bare engine purely for AST introspection: it
 // never evaluates, so `fromString` is identity and no funcs are registered (parse
 // does not resolve function existence — that is an eval-time concern).
-function parseCalls(template: string): readonly MenuCall[] | "parse-failed" {
+function parseCalls(
+  template: string,
+): readonly MenuAnalysis[] | "parse-failed" {
   const engine = createEngine<string>({ fromString: (s) => s });
   try {
     return engine
       .parse(template)
       .referencedCalls()
       .filter((c) => c.name === MENU_FUNC)
-      .map((c) => ({
-        apply: c.args[ARG_APPLY] ?? null,
-        // `referencedCalls` reports an omitted positional slot as absent and a
-        // present non-literal as null; preserve that distinction.
-        key: c.args.length > ARG_KEY ? c.args[ARG_KEY] : undefined,
-      }));
+      .map(analyzeMenuCall);
   } catch {
     // A malformed template can host no usable menu; registerDslConfig re-parses
     // and reports the real error. [LAW:no-silent-failure] — not swallowed, just
@@ -106,18 +166,9 @@ export function synthesizeMenuDecls(
   // user name under it is rejected whether or not any menu is placed this load, so
   // the reservation is a stable contract ("you never author menus.*"), not a rule
   // that only switches on when synthesis happens to collide. Runs before any early
-  // return so a `menus.*` user name can never load silently.
-  for (const section of ["variables", "actions", "segments"] as const) {
-    for (const name of Object.keys(out[section] ?? {})) {
-      if (name.startsWith(MENU_NS)) {
-        menuIssue(
-          ctx,
-          `${section}.${name}`,
-          `"${name}" is in the reserved "${MENU_NS}" namespace (synthesized by {{ menu }} helpers) — rename it`,
-        );
-      }
-    }
-  }
+  // return so a `menus.*` user name can never load silently. The check is the
+  // disclosure primitive's shared enforcer (mirroring group sugar's `groups.`).
+  reservedNamespaceCollisions(ctx, out, MENU_NS, "{{ menu }} helpers");
 
   // [LAW:no-silent-failure] A menu derives its identity from the SEGMENT it sits
   // in (the published segment name) plus its own apply arg; a `{{ define }}`
@@ -196,9 +247,10 @@ export function synthesizeMenuDecls(
   }
 
   // One state var per state key (default "closed"); one cycle action per
-  // (stateKey, member). [LAW:dataflow-not-control-flow] Independent menus each
-  // contribute their own key; shared-key menus contribute distinct members to one
-  // key, and the same-key validator merge unions them into one accordion gate.
+  // (stateKey, member); one page-cursor var + int action per state key.
+  // [LAW:dataflow-not-control-flow] Independent menus each contribute their own
+  // key; shared-key menus contribute distinct members to one key, and the
+  // same-key validator merge unions them into one accordion gate.
   const stateKeys = new Set<string>();
   const actions: Record<string, ActionDecl> = {};
   // Guard against two menus claiming one identity (same key + same member): for
@@ -206,53 +258,42 @@ export function synthesizeMenuDecls(
   // segment; for shared-key menus it means two menus with the same apply name
   // sharing a key — neither can be addressed distinctly, so reject.
   const claimed = new Set<string>();
-  // [LAW:types-are-the-program] The state key is `ident()`-normalized so it carries
-  // no separators; that normalization is lossy (`a-b` and `a_b` collapse), so two
-  // DISTINCT declarations could map to one key and silently share open-state (an
-  // unintended accordion). Track the raw "owner" each key legitimately belongs to
-  // — a shared key is owned by its raw key string (every sibling agrees); an
-  // independent menu by its raw (segment, apply). A second owner on the same key
-  // is a normalization collision, rejected at load so it is unrepresentable
-  // [LAW:no-silent-failure] rather than corrupting grouping.
-  const ownerByStateKey = new Map<string, string>();
+  // [LAW:types-are-the-program] A synthesized key is `ident()`-normalized so it
+  // carries no separators; that normalization is lossy (`a-b` and `a_b`
+  // collapse), so two DISTINCT declarations could map to one key and silently
+  // share state (an unintended accordion). Track the raw "owner" each
+  // synthesized name (state key AND its derived page key) legitimately belongs
+  // to — a shared key is owned by its raw key string (every sibling agrees); an
+  // independent menu by its raw (segment, apply). A second owner on the same
+  // name is a collision, rejected at load so it is unrepresentable
+  // [LAW:no-silent-failure] rather than corrupting grouping. Registering the
+  // page key too closes the cross-shape aliasing corner (e.g. an apply action
+  // named "page" in segment "s" vs the page cursor of a shared key "s").
+  const ownerBySynthKey = new Map<string, string>();
 
   for (const [segName, seg] of Object.entries(segments)) {
     if (!segmentReferencesMenu(seg.template)) continue;
     const calls = parseCalls(seg.template);
     if (calls === "parse-failed") continue;
     for (const call of calls) {
-      if (call.apply === null) {
-        menuIssue(
-          ctx,
-          `segments.${segName}`,
-          `segment "${segName}" has a {{ menu }} whose apply action is not a string literal — a menu's identity is its apply-action name, which must be a literal so it can be gated at load (e.g. {{ menu "applyTheme" "themePage" }}).`,
-        );
-        continue;
-      }
-      if (call.key === null) {
+      // [LAW:no-silent-failure] Every non-ok argument shape (missing apply,
+      // non-literal apply, the removed positional tail, a non-literal or
+      // malformed options dict) surfaces here as one load error with the
+      // analysis's migration-pointing text.
+      if (call.kind === "issue") {
         menuIssue(
           ctx,
           `segments.${segName}`,
-          `segment "${segName}" has a {{ menu }} whose accordion key is not a string literal — a shared key must be a literal so the mutually-exclusive group can be gated at load (e.g. {{ menu "applyTheme" "themePage" false false "pickers" }}).`,
-        );
-        continue;
-      }
-      // [LAW:types-are-the-program] An empty shared key collapses the state key to
-      // the bare reserved `menus.` namespace (and a `menus..member` action name).
-      // Reject it — a shared key, when present, must name a group.
-      if (call.key === "") {
-        menuIssue(
-          ctx,
-          `segments.${segName}`,
-          `segment "${segName}" has a {{ menu }} with an empty accordion key — a shared key must be a non-empty name (or omit it for an independent menu).`,
+          `segment "${segName}" has a {{ menu }} ${call.message}.`,
         );
         continue;
       }
+      const { apply, options } = call;
       // [LAW:types-are-the-program] An empty apply name → empty member, and the
       // store returns "" for an absent state key, so `open = read === member`
       // would be true before any click — the menu would render open spuriously.
       // Reject it (the member must never alias the absent-state sentinel).
-      if (call.apply === "") {
+      if (apply === "") {
         menuIssue(
           ctx,
           `segments.${segName}`,
@@ -260,56 +301,62 @@ export function synthesizeMenuDecls(
         );
         continue;
       }
-      const member = menuMember(call.apply);
+      const member = menuMember(apply);
       // [LAW:types-are-the-program] A member equal to the closed sentinel makes
       // the cycle [closed, "closed"] — two identical members, leaving the menu
       // unopenable. The only apply name that breaks a menu; reject it at load.
-      if (member === MENU_CLOSED) {
+      if (member === DISCLOSURE_CLOSED) {
         menuIssue(
           ctx,
           `segments.${segName}`,
-          `segment "${segName}" has a {{ menu }} whose apply action is named "${MENU_CLOSED}", which collides with the menu's closed-state sentinel and leaves it unopenable. Rename the action.`,
+          `segment "${segName}" has a {{ menu }} whose apply action is named "${DISCLOSURE_CLOSED}", which collides with the menu's closed-state sentinel and leaves it unopenable. Rename the action.`,
         );
         continue;
       }
-      const stateKey = menuStateKey(segName, call.apply, call.key);
-      // The raw declaration this key legitimately belongs to. Shared-key siblings
-      // all share one owner (their raw key); an independent menu owns its key alone
-      // (its raw segment+apply, NUL-joined so the two parts can't run together).
+      const stateKey = menuStateKey(segName, apply, options.key);
+      const pageKey = menuPageKey(stateKey);
+      // The raw declaration these keys legitimately belong to. Shared-key
+      // siblings all share one owner (their raw key); an independent menu owns
+      // its keys alone (its raw segment+apply, NUL-joined so the two parts
+      // can't run together).
       const owner =
-        call.key !== undefined
-          ? `key${call.key}`
-          : `ind${segName}${call.apply}`;
-      const priorOwner = ownerByStateKey.get(stateKey);
-      if (priorOwner !== undefined && priorOwner !== owner) {
+        options.key !== undefined
+          ? `key${options.key}`
+          : `ind${segName}${apply}`;
+      const clashKey = [stateKey, pageKey].find((k) => {
+        const prior = ownerBySynthKey.get(k);
+        return prior !== undefined && prior !== owner;
+      });
+      if (clashKey !== undefined) {
         menuIssue(
           ctx,
           `segments.${segName}`,
-          `two {{ menu }} disclosures normalize to the same state key ("${stateKey}") but were declared differently — distinct names that differ only by non-alphanumeric characters (e.g. "a-b" vs "a_b") collapse to one key and would silently share open-state. Rename so they don't collide.`,
+          `two {{ menu }} disclosures normalize to the same state key ("${clashKey}") but were declared differently — distinct names that differ only by non-alphanumeric characters (e.g. "a-b" vs "a_b") collapse to one key and would silently share open-state. Rename so they don't collide.`,
         );
         continue;
       }
-      ownerByStateKey.set(stateKey, owner);
+      ownerBySynthKey.set(stateKey, owner);
+      ownerBySynthKey.set(pageKey, owner);
       const identity = menuActionName(stateKey, member);
       if (claimed.has(identity)) {
         menuIssue(
           ctx,
           `segments.${segName}`,
           `two {{ menu }} disclosures resolve to the same identity ("${identity}") — ${
-            call.key !== undefined
-              ? `menus sharing key "${call.key}" must have distinct apply actions`
-              : `a segment cannot contain two menus over the same apply action "${call.apply}"`
+            options.key !== undefined
+              ? `menus sharing key "${options.key}" must have distinct apply actions`
+              : `a segment cannot contain two menus over the same apply action "${apply}"`
           }.`,
         );
         continue;
       }
       claimed.add(identity);
       stateKeys.add(stateKey);
-      // [LAW:one-source-of-truth] Members ordered closed-first: an unset/foreign
-      // value counts as the first member (the cycle's "unknown ⇒ first" rule), so
-      // a never-clicked menu renders ▸ and a click opens it; a shared key holding
-      // one member auto-closes its siblings.
-      actions[identity] = { set: stateKey, cycle: [MENU_CLOSED, member] };
+      // [LAW:one-source-of-truth] The shared disclosure toggle: members ordered
+      // closed-first (an unset/foreign value counts as the first member — the
+      // cycle's "unknown ⇒ first" rule — so a never-clicked menu renders ▸ and a
+      // click opens it; a shared key holding one member auto-closes its siblings).
+      actions[identity] = disclosureCycleAction(stateKey, member);
     }
   }
 
@@ -317,11 +364,19 @@ export function synthesizeMenuDecls(
 
   const variables: Record<string, VariableDecl> = {};
   for (const stateKey of stateKeys) {
-    variables[stateKey] = {
-      kind: "state",
-      key: stateKey,
-      default: MENU_CLOSED,
-    };
+    variables[stateKey] = disclosureStateVar(stateKey, DISCLOSURE_CLOSED);
+    // [LAW:one-source-of-truth] The synthesized page cursor — the half a blind
+    // author used to hand-declare and forget, silently freezing the picker on
+    // page 0 (renderPicker read an unbound key as "" → clamp 0). Both halves
+    // are emitted together, named by menuPageKey, so the pairing is a
+    // construction, not a convention: the state VAR (named by the key, the
+    // disclosure-var convention) is what the renderer reads the live page
+    // through; the int ACTION is what deriveActionValidators derives the ←/→/✕
+    // wire gate from — the one existing path, no parallel gate
+    // [LAW:single-enforcer].
+    const pageKey = menuPageKey(stateKey);
+    variables[pageKey] = { kind: "state", key: pageKey, default: "0" };
+    actions[pageKey] = { set: pageKey, int: true };
   }
 
   out.variables = { ...(out.variables ?? {}), ...variables };

package/src/config/loader/refs.ts

@@ -55,15 +55,15 @@ export function extractActionRefs(template: string): Set<string> {
 }
 
 // [LAW:dataflow-not-control-flow] Extract the action names a `picker` OR `menu`
-// call references — both bind the SAME (apply, page) action pair as their FIRST
-// TWO string-literal args (`{{ picker "applyTheme" "themePage" true true }}`,
-// `{{ menu "applyTheme" "themePage" false true "key" }}`). A menu's body IS a
-// picker, so the existence check on those two refs is identical; one extractor
-// arms on either keyword [LAW:single-enforcer]. Same code/string-span walk as
-// extractActionRefs; the keyword arms the next literal as the apply name and the
-// one after as the page name (trailing bools/the menu key are captured only if
-// they fall in the first two literal slots, which they never do).
-const PICKER_OR_MENU_ARG_RE = /\b(?:picker|menu)\s+$/;
+// call references, for the load-time existence check. A `picker` binds an
+// (apply, page) action pair as its first two string-literal args
+// (`{{ picker "applyTheme" "themePage" true true }}`); a `menu` binds ONLY its
+// apply action (`{{ menu "applyTheme" (dict …) }}`) — its page cursor is
+// synthesized from identity, and the dict's option-name literals must never be
+// misread as action refs. A menu's body IS a picker, so the existence check is
+// identical; one extractor arms on either keyword with the keyword's own arg
+// count [LAW:single-enforcer]. Same code/string-span walk as extractActionRefs.
+const PICKER_OR_MENU_ARG_RE = /\b(picker|menu)\s+$/;
 export function extractPickerMenuRefs(template: string): Set<string> {
   const refs = new Set<string>();
   TEMPLATE_BLOCK_RE.lastIndex = 0;
@@ -75,7 +75,8 @@ export function extractPickerMenuRefs(template: string): Set<string> {
     let s: RegExpExecArray | null;
     STRING_LITERAL_RE.lastIndex = 0;
     while ((s = STRING_LITERAL_RE.exec(block)) !== null) {
-      if (PICKER_OR_MENU_ARG_RE.test(block.slice(cursor, s.index))) pending = 2;
+      const kw = PICKER_OR_MENU_ARG_RE.exec(block.slice(cursor, s.index));
+      if (kw !== null) pending = kw[1] === "picker" ? 2 : 1;
       if (pending > 0) {
         refs.add(s[0].slice(1, -1));
         pending--;

package/src/config/loader/reserved-namespace.ts

@@ -0,0 +1,38 @@
+// [LAW:one-source-of-truth] The loader-side half of the disclosure primitive
+// (src/config/disclosure.ts): the ONE reserved-namespace collision check both
+// synthesis passes run. Group sugar reserves `groups.` and the `{{ menu }}`
+// helper reserves `menus.`; each synthesizes its `state` var, `cycle` action, and
+// (for a group) a toggle segment under its prefix, so a user-authored name under
+// that prefix must be a loud load error — never a silent overwrite of a
+// synthesized artifact. The check was duplicated verbatim in both passes; it lives
+// here now, parameterized by the prefix and a human description of what
+// synthesizes it, so the two body-kinds share one enforcer [LAW:single-enforcer].
+
+import type { Mutable, ValidateCtx } from "./validate-core.js";
+import type { RawDslConfig } from "../dsl-types.js";
+import { findKeyLine } from "./diagnostics.js";
+
+// [LAW:no-silent-failure] Reject every user name under the reserved prefix across
+// all three declaration sections (a synthesized disclosure lands in each), before
+// synthesis writes into them — so a `groups.*`/`menus.*` squatter surfaces as a
+// rename-pointing error rather than being silently shadowed. `synthesizedBy`
+// names the feature in the message (e.g. "group nodes", "{{ menu }} helpers") so
+// the author knows which sugar owns the prefix.
+export function reservedNamespaceCollisions(
+  ctx: ValidateCtx,
+  out: Mutable<RawDslConfig>,
+  ns: string,
+  synthesizedBy: string,
+): void {
+  for (const section of ["variables", "actions", "segments"] as const) {
+    for (const name of Object.keys(out[section] ?? {})) {
+      if (name.startsWith(ns)) {
+        ctx.issues.push({
+          path: `${section}.${name}`,
+          message: `"${name}" is in the reserved "${ns}" namespace (synthesized by ${synthesizedBy}) — rename it`,
+          line: findKeyLine(ctx.source, ["root"]),
+        });
+      }
+    }
+  }
+}

package/src/config/menu-keys.ts

@@ -28,17 +28,11 @@
 // can never silently collide.
 export const MENU_NS = "menus.";
 
-// The "no menu open" sentinel a key starts from and returns to on close. A
-// menu's member name is its apply-action name; an apply action named exactly
-// this would make the cycle [closed, "closed"] (two identical members, never
-// openable), which the synthesis pass rejects.
-export const MENU_CLOSED = "closed";
-
-// [LAW:representation] Disclosure glyph vocabulary — identical to group sugar so
-// every disclosure across the bar reads the same (trailing the label/content it
-// gates, per pdu.8): collapsed ▸, expanded ▾.
-export const MENU_GLYPH_CLOSED = "▸";
-export const MENU_GLYPH_OPEN = "▾";
+// [LAW:one-source-of-truth] The closed sentinel and the ▸/▾ glyphs are the shared
+// disclosure primitive, not menu-specific — they live in src/config/disclosure.ts
+// (DISCLOSURE_CLOSED / DISCLOSURE_GLYPH_*) so group sugar and {{ menu }} cannot
+// drift. This module keeps only the menu's own IDENTITY derivation (member = apply
+// name; key = optional shared key), which group sugar derives differently.
 
 // [LAW:types-are-the-program] Collapse an arbitrary name to an identifier-shaped
 // id so the synthesized var/action/SessionState-key names carry no dots or
@@ -76,3 +70,76 @@ export function menuStateKey(
 export function menuActionName(stateKey: string, member: string): string {
   return stateKey + "." + member;
 }
+
+// [LAW:single-enforcer] THE page-cursor key a menu's picker body paginates by —
+// synthesized by the loader (state var + int action, both named by this key)
+// and derived again by the renderer, so neither side hand-declares or restates
+// it. One cursor PER DISCLOSURE STATE KEY, not per menu: a shared (accordion)
+// key holds at most one open member, so its one open body is the only body the
+// cursor can belong to — sharing is exact by construction, not an
+// approximation — and the disclosure toggle's page-0 reset re-seeds it on
+// every open. [LAW:one-source-of-truth] The synthesized state VARIABLE is
+// named by this same string (the disclosure-var convention), so the renderer
+// reads the live page via this one name.
+export function menuPageKey(stateKey: string): string {
+  return stateKey + ".page";
+}
+
+// [LAW:types-are-the-program] The `{{ menu }}` rare-knob options, spelled as ONE
+// trailing `(dict …)` argument. Defaults are the canonical path: paged=true (a
+// drop menu wants bounded height; a short domain paginates to one page and shows
+// no arrows anyway), closeOnPick=false (stay-open so options can be tried in a
+// row), key omitted (an independent menu).
+export interface MenuOptions {
+  readonly closeOnPick: boolean;
+  readonly paged: boolean;
+  readonly key: string | undefined;
+}
+
+// [LAW:one-source-of-truth] THE reader of a menu's options dict — the loader
+// folds it over `staticDictEntries` (gating identity at load) and the renderer
+// folds it over the evaluated dict object (realizing the body), so the option
+// vocabulary, value types, and defaults live exactly once. An unknown name or a
+// mistyped value throws with text naming the legal shape — the blind authoring
+// agent's teaching channel [LAW:no-silent-failure]; the loader attaches segment
+// context, the renderer surfaces it via composeWithDiagnostics.
+export function parseMenuOptions(
+  entries: Readonly<Record<string, unknown>>,
+): MenuOptions {
+  for (const name of Object.keys(entries)) {
+    if (name !== "closeOnPick" && name !== "paged" && name !== "key") {
+      throw new Error(
+        `unknown {{ menu }} option "${name}" — the options dict takes "closeOnPick" (bool, default false), "paged" (bool, default true), "key" (string, accordion grouping)`,
+      );
+    }
+  }
+  const bool = (name: "closeOnPick" | "paged", def: boolean): boolean => {
+    const v = entries[name];
+    if (v === undefined) return def;
+    if (typeof v !== "boolean") {
+      throw new Error(
+        `{{ menu }} option "${name}" must be a boolean, got ${JSON.stringify(v)} (e.g. (dict "${name}" ${String(!def)}))`,
+      );
+    }
+    return v;
+  };
+  const key = entries["key"];
+  if (key !== undefined && typeof key !== "string") {
+    throw new Error(
+      `{{ menu }} option "key" must be a string naming the accordion group, got ${JSON.stringify(key)}`,
+    );
+  }
+  // [LAW:types-are-the-program] An empty shared key would collapse the state key
+  // to the bare reserved `menus.` namespace (and a `menus..member` action name) —
+  // a key, when present, must name a group.
+  if (key === "") {
+    throw new Error(
+      `{{ menu }} has an empty accordion key — a shared key must be a non-empty name (or omit "key" for an independent menu)`,
+    );
+  }
+  return {
+    closeOnPick: bool("closeOnPick", false),
+    paged: bool("paged", true),
+    key,
+  };
+}

package/src/daemon/cache/watchers.ts

@@ -18,7 +18,11 @@ const defaultLogger: WatcherLogger = (_level, message) => debug(message);
 // (git cache, config cache, ...). Scattered watchers across modules would leak
 // FDs and miss cleanup at shutdown.
 
-const DEBOUNCE_MS = 50;
+// [LAW:one-source-of-truth] Exported: the invalidation-debounce floor is the
+// single source consumers derive from (e.g. the load harness's git-churn
+// interval must sit above it). Restating "50" anywhere else would let the two
+// drift silently.
+export const DEBOUNCE_MS = 50;
 const DEFAULT_MAX_WATCHERS = 128;
 
 // Absolute filesystem paths the consumer wants invalidation for.