@skillstech/thunderlang 0.1.6

package/src/simulate.mjs

@@ -0,0 +1,106 @@
+// Intent Simulator (intent-simulate-v1) , estimate the impact of a proposed change BEFORE it is
+// implemented. Where Intent Guardian reports drift AFTER a change, the Simulator runs it forward on
+// a hypothetical: given a base and a proposed intent, it computes the blast radius (which nodes the
+// change transitively touches), the risk it would introduce, contradictions, and release risk , and
+// it clearly SEPARATES deterministic dependency impact from rule-derived risk from unknown impact,
+// per the directive. Deterministic, no AI. Composes the shared spine (diffGraphs + scanProject +
+// the Intent Graph). Pure ESM.
+//
+//   simulateChange(baseFiles, proposedFiles) -> an impact estimate
+
+import { parseIntent } from './parse.mjs';
+import { buildIntentGraph } from './intent-graph.mjs';
+import { diffGraphs } from './semantic-diff.mjs';
+import { scanProject } from './scan.mjs';
+import { isFactual } from './classification.mjs';
+
+export const SIMULATE_SCHEMA = 'intent-simulate-v1';
+
+function mergedGraph(files) {
+  const nodes = []; const relationships = []; const seen = new Set();
+  for (const { source } of files || []) {
+    const g = buildIntentGraph(parseIntent(String(source ?? '')));
+    for (const n of g.nodes) if (!seen.has(n.id)) { seen.add(n.id); nodes.push(n); }
+    relationships.push(...g.relationships);
+  }
+  return { nodes, relationships };
+}
+
+// Transitive reach from the changed nodes over the (undirected) relationship graph, bounded by
+// depth , the deterministic dependency blast radius. Returns a Set of affected node ids.
+function blastRadius(graph, changedIds, maxDepth = 3) {
+  const adj = new Map();
+  const link = (a, b) => { (adj.get(a) ?? adj.set(a, new Set()).get(a)).add(b); };
+  for (const r of graph.relationships || []) { link(r.from, r.to); link(r.to, r.from); }
+  const reached = new Set(changedIds);
+  let frontier = [...changedIds];
+  for (let d = 0; d < maxDepth && frontier.length; d += 1) {
+    const next = [];
+    for (const id of frontier) for (const nb of adj.get(id) ?? []) if (!reached.has(nb)) { reached.add(nb); next.push(nb); }
+    frontier = next;
+  }
+  return reached;
+}
+
+const groupByType = (nodes) => {
+  const by = {};
+  for (const n of nodes) (by[n.type] = by[n.type] || []).push({ id: n.id, title: n.title || null });
+  return by;
+};
+
+/**
+ * Estimate the impact of moving from `baseFiles` to `proposedFiles`.
+ * @param {Array<{file:string,source:string}>} baseFiles
+ * @param {Array<{file:string,source:string}>} proposedFiles
+ */
+export function simulateChange(baseFiles, proposedFiles) {
+  const baseGraph = mergedGraph(baseFiles);
+  const proposedGraph = mergedGraph(proposedFiles);
+  const diff = diffGraphs(baseGraph, proposedGraph);
+
+  // Union graph so reachability covers both removed (base) and added (proposed) nodes.
+  const unionNodes = new Map();
+  for (const n of [...baseGraph.nodes, ...proposedGraph.nodes]) if (!unionNodes.has(n.id)) unionNodes.set(n.id, n);
+  const union = { nodes: [...unionNodes.values()], relationships: [...baseGraph.relationships, ...proposedGraph.relationships] };
+
+  const changedIds = [...new Set([...diff.addedNodes.map((n) => n.id), ...diff.removedNodes.map((n) => n.id), ...diff.changedNodes.map((c) => c.id)])];
+  const reached = blastRadius(union, changedIds);
+  const affectedNodes = [...reached].map((id) => unionNodes.get(id)).filter(Boolean);
+  // The impact set minus the directly-changed nodes = the DEPENDENTS the change ripples out to.
+  const changedSet = new Set(changedIds);
+  const dependents = affectedNodes.filter((n) => !changedSet.has(n.id));
+
+  // Rule-derived risk: findings the proposed state has that the base did not.
+  const baseScan = scanProject(baseFiles);
+  const proposedScan = scanProject(proposedFiles);
+  const baseKeys = new Set(baseScan.findings.map((f) => `${f.ruleId}|${f.detected}`));
+  const introducedRisk = proposedScan.findings.filter((f) => !baseKeys.has(`${f.ruleId}|${f.detected}`));
+  const contradictions = proposedScan.findings.filter((f) => f.category === 'Intent risk' && /IL-CONFLICT/.test(f.ruleId));
+  const releaseRisks = introducedRisk.filter((f) => f.severity === 'blocker' || f.severity === 'error');
+
+  // Unknown impact: changed nodes whose classification is not factual (the estimate is uncertain
+  // there), and any changed node with no relationships (its ripple can't be traced deterministically).
+  const linked = new Set(union.relationships.flatMap((r) => [r.from, r.to]));
+  const unknownImpact = affectedNodes.filter((n) => (n.classification && !isFactual(n.classification)) || !linked.has(n.id))
+    .map((n) => ({ id: n.id, type: n.type, reason: n.classification && !isFactual(n.classification) ? `${n.classification} , impact is uncertain` : 'no relationships , ripple cannot be traced deterministically' }));
+
+  return {
+    schema: SIMULATE_SCHEMA,
+    changedNodes: changedIds.length,
+    // deterministic dependency impact , what the change transitively touches, by type
+    deterministicImpact: { total: dependents.length, byType: groupByType(dependents) },
+    ruleDerivedRisk: introducedRisk,
+    contradictions,
+    releaseRisks,
+    aiPredictedImpact: null, // not computed in deterministic mode (no AI); reserved for the Engine
+    unknownImpact,
+    summary: {
+      changed: changedIds.length,
+      dependentsAffected: dependents.length,
+      introducedRisk: introducedRisk.length,
+      releaseBlocking: releaseRisks.length,
+      contradictions: contradictions.length,
+      safe: releaseRisks.length === 0 && contradictions.length === 0,
+    },
+  };
+}

