@aestheticfunction/dspack-gen 0.1.0

package/src/core/lint/rules.ts

@@ -0,0 +1,320 @@
+/**
+ * Gate S3 — the rule-type registry and evaluators (normative semantics:
+ * spec/dspack-v0.3.md §5.3 and spec/dspack-v0.4.md §4).
+ *
+ * The registry is the thesis-bearing seam: new rule types land additively in
+ * v0.4 by adding an entry — never by touching existing evaluators. v0.4 kept
+ * that promise for `required-props` (a new entry); `forbiddenCategories` is
+ * the spec'd exception — a new OPTIONAL field on forbidden-composition
+ * (v0.4 §4.2; existing fields' semantics frozen). A rule whose type has no
+ * registry entry is a HARD error (UnknownRuleTypeError → CLI exit 4):
+ * silently skipping would misreport a surface as governed.
+ *
+ * All three v0.3 evaluators are implemented. (The M1 plan deferred
+ * `forbidden-composition` to M2, but the v0.3 shadcn contract carries a
+ * UNIVERSAL forbidden-composition rule and spec §5.4 forbids skipping — a
+ * two-evaluator linter would hard-error on every lint of the real contract.
+ * Deviation flagged for maintainer review in the PR; the evaluator is ~40
+ * lines and fixture F5 activates with it.)
+ */
+import type {
+  ComponentChoiceRule,
+  Contract,
+  ForbiddenCompositionRule,
+  RequiredCompositionRule,
+  RequiredPropsRule,
+  RuleEntry,
+  Surface,
+} from "../contract.js";
+import { categoryIndex } from "../contract.js";
+import { LEVEL_OF, type Finding } from "./findings.js";
+import { descendantsOf, walkSurface, type VisitedNode } from "./walk.js";
+
+export class UnknownRuleTypeError extends Error {
+  constructor(readonly ruleId: string, readonly ruleType: string, detail: string) {
+    super(`rule '${ruleId}' has unknown or unimplemented type '${ruleType}': ${detail}`);
+    this.name = "UnknownRuleTypeError";
+  }
+}
+
+type Evaluator = (rule: RuleEntry, surface: Surface, contract: Contract) => Finding[];
+
+/** The rule-type registry. Additive-only across spec versions. */
+const REGISTRY: Record<string, Evaluator> = {
+  "component-choice": evaluateComponentChoice,
+  "required-composition": evaluateRequiredComposition,
+  "forbidden-composition": evaluateForbiddenComposition,
+  "required-props": evaluateRequiredProps,
+};
+
+export function evaluateRules(surface: Surface, contract: Contract): Finding[] {
+  const findings: Finding[] = [];
+  for (const rule of contract.rules ?? []) {
+    if (rule.appliesTo && !rule.appliesTo.intents.includes(surface.intent)) continue;
+    const evaluator = REGISTRY[rule.type];
+    if (evaluator === undefined) {
+      throw new UnknownRuleTypeError(rule.id, rule.type, "not a v0.3/v0.4 rule type");
+    }
+    findings.push(...evaluator(rule, surface, contract));
+  }
+  return findings;
+}
+
+function finding(rule: RuleEntry, message: string, location: Finding["location"]): Finding {
+  return {
+    ruleId: rule.id,
+    type: rule.type,
+    requirement: rule.severity,
+    level: LEVEL_OF[rule.severity],
+    message,
+    rationale: rule.rationale,
+    location,
+    exampleIds: rule.examples ?? [],
+  };
+}
+
+const SURFACE_LOCATION = { path: "$.root", component: "surface" } as const;
+
+/** Human reference to a node for messages: path plus id when present. */
+function describeNode(visited: VisitedNode): string {
+  return visited.node.id ? `at ${visited.path}, id "${visited.node.id}"` : `at ${visited.path}`;
+}
+
+function locationOf(visited: VisitedNode): Finding["location"] {
+  return { path: visited.path, component: visited.node.component, nodeId: visited.node.id };
+}
+
+/**
+ * component-choice: every id in `require` MUST appear ≥1 time (finding at the
+ * surface root per missing id); every id in `forbid` MUST appear 0 times
+ * (finding per matching node).
+ */
+function evaluateComponentChoice(entry: RuleEntry, surface: Surface): Finding[] {
+  const rule = entry as ComponentChoiceRule;
+  const findings: Finding[] = [];
+  const nodes = walkSurface(surface);
+
+  for (const id of rule.forbid ?? []) {
+    for (const visited of nodes.filter((v) => v.node.component === id)) {
+      findings.push(
+        finding(rule, `Component '${id}' is forbidden for intent '${surface.intent}'.`, locationOf(visited)),
+      );
+    }
+  }
+  for (const id of rule.require ?? []) {
+    if (!nodes.some((v) => v.node.component === id)) {
+      findings.push(finding(rule, `Required component '${id}' does not appear in the surface.`, SURFACE_LOCATION));
+    }
+  }
+  return findings;
+}
+
+/**
+ * required-composition: for EVERY node matching `component`, each
+ * requiredSubComponents entry MUST have ≥ min matching descendants, and each
+ * requiredProps entry MUST hold (on the node itself, or on every descendant
+ * matching `on` — of which at least one must exist).
+ */
+function evaluateRequiredComposition(entry: RuleEntry, surface: Surface): Finding[] {
+  const rule = entry as RequiredCompositionRule;
+  const findings: Finding[] = [];
+
+  for (const visited of walkSurface(surface).filter((v) => v.node.component === rule.component)) {
+    const descendants = descendantsOf(visited);
+
+    for (const requirement of rule.requiredSubComponents ?? []) {
+      const min = requirement.min ?? 1;
+      const found = descendants.filter((d) => d.node.component === requirement.id).length;
+      if (found < min) {
+        findings.push(
+          finding(
+            rule,
+            `Required sub-component '${requirement.id}' (min ${min}) not found among descendants (found ${found}).`,
+            locationOf(visited),
+          ),
+        );
+      }
+    }
+
+    for (const requirement of rule.requiredProps ?? []) {
+      const holds = (candidate: VisitedNode): boolean =>
+        requirement.oneOf.includes(candidate.node.props?.[requirement.prop] as never);
+      if (requirement.on === undefined) {
+        if (!holds(visited)) {
+          findings.push(
+            finding(
+              rule,
+              `Required prop '${requirement.prop}' must be one of ${requirement.oneOf.map((v) => JSON.stringify(v)).join(", ")}.`,
+              locationOf(visited),
+            ),
+          );
+        }
+      } else {
+        const targets = descendants.filter((d) => d.node.component === requirement.on);
+        if (targets.length === 0) {
+          findings.push(
+            finding(
+              rule,
+              `No descendant '${requirement.on}' found to satisfy required prop '${requirement.prop}'.`,
+              locationOf(visited),
+            ),
+          );
+        }
+        for (const target of targets.filter((t) => !holds(t))) {
+          findings.push(
+            finding(
+              rule,
+              `Required prop '${requirement.prop}' on '${requirement.on}' must be one of ${requirement.oneOf.map((v) => JSON.stringify(v)).join(", ")}.`,
+              locationOf(target),
+            ),
+          );
+        }
+      }
+    }
+  }
+  return findings;
+}
+
+/**
+ * forbidden-composition: for EVERY node matching `component`, no descendant
+ * may match any forbiddenDescendants id — per spec §5.3 the finding is
+ * LOCATED AT the offending descendant (the message names the matching origin
+ * node) — and no forbiddenProps entry may hold (on the node itself, or on
+ * descendants matching `on`, located at the checked node).
+ */
+function evaluateForbiddenComposition(entry: RuleEntry, surface: Surface, contract: Contract): Finding[] {
+  const rule = entry as ForbiddenCompositionRule;
+  const findings: Finding[] = [];
+  const categories = rule.forbiddenCategories?.length ? categoryIndex(contract) : undefined;
+
+  for (const visited of walkSurface(surface).filter((v) => v.node.component === rule.component)) {
+    const descendants = descendantsOf(visited);
+
+    for (const id of rule.forbiddenDescendants ?? []) {
+      for (const offender of descendants.filter((d) => d.node.component === id)) {
+        findings.push(
+          finding(
+            rule,
+            `Forbidden descendant '${id}' inside '${rule.component}' (${describeNode(visited)}).`,
+            locationOf(offender),
+          ),
+        );
+      }
+    }
+
+    // v0.4 §4.2: membership resolved through the contract at lint time; the
+    // message names BOTH the concrete id and the matched category so repair
+    // feedback stays actionable without the contract in hand.
+    for (const category of rule.forbiddenCategories ?? []) {
+      for (const offender of descendants) {
+        if (categories?.get(offender.node.component)?.includes(category)) {
+          findings.push(
+            finding(
+              rule,
+              `Forbidden descendant '${offender.node.component}' (category '${category}') inside '${rule.component}' (${describeNode(visited)}).`,
+              locationOf(offender),
+            ),
+          );
+        }
+      }
+    }
+
+    for (const constraint of rule.forbiddenProps ?? []) {
+      const violates = (candidate: VisitedNode): boolean =>
+        constraint.values.includes(candidate.node.props?.[constraint.prop] as never);
+      const targets =
+        constraint.on === undefined ? [visited] : descendants.filter((d) => d.node.component === constraint.on);
+      for (const target of targets.filter(violates)) {
+        findings.push(
+          finding(
+            rule,
+            `Forbidden value ${JSON.stringify(target.node.props?.[constraint.prop])} for prop '${constraint.prop}'${constraint.on ? ` on '${constraint.on}'` : ""}.`,
+            locationOf(target),
+          ),
+        );
+      }
+    }
+  }
+  return findings;
+}
+
+/**
+ * required-props (v0.4 §4.1, as amended 2026-07-04): content every instance
+ * of `component` must carry. `requiredText` looks at the node's own `text`
+ * (textScope "self", the default) or anywhere in its subtree ("subtree" —
+ * for compound wrappers whose documented projections lift a label from
+ * within). Without `within`, EVERY matching node must satisfy. With
+ * `within`, each scope must contain at least one matching descendant, and
+ * AT LEAST ONE of them must satisfy (∃ — the amendment; the original ∀ form
+ * measurably rejected surfaces whose emission succeeds, dspack-gen#24).
+ */
+function evaluateRequiredProps(entry: RuleEntry, surface: Surface): Finding[] {
+  const rule = entry as RequiredPropsRule;
+  const findings: Finding[] = [];
+
+  const hasText = (node: VisitedNode["node"]): boolean => typeof node.text === "string" && node.text.length > 0;
+  const subtreeHasText = (node: VisitedNode["node"]): boolean =>
+    hasText(node) ||
+    (node.children ?? []).some(subtreeHasText) ||
+    Object.values(node.slots ?? {}).some((slot) => slot.some(subtreeHasText));
+
+  /** Violation messages for a node; empty when it satisfies the rule. */
+  const violations = (target: VisitedNode): string[] => {
+    const messages: string[] = [];
+    if (rule.requiredText) {
+      if (rule.textScope === "subtree") {
+        if (!subtreeHasText(target.node)) {
+          messages.push(`'${rule.component}' must carry non-empty text somewhere in its subtree (none found).`);
+        }
+      } else if (!hasText(target.node)) {
+        messages.push(
+          `'${rule.component}' must carry non-empty direct text (its own \`text\` field — text in descendants does not count).`,
+        );
+      }
+    }
+    for (const requirement of rule.requiredProps ?? []) {
+      const value = target.node.props?.[requirement.prop];
+      if (value === undefined) {
+        messages.push(`Required prop '${requirement.prop}' is not present on '${rule.component}' itself.`);
+      } else if (requirement.oneOf && !requirement.oneOf.includes(value as never)) {
+        messages.push(
+          `Required prop '${requirement.prop}' must be one of ${requirement.oneOf.map((v) => JSON.stringify(v)).join(", ")} (got ${JSON.stringify(value)}).`,
+        );
+      }
+    }
+    return messages;
+  };
+
+  if (rule.within === undefined) {
+    for (const target of walkSurface(surface).filter((v) => v.node.component === rule.component)) {
+      for (const message of violations(target)) findings.push(finding(rule, message, locationOf(target)));
+    }
+    return findings;
+  }
+
+  for (const scope of walkSurface(surface).filter((v) => v.node.component === rule.within)) {
+    const targets = descendantsOf(scope).filter((d) => d.node.component === rule.component);
+    if (targets.length === 0) {
+      findings.push(
+        finding(
+          rule,
+          `'${rule.within}' contains no '${rule.component}' to carry the required content.`,
+          locationOf(scope),
+        ),
+      );
+      continue;
+    }
+    // ∃ (amended): at least one matching descendant satisfies; a finding at
+    // the scope only when all of them violate.
+    if (targets.every((target) => violations(target).length > 0)) {
+      findings.push(
+        finding(
+          rule,
+          `No '${rule.component}' inside '${rule.within}' satisfies the required content (${targets.length} checked).`,
+          locationOf(scope),
+        ),
+      );
+    }
+  }
+  return findings;
+}

