@specverse/engines 4.1.14 → 4.1.16

package/dist/libs/instance-factories/cli/templates/commander/command-generator.js

@@ -19,8 +19,8 @@ function generateCommand(context) {
     const alias = flag.alias ? `${flag.alias}, ` : "";
     const flagType = flag.type?.toLowerCase();
     const valuePart = flagType === "boolean" ? "" : ` <${flagName.replace(/^--/, "")}>`;
-    const defaultVal = flag.default !== void 0 ? `, ${JSON.stringify(flag.default)}` : "";
-    const desc = flag.description || `${flagName} option`;
+    const defaultVal = flag.default !== void 0 ? `, ${commanderDefault(flag.default, flagType)}` : "";
+    const desc = escapeSingleQuotes(flag.description || `${flagName} option`);
     return `    .option('${alias}${flagName}${valuePart}', '${desc}'${defaultVal})`;
   });
   const optionTypes = Object.entries(flags).map(([flagName, flag]) => {
@@ -47,7 +47,16 @@ function generateCommand(context) {
       if (ENGINE_HANDLERS[key]?.imports) allImportSets.push(ENGINE_HANDLERS[key].imports);
     }
   }
-  const engineImports = deduplicateImports(allImportSets);
+  const registerBody = hasSubcommands ? generateCommandWithSubcommands(name, description, subcommands, optionDefs) : generateLeafCommand(name, description, commandStr, optionDefs, actionParams, serviceRef, exitCodes);
+  const bodyForUsage = `${serviceImport}
+${registerBody}
+${subcommandRegistrations}`;
+  const commandOptionsUsed = new RegExp("\\bCommandOptions\\b").test(bodyForUsage);
+  const engineImports = deduplicateImports(allImportSets, bodyForUsage);
+  const commandOptionsDecl = commandOptionsUsed ? `interface CommandOptions {
+${optionTypes.length > 0 ? optionTypes.join("\n") : "  [key: string]: any;"}
+}
+` : "";
   return `/**
  * ${name} command
  * ${description}
@@ -58,10 +67,7 @@ import { Command } from 'commander';
 ${serviceImport}
 ${engineImports}
 
-interface CommandOptions {
-${optionTypes.length > 0 ? optionTypes.join("\n") : "  [key: string]: any;"}
-}
-
+${commandOptionsDecl}
 ${exitCodeComments ? `/**
  * Exit codes:
 ${exitCodeComments}
@@ -71,7 +77,7 @@ ${exitCodeComments}
  * Register the ${name} command on the program.
  */
 export function register${capitalize(name)}Command(program: Command): void {
-  ${hasSubcommands ? generateCommandWithSubcommands(name, description, subcommands, optionDefs) : generateLeafCommand(name, description, commandStr, optionDefs, actionParams, serviceRef, exitCodes)}
+  ${registerBody}
 }
 ${subcommandRegistrations}
 `;
@@ -117,6 +123,27 @@ import type { ParserEngine } from '@specverse/types';`,
             console.warn('Warnings:');
             result.warnings.forEach((w: string) => console.warn(' ', w));
           }
