@skillstech/thunderlang 0.1.6

package/src/runtime.mjs

@@ -0,0 +1,96 @@
+// The Intent Runtime , EXECUTABLE intent with zero AI and zero code generation. Decisions
+// evaluate against concrete inputs; lifecycles simulate against a sequence of events. This
+// is the step beyond prompt engineering: you write intent and you can immediately RUN it,
+// TEST it, and PROVE how it behaves, before any implementation exists. Deterministic and
+// pure , the same intent and inputs always produce the same result and the same trace.
+
+import { compileExpr, ExprError } from './expr.mjs';
+import { buildLifecycle } from './lifecycle.mjs';
+
+export const RUNTIME_SCHEMA = 'intent-runtime-v1';
+
+/**
+ * Evaluate a declared decision (Gap 4) against a concrete inputs object. FIRST-hit: rules
+ * are tried in order, the first whose `when` is true wins; the mission `default` is the
+ * catch-all. Returns the result plus a full per-rule trace, so the evaluation is auditable.
+ * A malformed `when` does not throw , it is recorded as an error in the trace and skipped.
+ *
+ * @returns {{schema, decision, result, matched, trace, ok}}
+ */
+export function evaluateDecision(dec, inputs = {}) {
+  const trace = [];
+  let result = null;
+  let matched = null;
+  for (const rule of dec.rules || []) {
+    if (!rule.when) { trace.push({ rule: rule.name, when: null, matched: false, note: 'no condition' }); continue; }
+    let ok = false; let error = null;
+    try { ok = !!compileExpr(rule.when)(inputs); }
+    catch (e) { error = e instanceof ExprError ? e.message : String(e); }
+    trace.push({ rule: rule.name, when: rule.when, matched: ok, ...(error ? { error } : {}) });
+    if (ok && matched === null) { result = rule.result; matched = rule.name; }
+  }
+  if (matched === null && dec.default != null) { result = dec.default; matched = 'default'; }
+  return {
+    schema: RUNTIME_SCHEMA,
+    decision: dec.name,
+    result,
+    matched,
+    undecided: matched === null,
+    explanationRequired: !!dec.explanationRequired,
+    trace,
+    ok: trace.every((t) => !t.error),
+  };
+}
+
+/**
+ * Simulate a declared lifecycle (Gap 2) against a sequence of events. Each event is a
+ * transition name OR a target-state name; from the current state we take the matching
+ * transition. An event with no valid transition is recorded as rejected (the state does
+ * not change). Returns the walked path, a per-step trace, and whether every step was valid.
+ *
+ * @returns {{schema, lifecycle, path, steps, finalState, valid, endedTerminal}}
+ */
+export function simulateLifecycle(lc, events = []) {
+  const ir = buildLifecycle(lc);
+  const terminals = new Set(ir.terminals.length ? ir.terminals : ir.states.filter((s) => (ir.out[s] || []).length === 0));
+  let state = ir.initial;
+  const path = [state];
+  const steps = [];
+  let valid = true;
+  for (const ev of events) {
+    const candidates = (ir.transitions || []).filter((t) => t.from === state && (t.name === ev || t.to === ev));
+    if (candidates.length === 0) {
+      valid = false;
+      const reason = terminals.has(state) ? `state "${state}" is terminal` : `no transition "${ev}" from "${state}"`;
+      steps.push({ event: ev, from: state, to: state, ok: false, reason });
+      continue;
+    }
+    const t = candidates[0];
+    steps.push({ event: ev, from: state, to: t.to, ok: true, transition: t.name });
+    state = t.to;
+    path.push(state);
+  }
+  return {
+    schema: RUNTIME_SCHEMA,
+    lifecycle: lc.name,
+    path,
+    steps,
+    finalState: state,
+    valid,
+    endedTerminal: terminals.has(state),
+  };
+}
+
+/**
+ * Run a decision against a table of test cases (each {inputs, expect}). Returns pass/fail
+ * per case , this turns a decision into a self-checking specification you can regression-test
+ * with no code and no AI.
+ */
+export function checkDecisionCases(dec, cases = []) {
+  const results = cases.map((c, i) => {
+    const run = evaluateDecision(dec, c.inputs || {});
+    const pass = c.expect === undefined || String(run.result) === String(c.expect);
+    return { case: c.name || `case ${i + 1}`, inputs: c.inputs || {}, expected: c.expect, actual: run.result, matched: run.matched, pass };
+  });
+  return { schema: RUNTIME_SCHEMA, decision: dec.name, total: results.length, passed: results.filter((r) => r.pass).length, results };
+}