package/src/core/lint/vocabulary.ts

@@ -0,0 +1,80 @@
+/**
+ * Gate S2 — contract vocabulary. A check on ANY produced surface (model
+ * output, hand-authored, fixture), regardless of how generation was
+ * constrained: the S0 spike caught Ollama's mlx engine silently ignoring
+ * `format`, which is why S2 is never assumed from generation.
+ *
+ * Scope per spec §8: component/sub-component ids, prop names on components,
+ * enum prop values, declared slot names, plus surface-level consistency
+ * (registered intent, matching system name). Deliberately NOT checked:
+ * acceptsChildren semantics, non-enum prop types, ordering.
+ */
+import { type Contract, type Surface, duplicateSubComponentIds, enumValues, subComponentIndex } from "../contract.js";
+import { walkSurface } from "./walk.js";
+
+export function checkVocabulary(surface: Surface, contract: Contract): string[] {
+  const errors: string[] = [];
+  const components = contract.components ?? {};
+  const subIndex = subComponentIndex(contract);
+
+  // Ambiguous vocabulary fails loudly before any id-dependent check — S2 and
+  // rule resolution must never depend on object iteration order (mirrors the
+  // dspack validate harness; spec v0.3 §5).
+  for (const [id, declaredBy] of duplicateSubComponentIds(contract)) {
+    errors.push(
+      `contract: sub-component id '${id}' is declared by multiple components (${declaredBy.join(", ")}); ` +
+        `sub-component ids must be unique document-wide for deterministic S2 and rule resolution`,
+    );
+  }
+
+  if (surface.system !== contract.name) {
+    errors.push(`$.system: surface.system '${surface.system}' does not match contract name '${contract.name}'`);
+  }
+  if (!(contract.intents ?? []).some((i) => i.id === surface.intent)) {
+    errors.push(`$.intent: intent '${surface.intent}' is not registered in the contract`);
+  }
+
+  for (const { node, path } of walkSurface(surface)) {
+    const isComponent = node.component in components;
+    const isSub = subIndex.has(node.component);
+    if (!isComponent && !isSub) {
+      errors.push(`${path}: component '${node.component}' is not a component or sub-component of the contract`);
+      continue;
+    }
+    if (node.props && Object.keys(node.props).length > 0) {
+      if (isSub) {
+        errors.push(`${path}: sub-component '${node.component}' does not declare props in this contract`);
+      } else {
+        const declared = components[node.component].props ?? {};
+        for (const [name, value] of Object.entries(node.props)) {
+          const descriptor = declared[name];
+          if (!descriptor) {
+            errors.push(`${path}: prop '${name}' is not declared on component '${node.component}'`);
+            continue;
+          }
+          const allowed = enumValues(descriptor);
+          if (allowed && !allowed.includes(value)) {
+            errors.push(
+              `${path}: prop '${name}' on '${node.component}' has value ${JSON.stringify(value)}; allowed: ${allowed
+                .map((v) => JSON.stringify(v))
+                .join(", ")}`,
+            );
+          }
+        }
+      }
+    }
+    if (node.slots && isComponent) {
+      const declaredSlots = new Set(
+        (components[node.component].composition?.subComponents ?? [])
+          .map((s) => s.slot)
+          .filter((s): s is string => Boolean(s)),
+      );
+      for (const slot of Object.keys(node.slots)) {
+        if (!declaredSlots.has(slot)) {
+          errors.push(`${path}: slot '${slot}' is not declared on component '${node.component}'`);
+        }
+      }
+    }
+  }
+  return errors;
+}

