@skillstech/thunderlang 0.1.6

package/src/codegen.mjs

@@ -0,0 +1,214 @@
+// Code generation (intent-codegen-v1) , deterministic scaffolds from intent. NO AI: the same
+// intent always produces the same code. It generates what the intent fully determines (typed
+// interfaces, and the decision logic, which is already executable) and leaves honest TODO
+// markers where a human must supply the business logic , never a fake implementation. This is
+// the "see how it works, then change it" surface for the playground and `intent gen`.
+//
+// Pure and browser-safe so the playground can render it. TypeScript first; the same adapter
+// shape (a type map + a body walk) extends to C# / Java.
+
+import { exprToJs, exprToCSharp, exprToJava } from './expr.mjs';
+import { subjectName } from './parse.mjs';
+
+export const CODEGEN_SCHEMA = 'intent-codegen-v1';
+
+// Semantic type -> TypeScript type. Unknown/domain types become a named type (interface stub).
+const TS_TYPES = {
+  Email: 'string', Url: 'string', UserId: 'string', AccountId: 'string', OrderId: 'string',
+  InvoiceId: 'string', CustomerId: 'string', PaymentId: 'string', EventId: 'string',
+  Secret: 'string', Token: 'string', Jwt: 'string', Password: 'string', IdempotencyKey: 'string',
+  Money: 'number', Currency: 'string', Percentage: 'number', Count: 'number', Duration: 'number',
+  Date: 'string', DateTime: 'string', Flag: 'boolean', TraceId: 'string', CorrelationId: 'string',
+  Version: 'string', EnvironmentName: 'string',
+};
+
+function tsType(type, domain) {
+  if (!type) return 'unknown';
+  const list = /^List<(.+)>$/.exec(type);
+  if (list) { domain.add(list[1]); return `${tsType(list[1], domain)}[]`; }
+  const base = type.replace(/\(.*\)/, '');
+  if (TS_TYPES[base]) return TS_TYPES[base];
+  domain.add(base); // a domain/entity type -> emit an interface stub for it
+  return base;
+}
+
+const lower = (s) => (s ? s[0].toLowerCase() + s.slice(1) : s);
+const pascal = (s) => (s ? s[0].toUpperCase() + s.slice(1) : s).replace(/[^A-Za-z0-9]/g, '');
+const fieldsIface = (name, fields, domain) => [
+  `export interface ${name} {`,
+  ...fields.map((f) => `  ${f.name}: ${tsType(f.type, domain)};`),
+  '}', '',
+];
+
+/** Generate a deterministic TypeScript scaffold from a parsed intent AST. Returns a string. */
+export function toTypeScript(ast) {
+  const subject = pascal(subjectName(ast) || 'Intent');
+  const domain = new Set();
+  const L = [];
+
+  L.push(
+    `// ${subject} , generated from ThunderLang (intent-codegen-v1). Deterministic, no AI.`,
+    '// The typed contract and the decision logic below are fully determined by the intent.',
+    '// Business logic marked TODO is yours to complete; the guarantees and never-rules state',
+    '// what your implementation must uphold. Regenerate any time; edits to TODO bodies are lost.',
+    '',
+  );
+
+  // Input / output interfaces.
+  if ((ast.inputs || []).length) L.push(...fieldsIface(`${subject}Input`, ast.inputs, domain));
+  if ((ast.outputs || []).length) L.push(...fieldsIface(`${subject}Output`, ast.outputs, domain));
+
+  // Decisions , real, first-hit logic (the intent already executes these).
+  for (const d of ast.decisions || []) {
+    const inputs = d.inputs || [];
+    const params = inputs.map((i) => `${i}: unknown`).join(', ');
+    L.push(`// decision ${d.name} , first matching rule wins.`);
+    L.push(`export function ${lower(pascal(d.name))}(${params}): string {`);
+    for (const r of d.rules || []) {
+      let cond;
+      try { cond = exprToJs(r.when, { inputs }); }
+      catch { cond = `false /* TODO: could not translate "${r.when}" */`; }
+      L.push(`  if (${cond}) return ${JSON.stringify(r.result)}; // rule ${r.name}`);
+    }
+    L.push(`  return ${JSON.stringify(d.default ?? 'Undecided')}; // default`);
+    L.push('}', '');
+  }
+
+  // The mission function , signature is determined; body is a guarded stub.
+  const inName = (ast.inputs || []).length ? `${subject}Input` : 'void';
+  const outName = (ast.outputs || []).length ? `${subject}Output` : 'void';
+  const arg = inName === 'void' ? '' : `input: ${inName}`;
+  L.push(`export function ${lower(subject)}(${arg}): ${outName} {`);
+  for (const r of ast.requires || []) L.push(`  // precondition: ${r}  , TODO: validate`);
+  for (const n of ast.neverRules || []) L.push(`  // NEVER: ${n.statement}  , your code must not do this`);
+  for (const g of ast.guarantees || []) L.push(`  // GUARANTEE: ${g.statement}  , your code must uphold this${g.verify?.length ? ` (verify: ${g.verify.join(', ')})` : ''}`);
+  L.push('  throw new Error("TODO: implement , the intent above defines what this must do.");');
+  L.push('}', '');
+
+  // Domain type stubs for any referenced entity types.
+  const stubs = [...domain].filter((t) => !TS_TYPES[t] && /^[A-Z]/.test(t)).sort();
+  if (stubs.length) {
+    L.push('// Domain types referenced by the intent , complete these.');
+    for (const t of stubs) L.push(`export interface ${t} { /* TODO: fields */ }`);
+    L.push('');
+  }
+
+  return L.join('\n');
+}
+
+// ── C# ───────────────────────────────────────────────────────────────────────
+const CS_TYPES = {
+  Email: 'string', Url: 'string', UserId: 'string', AccountId: 'string', OrderId: 'string',
+  InvoiceId: 'string', CustomerId: 'string', Secret: 'string', Token: 'string', Jwt: 'string',
+  IdempotencyKey: 'string', Currency: 'string', Date: 'DateTime', DateTime: 'DateTime',
+  Money: 'decimal', Percentage: 'decimal', Count: 'int', Duration: 'int', Flag: 'bool',
+};
+function csType(type, domain) {
+  if (!type) return 'object';
+  const list = /^List<(.+)>$/.exec(type);
+  if (list) return `List<${csType(list[1], domain)}>`;
+  const base = type.replace(/\(.*\)/, '');
+  if (CS_TYPES[base]) return CS_TYPES[base];
+  domain.add(base); return base;
+}
+
+/** Generate a deterministic C# scaffold from an intent AST. */
+export function toCSharp(ast) {
+  const subject = pascal(subjectName(ast) || 'Intent');
+  const domain = new Set();
+  const L = [
+    `// ${subject} , generated from ThunderLang (intent-codegen-v1). Deterministic, no AI.`,
+    '// The record contract and the decision logic are fully determined by the intent;',
+    '// business logic marked TODO is yours, bound by the guarantees and never-rules below.',
+    '',
+    'using System;',
+    'using System.Collections.Generic;',
+    'using System.Linq;',
+    '',
+  ];
+  const rec = (name, fields) => fields.length
+    ? [`public record ${name}(${fields.map((f) => `${csType(f.type, domain)} ${pascal(f.name)}`).join(', ')});`, '']
+    : [];
+  if ((ast.inputs || []).length) L.push(...rec(`${subject}Input`, ast.inputs));
+  if ((ast.outputs || []).length) L.push(...rec(`${subject}Output`, ast.outputs));
+  L.push(`public static class ${subject}`, '{');
+  for (const d of ast.decisions || []) {
+    const inputs = d.inputs || [];
+    L.push(`  // decision ${d.name} , first matching rule wins.`);
+    L.push(`  public static string ${pascal(d.name)}(${inputs.map((i) => `dynamic ${i}`).join(', ')})`);
+    L.push('  {');
+    for (const r of d.rules || []) {
+      let cond; try { cond = exprToCSharp(r.when, { inputs }); } catch { cond = `false /* TODO: "${r.when}" */`; }
+      L.push(`    if (${cond}) return ${JSON.stringify(r.result)}; // rule ${r.name}`);
+    }
+    L.push(`    return ${JSON.stringify(d.default ?? 'Undecided')}; // default`, '  }');
+  }
+  const inName = (ast.inputs || []).length ? `${subject}Input` : null;
+  const outName = (ast.outputs || []).length ? `${subject}Output` : 'void';
+  L.push(`  public static ${outName} Run(${inName ? `${inName} input` : ''})`, '  {');
+  for (const n of ast.neverRules || []) L.push(`    // NEVER: ${n.statement}`);
+  for (const g of ast.guarantees || []) L.push(`    // GUARANTEE: ${g.statement}`);
+  L.push('    throw new NotImplementedException("TODO: implement , the intent above defines what this must do.");', '  }');
+  L.push('}', '');
+  return L.join('\n');
+}
+
+// ── Java ─────────────────────────────────────────────────────────────────────
+const JAVA_TYPES = {
+  Email: 'String', Url: 'String', UserId: 'String', AccountId: 'String', OrderId: 'String',
+  InvoiceId: 'String', CustomerId: 'String', Secret: 'String', Token: 'String', Jwt: 'String',
+  IdempotencyKey: 'String', Currency: 'String', Date: 'java.time.LocalDate', DateTime: 'java.time.Instant',
+  Money: 'java.math.BigDecimal', Percentage: 'double', Count: 'int', Duration: 'long', Flag: 'boolean',
+};
+function javaType(type, domain) {
+  if (!type) return 'Object';
+  const list = /^List<(.+)>$/.exec(type);
+  if (list) return `java.util.List<${javaType(list[1], domain)}>`;
+  const base = type.replace(/\(.*\)/, '');
+  if (JAVA_TYPES[base]) return JAVA_TYPES[base];
+  domain.add(base); return base;
+}
+
+/** Generate a deterministic Java scaffold from an intent AST. */
+export function toJava(ast) {
+  const subject = pascal(subjectName(ast) || 'Intent');
+  const domain = new Set();
+  const L = [
+    `// ${subject} , generated from ThunderLang (intent-codegen-v1). Deterministic, no AI.`,
+    '// The record contract and the decision logic are fully determined by the intent;',
+    '// business logic marked TODO is yours, bound by the guarantees and never-rules below.',
+    '',
+    `public final class ${subject} {`,
+    `  private ${subject}() {}`,
+    '',
+  ];
+  const rec = (name, fields) => fields.length
+    ? [`  public record ${name}(${fields.map((f) => `${javaType(f.type, domain)} ${f.name}`).join(', ')}) {}`, '']
+    : [];
+  if ((ast.inputs || []).length) L.push(...rec(`${subject}Input`, ast.inputs));
+  if ((ast.outputs || []).length) L.push(...rec(`${subject}Output`, ast.outputs));
+  for (const d of ast.decisions || []) {
+    const inputs = d.inputs || [];
+    L.push(`  // decision ${d.name} , first matching rule wins.`);
+    L.push(`  public static String ${lower(pascal(d.name))}(${inputs.map((i) => `Object ${i}`).join(', ')}) {`);
+    for (const r of d.rules || []) {
+      let cond; try { cond = exprToJava(r.when, { inputs }); } catch { cond = `false /* TODO: "${r.when}" */`; }
+      L.push(`    if (${cond}) return ${JSON.stringify(r.result)}; // rule ${r.name}`);
+    }
+    L.push(`    return ${JSON.stringify(d.default ?? 'Undecided')}; // default`, '  }');
+  }
+  const inName = (ast.inputs || []).length ? `${subject}Input` : null;
+  const outName = (ast.outputs || []).length ? `${subject}Output` : 'void';
+  L.push(`  public static ${outName} run(${inName ? `${inName} input` : ''}) {`);
+  for (const n of ast.neverRules || []) L.push(`    // NEVER: ${n.statement}`);
+  for (const g of ast.guarantees || []) L.push(`    // GUARANTEE: ${g.statement}`);
+  L.push('    throw new UnsupportedOperationException("TODO: implement , the intent above defines what this must do.");', '  }');
+  L.push('}', '');
+  return L.join('\n');
+}
+
+export const GENERATORS = {
+  typescript: toTypeScript, ts: toTypeScript,
+  csharp: toCSharp, cs: toCSharp,
+  java: toJava,
+};

