@skillstech/thunderlang 0.3.0 → 0.4.2

package/src/cli.mjs

@@ -84,6 +84,7 @@ function runLiveTarget(ast, target) {
 }
 import { importIntent, importReport, detectFormat, IMPORT_FORMATS } from './importers.mjs';
 import { runTests } from './testing.mjs';
+import { toEvidenceEvents, verifyDiffToEvidence, conformToEvidence, driftToEvidence } from './evidence.mjs';
 import { evaluateOutcomes } from './outcome.mjs';
 import { analyzeStyle } from './style.mjs';
 import { intentProofJsonSchema, validateProof } from './proof-schema.mjs';
@@ -261,6 +262,7 @@ function parseArgs(argv) {
     else if (a === '--governed') args.governed = true;
     else if (a === '--target') args.target = argv[++i];
     else if (a === '--all-targets') args.allTargets = true;
+    else if (a === '--evidence') args.evidence = true;
     else if (a === '--env') args.env = argv[++i];
     else if (a === '--brief') args.brief = argv[++i];
     else if (a === '--after') args.after = argv[++i];
@@ -327,81 +329,85 @@ function printDiagnostics(diags) {
 
 const HELP = `thunder , the ThunderLang compiler + engine (deterministic, no AI required)
 
+The flow: author intent, inspect it, run and prove it, then keep real code aligned with it.
+
 usage: thunder <command> <file> [options]
        thunder mission <Name> <command>     run any command on a mission by name
 
-Everyday
-  new [Name]               scaffold a runnable starter mission (Name.thunder)   [alias: init]
-  mission <Name> [cmd]     resolve a mission by name and run a command on it (list | <Name> | <Name> <cmd>)
-  check <file|dir>         parse + lint + explainable diagnostics
-  run <file> --inputs '<json>'         execute the decision(s) deterministically
+Author
+  new [Name]                 scaffold a runnable starter mission (Name.thunder)   [alias: init]
+  mission <Name> [cmd]       resolve a mission by name and run a command on it (list | <Name> | <Name> <cmd>)
+  draft --brief <json|->     scaffold a rigorous intent draft + gap checklist from a brief
+  edit <file> [--edits <json|->] [--set-goal ..] [--add-guarantee ..] [--write]   structural edits, comments kept
+  fmt <file|dir> [--write|--check]   canonical formatting (whitespace only; comments kept)
+  source <file|graph.json>   regenerate .thunder from a persisted graph
+
+Inspect
+  check <file|dir> [--json|--format sarif]   parse + lint + explainable diagnostics; gate a whole dir
+  report [dir] [--json]      repo-wide intent health: severity + area counts, coverage
+  risks | gaps | unverified | coverage | unknowns | contradictions [dir] [--json]   focused scan queries
+  focus <mission|query|--nodes a,b> [--depth N] [--dir <d>] [--json]   Intent Lens: focused graph + brief
+  comprehension <file|dir> [--observed] [--learning] [--governed] [--json]   the C0..C7 understanding level
+  twelve-factor <file> [--json]   score against the 13 humanlayer/12-factor-agents principles   [alias: 12factor]
+  explain <IL-CODE>          explain a diagnostic code (area, severity, what it blocks)
+  rules [--json]             list the whole canonical diagnostic catalog
+  notes <file> [--lens <lens>] [--json]   ThunderLens: the compiled note blocks by lens (not verification)
+  docs <file> [--lens <lens>] [--out <dir>]   render a mission as Markdown docs (per-audience with --lens)
+  index <dir>                the Mission Atlas inventory
+  atlas <dir> [--search q | --expand id]   the whole-system Atlas
+
+Run & test
+  run <file> --inputs '<json>'   execute the decision(s) deterministically
   test <file> [--contracts | --properties | --scenarios | --mutate | --evals | --changed | --coverage] [--strict]
   test <file> --target typescript|python|csharp|java   run the tests against the EXECUTED generated code
-  test <file> --all-targets            run the tests against every AVAILABLE target in one pass
-  prove <file>             emit an intent-proof-v1 artifact (honest verdicts + freshness)
+  test <file> --all-targets  run the tests against every AVAILABLE target in one pass
+  simulate <file> --events a,b,c   walk the lifecycle(s) over events
+  outcomes <file>            evaluate outcome contracts vs delivery results
+  style <file>               resolve style intents vs the canonical token space
+  gen <file> [--target typescript|csharp|java|python] [--out <dir>]   deterministic code scaffold (types + decision logic + TODOs)
+  build <file>               generate docs, contract graph, test plan, and .thunder-proof.json
+
+Prove & verify intent
+  prove <file>               emit an intent-proof-v1 artifact (honest verdicts + freshness)
+  proof <file>               the .thunder-proof.json artifact (see also: prove, which emits verdicts)
+  proof --schema             emit the canonical proof envelope JSON Schema (intent-proof-v1)
   verify <proof.json> [src]  re-check a proof; reports STALE when impl/deps/compiler moved
-  build <file>             generate docs, contract graph, test plan, targets
-
-Author & check
-  init [Name]              scaffold a runnable starter mission (Name.thunder)
-  draft --brief <json|->   scaffold a rigorous intent draft + gap checklist from a brief
-  check <file|dir> [--json|--format sarif]  diagnostics for one file, or gate a whole dir
-  report [dir] [--json]     repo-wide intent health: severity + area counts, coverage
-  scan [dir] [--json] [--ir <path>]  Scanner: intent -> Intent IR -> Fable findings -> risk themes
-  risks | gaps | unverified | coverage | unknowns | contradictions [dir] [--json]  focused scan queries
-  focus <mission|query|--nodes a,b> [--depth N] [--dir <d>] [--json]  Intent Lens: focused graph + brief
-  comprehension <file|dir> [--observed] [--learning] [--governed] [--json]  the C0..C7 understanding level
-  twelve-factor <file> [--json]  score an intent against the 13 humanlayer/12-factor-agents principles
-  gen <file> [--target typescript|csharp|java] [--out <dir>]  deterministic code scaffold (types + decision logic + TODOs)
-  changes [<base>..<head> | <base>] [--json]  Change Lens: what a branch/PR changed by meaning
-  guardian <before> <after>  drift: what changed, what risk, what to reverify, what learning is stale
-  impact <base> <proposed>  Simulator: estimate a change's blast radius + risk BEFORE building it
-  ledger <file.json> [--subject <id>]  verify the tamper-evident history + explain why/who/what changed
-  guard <file> [--json]     preview the runtime guard (redacted fields, enforced decisions)
-  fmt <file|dir> [--write|--check]  canonical formatting (whitespace only; comments kept)
-  edit <file> [--edits <json|->] [--set-goal ..] [--add-guarantee ..] [--write]  structural edits, comments kept
-  lsp                      start the Language Server (LSP over stdio, for editors)
-  mcp                      start the MCP server (for AI coding agents; stdio)
-  build <file>              docs, contract graph, test plan, and .thunder-proof.json
-  graph <file> [--safe]     the canonical Intent Graph (intent-graph-v1); --safe = display-safe on stdout
-  proof <file>              the .thunder-proof.json artifact
-  proof --schema            emit the canonical proof envelope JSON Schema (intent-proof-v1)
-  verify <proof.json> [src]  confirm a proof is well-formed and still matches its source
-  conform <file> [--targets a,b] [--run typescript,python,csharp,java | --all-targets] [--results <json>]  run the same cases against every target (conformance matrix)
-  schema                    emit the canonical graph schema + diagnostic catalog
-  explain <IL-CODE>         explain a diagnostic code (area, severity, what it blocks)
-  rules [--json]            list the whole canonical diagnostic catalog
-  notes <file> [--lens <lens>] [--json]  ThunderLens: the compiled note blocks by lens (not verification)
-  docs <file> [--lens <lens>] [--out <dir>]  render a mission as Markdown docs (per-audience with --lens)
-  code-actions <file> [--json]  available quick-fixes, safety-graded (safe | reviewable)
-  apply-fix <file> [--write]    apply the SAFE autocorrects (header aliases, stray colons)
-
-Execute (no AI, no generated code)
-  run <file> --inputs '<json>'      evaluate the decision(s) against inputs
-  simulate <file> --events a,b,c    walk the lifecycle(s) over events
-  test <file>                       run the in-file test blocks (case/scenario)
-  outcomes <file>                   evaluate outcome contracts vs delivery results
-  style <file>                      resolve style intents vs the canonical token space
+  evidence <file>            emit evidence-event-v1 JSON (tool_verified) for the shared proof spine
+                             (also: prove/verify-diff/conform/drift accept --evidence to emit their own event)
+  conform <file> [--targets a,b] [--run typescript,python,csharp,java | --all-targets] [--results <json>]   conformance matrix across targets
+
+Real code vs intent (drift)
+  lift <file> [--from <lang>]    lift source code into inferred intent
+  drift <codeFile> --intent <file.intent> [--from <lang>]   check intent vs code drift
+  approve <file> --by <name>     approve intent (drift baseline)
+  verify-diff <intent> --after <code> [--before <code>]   gate a code change against its intent
+  changes [<base>..<head> | <base>] [--json]   Change Lens: what a branch/PR changed by meaning
+  guardian <before> <after>      drift: what changed, what risk, what to reverify, what learning is stale
+  impact <base> <proposed>       Simulator: estimate a change's blast radius + risk BEFORE building it
+  diff <before> <after>          semantic diff (by meaning)
+  merge <base> <ours> <theirs>   deterministic 3-way semantic merge
+  handoff <file>                 the OpenThunder drift handoff
+  ledger <file.json> [--subject <id>]   verify the tamper-evident history + explain why/who/what changed
+  guard <file> [--json]          preview the runtime guard (redacted fields, enforced decisions)
+
+Graph & IR
+  graph <file> [--safe]      the canonical Intent Graph (intent-graph-v1); --safe = display-safe on stdout
+  migrate <graph.json> [--to <version>]   upgrade a persisted graph
+  validate <graph.json> [--json]   check a graph is canonical (anti-fork)
+  schema                     emit the canonical graph schema + diagnostic catalog
 
 Interop
   export <file> --format <dmn|bpmn|smv|jsonschema|openapi|tokens|mermaid|css|playwright>   render to a standard format
-  import <file> [--format dmn|bpmn] [--json]                 lift DMN/BPMN into intent
-  source <file|graph.json>                                   regenerate .thunder from a graph
-  migrate <graph.json> [--to <version>]                      upgrade a persisted graph
-  validate <graph.json> [--json]                             check a graph is canonical (anti-fork)
+  import <file> [--format dmn|bpmn] [--json]   lift DMN/BPMN into intent
 
-Navigate & compare (over many missions)
-  atlas <dir> [--search q | --expand id]   the whole-system Atlas
-  index <dir>                              the Mission Atlas inventory
-  diff <before> <after>                    semantic diff (by meaning)
-  merge <base> <ours> <theirs>             deterministic 3-way semantic merge
+Fix
+  scan [dir] [--json] [--ir <path>]   Scanner: intent -> Intent IR -> Fable findings -> risk themes
+  code-actions <file> [--json]   available quick-fixes, safety-graded (safe | reviewable)
+  apply-fix <file> [--write]     apply the SAFE autocorrects (header aliases, stray colons)
 
-Code <-> intent
-  lift <file> [--from <lang>]   lift source code into inferred intent
-  approve <file> --by <name>    approve intent (drift baseline)
-  drift <file> --from <code>    check intent vs code drift
-  verify-diff <intent> --after <code> [--before <code>]  gate a code change against its intent
-  handoff <file>                the OpenThunder drift handoff
+Servers
+  lsp                        start the Language Server (LSP over stdio, for editors)
+  mcp                        start the MCP server (for AI coding agents; stdio)
 
 Common options: --out <dir>, --json, --no-ai. See https://thunderlang.dev/docs`;
 
@@ -648,7 +654,7 @@ function main() {
     return;
   }
 
-  // `thunder gen <file> [--target typescript|csharp|java] [--out <dir>]` , deterministic code scaffold from
+  // `thunder gen <file> [--target typescript|csharp|java|python] [--out <dir>]` , deterministic code scaffold from
   // intent. Generates the typed contract + the decision logic (already executable) and leaves
   // honest TODO markers for business logic. No AI. Prints, or writes with --out.
   if (cmd === 'gen') {
@@ -659,7 +665,7 @@ function main() {
     const ast = parseIntent(readFileSync(file, 'utf8'));
     const code = generate(ast);
     if (args.outExplicit) {
-      const ext = target.startsWith('ts') || target === 'typescript' ? 'ts' : target;
+      const ext = target.startsWith('ts') || target === 'typescript' ? 'ts' : target === 'python' ? 'py' : target === 'csharp' ? 'cs' : target;
       const p = writeText(args.out, `${slug(subjectName(ast) || 'intent')}.${ext}`, code.endsWith('\n') ? code : code + '\n');
       console.log(`wrote ${p.replace(process.cwd() + '/', '')}`);
       return;
@@ -858,7 +864,7 @@ test Example
     if (!res.ok) { console.error(res.error); process.exit(1); }
     if (args.json) { console.log(JSON.stringify(res.summary, null, 2)); return; }
     if (args.out) {
-      const p = writeText(args.out, `${slug(res.lifted.mission)}.intent`, res.intentText);
+      const p = writeText(args.out, `${slug(res.lifted.mission)}.thunder`, res.intentText);
       console.log(`thunder lift ${basename(file)} -> ${p.replace(process.cwd() + '/', '')}`);
     } else {
       console.log(res.intentText);
@@ -899,6 +905,11 @@ test Example
     const codeText = readFileSync(file, 'utf8');
     const language = args.from && args.from !== 'repo' ? args.from : languageForFile(file);
     const res = checkDrift(intentText, codeText, { language });
+    if (args.evidence) {
+      const ctx = { compilerVersion: COMPILER_VERSION, occurredAt: new Date().toISOString(), missionName: parseIntent(intentText).mission || null, intentHash: sha256(intentText), codeHash: sha256(codeText) };
+      console.log(JSON.stringify(driftToEvidence(res, ctx), null, 2));
+      process.exit(res.status === 'drift' ? 1 : 0); return;
+    }
     if (args.json) { console.log(JSON.stringify(res, null, 2)); }
     else {
       console.log(`thunder drift: ${res.status.toUpperCase()} (${res.summary.blocking} blocking)`);
@@ -1503,6 +1514,34 @@ test Example
     return;
   }
 
+  // `thunder evidence <file>` , project the intent's proof into evidence-event-v1 events for the
+  // shared SkillsTech evidence graph (STW spine). Deterministic, offline, safe-derived; prints JSON.
+  // The network push to the spine belongs to the org-layer/CI, not this CLI.
+  if (cmd === 'evidence') {
+    if (!file || !existsSync(file)) { console.error('usage: thunder evidence <file>  # emit evidence-event-v1 JSON for the shared proof spine'); process.exit(2); return; }
+    const source = readFileSync(file, 'utf8');
+    const ast = parseIntent(source);
+    const diagnostics = semanticDiagnostics(ast);
+    const resolved = resolveObligations(ast);
+    const proof = buildProof(ast, {
+      sourceFile: basename(file),
+      sourceHash: sha256(source),
+      targetsRequested: ast.targets || [],
+      targetsGenerated: [],
+      diagnostics,
+      generatedAt: new Date().toISOString(),
+    });
+    const CLAIM_MAP = { verified: 'verified', failed: 'failed', declared: 'planned', unverified: 'needs_verification' };
+    const byId = new Map(resolved.obligations.map((o) => [o.id, o]));
+    const applyStatus = (claim) => { const o = byId.get(claim.id); return o ? { ...claim, status: CLAIM_MAP[o.status], provenBy: o.provenBy || null } : claim; };
+    proof.guarantees = proof.guarantees.map(applyStatus);
+    proof.neverRules = proof.neverRules.map(applyStatus);
+    proof.freshness = freshnessFor(file, proof, args.env);
+    const events = toEvidenceEvents(proof);
+    console.log(JSON.stringify(events, null, 2));
+    return;
+  }
+
   // CONFORMANCE: the same test cases run against every target. The engine defines the canonical
   // result each case must produce; target outputs fed via --results are graded against it.
   // `thunder conform <file> [--targets ts,py] [--results <json|path>] [--json]`.
@@ -1540,6 +1579,11 @@ test Example
     const rep = buildConformance(ast, { targets, results });
     if (skippedTargets.length) rep.skipped = Array.from(new Set(skippedTargets));
     const bad = rep.semanticFailures > 0 || rep.failures.length > 0;
+    if (args.evidence) {
+      const ctx = { compilerVersion: COMPILER_VERSION, occurredAt: new Date().toISOString(), missionName: ast.mission || null, intentHash: sha256(readFileSync(file, 'utf8')) };
+      console.log(JSON.stringify(conformToEvidence(rep, ctx), null, 2));
+      process.exit(bad ? 1 : 0); return;
+    }
     if (args.json) { console.log(JSON.stringify(rep, null, 2)); process.exit(bad ? 1 : 0); return; }
     if (!rep.total) { console.log(`thunder conform ${basename(file)}: no test cases to conform.`); return; }
 
@@ -1750,6 +1794,11 @@ test Example
     const before = args.before ? readFileSync(args.before, 'utf8') : null;
     const language = args.from || languageForFile(args.after);
     const r = verifyDiff(intentText, { before, after, language });
+    if (args.evidence) {
+      const ctx = { compilerVersion: COMPILER_VERSION, occurredAt: new Date().toISOString(), missionName: parseIntent(intentText).mission || null, intentHash: sha256(intentText), changeHash: sha256(after) };
+      console.log(JSON.stringify(verifyDiffToEvidence(r, ctx), null, 2));
+      process.exit(r.ok ? 0 : 1); return;
+    }
     if (args.json) { console.log(JSON.stringify(r, null, 2)); process.exit(r.ok ? 0 : 1); return; }
     console.log(`thunder verify-diff ${basename(file)} vs ${basename(args.after)}: ${r.verdict} (${r.blocking} blocking, ${r.summary.regressions} regression(s))`);
     for (const f of r.findings) {

package/src/codegen.mjs

@@ -5,9 +5,9 @@
 // the "see how it works, then change it" surface for the playground and `thunder 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.
+// shape (a type map + a body walk) extends to C# / Java / Python.
 
-import { exprToJs, exprToCSharp, exprToJava } from './expr.mjs';
+import { exprToJs, exprToCSharp, exprToJava, exprToPython } from './expr.mjs';
 import { subjectName } from './parse.mjs';
 
 export const CODEGEN_SCHEMA = 'intent-codegen-v1';
@@ -138,7 +138,7 @@ export function toCSharp(ast) {
     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}" */`; }
+      let cond; try { cond = exprToCSharp(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`, '  }');
@@ -146,6 +146,7 @@ export function toCSharp(ast) {
   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 r of ast.requires || []) L.push(`    // precondition: ${r}  , TODO: validate`);
   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.");', '  }');
@@ -192,7 +193,7 @@ export function toJava(ast) {
     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}" */`; }
+      let cond; try { cond = exprToJava(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`, '  }');
@@ -200,6 +201,7 @@ export function toJava(ast) {
   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 r of ast.requires || []) L.push(`    // precondition: ${r}  , TODO: validate`);
   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.");', '  }');
@@ -207,8 +209,75 @@ export function toJava(ast) {
   return L.join('\n');
 }
 
+// ── Python ───────────────────────────────────────────────────────────────────
+const PY_TYPES = {
+  Email: 'str', Url: 'str', UserId: 'str', AccountId: 'str', OrderId: 'str',
+  InvoiceId: 'str', CustomerId: 'str', Secret: 'str', Token: 'str', Jwt: 'str',
+  IdempotencyKey: 'str', Currency: 'str', Date: 'str', DateTime: 'str',
+  Money: 'float', Percentage: 'float', Count: 'int', Duration: 'int', Flag: 'bool',
+};
+function pyType(type, domain) {
+  if (!type) return 'object';
+  const list = /^List<(.+)>$/.exec(type);
+  if (list) return `list[${pyType(list[1], domain)}]`;
+  const base = type.replace(/\(.*\)/, '');
+  if (PY_TYPES[base]) return PY_TYPES[base];
+  domain.add(base); return base;
+}
+// PascalCase/camelCase -> snake_case, for idiomatic Python function names. Field and decision
+// input names stay verbatim: the translated conditions reference them by their intent names.
+const snake = (s) => pascal(s).replace(/([a-z0-9])([A-Z])/g, '$1_$2').toLowerCase();
+
+/** Generate a deterministic Python scaffold from an intent AST. */
+export function toPython(ast) {
+  const subject = pascal(subjectName(ast) || 'Intent');
+  const domain = new Set();
+  const L = [
+    `# ${subject} , generated from ThunderLang (intent-codegen-v1). Deterministic, no AI.`,
+    '# The dataclass 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.',
+    '',
+  ];
+  const hasData = (ast.inputs || []).length || (ast.outputs || []).length;
+  // Postponed annotations so a dataclass may reference a domain stub declared below it.
+  if (hasData) L.push('from __future__ import annotations', 'from dataclasses import dataclass', '');
+  const cls = (name, fields) => fields.length
+    ? ['@dataclass', `class ${name}:`, ...fields.map((f) => `    ${f.name}: ${pyType(f.type, domain)}`), '']
+    : [];
+  if ((ast.inputs || []).length) L.push(...cls(`${subject}Input`, ast.inputs));
+  if ((ast.outputs || []).length) L.push(...cls(`${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(`def ${snake(d.name)}(${inputs.join(', ')}) -> str:`);
+    for (const r of d.rules || []) {
+      let cond, note = '';
+      try { cond = exprToPython(r.when, { inputs }); }
+      catch { cond = 'False'; note = `  # TODO: could not translate "${r.when}"`; }
+      L.push(`    if ${cond}:${note}`);
+      L.push(`        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` : 'None';
+  L.push(`def run(${inName ? `input: ${inName}` : ''}) -> ${outName}:`);
+  for (const r of ast.requires || []) L.push(`    # precondition: ${r}  , TODO: validate`);
+  for (const n of ast.neverRules || []) L.push(`    # NEVER: ${n.statement}`);
+  for (const g of ast.guarantees || []) L.push(`    # GUARANTEE: ${g.statement}`);
+  L.push('    raise NotImplementedError("TODO: implement , the intent above defines what this must do.")', '');
+  const stubs = [...domain].filter((t) => !PY_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(`class ${t}: pass  # TODO: fields`);
+    L.push('');
+  }
+  return L.join('\n');
+}
+
 export const GENERATORS = {
   typescript: toTypeScript, ts: toTypeScript,
   csharp: toCSharp, cs: toCSharp,
   java: toJava,
+  python: toPython, py: toPython,
 };

package/src/core.d.ts

@@ -50,7 +50,7 @@ export {
 } from './index';
 
 // Code generation , deterministic scaffolds from intent.
-export { CODEGEN_SCHEMA, GENERATORS, toTypeScript, toCSharp, toJava, subjectName, intentRefId, skillRefId } from './index';
+export { CODEGEN_SCHEMA, GENERATORS, toTypeScript, toCSharp, toJava, toPython, subjectName, intentRefId, skillRefId } from './index';
 
 // 12-Factor Agents conformance lens (twelve-factor-v1).
 export { TWELVE_FACTOR_SCHEMA, TwelveFactorResult, twelveFactorReport, twelveFactorSummary } from './index';

package/src/core.mjs

@@ -80,7 +80,7 @@ export { FOCUS_SCHEMA, SCOPE_TYPES, FOCUS_REASONS, makeScope, buildFocusGraph, i
 // Comprehension Contract: the C0..C7 understanding level (browser-safe; every product reads it).
 export { COMPREHENSION_SCHEMA, LEVELS as COMPREHENSION_LEVELS, comprehensionLevel, comprehensionReport } from './comprehension.mjs';
 // Code generation: deterministic scaffolds from intent (browser-safe, so the playground renders it).
-export { CODEGEN_SCHEMA, GENERATORS, toTypeScript, toCSharp, toJava } from './codegen.mjs';
+export { CODEGEN_SCHEMA, GENERATORS, toTypeScript, toCSharp, toJava, toPython } from './codegen.mjs';
 // Change Lens: what a branch/PR changed by meaning (pure; the CLI supplies the git-diffed graphs).
 export { CHANGES_SCHEMA, changeReport } from './changes.mjs';
 export { subjectName, intentRefId, skillRefId } from './parse.mjs';

package/src/emit.mjs

@@ -30,7 +30,7 @@ export function notesSummary(ast) {
   };
 }
 
-export const COMPILER_VERSION = '0.3.0';
+export const COMPILER_VERSION = '0.4.2';
 export const PROOF_SCHEMA_VERSION = '0.1.0';
 // Identifies which ecosystem product emitted this proof. Consumed by SkillsTech
 // Certified to key cert proofs to the compiler. Stable slug per the coordination bus.

package/src/evidence.mjs

@@ -0,0 +1,116 @@
+// ThunderLang -> shared evidence graph projection.
+//
+// Maps ThunderLang's verification artifacts into evidence-event-v1 events for the SkillsTech proof
+// spine (owned by STW: siblings emit evidence-event-v1, STW composes proof-bundle-v1). ThunderLang is
+// the deterministic, machine-checked layer, so its evidence is evidenceType `tool_verified`.
+//
+// These projections are PURE and OFFLINE. They perform no network I/O: the transport (POST to the
+// spine) belongs to the hosted org-layer / CI, never the end-user CLI, so the compiler stays
+// deterministic and phone-home-free. They are also SAFE-DERIVED: events carry only ids, hashes,
+// verdicts, diagnostic codes, and counts , never source code, never secret values, never claim
+// statement text, never data-element contents (no finding `message`, no expected/actual values).
+//
+// NOTE: the evidence-event-v1 envelope below is ThunderLang's PROPOSED shape, pending STW's canonical
+// schema (see the TL->STW proposal on the comms bus). Field names may adjust once STW confirms.
+
+const COUNTED_STATUSES = ['verified', 'failed', 'planned', 'needs_verification'];
+const stripHash = (h) => String(h || '').replace(/^sha256:/, '');
+const short = (h, n = 16) => stripHash(h).slice(0, n);
+
+// The shared evidence-event-v1 envelope. `ctx` carries the cross-artifact context the individual
+// artifacts do not all include (missionName, intentHash, compilerVersion, occurredAt).
+function envelope(eventType, evidenceId, ctx = {}, payload = {}) {
+  return {
+    schema: 'evidence-event-v1',
+    sourceProduct: 'thunderlang',
+    producer: { name: 'thunderlang', version: ctx.compilerVersion || null },
+    eventType,
+    evidenceType: 'tool_verified',
+    evidenceId,
+    occurredAt: ctx.occurredAt || null,
+    visibility: ctx.visibility || 'private',
+    subject: { missionName: ctx.missionName || null, intentHash: ctx.intentHash || null },
+    payload,
+  };
+}
+
+const safeClaim = (kind, c) => ({ id: c.id, kind, status: c.status, provenBy: c.provenBy || null });
+function countByStatus(claims) {
+  const counts = Object.fromEntries(COUNTED_STATUSES.map((s) => [s, 0]));
+  for (const c of claims) if (c && Object.prototype.hasOwnProperty.call(counts, c.status)) counts[c.status]++;
+  return counts;
+}
+// Safe-derived finding: diagnostic code + level (+ flags), never the human message (which can quote code).
+const safeFinding = (f) => ({ code: f.code, level: f.level, ...(f.regression !== undefined ? { regression: !!f.regression } : {}), ...(f.line !== undefined ? { line: f.line } : {}) });
+
+// intent.proven , from an intent-proof-v1 artifact.
+export function toEvidenceEvents(proof) {
+  if (!proof || typeof proof !== 'object') return [];
+  const guarantees = Array.isArray(proof.guarantees) ? proof.guarantees : [];
+  const neverRules = Array.isArray(proof.neverRules) ? proof.neverRules : [];
+  const claims = [
+    ...guarantees.map((c) => safeClaim('guarantee', c)),
+    ...neverRules.map((c) => safeClaim('prohibition', c)),
+  ];
+  const fr = proof.freshness || {};
+  const intentHash = proof.freshness?.intentHash || proof.sourceHash || null;
+  return [envelope('intent.proven', `tl-proof-${short(intentHash)}`, {
+    compilerVersion: proof.compilerVersion, occurredAt: proof.generatedAt, missionName: proof.missionName, intentHash,
+  }, {
+    proofStatus: proof.proofStatus || null,
+    total: claims.length,
+    counts: countByStatus(claims),
+    freshness: { implementation: fr.implementation || null, dependencies: fr.dependencies ? fr.dependencies.hash || null : null, environment: fr.environment || null },
+    claims,
+  })];
+}
+
+// change.gated , from a verify-diff verdict ({ verdict, ok, findings, blocking, summary }).
+export function verifyDiffToEvidence(verdict, ctx = {}) {
+  if (!verdict || typeof verdict !== 'object') return [];
+  const findings = Array.isArray(verdict.findings) ? verdict.findings : [];
+  const id = `tl-verifydiff-${short(ctx.intentHash)}${ctx.changeHash ? `-${short(ctx.changeHash, 8)}` : ''}`;
+  return [envelope('change.gated', id, ctx, {
+    verdict: verdict.verdict || null,
+    ok: !!verdict.ok,
+    blocking: verdict.blocking || 0,
+    regressions: verdict.summary?.regressions ?? findings.filter((f) => f.regression).length,
+    findings: findings.map(safeFinding),
+  })];
+}
+
+// conformance.verified , from a thunder-conformance-v1 report.
+export function conformToEvidence(report, ctx = {}) {
+  if (!report || typeof report !== 'object') return [];
+  const cases = Array.isArray(report.cases) ? report.cases : [];
+  const columns = Array.isArray(report.columns) ? report.columns : [];
+  // Per-target pass/fail/declared counts, derived without leaking any expected/actual values.
+  const targets = {};
+  for (const col of columns) {
+    const t = { pass: 0, fail: 0, declared: 0 };
+    for (const c of cases) { const s = c.targets?.[col]?.status; if (s === 'pass') t.pass++; else if (s === 'fail') t.fail++; else t.declared++; }
+    targets[col] = t;
+  }
+  return [envelope('conformance.verified', `tl-conform-${short(ctx.intentHash)}`, ctx, {
+    total: report.total || cases.length,
+    columns,
+    semanticFailures: report.semanticFailures || 0,
+    graded: !!report.graded,
+    targets,
+    // failure locations by name only (case + target), never expected/actual values.
+    failures: (Array.isArray(report.failures) ? report.failures : []).map((f) => ({ target: f.target, case: f.case })),
+  })];
+}
+
+// intent.drift , from a checkDrift report ({ status, findings, summary }).
+export function driftToEvidence(report, ctx = {}) {
+  if (!report || typeof report !== 'object') return [];
+  const findings = Array.isArray(report.findings) ? report.findings : [];
+  const id = `tl-drift-${short(ctx.intentHash)}${ctx.codeHash ? `-${short(ctx.codeHash, 8)}` : ''}`;
+  return [envelope('intent.drift', id, ctx, {
+    status: report.status || null,
+    total: findings.length,
+    blocking: report.summary?.blocking ?? 0,
+    findings: findings.map(safeFinding),
+  })];
+}

package/src/exporters.mjs

@@ -180,17 +180,23 @@ export function toMermaid(ast) {
 
 // ── Playwright (experience -> E2E test scaffold) ─────────────────────────────
 // A SKELETON, not a passing test: declared experiences/journeys/states become structured
-// Playwright stubs (describe/test/test.step) with TODOs for selectors + assertions. This is
-// the test-plan target for the experience profile , it turns "what the UI must do" into the
-// shape of the test that proves it, deterministically. Consistent with the compiler's scope
-// (test scaffolds, not production code).
+// Playwright stubs (describe/test/test.step) with TODOs for selectors + assertions. The
+// TODOs are intentional and stay: a deterministic compiler cannot know the app's selectors,
+// so it must not fabricate them. To keep the scaffold honest, every generated test opens
+// with a test.fixme(true, ...) guard: Playwright reports it as "fixme" (not a vacuous pass)
+// until a human fills in the body and removes the guard. This is the test-plan target for
+// the experience profile , it turns "what the UI must do" into the shape of the test that
+// proves it, deterministically. Consistent with the compiler's scope (test scaffolds, not
+// production code).
 const jsStr = (s) => `'${String(s ?? '').replace(/\\/g, '\\\\').replace(/'/g, "\\'").replace(/\r?\n/g, ' ')}'`;
 
 export function toPlaywright(ast) {
   const exps = ast.experiences || [];
   const L = [];
   L.push('// Playwright test scaffold generated from experience intent by @skillstech/thunderlang.');
-  L.push('// SKELETON: fill in selectors and assertions. It is not a passing test until you do.');
+  L.push('// SKELETON: fill in selectors and assertions. Every test starts with a test.fixme');
+  L.push('// guard so an unimplemented scaffold reports "fixme" instead of passing vacuously;');
+  L.push('// remove the guard from each test once its body is real.');
   L.push("import { test, expect } from '@playwright/test';");
   L.push('');
   if (!exps.length) {
@@ -204,6 +210,7 @@ export function toPlaywright(ast) {
     }
     for (const j of exp.journeys || []) {
       L.push(`  test(${jsStr(j.name || 'journey')}, async ({ page }) => {`);
+      L.push(`    test.fixme(true, ${jsStr('scaffold: implement the steps, then remove this guard')});`);
       if (!(j.steps || []).length) L.push('    // TODO: no steps declared for this journey');
       for (const step of j.steps || []) {
         L.push(`    await test.step(${jsStr(step)}, async () => {`);
@@ -215,10 +222,12 @@ export function toPlaywright(ast) {
     for (const st of exp.states || []) {
       if (st.hasRecovery) {
         L.push(`  test(${jsStr(`failure state "${st.name}" offers a recovery path`)}, async ({ page }) => {`);
+        L.push(`    test.fixme(true, ${jsStr('scaffold: implement this state check, then remove this guard')});`);
         L.push(`    // TODO: drive the UI into "${st.name}", assert a recovery action is available`);
         L.push('  });');
       } else {
         L.push(`  test(${jsStr(`reaches state: ${st.name}`)}, async ({ page }) => {`);
+        L.push(`    test.fixme(true, ${jsStr('scaffold: implement this state check, then remove this guard')});`);
         L.push(`    // TODO: drive the UI to "${st.name}" and assert it is shown`);
         L.push('  });');
       }

package/src/index.d.ts

@@ -691,6 +691,7 @@ export const CODEGEN_SCHEMA: string;
 export function toTypeScript(ast: IntentAst): string;
 export function toCSharp(ast: IntentAst): string;
 export function toJava(ast: IntentAst): string;
+export function toPython(ast: IntentAst): string;
 export const GENERATORS: Record<string, (ast: IntentAst) => string>;
 export function exprToJs(src: string, opts?: { inputs?: string[] }): string;
 export function subjectName(ast: IntentAst): string | null;

package/src/index.mjs

@@ -8,6 +8,7 @@
 
 // Parsing
 export { parseIntent, slug, KNOWN_LENSES } from './parse.mjs';
+export { toEvidenceEvents, verifyDiffToEvidence, conformToEvidence, driftToEvidence } from './evidence.mjs';
 
 // Semantic analysis, graphs, and proof
 export {
@@ -113,7 +114,7 @@ export { FOCUS_SCHEMA, SCOPE_TYPES, FOCUS_REASONS, makeScope, buildFocusGraph, i
 // Comprehension Contract , the C0..C7 understanding level (intent-comprehension-v1)
 export { COMPREHENSION_SCHEMA, LEVELS as COMPREHENSION_LEVELS, comprehensionLevel, comprehensionReport } from './comprehension.mjs';
 // Code generation , deterministic scaffolds from intent (intent-codegen-v1)
-export { CODEGEN_SCHEMA, GENERATORS, toTypeScript, toCSharp, toJava } from './codegen.mjs';
+export { CODEGEN_SCHEMA, GENERATORS, toTypeScript, toCSharp, toJava, toPython } from './codegen.mjs';
 // Change Lens , what a branch/PR changed by meaning (intent-changes-v1)
 export { CHANGES_SCHEMA, changeReport } from './changes.mjs';
 export { exprToJs, exprToCSharp, exprToJava, exprToCode } from './expr.mjs';

package/src/lift.mjs

@@ -696,7 +696,7 @@ export function liftRepo(files, { language } = {}) {
     const base = slug(r.lifted.mission);
     const n = (usedNames.get(base) || 0) + 1;
     usedNames.set(base, n);
-    const outName = n === 1 ? `${base}.intent` : `${base}-${n}.intent`;
+    const outName = n === 1 ? `${base}.thunder` : `${base}-${n}.thunder`;
     missions.push({
       mission: r.lifted.mission, sourceFile: file, outName,
       intentText: r.intentText, summary: r.summary, diagnostics: r.diagnostics,