package/src/core/lint/walk.ts

@@ -0,0 +1,44 @@
+/**
+ * Surface-tree traversal shared by S2 and S3. Paths use the `$.root…` JSONPath
+ * style that findings, the emitter, and the spec's worked failures all share.
+ * "Descendants" (spec §5.3) = everything reachable through `children` and
+ * `slots`, at any depth.
+ */
+import type { Surface, SurfaceNode } from "../contract.js";
+
+export interface VisitedNode {
+  node: SurfaceNode;
+  path: string;
+}
+
+export function walkSurface(surface: Surface): VisitedNode[] {
+  const visited: VisitedNode[] = [];
+  const visit = (node: SurfaceNode, path: string): void => {
+    visited.push({ node, path });
+    (node.children ?? []).forEach((child, i) => visit(child, `${path}.children[${i}]`));
+    for (const slot of Object.keys(node.slots ?? {}).sort()) {
+      node.slots![slot].forEach((child, i) => visit(child, `${path}.slots.${slot}[${i}]`));
+    }
+  };
+  visit(surface.root, "$.root");
+  return visited;
+}
+
+/** Descendants of `origin` (excluding itself), with absolute paths. */
+export function descendantsOf(origin: VisitedNode): VisitedNode[] {
+  const visited: VisitedNode[] = [];
+  const visit = (node: SurfaceNode, path: string): void => {
+    (node.children ?? []).forEach((child, i) => {
+      visited.push({ node: child, path: `${path}.children[${i}]` });
+      visit(child, `${path}.children[${i}]`);
+    });
+    for (const slot of Object.keys(node.slots ?? {}).sort()) {
+      node.slots![slot].forEach((child, i) => {
+        visited.push({ node: child, path: `${path}.slots.${slot}[${i}]` });
+        visit(child, `${path}.slots.${slot}[${i}]`);
+      });
+    }
+  };
+  visit(origin.node, origin.path);
+  return visited;
+}