package/src/style.mjs

@@ -0,0 +1,250 @@
+// Style Intent (intent-style-v1) , brand + visual language as a governed, deterministic
+// extension of the Experience profile. IL owns the canonical token address space and the
+// accessibility-target vocabulary so ST (Studio), STW (theming), and every renderer bind
+// to ONE schema instead of forking their own token trees.
+//
+// Two load-bearing rules, enforced here (no AI):
+//   1. Tokens address a CANONICAL, lockable namespace. An off-namespace path is a typo or
+//      a private fork , flagged, so the design system stays a closed vocabulary.
+//   2. `accessibility_target` is ALWAYS a PROPOSED claim. IL never lets a StyleIntent
+//      assert it is `verified`/compliant , conformance is OT's verdict after real testing.
+
+import { slug } from './parse.mjs';
+
+export const STYLE_SCHEMA = 'intent-style-v1';
+
+// Canonical, lockable design-token address space. A StyleIntent may only bind these paths
+// (plus the non-token brand.* addresses below). Extending the set is a request to IL, not a
+// private addition , that is what keeps themes portable across Studio, storefronts, and docs.
+export const TOKEN_PATHS = [
+  'color.primary', 'color.accent', 'color.surface', 'color.text',
+  'color.feedback.success', 'color.feedback.warning', 'color.feedback.error', 'color.feedback.info',
+  'typography.scale', 'typography.headingWeight',
+  'typography.families.heading', 'typography.families.body', 'typography.families.mono',
+  'shape.radius', 'shape.borders', 'shape.elevation',
+  'density', 'mode',
+];
+
+// Non-token, lockable brand addresses (assets, not scalar tokens).
+export const BRAND_PATHS = ['brand.logo'];
+
+// The full lockable address space a StyleIntent may bind.
+export const STYLE_ADDRESS_SPACE = [...TOKEN_PATHS, ...BRAND_PATHS];
+
+// Accessibility targets IL recognizes. Always a GOAL (classification `proposed`), never a
+// proof of conformance. `mode` token values are constrained separately.
+export const ACCESSIBILITY_TARGETS = ['WCAG_2_1_AA', 'WCAG_2_2_AA', 'WCAG_2_2_AAA'];
+
+// Legal values for the `mode` token.
+export const MODE_VALUES = ['light', 'dark', 'auto', 'both'];
+
+/** IL's stance: an accessibility target is a proposed goal, never IL-verified. */
+export const ACCESSIBILITY_CLASSIFICATION = 'proposed';
+
+export const DESIGN_TOKENS_SCHEMA = 'intent-design-tokens-v1';
+
+// A canonical token address -> a CSS custom-property name: dots become hyphens and camelCase
+// segments are kebab-cased. `color.feedback.error` -> `--color-feedback-error`,
+// `typography.headingWeight` -> `--typography-heading-weight`.
+function cssVarName(path) {
+  return `--${String(path).split('.').map((seg) => seg.replace(/([a-z0-9])([A-Z])/g, '$1-$2').toLowerCase()).join('-')}`;
+}
+
+const isKnownPath = (p) => STYLE_ADDRESS_SPACE.includes(p);
+
+// W3C Design Tokens (DTCG) `$type` for a canonical token address.
+function tokenType(path) {
+  if (path === 'brand.logo') return 'asset';
+  if (path === 'mode') return 'other';
+  if (path === 'density') return 'number';
+  if (path.startsWith('color.')) return 'color';
+  if (path.startsWith('typography.families.')) return 'fontFamily';
+  if (path === 'typography.scale' || path === 'typography.headingWeight') return 'number';
+  if (path.startsWith('shape.')) return 'dimension';
+  return 'other';
+}
+
+// Coerce a raw token value: bare numerics become numbers; everything else stays a string.
+function coerceValue(v) {
+  if (v == null) return null;
+  return /^-?\d+(?:\.\d+)?$/.test(v) ? Number(v) : v;
+}
+
+// Set a dotted address to a leaf value inside a nested group tree (last write wins).
+function setPath(root, path, leaf) {
+  const parts = path.split('.');
+  let cur = root;
+  for (let i = 0; i < parts.length - 1; i += 1) {
+    const k = parts[i];
+    if (typeof cur[k] !== 'object' || cur[k] === null || '$value' in cur[k]) cur[k] = {};
+    cur = cur[k];
+  }
+  cur[parts[parts.length - 1]] = leaf;
+}
+
+/**
+ * Deterministic diagnostics for every `style_intent` block. Returns an array of
+ * { ruleId, severity, blocks, message, styleIntent, line } , the same shape the rest of
+ * the compiler emits, so it composes into `intent check` with no special-casing.
+ */
+export function styleDiagnostics(ast) {
+  const out = [];
+  const styles = ast.styleIntents || [];
+  const experienceNames = new Set((ast.experiences || []).map((e) => slug(e.name || '')));
+
+  for (const si of styles) {
+    const where = si.line;
+    const label = si.name || '(unnamed)';
+
+    // IL-STYLE-001 , off-namespace token path (typo or private fork of the token tree).
+    for (const t of si.tokens) {
+      if (!isKnownPath(t.path)) {
+        out.push({
+          ruleId: 'IL-STYLE-001', severity: 'warning', blocks: [],
+          message: `Style intent "${label}" binds unknown token "${t.path}". Use a canonical address (see intent-style-v1) or request the extension from IL.`,
+          styleIntent: label, line: t.line ?? where,
+        });
+      }
+    }
+
+    // IL-STYLE-002 , unrecognized accessibility target.
+    if (si.accessibilityTarget && !ACCESSIBILITY_TARGETS.includes(si.accessibilityTarget)) {
+      out.push({
+        ruleId: 'IL-STYLE-002', severity: 'warning', blocks: [],
+        message: `Style intent "${label}" declares unknown accessibility_target "${si.accessibilityTarget}". Expected one of: ${ACCESSIBILITY_TARGETS.join(', ')}.`,
+        styleIntent: label, line: where,
+      });
+    }
+
+    // IL-STYLE-003 , no accessibility target declared. A style intent should state the
+    // conformance goal it is designing toward (as a proposed claim), so OT can later verify it.
+    if (!si.accessibilityTarget) {
+      out.push({
+        ruleId: 'IL-STYLE-003', severity: 'info', blocks: [],
+        message: `Style intent "${label}" declares no accessibility_target. State the goal (e.g. WCAG_2_2_AA) , it is a proposed claim OT verifies, never assumed met.`,
+        styleIntent: label, line: where,
+      });
+    }
+
+    // IL-STYLE-004 , invalid `mode` token value.
+    for (const t of si.tokens) {
+      if (t.path === 'mode' && t.value && !MODE_VALUES.includes(t.value)) {
+        out.push({
+          ruleId: 'IL-STYLE-004', severity: 'warning', blocks: [],
+          message: `Style intent "${label}" sets mode "${t.value}"; expected one of: ${MODE_VALUES.join(', ')}.`,
+          styleIntent: label, line: t.line ?? where,
+        });
+      }
+    }
+
+    // IL-STYLE-005 , applies_to references an experience that isn't declared here.
+    if (si.appliesTo && experienceNames.size && !experienceNames.has(slug(si.appliesTo))) {
+      out.push({
+        ruleId: 'IL-STYLE-005', severity: 'info', blocks: [],
+        message: `Style intent "${label}" applies_to "${si.appliesTo}", which is not a declared experience in this file.`,
+        styleIntent: label, line: where,
+      });
+    }
+  }
+  return out;
+}
+
+/**
+ * A structured, deterministic view of the style intents in a document , the payload
+ * Studio/renderers consume. Tokens are resolved against the canonical address space and
+ * the accessibility target is stamped with its (always proposed) classification.
+ */
+export function analyzeStyle(ast) {
+  const styles = (ast.styleIntents || []).map((si) => ({
+    id: `style.${slug(si.name || 'style')}`,
+    name: si.name,
+    appliesTo: si.appliesTo,
+    purpose: si.purpose,
+    audience: si.audience,
+    surfaces: si.surfaces,
+    scope: si.scope,
+    accessibility: si.accessibilityTarget
+      ? { target: si.accessibilityTarget, classification: ACCESSIBILITY_CLASSIFICATION, verified: false }
+      : null,
+    tokens: si.tokens.map((t) => ({ path: t.path, value: t.value, canonical: isKnownPath(t.path) })),
+  }));
+  return {
+    schema: STYLE_SCHEMA,
+    styleIntents: styles,
+    diagnostics: styleDiagnostics(ast),
+    addressSpace: STYLE_ADDRESS_SPACE,
+    accessibilityTargets: ACCESSIBILITY_TARGETS,
+  };
+}
+
+/**
+ * Render the style intents' tokens as a W3C Design Tokens (DTCG) document , the standard
+ * shape Style Dictionary, Figma Tokens, and CSS pipelines consume. Deterministic and pure.
+ * Every declared token is emitted (canonical or not); accessibility targets ride along in
+ * `$extensions` as PROPOSED claims, never as verified conformance. Empty-but-valid when a
+ * file declares no style intents.
+ */
+export function toDesignTokens(ast) {
+  const styles = ast.styleIntents || [];
+  const root = {};
+  const provenance = [];
+  for (const si of styles) {
+    provenance.push({
+      name: si.name || null,
+      purpose: si.purpose || null,
+      appliesTo: si.appliesTo || null,
+      accessibility: si.accessibilityTarget
+        ? { target: si.accessibilityTarget, classification: ACCESSIBILITY_CLASSIFICATION, verified: false }
+        : null,
+    });
+    for (const t of si.tokens) {
+      const leaf = { $value: coerceValue(t.value), $type: tokenType(t.path) };
+      if (!isKnownPath(t.path)) leaf.$extensions = { 'dev.thunderlang': { canonical: false } };
+      setPath(root, t.path, leaf);
+    }
+  }
+  return {
+    $description: `Design tokens for ${ast.title || ast.mission || 'intent'} (generated from style_intent by @skillstech/thunderlang)`,
+    ...root,
+    $extensions: {
+      'dev.thunderlang': {
+        schema: DESIGN_TOKENS_SCHEMA,
+        format: 'W3C Design Tokens (DTCG)',
+        source: ast.mission || null,
+        styleIntents: provenance,
+        note: 'accessibility targets are proposed claims, not verified conformance',
+      },
+    },
+  };
+}
+
+/**
+ * Render the style intents' tokens as a ready-to-use CSS custom-property sheet , the direct,
+ * no-external-tool last mile of the token pipeline. Every canonical address becomes a
+ * `--kebab-case` variable on `:root`; a `mode` token drives `color-scheme`; `brand.logo`
+ * becomes a `url(...)`. Accessibility targets appear only as comments (proposed, never a
+ * guarantee). Deterministic; empty-but-valid `:root {}` when nothing is declared.
+ */
+export function toCss(ast) {
+  const styles = ast.styleIntents || [];
+  const title = ast.title || ast.mission || 'intent';
+  const head = [`/* Design tokens for ${title} , generated from style_intent by @skillstech/thunderlang. */`];
+  for (const si of styles) {
+    if (si.accessibilityTarget) head.push(`/* ${si.name || 'style'}: accessibility target ${si.accessibilityTarget} (proposed, not verified). */`);
+  }
+  const vars = new Map(); // path -> declaration value (last write wins, dedup, order-stable)
+  let colorScheme = null;
+  for (const si of styles) {
+    for (const t of si.tokens) {
+      if (t.path === 'mode') {
+        const m = String(t.value || '').toLowerCase();
+        colorScheme = m === 'light' ? 'light' : m === 'dark' ? 'dark' : (m === 'both' || m === 'auto') ? 'light dark' : null;
+      }
+      const value = t.path === 'brand.logo' && t.value ? `url(${t.value})` : (t.value ?? '');
+      vars.set(t.path, value);
+    }
+  }
+  const body = [...vars].map(([path, value]) => `  ${cssVarName(path)}: ${value};`);
+  if (colorScheme) body.push(`  color-scheme: ${colorScheme};`);
+  return `${head.join('\n')}\n:root {\n${body.join('\n')}${body.length ? '\n' : ''}}\n`;
+}