+        }
+
+        // L3 verification \u2014 opt-in via --verify flag. Runs the
+        // transpiled Quint guards against the parsed spec. Guards
+        // whose state-var dependencies aren't present in this spec
+        // are reported as skipped (not failed).
+        if (options.verify) {
+          try {
+            const { verifySpec, formatVerificationResult } = await import('@specverse/engines/inference');
+            const verification = await verifySpec(result.ast);
+            if (options.json) {
+              console.log(JSON.stringify({ valid: true, verification }, null, 2));
+            } else {
+              console.log('');
+              console.log(formatVerificationResult(verification, options.verbose));
+            }
+            if (verification.failed.length > 0) process.exit(1);
+          } catch (ve: any) {
+            console.error('Verification error:', ve.message);
+            process.exit(1);
+          }
         }`
   },
   infer: {
@@ -243,6 +270,28 @@ import type { ParserEngine, InferenceEngine, RealizeEngine } from '@specverse/ty
           }
         }
 
+        // Merge service operation steps from original spec into inferred services
+        // Inference generates service shells with preconditions/returns but drops
+        // the declarative steps arrays \u2014 we restore them from the parsed AST.
+        const origServices = Array.isArray((origComponent as any).services)
+          ? (origComponent as any).services
+          : Object.values((origComponent as any).services || {});
+        const inferredServices = componentData.services || {};
+        for (const origSvc of origServices) {
+          const svcName = (origSvc as any).name;
+          if (!svcName) continue;
+          const inferredSvc = inferredServices[svcName];
+          if (!inferredSvc) continue;
+
+          const origOps = (origSvc as any).operations || {};
+          const inferredOps = inferredSvc.operations || {};
+          for (const [opName, origOp] of Object.entries(origOps) as [string, any][]) {
+            if (inferredOps[opName] && origOp.steps) {
+              inferredOps[opName].steps = origOp.steps;
+            }
+          }
+        }
+
         // Inject key as name into entity maps, and expand convention-format attributes
         // Iterate all object-valued sections (not hardcoded \u2014 covers any entity type)
         const entitySections = Object.keys(componentData).filter(k =>
@@ -311,7 +360,7 @@ import type { ParserEngine, InferenceEngine, RealizeEngine } from '@specverse/ty
         if (!realizeEngine) { console.error('No realize engine found.'); process.exit(1); }
         await realizeEngine.initialize({ manifestPath: effectiveManifestPath, workingDir: (process.env.SPECVERSE_USER_CWD || process.cwd()) });
 
-        const outputDir = options.output || resolve((process.env.SPECVERSE_USER_CWD || process.cwd()), 'generated/code');
+        const outputDir = resolve((process.env.SPECVERSE_USER_CWD || process.cwd()), options.output || 'generated/code');
         console.log('Realizing ' + type + ' from ' + file + '...');
         await (realizeEngine as any).realizeAll(inferredSpec, outputDir);
 
@@ -789,10 +838,12 @@ import { EngineRegistry } from '@specverse/entities';`,
     imports: ``,
     handler: `const { SessionManager } = await import('@specverse/engines/ai');
         const manager = new SessionManager();
-        const job = await manager.submit(sessionId, requirements, {
-          jobId: options.jobId,
-          outputPath: options.output,
-          operation: options.operation,
+        const job = await manager.submit({
+          jobId: options.jobId || ('job-' + Date.now()),
+          sessionId,
+          operation: (options.operation || 'create') as 'create' | 'analyse' | 'materialise' | 'realize',
+          requirements,
+          output: options.output,
         });
         console.log('Job submitted: ' + job.jobId);
         console.log('Status: ' + job.status);
@@ -808,8 +859,10 @@ import { EngineRegistry } from '@specverse/entities';`,
         } else {
           console.log('ID: ' + (status.sessionId || status.jobId));
           console.log('Status: ' + status.status);
-          if (status.created) console.log('Created: ' + new Date(status.created).toLocaleString());
-          if (status.jobsProcessed !== undefined) console.log('Jobs: ' + status.jobsProcessed);
+          if (status.submitted) console.log('Submitted: ' + new Date(status.submitted).toLocaleString());
+          if (status.started) console.log('Started: ' + new Date(status.started).toLocaleString());
+          if (status.completed) console.log('Completed: ' + new Date(status.completed).toLocaleString());
+          if (status.duration) console.log('Duration: ' + status.duration);
         }`
   },
   "session.process": {
@@ -817,7 +870,7 @@ import { EngineRegistry } from '@specverse/entities';`,
     handler: `const { SessionManager } = await import('@specverse/engines/ai');
         const manager = new SessionManager();
         console.log('Processing job: ' + jobId);
-        await manager.process(jobId);
+        await manager.processJob(jobId);
         console.log('Job processed successfully');`
   }
 };