package/src/core/surface-schema.ts

@@ -0,0 +1,86 @@
+/**
+ * Vendored copy of dspack.surface.v0_1.schema.json (dspack repo, schema/).
+ * Gate S1's ground truth. Re-vendor when the surface schema version bumps;
+ * the const below is asserted against surface documents at lint time.
+ */
+export const SURFACE_SCHEMA_VERSION = "0.1";
+
+export const surfaceSchemaV0_1 = {
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://github.com/aestheticfunction/dspack/blob/main/schema/dspack.surface.v0_1.schema.json",
+  "title": "dspack surface v0.1",
+  "description": "Schema for a dspack surface document — a protocol-neutral, nested component tree expressed in a dspack contract's vocabulary (component IDs, sub-component IDs, props, slots, text leaves) plus a declared generation intent. A surface is the pipeline's intermediate representation: never rendered, never transported, always compiled to a protocol by an emitter. This generic schema is the portable validation floor (gate S1); checking the tree against a specific contract's vocabulary is a separate gate (S2), and governance rules are a third (S3). The schema answers whether the object can exist; the linter answers whether it is correct; a renderer answers whether its compiled form can render. These layers must never collapse.",
+  "type": "object",
+  "required": [
+    "dspackSurface",
+    "system",
+    "intent",
+    "root"
+  ],
+  "properties": {
+    "dspackSurface": {
+      "type": "string",
+      "const": "0.1",
+      "description": "Surface format version. MUST be \"0.1\" for documents conforming to this version."
+    },
+    "system": {
+      "type": "string",
+      "minLength": 1,
+      "description": "Name of the design system contract this surface is expressed against (the contract's top-level name)."
+    },
+    "intent": {
+      "type": "string",
+      "description": "The declared generation intent (an intent ID registered in the bound contract). Declared by the caller, carried in the artifact, and used by the linter to activate intent-scoped rules."
+    },
+    "root": {
+      "$ref": "#/$defs/node",
+      "description": "The root component node of the surface tree."
+    }
+  },
+  "additionalProperties": false,
+  "$defs": {
+    "node": {
+      "type": "object",
+      "description": "A component instance in the surface tree. 'component' is a component ID or sub-component ID from the bound contract's vocabulary.",
+      "required": [
+        "component"
+      ],
+      "properties": {
+        "component": {
+          "type": "string",
+          "description": "Component ID or sub-component ID from the bound contract."
+        },
+        "id": {
+          "type": "string",
+          "description": "Optional stable identifier for this node, used in lint finding locations and emitted artifacts."
+        },
+        "props": {
+          "type": "object",
+          "description": "Prop values for this node. Prop names and enum values are validated against the bound contract (gate S2), not by this schema."
+        },
+        "text": {
+          "type": "string",
+          "description": "Text content for leaf nodes (components or sub-components that accept text children)."
+        },
+        "children": {
+          "type": "array",
+          "description": "Ordered child nodes.",
+          "items": {
+            "$ref": "#/$defs/node"
+          }
+        },
+        "slots": {
+          "type": "object",
+          "description": "Named slot contents, keyed by slot name declared on the parent's sub-components in the bound contract.",
+          "additionalProperties": {
+            "type": "array",
+            "items": {
+              "$ref": "#/$defs/node"
+            }
+          }
+        }
+      },
+      "additionalProperties": false
+    }
+  }
+} as const;

