@promptctl/cc-candybar 1.0.0

package/src/config/loader/cache.ts

@@ -0,0 +1,206 @@
+// [LAW:types-are-the-program] The cache-policy schema: a CacheDecl is exactly one
+// of ttl / watch_file / depends_on / key / never, declared as DATA (CACHE_SCHEMA)
+// and interpreted by the tag-by-present-key engine (oneOfPresent).
+// requireCache/optionalCache gate presence by source kind. This file changes when
+// the cache vocabulary changes — add an arm to CACHE_SCHEMA and CacheDecl.
+
+import {
+  CACHE_KEYS,
+  SOURCES_REQUIRING_CACHE,
+  type CacheDecl,
+  type SourceKind,
+  type TtlCacheDecl,
+} from "../dsl-types.js";
+import { findKeyLine } from "./diagnostics.js";
+import {
+  describeValue,
+  oneOfPresent,
+  oneOfPresentJson,
+  type FieldSpec,
+  type JsonNode,
+  type OneOfPresentSchema,
+  type ValidateCtx,
+} from "./validate-core.js";
+
+export function requireCache(
+  ctx: ValidateCtx,
+  path: string,
+  raw: Record<string, unknown>,
+  kind: SourceKind,
+): CacheDecl | null {
+  if (raw.cache === undefined) {
+    if (SOURCES_REQUIRING_CACHE.includes(kind)) {
+      ctx.issues.push({
+        path: `${path}.cache`,
+        message: `${kind} variables must declare a cache policy (one of: ${CACHE_KEYS.join(", ")})`,
+        line: findKeyLine(ctx.source, path.split(".")),
+      });
+      return null;
+    }
+    // For kinds where cache is optional and absent, this path is unreachable
+    // because callers use optionalCache; keep narrow.
+    return null;
+  }
+  return validateCache(ctx, `${path}.cache`, raw.cache);
+}
+
+export function optionalCache(
+  ctx: ValidateCtx,
+  path: string,
+  raw: Record<string, unknown>,
+): CacheDecl | undefined {
+  if (raw.cache === undefined) return undefined;
+  const c = validateCache(ctx, `${path}.cache`, raw.cache);
+  return c ?? undefined;
+}
+
+// [LAW:dataflow-not-control-flow] The `cache` field as a record-field spec, so a
+// per-kind variable schema declares its cache policy as DATA. `kind` selects the
+// requiredness: file/shell/git require it (a missing cache reports the per-kind
+// message and fails the arm); template leaves it optional; time is optional but
+// ttl-only (ttlOnlyCacheSpec below). The field key is conventionally "cache",
+// read directly by requireCache/optionalCache.
+export function requireCacheSpec(kind: SourceKind): FieldSpec<CacheDecl> {
+  return {
+    required: true,
+    json: cacheJson(),
+    parse: (ctx, path, _field, raw) =>
+      requireCache(ctx, path, raw, kind) ?? undefined,
+  };
+}
+
+export function optionalCacheSpec(): FieldSpec<CacheDecl> {
+  return {
+    required: false,
+    json: cacheJson(),
+    parse: (ctx, path, _field, raw) => optionalCache(ctx, path, raw),
+  };
+}
+
+// [LAW:single-enforcer] One arm helper to push a variant's bespoke message and
+// drop — the message is the only thing that varies per arm, carried as DATA.
+function reject<M>(ctx: ValidateCtx, path: string, message: string): M | null {
+  ctx.issues.push({
+    path,
+    message,
+    line: findKeyLine(ctx.source, path.split(".")),
+  });
+  return null;
+}
+
+// [LAW:types-are-the-program] The cache schema declared as DATA: arm keys in
+// CACHE_KEYS order (the structural messages join them), each arm carrying its
+// value-validation predicate and bespoke message. The literal "cache.<key>"
+// prefix is the contract text, independent of the runtime path used for line.
+// [LAW:one-source-of-truth] Each arm's `json` is the schema for the VALUE at its
+// present key — duration/path/key are strings, depends_on a string array, never
+// the literal true; the duration FORMAT (and non-empty) is a semantic check the
+// validator keeps (a JSON Schema `pattern` could mirror it, but the loader's
+// duration grammar is the single authority, so the schema stays at `type:string`).
+const CACHE_SCHEMA: OneOfPresentSchema<CacheDecl> = {
+  noun: "cache",
+  arms: {
+    ttl: {
+      json: { type: "string" },
+      parse: (ctx, path, value) =>
+        typeof value === "string" && isValidDuration(value)
+          ? { ttl: value }
+          : reject(
+              ctx,
+              path,
+              `cache.ttl must be a duration string like "5s", "100ms", "2m", "1h"; got ${describeValue(value)}`,
+            ),
+    },
+    watch_file: {
+      json: { type: "string" },
+      parse: (ctx, path, value) =>
+        typeof value === "string" && value !== ""
+          ? { watch_file: value }
+          : reject(
+              ctx,
+              path,
+              `cache.watch_file must be a non-empty path string, got ${describeValue(value)}`,
+            ),
+    },
+    depends_on: {
+      json: { type: "array", items: { type: "string" } },
+      parse: (ctx, path, value) =>
+        Array.isArray(value) && value.every((v) => typeof v === "string")
+          ? { depends_on: value as string[] }
+          : reject(
+              ctx,
+              path,
+              `cache.depends_on must be an array of variable-name strings, got ${describeValue(value)}`,
+            ),
+    },
+    key: {
+      json: { type: "string" },
+      parse: (ctx, path, value) =>
+        typeof value === "string" && value !== ""
+          ? { key: value }
+          : reject(
+              ctx,
+              path,
+              `cache.key must be a non-empty template string, got ${describeValue(value)}`,
+            ),
+    },
+    never: {
+      json: { const: true },
+      parse: (ctx, path, value) =>
+        value === true
+          ? { never: true }
+          : reject(
+              ctx,
+              path,
+              `cache.never must be the literal boolean true, got ${describeValue(value)}`,
+            ),
+    },
+  },
+};
+
+function validateCache(
+  ctx: ValidateCtx,
+  path: string,
+  raw: unknown,
+): CacheDecl | null {
+  return oneOfPresent(ctx, CACHE_SCHEMA, path, raw);
+}
+
+// [LAW:types-are-the-program] The ttl-only subset for kinds whose runtime
+// honors no other invalidation (time vars refresh on a clock; declareTime
+// always registers a TTL timer). OneOfPresentSchema<TtlCacheDecl> forces
+// exactly the ttl arm at compile time, and the arm is CACHE_SCHEMA's own —
+// a subset of the vocabulary, never a parallel grammar. A non-ttl form is a
+// load-time diagnostic naming ttl as the only supported key, replacing the
+// runtime's former silent coercion to the default TTL [LAW:no-silent-failure].
+const TTL_ONLY_CACHE_SCHEMA: OneOfPresentSchema<TtlCacheDecl> = {
+  noun: "time-variable cache",
+  arms: { ttl: CACHE_SCHEMA.arms.ttl },
+};
+
+export function ttlOnlyCacheSpec(): FieldSpec<TtlCacheDecl> {
+  return {
+    required: false,
+    json: oneOfPresentJson(TTL_ONLY_CACHE_SCHEMA),
+    parse: (ctx, path, _field, raw) =>
+      raw.cache === undefined
+        ? undefined
+        : (oneOfPresent(
+            ctx,
+            TTL_ONLY_CACHE_SCHEMA,
+            `${path}.cache`,
+            raw.cache,
+          ) ?? undefined),
+  };
+}
+
+// [LAW:one-source-of-truth] The cache emitter derives from the SAME CACHE_SCHEMA
+// the validator interprets — shared by the per-kind variable cache fields.
+export function cacheJson(): JsonNode {
+  return oneOfPresentJson(CACHE_SCHEMA);
+}
+
+const DURATION_RE = /^(\d+(?:\.\d+)?)(ms|s|m|h)$/;
+function isValidDuration(s: string): boolean {
+  return DURATION_RE.test(s);
+}

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