package/src/sarif.mjs

@@ -0,0 +1,88 @@
+// SARIF 2.1.0 output for `intent check` , so ThunderLang diagnostics show up natively in the
+// surfaces teams already use: GitHub / GitLab code scanning (inline PR annotations + the
+// Security tab) and any SARIF-aware IDE. Pure: reports in, one SARIF log object out.
+//
+// Feed it per-file reports: [{ file, diagnostics: [{ code, level, severity, message, line? }] }].
+// `level`/`severity` map to SARIF levels (blocker/error -> error, warning -> warning,
+// info -> note). A diagnostic with a `line` gets a precise region; otherwise it lands at the
+// file level (valid SARIF; the surface shows it at the top of the file).
+
+import { ALL_DIAGNOSTICS } from './intent-schema.mjs';
+
+export const SARIF_SCHEMA = 'https://json.schemastore.org/sarif-2.1.0.json';
+
+const META = new Map(ALL_DIAGNOSTICS.map((r) => [r.ruleId, r]));
+
+// SARIF result level for one diagnostic.
+export function sarifLevel(diag) {
+  if (diag.severity === 'blocker' || diag.level === 'error') return 'error';
+  if (diag.level === 'warning') return 'warning';
+  return 'note';
+}
+
+/**
+ * Build a SARIF 2.1.0 log from per-file diagnostic reports.
+ * @param {Array<{file: string, diagnostics: Array}>} reports
+ * @param {{version?: string, toolName?: string}} [opts]
+ */
+export function toSarif(reports, opts = {}) {
+  const version = opts.version || '0.0.0';
+  const toolName = opts.toolName || 'ThunderLang';
+
+  // Rules referenced by results, in first-seen order, with catalog metadata when available.
+  const ruleIndex = new Map();
+  const rules = [];
+  const ruleIndexOf = (code) => {
+    if (ruleIndex.has(code)) return ruleIndex.get(code);
+    const meta = META.get(code);
+    const idx = rules.length;
+    rules.push({
+      id: code,
+      name: code,
+      shortDescription: { text: meta ? meta.summary : code },
+      defaultConfiguration: { level: meta ? (meta.severity === 'blocker' ? 'error' : meta.severity === 'error' ? 'error' : meta.severity === 'warning' ? 'warning' : 'note') : 'warning' },
+      properties: meta ? { area: meta.area, severity: meta.severity, blocks: meta.blocks } : {},
+      ...(code.startsWith('IL-') || META.has(code)
+        ? { helpUri: `https://thunderlang.dev/docs/diagnostics#${code.toLowerCase()}` }
+        : {}),
+    });
+    ruleIndex.set(code, idx);
+    return idx;
+  };
+
+  const results = [];
+  for (const rep of reports) {
+    for (const d of rep.diagnostics || []) {
+      if (!d.code) continue;
+      const region = Number.isInteger(d.line) && d.line > 0 ? { region: { startLine: d.line } } : {};
+      results.push({
+        ruleId: d.code,
+        ruleIndex: ruleIndexOf(d.code),
+        level: sarifLevel(d),
+        message: { text: d.message || d.code },
+        locations: [{
+          physicalLocation: {
+            artifactLocation: { uri: rep.file },
+            ...region,
+          },
+        }],
+      });
+    }
+  }
+
+  return {
+    $schema: SARIF_SCHEMA,
+    version: '2.1.0',
+    runs: [{
+      tool: {
+        driver: {
+          name: toolName,
+          informationUri: 'https://thunderlang.dev',
+          version,
+          rules,
+        },
+      },
+      results,
+    }],
+  };
+}

package/src/scan-queries.mjs

