@orcalang/orca-lang 0.1.18 → 0.1.21

package/src/skills.ts

@@ -7,6 +7,15 @@ import { checkProperties } from './verifier/properties.js';
 import { compileToXState } from './compiler/xstate.js';
 import { compileToMermaid } from './compiler/mermaid.js';
 import { MachineDef, StateDef, GuardExpression, Type } from './parser/ast.js';
+import { DecisionTableDef } from './parser/dt-ast.js';
+import { verifyDecisionTable, verifyDecisionTables, checkFileContextAlignment, checkDTMachineIntegration, computeAlignedDTOutputDomain } from './verifier/dt-verifier.js';
+import {
+  compileDecisionTableToTypeScript,
+  compileDecisionTableToPython,
+  compileDecisionTableToGo,
+  compileDecisionTableToJSON,
+  toSnakeCase,
+} from './compiler/dt-compiler.js';
 import { loadConfig, resolveConfigOverrides } from './config/index.js';
 import { createProvider } from './llm/index.js';
 import type { LLMProvider } from './llm/index.js';
@@ -45,7 +54,12 @@ export interface SkillError {
   location?: {
     state?: string;
     event?: string;
-    transition?: string;
+    transition?: string | { source?: string; target?: string; event?: string }; // string for machine errors, object for DT errors
+    // Decision table specific
+    rule?: number;
+    condition?: string;
+    action?: string;
+    decisionTable?: string;
   };
   suggestion?: string;
 }
@@ -81,6 +95,7 @@ export interface GenerateActionsResult {
   machine: string;
   actions: ActionScaffold[];
   scaffolds: Record<string, string>;
+  decisionTableCode?: Record<string, string>;  // DT name → compiled evaluator code
   tests?: Record<string, string>;
 }
 
@@ -240,8 +255,13 @@ export async function verifySkill(input: SkillInput): Promise<VerifySkillResult>
   const label = resolveLabel(input);
 
   let machine: MachineDef;