package/src/compile.mjs

@@ -0,0 +1,142 @@
+// Pure, in-memory compile entrypoint shared by the CLI (writes to disk) and the
+// web playground (returns artifacts as strings). No filesystem, no AI.
+// Deterministic given a fixed `generatedAt`.
+
+import { parseIntent, slug, subjectName, intentRefId } from './parse.mjs';
+import { twelveFactorSummary } from './twelve-factor.mjs';
+import {
+  buildContractGraph, buildArchitectureGraph, buildImplementationPlan,
+  semanticDiagnostics, buildProof, sha256,
+} from './emit.mjs';
+
+export function renderMarkdown(ast) {
+  const L = [];
+  L.push(`# ${subjectName(ast) || 'Untitled intent'}`, '');
+  if (ast.goal) L.push(`**Goal.** ${ast.goal}`, '');
+  if (ast.why) L.push(`**Why.** ${ast.why}`, '');
+  if (ast.guarantees.length) {
+    L.push('## Guarantees', '');
+    for (const g of ast.guarantees) L.push(`- ${g.statement}${g.because ? ` (because ${g.because})` : ''}`);
+    L.push('');
+  }
+  if (ast.neverRules.length) {
+    L.push('## Never', '');
+    for (const n of ast.neverRules) L.push(`- ${n.statement}${n.because ? ` (because ${n.because})` : ''}`);
+    L.push('');
+  }
+  if (ast.verify.length) { L.push('## Verification', ''); for (const v of ast.verify) L.push(`- ${v}`); L.push(''); }
+  return L.join('\n');
+}
+
+/**
+ * Render a mission as Markdown documentation for ONE audience, weaving that lens's
+ * IntentLens notes inline next to the mission element they annotate. Notes explain
+ * meaning; they are never verification, and the doc says so. Pure and browser-safe.
+ */
+export function renderLensDoc(ast, lens) {
+  const m = ast.mission || 'mission';
+  const prefix = `mission.${m}`;
+  const flat = (t) => String(t).replace(/\s+/g, ' ').trim();
+  const notesFor = (path) => (ast.notes || []).filter((n) => n.lens === lens && n.targetPath === path);
+  const L = [];
+  L.push(`# ${m} , for the ${lens} reader`, '');
+  L.push(`> IntentLens \`${lens}\` notes are woven in below. They explain meaning for this`,
+    `> audience; they are documentation, not verification.`, '');
+  for (const nt of notesFor(prefix)) L.push(`_${flat(nt.text)}_`, '');
+  if (ast.goal) L.push(`**Goal.** ${ast.goal}`, '');
+  if (ast.why) L.push(`**Why.** ${ast.why}`, '');
+  const fieldSection = (title, fields, kind) => {
+    if (!fields.length) return;
+    L.push(`## ${title}`, '');
+    for (const f of fields) {
+      L.push(`- \`${f.name}: ${f.type}\``);
+      for (const nt of notesFor(`${prefix}.${kind}.${f.name}`)) L.push(`  , ${flat(nt.text)}`);
+    }
+    L.push('');
+  };
+  fieldSection('Inputs', ast.inputs, 'input');
+  fieldSection('Outputs', ast.outputs, 'output');
+  const ruleSection = (title, rules, kind) => {
+    if (!rules.length) return;
+    L.push(`## ${title}`, '');
+    for (const r of rules) {
+      L.push(`- ${r.statement}${r.because ? ` (because ${r.because})` : ''}`);
+      for (const nt of notesFor(`${prefix}.${kind}.${r.id}`)) L.push(`  , ${flat(nt.text)}`);
+    }
+    L.push('');
+  };
+  ruleSection('Guarantees', ast.guarantees, 'guarantee');
+  ruleSection('Never', ast.neverRules, 'never');
+  const count = (ast.notes || []).filter((n) => n.lens === lens).length;
+  L.push('---', `${count} \`${lens}\` note${count === 1 ? '' : 's'} in this mission.`);
+  return L.join('\n');
+}
+
+export function renderMermaid(ast) {
+  const L = ['graph TD'];
+  const m = slug(ast.mission || 'mission');
+  L.push(`  ${m}["${ast.mission}"]`);
+  ast.guarantees.forEach((g, i) => L.push(`  ${m} --> g${i}["guarantee: ${g.statement}"]`));
+  ast.neverRules.forEach((n, i) => L.push(`  ${m} --> n${i}["never: ${n.statement}"]`));
+  ast.events.forEach((e) => L.push(`  ${m} --> ev_${e.id}(["event: ${e.name}"])`));
+  return L.join('\n') + '\n';
+}
+
+export function renderTestplan(ast) {
+  const L = [`# Test plan: ${ast.mission}`, ''];
+  for (const g of ast.guarantees) L.push(`- [ ] Guarantee holds: ${g.statement}${g.verify.length ? ` (via ${g.verify.join(', ')})` : ''}`);
+  for (const n of ast.neverRules) L.push(`- [ ] Never occurs: ${n.statement}${n.verify.length ? ` (via ${n.verify.join(', ')})` : ''}`);
+  for (const e of ast.errors || []) L.push(`- [ ] Failure mode handled: ${e.name}`);
+  for (const ex of ast.examples || []) L.push(`- [ ] Example: given ${ex.given}${ex.expect ? ` -> expect ${ex.expect}` : ''}`);
+  for (const v of ast.verify) L.push(`- [ ] ${v}`);
+  return L.join('\n') + '\n';
+}
+
+/**
+ * Compile ThunderLang source in memory and return every artifact `intent build`
+ * would emit, without touching the filesystem.
+ */
+export function compileSource(source, { sourceFile = 'playground.intent', generatedAt, origin = 'authored' } = {}) {
+  const ast = parseIntent(source);
+  const at = generatedAt || new Date().toISOString();
+  const sourceHash = sha256(source);
+  const diagnostics = semanticDiagnostics(ast);
+
+  const contractGraph = buildContractGraph(ast, at);
+  const architectureGraph = buildArchitectureGraph(ast, at);
+  const implementationPlan = buildImplementationPlan(ast, at);
+  const markdown = renderMarkdown(ast);
+  const mermaid = renderMermaid(ast);
+  const testplan = renderTestplan(ast);
+
+  const mission = ast.mission || 'mission';
+  const targetsGenerated = [
+    'contract-graph.json', 'architecture-graph.json', 'implementation-plan.json',
+    `${slug(mission)}.md`, `${slug(mission)}.mmd`, `${slug(mission)}.testplan.md`,
+  ];
+  const proof = buildProof(ast, {
+    sourceFile, sourceHash, generatedAt: at, origin,
+    targetsRequested: ast.targets, targetsGenerated, diagnostics,
+  });
+
+  return {
+    mission,
+    origin,
+    // Canonical cross-ecosystem intent reference ids , producers (OT/RM/STT/Certified) put these
+    // in evidence-event-v1 / proof-bundle-v1 `intentReferences[]` so evidence cites this exact intent.
+    intentRef: intentRefId(ast),                          // subject-level: intent:<slug>
+    intentRefPinned: intentRefId(ast, { sourceHash }),    // version-pinned: intent:<slug>@<sha8>
+    // Ownership Graph seam: skills this intent requires (shared skill: ids) + required-understanding.
+    // Producers drop `skillsRequired` straight into evidence-event-v1 `skillIds[]`.
+    skillsRequired: (ast.skills || []).map((s) => s.id).filter(Boolean),
+    demonstrates: (ast.demonstrates || []).map((d) => d.statement),
+    // 12-Factor Agents conformance summary (score/grade/counts). Full per-factor report via twelveFactorReport.
+    twelveFactor: twelveFactorSummary(ast),
+    diagnostics,
+    notes: ast.notes || [],
+    artifacts: {
+      markdown, mermaid, testplan,
+      contractGraph, architectureGraph, implementationPlan, proof,
+    },
+  };
+}

