@specverse/engines 6.7.8 → 6.11.2

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

@@ -56,6 +56,7 @@ export default function generateMongoNativeController(context: TemplateContext):
 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/${controllerName}.ai.js';` : ''}
 
 const COLLECTION_NAME = '${collection}';
 
@@ -275,29 +276,86 @@ function generateDeleteMethod(modelName: string, modelVar: string, collection: s
 
 interface CustomActionsResult {
   code: string;
+  needsAiBehaviors: boolean;
 }
 
 /**
- * Custom actions emit TODO stubs that throw "not implemented".
+ * Custom actions emit a per-step body using `matchMongoStep`. The same
+ * matcher is passed to the AI-behaviors-generator (via realize/index.ts)
+ * so both sides accumulate the same `declaredVars` set and produce
+ * matching function names + inputs for unmatched steps.
  *
- * Why not delegate to `aiBehaviors.<actionName>`? Because the AI-behaviors
- * generator only emits functions for STEPS that didn't match a convention
- * pattern — not for actions themselves. So `aiBehaviors.rotate` would not
- * exist even when an action named `rotate` is declared on the controller.
- *
- * Real implementation of action bodies is deferred to the MongoDB-native
- * step-conventions library (#43F follow-up — mirror Prisma's
- * step-conventions.ts but emit native-driver collection calls).
+ * Per step:
+ *   - matched → emit conventional native-driver code inline
+ *   - unmatched → emit `const stepNResult = await aiBehaviors.<funcName>({...});`
+ *     (the aiBehaviors function comes from the controller's `*.ai.ts`
+ *     file, generated by AI-behaviors-generator using the SAME matcher).
  */
+import { matchMongoStep, type MongoStepContext } from './step-conventions.js';
+
 function generateCustomActions(controller: any): CustomActionsResult {
   if (!controller.actions || Object.keys(controller.actions).length === 0) {
-    return { code: '' };
+    return { code: '', needsAiBehaviors: false };
   }
+  const CRUD_NAMES = new Set(['create', 'retrieve', 'retrieveAll', 'update', 'evolve', 'delete', 'validate']);
+  const modelName = controller.model || (controller.name || '').replace(/Controller$/, '') || 'Model';
+  const collectionName = modelName.toLowerCase() + 's';
   const out: string[] = [];
+  let needsAiBehaviors = false;
   for (const [actionName, action] of Object.entries<any>(controller.actions)) {
-    const stepsHeader = (action.steps && action.steps.length > 0)
-      ? action.steps.map((s: any) => `   *   - ${typeof s === 'string' ? s : (s.action || JSON.stringify(s))}`).join('\n')
+    if (CRUD_NAMES.has(actionName)) continue;
+    const steps: any[] = Array.isArray(action.steps) ? action.steps : [];
+    const stepsHeader = steps.length > 0
+      ? steps.map((s: any) => `   *   - ${typeof s === 'string' ? s : (s.action || JSON.stringify(s))}`).join('\n')
       : '   *   (no spec steps declared)';
+
+    const declaredVars = new Set<string>();
+    const stepBodies: string[] = [];
+    let usesArgs = false;
+    let actionRefersToAi = false;
+    steps.forEach((rawStep: any, i: number) => {
+      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: MongoStepContext = {
+        modelName,
+        collectionName,
+        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');
+    // Drop the `const stepNResult =` declaration when no later step
+    // references the result. Strict tsc's noUnusedLocals applies to
+    // locals regardless of underscore prefix, so the only safe fix is
+    // to omit the assignment entirely. The await still fires.
+    const stepResultRe = /const\s+(step\d+Result)\s*=/g;
+    let mres: RegExpExecArray | null;
+    const declared: string[] = [];
+    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) {
+        // Only the declaration itself — drop the binding, keep the await.
+        combined = combined.replace(new RegExp(`const\\s+${name}\\s*=\\s*`), '');
+      }
+    }
+    const body = steps.length > 0
+      ? combined + `\n    return { success: true };`
+      : `    throw new Error('${controller.name || 'Controller'}.${actionName} is not implemented');`;
+
     out.push(`
   /**
    * ${actionName}
@@ -306,14 +364,10 @@ function generateCustomActions(controller: any): CustomActionsResult {
    * Spec steps:
 ${stepsHeader}
    */
-  public async ${actionName}(_args: any = {}): Promise<any> {
-    // TODO (#43F): translate spec steps into native MongoDB driver calls
-    // via a mongodb-native step-conventions library (mirror of the prisma
-    // one). For now this is a stub so realize completes and the action
-    // surface is callable for parity tests.
-    throw new Error('${controller.name}.${actionName} is not implemented');
+  public async ${actionName}(${argsParam}): Promise<any> {
+${body}
   }
 `);
   }
-  return { code: out.join('\n') };
+  return { code: out.join('\n'), needsAiBehaviors };
 }

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

@@ -0,0 +1,423 @@
+/**
+ * Step Conventions for MongoDB native driver — mirrors the prisma library's
+ * pattern set but emits native-driver collection code instead of `prisma.X`.
+ *
+ * Each convention maps a natural-language step pattern to a generated code
+ * block. Patterns are tried in order; first match wins. Unmatched steps
+ * fall through to the AI-behaviors layer (a separate concern).
+ *
+ * The emitted code assumes the controller's surrounding scope provides:
+ *   - `getCollection(name)` (from `../db/mongoClient.js`)
+ *   - `byId(id)` filter helper for `_id`-shaped queries
+ *   - `eventBus` for `publish`
+ * These are imported by the mongo-native controller-generator regardless,
+ * so step-emitted code compiles inline.
+ */
+
+export interface MongoStepConvention {
+  name: string;
+  pattern: RegExp;
+  generateCall: (match: RegExpMatchArray, ctx: MongoStepContext) => string;
+}
+
+export interface MongoStepContext {
+  /** The model the action lives on (e.g. 'Player' for PlayerController). */
+  modelName: string;
+  /** Collection name for the model (lowercased + 's' or storage.collection). */
+  collectionName: string;
+  serviceName: string;
+  operationName: string;
+  stepNum: number;
+  /** Parameter names from the action (so we know what's in `args`). */
+  parameterNames?: string[];
+  /** Variables already declared (to avoid redeclaration). */
+  declaredVars?: Set<string>;
+  /** Named result variable from spec's `as:` clause. */
+  resultName?: string;
+}
+
+function toVar(name: string): string {
+  return name.charAt(0).toLowerCase() + name.slice(1);
+}
+
+function toCollection(modelName: string): string {
+  return modelName.toLowerCase() + 's';
+}
+
+/** Camel-case a step's text into a TS identifier. Identical algorithm to
+ * prisma's step-conventions `toMethod` so AI-behavior function names align
+ * across the orm-agnostic generator. */
+function toMethod(words: string): string {
+  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';
+}
+
+/** Resolve a value reference in step text to a TS expression. */
+function resolveValue(rawValue: string, ctx: MongoStepContext): string {
+  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 || 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}`;
+  }
+
+  // Fallback: quoted string literal so generated code stays valid TS
+  if (/\s/.test(value)) return `/* TODO: resolve "${value}" */ null`;
+  return `'${value.replace(/'/g, "\\'")}'`;
+}
+
+export const MONGO_STEP_CONVENTIONS: MongoStepConvention[] = [
+  // --- 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 || 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 || 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 || 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 '';  // signal "not really matched"
+      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 || new Set();
+      const params = ctx.parameterNames || [];
+      const modelVar = toVar(ctx.modelName);
+      // Resolve to a declared variable, parameter, or the controller's
+      // primary model variable. Anything else doesn't have a JS expression
+      // — fall through (return unmatched so the TODO path fires).
+      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};`;
+      }
+      // Unresolvable — emit a TODO comment + neutral return so generated
+      // code still compiles. Caller can replace.
+      return `    // Step ${ctx.stepNum}: Return ${valueRaw} — TODO: resolve binding
+    return null;`;
+    },
+  },
+];
+
+/**
+ * Match a step against the mongo-native conventions.
+ *
+ * Matched: returns the inline native-driver code to emit AND advances the
+ * convention's bookkeeping (e.g. find/create add the model variable to
+ * declaredVars).
+ *
+ * Unmatched: returns the function name + inputs + resultVar that an
+ * AI-behaviors layer should produce for this step. The shape mirrors
+ * prisma's step-conventions matchStep so the orm-agnostic
+ * AI-behaviors-generator can drive either side without branching.
+ */
+export function matchMongoStep(
+  step: string,
+  ctx: MongoStepContext,
+): {
+  matched: boolean;
+  call: string;
+  helperMethod?: string;
+  functionName?: string;
+  inputs?: string[];
+  resultVar?: string;
+} {
+  for (const convention of MONGO_STEP_CONVENTIONS) {
+    const m = step.match(convention.pattern);
+    if (m) {
+      const call = convention.generateCall(m, ctx);
+      // A convention may signal "regex matched but I can't safely emit"
+      // by returning the empty string (e.g. update-field needs the model
+      // to be declared by a prior find; if it isn't, fall through to AI).
+      if (call) {
+        return { matched: true, call };
+      }
+    }
+  }
+
+  // Unmatched — caller is expected to delegate to an AI-generated pure
+  // function in `behaviors/<Owner>.ai.ts`. Inputs = action parameters +
+  // any variables already declared by prior matched conventions; this
+  // matches what the AI-behaviors-generator will produce for the same
+  // step (it walks the same conventions in the same order, so its
+  // declaredVars set agrees with ours by construction).
+  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 — pure function]
+    const ${resultVar} = await aiBehaviors.${functionName}(${inputObj});`,
+    functionName,
+    inputs,
+    resultVar,
+  };
+}

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