package/src/eval/assert.ts

@@ -0,0 +1,55 @@
+#!/usr/bin/env -S npx tsx
+/**
+ * `npm run eval:assert -- --results <results.json> --model <ref> --min-repair-success 0.9`
+ *
+ * Threshold check over an eval `results.json`: exit 0 when the model's
+ * repair-success rate meets the minimum, exit 2 when it does not (or when
+ * the rate is undefined because no run violated — a threshold over zero
+ * observations is vacuously unmet, stated loudly rather than passed
+ * silently). Per the plan, the hosted-model threshold is the only hard eval
+ * gate in M2; local models are report-only.
+ */
+import { readFileSync } from "node:fs";
+import { resolve } from "node:path";
+import type { EvalResults } from "./types.js";
+
+function fail(message: string): never {
+  console.error(`error: ${message}`);
+  process.exit(1);
+}
+
+const flags = new Map<string, string>();
+const argv = process.argv.slice(2);
+for (let i = 0; i < argv.length; i++) {
+  const token = argv[i];
+  if (!token.startsWith("--")) fail(`unexpected argument '${token}'`);
+  const eq = token.indexOf("=");
+  if (eq !== -1) flags.set(token.slice(2, eq), token.slice(eq + 1));
+  else {
+    const value = argv[++i];
+    if (value === undefined) fail(`flag '${token}' is missing a value`);
+    flags.set(token.slice(2), value);
+  }
+}
+
+const resultsPath = flags.get("results") ?? fail("--results <results.json> is required");
+const model = flags.get("model") ?? fail("--model <ref> is required");
+const minRaw = flags.get("min-repair-success") ?? fail("--min-repair-success <0..1> is required");
+const min = Number(minRaw);
+if (!(min >= 0 && min <= 1)) fail(`--min-repair-success must be in [0,1] (got '${minRaw}')`);
+
+const results = JSON.parse(readFileSync(resolve(resultsPath), "utf8")) as EvalResults;
+const metrics = results.byModel[model];
+if (!metrics) fail(`no results for model '${model}' (models present: ${Object.keys(results.byModel).join(", ")})`);
+
+if (metrics.repairSuccessRate === null) {
+  console.error(
+    `eval:assert FAIL — ${model}: repair-success rate is undefined (no first-attempt violations in ${metrics.runs} run(s)); a threshold cannot be met over zero observations`,
+  );
+  process.exit(2);
+}
+const pass = metrics.repairSuccessRate >= min;
+console.error(
+  `eval:assert ${pass ? "PASS" : "FAIL"} — ${model}: repair-success ${metrics.repairSuccessRate} (min ${min}, over ${metrics.runs} run(s))`,
+);
+process.exit(pass ? 0 : 2);