package/src/comprehension.mjs

@@ -0,0 +1,130 @@
+// Comprehension Contracts + the C0..C6 level (intent-comprehension-v1). The measurable backbone
+// of the Software Understanding System: given a mission's Intended Truth (its intent), compute
+// how well-understood it is, from C0 (Unknown) to C6 (Teachable). Deterministic, no AI, pure
+// (browser-safe), so IL is the single evaluator and every product , Atlas overlays it, Fable
+// reports it, Skills Tech Talk targets it, OpenThunder lifts it to C5 with runtime evidence ,
+// reads ONE number, never a fork.
+//
+// Honesty boundary: IL computes the intent-side levels (C1..C4) deterministically. C5 (Observed)
+// needs runtime evidence (OpenThunder / runtime) and C6 (Teachable) needs a learning path
+// (Skills Tech Talk); IL reports what it can determine and names the sibling that owns each gap,
+// never inflating a level on evidence it does not have.
+
+export const COMPREHENSION_SCHEMA = 'intent-comprehension-v1';
+
+export const LEVELS = [
+  { level: 'C0', name: 'Unknown', means: 'Intent exists with no stated purpose.' },
+  { level: 'C1', name: 'Described', means: 'Purpose and a summary exist.' },
+  { level: 'C2', name: 'Structured', means: 'Guarantees, rules, states, failures, or constraints exist.' },
+  { level: 'C3', name: 'Mapped', means: 'Intent links to implementation (targets, components, APIs, architecture).' },
+  { level: 'C4', name: 'Verified', means: 'Every guarantee and never-rule carries a verification.' },
+  { level: 'C5', name: 'Observed', means: 'Runtime evidence is connected and discrepancies are monitored.' },
+  { level: 'C6', name: 'Teachable', means: 'A source-grounded explanation and learning path exist.' },
+  { level: 'C7', name: 'Governed', means: 'Drift is monitored, ownership and risk are on the record, and the understanding stays true as the software evolves.' },
+];
+
+const nonEmpty = (a) => Array.isArray(a) && a.length > 0;
+
+/**
+ * Evaluate a mission's comprehension level from its AST (its Intended Truth). Optional external
+ * signals let a sibling lift the joint level: `observed` (OpenThunder/runtime evidence present)
+ * for C5, `learningPath` (Skills Tech Talk) for C6. Pure and deterministic.
+ */
+export function comprehensionLevel(ast, { observed = false, learningPath = false, governed = false } = {}) {
+  const guarantees = ast?.guarantees || [];
+  const nevers = ast?.neverRules || [];
+  const claims = [...guarantees, ...nevers];
+  const allVerified = claims.length > 0 && claims.every((c) => nonEmpty(c.verify));
+
+  // Each signal: is it met, from what evidence, and (if not IL-determinable) who owns it.
+  const signals = {
+    purpose: {
+      // A purpose/summary in any form: a goal, a why, a product title, or the problem statement.
+      // (goal/why/title/problem are strings on the AST, not lists.)
+      met: Boolean(ast?.goal) || Boolean(ast?.why) || Boolean(ast?.title) || Boolean(ast?.problem),
+      evidence: [ast?.goal && 'goal', ast?.why && 'why', ast?.title && 'title', ast?.problem && 'problem'].filter(Boolean),
+      owner: 'ThunderLang',
+    },
+    structure: {
+      met: nonEmpty(guarantees) || nonEmpty(nevers) || nonEmpty(ast?.decisions)
+        || nonEmpty(ast?.lifecycles) || nonEmpty(ast?.errors) || nonEmpty(ast?.constraints) || nonEmpty(ast?.invariants),
+      evidence: [
+        nonEmpty(guarantees) && 'guarantees', nonEmpty(nevers) && 'never', nonEmpty(ast?.decisions) && 'decisions',
+        nonEmpty(ast?.lifecycles) && 'lifecycles', nonEmpty(ast?.errors) && 'errors', nonEmpty(ast?.constraints) && 'constraints',
+        nonEmpty(ast?.invariants) && 'invariants',
+      ].filter(Boolean),
+      owner: 'ThunderLang',
+    },
+    mapping: {
+      met: nonEmpty(ast?.targets) || nonEmpty(ast?.components) || nonEmpty(ast?.apis)
+        || nonEmpty(ast?.services) || Boolean(ast?.implementation) || nonEmpty(ast?.architecture),
+      evidence: [
+        nonEmpty(ast?.targets) && 'target', nonEmpty(ast?.components) && 'components', nonEmpty(ast?.apis) && 'apis',
+        nonEmpty(ast?.services) && 'services', ast?.implementation && 'implementation', nonEmpty(ast?.architecture) && 'architecture',
+      ].filter(Boolean),
+      owner: 'ThunderLang',
+    },
+    verification: {
+      met: allVerified,
+      evidence: allVerified ? [`${claims.length}/${claims.length} claims verified`] : (claims.length ? [`${claims.filter((c) => nonEmpty(c.verify)).length}/${claims.length} claims verified`] : []),
+      owner: 'ThunderLang + OpenThunder',
+    },
+    observation: {
+      met: Boolean(observed),
+      evidence: observed ? ['runtime evidence provided'] : [],
+      owner: 'OpenThunder / runtime', // IL cannot observe production; the level rises when OT attaches evidence
+    },
+    teachability: {
+      met: Boolean(learningPath) || nonEmpty(ast?.notes) || nonEmpty(ast?.examples),
+      evidence: [learningPath && 'learning path', nonEmpty(ast?.notes) && 'notes', nonEmpty(ast?.examples) && 'examples'].filter(Boolean),
+      owner: 'Skills Tech Talk (learning) + ThunderLang (notes/examples)',
+    },
+    governance: {
+      // Understanding that stays true as the software changes: drift monitored (Guardian) AND
+      // ownership + declared risk on the record. IL supplies the record; Guardian supplies drift.
+      met: Boolean(governed) && Boolean(ast?.owner) && (nonEmpty(ast?.unknowns) || nonEmpty(ast?.assumptions) || nonEmpty(ast?.conflicts) || nonEmpty(ast?.waivers)),
+      evidence: [governed && 'drift-monitored', ast?.owner && 'ownership', (nonEmpty(ast?.unknowns) || nonEmpty(ast?.assumptions) || nonEmpty(ast?.conflicts) || nonEmpty(ast?.waivers)) && 'risk on record'].filter(Boolean),
+      owner: 'Intent Guardian (drift) + Workspace/Ledger (risk + approvals)',
+    },
+  };
+
+  // The ladder is cumulative: the level is the highest Cn where C1..Cn are all met.
+  const ladder = ['purpose', 'structure', 'mapping', 'verification', 'observation', 'teachability', 'governance'];
+  let n = 0;
+  for (const s of ladder) { if (signals[s].met) n += 1; else break; }
+  const level = LEVELS[n];
+
+  // The next unmet rungs become explicit gaps with the owner responsible for closing each.
+  const missing = [];
+  for (let i = n; i < ladder.length; i += 1) {
+    const lv = LEVELS[i + 1];
+    missing.push({ level: lv.level, name: lv.name, need: lv.means, owner: signals[ladder[i]].owner });
+  }
+
+  return {
+    schema: COMPREHENSION_SCHEMA,
+    mission: ast?.mission || null,
+    level: level.level,
+    levelName: level.name,
+    means: level.means,
+    signals,
+    missing,
+    // The Comprehension Contract checklist , what a critical capability should declare (capability 14).
+    contract: {
+      why: signals.purpose.met, structure: signals.structure.met, mapping: signals.mapping.met,
+      verification: signals.verification.met, observation: signals.observation.met,
+      teachability: signals.teachability.met, governance: signals.governance.met,
+      ownership: Boolean(ast?.owner), nonGoals: nonEmpty(ast?.nonGoals),
+      unknownsDeclared: nonEmpty(ast?.unknowns) || nonEmpty(ast?.assumptions) || nonEmpty(ast?.conflicts),
+    },
+  };
+}
+
+/** Evaluate many missions and summarize the distribution across levels. */
+export function comprehensionReport(asts, opts = {}) {
+  const missions = (asts || []).map((ast) => comprehensionLevel(ast, opts));
+  const byLevel = {};
+  for (const lv of LEVELS) byLevel[lv.level] = 0;
+  for (const m of missions) byLevel[m.level] += 1;
+  return { schema: COMPREHENSION_SCHEMA, count: missions.length, byLevel, missions };
+}

