design-constraint-validator 1.0.0 → 1.1.0

package/core/cross-axis-config.ts

@@ -1,152 +1,182 @@
-import fs from "node:fs";
-import { CrossAxisPlugin, type CrossAxisRule, type Ctx } from "./constraints/cross-axis.js";
-
-type When = { id: string; op: "<="|">="|"<"|">"|"=="|"!="; value: number };
-type Require = { id: string; op: "<="|">="|"<"|">"|"=="|"!="; ref?: string; fallback?: string|number };
-type Compare = { a: string; op: "<="|">="|"<"|">"|"=="|"!="; b: string; delta?: string|number };
-type RawRule = { id: string; level?: "error"|"warn"; where?: string; bp?: string; when?: When; require?: Require; compare?: Compare; };
-
-export function loadCrossAxisPlugin(
-  path: string,
-  bp?: string,
-  opts?: { debug?: boolean; knownIds?: Set<string> }
-) {
-  const debug = !!opts?.debug;
-  const known = opts?.knownIds ?? new Set<string>();
-  const log = (...args: any[]) => { if (debug) console.log("[cross-axis]", ...args); };
-
-  if (!fs.existsSync(path)) {
-    log(`no rules file at ${path} (bp=${bp ?? "global"})`);
-    return CrossAxisPlugin([], bp);
-  }
-
-  const raw = JSON.parse(fs.readFileSync(path, "utf8")) as { rules: RawRule[] };
-  const rules: CrossAxisRule[] = [];
-  const unknownIds = new Set<string>();
-  const skipped: Array<{ id?: string; reason: string }> = [];
-
-  // Fuzzy suggestion helpers (lightweight Levenshtein)
-  function levenshtein(a: string, b: string) {
-    const dp = Array(b.length + 1).fill(0).map((_, j) => j);
-    for (let i = 1; i <= a.length; i++) {
-      let prev = i - 1, cur = i;
-      for (let j = 1; j <= b.length; j++) {
-        const tmp = cur;
-        const cost = a[i - 1] === b[j - 1] ? 0 : 1;
-        cur = Math.min(dp[j] + 1, cur + 1, prev + cost);
-        dp[j] = tmp;
-        prev = tmp;
-      }
-      dp[b.length] = cur;
-    }
-    return dp[b.length];
-  }
-  function suggest(id: string, k = 3) {
-    return [...known].map(c => ({ id: c, d: levenshtein(id, c) }))
-      .sort((a, b) => a.d - b.d)
-      .slice(0, k);
-  }
-
-  const needId = (id?: string) => {
-    if (!id) return false;
-    if (!known.has(id)) { unknownIds.add(id); }
-    return true;
-  };
-
-  for (const r of raw.rules || []) {
-    if (r.bp && bp && r.bp !== bp) { continue; }
-    if (r.bp && !bp) { // rule targets specific breakpoint; skip in global run
-      continue;
-    }
-    try {
-      if (r.when && r.require) {
-        // Validate IDs
-        needId(r.when.id);
-        needId(r.require.id);
-        if (r.require.ref) needId(r.require.ref);
-
-        rules.push({
-          id: r.id, level: r.level, where: r.where,
-          when: { id: r.when.id, test: makeOp(r.when.op, r.when.value) },
-          require: {
-            id: r.require.id,
-            test: (v: number, ctx: Ctx) => {
-              const rhs = valueOrRef(ctx, r.require!.ref, r.require!.fallback);
-              return cmp(v, rhs, r.require!.op);
-            },
-            msg: (v: number, ctx: Ctx) => {
-              const rhs = valueOrRef(ctx, r.require!.ref, r.require!.fallback);
-              return `${r.require!.id} ${prettyFail(r.require!.op)} ${fmt(rhs)} (was ${fmt(v)})`;
-            }
-          }
-        });
-      } else if (r.compare) {
-        needId(r.compare.a);
-        needId(r.compare.b);
-
-        rules.push({
-          id: r.id, level: r.level, where: r.where,
-          when: { id: r.compare.a, test: () => true },
-          require: {
-            id: r.compare.a,
-            test: (_: number, ctx: Ctx) => {
-              const a = ctx.getPx(r.compare!.a) ?? NaN;
-              const b = ctx.getPx(r.compare!.b) ?? NaN;
-              const delta = px(r.compare!.delta ?? 0);
-              if (Number.isNaN(a) || Number.isNaN(b)) return true; // skip check if missing
-              return cmp(a, b + delta, r.compare!.op);
-            },
-            msg: (_: number, ctx: Ctx) => {
-              const a = ctx.getPx(r.compare!.a);
-              const b = ctx.getPx(r.compare!.b);
-              const delta = px(r.compare!.delta ?? 0);
-              return `${r.compare!.a} ${prettyFail(r.compare!.op)} ${fmt((b ?? 0) + delta)} (was ${fmt(a ?? NaN)})`;
-            }
-          }
-        });
-      } else {
-        skipped.push({ id: r.id, reason: "neither when+require nor compare present" });
-      }
-    } catch (e: any) {
-      skipped.push({ id: r.id, reason: `exception: ${e?.message ?? e}` });
-    }
-  }
-
-  log(`loaded ${rules.length} rule(s) from ${path}${bp ? ` [bp=${bp}]` : ""}`);
-  if (unknownIds.size) {
-    log(`unknown ids referenced:`, [...unknownIds].join(", "));
-    for (const u of unknownIds) {
-      const s = suggest(u, 3);
-      if (s.length) log(`  did you mean: ${s.map(x => `${x.id} (d=${x.d})`).join(', ')}`);
-    }
-  }
-  if (skipped.length) {
-    for (const s of skipped) log(`skipped rule ${s.id ?? "(no id)"} — ${s.reason}`);
-  }
-
-  // Extra hint for common anchor pitfall
-  for (const r of raw.rules || []) {
-    if (r.require?.ref && !known.has(r.require.ref)) {
-      log(`anchor missing: ${r.require.ref} → will use fallback=${JSON.stringify(r.require.fallback)} when evaluating`);
-    }
-  }
-
-  return CrossAxisPlugin(rules, bp);
-}
-
-// helpers
-const px = (v: string|number) => typeof v === "number" ? v : parseFloat(String(v)) * (String(v).trim().endsWith("rem") ? 16 : 1);
-const cmp = (a:number,b:number,op:When["op"]) =>
-  op === ">="? a>=b : op === ">"? a>b : op === "<="? a<=b : op === "<"? a<b : op === "=="? a===b : a!==b;
-const prettyFail = (op: string) => ({">=":"<",">":"≤","<=":">","<": "≥","==":"≠","!=":"="} as any)[op] || "≠";
-const fmt = (v:number|string) => Number.isFinite(Number(v)) ? `${Number(v)}px` : String(v);
-function valueOrRef(ctx: Ctx, ref?: string, fallback?: string|number) {
-  if (ref) {
-    const v = ctx.getPx(ref);
-    if (v != null) return v;
-  }
-  return typeof fallback === "number" ? fallback : px(fallback ?? 0);
-}
-function makeOp(op: When["op"], rhs: number) {
-  return (v: number) => cmp(v, rhs, op);
+/**
+ * @deprecated This module is deprecated. Use cli/cross-axis-loader.ts instead.
+ *
+ * Phase 3B (Filesystem Separation): This file contains filesystem access logic
+ * that has been moved to the CLI layer (cli/cross-axis-loader.ts).
+ *
+ * Core modules should not import from node:fs. Instead:
+ * - CLI code uses cli/cross-axis-loader.ts to read and parse rules
+ * - Core plugin (core/constraints/cross-axis.ts) accepts pre-parsed rules
+ *
+ * Migration:
+ * ```ts
+ * // OLD (core reads filesystem):
+ * import { loadCrossAxisPlugin } from './core/cross-axis-config.js';
+ * engine.use(loadCrossAxisPlugin(path, bp, { knownIds }));
+ *
+ * // NEW (CLI reads, core receives data):
+ * import { loadCrossAxisRules } from './cli/cross-axis-loader.js';
+ * import { CrossAxisPlugin } from './core/constraints/cross-axis.js';
+ * const rules = loadCrossAxisRules(path, { bp, knownIds });
+ * engine.use(CrossAxisPlugin(rules, bp));
+ * ```
+ *
+ * This file will be removed in a future major version.
+ */
+
+import fs from "node:fs";
+import { CrossAxisPlugin, type CrossAxisRule, type Ctx } from "./constraints/cross-axis.js";
+
+type When = { id: string; op: "<="|">="|"<"|">"|"=="|"!="; value: number };
+type Require = { id: string; op: "<="|">="|"<"|">"|"=="|"!="; ref?: string; fallback?: string|number };
+type Compare = { a: string; op: "<="|">="|"<"|">"|"=="|"!="; b: string; delta?: string|number };
+type RawRule = { id: string; level?: "error"|"warn"; where?: string; bp?: string; when?: When; require?: Require; compare?: Compare; };
+
+/**
+ * @deprecated Use cli/cross-axis-loader.ts loadCrossAxisRules() + CrossAxisPlugin() instead.
+ * This function will be removed in a future major version.
+ */
+export function loadCrossAxisPlugin(
+  path: string,
+  bp?: string,
+  opts?: { debug?: boolean; knownIds?: Set<string> }
+) {
+  const debug = !!opts?.debug;
+  const known = opts?.knownIds ?? new Set<string>();
+  const log = (...args: any[]) => { if (debug) console.log("[cross-axis]", ...args); };
+
+  if (!fs.existsSync(path)) {
+    log(`no rules file at ${path} (bp=${bp ?? "global"})`);
+    return CrossAxisPlugin([], bp);
+  }
+
+  const raw = JSON.parse(fs.readFileSync(path, "utf8")) as { rules: RawRule[] };
+  const rules: CrossAxisRule[] = [];
+  const unknownIds = new Set<string>();
+  const skipped: Array<{ id?: string; reason: string }> = [];
+
+  // Fuzzy suggestion helpers (lightweight Levenshtein)
+  function levenshtein(a: string, b: string) {
+    const dp = Array(b.length + 1).fill(0).map((_, j) => j);
+    for (let i = 1; i <= a.length; i++) {
+      let prev = i - 1, cur = i;
+      for (let j = 1; j <= b.length; j++) {
+        const tmp = cur;
+        const cost = a[i - 1] === b[j - 1] ? 0 : 1;
+        cur = Math.min(dp[j] + 1, cur + 1, prev + cost);
+        dp[j] = tmp;
+        prev = tmp;
+      }
+      dp[b.length] = cur;
+    }
+    return dp[b.length];
+  }
+  function suggest(id: string, k = 3) {
+    return [...known].map(c => ({ id: c, d: levenshtein(id, c) }))
+      .sort((a, b) => a.d - b.d)
+      .slice(0, k);
+  }
+
+  const needId = (id?: string) => {
+    if (!id) return false;
+    if (!known.has(id)) { unknownIds.add(id); }
+    return true;
+  };
+
+  for (const r of raw.rules || []) {
+    if (r.bp && bp && r.bp !== bp) { continue; }
+    if (r.bp && !bp) { // rule targets specific breakpoint; skip in global run
+      continue;
+    }
+    try {
+      if (r.when && r.require) {
+        // Validate IDs
+        needId(r.when.id);
+        needId(r.require.id);
+        if (r.require.ref) needId(r.require.ref);
+
+        rules.push({
+          id: r.id, level: r.level, where: r.where,
+          when: { id: r.when.id, test: makeOp(r.when.op, r.when.value) },
+          require: {
+            id: r.require.id,
+            test: (v: number, ctx: Ctx) => {
+              const rhs = valueOrRef(ctx, r.require!.ref, r.require!.fallback);
+              return cmp(v, rhs, r.require!.op);
+            },
+            msg: (v: number, ctx: Ctx) => {
+              const rhs = valueOrRef(ctx, r.require!.ref, r.require!.fallback);
+              return `${r.require!.id} ${prettyFail(r.require!.op)} ${fmt(rhs)} (was ${fmt(v)})`;
+            }
+          }
+        });
+      } else if (r.compare) {
+        needId(r.compare.a);
+        needId(r.compare.b);
+
+        rules.push({
+          id: r.id, level: r.level, where: r.where,
+          when: { id: r.compare.a, test: () => true },
+          require: {
+            id: r.compare.a,
+            test: (_: number, ctx: Ctx) => {
+              const a = ctx.getPx(r.compare!.a) ?? NaN;
+              const b = ctx.getPx(r.compare!.b) ?? NaN;
+              const delta = px(r.compare!.delta ?? 0);
+              if (Number.isNaN(a) || Number.isNaN(b)) return true; // skip check if missing
+              return cmp(a, b + delta, r.compare!.op);
+            },
+            msg: (_: number, ctx: Ctx) => {
+              const a = ctx.getPx(r.compare!.a);
+              const b = ctx.getPx(r.compare!.b);
+              const delta = px(r.compare!.delta ?? 0);
+              return `${r.compare!.a} ${prettyFail(r.compare!.op)} ${fmt((b ?? 0) + delta)} (was ${fmt(a ?? NaN)})`;
+            }
+          }
+        });
+      } else {
+        skipped.push({ id: r.id, reason: "neither when+require nor compare present" });
+      }
+    } catch (e: any) {
+      skipped.push({ id: r.id, reason: `exception: ${e?.message ?? e}` });
+    }
+  }
+
+  log(`loaded ${rules.length} rule(s) from ${path}${bp ? ` [bp=${bp}]` : ""}`);
+  if (unknownIds.size) {
+    log(`unknown ids referenced:`, [...unknownIds].join(", "));
+    for (const u of unknownIds) {
+      const s = suggest(u, 3);
+      if (s.length) log(`  did you mean: ${s.map(x => `${x.id} (d=${x.d})`).join(', ')}`);
+    }
+  }
+  if (skipped.length) {
+    for (const s of skipped) log(`skipped rule ${s.id ?? "(no id)"} — ${s.reason}`);
+  }
+
+  // Extra hint for common anchor pitfall
+  for (const r of raw.rules || []) {
+    if (r.require?.ref && !known.has(r.require.ref)) {
+      log(`anchor missing: ${r.require.ref} → will use fallback=${JSON.stringify(r.require.fallback)} when evaluating`);
+    }
+  }
+
+  return CrossAxisPlugin(rules, bp);
+}
+
+// helpers
+const px = (v: string|number) => typeof v === "number" ? v : parseFloat(String(v)) * (String(v).trim().endsWith("rem") ? 16 : 1);
+const cmp = (a:number,b:number,op:When["op"]) =>
+  op === ">="? a>=b : op === ">"? a>b : op === "<="? a<=b : op === "<"? a<b : op === "=="? a===b : a!==b;
+const prettyFail = (op: string) => ({">=":"<",">":"≤","<=":">","<": "≥","==":"≠","!=":"="} as any)[op] || "≠";
+const fmt = (v:number|string) => Number.isFinite(Number(v)) ? `${Number(v)}px` : String(v);
+function valueOrRef(ctx: Ctx, ref?: string, fallback?: string|number) {
+  if (ref) {
+    const v = ctx.getPx(ref);
+    if (v != null) return v;
+  }
+  return typeof fallback === "number" ? fallback : px(fallback ?? 0);
+}
+function makeOp(op: When["op"], rhs: number) {
+  return (v: number) => cmp(v, rhs, op);
 }

package/core/engine.d.ts

@@ -1,13 +1,90 @@
 import type { TokenId, TokenValue } from "./flatten.js";
+/**
+ * Represents a constraint violation.
+ *
+ * Phase 3C: Enhanced with metadata for tooling and visualization.
+ */
 export type ConstraintIssue = {
     id: TokenId | string;
     rule: string;
     level: "error" | "warn";
     message: string;
     where?: string;
+    /**
+     * Token IDs involved in this violation.
+     * Useful for filtering, highlighting, and incremental validation.
+     *
+     * Example: For a WCAG contrast violation between fg and bg tokens,
+     * this would be [fgTokenId, bgTokenId].
+     */
+    involvedTokens?: TokenId[];
+    /**
+     * Graph edges (reference relationships) involved in this violation.
+     * Useful for visualization and "why" explanations.
+     *
+     * Example: If a token references another that violates a constraint,
+     * this captures that reference edge.
+     */
+    involvedEdges?: Array<[TokenId, TokenId]>;
 };
+/**
+ * Constraint plugin interface.
+ *
+ * Phase 3C: Documented contract for candidate-based evaluation.
+ *
+ * ## Candidate Contract
+ *
+ * Plugins MUST honor the `candidates` set for incremental validation:
+ * - Only evaluate constraints that involve at least one candidate token
+ * - Return violations where at least one involved token is in candidates
+ * - This enables efficient re-validation when tokens change
+ *
+ * ## Metadata Contract
+ *
+ * Plugins SHOULD populate `involvedTokens` in returned issues:
+ * - List all token IDs that participate in the constraint
+ * - This enables filtering, highlighting, and graph visualization
+ * - Optional but recommended for better tooling support
+ *
+ * ## Example Implementation
+ *
+ * ```ts
+ * export function MyPlugin(rules: Rule[]): ConstraintPlugin {
+ *   return {
+ *     id: "my-plugin",
+ *     evaluate(engine, candidates) {
+ *       const issues: ConstraintIssue[] = [];
+ *       for (const rule of rules) {
+ *         // Honor candidates: skip if no involved tokens are candidates
+ *         if (!candidates.has(rule.tokenA) && !candidates.has(rule.tokenB)) {
+ *           continue;
+ *         }
+ *         // Check constraint...
+ *         if (violated) {
+ *           issues.push({
+ *             id: `${rule.tokenA}|${rule.tokenB}`,
+ *             rule: "my-plugin",
+ *             level: "error",
+ *             message: "...",
+ *             involvedTokens: [rule.tokenA, rule.tokenB], // Metadata
+ *           });
+ *         }
+ *       }
+ *       return issues;
+ *     }
+ *   };
+ * }
+ * ```
+ */
 export type ConstraintPlugin = {
     id: string;
+    /**
+     * Evaluate constraints for a set of candidate tokens.
+     *
+     * @param engine Engine instance providing token values and graph
+     * @param candidates Set of token IDs to evaluate (changed + affected)
+     * @returns Array of constraint violations
+     */
     evaluate(engine: Engine, candidates: Set<TokenId>): ConstraintIssue[];
 };
 export type Graph = Map<TokenId, Set<TokenId>>;
@@ -19,6 +96,24 @@ export declare class Engine {
     use(plugin: ConstraintPlugin): this;
     get(id: TokenId): TokenValue | undefined;
     set(id: TokenId, value: TokenValue): void;
+    /**
+     * Get all token IDs in the engine.
+     *
+     * Phase 3C: Exposed for plugins and adapters.
+     * Useful for iterating all tokens or creating a full candidate set.
+     *
+     * @returns Array of all token IDs
+     */
+    getAllIds(): TokenId[];
+    /**
+     * Get flat token map (ID → value).
+     *
+     * Phase 3C: Exposed to avoid duplicate flattening in CLI/adapters.
+     * Returns a plain object suitable for serialization or adapter use.
+     *
+     * @returns Record mapping token IDs to their current values
+     */
+    getFlatTokens(): Record<TokenId, TokenValue>;
     /** All nodes that depend (directly/indirectly) on start. */
     affected(start: TokenId): Set<TokenId>;
     evaluate(candidates: Set<TokenId>): ConstraintIssue[];

package/core/engine.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"engine.d.ts","sourceRoot":"","sources":["engine.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,UAAU,EAAE,MAAM,cAAc,CAAC;AAExD,MAAM,MAAM,eAAe,GAAG;IAC5B,EAAE,EAAE,OAAO,GAAG,MAAM,CAAC;IACrB,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,OAAO,GAAG,MAAM,CAAC;IACxB,OAAO,EAAE,MAAM,CAAC;IAChB,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB,CAAC;AAEF,MAAM,MAAM,gBAAgB,GAAG;IAC7B,EAAE,EAAE,MAAM,CAAC;IAEX,QAAQ,CAAC,MAAM,EAAE,MAAM,EAAE,UAAU,EAAE,GAAG,CAAC,OAAO,CAAC,GAAG,eAAe,EAAE,CAAC;CACvE,CAAC;AAEF,MAAM,MAAM,KAAK,GAAG,GAAG,CAAC,OAAO,EAAE,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC;AAE/C,qBAAa,MAAM;IACjB,OAAO,CAAC,MAAM,CAAkC;IAChD,OAAO,CAAC,KAAK,CAAoB;IACjC,OAAO,CAAC,OAAO,CAA0B;gBAE7B,UAAU,EAAE,MAAM,CAAC,OAAO,EAAE,UAAU,CAAC,EAAE,KAAK,EAAE,KAAK,CAAC,CAAC,OAAO,EAAE,OAAO,CAAC,CAAC;IASrF,GAAG,CAAC,MAAM,EAAE,gBAAgB;IAE5B,GAAG,CAAC,EAAE,EAAE,OAAO,GAAG,UAAU,GAAG,SAAS;IACxC,GAAG,CAAC,EAAE,EAAE,OAAO,EAAE,KAAK,EAAE,UAAU;IAElC,4DAA4D;IAC5D,QAAQ,CAAC,KAAK,EAAE,OAAO,GAAG,GAAG,CAAC,OAAO,CAAC;IAatC,QAAQ,CAAC,UAAU,EAAE,GAAG,CAAC,OAAO,CAAC;IAIjC,2FAA2F;IAC3F,MAAM,CAAC,EAAE,EAAE,OAAO,EAAE,KAAK,EAAE,UAAU;;;;;CAQtC"}
+{"version":3,"file":"engine.d.ts","sourceRoot":"","sources":["engine.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,UAAU,EAAE,MAAM,cAAc,CAAC;AAExD;;;;GAIG;AACH,MAAM,MAAM,eAAe,GAAG;IAC5B,EAAE,EAAE,OAAO,GAAG,MAAM,CAAC;IACrB,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,OAAO,GAAG,MAAM,CAAC;IACxB,OAAO,EAAE,MAAM,CAAC;IAChB,KAAK,CAAC,EAAE,MAAM,CAAC;IAEf;;;;;;OAMG;IACH,cAAc,CAAC,EAAE,OAAO,EAAE,CAAC;IAE3B;;;;;;OAMG;IACH,aAAa,CAAC,EAAE,KAAK,CAAC,CAAC,OAAO,EAAE,OAAO,CAAC,CAAC,CAAC;CAC3C,CAAC;AAEF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgDG;AACH,MAAM,MAAM,gBAAgB,GAAG;IAC7B,EAAE,EAAE,MAAM,CAAC;IACX;;;;;;OAMG;IACH,QAAQ,CAAC,MAAM,EAAE,MAAM,EAAE,UAAU,EAAE,GAAG,CAAC,OAAO,CAAC,GAAG,eAAe,EAAE,CAAC;CACvE,CAAC;AAEF,MAAM,MAAM,KAAK,GAAG,GAAG,CAAC,OAAO,EAAE,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC;AAE/C,qBAAa,MAAM;IACjB,OAAO,CAAC,MAAM,CAAkC;IAChD,OAAO,CAAC,KAAK,CAAoB;IACjC,OAAO,CAAC,OAAO,CAA0B;gBAE7B,UAAU,EAAE,MAAM,CAAC,OAAO,EAAE,UAAU,CAAC,EAAE,KAAK,EAAE,KAAK,CAAC,CAAC,OAAO,EAAE,OAAO,CAAC,CAAC;IASrF,GAAG,CAAC,MAAM,EAAE,gBAAgB;IAE5B,GAAG,CAAC,EAAE,EAAE,OAAO,GAAG,UAAU,GAAG,SAAS;IACxC,GAAG,CAAC,EAAE,EAAE,OAAO,EAAE,KAAK,EAAE,UAAU;IAElC;;;;;;;OAOG;IACH,SAAS,IAAI,OAAO,EAAE;IAItB;;;;;;;OAOG;IACH,aAAa,IAAI,MAAM,CAAC,OAAO,EAAE,UAAU,CAAC;IAI5C,4DAA4D;IAC5D,QAAQ,CAAC,KAAK,EAAE,OAAO,GAAG,GAAG,CAAC,OAAO,CAAC;IAatC,QAAQ,CAAC,UAAU,EAAE,GAAG,CAAC,OAAO,CAAC;IAIjC,2FAA2F;IAC3F,MAAM,CAAC,EAAE,EAAE,OAAO,EAAE,KAAK,EAAE,UAAU;;;;;CAQtC"}

package/core/engine.js

@@ -16,6 +16,28 @@ export class Engine {
     use(plugin) { this.plugins.push(plugin); return this; }
     get(id) { return this.values.get(id); }
     set(id, value) { this.values.set(id, value); }
+    /**
+     * Get all token IDs in the engine.
+     *
+     * Phase 3C: Exposed for plugins and adapters.
+     * Useful for iterating all tokens or creating a full candidate set.
+     *
+     * @returns Array of all token IDs
+     */
+    getAllIds() {
+        return Array.from(this.values.keys());
+    }
+    /**
+     * Get flat token map (ID → value).
+     *
+     * Phase 3C: Exposed to avoid duplicate flattening in CLI/adapters.
+     * Returns a plain object suitable for serialization or adapter use.
+     *
+     * @returns Record mapping token IDs to their current values
+     */
+    getFlatTokens() {
+        return Object.fromEntries(this.values);
+    }
     /** All nodes that depend (directly/indirectly) on start. */
     affected(start) {
         const seen = new Set();