+  let fileDecisionTables: import('./parser/dt-ast.js').DecisionTableDef[] = [];
   try {
-    machine = parseSource(label, source);
+    const { file } = parseMarkdown(source);
+    if (file.machines.length === 0) throw new Error(`${label} contains no machine definition.`);
+    if (file.machines.length > 1) throw new Error(`${label} contains multiple machines.`);
+    machine = file.machines[0];
+    fileDecisionTables = file.decisionTables;
   } catch (err) {
     // Parse error - return as verification error
     const message = err instanceof Error ? err.message : String(err);
@@ -263,15 +283,28 @@ export async function verifySkill(input: SkillInput): Promise<VerifySkillResult>
   const structural = checkStructural(machine);
   const completeness = checkCompleteness(machine);
   const determinism = checkDeterminism(machine);
-  const properties = checkProperties(machine);
 
-  const mapError = (e: { code: string; message: string; severity: 'error' | 'warning'; location?: { state?: string; event?: string }; suggestion?: string }): SkillError => ({
+  // Check co-located decision table alignment and machine integration (single-machine files only)
+  const orcaFile = { machines: [machine], decisionTables: fileDecisionTables };
+  const dtOutputDomain = fileDecisionTables.length > 0 ? computeAlignedDTOutputDomain(orcaFile) : undefined;
+  const properties = checkProperties(machine, { dtOutputDomain });
+  const dtAlignment = fileDecisionTables.length > 0
+    ? checkFileContextAlignment(orcaFile)
+    : [];
+  const dtIntegration = fileDecisionTables.length > 0
+    ? checkDTMachineIntegration(orcaFile)
+    : [];
+
+  const mapError = (e: { code: string; message: string; severity: 'error' | 'warning'; location?: { state?: string; event?: string; decisionTable?: string; condition?: string; action?: string }; suggestion?: string }): SkillError => ({
     code: e.code,
     message: e.message,
     severity: e.severity,
     location: e.location ? {
       state: e.location.state,
       event: e.location.event,
+      decisionTable: e.location.decisionTable,
+      condition: e.location.condition,
+      action: e.location.action,
     } : undefined,
     suggestion: e.suggestion,
   });
@@ -281,6 +314,8 @@ export async function verifySkill(input: SkillInput): Promise<VerifySkillResult>
     ...completeness.errors.map(mapError),
     ...determinism.errors.map(mapError),
     ...properties.errors.map(mapError),
+    ...dtAlignment.map(mapError),
+    ...dtIntegration.map(mapError),
   ];
 
   return {
@@ -340,7 +375,18 @@ export async function generateActionsSkill(
   generateTests: boolean = false
 ): Promise<GenerateActionsResult> {
   const source = resolveSource(input);
-  const machine = parseSource(resolveLabel(input), source);
+
+  // Parse the full file to get both the machine and any co-located decision tables
+  const { file } = parseMarkdown(source);
+  const label = resolveLabel(input);
+  if (file.machines.length === 0) {
+    throw new Error(`${label} contains no machine definition.`);
+  }
+  if (file.machines.length > 1) {
+    throw new Error(`${label} contains multiple machines. Use a single-machine file for action generation.`);
+  }
+  const machine = file.machines[0];
+  const decisionTables = file.decisionTables;
 
   const actions: ActionScaffold[] = machine.actions.map(action => ({
     name: action.name,
@@ -352,6 +398,18 @@ export async function generateActionsSkill(
     context_used: extractContextFields(machine, action.name),
   }));
 
+  // Compile decision table evaluator code for each DT in the file
+  const decisionTableCode: Record<string, string> = {};
+  for (const dt of decisionTables) {
+    if (language === 'python') {
+      decisionTableCode[dt.name] = compileDecisionTableToPython(dt);
+    } else if (language === 'go') {
+      decisionTableCode[dt.name] = compileDecisionTableToGo(dt);
+    } else {
+      decisionTableCode[dt.name] = compileDecisionTableToTypeScript(dt);
+    }
+  }
+
   let scaffolds: Record<string, string> = {};
   let tests: Record<string, string> = {};
 
@@ -366,7 +424,7 @@ export async function generateActionsSkill(
       temperature: config.temperature,
     });
 
-    scaffolds = await generateWithLLM(provider, actions, machine, language as CodeGeneratorType);
+    scaffolds = await generateWithLLM(provider, actions, machine, language as CodeGeneratorType, decisionTables);
 
     if (generateTests) {
       tests = await generateUnitTests(provider, actions, machine, language as CodeGeneratorType);
@@ -374,7 +432,13 @@ export async function generateActionsSkill(
   } else {
     // Use template-based scaffold generation
     for (const action of machine.actions) {
-      scaffolds[action.name] = generateActionScaffold(action, machine, language);
+      const matchedDT = findMatchingDT(action.name, decisionTables);
+      if (matchedDT && !action.hasEffect && isDTFullyAligned(matchedDT, machine)) {
+        // All DT conditions and outputs exist in context — generate fully wired code
+        scaffolds[action.name] = generateFullyWiredActionScaffold(action, machine, language, matchedDT);
+      } else {
+        scaffolds[action.name] = generateActionScaffold(action, machine, language, matchedDT ?? undefined);
+      }
     }
 
     if (generateTests) {
@@ -387,6 +451,7 @@ export async function generateActionsSkill(
     machine: machine.name,
     actions,
     scaffolds,
+    decisionTableCode: Object.keys(decisionTableCode).length > 0 ? decisionTableCode : undefined,
     tests: Object.keys(tests).length > 0 ? tests : undefined,
   };
 }
@@ -395,22 +460,35 @@ async function generateWithLLM(
   provider: LLMProvider,
   actions: ActionScaffold[],
   machine: MachineDef,
-  language: CodeGeneratorType
+  language: CodeGeneratorType,
+  decisionTables: DecisionTableDef[] = []
 ): Promise<Record<string, string>> {
   const generator = getCodeGenerator(language);
   const scaffolds: Record<string, string> = {};
 
+  const dtContext = decisionTables.length > 0
+    ? `\nDecision tables available:\n${decisionTables.map(dt =>
+        `- ${dt.name}: conditions=[${dt.conditions.map(c => c.name).join(', ')}] outputs=[${dt.actions.map(a => a.name).join(', ')}]`
+      ).join('\n')}`
+    : '';
+
   const systemPrompt = `You are an expert ${language} developer specializing in state machine action implementations.
 Given a machine definition and action signatures, generate complete action implementations.
 Follow the type signatures exactly. Use the provided context fields.
-If an action has an effect, return [newContext, effect] tuple.`;
+If an action has an effect, return [newContext, effect] tuple.
+If decision tables are listed, use their evaluator functions (e.g. evaluate${language === 'go' ? 'DtName' : 'DtName'}) when appropriate.`;
 
   for (const action of actions) {
+    const matchedDT = findMatchingDT(action.name, decisionTables);
+    const dtHint = matchedDT
+      ? `\nThis action should use the ${matchedDT.name} decision table evaluator.`
+      : '';
+
     const userPrompt = `Machine: ${machine.name}
-Context fields: ${machine.context.map(f => `${f.name}: ${f.type || 'unknown'}`).join(', ')}
+Context fields: ${machine.context.map(f => `${f.name}: ${f.type || 'unknown'}`).join(', ')}${dtContext}
 
 Action: ${action.signature}
-Description: ${action.name}${action.hasEffect ? ` (effect type: ${action.effectType})` : ''}
+Description: ${action.name}${action.hasEffect ? ` (effect type: ${action.effectType})` : ''}${dtHint}
 
 Generate the implementation:`;
 
@@ -429,7 +507,7 @@ Generate the implementation:`;
     } catch (err) {
       console.error(`LLM error for action ${action.name}: ${err instanceof Error ? err.message : String(err)}`);
       // Fall back to scaffold on error
-      scaffolds[action.name] = generateActionScaffold(action, machine, language);
+      scaffolds[action.name] = generateActionScaffold(action, machine, language, matchedDT ?? undefined);
     }
   }
 
@@ -772,10 +850,222 @@ function toPascalCase(snake: string): string {
   return snake.split('_').map(w => w.charAt(0).toUpperCase() + w.slice(1)).join('');
 }
 
+/**
+ * Find a decision table whose name tokens overlap with the action name tokens.
+ * E.g. action "apply_routing_decision" matches DT "PaymentRouting" via "routing".
+ */
+function findMatchingDT(actionName: string, dts: DecisionTableDef[]): DecisionTableDef | null {
+  if (dts.length === 0) return null;
+  const actionTokens = new Set(
+    actionName.toLowerCase().split('_').filter(t => t.length > 2)
+  );
+  for (const dt of dts) {
+    const dtTokens = dt.name
+      .replace(/([A-Z])/g, ' $1')
+      .trim()
+      .toLowerCase()
+      .split(/\s+/)
+      .filter(t => t.length > 2);
+    if (dtTokens.some(t => actionTokens.has(t))) return dt;
+  }
+  return null;
+}
+
+/**
+ * Generate a commented example DT call block to include in an action stub.
+ */
+function generateDTCallComment(dt: DecisionTableDef, language: string): string {
+  const dtName = dt.name;
+
+  if (language === 'python') {
+    const fnName = `evaluate_${toSnakeCase(dtName)}`;
+    const inputClass = `${toPascalCase(dtName)}Input`;
+    const inputArgs = dt.conditions.map(c => {
+      const hint = c.type === 'enum' && c.values.length > 0
+        ? `str (${c.values.join(', ')})`
+        : c.type === 'bool' ? 'bool' : 'str';
+      return `    #     ${c.name}=...,  # ${hint} — map from ctx`;
+    }).join('\n');
+    const outputFields = dt.actions.map(a =>
+      `    #     # dt_result.${a.name} → ctx['${a.name}']`
+    ).join('\n');
+    return [
+      `    # Call ${fnName} to evaluate ${dtName} rules:`,
+      `    # dt_result = ${fnName}(${inputClass}(`,
+      inputArgs,
+      `    # ))`,
+      `    # if dt_result is not None:`,
+      outputFields,
+    ].join('\n');
+  }
+
+  if (language === 'go') {
+    const fnName = `Evaluate${toPascalCase(dtName)}`;
+    const inputStruct = `${toPascalCase(dtName)}Input`;
+    const inputArgs = dt.conditions.map(c => {
+      const goField = toPascalCase(c.name);
+      const hint = c.type === 'enum' && c.values.length > 0
+        ? `string (${c.values.join(', ')})`
+        : c.type === 'bool' ? 'bool' : 'string';
+      return `\t// \t${goField}: ..., // ${hint} — map from ctx`;
+    }).join('\n');
+    const outputFields = dt.actions.map(a =>
+      `\t// \tresult["${a.name}"] = dtResult.${toPascalCase(a.name)}`
+    ).join('\n');
+    return [
+      `\t// Call ${fnName} to evaluate ${dtName} rules:`,
+      `\t// dtResult := ${fnName}(${inputStruct}{`,
+      inputArgs,
+      `\t// })`,
+      `\t// if dtResult != nil {`,
+      outputFields,
+      `\t// }`,
+    ].join('\n');
+  }
+
+  // TypeScript (default)
+  const fnName = `evaluate${toPascalCase(dtName)}`;
+  const inputType = `${toPascalCase(dtName)}Input`;
+  const inputArgs = dt.conditions.map(c => {
+    const hint = c.type === 'enum' && c.values.length > 0
+      ? `enum: ${c.values.join(', ')}`
+      : c.type;
+    return `  //   ${c.name}: /* ctx.? */ as ${inputType}['${c.name}'],  // ${hint} — map from ctx`;
+  }).join('\n');
+  const outputFields = dt.actions.map(a =>
+    `  //   ${a.name}: dtResult.${a.name},`
+  ).join('\n');
+  return [
+    `  // Call ${fnName} to evaluate ${dtName} rules:`,
+    `  // const dtResult = ${fnName}({`,
+    inputArgs,
+    `  // });`,
+    `  // if (dtResult !== null) {`,
+    `  //   return { ...ctx,`,
+    outputFields,
+    `  //   };`,
+    `  // }`,
+  ].join('\n');
+}
+
+/**
+ * Returns true when every DT condition name and output name exists as a
+ * context field in the machine — the full co-location contract is satisfied.
+ */
+function isDTFullyAligned(dt: DecisionTableDef, machine: MachineDef): boolean {
+  const contextNames = new Set(machine.context.map(f => f.name));
+  return dt.conditions.every(c => contextNames.has(c.name)) &&
+         dt.actions.every(a => contextNames.has(a.name));
+}
+
+/** Generate a Go type assertion for reading a context value. */
+function goCtxRead(fieldName: string, condType: string): string {
+  if (condType === 'bool') return `ctx["${fieldName}"].(bool)`;
+  if (condType === 'int_range') return `ctx["${fieldName}"].(int)`;
+  return `ctx["${fieldName}"].(string)`;
+}
+
+function generateFullyWiredActionScaffold(
+  action: { name: string; parameters: string[]; returnType: string; hasEffect: boolean; effectType?: string },
+  machine: MachineDef,
+  language: string,
+  dt: DecisionTableDef
+): string {
+  if (language === 'python') {
+    const dtFnName = `evaluate_${toSnakeCase(dt.name)}`;
+    const inputClass = `${toPascalCase(dt.name)}Input`;
+    const inputArgs = dt.conditions
+      .map(c => `        ${c.name}=ctx['${c.name}'],`)
+      .join('\n');
+    const outputAssigns = dt.actions
+      .map(a => `            '${a.name}': dt_result.${a.name},`)
+      .join('\n');
+    return `# Action: ${action.name}
+# Decision table: ${dt.name}
+# Register via: machine.register_action("${action.name}", ${action.name})
+
+from typing import Any
+
+async def ${action.name}(ctx: dict[str, Any], event: Any = None) -> dict[str, Any]:
+    dt_result = ${dtFnName}(${inputClass}(
+${inputArgs}
+    ))
+    if dt_result is not None:
+        return {**ctx,
+${outputAssigns}
+        }
+    return dict(ctx)
+`;
+  }
+
+  if (language === 'go') {
+    const fnName = toPascalCase(action.name);
+    const dtFnName = `Evaluate${toPascalCase(dt.name)}`;
+    const inputStruct = `${toPascalCase(dt.name)}Input`;
+    const ctxReads = dt.conditions.map(c => {
+      const varName = toPascalCase(c.name).charAt(0).toLowerCase() + toPascalCase(c.name).slice(1);
+      return `\t${varName}, _ := ${goCtxRead(c.name, c.type)}`;
+    }).join('\n');
+    const inputFields = dt.conditions.map(c => {
+      const goField = toPascalCase(c.name);
+      const varName = goField.charAt(0).toLowerCase() + goField.slice(1);
+      return `\t\t${goField}: ${varName},`;
+    }).join('\n');
+    const outputAssigns = dt.actions
+      .map(a => `\t\tresult["${a.name}"] = dtResult.${toPascalCase(a.name)}`)
+      .join('\n');
+    return `// Action: ${action.name}
+// Decision table: ${dt.name}
+// Register via: machine.RegisterAction("${action.name}", ${fnName})
+
+func ${fnName}(ctx orca.Context, event map[string]any) map[string]any {
+${ctxReads}
+\tdtResult := ${dtFnName}(${inputStruct}{
+${inputFields}
+\t})
+\tresult := make(orca.Context)
+\tfor k, v := range ctx {
+\t\tresult[k] = v
+\t}
+\tif dtResult != nil {
+${outputAssigns}
+\t}
+\treturn result
+}
+`;
+  }
+
+  // TypeScript (default)
+  const dtFnName = `evaluate${toPascalCase(dt.name)}`;
+  const inputArgs = dt.conditions
+    .map(c => `    ${c.name}: ctx.${c.name},`)
+    .join('\n');
+  const outputAssigns = dt.actions
+    .map(a => `      ${a.name}: dtResult.${a.name},`)
+    .join('\n');
+  return `// Action: ${action.name}
+// Decision table: ${dt.name}
+
+export function ${action.name}(ctx: Context): Context {
+  const dtResult = ${dtFnName}({
+${inputArgs}
+  });
+  if (dtResult !== null) {
+    return {
+      ...ctx,
+${outputAssigns}
+    };
+  }
+  return { ...ctx };
+}
+`;
+}
+
 function generateActionScaffold(
   action: { name: string; parameters: string[]; returnType: string; hasEffect: boolean; effectType?: string },
   machine: MachineDef,
-  language: string
+  language: string,
+  matchedDT?: DecisionTableDef
 ): string {
   if (language === 'python') {
     if (action.hasEffect) {
@@ -793,13 +1083,17 @@ async def ${action.name}(effect: Effect) -> EffectResult:
     return EffectResult(status=EffectStatus.SUCCESS, data={})
 `;
     }
-    return `# Action: ${action.name}
+    const pyDTComment = matchedDT ? '\n' + generateDTCallComment(matchedDT, 'python') + '\n' : '';
+    const pyTodo = matchedDT
+      ? `    # TODO: Implement action using ${matchedDT.name} decision table`
+      : '    # TODO: Implement action';
+    return `# Action: ${action.name}${matchedDT ? `\n# Decision table: ${matchedDT.name}` : ''}
 # Register via: machine.register_action("${action.name}", ${action.name})
 
 from typing import Any
 
-async def ${action.name}(ctx: dict[str, Any], event: Any = None) -> dict[str, Any]:
-    # TODO: Implement action
+async def ${action.name}(ctx: dict[str, Any], event: Any = None) -> dict[str, Any]:${pyDTComment}
+${pyTodo}
     return dict(ctx)
 `;
   }
@@ -820,11 +1114,15 @@ func ${fnName}(effect orca.Effect) orca.EffectResult {
 }
 `;
     }
-    return `// Action: ${action.name}
+    const goDTComment = matchedDT ? '\n' + generateDTCallComment(matchedDT, 'go') + '\n' : '';
+    const goTodo = matchedDT
+      ? `\t// TODO: Implement action using ${matchedDT.name} decision table`
+      : '\t// TODO: Implement action';
+    return `// Action: ${action.name}${matchedDT ? `\n// Decision table: ${matchedDT.name}` : ''}
 // Register via: machine.RegisterAction("${action.name}", ${fnName})
 
-func ${fnName}(ctx orca.Context, event map[string]any) map[string]any {
-\t// TODO: Implement action
+func ${fnName}(ctx orca.Context, event map[string]any) map[string]any {${goDTComment}
+${goTodo}
 \tresult := make(orca.Context)
 \tfor k, v := range ctx {
 \t\tresult[k] = v
@@ -856,10 +1154,15 @@ export function ${action.name}(${params}): [Context, Effect<${action.effectType}
 // }
 `;
   }
-  return `// Action: ${action.name}
 
-export function ${action.name}(ctx: Context): Context {
-  // TODO: Implement action
+  const tsDTComment = matchedDT ? '\n' + generateDTCallComment(matchedDT, 'typescript') + '\n' : '';
+  const tsTodo = matchedDT
+    ? `  // TODO: Implement action using ${matchedDT.name} decision table`
+    : '  // TODO: Implement action';
+  return `// Action: ${action.name}${matchedDT ? `\n// Decision table: ${matchedDT.name}` : ''}
+
+export function ${action.name}(ctx: Context): Context {${tsDTComment}
+${tsTodo}
   return { ...ctx };
 }
 `;
@@ -1677,3 +1980,269 @@ function extractMachineNameFromSource(orca: string): string {
   const match = orca.match(/^(?:#\s+)?machine\s+(\w+)/m);
   return match ? match[1] : 'Unknown';
 }
+
+// ============================================================
+// Decision Table Skills
+// ============================================================
+
+export interface VerifyDTSkillResult {
+  status: 'valid' | 'invalid';
+  decisionTable: string;
+  conditions: number;
+  actions: number;
+  rules: number;
+  errors: SkillError[];
+}
+
+export interface CompileDTSkillResult {
+  status: 'success' | 'error';
+  target: 'typescript' | 'json';
+  output: string;
+  warnings: SkillError[];
+}
+
+/**
+ * Parse a decision table from source.
+ */
+export function parseDTSkill(input: SkillInput): { status: 'success' | 'error'; decisionTables?: object[]; error?: string } {
+  try {
+    const source = resolveSource(input);
+    const { file } = parseMarkdown(source);
+
+    if (file.decisionTables.length === 0) {
+      return { status: 'error', error: 'No decision table found in source' };
+    }
+
+    // Return all decision tables as plain objects
+    const tables = file.decisionTables.map(dt => ({
+      name: dt.name,
+      description: dt.description,
+      conditions: dt.conditions.map(c => ({
+        name: c.name,
+        type: c.type,
+        values: c.values,
+        range: c.range,
+      })),
+      actions: dt.actions.map(a => ({
+        name: a.name,
+        type: a.type,
+        description: a.description,
+        values: a.values,
+      })),
+      rules: dt.rules.map(r => ({
+        number: r.number,
+        conditions: Object.fromEntries(r.conditions),
+        actions: Object.fromEntries(r.actions),
+      })),
+      policy: dt.policy,
+    }));
+
+    return { status: 'success', decisionTables: tables };
+  } catch (err) {
+    return { status: 'error', error: err instanceof Error ? err.message : String(err) };
+  }
+}
+
+/**
+ * Verify a decision table.
+ */
+export function verifyDTSkill(input: SkillInput): VerifyDTSkillResult {
+  try {
+    const source = resolveSource(input);
+    const { file } = parseMarkdown(source);
+
+    if (file.decisionTables.length === 0) {
+      return {
+        status: 'invalid',
+        decisionTable: '',
+        conditions: 0,
+        actions: 0,
+        rules: 0,
+        errors: [{ code: 'DT_NOT_FOUND', message: 'No decision table found in source', severity: 'error' }],
+      };
+    }
+
+    // Verify all decision tables
+    const verification = verifyDecisionTables(file.decisionTables);
+
+    // Return result for the first decision table
+    const dt = file.decisionTables[0];
+    const errors: SkillError[] = [];
+    for (const e of verification.errors) {
+      const loc = e.location;
+      errors.push({
+        code: e.code,
+        message: e.message,
+        severity: e.severity as 'error' | 'warning',
+        location: loc ? {
+          state: loc.state,
+          event: loc.event,
+          rule: loc.rule,
+          condition: loc.condition,
+          action: loc.action,
+          decisionTable: loc.decisionTable,
+        } : undefined,
+        suggestion: e.suggestion,
+      });
+    }
+
+    return {
+      status: verification.valid ? 'valid' : 'invalid',
+      decisionTable: dt.name,
+      conditions: dt.conditions.length,
+      actions: dt.actions.length,
+      rules: dt.rules.length,
+      errors,
+    };
+  } catch (err) {
+    return {
+      status: 'invalid',
+      decisionTable: '',
+      conditions: 0,
+      actions: 0,
+      rules: 0,
+      errors: [{ code: 'PARSE_ERROR', message: err instanceof Error ? err.message : String(err), severity: 'error' }],
+    };
+  }
+}
+
+/**
+ * Compile a decision table to TypeScript or JSON.
+ */
+export function compileDTSkill(input: SkillInput, target: 'typescript' | 'json' = 'typescript'): CompileDTSkillResult {
+  try {
+    const source = resolveSource(input);
+    const { file } = parseMarkdown(source);
+
+    if (file.decisionTables.length === 0) {
+      return {
+        status: 'error',
+        target,
+        output: '',
+        warnings: [{ code: 'DT_NOT_FOUND', message: 'No decision table found in source', severity: 'error' }],
+      };
+    }
+
+    const dt = file.decisionTables[0];
+    const output = target === 'json'
+      ? compileDecisionTableToJSON(dt)
+      : compileDecisionTableToTypeScript(dt);
+
+    return { status: 'success', target, output, warnings: [] };
+  } catch (err) {
+    return {
+      status: 'error',
+      target,
+      output: '',
+      warnings: [{ code: 'COMPILE_ERROR', message: err instanceof Error ? err.message : String(err), severity: 'error' }],
+    };
+  }
+}
+
+// Decision table syntax reference for LLM generation
+const DT_SYNTAX_REFERENCE = `
+# decision_table Name
+
+## conditions
+
+| Name | Type | Values |
+|------|------|--------|
+| field_name | enum | value1, value2 |
+| is_active | bool | |
+| count | int_range | 1..100 |
+
+## actions
+
+| Name | Type | Description |
+|------|------|-------------|
+| result | enum | Result description |
+| flag | bool | Whether something |
+
+## rules
+
+| condition1 | condition2 | → action1 | → action2 |
+|------------|-----------|----------|-----------|
+| value1 | - | result1 | true |
+| value2 | !value3 | result2 | false |
+
+Notes:
+- "-" in a condition cell means "any" (wildcard)
+- "!value" negates a value
+- "a,b" matches any of the values (OR semantics)
+- Rules are evaluated top-to-bottom; first match wins
+`;
+
+/**
+ * Generate a decision table from natural language spec.
+ */
+export async function generateDTSkill(spec: string, configPath?: string): Promise<{
+  status: 'success' | 'error' | 'requires_refinement';
+  decisionTable?: string;
+  orca?: string;
+  verification?: VerifyDTSkillResult;
+  error?: string;
+}> {
+  const config = loadConfig(configPath);
+  const provider = createProvider(config.provider, {
+    api_key: config.api_key,
+    base_url: config.base_url,
+    model: config.model,
+    max_tokens: config.max_tokens,
+    temperature: config.temperature,
+  });
+
+  if (!provider) {
+    return { status: 'error', error: 'No LLM provider configured' };
+  }
+
+  const prompt = `Generate a decision table in .orca.md format based on the following specification.
+
+${DT_SYNTAX_REFERENCE}
+
+Specification:
+${spec}
+
+Respond with the decision table only, no explanation.`;
+
+  try {
+    const response = await provider.complete({
+      messages: [{ role: 'user', content: prompt }],
+      model: '',
+      max_tokens: config.max_tokens || 2048,
+      temperature: 0.7,
+    });
+
+    const orca = stripCodeFence(response.content);
+
+    // Verify the generated decision table
+    const { file } = parseMarkdown(orca);
+    if (file.decisionTables.length === 0) {
+      return { status: 'error', error: 'Generated content does not contain a valid decision table', orca };
+    }
+
+    const verification = verifyDecisionTables(file.decisionTables);
+
+    return {
+      status: verification.valid ? 'success' : 'requires_refinement',
+      decisionTable: file.decisionTables[0].name,
+      orca,
+      verification: verification.valid ? undefined : {
+        status: 'invalid',
+        decisionTable: file.decisionTables[0].name,
+        conditions: file.decisionTables[0].conditions.length,
+        actions: file.decisionTables[0].actions.length,
+        rules: file.decisionTables[0].rules.length,
+        errors: verification.errors.map(e => ({
+          code: e.code,
+          message: e.message,
+          severity: e.severity,
+          location: e.location,
+          suggestion: e.suggestion,
+        })),
+      },
+    };
+  } catch (err) {
+    return { status: 'error', error: err instanceof Error ? err.message : String(err) };
+  }
+}
+