@specverse/engines 6.6.3 → 6.11.2

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

@@ -21,10 +21,14 @@ function generateFastifyRoutes(context) {
     for (const [actionName, action] of Object.entries(controller.actions)) {
       const params = action.parameters || {};
       const hasIdParam = Object.keys(params).some((p) => p === "id" || p === `${modelName?.charAt(0).toLowerCase()}${modelName?.slice(1)}Id`);
+      const explicitPath = action.path;
+      const explicitMethod = action.method;
+      const isExternal = !!(explicitPath && /^\/api\//.test(explicitPath));
       endpoints.push({
         operation: actionName,
-        method: "POST",
-        path: hasIdParam ? `/:id/${actionName}` : `/${actionName}`,
+        method: explicitMethod || "POST",
+        path: explicitPath || (hasIdParam ? `/:id/${actionName}` : `/${actionName}`),
+        external: isExternal,
         parameters: params,
         description: action.description || `Custom action: ${actionName}`
       });
@@ -33,9 +37,27 @@ function generateFastifyRoutes(context) {
   if (!endpoints || endpoints.length === 0) {
     console.warn(`Warning: Controller ${controllerName} has no endpoints. Generating empty routes file.`);
   }
-  const routeHandlers = endpoints?.map((endpoint) => {
-    return generateRouteHandler(endpoint, modelName, handlerName, isModelController, implType, controllerName);
-  }).join("\n\n") || "";
+  const internalEndpoints = endpoints?.filter((e) => !e.external) || [];
+  const externalEndpoints = endpoints?.filter((e) => e.external) || [];
+  const internalHandlers = internalEndpoints.map((endpoint) => generateRouteHandler(endpoint, modelName, handlerName, isModelController, implType, controllerName)).join("\n\n");
+  const externalHandlers = externalEndpoints.map((endpoint) => generateRouteHandler(endpoint, modelName, handlerName, isModelController, implType, controllerName)).join("\n\n");
+  const externalRoutesExport = externalEndpoints.length > 0 ? `
+/**
+ * Mount the external (root-prefix) routes for this controller.
+ *
+ * Called by the generated main.ts at root scope (no prefix) so action.path
+ * declarations like '/api/v2/auth/register' land at exactly that URL,
+ * bypassing the controller's '/api/<plural>' prefix.
+ */
+export async function registerExternalRoutes(
+  fastify: FastifyInstance,
+  options: any
+) {
+  const handler = ${isModelController ? "options.controllers" : "options.services"}.${handlerName};
+
+${externalHandlers.split("\n").map((line) => "  " + line).join("\n")}
+}
+` : "";
   return `${imports}
 
 /**
@@ -51,9 +73,9 @@ export default async function ${routeName.replace("Controller", "")}Routes(
 ) {
   const handler = ${isModelController ? "options.controllers" : "options.services"}.${handlerName};
 
-${routeHandlers.split("\n").map((line) => "  " + line).join("\n")}
+${internalHandlers.split("\n").map((line) => "  " + line).join("\n")}
 }
-`;
+${externalRoutesExport}`;
 }
 function generateImports(controller, modelName, handlerName, isModelController, implType) {
   const imports = [
@@ -226,36 +248,49 @@ function generateHandlerBody(operation, modelName, handlerName, isModelControlle
   });
 }`;
     default: {
+      const path = endpoint?.path || "";
+      const urlParamNames = /* @__PURE__ */ new Set();
+      const urlParamRegex = /:([A-Za-z_][\w]*)/g;
+      let urlMatch;
+      while ((urlMatch = urlParamRegex.exec(path)) !== null) {
+        urlParamNames.add(urlMatch[1]);
+      }
       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)) {
+        if (urlParamNames.has(pName)) continue;
         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' });`);
+          validations.push(`  if (args.${pName} === undefined || args.${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' });`);
+          validations.push(`  if (args.${pName} !== undefined && typeof args.${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' });`);
+          validations.push(`  if (args.${pName} !== undefined && typeof args.${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' });`);
+          validations.push(`  if (args.${pName} !== undefined && typeof args.${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 params = (request.params || {}) as Record<string, any>;
   const body = (request.body || {}) as Record<string, any>;
+  const args = { ...params, ...body };
 ${validationBlock}
-  const result = await handler.${operation}(${callArgs});
+  const result = await handler.${operation}(args);
   return reply.send(result || { success: true });
 } catch (error) {
+  const msg = error instanceof Error ? error.message : String(error);
+  // 501 for TODO-stubbed action bodies (#43F); 400 for real failures.
+  if (msg.includes('is not implemented')) {
+    return reply.status(501).send({ error: 'Not Implemented', message: msg });
+  }
   return reply.status(400).send({
     error: 'Failed to execute ${operation}',
-    message: error instanceof Error ? error.message : String(error)
+    message: msg
   });
 }`;
     }

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

@@ -1,15 +1,31 @@
 import { normalizeSpec, deriveBasePath } from "@specverse/types/spec-rules";
+function resolveOrmName(manifest) {
+  if (!manifest) return "PrismaORM";
+  const inner = manifest.manifests ? Object.values(manifest.manifests)[0] : manifest;
+  if (!inner) return "PrismaORM";
+  const caps = Array.isArray(inner.capabilityMappings) ? inner.capabilityMappings : [];
+  const ormCap = caps.find((m) => m?.capability === "orm.client") || caps.find((m) => m?.capability === "orm.schema");
+  if (ormCap) return ormCap.implementation || ormCap.instanceFactory || "PrismaORM";
+  return inner.defaultMappings?.orm || "PrismaORM";
+}
 function generateFastifyServer(context) {
-  const { spec, models } = context;
+  const { spec, models, manifest } = context;
+  const orm = resolveOrmName(manifest);
+  const isMongoNative = orm === "MongoDBNativeDriver";
   const allModels = models || (spec?.models ? Object.values(spec.models) : []);
   const modelNames = allModels.map((m) => m.name).filter(Boolean);
   const routeImports = modelNames.map(
-    (name) => `import ${name}Routes from './routes/${name}Controller.js';`
+    (name) => `import ${name}Routes, * as ${name}RoutesNS from './routes/${name}Controller.js';`
   ).join("\n");
   const routeRegistrations = modelNames.map((name) => {
     const path = deriveBasePath(name);
     return `  await fastify.register(${name}Routes, { prefix: '${path}', controllers: { ${name}Controller: new (await import('./controllers/${name}Controller.js')).${name}Controller() } });`;
   }).join("\n");
+  const externalRouteRegistrations = modelNames.map((name) => {
+    return `  if (typeof (${name}RoutesNS as any).registerExternalRoutes === 'function') {
+    await (${name}RoutesNS as any).registerExternalRoutes(fastify, { controllers: { ${name}Controller: new (await import('./controllers/${name}Controller.js')).${name}Controller() } });
+  }`;
+  }).join("\n");
   const specEvents = spec.events ? Object.keys(spec.events) : [];
   const hasEvents = specEvents.length > 0 || modelNames.length > 0;
   const servicesList = spec.services ? Object.keys(spec.services) : [];
@@ -39,7 +55,7 @@ function generateFastifyServer(context) {
 // workspace before running the script.
 import { config as loadEnv } from 'dotenv';
 import { existsSync } from 'fs';
-import { resolve as resolvePath, dirname, join } from 'path';
+import { dirname, join } from 'path';
 import { fileURLToPath } from 'url';
 {
   let dir = dirname(fileURLToPath(import.meta.url));
@@ -52,12 +68,13 @@ import { fileURLToPath } from 'url';
 
 import Fastify from 'fastify';
 import cors from '@fastify/cors';
-import { PrismaClient } from '@prisma/client';
+${isMongoNative ? `import { disconnect as disconnectMongo } from './db/mongoClient.js';` : `import { PrismaClient } from '@prisma/client';`}
 ${hasEvents ? `import { eventBus } from './events/eventBus.js';
 import { registerWebSocketBridge } from './events/websocket-bridge.js';` : ""}
 
-// Initialize Prisma
-export const prisma = new PrismaClient();
+${isMongoNative ? `// MongoDB native driver client lives in db/mongoClient.ts; nothing
+// to initialize at module scope (lazy-connect on first getCollection).` : `// Initialize Prisma
+export const prisma = new PrismaClient();`}
 
 // Initialize Fastify
 const fastify = Fastify({
@@ -99,6 +116,9 @@ ${serviceRouteImports}` : ""}
 async function registerRoutes() {
 ${routeRegistrations}
 ${serviceRouteRegistrations ? "\n  // Service operation routes (RPC-style under /api/services/{ServiceName})\n" + serviceRouteRegistrations : ""}
+
+  // External-prefix actions (action.path declarations like '/api/v2/auth/register')
+${externalRouteRegistrations}
 }
 
 // Start server
@@ -127,7 +147,7 @@ ${hasEvents ? `    console.log(\`WebSocket: ws://localhost:\${port}/ws\`);
       try {
         fastify.log.info(\`Received \${signal}, closing server...\`);
         await fastify.close();
-        try { await (prisma as any).$disconnect?.(); } catch { /* ignore */ }
+        try { ${isMongoNative ? "await disconnectMongo();" : "await (prisma as any).$disconnect?.();"} } catch { /* ignore */ }
         process.exit(0);
       } catch (err) {
         fastify.log.error({ err }, 'Error during shutdown');

package/dist/libs/instance-factories/services/templates/mongodb-native/controller-generator.js

@@ -8,7 +8,7 @@ function generateMongoNativeController(context) {
   const modelVar = lowerFirst(modelName);
   const collection = collectionName(model);
   const curedOps = controller.cured || {};
-  const customActions = generateCustomActions(controller, modelName);
+  const customActions = generateCustomActions(controller);
   const validate = generateValidateMethod(model, modelName);
   const create = curedOps.create ? generateCreateMethod(model, modelName, modelVar, collection) : "";
   const retrieve = curedOps.retrieve ? generateRetrieveMethod(modelName, modelVar, collection) : "";
@@ -24,7 +24,7 @@ function generateMongoNativeController(context) {
 import { ObjectId, type Filter, type Document } from 'mongodb';
 import { getCollection } from '../db/mongoClient.js';
 ${hasEventPublishing ? `import { eventBus } from '../events/eventBus.js';` : ""}
-${customActions.needsAiBehaviors ? `import * as aiBehaviors from '../behaviors/${modelName}Controller.ai.js';` : ""}
+${customActions.needsAiBehaviors ? `import * as aiBehaviors from '../behaviors/${controllerName}.ai.js';` : ""}
 
 const COLLECTION_NAME = '${collection}';
 
@@ -107,7 +107,7 @@ function generateCreateMethod(model, modelName, modelVar, collection) {
     const validation = this.validate(data, { operation: 'create' });
     if (!validation.valid) throw new Error(\`Validation failed: \${validation.errors.join(', ')}\`);
 
-    const collection = await getCollection('${collection}');
+    const collection = await getCollection(COLLECTION_NAME);
     const result = await collection.insertOne({ ...data });
     const ${modelVar} = { _id: result.insertedId, ...data };
 
@@ -122,7 +122,7 @@ function generateRetrieveMethod(modelName, modelVar, collection) {
    * Retrieve ${modelName} by id. Returns null when not found.
    */
   public async retrieve(id: string): Promise<any | null> {
-    const collection = await getCollection('${collection}');
+    const collection = await getCollection(COLLECTION_NAME);
     return await collection.findOne(byId(id));
   }
 
@@ -130,7 +130,7 @@ function generateRetrieveMethod(modelName, modelVar, collection) {
    * Retrieve a page of ${modelName}s.
    */
   public async retrieveAll(options: { skip?: number; take?: number } = {}): Promise<any[]> {
-    const collection = await getCollection('${collection}');
+    const collection = await getCollection(COLLECTION_NAME);
     const cursor = collection.find({});
     if (options.skip) cursor.skip(options.skip);
     if (options.take) cursor.limit(options.take);
@@ -156,7 +156,7 @@ function generateUpdateMethod(modelName, modelVar, collection) {
       updateData[key] = value;
     }
 
-    const collection = await getCollection('${collection}');
+    const collection = await getCollection(COLLECTION_NAME);
     await collection.updateOne(byId(id), { $set: updateData });
     const ${modelVar} = await collection.findOne(byId(id));
     if (!${modelVar}) throw new Error('${modelName} not found after update');
@@ -181,7 +181,7 @@ function generateEvolveMethod(model, modelName, modelVar, collection) {
    * States: ${states.join(" \u2192 ") || "(none declared)"}
    */
   public async evolve(id: string, data: any): Promise<any> {
-    const collection = await getCollection('${collection}');
+    const collection = await getCollection(COLLECTION_NAME);
     const current = await collection.findOne(byId(id));
     if (!current) throw new Error('${modelName} not found');
 
@@ -213,7 +213,7 @@ function generateDeleteMethod(modelName, modelVar, collection) {
    * Delete ${modelName}.
    */
   public async delete(id: string): Promise<void> {
-    const collection = await getCollection('${collection}');
+    const collection = await getCollection(COLLECTION_NAME);
     const ${modelVar} = await collection.findOne(byId(id));
     await collection.deleteOne(byId(id));
     if (${modelVar}) {
@@ -222,14 +222,59 @@ function generateDeleteMethod(modelName, modelVar, collection) {
   }
 `;
 }
-function generateCustomActions(controller, modelName) {
+import { matchMongoStep } from "./step-conventions.js";
+function generateCustomActions(controller) {
   if (!controller.actions || Object.keys(controller.actions).length === 0) {
     return { code: "", needsAiBehaviors: false };
   }
+  const CRUD_NAMES = /* @__PURE__ */ new Set(["create", "retrieve", "retrieveAll", "update", "evolve", "delete", "validate"]);
+  const modelName = controller.model || (controller.name || "").replace(/Controller$/, "") || "Model";
+  const collectionName2 = modelName.toLowerCase() + "s";
   const out = [];
+  let needsAiBehaviors = false;
   for (const [actionName, action] of Object.entries(controller.actions)) {
-    const params = generateActionParams(action);
-    const stepsHeader = action.steps && action.steps.length > 0 ? action.steps.map((s) => `   *   - ${typeof s === "string" ? s : s.action || JSON.stringify(s)}`).join("\n") : "   *   (no spec steps declared)";
+    if (CRUD_NAMES.has(actionName)) continue;
+    const steps = Array.isArray(action.steps) ? action.steps : [];
+    const stepsHeader = steps.length > 0 ? steps.map((s) => `   *   - ${typeof s === "string" ? s : s.action || JSON.stringify(s)}`).join("\n") : "   *   (no spec steps declared)";
+    const declaredVars = /* @__PURE__ */ new Set();
+    const stepBodies = [];
+    let usesArgs = false;
+    let actionRefersToAi = false;
+    steps.forEach((rawStep, i) => {
+      const stepText = typeof rawStep === "string" ? rawStep : rawStep?.step || rawStep?.action;
+      if (typeof stepText !== "string") {
+        stepBodies.push(`    // Step ${i + 1}: (non-string step ignored)`);
+        return;
+      }
+      const ctx = {
+        modelName,
+        collectionName: collectionName2,
+        serviceName: controller.name || "Controller",
+        operationName: actionName,
+        stepNum: i + 1,
+        parameterNames: Object.keys(action.parameters || {}),
+        declaredVars
+      };
+      const result = matchMongoStep(stepText, ctx);
+      stepBodies.push(result.call);
+      if (/\bargs\./.test(result.call)) usesArgs = true;
+      if (!result.matched) actionRefersToAi = true;
+    });
+    if (actionRefersToAi) needsAiBehaviors = true;
+    const argsParam = usesArgs ? "args: any = {}" : "_args: any = {}";
+    let combined = stepBodies.join("\n\n");
+    const stepResultRe = /const\s+(step\d+Result)\s*=/g;
+    let mres;
+    const declared = [];
+    while ((mres = stepResultRe.exec(combined)) !== null) declared.push(mres[1]);
+    for (const name of declared) {
+      const refCount = (combined.match(new RegExp(`\\b${name}\\b`, "g")) || []).length;
+      if (refCount <= 1) {
+        combined = combined.replace(new RegExp(`const\\s+${name}\\s*=\\s*`), "");
+      }
+    }
+    const body = steps.length > 0 ? combined + `
+    return { success: true };` : `    throw new Error('${controller.name || "Controller"}.${actionName} is not implemented');`;
     out.push(`
   /**
    * ${actionName}
@@ -238,21 +283,12 @@ function generateCustomActions(controller, modelName) {
    * Spec steps:
 ${stepsHeader}
    */
-  public async ${actionName}(${params}): Promise<any> {
-    return await aiBehaviors.${actionName}({ controller: this, ...args });
+  public async ${actionName}(${argsParam}): Promise<any> {
+${body}
   }
 `);
   }
-  return { code: out.join("\n"), needsAiBehaviors: true };
-}
-function generateActionParams(action) {
-  if (Array.isArray(action.parameters) && action.parameters.length > 0) {
-    return "args: any";
-  }
-  if (action.parameters && typeof action.parameters === "object" && Object.keys(action.parameters).length > 0) {
-    return "args: any";
-  }
-  return "args: any = {}";
+  return { code: out.join("\n"), needsAiBehaviors };
 }
 export {
   generateMongoNativeController as default

package/dist/libs/instance-factories/services/templates/mongodb-native/step-conventions.js

@@ -0,0 +1,319 @@
+function toVar(name) {
+  return name.charAt(0).toLowerCase() + name.slice(1);
+}
+function toCollection(modelName) {
+  return modelName.toLowerCase() + "s";
+}
+function toMethod(words) {
+  const cleaned = words.trim().replace(/[^A-Za-z0-9\s]+/g, " ");
+  const camel = cleaned.replace(/\s+(.)/g, (_, c) => c.toUpperCase()).replace(/^\w/, (c) => c.toLowerCase());
+  const safe = camel.replace(/[^A-Za-z0-9_$]/g, "");
+  return safe || "unnamedStep";
+}
+function resolveValue(rawValue, ctx) {
+  const value = rawValue.trim().replace(/^['"]|['"]$/g, "");
+  if (/^(current\s*time|now|timestamp)$/i.test(value)) return "new Date().toISOString()";
+  if (value === "true" || value === "false") return value;
+  if (/^-?\d+(\.\d+)?$/.test(value)) return value;
+  const declared = ctx.declaredVars || /* @__PURE__ */ new Set();
+  const params = ctx.parameterNames || [];
+  const rootMatch = value.match(/^([a-zA-Z_][a-zA-Z0-9_]*)(\.[a-zA-Z0-9_.]+)?$/);
+  if (rootMatch) {
+    const root = rootMatch[1];
+    if (declared.has(root) || params.includes(root)) return value;
+    if (params.length > 0) return `args.${value}`;
+  }
+  if (/\s/.test(value)) return `/* TODO: resolve "${value}" */ null`;
+  return `'${value.replace(/'/g, "\\'")}'`;
+}
+const MONGO_STEP_CONVENTIONS = [
+  // --- Find / Lookup by single field ---
+  // Matches: "Look up X by Y", "Find X by Y", "Find X by Y or fail with 404"
+  {
+    name: "find-by-field",
+    pattern: /^(?:look\s+up|find|fetch|get)\s+(\w+)\s+by\s+(\w+)(?:\s+or\s+fail.*)?$/i,
+    generateCall: (m, ctx) => {
+      const model = m[1];
+      const field = m[2];
+      const modelVar = toVar(model);
+      const collection = toCollection(model);
+      const params = ctx.parameterNames || [];
+      const declared = ctx.declaredVars || /* @__PURE__ */ new Set();
+      const idVal = field === "id" ? params.includes(`${modelVar}Id`) ? `args.${modelVar}Id` : "args.id" : params.includes(field) ? `args.${field}` : `args.${field}`;
+      if (declared.has(modelVar)) {
+        return `    // Step ${ctx.stepNum}: Find ${model} by ${field} (already loaded)`;
+      }
+      declared.add(modelVar);
+      const failOnMissing = /or\s+fail/i.test(m[0]);
+      return `    // Step ${ctx.stepNum}: Find ${model} by ${field}
+    const ${modelVar}_collection = await getCollection('${collection}');
+    const ${modelVar} = await ${modelVar}_collection.findOne({ ${field}: ${idVal} });${failOnMissing ? `
+    if (!${modelVar}) throw new Error('${model} not found');` : ""}`;
+    }
+  },
+  // --- Find by composite (two fields) ---
+  // Matches: "Look up X by Y and Z", "Find X by Y and Z"
+  {
+    name: "find-by-composite",
+    pattern: /^(?:look\s+up|find|fetch|get)(?:\s+existing)?\s+(\w+)\s+by\s+(\w+)\s+and\s+(\w+)$/i,
+    generateCall: (m, ctx) => {
+      const model = m[1];
+      const f1 = m[2];
+      const f2 = m[3];
+      const modelVar = toVar(model);
+      const collection = toCollection(model);
+      const declared = ctx.declaredVars || /* @__PURE__ */ new Set();
+      if (declared.has(modelVar)) {
+        return `    // Step ${ctx.stepNum}: Find ${model} by ${f1} and ${f2} (already loaded)`;
+      }
+      declared.add(modelVar);
+      return `    // Step ${ctx.stepNum}: Find ${model} by ${f1} and ${f2}
+    const ${modelVar}_collection = await getCollection('${collection}');
+    const ${modelVar} = await ${modelVar}_collection.findOne({ ${f1}: args.${f1}, ${f2}: args.${f2} });`;
+    }
+  },
+  // --- Create model record ---
+  // Matches: "Create X", "Create new X with ..."
+  {
+    name: "create",
+    pattern: /^create\s+(?:new\s+)?(\w+)(?:\s+(?:with\s+)?(.+))?/i,
+    generateCall: (m, ctx) => {
+      const model = m[1];
+      const modelVar = toVar(model);
+      const collection = toCollection(model);
+      const params = ctx.parameterNames || [];
+      const declared = ctx.declaredVars || /* @__PURE__ */ new Set();
+      declared.add(modelVar);
+      const dataExpr = params.length > 0 ? `{ ${params.join(", ")} }` : "args";
+      return `    // Step ${ctx.stepNum}: Create ${model}
+    const ${modelVar}_collection = await getCollection('${collection}');
+    const ${modelVar}_inserted = await ${modelVar}_collection.insertOne(${dataExpr});
+    const ${modelVar} = { _id: ${modelVar}_inserted.insertedId, ...${dataExpr} };`;
+    }
+  },
+  // --- Update specific field on previously-loaded model ---
+  // Matches: "Update X field to value". Only fires when X has been
+  // declared by a prior matched find — otherwise the model var doesn't
+  // exist in scope and tsc fails. Falling through to the unmatched path
+  // lets the AI layer handle it.
+  {
+    name: "update-field",
+    pattern: /^update\s+(\w+)\s+(\w+)\s+to\s+(.+)/i,
+    generateCall: (m, ctx) => {
+      const model = m[1];
+      const field = m[2];
+      const rawValue = m[3];
+      const modelVar = toVar(model);
+      if (!ctx.declaredVars?.has(modelVar)) return "";
+      const collection = toCollection(model);
+      const val = resolveValue(rawValue, ctx);
+      return `    // Step ${ctx.stepNum}: Update ${model}.${field} to ${rawValue.trim()}
+    {
+      const ${modelVar}_collection = await getCollection('${collection}');
+      await ${modelVar}_collection.updateOne({ _id: ${modelVar}._id }, { $set: { ${field}: ${val} } });
+    }`;
+    }
+  },
+  // --- Update field timestamp (e.g. "Update device lastLoginAt timestamp") ---
+  {
+    name: "update-field-timestamp",
+    pattern: /^update\s+(\w+)\s+(\w+)\s+timestamp$/i,
+    generateCall: (m, ctx) => {
+      const model = m[1];
+      const field = m[2];
+      const modelVar = toVar(model);
+      if (!ctx.declaredVars?.has(modelVar)) return "";
+      const collection = toCollection(model);
+      return `    // Step ${ctx.stepNum}: Update ${model}.${field} timestamp
+    {
+      const ${modelVar}_collection = await getCollection('${collection}');
+      await ${modelVar}_collection.updateOne({ _id: ${modelVar}._id }, { $set: { ${field}: new Date().toISOString() } });
+    }`;
+    }
+  },
+  // --- Generic "Update X" (writes args back to record) ---
+  {
+    name: "update",
+    pattern: /^update\s+(\w+)(?:\s+(.+))?$/i,
+    generateCall: (m, ctx) => {
+      const model = m[1];
+      const modelVar = toVar(model);
+      if (!ctx.declaredVars?.has(modelVar)) return "";
+      const collection = toCollection(model);
+      return `    // Step ${ctx.stepNum}: Update ${model}
+    {
+      const ${modelVar}_collection = await getCollection('${collection}');
+      await ${modelVar}_collection.updateOne({ _id: ${modelVar}._id }, { $set: args });
+    }`;
+    }
+  },
+  // --- Delete model record ---
+  {
+    name: "delete",
+    pattern: /^delete\s+(\w+)/i,
+    generateCall: (m, ctx) => {
+      const model = m[1];
+      const modelVar = toVar(model);
+      if (!ctx.declaredVars?.has(modelVar)) return "";
+      const collection = toCollection(model);
+      return `    // Step ${ctx.stepNum}: Delete ${model}
+    {
+      const ${modelVar}_collection = await getCollection('${collection}');
+      await ${modelVar}_collection.deleteOne({ _id: ${modelVar}._id });
+    }`;
+    }
+  },
+  // --- Transition to lifecycle state ---
+  // Matches: "Transition X to state"
+  {
+    name: "transition",
+    pattern: /^transition\s+(\w+)\s+to\s+(\w+)/i,
+    generateCall: (m, ctx) => {
+      const model = m[1];
+      const state = m[2];
+      const modelVar = toVar(model);
+      if (!ctx.declaredVars?.has(modelVar)) return "";
+      const collection = toCollection(model);
+      return `    // Step ${ctx.stepNum}: Transition ${model} to ${state}
+    if ((${modelVar} as any).status === '${state}') throw new Error('${model} is already ${state}');
+    {
+      const ${modelVar}_collection = await getCollection('${collection}');
+      await ${modelVar}_collection.updateOne({ _id: ${modelVar}._id }, { $set: { status: '${state}' } });
+    }`;
+    }
+  },
+  // --- Set field to value (on the controller's primary model) ---
+  {
+    name: "set",
+    pattern: /^set\s+(\w+)\s+to\s+(.+)/i,
+    generateCall: (m, ctx) => {
+      const field = m[1];
+      const rawValue = m[2];
+      const modelVar = toVar(ctx.modelName);
+      const val = resolveValue(rawValue, ctx);
+      return `    // Step ${ctx.stepNum}: Set ${field} to ${rawValue.trim()}
+    {
+      const ${modelVar}_collection = await getCollection(COLLECTION_NAME);
+      await ${modelVar}_collection.updateOne({ _id: ${modelVar}._id }, { $set: { ${field}: ${val} } });
+    }`;
+    }
+  },
+  // --- Increment / Decrement ---
+  {
+    name: "increment",
+    pattern: /^increment\s+(\w+)\s+by\s+(\w+)/i,
+    generateCall: (m, ctx) => {
+      const field = m[1];
+      const amount = m[2];
+      const modelVar = toVar(ctx.modelName);
+      return `    // Step ${ctx.stepNum}: Increment ${field} by ${amount}
+    {
+      const ${modelVar}_collection = await getCollection(COLLECTION_NAME);
+      await ${modelVar}_collection.updateOne({ _id: ${modelVar}._id }, { $inc: { ${field}: ${amount} } });
+    }`;
+    }
+  },
+  {
+    name: "decrement",
+    pattern: /^decrement\s+(\w+)\s+by\s+(\w+)/i,
+    generateCall: (m, ctx) => {
+      const field = m[1];
+      const amount = m[2];
+      const modelVar = toVar(ctx.modelName);
+      return `    // Step ${ctx.stepNum}: Decrement ${field} by ${amount}
+    {
+      const ${modelVar}_collection = await getCollection(COLLECTION_NAME);
+      await ${modelVar}_collection.updateOne({ _id: ${modelVar}._id }, { $inc: { ${field}: -${amount} } });
+    }`;
+    }
+  },
+  // --- Send/Emit/Publish event ---
+  // Emits an eventBus.publish call. The payload references the controller's
+  // primary model variable IF it was declared by a prior matched step;
+  // otherwise the payload is just operation + timestamp (the event still
+  // fires, just without a record-level id).
+  {
+    name: "send-event",
+    pattern: /^(?:send|emit|publish)\s+(\w+)\s+event/i,
+    generateCall: (m, ctx) => {
+      const event = m[1];
+      const modelVar = toVar(ctx.modelName);
+      const hasModelVar = ctx.declaredVars?.has(modelVar);
+      const payload = hasModelVar ? `{ ${modelVar}Id: (${modelVar} as any)?._id, operation: '${ctx.operationName}', timestamp: new Date().toISOString() }` : `{ operation: '${ctx.operationName}', timestamp: new Date().toISOString() }`;
+      return `    // Step ${ctx.stepNum}: Emit ${event} event
+    await eventBus.publish('${event}', ${payload} as any);`;
+    }
+  },
+  // --- Call service ---
+  {
+    name: "call-service",
+    pattern: /^call\s+(\w+)\.(\w+)/i,
+    generateCall: (m, ctx) => {
+      const service = m[1];
+      const method = m[2];
+      const args = (ctx.parameterNames || []).join(", ");
+      return `    // Step ${ctx.stepNum}: Call ${service}.${method}
+    await (${toVar(service)} as any).${method}({ ${args} });`;
+    }
+  },
+  // --- Return ---
+  // Only matches when the returned value is a single declared identifier
+  // OR when the natural-language reference resolves to "the model" (e.g.
+  // "Return the user", "Return updated game"). Multi-word phrases like
+  // "Return state to caller" don't translate to valid JS, so they fall
+  // through to the unmatched-step path and emit a `// TODO:` line.
+  {
+    name: "return-model",
+    pattern: /^return\s+(?:the\s+|updated\s+|created\s+)?(\w+)\s*$/i,
+    generateCall: (m, ctx) => {
+      const valueRaw = m[1].trim();
+      const declared = ctx.declaredVars || /* @__PURE__ */ new Set();
+      const params = ctx.parameterNames || [];
+      const modelVar = toVar(ctx.modelName);
+      if (valueRaw.toLowerCase() === ctx.modelName.toLowerCase() || valueRaw === modelVar) {
+        return `    // Step ${ctx.stepNum}: Return ${ctx.modelName}
+    return ${modelVar};`;
+      }
+      if (declared.has(valueRaw)) {
+        return `    // Step ${ctx.stepNum}: Return ${valueRaw}
+    return ${valueRaw};`;
+      }
+      if (params.includes(valueRaw)) {
+        return `    // Step ${ctx.stepNum}: Return ${valueRaw}
+    return args.${valueRaw};`;
+      }
+      return `    // Step ${ctx.stepNum}: Return ${valueRaw} \u2014 TODO: resolve binding
+    return null;`;
+    }
+  }
+];
+function matchMongoStep(step, ctx) {
+  for (const convention of MONGO_STEP_CONVENTIONS) {
+    const m = step.match(convention.pattern);
+    if (m) {
+      const call = convention.generateCall(m, ctx);
+      if (call) {
+        return { matched: true, call };
+      }
+    }
+  }
+  const functionName = toMethod(step);
+  const declared = Array.from(ctx.declaredVars || []);
+  const paramNames = ctx.parameterNames || [];
+  const inputs = [...paramNames, ...declared];
+  const resultVar = ctx.resultName || `step${ctx.stepNum}Result`;
+  if (ctx.declaredVars) ctx.declaredVars.add(resultVar);
+  const inputObj = inputs.length > 0 ? `{ ${inputs.map((n) => paramNames.includes(n) ? `${n}: args.${n}` : n).join(", ")} }` : "{}";
+  return {
+    matched: false,
+    call: `    // Step ${ctx.stepNum}: ${step} [AI-generated \u2014 pure function]
+    const ${resultVar} = await aiBehaviors.${functionName}(${inputObj});`,
+    functionName,
+    inputs,
+    resultVar
+  };
+}
+export {
+  MONGO_STEP_CONVENTIONS,
+  matchMongoStep
+};