@promptctl/cc-candybar 1.0.0

package/src/config/dsl-loader.ts

@@ -0,0 +1,265 @@
+// [LAW:one-type-per-behavior] Three primitives, three concerns:
+//
+//   parseDslConfig (text → RawDslConfig)
+//     JSON5 syntax + per-record structural validation. Rejects the removed
+//     `layout:` key and `kind:"cells"` node with migration-pointing errors.
+//     Throws ConfigError on syntax / structural problems.
+//
+//   mergeWithDefault (RawDslConfig + DslConfig → DslConfig)
+//     Cascade: shallow merge globals fields, by-name merge variables and
+//     segments, wholesale root replacement when present. Pure function.
+//
+//   validateConfig (DslConfig → ValidatedConfig)
+//     Cross-references + cycle detection on the merged shape. Sole producer
+//     of ValidatedConfig. Throws ConfigError on cross-ref / cycle problems.
+//
+// loadConfig (path|null → DslConfig) wires parse+merge for the daemon's
+// production path. validateConfig finishes the chain.
+//
+// [LAW:dataflow-not-control-flow] Validation passes accumulate issues into
+// a list; consumers see every problem at once (compiler-style).
+//
+// This file is the pipeline orchestrator + the public barrel. Each validation
+// concern lives in its own `loader/` module (split by change-reason); the
+// re-exports below keep the import surface stable for every consumer.
+
+import fs from "node:fs";
+import JSON5 from "json5";
+import {
+  type DslConfig,
+  type RawDslConfig,
+  type ValidatedConfig,
+} from "./dsl-types.js";
+import { DEFAULT_DSL_CONFIG } from "./default-dsl-config.js";
+import { listResolvablePaletteNames } from "../themes/policy.js";
+import {
+  ConfigError,
+  findKeyLine,
+  type ConfigIssue,
+} from "./loader/diagnostics.js";
+import {
+  describeType,
+  isPlainObject,
+  type Mutable,
+  type ValidateCtx,
+} from "./loader/validate-core.js";
+import { mergeWithDefault } from "./loader/merge.js";
+import { validateGlobals } from "./loader/globals.js";
+import { validateVariables } from "./loader/variables.js";
+import { validateSegments } from "./loader/segments.js";
+import { synthesizeGroupDecls, validateRoot } from "./loader/layout.js";
+import { validateActions } from "./loader/actions.js";
+import { validateHelpers } from "./loader/helpers.js";
+import { validateCrossReferences } from "./loader/cross-ref.js";
+import { validateNoCycles } from "./loader/cycles.js";
+
+// ─── Public barrel ───────────────────────────────────────────────────────────
+// [LAW:locality-or-seam] Consumers import from `dsl-loader`; the internal split
+// is invisible to them. Moving a symbol between loader/ modules never touches a
+// callsite as long as it stays re-exported here.
+
+export { ConfigError, findKeyLine } from "./loader/diagnostics.js";
+export type { ConfigIssue } from "./loader/diagnostics.js";
+export {
+  expandHome,
+  dslConfigCandidatePaths,
+  resolveDslConfigPath,
+  detectConfigCollisions,
+} from "./loader/discovery.js";
+export { mergeWithDefault } from "./loader/merge.js";
+export {
+  extractTemplateRefs,
+  extractActionRefs,
+  extractPickerRefs,
+} from "./loader/refs.js";
+
+// ─── Three-stage pipeline ────────────────────────────────────────────────────
+
+/**
+ * Load a JSON5 DSL config file from disk and merge it with the bundled
+ * default. Returns the effective DslConfig AND the raw source text.
+ *
+ * `path = null` means "no user file exists" — returns the default unchanged
+ * (uniform merge against an empty raw, which is deep-equal to the default) and
+ * an empty source. No consumer branches on file presence; that branch lives
+ * inside loadConfig exactly once.
+ *
+ * [LAW:one-source-of-truth] The source is returned alongside the config so the
+ * caller can hand it to validateConfig — cross-ref diagnostics (line numbers,
+ * the authored-surface discriminator) are derived from it, and the file is read
+ * exactly once here rather than re-read downstream.
+ *
+ * Throws ConfigError on JSON5 syntax / structural / per-record validation
+ * failures. Cross-references and cycles are validateConfig()'s job.
+ *
+ * [LAW:dataflow-not-control-flow] One function, one branch, same operations
+ * each call.
+ */
+export function loadConfig(
+  path: string | null,
+  dflt: DslConfig = DEFAULT_DSL_CONFIG,
+  allowedPalettes?: ReadonlySet<string>,
+): { config: DslConfig; source: string } {
+  const source = path === null ? "" : fs.readFileSync(path, "utf-8");
+  const raw: RawDslConfig =
+    path === null ? {} : parseDslConfig(path, source, allowedPalettes);
+  return { config: mergeWithDefault(raw, dflt), source };
+}
+
+/**
+ * Promote a merged DslConfig to a ValidatedConfig by running cross-references
+ * and cycle detection. Sole producer of ValidatedConfig in the codebase — the
+ * phantom brand makes "the renderer never receives an unvalidated config" a
+ * compile-time invariant, not a runtime convention.
+ *
+ * Throws ConfigError aggregating every issue.
+ *
+ * [LAW:single-enforcer] One cast site, here, exclusive.
+ */
+export function validateConfig(
+  config: DslConfig,
+  filePath = "<config>",
+  source = "",
+  allowedPalettes: ReadonlySet<string> = new Set(listResolvablePaletteNames()),
+): ValidatedConfig {
+  const issues: ConfigIssue[] = [];
+  const ctx: ValidateCtx = { source, issues, allowedPalettes, groups: [] };
+  validateCrossReferences(ctx, config);
+  validateNoCycles(ctx, config);
+  if (issues.length > 0) {
+    throw new ConfigError(filePath, issues);
+  }
+  return config as ValidatedConfig;
+}
+
+/**
+ * Parse a JSON5 DSL config source into a RawDslConfig. JSON5 syntax + per-
+ * record structural validation. Cross-references and cycles are NOT checked
+ * here — they belong to validateConfig, which runs on the merged shape.
+ *
+ * Returned shape preserves absence: top-level keys are optional in RawDslConfig.
+ *
+ * `allowedPalettes` is the set of palette names a `palette:` field may name.
+ * It defaults to every name that resolves to a concrete Palette, so production
+ * always validates loudly against the real registry. Tests inject a custom set
+ * to exercise validation without depending on registry contents.
+ */
+export function parseDslConfig(
+  filePath: string,
+  source: string,
+  allowedPalettes: ReadonlySet<string> = new Set(listResolvablePaletteNames()),
+): RawDslConfig {
+  // ── Stage 1: JSON5 syntax. A parse error here is single, immediate, and
+  // carries line/col from the json5 package — no point continuing to other
+  // passes that need a parsed structure to inspect.
+  const raw = parseJson5OrThrow(filePath, source);
+
+  const issues: ConfigIssue[] = [];
+  const ctx: ValidateCtx = { source, issues, allowedPalettes, groups: [] };
+
+  // ── Stage 2: top-level shape + per-record shape. Absence survives as
+  // `undefined` in the returned RawDslConfig.
+  if (!isPlainObject(raw)) {
+    throw new ConfigError(filePath, [
+      {
+        path: "",
+        message: `Config root must be an object, got ${describeType(raw)}`,
+      },
+    ]);
+  }
+
+  const topLevel = validateTopLevel(ctx, raw);
+
+  if (issues.length > 0) {
+    throw new ConfigError(filePath, issues);
+  }
+
+  return topLevel;
+}
+
+// ─── Internals ───────────────────────────────────────────────────────────────
+
+interface Json5Error extends Error {
+  lineNumber?: number;
+  columnNumber?: number;
+}
+
+function parseJson5OrThrow(filePath: string, source: string): unknown {
+  try {
+    return JSON5.parse(source);
+  } catch (err) {
+    const e = err as Json5Error;
+    throw new ConfigError(filePath, [
+      {
+        path: "",
+        message: `JSON5 syntax error: ${e.message}`,
+        line: e.lineNumber,
+        col: e.columnNumber,
+      },
+    ]);
+  }
+}
+
+// [LAW:types-are-the-program] Returns RawDslConfig — absence of a top-level
+// key survives the parse as `undefined`, distinct from explicit empty. The
+// merge step downstream decides what "absent" means policy-wise (currently:
+// inherit from default).
+function validateTopLevel(
+  ctx: ValidateCtx,
+  raw: Record<string, unknown>,
+): RawDslConfig {
+  for (const key of Object.keys(raw)) {
+    if (!TOP_LEVEL_KEYS.has(key)) {
+      ctx.issues.push({
+        path: key,
+        message: `Unknown top-level key "${key}". Expected one of: ${[...TOP_LEVEL_KEYS].join(", ")}`,
+        line: findKeyLine(ctx.source, [key]),
+      });
+    }
+  }
+
+  const out: Mutable<RawDslConfig> = {};
+  if (raw.globals !== undefined)
+    out.globals = validateGlobals(ctx, raw.globals);
+  if (raw.variables !== undefined)
+    out.variables = validateVariables(ctx, "variables", raw.variables);
+  if (raw.segments !== undefined)
+    out.segments = validateSegments(ctx, raw.segments);
+  // [LAW:no-silent-failure] `layout:` was removed in 2de.19. Reject loudly with
+  // a migration hint so the author knows exactly how to rewrite their config.
+  if (raw.layout !== undefined) {
+    ctx.issues.push({
+      path: "layout",
+      message:
+        `"layout" is no longer supported — use "root" with the A-grammar instead.\n` +
+        `  Replace:  layout: [["seg1", "seg2"], ["seg3"]]\n` +
+        `  With:     root: { v: [{ h: ["seg1", "seg2"] }, "seg3"] }\n` +
+        `  Single-row example:  root: { h: ["seg1", "seg2"] }`,
+      line: findKeyLine(ctx.source, ["layout"]),
+    });
+  }
+  if (raw.root !== undefined) out.root = validateRoot(ctx, "root", raw.root);
+  if (raw.actions !== undefined)
+    out.actions = validateActions(ctx, raw.actions);
+  if (raw.helpers !== undefined)
+    out.helpers = validateHelpers(ctx, raw.helpers);
+  // [LAW:one-source-of-truth] Group sugar synthesis runs AFTER every section
+  // parsed: each group collected during the root walk emits its state var +
+  // cycle action + toggle segment into the raw sections (so they merge over the
+  // default and cross-ref like any user declaration), and user names under the
+  // reserved namespace are rejected against the fully-parsed sections.
+  synthesizeGroupDecls(ctx, out);
+  return out;
+}
+
+// [LAW:no-silent-failure] `layout` is intentionally absent — a config that
+// writes it gets an explicit migration error, not an "unknown key" message.
+const TOP_LEVEL_KEYS = new Set([
+  "globals",
+  "variables",
+  "segments",
+  "layout",
+  "root",
+  "actions",
+  "helpers",
+]);