package/src/sync.mjs

@@ -0,0 +1,103 @@
+// Human <-> Structured <-> ThunderLang synchronization (intent-sync-v1). IL owns the boundary
+// between a plain-language / structured editor (SkillsTech Studio) and canonical ThunderLang,
+// so a non-developer edits structured fields and IL stays the source of truth , never a silent
+// rewrite. Pure ESM, ZERO Node deps: browser-safe for Studio's Vite build.
+//
+//   parseToStructured(source) -> the canonical structured view (intent graph + flat fields)
+//   proposeIntent(structured, { base }) -> { source, diff, ambiguities, warnings } , a PROPOSAL
+//     the caller reviews and applies; it is never applied here, and ambiguity is surfaced,
+//     not guessed.
+
+import { parseIntent } from './parse.mjs';
+import { buildIntentGraph } from './intent-graph.mjs';
+import { graphToSource } from './graph-source.mjs';
+import { diffGraphs } from './semantic-diff.mjs';
+import { validateGraph } from './migrate.mjs';
+import { isFactual } from './classification.mjs';
+
+export const SYNC_SCHEMA = 'intent-sync-v1';
+
+const hasComments = (src) => typeof src === 'string' && /(^|\s)#/.test(src);
+
+/**
+ * The canonical structured view of ThunderLang source: the intent graph a projector (Studio's
+ * ProjectNode/ProjectEdge) builds from, plus a flat, PM-friendly field summary. IL stays the
+ * source of truth; this is a projection of it.
+ */
+export function parseToStructured(source) {
+  const ast = parseIntent(String(source ?? ''));
+  const graph = buildIntentGraph(ast);
+  const fields = {
+    mission: ast.mission || null,
+    title: ast.title || null,
+    goal: ast.goal || null,
+    why: ast.why || null,
+    guarantees: (ast.guarantees || []).map((g) => g.statement),
+    neverRules: (ast.neverRules || []).map((n) => n.statement),
+    inputs: (ast.inputs || []).map((f) => ({ name: f.name, type: f.type })),
+    outputs: (ast.outputs || []).map((f) => ({ name: f.name, type: f.type })),
+    decisions: (ast.decisions || []).map((d) => d.name),
+    lifecycles: (ast.lifecycles || []).map((l) => l.name),
+    outcomes: (ast.outcomes || []).map((o) => o.name),
+  };
+  return { schema: SYNC_SCHEMA, mission: fields.mission, graph, fields };
+}
+
+// Non-factual (proposed/assumed/inferred/unknown) nodes are decisions a human still owes , the
+// "return a proposal, not a guess" surface.
+function collectAmbiguities(graph) {
+  const out = [];
+  for (const n of graph.nodes || []) {
+    if (n.classification && !isFactual(n.classification)) {
+      out.push({ id: n.id, type: n.type, title: n.title || null, classification: n.classification, reason: `${n.classification} , confirm before treating as fact` });
+    }
+  }
+  return out;
+}
+
+/**
+ * Propose ThunderLang source from a structured graph, with a REVIEWABLE diff against the base.
+ * Accepts a graph, `{ graph }`, or the object `parseToStructured` returns. `base` may be the
+ * prior ThunderLang source (string) or its graph. Returns a proposal , it is never applied.
+ *
+ * Fidelity is honest: regenerating source from a graph does NOT preserve free-text comments;
+ * when the base carried comments, that is surfaced as a warning so the caller keeps the base
+ * source and applies structural edits rather than overwriting it.
+ */
+export function proposeIntent(structured, { base = null } = {}) {
+  const graph = structured && structured.graph ? structured.graph : structured;
+  if (!graph || !Array.isArray(graph.nodes)) {
+    return { schema: SYNC_SCHEMA, ok: false, error: 'proposeIntent expects an intent graph (or { graph }).' };
+  }
+
+  const source = graphToSource(graph);
+
+  // Round-trip check: does the proposed source rebuild the same node set? Anything dropped is a
+  // fidelity ambiguity the caller should see (not silently lost).
+  const roundGraph = buildIntentGraph(parseIntent(source));
+  const roundIds = new Set(roundGraph.nodes.map((n) => n.id));
+  const lostNodes = graph.nodes.filter((n) => n.id && !roundIds.has(n.id)).map((n) => ({ id: n.id, type: n.type, title: n.title || null }));
+
+  const baseGraph = typeof base === 'string' ? buildIntentGraph(parseIntent(base)) : (base && base.graph) || base || null;
+  const diff = baseGraph && Array.isArray(baseGraph.nodes) ? diffGraphs(baseGraph, graph) : null;
+
+  const validation = validateGraph(graph);
+  const ambiguities = collectAmbiguities(graph);
+
+  const warnings = [];
+  if (hasComments(base)) warnings.push('Regenerating source from the graph does not preserve free-text comments in the base. To keep comments, use applyEdits(base, edits) (intent-patch-v1) to edit the source in place instead of replacing it.');
+  if (lostNodes.length) warnings.push(`${lostNodes.length} node(s) did not survive the graph->source round-trip; review before applying.`);
+  if (!validation.valid) warnings.push('Proposed graph has validation issues (see validation).');
+
+  return {
+    schema: SYNC_SCHEMA,
+    ok: true,
+    source,
+    diff,          // reviewable: added/removed/changed nodes + relationships + invalidated approvals
+    ambiguities,   // non-factual nodes: proposals, not guesses
+    lostNodes,     // round-trip fidelity gaps
+    validation,    // canonical-vocabulary + no-dangling check
+    warnings,
+    applied: false, // NEVER a silent rewrite; the caller reviews and applies
+  };
+}