@@ -0,0 +1,97 @@
+// Scanner query views (intent-scan-view-v1) , the deterministic answers behind the Part 3
+// CLI verbs: `intent risks | gaps | unverified | coverage | unknowns | contradictions`.
+// These are pure derivations over a scanProject() result (its Intent IR + Fable findings) ,
+// no new analysis, no AI. They exist so a person can ask one focused question ("what is
+// unverified?", "what contradicts?") instead of reading the whole scan report.
+//
+// ThunderLang owns this because it owns the Scanner spine + Intent IR. It deliberately does
+// NOT own learning/mastery (RepoMastery) or code verification (OpenThunder); those consume
+// these same artifacts.
+
+export const VIEW_SCHEMA = 'intent-scan-view-v1';
+
+const nodes = (scan) => scan?.ir?.nodes || [];
+const rels = (scan) => scan?.ir?.relationships || [];
+const findings = (scan) => scan?.findings || [];
+const claimNodes = (scan) => nodes(scan).filter((n) => n.type === 'Guarantee' || n.type === 'Never');
+
+// Node ids that a `verified_by` edge touches (robust to edge direction).
+function verifiedIds(scan) {
+  const s = new Set();
+  for (const e of rels(scan)) if (e.type === 'verified_by') { s.add(e.from); s.add(e.to); }
+  return s;
+}
+
+/** Risk themes + the highest-impact remediation order (the scan report's risk half, focused). */
+export function risksView(scan) {
+  return {
+    schema: VIEW_SCHEMA, view: 'risks',
+    bySeverity: scan?.bySeverity || {},
+    themes: scan?.risks || [],
+    remediationSequence: scan?.remediationSequence || [],
+    count: (scan?.risks || []).length,
+  };
+}
+
+/** Intent gaps: missing goal, unverified guarantees, and other "something required is absent" findings. */
+export function gapsView(scan) {
+  const GAP = /(^missing-|-without-|-missing$|^no-)/;
+  const gaps = findings(scan).filter((f) => f.category === 'Intent risk' || GAP.test(f.ruleId));
+  return {
+    schema: VIEW_SCHEMA, view: 'gaps', count: gaps.length,
+    gaps: gaps.map((f) => ({ ruleId: f.ruleId, severity: f.severity, detected: f.detected, why: f.why, remediation: f.remediation })),
+  };
+}
+
+/** Unverified claims: guarantees / never-rules with no verification behind them (IR + findings). */
+export function unverifiedView(scan) {
+  const verified = verifiedIds(scan);
+  const claims = claimNodes(scan).filter((c) => !verified.has(c.id));
+  return {
+    schema: VIEW_SCHEMA, view: 'unverified', count: claims.length,
+    claims: claims.map((c) => ({ id: c.id, type: c.type, title: c.title })),
+    findings: findings(scan).filter((f) => /-without-verification$/.test(f.ruleId)).map((f) => ({ ruleId: f.ruleId, detected: f.detected })),
+  };
+}
+
+/** Verification coverage: share of guarantees + never-rules that have a verification. */
+export function coverageView(scan) {
+  const claims = claimNodes(scan);
+  const verified = verifiedIds(scan);
+  const covered = claims.filter((c) => verified.has(c.id));
+  const coverage = claims.length ? Math.round((covered.length / claims.length) * 100) : 100;
+  return {
+    schema: VIEW_SCHEMA, view: 'coverage',
+    total: claims.length, verified: covered.length, coverage,
+    unverified: claims.filter((c) => !verified.has(c.id)).map((c) => ({ id: c.id, type: c.type, title: c.title })),
+  };
+}
+
+/** Unknowns: nodes that are open questions, assumptions, or low-confidence (never shown as fact). */
+export function unknownsView(scan) {
+  const LOW = new Set(['Inferred', 'Speculative', 'Conflicted']);
+  const open = nodes(scan).filter((n) => ['Unknown', 'Question', 'Assumption'].includes(n.type) || LOW.has(n.confidence));
+  return {
+    schema: VIEW_SCHEMA, view: 'unknowns', count: open.length,
+    unknowns: open.map((n) => ({ id: n.id, type: n.type, title: n.title, confidence: n.confidence || null, provenance: n.provenance || null })),
+  };
+}
+
+/** Contradictions: explicit Conflict nodes, contradicts/conflicts edges, and conflict-shaped findings. */
+export function contradictionsView(scan) {
+  const conflictNodes = nodes(scan).filter((n) => n.type === 'Conflict');
+  const conflictRels = rels(scan).filter((e) => e.type === 'contradicts' || e.type === 'conflicts_with');
+  const conflictFindings = findings(scan).filter((f) => /(contradict|conflict)/.test(f.ruleId));
+  return {
+    schema: VIEW_SCHEMA, view: 'contradictions',
+    count: conflictNodes.length + conflictRels.length + conflictFindings.length,
+    conflicts: conflictNodes.map((n) => ({ id: n.id, title: n.title })),
+    links: conflictRels.map((e) => ({ from: e.from, to: e.to, type: e.type })),
+    findings: conflictFindings.map((f) => ({ ruleId: f.ruleId, detected: f.detected })),
+  };
+}
+
+export const VIEWS = {
+  risks: risksView, gaps: gapsView, unverified: unverifiedView,
+  coverage: coverageView, unknowns: unknownsView, contradictions: contradictionsView,
+};