@@ -0,0 +1,326 @@
+// [LAW:single-enforcer] All cross-reference resolution on the MERGED config:
+// layout nodes name declared segments, every template-bearing field references
+// only existing variables/actions, depends_on points at declared variables, and
+// state/set-action configs declare the session.id anchor. Runs after merge so a
+// user surface can reference default-provided segments/actions. This file changes
+// when the visibility/scoping rules between config parts change.
+
+import JSON5 from "json5";
+import {
+  hasCacheField,
+  walkNodes,
+  type DslConfig,
+  type VariableDecl,
+} from "../dsl-types.js";
+import { actionBindsSet } from "../action.js";
+import { findKeyLine } from "./diagnostics.js";
+import { isPlainObject, type ValidateCtx } from "./validate-core.js";
+import {
+  extractActionRefs,
+  extractPickerRefs,
+  extractTemplateRefs,
+  refResolves,
+} from "./refs.js";
+
+export function validateCrossReferences(
+  ctx: ValidateCtx,
+  cfg: DslConfig,
+): void {
+  // [LAW:one-source-of-truth] THE set of resolvable variable names — a
+  // faithful mirror of the runtime store's key set (declareOne in
+  // src/dsl/render.ts registers globals under their bare names and segment
+  // locals under segName.varName, nothing else). The runtime scope proxy
+  // (src/template-engine/scope.ts) resolves only keys literally present in
+  // the store, and the depends_on reaction (src/var-system/sources.ts) calls
+  // store.read with each listed name verbatim — so exactly the names in this
+  // set exist at runtime. One set for every reference surface, template refs
+  // and depends_on lists alike: a name's meaning is a pure function of the
+  // name string, never of which segment declares or renders it.
+  const templateScope = new Set<string>(Object.keys(cfg.variables));
+  for (const [segName, seg] of Object.entries(cfg.segments)) {
+    if (!seg.vars) continue;
+    for (const v of Object.keys(seg.vars)) templateScope.add(`${segName}.${v}`);
+  }
+
+  // [LAW:single-enforcer] ONE pre-order walk over the canonical node tree owns
+  // every layout cross-ref: each cells node's segment names must resolve to a
+  // declared segment, and any node's `when` predicate (a template like any
+  // other) must reference only existing variables. Cross-ref runs on the MERGED
+  // config so a node can name default-provided segments without re-declaring
+  // them. It traverses the canonical tree — the raw `layout`-vs-`root` authoring
+  // form is already collapsed and unrecoverable post-merge — so the path
+  // describes the tree and `line` points at whichever layout key the user wrote.
+  // [LAW:one-source-of-truth] Which top-level layout surface the user authored
+  // is read from the PARSED structure, not a text probe: a nested key named
+  // `root` (a variable, a segment) — or `layout` (a `time` var's `layout`
+  // field) — would fool a raw `findKeyLine` search and misclassify the config.
+  // Validation is cold-path, so reading the source's top-level keys is exact.
+  // The reported path/message then point at the surface the user wrote.
+  const layoutKey = authoredLayoutKey(ctx.source);
+  const layoutLine = findKeyLine(ctx.source, [layoutKey]);
+  for (const node of walkNodes(cfg.root)) {
+    // [LAW:locality-or-seam] A node's `when` reads the global scope (bare
+    // globals + namespaced segment vars) — the same existence-check shape as a
+    // segment template, surfaced at load time.
+    if (node.when !== undefined) {
+      checkTemplateRefs(ctx, `${layoutKey}.when`, node.when, templateScope, {
+        line: layoutLine,
+      });
+    }
+    if (node.kind !== "segment") continue;
+    if (!Object.prototype.hasOwnProperty.call(cfg.segments, node.name)) {
+      ctx.issues.push({
+        path: layoutKey,
+        message: `${layoutKey} entry "${node.name}" does not match any declared segment`,
+        line: layoutLine,
+      });
+    }
+  }
+
+  // For each variable's template/cache.key, every dotted ref must exist
+  // (full path OR a prefix that matches an existing variable's namespace).
+  for (const [name, v] of Object.entries(cfg.variables)) {
+    checkVarRefs(ctx, `variables.${name}`, v, templateScope);
+  }
+
+  for (const [segName, seg] of Object.entries(cfg.segments)) {
+    // [LAW:one-source-of-truth] Segment templates check against the SAME
+    // templateScope as everything else — segment locals resolve via the
+    // namespaced segName.varName form only, exactly as the runtime store
+    // keys them. The segment name is passed purely as a diagnostic hint: a
+    // bare ref to an own local is rejected with a message naming the
+    // namespaced form the author should write.
+    if (seg.vars) {
+      for (const [vName, vDecl] of Object.entries(seg.vars)) {
+        checkVarRefs(
+          ctx,
+          `segments.${segName}.vars.${vName}`,
+          vDecl,
+          templateScope,
+          segName,
+        );
+      }
+    }
+    // [LAW:locality-or-seam] Variable refs AND `{{ action }}`/`{{ picker }}` refs
+    // are checked across EVERY template-bearing field, not just `template` —
+    // bg/fg/when are templates too, so an unknown ref in them is a load error, not
+    // a render-time surprise. Same existence-check shape as layout→segments; runs
+    // on the merged config so a segment can reference a default-provided action.
+    for (const field of ["template", "bg", "fg", "when"] as const) {
+      const tpl = seg[field];
+      if (typeof tpl !== "string") continue;
+      checkTemplateRefs(
+        ctx,
+        `segments.${segName}.${field}`,
+        tpl,
+        templateScope,
+        {
+          segCtx: segName,
+        },
+      );
+      // [LAW:locality-or-seam] `{{ action "name" … }}` refs resolve against the
+      // action table on the merged config so a segment can reference a
+      // default-provided action.
+      for (const aref of extractActionRefs(tpl)) {
+        if (!Object.prototype.hasOwnProperty.call(cfg.actions, aref)) {
+          ctx.issues.push({
+            path: `segments.${segName}.${field}`,
+            message: `${field} references unknown action "${aref}"`,
+            line: findKeyLine(ctx.source, ["segments", segName, field]),
+          });
+        }
+      }
+      // [LAW:locality-or-seam] A `{{ picker "apply" "page" … }}` references two
+      // named actions — both resolve against the action table at load, same
+      // existence-check shape as a bare action ref.
+      for (const pref of extractPickerRefs(tpl)) {
+        if (!Object.prototype.hasOwnProperty.call(cfg.actions, pref)) {
+          ctx.issues.push({
+            path: `segments.${segName}.${field}`,
+            message: `${field} references unknown action "${pref}" (in a picker)`,
+            line: findKeyLine(ctx.source, ["segments", segName, field]),
+          });
+        }
+      }
+    }
+  }
+
+  // depends_on lists must point at declared variables — checked against the
+  // SAME templateScope as template refs, since both resolve against the one
+  // runtime store. The segment name is a diagnostic hint only, never a
+  // resolution rule, exactly as for templates.
+  for (const [name, v] of Object.entries(cfg.variables)) {
+    checkDependsOn(ctx, `variables.${name}`, v, templateScope);
+  }
+  for (const [segName, seg] of Object.entries(cfg.segments)) {
+    if (!seg.vars) continue;
+    for (const [vName, vDecl] of Object.entries(seg.vars)) {
+      checkDependsOn(
+        ctx,
+        `segments.${segName}.vars.${vName}`,
+        vDecl,
+        templateScope,
+        segName,
+      );
+    }
+  }
+
+  // [LAW:verifiable-goals] state-kind variables have an implicit dependency
+  // on the canonical session-id input variable. Same shape as the
+  // depends_on / template-ref existence checks above — surface a missing
+  // anchor at load time so the user fixes the config from a config-file
+  // error message, not from a render-time ReferenceError.
+  //
+  // [LAW:types-are-the-program] Check against `cfg.variables` directly: the
+  // accept/reject table for this predicate is "GLOBAL session.id declared".
+  // A segment-local declaration named "session.id" registers at runtime as
+  // `<seg>.session.id` and does NOT satisfy declareState's read of the
+  // global `session.id` box.
+  // [LAW:verifiable-goals] A widget `set` action composes a set-state click URL
+  // whose first segment is `session.id` (read from the store at render). Without
+  // a global session.id the URL is malformed and the daemon rejects the click
+  // (requireSessionId is the single enforcer — it rejects empty/slash session
+  // ids loudly, so there is no silent corruption; this surfaces the SAME
+  // requirement at load instead of at first click). Same anchor + same shape as
+  // the state-kind requirement above; OR them so either trigger fires it once.
+  // [LAW:dataflow-not-control-flow] A `set` action composes a set-state click URL
+  // whose first segment is session.id. OR it into the same requirement so an
+  // actions-only config (no state vars) still demands the anchor it needs. A
+  // picker's ✕/←/→/apply-close all go through `set` actions, so this covers them.
+  if (
+    (hasStateKind(cfg) || hasActionSetAction(cfg)) &&
+    !Object.prototype.hasOwnProperty.call(cfg.variables, "session.id")
+  ) {
+    ctx.issues.push({
+      path: "variables.session.id",
+      message: `state reads and action set-writes require a global "session.id" variable (segment-local declarations do not satisfy this — declareState/set-state both read the global box; conventionally { kind: "input", path: "session_id" })`,
+      line: findKeyLine(ctx.source, ["variables"]),
+    });
+  }
+}
+
+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;
+}
+
+// [LAW:dataflow-not-control-flow] A config emits a set-state click — and so needs
+// session.id — when any declared action is a `set` (literal, option, or bounded).
+// copy/open actions write nothing, so they embed no session.id.
+function hasActionSetAction(cfg: DslConfig): boolean {
+  return Object.values(cfg.actions).some(actionBindsSet);
+}
+
+function checkVarRefs(
+  ctx: ValidateCtx,
+  declPath: string,
+  v: VariableDecl,
+  allVars: Set<string>,
+  segCtx?: string,
+): void {
+  if (v.kind === "template") {
+    checkTemplateRefs(ctx, `${declPath}.template`, v.template, allVars, {
+      segCtx,
+    });
+  }
+  if (hasCacheField(v)) {
+    if (v.cache && "key" in v.cache) {
+      checkTemplateRefs(ctx, `${declPath}.cache.key`, v.cache.key, allVars, {
+        segCtx,
+      });
+    }
+  }
+}
+
+function checkDependsOn(
+  ctx: ValidateCtx,
+  declPath: string,
+  v: VariableDecl,
+  allVars: Set<string>,
+  segCtx?: string,
+): void {
+  if (!hasCacheField(v)) return;
+  if (!v.cache) return;
+  if (!("depends_on" in v.cache)) return;
+  for (let i = 0; i < v.cache.depends_on.length; i++) {
+    const target = v.cache.depends_on[i]!;
+    // [LAW:one-source-of-truth] Exact membership, not refResolves: the
+    // depends_on reaction calls store.read(name) with each listed name
+    // verbatim, and the store is an exact-key map. A dotted prefix that
+    // merely navigates INTO a value (resolvable in a template) is not a
+    // store key and would throw at runtime.
+    if (allVars.has(target)) continue;
+    const namespaced = segCtx !== undefined ? `${segCtx}.${target}` : undefined;
+    const hint =
+      namespaced !== undefined && allVars.has(namespaced)
+        ? ` (segment-local vars are namespaced — write "${namespaced}")`
+        : "";
+    ctx.issues.push({
+      path: `${declPath}.cache.depends_on[${i}]`,
+      message: `cache.depends_on references unknown variable "${target}"${hint}`,
+      line: findKeyLine(ctx.source, [
+        ...declPath.split("."),
+        "cache",
+        "depends_on",
+      ]),
+    });
+  }
+}
+
+function checkTemplateRefs(
+  ctx: ValidateCtx,
+  declPath: string,
+  template: string,
+  allVars: Set<string>,
+  opts?: {
+    // [LAW:one-source-of-truth] Callers whose `declPath` is not a literal key
+    // path into the source (a node `when`, whose canonical tree position no
+    // longer maps to a source key after the layout/root merge) pass the
+    // already-resolved line explicitly. Absent, the line is derived from the
+    // dotted declPath as before.
+    line?: number;
+    // The segment whose template is being checked — a diagnostic hint only,
+    // never a resolution rule. When a failing bare ref would resolve under
+    // this segment's namespace, the message names the namespaced form.
+    segCtx?: string;
+  },
+): void {
+  for (const ref of extractTemplateRefs(template)) {
+    if (refResolves(ref, allVars)) continue;
+    const namespaced =
+      opts?.segCtx !== undefined ? `${opts.segCtx}.${ref}` : undefined;
+    const hint =
+      namespaced !== undefined && refResolves(namespaced, allVars)
+        ? ` (segment-local vars are namespaced — write ".${namespaced}")`
+        : "";
+    ctx.issues.push({
+      path: declPath,
+      message: `Template references unknown variable ".${ref}"${hint}`,
+      line: opts?.line ?? findKeyLine(ctx.source, declPath.split(".")),
+    });
+  }
+}
+
+// [LAW:one-source-of-truth] The authored top-level layout surface, read from the
+// PARSED top-level keys (`root` wins; the loader already rejects authoring both).
+// A structural read — not a text search — so a nested key named `root`/`layout`
+// can never misclassify the config. Empty/unparseable source (the bundled
+// default, no file) has no surface; defaults to the historical `layout` label.
+function authoredLayoutKey(source: string): "root" | "layout" {
+  try {
+    const parsed = JSON5.parse(source);
+    if (isPlainObject(parsed) && "root" in parsed) return "root";
+  } catch {
+    // No source to read (default config) or unparseable — fall through. A real
+    // syntax error is already reported by parseDslConfig before cross-ref runs.
+  }
+  return "layout";
+}