package/src/testing.mjs

@@ -0,0 +1,59 @@
+// First-class tests , make a .intent file SELF-VERIFYING. A `test <target>` block declares
+// cases (for a decision) or scenarios (for a lifecycle) right next to the intent they check.
+// `runTests` executes them through the deterministic Intent Runtime: no AI, no code, the
+// spec proves itself. This is what lets intent be trustworthy , the behavior is asserted.
+
+import { slug } from './parse.mjs';
+import { evaluateDecision, simulateLifecycle } from './runtime.mjs';
+
+export const TEST_SCHEMA = 'intent-test-v1';
+
+// Coerce declared `given` values: numeric-looking -> number, true/false -> boolean, else
+// string. A value wrapped in matching quotes is treated as a string with the quotes stripped,
+// so `given severity "high"` and `given severity high` behave identically.
+function coerce(given) {
+  const out = {};
+  for (const [k, raw] of Object.entries(given || {})) {
+    const v = String(raw).trim();
+    const quoted = v.length >= 2 && ((v[0] === '"' && v[v.length - 1] === '"') || (v[0] === "'" && v[v.length - 1] === "'"));
+    if (quoted) out[k] = v.slice(1, -1);
+    else if (v === 'true' || v === 'false') out[k] = v === 'true';
+    else if (v !== '' && !isNaN(Number(v))) out[k] = Number(v);
+    else out[k] = v;
+  }
+  return out;
+}
+
+/**
+ * Run every `test` block in an AST against its target decision or lifecycle.
+ * @returns {{schema, total, passed, failed, results, ok}}
+ */
+export function runTests(ast) {
+  const decisions = ast.decisions || [];
+  const lifecycles = ast.lifecycles || [];
+  const results = [];
+
+  for (const t of ast.tests || []) {
+    const dec = decisions.find((d) => slug(d.name) === slug(t.name || ''));
+    const lc = lifecycles.find((l) => slug(l.name) === slug(t.name || ''));
+    for (const c of t.cases) {
+      const label = { target: t.name, case: c.name || `case ${results.length + 1}` };
+      if (dec) {
+        const inputs = coerce(c.given);
+        const run = evaluateDecision(dec, inputs);
+        const pass = c.expect == null || String(run.result) === String(c.expect);
+        results.push({ ...label, kind: 'decision', expected: c.expect, actual: run.result, pass, ...(run.ok ? {} : { note: 'a condition failed to evaluate' }) });
+      } else if (lc) {
+        const sim = simulateLifecycle(lc, c.events || []);
+        const passState = c.expect == null || sim.finalState === c.expect;
+        const passValid = c.expectValid == null || sim.valid === c.expectValid;
+        results.push({ ...label, kind: 'lifecycle', expected: c.expect, actual: sim.finalState, valid: sim.valid, expectValid: c.expectValid, pass: passState && passValid });
+      } else {
+        results.push({ ...label, kind: 'unknown', pass: false, error: `no decision or lifecycle named "${t.name}"` });
+      }
+    }
+  }
+
+  const passed = results.filter((r) => r.pass).length;
+  return { schema: TEST_SCHEMA, total: results.length, passed, failed: results.length - passed, results, ok: passed === results.length };
+}