@@ -173,10 +173,33 @@ function cacheWrite(key: string, body: string): void {
  *
  * This is async — it calls the AI engine to generate function bodies.
  */
-export default async function generateAiBehaviors(context: TemplateContext): Promise<string> {
+/** Optional matcher for orm-agnostic step matching. When present, this is
+ * used in place of the prisma library's `matchStep` so that the unmatched
+ * functions' names + inputs are computed by the same conventions library
+ * the consuming controller is using. Without this, mongo-native (or any
+ * non-prisma) controllers would diverge: they'd emit `aiBehaviors.X` calls
+ * with one inputs set while this generator would emit a function with a
+ * different signature. */
+type StepMatcher = (step: string, ctx: any) => {
+  matched: boolean;
+  call?: string;
+  helperMethod?: string;
+  functionName?: string;
+  inputs?: string[];
+  resultVar?: string;
+};
+
+export default async function generateAiBehaviors(
+  context: TemplateContext,
+  matcher?: StepMatcher,
+): Promise<string> {
   const { controller, model } = context;
   if (!controller?.actions) return '';
 
+  // Default matcher = prisma's matchStep for back-compat. Mongo-native
+  // (and any future ORM) passes its own matcher.
+  const stepMatcher: StepMatcher = matcher || (matchStep as any);
+
   const modelName = model?.name || controller.model || 'Model';
   const modelVar = modelName.charAt(0).toLowerCase() + modelName.slice(1);
   // List of all entity-model names available in the realized output. Forwarded
@@ -234,7 +257,7 @@ export default async function generateAiBehaviors(context: TemplateContext): Pro
         resultName: stepAs,
       };
 
-      const result = matchStep(stepText, ctx);
+      const result = stepMatcher(stepText, ctx);
       if (!result.matched && result.functionName) {
         // Avoid duplicate function definitions
         const existing = unmatchedFunctions.find(f => f.functionName === result.functionName);
@@ -322,13 +345,44 @@ export async function generateAiBehaviorsFile(opts: {
     /** Strip string/template/comment content so identifier-reference checks
      * don't match `reward` inside a kebab-case string like `'reward-not-granted'`
      * or `// reward stays as text`. We replace the literal contents with
-     * spaces so positions stay roughly aligned in case of debugging. */
+     * spaces so positions stay roughly aligned in case of debugging.
+     *
+     * Critical: template-string `${...}` interpolations are EXPRESSIONS, not
+     * literal text — they really do reference `input.X` etc. Strip only the
+     * non-interpolation segments of the template so the expression content
+     * survives the regex check. */
     const stripLiteralsAndComments = (src: string): string => {
-      return src
+      let out = src
         .replace(/\/\*[\s\S]*?\*\//g, (m) => ' '.repeat(m.length))
         .replace(/\/\/[^\n]*/g, (m) => ' '.repeat(m.length))
-        .replace(/(['"])(?:\\.|(?!\1).)*\1/g, (m) => m[0] + ' '.repeat(m.length - 2) + m[0])
-        .replace(/`(?:\\.|\$\{[^}]*\}|(?!`).)*`/g, (m) => '`' + ' '.repeat(m.length - 2) + '`');
+        .replace(/(['"])(?:\\.|(?!\1).)*\1/g, (m) => m[0] + ' '.repeat(m.length - 2) + m[0]);
+      // Strip text INSIDE backticks but preserve `${...}` expressions.
+      // We rebuild template contents by replacing literal-text spans
+      // (everything between `\`` and `${`, between `}` and `${`, or
+      // between `}` and the closing `\``) with spaces.
+      out = out.replace(/`((?:\\.|\$\{[^}]*\}|(?!`).)*)`/g, (full, content) => {
+        // Walk the content, copy `${...}` segments verbatim, replace other
+        // characters with spaces.
+        let result = '`';
+        let i = 0;
+        while (i < content.length) {
+          if (content[i] === '\\' && i + 1 < content.length) {
+            result += '  '; i += 2; continue;
+          }
+          if (content[i] === '$' && content[i + 1] === '{') {
+            // copy interpolation verbatim including the `${...}` markers
+            const end = content.indexOf('}', i);
+            const slice = end >= 0 ? content.slice(i, end + 1) : content.slice(i);
+            result += slice;
+            i += slice.length;
+            continue;
+          }
+          result += ' ';
+          i++;
+        }
+        return result + '`';
+      });
+      return out;
     };
 
     /** Detect whether the body manages its own input access (so adding our

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@specverse/engines",
-  "version": "6.7.8",
+  "version": "6.11.2",
   "description": "SpecVerse toolchain — parser, inference, realize, generators, AI, registry, bundles",
   "type": "module",
   "main": "dist/index.js",
@@ -62,7 +62,8 @@
     "@ai-sdk/openai-compatible": "^2.0.41",
     "@ai-sdk/provider": "^3.0.8",
     "@specverse/assets": "^1.6.0",
-    "@specverse/entities": "^5.1.0",
+    "@specverse/engines": "^6.8.7",
+    "@specverse/entities": "^5.2.2",
     "@specverse/runtime": "^5.0.1",
     "@specverse/types": "^5.1.0",
     "ai": "^6.0.168",