package/src/config/loader/cycles.ts

@@ -0,0 +1,148 @@
+// [LAW:types-are-the-program] Dependency-cycle detection over the variable graph.
+// Edges come from three sources (template refs, cache.key refs, cache.depends_on);
+// a single DFS catches mixed cycles spanning edge types. This file changes when
+// what constitutes a runtime dependency edge changes.
+
+import {
+  hasCacheField,
+  type DslConfig,
+  type VariableDecl,
+} from "../dsl-types.js";
+import { findKeyLine } from "./diagnostics.js";
+import { type ValidateCtx } from "./validate-core.js";
+import { extractTemplateRefs } from "./refs.js";
+
+// Carries declaration metadata for each graph node so cycle errors report the
+// correct config path (variables.X vs segments.S.vars.X) and correct line.
+interface NodeInfo {
+  readonly declarationPath: string;
+  readonly linePathParts: readonly string[];
+}
+
+export function validateNoCycles(ctx: ValidateCtx, cfg: DslConfig): void {
+  const { graph, nodeInfo } = buildTemplateGraph(cfg);
+
+  const WHITE = 0;
+  const GRAY = 1;
+  const BLACK = 2;
+  const color = new Map<string, number>();
+  const stack: string[] = [];
+
+  for (const node of graph.keys()) color.set(node, WHITE);
+
+  for (const start of graph.keys()) {
+    if (color.get(start) !== WHITE) continue;
+    if (dfs(start)) return; // first cycle is enough — report and stop walking
+  }
+
+  function dfs(node: string): boolean {
+    color.set(node, GRAY);
+    stack.push(node);
+    for (const next of graph.get(node) ?? []) {
+      const c = color.get(next);
+      if (c === GRAY) {
+        const cycleStart = stack.indexOf(next);
+        const cycle = [...stack.slice(cycleStart), next];
+        const firstNode = cycle[0]!;
+        const info = nodeInfo.get(firstNode);
+        ctx.issues.push({
+          path: info?.declarationPath ?? `variables.${firstNode}`,
+          message: `Dependency cycle: ${cycle.join(" → ")}`,
+          line: findKeyLine(
+            ctx.source,
+            info?.linePathParts ?? ["variables", firstNode],
+          ),
+        });
+        return true;
+      }
+      if (c === WHITE && dfs(next)) return true;
+    }
+    color.set(node, BLACK);
+    stack.pop();
+    return false;
+  }
+}
+
+// [LAW:types-are-the-program] Build the full variable dependency graph: edges
+// are X → Y for any of three edge kinds:
+//   1. template-kind vars: template string references Y (eval dependency)
+//   2. any var with cache.key: key template references Y (cache-key dependency)
+//   3. any var with cache.depends_on: each listed name is Y (invalidation dep)
+// All three kinds can form infinite loops at runtime; a single DFS catches
+// mixed cycles that span multiple edge types.
+//
+// Segment vars use the namespaced form (segName.varName) as their sole graph
+// node — eliminates bare-name collisions when two segments both declare a var
+// named e.g. "local". Global vars keep their bare names.
+function buildTemplateGraph(cfg: DslConfig): {
+  graph: Map<string, Set<string>>;
+  nodeInfo: Map<string, NodeInfo>;
+} {
+  const allVarNames = new Set<string>(Object.keys(cfg.variables));
+  const nodeInfo = new Map<string, NodeInfo>();
+
+  for (const name of Object.keys(cfg.variables)) {
+    nodeInfo.set(name, {
+      declarationPath: `variables.${name}`,
+      linePathParts: ["variables", name],
+    });
+  }
+  for (const [segName, seg] of Object.entries(cfg.segments)) {
+    if (!seg.vars) continue;
+    for (const vName of Object.keys(seg.vars)) {
+      const canonical = `${segName}.${vName}`;
+      allVarNames.add(canonical);
+      nodeInfo.set(canonical, {
+        declarationPath: `segments.${segName}.vars.${vName}`,
+        linePathParts: ["segments", segName, "vars", vName],
+      });
+    }
+  }
+
+  const graph = new Map<string, Set<string>>();
+  for (const name of allVarNames) graph.set(name, new Set());
+
+  // [LAW:one-source-of-truth] Edges resolve refs exactly as the runtime scope
+  // proxy does: a ref is the literal store key (globals bare, segment locals
+  // namespaced as segName.varName) — never re-derived per segment. Bare
+  // own-segment refs are not aliased here because the runtime has no such
+  // aliasing; cross-ref rejects them at load with the namespaced suggestion.
+  const addTemplateEdges = (from: string, template: string): void => {
+    for (const ref of extractTemplateRefs(template)) {
+      if (allVarNames.has(ref)) {
+        graph.get(from)!.add(ref);
+        continue;
+      }
+      // Resolve "first identifier" — `.session.id` may indicate dependence on
+      // `session` if that's the declared var (matches scope.ts proxy walk).
+      const head = ref.split(".")[0]!;
+      if (head !== ref && allVarNames.has(head)) {
+        graph.get(from)!.add(head);
+      }
+    }
+  };
+
+  const addVarEdges = (name: string, v: VariableDecl): void => {
+    if (v.kind === "template") addTemplateEdges(name, v.template);
+    if (hasCacheField(v)) {
+      if (v.cache && "key" in v.cache) addTemplateEdges(name, v.cache.key);
+      if (v.cache && "depends_on" in v.cache) {
+        for (const dep of v.cache.depends_on) {
+          if (allVarNames.has(dep)) graph.get(name)!.add(dep);
+        }
+      }
+    }
+  };
+
+  for (const [name, v] of Object.entries(cfg.variables)) {
+    addVarEdges(name, v);
+  }
+  for (const [segName, seg] of Object.entries(cfg.segments)) {
+    if (!seg.vars) continue;
+    for (const [vName, vDecl] of Object.entries(seg.vars)) {
+      addVarEdges(`${segName}.${vName}`, vDecl);
+    }
+  }
+
+  return { graph, nodeInfo };
+}