package/src/scan.mjs

@@ -0,0 +1,87 @@
+// Intent Scanner (intent-scan-v1) , the staged pipeline that turns a project into Intent IR +
+// explainable Fable findings + a risk view. This is the Scanner SPINE: discover -> normalize into
+// Intent IR -> run deterministic Fable rules -> produce findings -> group into risk themes ->
+// report. Deterministic (no AI, no key required); the whole thing runs locally. Pure ESM.
+//
+//   scanIntent(source, { file }) -> per-file scan result (IR + findings + risks)
+//   scanProject([{ file, source }]) -> whole-project scan (merged IR + findings + executive summary)
+
+import { parseIntent } from './parse.mjs';
+import { buildIntentGraph } from './intent-graph.mjs';
+import { semanticDiagnostics } from './emit.mjs';
+import { graphToIR } from './intent-ir.mjs';
+import { toFinding, RISK_CATEGORIES } from './fable.mjs';
+
+export const SCAN_SCHEMA = 'intent-scan-v1';
+
+const severityRank = { blocker: 0, error: 1, warning: 2, info: 3 };
+
+// Group findings into risk themes: one entry per risk category that has findings.
+function groupRisks(findings) {
+  const byCat = new Map();
+  for (const f of findings) {
+    const c = byCat.get(f.category) || { category: f.category, count: 0, blocker: 0, error: 0, warning: 0, info: 0, findingIds: [] };
+    c.count += 1;
+    c[f.severity] = (c[f.severity] || 0) + 1;
+    c.findingIds.push(f.findingId);
+    byCat.set(f.category, c);
+  }
+  // ordered by the canonical risk taxonomy, then severity weight
+  return [...byCat.values()].sort((a, b) => RISK_CATEGORIES.indexOf(a.category) - RISK_CATEGORIES.indexOf(b.category));
+}
+
+const countBySeverity = (findings) => findings.reduce((m, f) => ((m[f.severity] = (m[f.severity] || 0) + 1), m), { blocker: 0, error: 0, warning: 0, info: 0 });
+
+/** Scan one intent source into Intent IR + Fable findings + risk themes. */
+export function scanIntent(source, { file = null } = {}) {
+  const ast = parseIntent(String(source ?? ''));
+  const graph = buildIntentGraph(ast);
+  const ir = graphToIR(graph);
+  const missionNodeId = graph.nodes.find((n) => n.type === 'Mission')?.id;
+  const diags = semanticDiagnostics(ast);
+  const findings = diags.map((d, i) => toFinding(d, { file, index: i, affectedNodes: missionNodeId ? [missionNodeId] : [] }));
+  const risks = groupRisks(findings);
+  const bySeverity = countBySeverity(findings);
+  return {
+    schema: SCAN_SCHEMA,
+    file,
+    mission: ast.mission || null,
+    ir,
+    findings,
+    risks,
+    summary: { file, mission: ast.mission || null, findings: findings.length, bySeverity, ok: bySeverity.error === 0 && bySeverity.blocker === 0 },
+  };
+}
+
+/** Scan a whole project: merge each file's IR + findings, plus an executive summary. */
+export function scanProject(files) {
+  const perFile = [];
+  const allFindings = [];
+  const irNodes = [];
+  const irRels = [];
+  const seenNodeIds = new Set();
+  for (const { file, source } of files || []) {
+    const r = scanIntent(source, { file });
+    perFile.push(r.summary);
+    allFindings.push(...r.findings);
+    for (const n of r.ir.nodes) { const key = `${file}:${n.id}`; if (!seenNodeIds.has(key)) { seenNodeIds.add(key); irNodes.push({ ...n, id: `${file ? `${file}#` : ''}${n.id}` }); } }
+    for (const e of r.ir.relationships) irRels.push({ ...e, from: `${file ? `${file}#` : ''}${e.from}`, to: `${file ? `${file}#` : ''}${e.to}` });
+  }
+  const risks = groupRisks(allFindings);
+  const bySeverity = countBySeverity(allFindings);
+  // Highest-impact remediation sequence: blocker > error > warning, most-common rule first.
+  const byRule = new Map();
+  for (const f of allFindings) { const k = f.ruleId; const e = byRule.get(k) || { ruleId: k, category: f.category, severity: f.severity, count: 0, remediation: f.remediation }; e.count += 1; byRule.set(k, e); }
+  const remediationSequence = [...byRule.values()].sort((a, b) => (severityRank[a.severity] - severityRank[b.severity]) || (b.count - a.count)).slice(0, 10);
+  return {
+    schema: SCAN_SCHEMA,
+    totals: { files: perFile.length, missions: perFile.filter((f) => f.mission).length, findings: allFindings.length },
+    bySeverity,
+    risks,
+    remediationSequence,
+    ir: { schema: 'intent-ir-v1', embeds: 'intent-graph-v1', nodes: irNodes, relationships: irRels },
+    files: perFile,
+    findings: allFindings,
+    ok: bySeverity.error === 0 && bySeverity.blocker === 0,
+  };
+}

package/src/security.mjs

@@ -0,0 +1,73 @@
+// Security + type semantic pass , the deterministic checks that catch the mistakes prompt
+// engineering routinely ships: secrets travelling over the event bus, sensitive data returned
+// from an unauthenticated API, and mistyped fields. No AI; pure functions over the AST.
+//
+// These sit alongside privacy.mjs (which governs declared `data` blocks): this pass looks at
+// TYPED FIELDS (input/output/event payload/api) rather than governed data elements.
+
+import { isRecognizedType } from './data-schema.mjs';
+
+export const SECURITY_SCHEMA = 'intent-security-v1';
+
+// Types that are secret by construction: transporting or exposing them is a leak. Kept tight
+// (secret/password/jwt) so the checks never cry wolf on ambiguous names like "token".
+const SECRET_TYPES = new Set(['secret', 'password', 'jwt']);
+
+const baseType = (t) => {
+  const m = String(t || '').trim().match(/^(?:List|Array)<(.+)>$/i);
+  return (m ? m[1] : String(t || '')).trim();
+};
+const isSecretType = (t) => SECRET_TYPES.has(baseType(t).toLowerCase());
+
+/**
+ * Deterministic security + type findings. Returns { code, severity, message, where, line }.
+ *   IL-SEC-001  a secret-typed field rides an event payload (secret over the bus)   [blocker]
+ *   IL-SEC-002  an API returns a secret-typed output with no auth requirement        [blocker]
+ *   IL-TYPE-001 a field uses an unrecognized (lowercase, likely mistyped) type       [info]
+ */
+export function securityDiagnostics(ast) {
+  const out = [];
+
+  // IL-SEC-001 , secrets on the event bus.
+  for (const ev of ast.events || []) {
+    for (const f of ev.payload || []) {
+      if (isSecretType(f.type)) {
+        out.push({
+          code: 'IL-SEC-001', severity: 'blocker',
+          message: `Event "${ev.name}" payload field "${f.name}" is a ${baseType(f.type)}; secrets must not travel over the event bus.`,
+          where: ev.name, line: f.line ?? null,
+        });
+      }
+    }
+  }
+
+  // IL-SEC-002 , sensitive output from an unauthenticated API. `requires` is the auth gate.
+  for (const api of ast.apis || []) {
+    const hasAuth = (api.requires || []).length > 0;
+    if (isSecretType(api.output) && !hasAuth) {
+      out.push({
+        code: 'IL-SEC-002', severity: 'blocker',
+        message: `API "${api.name}" returns a ${baseType(api.output)} but declares no auth requirement; sensitive output must be authenticated.`,
+        where: api.name, line: api.line ?? null,
+      });
+    }
+  }
+
+  // IL-TYPE-001 , unrecognized field type (almost always a typo). Info, gate-safe.
+  const checkFields = (fields, where) => {
+    for (const f of fields || []) {
+      if (f.type && !isRecognizedType(f.type)) {
+        out.push({
+          code: 'IL-TYPE-001', severity: 'info',
+          message: `Field "${f.name}" has an unrecognized type "${f.type}". Use a known semantic type/primitive, or a PascalCase entity name.`,
+          where, line: f.line ?? null,
+        });
+      }
+    }
+  };
+  checkFields(ast.inputs, 'input');
+  checkFields(ast.outputs, 'output');
+  for (const ev of ast.events || []) checkFields(ev.payload, `event ${ev.name}`);
+
+  return out;
+}

package/src/select.mjs

@@ -0,0 +1,80 @@
+// Deterministic candidate selection , the AI generates N candidates; ThunderLang and
+// OpenThunder pick the winner by MEASURABLE rules. An LLM never decides which
+// candidate is best. Pure (no Node deps): browser-safe.
+//
+//   selection
+//     require all verification checks
+//     prefer lower complexity
+//     prefer fewer dependencies
+//     prefer smaller implementation
+//     prefer better mutation score
+
+const MIN_WORDS = new Set(['lower', 'fewer', 'smaller', 'less', 'least', 'lowest', 'minimal']);
+const MAX_WORDS = new Set(['higher', 'more', 'better', 'greater', 'most', 'highest', 'larger', 'best']);
+
+function normalizeMetric(s) {
+  const t = String(s).toLowerCase();
+  if (/complex/.test(t)) return 'complexity';
+  if (/depend/.test(t)) return 'dependencies';
+  if (/implement|size|line/.test(t)) return 'size';
+  if (/alloc/.test(t)) return 'allocation';
+  if (/mutation/.test(t)) return 'mutationScore';
+  return t.trim().replace(/\s+/g, '_');
+}
+
+/** Parse selection-block lines into a structured, deterministic policy. */
+export function parseSelection(lines) {
+  const require = [];
+  const prefer = [];
+  for (const raw of lines || []) {
+    const t = String(raw).trim().toLowerCase();
+    if (/^require\b/.test(t)) {
+      require.push(t.replace(/^require\s+/, ''));
+    } else if (/^prefer\b/.test(t)) {
+      const words = t.replace(/^prefer\s+/, '').split(/\s+/);
+      const direction = MAX_WORDS.has(words[0]) ? 'max' : MIN_WORDS.has(words[0]) ? 'min' : 'min';
+      prefer.push({ metric: normalizeMetric(words.slice(1).join(' ')), direction });
+    }
+  }
+  return { require, prefer, requireAllChecks: require.some((r) => /verification|all/.test(r)) };
+}
+
+/** Deterministic metrics derivable from a code region (size / complexity / deps). */
+export function regionMetrics(code) {
+  const text = String(code || '');
+  const size = text.split('\n').filter((l) => l.trim() && !l.trim().startsWith('//') && !l.includes('intent:')).length;
+  const complexity = (text.match(/\b(if|else|for|while|switch|case|catch|return)\b|&&|\|\||\?/g) || []).length;
+  const dependencies = (text.match(/\b(import|require)\b/g) || []).length;
+  return { size, complexity, dependencies };
+}
+
+const DEFAULT_PREFER = [
+  { metric: 'complexity', direction: 'min' },
+  { metric: 'dependencies', direction: 'min' },
+  { metric: 'size', direction: 'min' },
+];
+
+/**
+ * Select the winning candidate by measurable rules. Deterministic:
+ * lexicographic by the `prefer` list, stable tiebreak by id. An unavailable metric
+ * ranks last for that comparison. Candidates failing `require` are ineligible.
+ * @param {{id:string, metrics:object, checksPassed?:boolean}[]} candidates
+ * @param {{prefer?:{metric,direction}[], requireAllChecks?:boolean}} policy
+ */
+export function selectCandidate(candidates, policy = {}) {
+  const prefer = policy.prefer && policy.prefer.length ? policy.prefer : DEFAULT_PREFER;
+  const requireAllChecks = !!policy.requireAllChecks;
+  const eligible = (candidates || []).filter((c) => (requireAllChecks ? c.checksPassed !== false : true));
+  const ranked = [...eligible].sort((a, b) => {
+    for (const p of prefer) {
+      const av = a.metrics ? a.metrics[p.metric] : undefined;
+      const bv = b.metrics ? b.metrics[p.metric] : undefined;
+      if (av == null && bv == null) continue;
+      if (av == null) return 1;
+      if (bv == null) return -1;
+      if (av !== bv) return p.direction === 'max' ? bv - av : av - bv;
+    }
+    return String(a.id).localeCompare(String(b.id)); // stable tiebreak
+  });
+  return { winner: ranked[0] || null, ranking: ranked, eligibleCount: eligible.length, rejected: (candidates || []).length - eligible.length, prefer };
+}

package/src/semantic-diff.mjs

@@ -0,0 +1,125 @@
+// Semantic diff over the Intent Graph (founder directive #4, IL owns diff/merge). Diff
+// two versions of a graph/atlas BY MEANING: nodes added/removed/changed, relationships
+// added/removed, and , the load-bearing feature , which approvals a change invalidates.
+// Deterministic; pure (no Node deps).
+
+// Content identity of a node (ignores volatile timestamps).
+const contentKey = (n) => JSON.stringify({
+  type: n.type, title: n.title ?? null, description: n.description ?? null,
+  status: n.status ?? null, owner: n.owner ?? null,
+  classification: n.classification ?? null, confidence: n.confidence ?? null,
+});
+const relKey = (r) => `${r.from}|${r.type}|${r.to}`;
+const CONTRACT_RELS = new Set(['requires', 'constrained_by', 'targets', 'measured_by']);
+
+/**
+ * Semantic diff of two Intent Graphs (or Atlases). Deterministic.
+ * @param {{nodes, relationships}} before
+ * @param {{nodes, relationships}} after
+ */
+export function diffGraphs(before, after) {
+  const bNodes = new Map((before.nodes || []).map((n) => [n.id, n]));
+  const aNodes = new Map((after.nodes || []).map((n) => [n.id, n]));
+
+  const addedNodes = [];
+  const removedNodes = [];
+  const changedNodes = [];
+  for (const [id, n] of aNodes) if (!bNodes.has(id)) addedNodes.push(n);
+  for (const [id, n] of bNodes) if (!aNodes.has(id)) removedNodes.push(n);
+  for (const [id, an] of aNodes) {
+    const bn = bNodes.get(id);
+    if (bn && contentKey(bn) !== contentKey(an)) changedNodes.push({ id, type: an.type, before: bn, after: an });
+  }
+  addedNodes.sort((a, b) => a.id.localeCompare(b.id));
+  removedNodes.sort((a, b) => a.id.localeCompare(b.id));
+  changedNodes.sort((a, b) => a.id.localeCompare(b.id));
+
+  const bRel = new Set((before.relationships || []).map(relKey));
+  const aRel = new Set((after.relationships || []).map(relKey));
+  const addedRelationships = (after.relationships || []).filter((r) => !bRel.has(relKey(r)));
+  const removedRelationships = (before.relationships || []).filter((r) => !aRel.has(relKey(r)));
+
+  // Which approvals does this change invalidate? An approval is invalidated when its
+  // mission's contract (requires / constrained_by / targets / measured_by nodes) changed.
+  const changedIds = new Set([...addedNodes.map((n) => n.id), ...removedNodes.map((n) => n.id), ...changedNodes.map((c) => c.id)]);
+  const missionContract = {};
+  const missionApprovals = {};
+  for (const r of after.relationships || []) {
+    if (!r.from.startsWith('mission.')) continue;
+    if (CONTRACT_RELS.has(r.type)) (missionContract[r.from] ||= new Set()).add(r.to);
+    if (r.type === 'approved_by') (missionApprovals[r.from] ||= []).push(r.to);
+  }
+  const invalidatedApprovals = [];
+  for (const [mission, contractIds] of Object.entries(missionContract)) {
+    const contractChanged = changedIds.has(mission) || [...contractIds].some((id) => changedIds.has(id));
+    if (contractChanged) for (const ap of missionApprovals[mission] || []) invalidatedApprovals.push(ap);
+  }
+
+  const byType = (arr) => arr.reduce((m, n) => ((m[n.type] = (m[n.type] || 0) + 1), m), {});
+  void relKey; // (used by mergeGraphs below)
+  return {
+    schema: 'intent-diff-v1',
+    addedNodes, removedNodes, changedNodes,
+    addedRelationships, removedRelationships,
+    invalidatedApprovals: [...new Set(invalidatedApprovals)].sort(),
+    summary: {
+      added: addedNodes.length, removed: removedNodes.length, changed: changedNodes.length,
+      addedByType: byType(addedNodes), removedByType: byType(removedNodes),
+      relationshipsAdded: addedRelationships.length, relationshipsRemoved: removedRelationships.length,
+      approvalsInvalidated: [...new Set(invalidatedApprovals)].length,
+    },
+  };
+}
+
+/**
+ * Three-way semantic merge over the Intent Graph. Given a common `base` and two
+ * concurrent versions `ours` / `theirs`, produce the merged graph and the list of
+ * CONFLICTS (the same node changed differently on both sides). Deterministic; the side
+ * that changed a node from base wins; if both changed it differently, it is a conflict
+ * (merged keeps `ours` provisionally). Node identity is the stable id; equality is content.
+ */
+export function mergeGraphs(base, ours, theirs) {
+  const key = (n) => (n ? contentKey(n) : 'MISSING');
+  const bN = new Map((base?.nodes || []).map((n) => [n.id, n]));
+  const oN = new Map((ours?.nodes || []).map((n) => [n.id, n]));
+  const tN = new Map((theirs?.nodes || []).map((n) => [n.id, n]));
+
+  const ids = [...new Set([...bN.keys(), ...oN.keys(), ...tN.keys()])].sort();
+  const merged = new Map();
+  const conflicts = [];
+  for (const id of ids) {
+    const b = bN.get(id) || null;
+    const o = oN.get(id) || null;
+    const t = tN.get(id) || null;
+    const oChanged = key(o) !== key(b);
+    const tChanged = key(t) !== key(b);
+    if (!oChanged && !tChanged) { if (b) merged.set(id, b); continue; }        // untouched (or both removed)
+    if (oChanged && !tChanged) { if (o) merged.set(id, o); continue; }         // only ours
+    if (!oChanged && tChanged) { if (t) merged.set(id, t); continue; }         // only theirs
+    if (key(o) === key(t)) { if (o) merged.set(id, o); continue; }             // both made the same change
+    conflicts.push({ id, type: (o || t || b).type, base: b, ours: o, theirs: t }); // both changed differently
+    if (o) merged.set(id, o); else if (t) merged.set(id, t);                   // keep ours provisionally
+  }
+
+  // Relationships (presence booleans): whoever changed presence from base wins.
+  const bR = new Set((base?.relationships || []).map(relKey));
+  const oR = new Set((ours?.relationships || []).map(relKey));
+  const tR = new Set((theirs?.relationships || []).map(relKey));
+  const byKey = new Map();
+  for (const r of [...(ours?.relationships || []), ...(theirs?.relationships || []), ...(base?.relationships || [])]) byKey.set(relKey(r), r);
+  const mergedRels = [];
+  for (const [k, r] of byKey) {
+    const inB = bR.has(k), inO = oR.has(k), inT = tR.has(k);
+    const present = inO !== inB ? inO : inT; // ours changed presence -> ours; else theirs
+    if (present) mergedRels.push(r);
+  }
+  mergedRels.sort((a, b2) => relKey(a).localeCompare(relKey(b2)));
+
+  return {
+    schema: 'intent-merge-v1',
+    merged: { nodes: [...merged.values()].sort((a, b2) => a.id.localeCompare(b2.id)), relationships: mergedRels },
+    conflicts: conflicts.sort((a, b2) => a.id.localeCompare(b2.id)),
+    clean: conflicts.length === 0,
+    summary: { nodes: merged.size, relationships: mergedRels.length, conflicts: conflicts.length },
+  };
+}