package/src/core.d.ts

@@ -0,0 +1,99 @@
+// Types for `@skillstech/thunderlang/core` , the universal (Node + browser + React Native)
+// surface. This re-exports exactly the symbols core.mjs exports, using the declarations in
+// index.d.ts as the single source of truth. It intentionally does NOT re-export the Node-only
+// surface (CLI, LSP, filesystem lift/drift), so a consumer cannot type-import something that
+// is not actually in the universal build.
+
+// The canonical hash (byte-identical to node:crypto).
+export { sha256, sha256hex } from './index';
+
+// Parser + graph + in-memory compile.
+export {
+  IntentAst, Diagnostic, parseIntent, slug, KNOWN_LENSES,
+  INTENT_GRAPH_SCHEMA, IntentGraph, IntentGraphNode, buildIntentGraph,
+  compileSource, renderMarkdown, renderMermaid, renderTestplan,
+  semanticDiagnostics, buildContractGraph, buildArchitectureGraph, buildImplementationPlan, buildProof,
+} from './index';
+
+// IntentLift: code -> inferred candidate intent (OT orchestrates this in-process).
+export {
+  liftSource, liftAll, liftRepo, languageForFile, inferIntent, renderLiftedIntent, SUPPORTED_LANGUAGES,
+  IntentSeed, SEED_SCHEMA, normalizeSeeds,
+} from './index';
+
+// Intent Scanner + Fable.
+export {
+  SCAN_SCHEMA, ScanResult, scanIntent, scanProject,
+  FABLE_SCHEMA, RISK_CATEGORIES, Finding, toFinding, fableRuleFor, universalPack,
+} from './index';
+
+// Focused scan query views.
+export {
+  VIEW_SCHEMA, VIEWS, risksView, gapsView, unverifiedView, coverageView, unknownsView, contradictionsView,
+} from './index';
+
+// Intent Atlas + navigation.
+export {
+  ATLAS_SCHEMA, IntentAtlas, buildAtlas, atlasNode, expandNode, searchAtlas,
+} from './index';
+
+// Intent Lens , Intent Scope + Focus Graph + Intent Brief.
+export {
+  FOCUS_SCHEMA, SCOPE_TYPES, FOCUS_REASONS, IntentScope, FocusNode, FocusGraph, IntentBrief,
+  makeScope, buildFocusGraph, intentBrief,
+} from './index';
+
+// Comprehension Contract , the C0..C7 understanding level.
+export {
+  COMPREHENSION_SCHEMA, COMPREHENSION_LEVELS, ComprehensionResult, ComprehensionSignal,
+  comprehensionLevel, comprehensionReport,
+} from './index';
+
+// Code generation , deterministic scaffolds from intent.
+export { CODEGEN_SCHEMA, GENERATORS, toTypeScript, toCSharp, toJava, subjectName, intentRefId, skillRefId } from './index';
+
+// 12-Factor Agents conformance lens (twelve-factor-v1).
+export { TWELVE_FACTOR_SCHEMA, TwelveFactorResult, twelveFactorReport, twelveFactorSummary } from './index';
+
+// Change Lens , what a branch/PR changed by meaning.
+export { CHANGES_SCHEMA, ChangeReport, changeReport } from './index';
+
+// Change Lens , semantic diff + 3-way merge + graph->source round-trip.
+export {
+  IntentDiff, IntentMerge, diffGraphs, mergeGraphs,
+  GRAPH_SOURCE_SCHEMA, graphToSource,
+} from './index';
+
+// Shared Intent IR (intent-ir-v1) + classification model.
+export {
+  IR_SCHEMA, IR_EMBEDS, IR_NODE_TYPES, IR_RELATIONSHIP_TYPES, PROVENANCE, FACTUAL_PROVENANCE,
+  isFactualProvenance, IR_CONFIDENCE, IR_CONFIDENCE_MEANING, confidenceFromClassification,
+  SENSITIVITY, RETENTION, REVIEW_STATUS, APPROVAL_STATUS, NODE_FIELDS,
+  IntentIR, IntentIRNode, validateIR, graphToIR,
+  CLASSIFICATIONS, CONFIDENCE, UNSETTLED, BLOCKABLE_PHASES,
+} from './index';
+
+// Canonical schema constants + proof envelope.
+export {
+  SCHEMA_VERSION, NODE_TYPES, RELATIONSHIP_TYPES, intentGraphJsonSchema,
+  DIAGNOSTIC_RULES, CORE_DIAGNOSTICS, ALL_DIAGNOSTICS,
+  RULE_PHASES, RULE_OWNERS, RULE_NAMESPACES, VERIFICATION_RULES, ruleNamespace,
+  PROOF_SCHEMA, CLAIM_STATUSES, PROOF_STATUSES, intentProofJsonSchema, validateProof,
+} from './index';
+
+// The pure Intent Runtime + guard + prompt->intent draft + expression engine.
+export {
+  evaluateDecision, simulateLifecycle, checkDecisionCases, RUNTIME_SCHEMA,
+  buildGuard, compileGuard, guardSummary, GUARD_SCHEMA,
+  draftIntent, DRAFT_SCHEMA,
+} from './index';
+
+// Human <-> Structured <-> ThunderLang sync + comment-preserving structural editing.
+export {
+  parseToStructured, proposeIntent, SYNC_SCHEMA, applyEdits, PATCH_SCHEMA,
+} from './index';
+
+// Style intent , canonical token address space + accessibility vocabulary.
+export {
+  analyzeStyle, styleDiagnostics, toDesignTokens, toCss, STYLE_SCHEMA, DESIGN_TOKENS_SCHEMA,
+} from './index';