package/src/eval/run.ts

@@ -0,0 +1,62 @@
+#!/usr/bin/env -S npx tsx
+/**
+ * `npm run eval -- --adapter fake --matrix eval/matrix.fake.json [--out out/eval/fake]`
+ * `npm run eval -- --adapter live --matrix eval/matrix.json      [--out out/eval/<ts>]`
+ *
+ * Fake mode is deterministic (scripted fixtures, fixed clock) and is the CI
+ * gate; live mode talks to the configured providers and is documented, never
+ * CI-gating. Exit 0 on completion (results are data, not a pass/fail —
+ * thresholds are `eval:assert`'s job); exit 1 on usage/internal error.
+ */
+import { runMatrix } from "./runner.js";
+
+function fail(message: string): never {
+  console.error(`error: ${message}`);
+  process.exit(1);
+}
+
+const BOOLEAN_FLAGS = new Set(["resume"]);
+
+function parseFlags(argv: string[]): Map<string, string> {
+  const flags = new Map<string, string>();
+  for (let i = 0; i < argv.length; i++) {
+    const token = argv[i];
+    if (!token.startsWith("--")) fail(`unexpected argument '${token}'`);
+    const eq = token.indexOf("=");
+    if (eq !== -1) flags.set(token.slice(2, eq), token.slice(eq + 1));
+    else if (BOOLEAN_FLAGS.has(token.slice(2))) flags.set(token.slice(2), "true");
+    else {
+      const value = argv[++i];
+      if (value === undefined) fail(`flag '${token}' is missing a value`);
+      flags.set(token.slice(2), value);
+    }
+  }
+  return flags;
+}
+
+async function main(): Promise<void> {
+  const flags = parseFlags(process.argv.slice(2));
+  const adapterMode = flags.get("adapter") ?? fail("--adapter fake|live is required");
+  if (adapterMode !== "fake" && adapterMode !== "live") fail("--adapter must be 'fake' or 'live'");
+  const matrixPath = flags.get("matrix") ?? fail("--matrix <matrix.json> is required");
+  const outDir =
+    flags.get("out") ??
+    (adapterMode === "fake" ? "out/eval/fake" : `out/eval/${new Date().toISOString().replace(/[:.]/g, "-")}`);
+
+  const results = await runMatrix({
+    matrixPath,
+    outDir,
+    adapterMode,
+    // --resume: skip runs whose audit report is already retained in outDir
+    // (contained-error records are retried) — an interrupted matrix picks up
+    // where it stopped instead of re-burning compute.
+    resume: flags.get("resume") === "true",
+    // Fixed clock in fake mode: retained reports and results.json are byte-stable.
+    now: adapterMode === "fake" ? () => new Date("2026-01-01T00:00:00.000Z") : undefined,
+    log: (line) => console.error(line),
+  });
+  const errorRuns = results.cells.reduce((k, c) => k + c.metrics.errorRuns, 0);
+  console.error(`eval: ${results.cells.length} cell(s)${errorRuns ? ` — ${errorRuns} CONTAINED ERROR RUN(S), see .error.json records` : ""} -> ${outDir}/results.json`);
+}
+
+void main();