@skillstech/thunderlang 0.1.6

package/src/lsp.mjs

@@ -0,0 +1,152 @@
+// A minimal Language Server for ThunderLang (LSP over stdio). Wraps the compiler's existing
+// diagnostics + IntelliSense so ANY LSP-capable editor (VS Code, Neovim, Helix, ...) gets
+// live ThunderLang intelligence: diagnostics on open/change, keyword/type completions, and
+// hover docs for semantic types and note lenses. Deterministic; no AI. `intent lsp` starts it.
+
+import { parseIntent } from './parse.mjs';
+import { semanticDiagnostics } from './emit.mjs';
+import { getCompletions, getHover } from './intellisense.mjs';
+import { COMPILER_VERSION } from './emit.mjs';
+
+// LSP CompletionItemKind numbers for the kinds IntelliSense returns.
+const COMPLETION_KIND = { keyword: 14, semantic_type: 7, field: 5, snippet: 15, value: 12, block: 14 };
+// LSP DiagnosticSeverity: 1 error, 2 warning, 3 info, 4 hint.
+const SEVERITY = { error: 1, warning: 2, info: 3 };
+
+// Diagnostics don't carry a source span, so anchor them best-effort: to the line containing
+// the quoted subject in the message, else the mission line, else line 0.
+function anchorLine(message, lines) {
+  const q = String(message || '').match(/"([^"]+)"/);
+  if (q) { const i = lines.findIndex((l) => l.includes(q[1])); if (i >= 0) return i; }
+  const m = lines.findIndex((l) => /^mission\b/.test(l.trim()));
+  return m >= 0 ? m : 0;
+}
+
+function toLspDiagnostic(d, lines) {
+  const line = anchorLine(d.message, lines);
+  const text = lines[line] || '';
+  return {
+    range: { start: { line, character: 0 }, end: { line, character: Math.max(1, text.length) } },
+    severity: SEVERITY[d.level] || 3,
+    code: d.code,
+    source: 'thunderlang',
+    message: d.message + (d.why ? `\n\n${d.why}` : ''),
+  };
+}
+
+function toLspCompletion(item) {
+  const insert = item.insertText || item.label;
+  return {
+    label: item.label,
+    kind: COMPLETION_KIND[item.kind] || 1,
+    detail: item.detail || undefined,
+    insertText: insert,
+    insertTextFormat: /\$\{|\$\d/.test(insert) ? 2 : 1, // 2 = snippet, 1 = plaintext
+    sortText: item.sortText || undefined,
+  };
+}
+
+function toLspHover(out) {
+  const h = out && out.hover;
+  if (!h) return null;
+  const parts = [h.title ? `**${h.title}**` : null, h.description || null];
+  if (Array.isArray(h.examples) && h.examples.length) parts.push('```\n' + h.examples.join('\n') + '\n```');
+  return { contents: { kind: 'markdown', value: parts.filter(Boolean).join('\n\n') } };
+}
+
+/**
+ * Start the language server. Reads LSP JSON-RPC (Content-Length framed) from `readable` and
+ * writes responses to `writable`. Testable: pass in-memory streams. Returns nothing.
+ */
+export function startLspServer({ readable = process.stdin, writable = process.stdout } = {}) {
+  const docs = new Map(); // uri -> text
+  let buffer = Buffer.alloc(0);
+
+  const send = (msg) => {
+    const payload = Buffer.from(JSON.stringify(msg), 'utf8');
+    writable.write(`Content-Length: ${payload.length}\r\n\r\n`);
+    writable.write(payload);
+  };
+  const respond = (id, result) => send({ jsonrpc: '2.0', id, result });
+  const notify = (method, params) => send({ jsonrpc: '2.0', method, params });
+
+  const publish = (uri) => {
+    const lines = (docs.get(uri) || '').split('\n');
+    let diags;
+    try { diags = semanticDiagnostics(parseIntent(docs.get(uri) || '')); } catch { diags = []; }
+    notify('textDocument/publishDiagnostics', { uri, diagnostics: diags.map((d) => toLspDiagnostic(d, lines)) });
+  };
+
+  const handle = (msg) => {
+    switch (msg.method) {
+      case 'initialize':
+        respond(msg.id, {
+          capabilities: {
+            textDocumentSync: 1, // full document sync
+            completionProvider: { triggerCharacters: [' '] },
+            hoverProvider: true,
+          },
+          serverInfo: { name: 'thunderlang-lsp', version: COMPILER_VERSION },
+        });
+        break;
+      case 'initialized':
+        break;
+      case 'shutdown':
+        respond(msg.id, null);
+        break;
+      case 'exit':
+        process.exit(0);
+        break;
+      case 'textDocument/didOpen':
+        docs.set(msg.params.textDocument.uri, msg.params.textDocument.text || '');
+        publish(msg.params.textDocument.uri);
+        break;
+      case 'textDocument/didChange': {
+        const changes = msg.params.contentChanges || [];
+        if (changes.length) docs.set(msg.params.textDocument.uri, changes[changes.length - 1].text || '');
+        publish(msg.params.textDocument.uri);
+        break;
+      }
+      case 'textDocument/didClose':
+        docs.delete(msg.params.textDocument.uri);
+        break;
+      case 'textDocument/completion': {
+        const text = docs.get(msg.params.textDocument.uri) || '';
+        const p = msg.params.position;
+        let items = [];
+        try { items = (getCompletions(text, { line: p.line + 1, column: p.character + 1 }).items || []); } catch { items = []; }
+        respond(msg.id, items.map(toLspCompletion));
+        break;
+      }
+      case 'textDocument/hover': {
+        const text = docs.get(msg.params.textDocument.uri) || '';
+        const p = msg.params.position;
+        let hover = null;
+        try { hover = toLspHover(getHover(text, { line: p.line + 1, column: p.character + 1 })); } catch { hover = null; }
+        respond(msg.id, hover);
+        break;
+      }
+      default:
+        if (msg.id != null) respond(msg.id, null); // unknown request -> empty result, keep alive
+    }
+  };
+
+  readable.on('data', (chunk) => {
+    buffer = Buffer.concat([buffer, chunk]);
+    for (;;) {
+      const headerEnd = buffer.indexOf('\r\n\r\n');
+      if (headerEnd < 0) break;
+      const header = buffer.slice(0, headerEnd).toString('ascii');
+      const m = header.match(/Content-Length:\s*(\d+)/i);
+      if (!m) { buffer = buffer.slice(headerEnd + 4); continue; }
+      const len = Number(m[1]);
+      const start = headerEnd + 4;
+      if (buffer.length < start + len) break; // wait for the rest of the body
+      const body = buffer.slice(start, start + len).toString('utf8');
+      buffer = buffer.slice(start + len);
+      let msg;
+      try { msg = JSON.parse(body); } catch { continue; }
+      try { handle(msg); } catch { /* one bad message must not kill the server */ }
+    }
+  });
+}

package/src/mcp.mjs

@@ -0,0 +1,158 @@
+// ThunderLang MCP server , makes ThunderLang a first-class tool for AI coding agents (Claude
+// Code, Cursor, ...). It speaks the Model Context Protocol over stdio (newline-delimited
+// JSON-RPC 2.0) and exposes the deterministic capabilities an agent needs to author intent,
+// check its own output, and , the keystone , verify a proposed code change against the intent
+// before it ships. No AI runs here; every tool is the pure, deterministic compiler.
+//
+// Start it with `intent mcp`. Point an MCP client at that command.
+
+import { parseIntent } from './parse.mjs';
+import { semanticDiagnostics, COMPILER_VERSION } from './emit.mjs';
+import { verifyDiff } from './verify-diff.mjs';
+import { liftSource, SUPPORTED_LANGUAGES } from './lift.mjs';
+import { runTests } from './testing.mjs';
+import { evaluateDecision } from './runtime.mjs';
+import { buildIntentGraph } from './intent-graph.mjs';
+import { draftIntent } from './draft.mjs';
+import { ALL_DIAGNOSTICS } from './intent-schema.mjs';
+
+const PROTOCOL_VERSION = '2024-11-05';
+const str = { type: 'string' };
+
+// Each tool is a pure function of its arguments. `run` returns a JSON-able value or a string.
+const TOOLS = [
+  {
+    name: 'intent_check',
+    description: 'Run ThunderLang semantic diagnostics on .intent source. Returns the diagnostics (codes, severity, messages) , the deterministic checks that catch missing verification, secrets on the bus, contradictions, and more.',
+    inputSchema: { type: 'object', required: ['source'], properties: { source: { ...str, description: 'the .intent source' } } },
+    run: ({ source }) => {
+      const diagnostics = semanticDiagnostics(parseIntent(String(source)));
+      return { ok: !diagnostics.some((d) => d.level === 'error'), count: diagnostics.length, diagnostics };
+    },
+  },
+  {
+    name: 'intent_verify_diff',
+    description: 'THE AI-LOOP GATE. Prove, deterministically, which of an intent\'s guarantees and never-rules a code change upholds or breaks. Returns verdict PASS or BLOCK. Blocks on regressions (a claim that held on `before` and broke on `after`) and guardrail hits (an added line pushing a protected secret into a log/response). Call this on your own proposed change before shipping it.',
+    inputSchema: {
+      type: 'object', required: ['intent', 'after'],
+      properties: {
+        intent: { ...str, description: 'the .intent source (the contract)' },
+        after: { ...str, description: 'the proposed/changed code' },
+        before: { ...str, description: 'the code before the change (optional; enables regression detection)' },
+        language: { ...str, description: `source language (default typescript). One of: ${SUPPORTED_LANGUAGES.join(', ')}` },
+      },
+    },
+    run: ({ intent, after, before = null, language = 'typescript' }) => verifyDiff(String(intent), { before: before == null ? null : String(before), after: String(after), language }),
+  },
+  {
+    name: 'intent_draft',
+    description: 'Turn a STRUCTURED brief into a rigorous, canonically-formatted ThunderLang draft plus a review checklist of what a human must still fill in (unverified guarantees, unguarded secrets, missing goal). Use this after distilling a user request into structured fields; the draft is a proposal for human approval, never verified.',
+    inputSchema: {
+      type: 'object', required: ['brief'],
+      properties: { brief: { type: 'object', description: 'fields: mission, goal, actor, problem, guarantees[], neverRules[], inputs[{name,type}], outputs[], decisions[]' } },
+    },
+    run: ({ brief }) => draftIntent(brief || {}),
+  },
+  {
+    name: 'intent_lift',
+    description: 'Lift source code into an inferred, humble ThunderLang draft (never claims verified). Covers the top languages. Use it to bootstrap intent from code you already have.',
+    inputSchema: {
+      type: 'object', required: ['source'],
+      properties: { source: { ...str, description: 'the source code' }, language: { ...str, description: `source language (default typescript). One of: ${SUPPORTED_LANGUAGES.join(', ')}` } },
+    },
+    run: ({ source, language = 'typescript' }) => {
+      const r = liftSource(String(source), { language });
+      return r.ok ? { ok: true, intent: r.intentText, summary: r.summary, diagnostics: r.diagnostics } : { ok: false, error: r.error };
+    },
+  },
+  {
+    name: 'intent_run',
+    description: 'Evaluate a decision in .intent source against concrete inputs (FIRST-hit, with a per-rule trace). Deterministic , the intent itself decides.',
+    inputSchema: {
+      type: 'object', required: ['source', 'inputs'],
+      properties: { source: str, inputs: { type: 'object', description: 'the input values' }, decision: { ...str, description: 'decision name (default: the first declared)' } },
+    },
+    run: ({ source, inputs = {}, decision }) => {
+      const ast = parseIntent(String(source));
+      const d = decision ? (ast.decisions || []).find((x) => x.name === decision) : (ast.decisions || [])[0];
+      if (!d) return { error: decision ? `no decision "${decision}"` : 'no decision declared' };
+      return evaluateDecision(d, inputs);
+    },
+  },
+  {
+    name: 'intent_test',
+    description: 'Run the in-file test blocks (case/scenario) in .intent source through the deterministic runtime. The spec proves itself.',
+    inputSchema: { type: 'object', required: ['source'], properties: { source: str } },
+    run: ({ source }) => runTests(parseIntent(String(source))),
+  },
+  {
+    name: 'intent_graph',
+    description: 'Build the canonical Intent Graph (intent-graph-v1) from .intent source , the typed nodes + relationships other tools reason over.',
+    inputSchema: { type: 'object', required: ['source'], properties: { source: str } },
+    run: ({ source }) => buildIntentGraph(parseIntent(String(source))),
+  },
+  {
+    name: 'intent_explain',
+    description: 'Explain a diagnostic code (area, severity, what it blocks). Accepts any code the compiler emits.',
+    inputSchema: { type: 'object', required: ['code'], properties: { code: { ...str, description: 'e.g. IL-SEC-001' } } },
+    run: ({ code }) => ALL_DIAGNOSTICS.find((r) => r.ruleId.toLowerCase() === String(code).toLowerCase()) || { code, found: false },
+  },
+];
+
+export const MCP_TOOLS = TOOLS.map((t) => t.name);
+
+/** Start the ThunderLang MCP server over the given streams (default: process stdio). */
+export function startMcpServer({ readable = process.stdin, writable = process.stdout } = {}) {
+  const send = (msg) => writable.write(`${JSON.stringify(msg)}\n`);
+  const respond = (id, result) => send({ jsonrpc: '2.0', id, result });
+  const fail = (id, code, message) => send({ jsonrpc: '2.0', id, error: { code, message } });
+
+  function handle(msg) {
+    const { id, method, params } = msg || {};
+    switch (method) {
+      case 'initialize':
+        respond(id, { protocolVersion: PROTOCOL_VERSION, capabilities: { tools: {} }, serverInfo: { name: 'thunderlang', version: COMPILER_VERSION } });
+        break;
+      case 'notifications/initialized':
+      case 'initialized':
+      case 'notifications/cancelled':
+        break; // notifications , no response
+      case 'ping':
+        respond(id, {});
+        break;
+      case 'tools/list':
+        respond(id, { tools: TOOLS.map((t) => ({ name: t.name, description: t.description, inputSchema: t.inputSchema })) });
+        break;
+      case 'tools/call': {
+        const tool = TOOLS.find((t) => t.name === params?.name);
+        if (!tool) { fail(id, -32602, `Unknown tool: ${params?.name}`); break; }
+        try {
+          const result = tool.run(params.arguments || {});
+          const text = typeof result === 'string' ? result : JSON.stringify(result, null, 2);
+          respond(id, { content: [{ type: 'text', text }] });
+        } catch (e) {
+          respond(id, { content: [{ type: 'text', text: `Error: ${e instanceof Error ? e.message : String(e)}` }], isError: true });
+        }
+        break;
+      }
+      default:
+        if (id != null) fail(id, -32601, `Method not found: ${method}`);
+    }
+  }
+
+  let buffer = '';
+  readable.on('data', (chunk) => {
+    buffer += chunk.toString('utf8');
+    let nl;
+    while ((nl = buffer.indexOf('\n')) >= 0) {
+      const line = buffer.slice(0, nl).trim();
+      buffer = buffer.slice(nl + 1);
+      if (!line) continue;
+      let msg;
+      try { msg = JSON.parse(line); } catch { continue; }
+      handle(msg);
+    }
+  });
+  if (typeof readable.resume === 'function') readable.resume();
+  return { handle }; // exposed for in-process testing
+}

package/src/migrate.mjs

@@ -0,0 +1,118 @@
+// Schema migrations for the Intent Graph. As `intent-graph-v1` evolves, consumers (OT, RM,
+// ST) hold persisted graphs; when the schema bumps, those old graphs must upgrade
+// deterministically rather than break. This is the upgrade path: an ordered chain of pure
+// migration steps + declarative builders so a future v1 -> v2 is a one-liner, plus a
+// baseline that normalizes pre-versioned (v0) graphs into a well-formed v1.
+
+import { SCHEMA_VERSION, NODE_TYPES, RELATIONSHIP_TYPES } from './intent-schema.mjs';
+
+export const MIGRATION_SCHEMA = 'intent-migration-v1';
+
+// The ordered version chain. Every known schema version, oldest first. A graph with no (or
+// unrecognized) `schema` is treated as the oldest, `intent-graph-v0` (pre-versioned).
+export const SCHEMA_CHAIN = ['intent-graph-v0', 'intent-graph-v1'];
+
+// The standard v1 node fields, with their defaults, for backfilling legacy nodes.
+const NODE_DEFAULTS = {
+  title: null, description: null, status: 'draft', owner: null,
+  classification: null, confidence: null, source: null, tags: [],
+  createdTime: null, updatedTime: null,
+};
+
+/** The schema version of a graph (defaults unversioned/unknown graphs to the oldest). */
+export function graphVersion(graph) {
+  const v = graph && graph.schema;
+  return SCHEMA_CHAIN.includes(v) ? v : SCHEMA_CHAIN[0];
+}
+
+// ── Declarative migration builders , compose these into a step's `migrate` function. ──
+
+/** Rename every node of `fromType` to `toType`. */
+export const renameNodeType = (fromType, toType) => (g) => ({
+  ...g, nodes: (g.nodes || []).map((n) => (n.type === fromType ? { ...n, type: toType } : n)),
+});
+
+/** Rename every relationship of `fromType` to `toType`. */
+export const renameRelationshipType = (fromType, toType) => (g) => ({
+  ...g, relationships: (g.relationships || []).map((r) => (r.type === fromType ? { ...r, type: toType } : r)),
+});
+
+/** Backfill a field on every node (only where currently missing/undefined). */
+export const backfillNodeField = (field, value) => (g) => ({
+  ...g, nodes: (g.nodes || []).map((n) => (n[field] === undefined ? { ...n, [field]: (Array.isArray(value) ? [...value] : value) } : n)),
+});
+
+/** Drop a field from every node. */
+export const dropNodeField = (field) => (g) => ({
+  ...g, nodes: (g.nodes || []).map((n) => { const c = { ...n }; delete c[field]; return c; }),
+});
+
+/** Run several step-transforms left to right, then stamp the target schema version. */
+const pipe = (toVersion, ...fns) => (g) => ({ ...fns.reduce((acc, fn) => fn(acc), g), schema: toVersion });
+
+// ── The baseline migration: v0 (pre-versioned) -> v1 ──
+// Normalizes a legacy graph into a well-formed v1: stamps the schema and backfills every
+// standard v1 node field so downstream code can rely on the shape.
+function migrateV0toV1(g) {
+  const nodes = (g.nodes || []).map((n) => {
+    const out = { ...n };
+    for (const [k, v] of Object.entries(NODE_DEFAULTS)) if (out[k] === undefined) out[k] = Array.isArray(v) ? [...v] : v;
+    return out;
+  });
+  const relationships = (g.relationships || []).map((r) => ({ from: r.from, type: r.type, to: r.to, ...(r.name !== undefined ? { name: r.name } : {}), ...(r.within !== undefined ? { within: r.within } : {}) }));
+  return { ...g, schema: 'intent-graph-v1', nodes, relationships };
+}
+
+// The registry: exactly one step per adjacent version pair. To add v2, append
+// { from:'intent-graph-v1', to:'intent-graph-v2', description, migrate: pipe('intent-graph-v2', ...builders) }.
+export const MIGRATIONS = [
+  { from: 'intent-graph-v0', to: 'intent-graph-v1', description: 'Stamp schema version and backfill the standard node fields.', migrate: migrateV0toV1 },
+];
+
+/**
+ * Migrate a graph forward to a target schema version (default: the latest). Applies each
+ * registered step in chain order. Deterministic and pure , the input graph is not mutated.
+ * @returns {{schema, from, to, migrated, applied, graph}}
+ */
+export function migrateGraph(graph, { to = SCHEMA_VERSION } = {}) {
+  if (!SCHEMA_CHAIN.includes(to)) throw new Error(`migrateGraph: unknown target schema "${to}"`);
+  const from = graphVersion(graph);
+  const targetIdx = SCHEMA_CHAIN.indexOf(to);
+  if (SCHEMA_CHAIN.indexOf(from) > targetIdx) throw new Error(`migrateGraph: cannot downgrade from "${from}" to "${to}"`);
+
+  let cur = from;
+  let g = graph;
+  const applied = [];
+  let guard = 0;
+  while (cur !== to) {
+    const step = MIGRATIONS.find((m) => m.from === cur);
+    if (!step) throw new Error(`migrateGraph: no migration registered from "${cur}"`);
+    g = step.migrate(g);
+    applied.push({ from: step.from, to: step.to, description: step.description });
+    cur = step.to;
+    if (++guard > SCHEMA_CHAIN.length + 1) throw new Error('migrateGraph: migration loop detected');
+  }
+  return { schema: MIGRATION_SCHEMA, from, to, migrated: applied.length > 0, applied, graph: g };
+}
+
+/**
+ * Validate a graph against the canonical vocabulary: every node has an id + canonical type,
+ * every relationship has a canonical type and non-dangling endpoints. Returns issues (never
+ * throws). Use after a migration to confirm the result is well-formed.
+ */
+export function validateGraph(graph) {
+  const issues = [];
+  const nodeTypes = new Set(NODE_TYPES);
+  const relTypes = new Set(RELATIONSHIP_TYPES);
+  const ids = new Set((graph.nodes || []).map((n) => n.id));
+  for (const n of graph.nodes || []) {
+    if (!n.id) issues.push({ level: 'error', code: 'MIG-001', message: 'node has no id' });
+    if (!nodeTypes.has(n.type)) issues.push({ level: 'error', code: 'MIG-002', message: `unknown node type "${n.type}"`, id: n.id });
+  }
+  for (const r of graph.relationships || []) {
+    if (!relTypes.has(r.type)) issues.push({ level: 'error', code: 'MIG-003', message: `unknown relationship type "${r.type}"` });
+    if (!(ids.has(r.from) || String(r.from).startsWith('phase.'))) issues.push({ level: 'error', code: 'MIG-004', message: `dangling relationship from "${r.from}"` });
+    if (!(ids.has(r.to) || String(r.to).startsWith('phase.'))) issues.push({ level: 'error', code: 'MIG-005', message: `dangling relationship to "${r.to}"` });
+  }
+  return { schema: 'intent-graph-validation-v1', version: graphVersion(graph), valid: issues.length === 0, issues };
+}

package/src/outcome.mjs

@@ -0,0 +1,93 @@
+// Outcome contracts , an executable commitment about a result. An `outcome_contract` binds
+// an outcome to a metric, a baseline, and a target, with a direction (higher/lower is
+// better) and a measurement window. Unlike a wish, a contract can be EVALUATED: given the
+// actual measured value (from a delivery `result`, or supplied directly), the runtime says
+// whether the commitment was met. Deterministic and pure , no AI.
+
+export const OUTCOME_SCHEMA = 'intent-outcome-v1';
+
+// Parse a target/baseline/actual value into a comparable number, keeping the unit for
+// display. Handles "60%", "48 percent", "$1,000", "2.5s", plain numbers.
+export function parseValue(raw) {
+  if (raw == null) return { value: null, unit: null, raw };
+  const s = String(raw).trim();
+  const m = s.match(/-?\d[\d,]*\.?\d*/);
+  if (!m) return { value: null, unit: null, raw: s };
+  const value = Number(m[0].replace(/,/g, ''));
+  const unit = s.includes('%') || /\bpercent\b/i.test(s) ? '%' : (s.replace(m[0], '').trim() || null);
+  return { value, unit, raw: s };
+}
+
+/**
+ * Evaluate an outcome contract against an actual measured value. Deterministic.
+ * "Better" is set by direction: higher (default) means met when actual >= target; lower
+ * means met when actual <= target. Returns null-ish `met` when the contract or actual is
+ * not numerically comparable (so the caller can flag "cannot evaluate").
+ * @returns {{schema, contract, target, actual, baseline, direction, met, improvement, comparable}}
+ */
+export function evaluateOutcomeContract(contract, actual) {
+  const t = parseValue(contract.target);
+  const a = parseValue(actual);
+  const b = parseValue(contract.baseline);
+  const dir = contract.direction === 'lower' ? 'lower' : 'higher';
+  const comparable = t.value != null && a.value != null;
+  const met = comparable ? (dir === 'lower' ? a.value <= t.value : a.value >= t.value) : null;
+  const improvement = (b.value != null && a.value != null) ? Number((a.value - b.value).toFixed(6)) : null;
+  return {
+    schema: OUTCOME_SCHEMA,
+    contract: contract.name,
+    target: t.raw, actual: a.raw ?? null, baseline: b.raw ?? null,
+    direction: dir, met, improvement, comparable,
+  };
+}
+
+/**
+ * Evaluate every outcome contract in an AST against the delivery `result` that measures the
+ * same outcome (or shares the metric). Contracts with no matching result are reported
+ * `pending` (comparable=false). This turns "did we achieve the outcome?" into a check.
+ */
+export function evaluateOutcomes(ast) {
+  const results = ast.results || [];
+  const evaluations = (ast.outcomeContracts || []).map((c) => {
+    // Match a delivery result by the outcome it measures, else by metric name.
+    const r = results.find((x) => x.measures && c.outcome && x.measures === c.outcome)
+      || results.find((x) => x.metric && c.metric && x.metric === c.metric);
+    const evalResult = evaluateOutcomeContract(c, r ? r.value : null);
+    return { ...evalResult, matchedResult: r ? r.name : null, status: !evalResult.comparable ? 'pending' : (evalResult.met ? 'met' : 'missed') };
+  });
+  return {
+    schema: OUTCOME_SCHEMA,
+    total: evaluations.length,
+    met: evaluations.filter((e) => e.status === 'met').length,
+    missed: evaluations.filter((e) => e.status === 'missed').length,
+    pending: evaluations.filter((e) => e.status === 'pending').length,
+    evaluations,
+  };
+}
+
+/** Authoring-time checks on declared outcome contracts (IL-OC-001..004). */
+export function outcomeDiagnostics(ast) {
+  const out = [];
+  for (const c of ast.outcomeContracts || []) {
+    const t = parseValue(c.target);
+    const b = parseValue(c.baseline);
+    if (!c.target) out.push({ code: 'IL-OC-001', contract: c.name, severity: 'blocker',
+      message: `Outcome contract "${c.name}" has no target, so it cannot be evaluated.` });
+    if (!c.metric) out.push({ code: 'IL-OC-002', contract: c.name, severity: 'warning',
+      message: `Outcome contract "${c.name}" names no metric.` });
+    if (!c.window) out.push({ code: 'IL-OC-003', contract: c.name, severity: 'blocker',
+      message: `Outcome contract "${c.name}" has no measurement window.` });
+    if (t.value != null && b.value != null) {
+      const better = c.direction === 'lower' ? t.value < b.value : t.value > b.value;
+      if (!better) out.push({ code: 'IL-OC-004', contract: c.name, severity: 'warning',
+        message: `Outcome contract "${c.name}" target (${t.raw}) is not better than its baseline (${b.raw}) for a "${c.direction}" goal.` });
+    }
+    // A target with no guardrail can be "achieved" by regressing something else (Goodhart's law).
+    if (c.target && !(c.guardrails || []).length) out.push({ code: 'IL-OC-005', contract: c.name, severity: 'warning',
+      message: `Outcome contract "${c.name}" has a target but no guardrails, so the target could be met by regressing something else.` });
+    // Never let a metric move read as causation , the attribution must be stated honestly.
+    if (c.target && (!c.attribution || c.attribution === 'unknown')) out.push({ code: 'IL-OC-006', contract: c.name, severity: 'info',
+      message: `Outcome contract "${c.name}" has no attribution , a metric moving after release is correlation, not proof this feature caused it.` });
+  }
+  return out;
+}