@@ -827,11 +880,12 @@ function generateLeafCommand(name, description, commandStr, optionDefs, actionPa
       const result = await service.execute(${actionParams.includes(":") ? "{ " + actionParams.split(",").map((p) => p.trim().split(":")[0].trim()).join(", ") + ", ...options }" : "options"});
       console.log(result);` : `console.log('Executing ${name}...');
       // TODO: Wire to service`;
-  return `const cmd = program
+  const finalActionParams = renameUnusedActionParams(actionParams, handler);
+  return `program
     .command('${commandStr}')
-    .description('${description}')
+    .description('${escapeSingleQuotes(description)}')
 ${optionDefs.join("\n")}
-    .action(async (${actionParams}) => {
+    .action(async (${finalActionParams}) => {
       try {
         ${handler}
       } catch (error: any) {
@@ -840,6 +894,27 @@ ${optionDefs.join("\n")}
       }
     });`;
 }
+function escapeSingleQuotes(s) {
+  return s.replace(/\\/g, "\\\\").replace(/'/g, "\\'");
+}
+function commanderDefault(value, flagType) {
+  if (flagType === "boolean") return JSON.stringify(Boolean(value));
+  if (typeof value === "number") return JSON.stringify(String(value));
+  return JSON.stringify(value);
+}
+function renameUnusedActionParams(actionParams, handler) {
+  if (!actionParams.trim()) return actionParams;
+  return actionParams.split(",").map((param) => {
+    const trimmed = param.trim();
+    const nameMatch = trimmed.match(/^(\w+)/);
+    if (!nameMatch) return param;
+    const name = nameMatch[1];
+    if (name.startsWith("_")) return param;
+    const re = new RegExp(`\\b${name}\\b`);
+    if (re.test(handler)) return param;
+    return param.replace(new RegExp(`\\b${name}\\b`), `_${name}`);
+  }).join(", ");
+}
 function generateCommandWithSubcommands(name, description, subcommands, optionDefs) {
   const subcmdRegistrations = Object.entries(subcommands).map(([subName, subDef]) => {
     const subDesc = subDef.description || "";
@@ -851,20 +926,22 @@ function generateCommandWithSubcommands(name, description, subcommands, optionDe
       const alias = flag.alias ? `${flag.alias}, ` : "";
       const flagType = flag.type?.toLowerCase();
       const valuePart = flagType === "boolean" ? "" : ` <${flagName.replace(/^--/, "")}>`;
-      const defaultVal = flag.default !== void 0 ? `, ${JSON.stringify(flag.default)}` : "";
-      return `    .option('${alias}${flagName}${valuePart}', '${flag.description || flagName}'${defaultVal})`;
+      const defaultVal = flag.default !== void 0 ? `, ${commanderDefault(flag.default, flagType)}` : "";
+      const desc = escapeSingleQuotes(flag.description || flagName);
+      return `    .option('${alias}${flagName}${valuePart}', '${desc}'${defaultVal})`;
     });
     const handlerKey = `${name}.${subName}`;
     const engineHandler = ENGINE_HANDLERS[handlerKey];
     const subArgTypes = Object.entries(subArgs).filter(([_, a]) => a.positional).map(([n, a]) => `${n}: ${mapArgTypeToTS(a.type)}`);
     const subActionParams = subArgTypes.length > 0 ? subArgTypes.join(", ") + ", options: any" : "options: any";
     const handler = engineHandler ? engineHandler.handler : `console.log('${name} ${subName}: not yet implemented via engine');`;
+    const finalSubActionParams = renameUnusedActionParams(subActionParams, handler);
     return `
   cmd
     .command('${subCmdStr}')
-    .description('${subDesc}')
+    .description('${escapeSingleQuotes(subDesc)}')
 ${subOptionDefs.join("\n")}
-    .action(async (${subActionParams}) => {
+    .action(async (${finalSubActionParams}) => {
       try {
         ${handler}
       } catch (error: any) {
@@ -875,7 +952,7 @@ ${subOptionDefs.join("\n")}
   });
   return `const cmd = program
     .command('${name}')
-    .description('${description}');
+    .description('${escapeSingleQuotes(description)}');
 ${subcmdRegistrations.join("\n")}`;
 }
 function generateSubcommandRegistrations(_parentName, _subcommands) {
@@ -899,10 +976,14 @@ function mapArgTypeToTS(type) {
 function capitalize(str) {
   return str.split("-").map((part) => part.charAt(0).toUpperCase() + part.slice(1)).join("");
 }
-function deduplicateImports(importBlocks) {
+function deduplicateImports(importBlocks, usedIn) {
   const seen = /* @__PURE__ */ new Map();
   const typeImports = /* @__PURE__ */ new Map();
   const rawLines = /* @__PURE__ */ new Set();
+  const isUsed = (name) => {
+    if (!usedIn) return true;
+    return new RegExp(`\\b${name.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")}\\b`).test(usedIn);
+  };
   for (const block of importBlocks) {
     for (const line of block.split("\n").map((l) => l.trim()).filter((l) => l)) {
       const namedMatch = line.match(/^import\s+\{\s*(.+?)\s*\}\s+from\s+'(.+?)';?$/);
@@ -926,11 +1007,14 @@ function deduplicateImports(importBlocks) {
   }
   const result = [];
   for (const [mod, names] of seen.entries()) {
-    result.push(`import { ${[...names].join(", ")} } from '${mod}';`);
+    const used = [...names].filter(isUsed);
+    if (used.length > 0) {
+      result.push(`import { ${used.join(", ")} } from '${mod}';`);
+    }
   }
   for (const [mod, names] of typeImports.entries()) {
     const regularNames = seen.get(mod) || /* @__PURE__ */ new Set();
-    const typeOnly = [...names].filter((n) => !regularNames.has(n));
+    const typeOnly = [...names].filter((n) => !regularNames.has(n)).filter(isUsed);
     if (typeOnly.length > 0) {
       result.push(`import type { ${typeOnly.join(", ")} } from '${mod}';`);
     }

package/dist/libs/instance-factories/communication/templates/eventemitter/bus-generator.js

@@ -8,8 +8,8 @@ function generateEventBus(context) {
  * Generated from SpecVerse specification
  */
 
-import EventEmitter from 'eventemitter3';
-${hasEvents || models.length > 0 ? `import type { EventPayloads, EventName } from './event-types.js';` : ""}
+import { EventEmitter } from 'eventemitter3';
+${hasEvents || models.length > 0 ? `import type { EventPayloads } from './event-types.js';` : ""}
 
 // Re-export types for consumers
 ${hasEvents || models.length > 0 ? `export type { EventPayloads, EventName } from './event-types.js';` : ""}
@@ -33,7 +33,6 @@ class EventBus extends EventEmitter {
 
   private constructor() {
     super();
-    this.setMaxListeners(100);
   }
 
   public static getInstance(): EventBus {

package/dist/libs/instance-factories/controllers/templates/fastify/routes-generator.js

@@ -214,10 +214,30 @@ function generateHandlerBody(operation, modelName, handlerName, isModelControlle
   });
 }`;
     default: {
-      const paramNames = endpoint?.parameters ? Object.keys(endpoint.parameters) : [];
+      const params = endpoint?.parameters || {};
+      const paramNames = Object.keys(params);
       const callArgs = paramNames.length > 0 ? paramNames.map((p) => `body.${p}`).join(", ") : "body";
+      const validations = [];
+      for (const [pName, pDef] of Object.entries(params)) {
+        const required = typeof pDef === "string" ? pDef.includes("required") : pDef?.required;
+        const typeStr = typeof pDef === "string" ? pDef.split(" ")[0] : pDef?.type || "String";
+        if (required) {
+          validations.push(`  if (body.${pName} === undefined || body.${pName} === null) errors.push({ field: '${pName}', message: '${pName} is required' });`);
+        }
+        if (typeStr === "UUID" || typeStr === "String" || typeStr === "Email") {
+          validations.push(`  if (body.${pName} !== undefined && typeof body.${pName} !== 'string') errors.push({ field: '${pName}', message: '${pName} must be a string' });`);
+        } else if (typeStr === "Integer" || typeStr === "Number" || typeStr === "Float") {
+          validations.push(`  if (body.${pName} !== undefined && typeof body.${pName} !== 'number') errors.push({ field: '${pName}', message: '${pName} must be a number' });`);
+        } else if (typeStr === "Boolean") {
+          validations.push(`  if (body.${pName} !== undefined && typeof body.${pName} !== 'boolean') errors.push({ field: '${pName}', message: '${pName} must be a boolean' });`);
+        }
+      }
+      const validationBlock = validations.length > 0 ? `  const errors: Array<{ field: string; message: string }> = [];
+${validations.join("\n")}
+  if (errors.length > 0) return reply.status(400).send({ error: 'Validation failed', details: errors });` : "";
       return `try {
   const body = (request.body || {}) as Record<string, any>;
+${validationBlock}
   const result = await handler.${operation}(${callArgs});
   return reply.send(result || { success: true });
 } catch (error) {

package/dist/libs/instance-factories/scaffolding/templates/generic/tsconfig-generator.js

@@ -1,8 +1,16 @@
 function generateTsConfig(context) {
   const { manifest, spec } = context;
-  const mergedOptions = extractTsConfigOptions(context.implementationTypes || []);
+  const implementationTypes = context.implementationTypes || [];
+  const isMonorepo = !implementationTypes.some((it) => {
+    const cfg = it?.configuration || it?.instanceFactory?.configuration || {};
+    return cfg.outputStructure === "standalone";
+  });
+  if (isMonorepo) {
+    return "";
+  }
+  const mergedOptions = extractTsConfigOptions(implementationTypes);
   const hasViews = spec && (spec.views || Array.isArray(spec.views) && spec.views.length > 0);
-  const usesReact = hasViews && (context.implementationTypes || []).some(
+  const usesReact = hasViews && implementationTypes.some(
     (implType) => implType.capabilities?.provides?.includes("ui.components") && implType.technology?.framework === "react"
   );
   const tsconfig = {

package/dist/libs/instance-factories/services/templates/prisma/ai-behaviors-generator.js

@@ -1,4 +1,48 @@
 import { matchStep } from "./step-conventions.js";
+import { createHash } from "crypto";
+import { readFileSync, writeFileSync, existsSync, mkdirSync } from "fs";
+import { join } from "path";
+async function validateTypeScript(code) {
+  try {
+    const esbuild = await import("esbuild");
+    await esbuild.transform(code, {
+      loader: "ts",
+      format: "esm",
+      target: "es2022"
+    });
+    return null;
+  } catch (err) {
+    const msg = err?.errors?.[0]?.text || err?.message || "unknown syntax error";
+    return msg;
+  }
+}
+const PROMPT_VERSION = "9.1.0";
+function cacheKey(step, modelName, operationName, functionName, inputs) {
+  const payload = JSON.stringify({ step, modelName, operationName, functionName, inputs: [...inputs].sort(), v: PROMPT_VERSION });
+  return createHash("sha256").update(payload).digest("hex").slice(0, 16);
+}
+function cacheDir() {
+  const cwd = process.env.SPECVERSE_USER_CWD || process.cwd();
+  return join(cwd, ".specverse", "ai-cache");
+}
+function cacheRead(key) {
+  const path = join(cacheDir(), `${key}.ts`);
+  if (!existsSync(path)) return null;
+  try {
+    return readFileSync(path, "utf8");
+  } catch {
+    return null;
+  }
+}
+function cacheWrite(key, body) {
+  const dir = cacheDir();
+  try {
+    if (!existsSync(dir)) mkdirSync(dir, { recursive: true });
+    writeFileSync(join(dir, `${key}.ts`), body, "utf8");
+  } catch (err) {
+    console.warn(`      [ai-cache] write failed: ${err?.message || err}`);
+  }
+}
 async function generateAiBehaviors(context) {
   const { controller, model } = context;
   if (!controller?.actions) return "";
@@ -18,8 +62,11 @@ async function generateAiBehaviors(context) {
       }
     }
     for (let i = 0; i < steps.length; i++) {
-      const step = steps[i];
-      if (typeof step !== "string") continue;
+      const stepInput = steps[i];
+      const stepText = typeof stepInput === "string" ? stepInput : stepInput?.step;
+      const stepAs = typeof stepInput === "object" ? stepInput?.as : void 0;
+      const stepReturns = typeof stepInput === "object" ? stepInput?.returns : void 0;
+      if (typeof stepText !== "string") continue;
       const ctx = {
         modelName,
         prismaModel: modelVar,
@@ -27,24 +74,39 @@ async function generateAiBehaviors(context) {
         operationName: actionName,
         stepNum: i + 1,
         parameterNames,
-        declaredVars
+        declaredVars,
+        resultName: stepAs
       };
-      const result = matchStep(step, ctx);
+      const result = matchStep(stepText, ctx);
       if (!result.matched && result.functionName) {
         const existing = unmatchedFunctions.find((f) => f.functionName === result.functionName);
         if (!existing) {
           unmatchedFunctions.push({
             functionName: result.functionName,
-            step,
+            step: stepText,
             operationName: actionName,
             parameterNames,
-            inputs: result.inputs || []
+            inputs: result.inputs || [],
+            returns: stepReturns
           });
         }
       }
     }
   }
   if (unmatchedFunctions.length === 0) return "";
+  return generateAiBehaviorsFile({
+    ownerName: `${modelName}Controller`,
+    unmatchedFunctions: unmatchedFunctions.map((f) => ({
+      ...f,
+      modelName
+    })),
+    availableModels,
+    spec: context.spec
+  });
+}
+async function generateAiBehaviorsFile(opts) {
+  const { ownerName, unmatchedFunctions, availableModels: availableModels2, spec } = opts;
+  if (unmatchedFunctions.length === 0) return "";
   let aiService = null;
   try {
     const { BehaviorAIService } = await import("@specverse/engines/ai");
@@ -52,19 +114,42 @@ async function generateAiBehaviors(context) {
     if (!aiService.isAvailable) {
       aiService = null;
     } else {
-      aiService.startSession(`${modelName}Controller`);
+      aiService.startSession(ownerName);
     }
   } catch {
     aiService = null;
   }
-  const availableModels = context.spec?.models ? Object.keys(context.spec.models) : [];
   const functions = [];
-  for (const { functionName, step, operationName, parameterNames, inputs } of unmatchedFunctions) {
+  let cacheHits = 0;
+  let cacheMisses = 0;
+  for (const { functionName, step, operationName, parameterNames, inputs, returns, modelName } of unmatchedFunctions) {
     const signature = inputs.length > 0 ? `input: { ${inputs.map((n) => `${n}: any`).join("; ")} }` : "input: Record<string, never>";
     const destructure = inputs.length > 0 ? `  const { ${inputs.join(", ")} } = input;` : "";
-    let body = null;
-    let source = "STUB";
-    if (aiService) {
+    let returnType = "any";
+    if (typeof returns === "string") {
+      returnType = returns;
+    } else if (returns && typeof returns === "object") {
+      const fields = Object.entries(returns).map(([k, v]) => `${k}: ${v}`).join("; ");
+      returnType = `{ ${fields} }`;
+    }
+    const key = cacheKey(step, modelName, operationName, functionName, inputs);
+    let body = cacheRead(key);
+    let source = body ? "AI-CACHED" : "STUB";
+    if (body) {
+      const testCode = `export async function ${functionName}(input: any): Promise<any> {
+${body}
+}`;
+      const validationError = await validateTypeScript(testCode);
+      if (validationError) {
+        console.warn(`      [ai-validate] cached ${functionName} failed validation: ${validationError}`);
+        body = null;
+        source = "STUB";
+      } else {
+        cacheHits++;
+      }
+    }
+    if (!body && aiService) {
+      cacheMisses++;
       try {
         body = await aiService.generateBehavior({
           step,
@@ -73,10 +158,27 @@ async function generateAiBehaviors(context) {
           functionName,
           parameterNames: inputs,
           // the actual inputs to the pure function
-          availableModels,
-          spec: context.spec
+          availableModels: availableModels2,
+          spec,
+          returnType
+          // Pass declared return type to Claude
         });
-        if (body) source = "AI-GENERATED";
+        if (body) {
+          const testCode = `export async function ${functionName}(input: any): Promise<any> {
+${body}
+}`;
+          const validationError = await validateTypeScript(testCode);
+          if (validationError) {
+            console.warn(`      [ai-validate] ${functionName} has syntax error: ${validationError}`);
+            body = `// AI-generated code failed validation: ${validationError}
+  // Step: ${step}
+  throw new Error('AI behavior has invalid syntax \u2014 see comment above');`;
+            source = "AI-INVALID";
+          } else {
+            source = "AI-GENERATED";
+            cacheWrite(key, body);
+          }
+        }
       } catch {
       }
     }
@@ -86,31 +188,36 @@ async function generateAiBehaviors(context) {
       body = body.split("\n").map((line) => line ? "  " + line : line).join("\n");
     }
     const inputsDoc = inputs.length > 0 ? ` * Inputs: ${inputs.join(", ")}
+` : "";
+    const returnsDoc = returnType !== "any" ? ` * Returns: ${returnType}
 ` : "";
     functions.push(`/**
  * ${functionName}
  *
  * Spec step: "${step}"
- * Called by: ${modelName}Controller.${operationName}()
-${inputsDoc} * Source: ${source}
+ * Called by: ${ownerName}.${operationName}()
+${inputsDoc}${returnsDoc} * Source: ${source}
  * Generated: ${(/* @__PURE__ */ new Date()).toISOString().split("T")[0]}
  *
  * PURE FUNCTION \u2014 no database access, no event publishing, no external services.
  * All data comes in via \`input\`; all effects happen in the calling controller.
- * ${source === "AI-GENERATED" ? "AI-generated implementation. Review and test before deploying." : "STUB \u2014 Claude CLI unavailable. Install Claude Code or implement manually."}
+ * ${source === "AI-GENERATED" ? "AI-generated implementation. Review and test before deploying." : source === "AI-CACHED" ? "Restored from AI cache (.specverse/ai-cache/). Delete cache entry to regenerate." : source === "AI-INVALID" ? "AI returned code with syntax errors \u2014 function throws at runtime. Fix or regenerate." : "STUB \u2014 Claude CLI unavailable. Install Claude Code or implement manually."}
  */
-export async function ${functionName}(${signature}): Promise<any> {
+export async function ${functionName}(${signature}): Promise<${returnType}> {
 ${destructure ? destructure + "\n" : ""}${body}
 }`);
   }
   if (aiService?.endSession) aiService.endSession();
+  if (cacheHits > 0 || cacheMisses > 0) {
+    console.log(`      AI cache: ${cacheHits} hit(s), ${cacheMisses} miss(es) for ${ownerName}`);
+  }
   return `/**
- * ${modelName}Controller \u2014 AI-Generated Behaviors
+ * ${ownerName} \u2014 AI-Generated Behaviors
  *
  * \u26A0\uFE0F  THIS FILE CONTAINS STUBS FOR STEPS THAT NEED IMPLEMENTATION
  *
  * These functions could not be generated from convention patterns.
- * They are called by ${modelName}Controller when executing custom actions.
+ * They are called by ${ownerName} when executing operations.
  *
  * Options for each function:
  * - Implement manually (recommended for business-critical logic)
@@ -137,5 +244,6 @@ ${functions.join("\n\n")}
 `;
 }
 export {
-  generateAiBehaviors as default
+  generateAiBehaviors as default,
+  generateAiBehaviorsFile
 };

package/dist/libs/instance-factories/services/templates/prisma/behavior-generator.js

@@ -101,8 +101,11 @@ function generateStepLogic(steps, context, preconditionDeclared) {
   const unmatchedSteps = [];
   const declaredVars = preconditionDeclared || /* @__PURE__ */ new Set();
   if (steps && steps.length > 0) {
-    const stepCode = steps.map((step, i) => {
-      if (typeof step !== "string") {
+    const stepCode = steps.map((stepInput, i) => {
+      const stepText = typeof stepInput === "string" ? stepInput : stepInput.step;
+      const resultName = typeof stepInput === "object" ? stepInput.as : void 0;
+      const returns = typeof stepInput === "object" ? stepInput.returns : void 0;
+      if (typeof stepText !== "string") {
         return `    // Step ${i + 1}: Complex operation \u2014 see expanded definition`;
       }
       const ctx = {
@@ -112,18 +115,22 @@ function generateStepLogic(steps, context, preconditionDeclared) {
         operationName: context.operationName,
         stepNum: i + 1,
         parameterNames: context.parameterNames,
-        declaredVars
+        declaredVars,
+        resultName
+        // Pass through the named result
       };
-      const result = matchStep(step, ctx);
+      const result = matchStep(stepText, ctx);
       if (result.helperMethod) {
         helpers.push(result.helperMethod);
       }
       if (!result.matched && result.functionName) {
         unmatchedSteps.push({
-          step,
+          step: stepText,
           functionName: result.functionName,
           operationName: context.operationName,
-          inputs: result.inputs || []
+          inputs: result.inputs || [],
+          returns,
+          resultName: resultName || `step${i + 1}Result`
         });
       }
       return result.call;
@@ -177,7 +184,7 @@ function generateEventPublishing(sideEffects, operationName, parameterNames) {
   if (!sideEffects || sideEffects.length === 0) return "";
   const paramFields = parameterNames?.length ? parameterNames.join(", ") + ", " : "";
   const publishes = sideEffects.map(
-    (event) => `    await eventBus.publish('${event}', { ${paramFields}timestamp: new Date().toISOString() });`
+    (event) => `    await eventBus.publish('${event}', { ${paramFields}timestamp: new Date().toISOString() } as any);`
   );
   return `    // === EVENTS ===
 ${publishes.join("\n")}`;