package/src/config/dsl-types.ts

@@ -0,0 +1,425 @@
+// [LAW:types-are-the-program] DslConfig is the strongest theorem we can write
+// about a validated config: every legal config is representable, every illegal
+// one is not. The loader is the proof — its body either narrows `unknown` to
+// `DslConfig` or throws ConfigError. Downstream consumers receive a DslConfig
+// and are free to assume invariants (closed source-kind set, exactly-one cache
+// key, no dangling cross-refs, no template cycles) without re-checking.
+//
+// [LAW:one-source-of-truth] These shapes are the JSON-shape mirror of the
+// var-system's runtime types (`CachePolicy`, `ShellOptions`, etc. in
+// src/var-system/sources.ts). The loader is the single point that translates
+// between the two; no other module should re-derive these shapes.
+
+// [LAW:one-way-deps] The action schema lives in its own leaf module; DslConfig
+// references it here. The dependency is one-way (this file → action.ts), never
+// the reverse, so that shape can be lifted out without a cycle.
+import type { ActionDecl } from "./action.js";
+
+// [LAW:types-are-the-program] Three stages, three names.
+//
+//   RawDslConfig    — the user-file shape. Every top-level key is optional
+//                     because "user didn't write this" is a representable,
+//                     distinct state from "user wrote an explicit empty."
+//                     Internal to the loader module; downstream consumers
+//                     never see it.
+//
+//   DslConfig       — the effective shape: the user's deltas merged on top
+//                     of DEFAULT_DSL_CONFIG. Every top-level key is required.
+//                     Output of `loadConfig`. Cross-refs and cycles have NOT
+//                     yet been checked at this stage.
+//
+//   ValidatedConfig — DslConfig + a phantom brand proving validateConfig()
+//                     has run. The renderer accepts only this type, so the
+//                     compiler structurally enforces "no unvalidated config
+//                     can reach rendering." The brand is module-scoped via
+//                     `unique symbol`, so the only construction site is
+//                     `validateConfig` itself.
+// [LAW:types-are-the-program] The recursive layout substrate collapses to
+// exactly two kinds: a `segment` leaf (a ref into the named `segments` block —
+// THE unit of rendering, a single template that IS its content) or a
+// `container` whose `direction` is DATA that decides how its children map onto
+// the 2D plane. Both the bar and (a later child's) menu are projections of this
+// one tree — they differ only in `direction`, not in code path
+// [LAW:dataflow-not-control-flow].
+//
+// [LAW:types-are-the-program] `Direction` carries the projection a container
+// applies to its child blocks as DATA. `vertical` STACKS them (concat the
+// children's line-lists); `horizontal` ZIPS them (per row, the children's cells
+// concatenate into one strip, so the powerline joiner caps ACROSS the seam —
+// abut is never valid). `outline` (a later child's menu) is NOT in the union
+// yet — it joins as a new arm only when its renderer exists, so the union stays
+// the strongest theorem that is still TRUE, with no representable-but-
+// unrenderable direction.
+// [LAW:one-source-of-truth] The runtime list and the type derive from one
+// declaration; the loader validates a container's `direction` against this set,
+// and renderDsl's projection switch is exhaustive over it (adding an arm here
+// forces a matching render arm).
+export const DIRECTIONS = ["vertical", "horizontal"] as const;
+export type Direction = (typeof DIRECTIONS)[number];
+
+// [LAW:one-type-per-behavior] THE unit of rendering: a ref into the named
+// `segments` block. A segment IS a single template (text, state-driven display,
+// clickable regions — whatever the template produces); there is no `inline` /
+// `stepper` / `picker` node kind, because "make a node flexible enough for
+// whatever" = one template expresses anything. A segment renders to ONE strip
+// item; the powerline joiner joins items, never inside one. A horizontal run of
+// segments is spelled `{ h: ["seg1", "seg2"] }` in the A-grammar.
+export interface SegmentNode {
+  readonly kind: "segment";
+  // A name into the `segments` block. The segment's own template/palette/`when`
+  // live on its SegmentDecl, not here; this node is purely the tree position.
+  readonly name: string;
+  // [LAW:dataflow-not-control-flow] Absent `when` ≡ always-rendered. A node-level
+  // predicate, ANDed with the segment-decl's own `when` at render.
+  readonly when?: string;
+}
+
+export interface ContainerNode {
+  readonly kind: "container";
+  readonly direction: Direction;
+  readonly children: readonly LayoutNode[];
+  // A container's `when` gates the whole subtree: a hidden container emits no
+  // lines, but its descendants are still walked so per-segment hue indices stay
+  // positionally stable.
+  readonly when?: string;
+}
+
+export type LayoutNode = ContainerNode | SegmentNode;
+
+// [LAW:types-are-the-program] The `group` SUGAR as collected at parse — an
+// INPUT-only shape, never a canonical LayoutNode kind: arranging + gating are
+// behaviors `container` already has, so "group" may only be a spelling. The
+// loader lowers each group to container/segment nodes and SYNTHESIZES its state
+// var + cycle action + toggle segment under the reserved `groups.` namespace
+// (one declaration; every derived artifact single-sourced from it
+// [LAW:one-source-of-truth]). `path` records the node's tree position so the
+// nesting invariant (an ancestor and a descendant must not share a state key)
+// is checkable after the walk.
+export interface GroupSugarDecl {
+  readonly name: string;
+  readonly label: string;
+  readonly open?: boolean;
+  readonly direction?: Direction;
+  readonly key?: string;
+  readonly bg?: string;
+  readonly fg?: string;
+  readonly when?: string;
+  readonly path: string;
+}
+
+// [LAW:single-enforcer] THE one pre-order walk over a node tree. Every consumer
+// that needs "which segments / which `when` predicates does this layout name"
+// (the reachability closure, the debug dump, the cross-ref validator) iterates
+// this — none re-recurses the tree itself.
+export function* walkNodes(node: LayoutNode): IterableIterator<LayoutNode> {
+  yield node;
+  if (node.kind === "container") {
+    for (const child of node.children) yield* walkNodes(child);
+  }
+}
+
+export interface RawDslConfig {
+  readonly globals?: Partial<Globals>;
+  readonly variables?: Readonly<Record<string, VariableDecl>>;
+  readonly segments?: Readonly<Record<string, SegmentDecl>>;
+  readonly root?: LayoutNode;
+  readonly actions?: Readonly<Record<string, ActionDecl>>;
+  // [LAW:single-enforcer] Config-level shared helper templates: name → Go-template
+  // body. Each compiles to one `{{ define "name" }}body{{ end }}` block, and the
+  // whole set into a single output-neutral preamble prepended to every template
+  // this config parses — so a formatter (`{{ template "formatCost" .x }}`) is
+  // defined ONCE and callable from any segment/predicate, never re-inlined per
+  // segment. Absent ≡ no helpers; merges by-name (user overrides a helper).
+  readonly helpers?: Readonly<Record<string, string>>;
+}
+
+export interface DslConfig {
+  readonly globals: Globals;
+  readonly variables: Readonly<Record<string, VariableDecl>>;
+  readonly segments: Readonly<Record<string, SegmentDecl>>;
+  // [LAW:one-source-of-truth] The SINGLE canonical layout representation authored
+  // via the A-grammar (seg/h/v node arms, group sugar). No legacy sugar reaches
+  // this field; the loader rejects `layout:` and `kind:"cells"` with migration errors.
+  readonly root: LayoutNode;
+  // [LAW:locality-or-seam] The named seam between click BEHAVIOR and the
+  // clickable REPRESENTATION. Each entry is a statically-declared effect a
+  // segment template binds a region to via `{{ action "name" … }}`. The
+  // writable-key gate derives from this table (deriveActionValidators), so a
+  // template cannot smuggle an un-gated write. Empty when no config declares
+  // actions — an absent `actions` key merges to `{}`.
+  readonly actions: Readonly<Record<string, ActionDecl>>;
+  // [LAW:single-enforcer] The effective helper set: a name → template-body map
+  // compiled to a defines-preamble at registerDslConfig. Empty when no config
+  // declares helpers — an absent `helpers` key merges to `{}` (same cascade as
+  // actions). The single definition site for each formatter/transform a template
+  // calls via `{{ template "name" .arg }}`.
+  readonly helpers: Readonly<Record<string, string>>;
+}
+
+// [LAW:single-enforcer] The brand symbol is `unique` and module-private —
+// nothing outside this file can construct a value carrying it. The only
+// production-path producer is validateConfig() in dsl-loader.ts (one
+// callsite of `config as ValidatedConfig`). Renderer signatures require
+// ValidatedConfig; the type system therefore proves the validation step
+// ran before any render path consumed the config.
+declare const __validated: unique symbol;
+export type ValidatedConfig = DslConfig & {
+  readonly [__validated]: true;
+};
+
+export interface Globals {
+  readonly default_bg?: string;
+  readonly default_fg?: string;
+  readonly default_empty_value?: string;
+  readonly default_separator?: string;
+  readonly default_truncate_marker?: string;
+  // [LAW:one-source-of-truth] A palette NAME, not a resolved Palette: DslConfig
+  // is the JSON-shape mirror, so the name is the authoritative datum and the
+  // renderer owns name→Palette resolution. The config default for the base
+  // theme; the daemon resolves the live base per render as
+  // `sessionState.theme ?? globals.palette ?? default`, and a per-segment
+  // `palette` is an explicit override that ignores the session theme.
+  readonly palette?: string;
+}
+
+// [LAW:one-type-per-behavior] One discriminated union covers every source
+// kind. Adding a new kind = code change here + matching runtime support in
+// var-system. There is no "extension" path that bypasses this list.
+export type VariableDecl =
+  | LiteralVarDecl
+  | InputVarDecl
+  | EnvVarDecl
+  | FileVarDecl
+  | ShellVarDecl
+  | TemplateVarDecl
+  | TimeVarDecl
+  | GitVarDecl
+  | StateVarDecl;
+
+export interface LiteralVarDecl {
+  readonly kind: "literal";
+  readonly value: string | number | boolean;
+  readonly default?: string;
+}
+
+// [LAW:types-are-the-program] `type` carries the runtime kind of the value at
+// the resolved payload path. Number/bool are needed for the usage/cost/today
+// family — token counts, cost amounts, percentages — whose formatters
+// (`formatCost`, `formatTokens`, `round`, `budgetStatus`) take numeric inputs.
+// Absent `type` defaults to "string" at the loader, preserving the historical
+// behavior of every existing declaration. The default value's literal type
+// must match the declared type — a number default on a string-typed input
+// (or vice versa) is rejected at load time, not at first render.
+export interface InputVarDecl {
+  readonly kind: "input";
+  readonly path: string;
+  readonly type?: "string" | "number" | "boolean";
+  readonly default?: string | number | boolean;
+}
+
+export interface EnvVarDecl {
+  readonly kind: "env";
+  readonly name: string;
+  readonly default?: string;
+}
+
+export interface FileVarDecl {
+  readonly kind: "file";
+  readonly path: string;
+  readonly readMode?: "whole" | "first-line";
+  readonly regex?: string;
+  readonly cache: CacheDecl;
+  readonly default?: string;
+}
+
+export interface ShellVarDecl {
+  readonly kind: "shell";
+  readonly command: string;
+  readonly regex?: string;
+  readonly cache: CacheDecl;
+  readonly default?: string;
+}
+
+export interface TemplateVarDecl {
+  readonly kind: "template";
+  readonly template: string;
+  readonly cache?: CacheDecl;
+  readonly default?: string;
+}
+
+// [LAW:types-are-the-program] Time vars refresh on a clock — ttl is the only
+// cache form the runtime honors (declareTime always registers a TTL timer).
+// The loader rejects the other CacheDecl arms at load, so past that boundary
+// a non-ttl cache on a time var is unrepresentable, not silently coerced.
+export interface TimeVarDecl {
+  readonly kind: "time";
+  readonly layout: string;
+  readonly cache?: TtlCacheDecl;
+  readonly default?: string;
+}
+
+export interface GitVarDecl {
+  readonly kind: "git";
+  readonly field: GitField;
+  readonly cache: CacheDecl;
+  readonly default?: string;
+}
+
+// [LAW:one-source-of-truth] A `state` variable reads through to the daemon's
+// SessionState (the canonical store for per-session toggles, random picks,
+// click-mutated values). Reactivity is wired by SessionState's internal MobX
+// atom — a click verb that writes into SessionState invalidates this
+// variable's downstream computeds automatically. Persistence rides for free
+// on SessionState's disk backing.
+//
+// The session id is resolved from the conventional `session.id` variable —
+// that name is the canonical anchor for "which session am I in," declared
+// once by DSL configs as an input variable carrying hook_data.session_id.
+// [LAW:no-mode-explosion] No per-decl override knob: a single canonical
+// session-id source keeps every state var's resolution uniform and removes
+// an axis along which configs could drift from each other.
+export interface StateVarDecl {
+  readonly kind: "state";
+  readonly key: string;
+  readonly default?: string;
+}
+
+export type GitField =
+  | "branch"
+  | "sha"
+  | "dirty"
+  | "ahead"
+  | "behind"
+  | "stash";
+
+// [LAW:dataflow-not-control-flow] The discriminator is "which key is present"
+// in the user's JSON — not a `kind` field. Encoded as a 5-arm union so the
+// type system enforces "exactly one of these." The loader validates the
+// runtime invariant (one and only one); the type then carries it forward.
+export type CacheDecl =
+  | TtlCacheDecl
+  | { readonly watch_file: string }
+  | { readonly depends_on: readonly string[] }
+  | { readonly key: string }
+  | { readonly never: true };
+
+// [LAW:one-source-of-truth] The ttl arm named once, so the kinds that honor
+// only a refresh interval (time) reference the same member the full vocabulary
+// is composed from — narrowing is a subset, never a parallel shape.
+export interface TtlCacheDecl {
+  readonly ttl: string;
+}
+
+export const CACHE_KEYS = [
+  "ttl",
+  "watch_file",
+  "depends_on",
+  "key",
+  "never",
+] as const;
+export type CacheKey = (typeof CACHE_KEYS)[number];
+
+export const SOURCE_KINDS = [
+  "literal",
+  "input",
+  "env",
+  "file",
+  "shell",
+  "template",
+  "time",
+  "git",
+  "state",
+] as const;
+export type SourceKind = (typeof SOURCE_KINDS)[number];
+
+// [LAW:one-source-of-truth] The "which kinds have a cache field" predicate
+// lives here once. The loader's cross-ref and cycle validators narrow via
+// this guard instead of repeating the kind list (`!== "literal" && !==
+// "input" && ...`) at every site — adding a new no-cache kind only requires
+// updating the union and this guard.
+export type VariableDeclWithCache =
+  | FileVarDecl
+  | ShellVarDecl
+  | TemplateVarDecl
+  | TimeVarDecl
+  | GitVarDecl;
+
+export function hasCacheField(v: VariableDecl): v is VariableDeclWithCache {
+  return (
+    v.kind !== "literal" &&
+    v.kind !== "input" &&
+    v.kind !== "env" &&
+    v.kind !== "state"
+  );
+}
+
+export const GIT_FIELDS: readonly GitField[] = [
+  "branch",
+  "sha",
+  "dirty",
+  "ahead",
+  "behind",
+  "stash",
+];
+
+// Source kinds where the user MUST declare a cache policy (no sensible default).
+// Aligns with the proposal's cache-invalidation table.
+export const SOURCES_REQUIRING_CACHE: readonly SourceKind[] = [
+  "file",
+  "shell",
+  "git",
+];
+
+export interface SegmentDecl {
+  readonly template: string;
+  readonly width?: "auto" | number;
+  readonly justify?: JustifyMode;
+  readonly truncate?: TruncateMode;
+  readonly bg?: string;
+  readonly fg?: string;
+  readonly when?: string;
+  // [LAW:one-source-of-truth] Per-segment palette override (a NAME). Overrides
+  // globals.palette for this segment only; undefined = inherit the cascade base.
+  readonly palette?: string;
+  // Per-segment vars sub-block — lives in the same global MobX store at
+  // runtime under the namespaced key `<segment>.<var>`. Templates reference a
+  // segment local ONLY via that namespaced form (`.<segment>.local`), from any
+  // segment including the owning one; the loader rejects bare refs at load
+  // with a diagnostic naming the namespaced form. [LAW:one-source-of-truth]
+  readonly vars?: Readonly<Record<string, VariableDecl>>;
+}
+
+export type JustifyMode = "left" | "center" | "right";
+export type TruncateMode = "right" | "left" | "middle";
+
+export const JUSTIFY_MODES: readonly JustifyMode[] = [
+  "left",
+  "center",
+  "right",
+];
+export const TRUNCATE_MODES: readonly TruncateMode[] = [
+  "right",
+  "left",
+  "middle",
+];
+
+// ─── Conventional render-time variable names ─────────────────────────────────
+//
+// [LAW:one-source-of-truth] These are not widget types (those live in
+// `./action.ts`); they are the conventional variable NAMES the renderer and the
+// picker agree on. Kept here, with the other render/config conventions.
+
+// [LAW:one-source-of-truth] The conventional variable a picker paginates against
+// — the usable terminal width renderDsl injects each render. One name shared by
+// the declaration (default config) and the picker's read, so they cannot drift.
+export const TERM_COLS_VAR = "term.cols";
+
+// [LAW:one-source-of-truth] The conventional variable per-segment hue rotation
+// reads. hueStep is NOT a globals field (that would be a second source for a
+// render-time value); it is a value in the store like every other render input.
+// A config declares this variable — as a `state` var so a stepper can drive it
+// live (session value over the declared default, the same session-over-default
+// the theme uses), or as any kind for a fixed value. renderDsl reads it through
+// this one name; a bounded stepper action writes the SessionState key it reads.
+// Absent ≡ no rotation (step 0) — the degenerate case, not a special branch.
+export const HUE_STEP_VAR = "hue.step";