@specverse/engines 6.11.2 → 6.16.0

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

@@ -14,44 +14,123 @@
  * so step-emitted code compiles inline.
  */
 
-export interface MongoStepConvention {
-  name: string;
-  pattern: RegExp;
-  generateCall: (match: RegExpMatchArray, ctx: MongoStepContext) => string;
-}
+import {
+  toMethod,
+  toVar,
+  matchAgainstConventions,
+  type SharedConvention,
+  type SharedStepContext,
+} from '../_shared/step-matching.js';
+
+export type MongoStepConvention = SharedConvention<MongoStepContext>;
 
-export interface MongoStepContext {
-  /** The model the action lives on (e.g. 'Player' for PlayerController). */
-  modelName: string;
+export interface MongoStepContext extends SharedStepContext {
   /** 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;
+  /** The full model registry (name → ModelSpec) so conventions can read
+   * attributes for default values, types, and FK target collections. */
+  models?: Record<string, any>;
 }
 
-function toVar(name: string): string {
-  return name.charAt(0).toLowerCase() + name.slice(1);
+/**
+ * Compute sensible default values for a model's attributes — used by
+ * mechanical create/insertMany conventions to fill required fields the
+ * action's `args` doesn't supply.
+ *
+ * Defaults are derived from the spec's attribute declarations:
+ *   - `default=<value>` annotation → that value (literal or expression)
+ *   - `Integer required` with `min=N` → N
+ *   - `Integer required` no min → 0
+ *   - `String required` → '""' (empty)
+ *   - `Boolean required` → false
+ *   - `DateTime auto=now` or with `auto=now` → new Date().toISOString()
+ *   - Foreign keys (fields ending in `Id` matching another model) → resolved
+ *     from a declared variable of that type (e.g. `userId` ← `user._id`)
+ *   - Anything optional or already present in args → omitted
+ *
+ * Returns an array of `key: expression` strings ready to inline into an
+ * object-literal record body. Empty if the model isn't in the registry.
+ */
+export function deriveModelDefaults(
+  modelName: string,
+  ctx: MongoStepContext,
+): string[] {
+  if (!ctx.models) return [];
+  const model = ctx.models[modelName] || ctx.models[modelName.charAt(0).toUpperCase() + modelName.slice(1)];
+  if (!model) return [];
+  const attrs = model.attributes;
+  if (!attrs) return [];
+  const list = Array.isArray(attrs)
+    ? attrs.map((a: any) => [a.name, a])
+    : Object.entries(attrs);
+
+  const declaredVars = ctx.declaredVars || new Set();
+  const out: string[] = [];
+
+  // Names emitted explicitly by the convention's record-tail (createdAt /
+   // updatedAt) — skip in defaults to avoid TS1117 duplicate-property errors.
+  const conventionManaged = new Set(['createdAt', 'updatedAt', 'id']);
+  for (const [name, attr] of list as [string, any][]) {
+    if (!name) continue;
+    if (conventionManaged.has(name)) continue;
+    // Skip optional fields without explicit defaults
+    const required = !!attr.required;
+    const hasDefault = attr.default !== undefined;
+    if (!required && !hasDefault) continue;
+    // Skip if already supplied via spread args (caller overlays)
+    // — handled at convention call site by spreading args first.
+    if (hasDefault) {
+      out.push(`${name}: ${formatDefault(attr.default, attr.type)}`);
+      continue;
+    }
+    // Required field — derive a default from type
+    const type = (attr.type || 'String').toLowerCase();
+    if (type === 'integer' || type === 'int' || type === 'number' || type === 'float') {
+      const min = attr.min ?? 0;
+      out.push(`${name}: ${min}`);
+    } else if (type === 'boolean') {
+      out.push(`${name}: false`);
+    } else if (type === 'datetime' || type === 'date') {
+      if (attr.auto === 'now') {
+        out.push(`${name}: new Date().toISOString()`);
+      } else {
+        out.push(`${name}: new Date().toISOString()`);
+      }
+    } else {
+      // String / UUID / Text / etc. — try FK resolution first.
+      // Exclude self-reference (current model would FK-resolve to itself
+      // and emit a self-loop). The current model name's lowercase form
+      // is the conventionally-bound variable name.
+      const selfVar = modelName.charAt(0).toLowerCase() + modelName.slice(1);
+      const fkMatch = name.match(/^(.+)Id$/);
+      if (fkMatch && fkMatch[1] !== selfVar && declaredVars.has(fkMatch[1])) {
+        out.push(`${name}: (${fkMatch[1]} as any)?._id ?? (${fkMatch[1]} as any)?.id`);
+      } else {
+        out.push(`${name}: ''`);
+      }
+    }
+  }
+  return out;
 }
 
-function toCollection(modelName: string): string {
-  return modelName.toLowerCase() + 's';
+function formatDefault(value: any, type?: string): string {
+  if (value === null || value === undefined) return 'null';
+  if (typeof value === 'boolean') return String(value);
+  if (typeof value === 'number') return String(value);
+  if (typeof value === 'string') {
+    // Numeric defaults are sometimes parsed as strings
+    if (/^-?\d+(\.\d+)?$/.test(value)) return value;
+    if (value === 'true' || value === 'false') return value;
+    if (value === 'now' && (type === 'DateTime' || type === 'Date')) {
+      return 'new Date().toISOString()';
+    }
+    return JSON.stringify(value);
+  }
+  return JSON.stringify(value);
 }
 
-/** 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';
+function toCollection(modelName: string): string {
+  return modelName.toLowerCase() + 's';
 }
 
 /** Resolve a value reference in step text to a TS expression. */
@@ -76,6 +155,20 @@ function resolveValue(rawValue: string, ctx: MongoStepContext): string {
   return `'${value.replace(/'/g, "\\'")}'`;
 }
 
+/** Find the most-recent step{N}Result variable in declaredVars — used as
+ * the source for `Persist X` / `Save X` patterns where the previous step
+ * (an AI pure transform) computed the record to write. */
+function mostRecentStepResult(ctx: MongoStepContext): string | null {
+  const declared = Array.from(ctx.declaredVars || []);
+  const stepResults = declared.filter((v) => /^step\d+Result$/.test(v))
+    .sort((a, b) => parseInt(b.slice(4), 10) - parseInt(a.slice(4), 10));
+  return stepResults[0] ?? null;
+}
+
+function pascal(model: string): string {
+  return model.charAt(0).toUpperCase() + model.slice(1);
+}
+
 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"
@@ -98,9 +191,14 @@ export const MONGO_STEP_CONVENTIONS: MongoStepConvention[] = [
       }
       declared.add(modelVar);
       const failOnMissing = /or\s+fail/i.test(m[0]);
+      // Emit as `let` so subsequent conditional-create steps can reassign
+      // the variable when the lookup returned null.
+      // Also surface `id` (string) alongside `_id` (ObjectId) for AI-body
+      // compatibility — LLMs trained on prisma routinely check `.id`.
       return `    // Step ${ctx.stepNum}: Find ${model} by ${field}
     const ${modelVar}_collection = await getCollection('${collection}');
-    const ${modelVar} = await ${modelVar}_collection.findOne({ ${field}: ${idVal} });${failOnMissing ? `
+    let ${modelVar} = await ${modelVar}_collection.findOne({ ${field}: ${idVal} });
+    if (${modelVar} && !(${modelVar} as any).id && (${modelVar} as any)._id) (${modelVar} as any).id = String((${modelVar} as any)._id);${failOnMissing ? `
     if (!${modelVar}) throw new Error('${model} not found');` : ''}`;
     },
   },
@@ -121,9 +219,29 @@ export const MONGO_STEP_CONVENTIONS: MongoStepConvention[] = [
         return `    // Step ${ctx.stepNum}: Find ${model} by ${f1} and ${f2} (already loaded)`;
       }
       declared.add(modelVar);
+      // `let` for downstream conditional-create reassignment.
+      // Field-source resolution: a field like `userId` typically comes
+      // from a prior find/create (`user._id`), not from the action's
+      // request body. Check declaredVars first — if there's a model var
+      // matching the field's prefix (userId → user, gameId → game),
+      // use its `_id`. Otherwise fall back to args. Exclude the CURRENT
+      // model var (we're loading it now; it can't reference itself).
+      const resolveFieldSource = (f: string) => {
+        const stripIdMatch = f.match(/^(.+)Id$/);
+        if (stripIdMatch) {
+          const candidate = stripIdMatch[1];
+          if (candidate !== modelVar && declared.has(candidate)) {
+            return `(${candidate} as any)?._id ?? (${candidate} as any)?.id`;
+          }
+        }
+        return `args.${f}`;
+      };
+      const f1Src = resolveFieldSource(f1);
+      const f2Src = resolveFieldSource(f2);
       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} });`;
+    let ${modelVar} = await ${modelVar}_collection.findOne({ ${f1}: ${f1Src}, ${f2}: ${f2Src} });
+    if (${modelVar} && !(${modelVar} as any).id && (${modelVar} as any)._id) (${modelVar} as any).id = String((${modelVar} as any)._id);`;
     },
   },
 
@@ -290,6 +408,183 @@ export const MONGO_STEP_CONVENTIONS: MongoStepConvention[] = [
     },
   },
 
+  // ──────────────────────────────────────────────────────────────────
+  // SIDE-EFFECT CONVENTIONS — patterns that the generator handles
+  // mechanically. The LLM never sees these; persistence happens
+  // deterministically from the spec text.
+  // ──────────────────────────────────────────────────────────────────
+
+  // --- Persist / Save / Store {Model} record ---
+  // Matches: "Persist refresh token for revocation tracking",
+  //          "Save user record", "Store session"
+  // Source of the record: most-recent step{N}Result if any (typical case
+  // — the prior AI step computed what to persist), else `args`.
+  {
+    name: 'persist',
+    pattern: /^(?:persist|save|store)\s+(\w+(?:\s+\w+)?)(?:\s+(?:for|to|record).*)?$/i,
+    generateCall: (m, ctx) => {
+      // m[1] may be "refresh token" — collapse to camelCase + collection
+      const target = toVar(m[1].replace(/\s+(.)/g, (_, c) => c.toUpperCase()));
+      const collection = toCollection(target);
+      const recordSrc = mostRecentStepResult(ctx) ?? 'args';
+      return `    // Step ${ctx.stepNum}: Persist ${m[1]}
+    {
+      const _coll = await getCollection('${collection}');
+      await _coll.insertOne(${recordSrc} && typeof ${recordSrc} === 'object' && !Array.isArray(${recordSrc}) ? ${recordSrc} as any : { value: ${recordSrc} });
+    }`;
+    },
+  },
+
+  // --- Conditional create: "If X does not exist, create new X with ..." ---
+  // Reuses the model variable already declared by a prior find; mutates
+  // it to point at the newly-created record so subsequent steps see it.
+  {
+    name: 'conditional-create',
+    pattern: /^if\s+(\w+)\s+does\s+not\s+exist,?\s+create\s+new\s+(\w+)(?:\s+with\s+.+)?$/i,
+    generateCall: (m, ctx) => {
+      const modelVar = toVar(m[1]);
+      const Model = pascal(m[2]);
+      const collection = toCollection(Model);
+      if (!ctx.declaredVars?.has(modelVar)) return '';  // need prior find
+      // Reassigns the original `let ${modelVar}` declared by find — so
+      // subsequent steps (AI or convention) see the newly-created record
+      // when the lookup originally returned null. Defaults come from the
+      // model spec (#43K-A): required fields not present in args get
+      // their type-default (level: 1, totalResources: '', etc.).
+      const defaults = deriveModelDefaults(Model, ctx);
+      const defaultsBlock = defaults.length > 0 ? defaults.join(', ') + ',' : '';
+      return `    // Step ${ctx.stepNum}: If ${modelVar} does not exist, create new ${Model}
+    if (!${modelVar}) {
+      const _newRecord = { ${defaultsBlock} ...args, createdAt: new Date().toISOString(), updatedAt: new Date().toISOString() };
+      const _ins = await (await getCollection('${collection}')).insertOne(_newRecord);
+      ${modelVar} = { _id: _ins.insertedId, id: String(_ins.insertedId), ..._newRecord } as any;
+    } else if (${modelVar} && !(${modelVar} as any).id && (${modelVar} as any)._id) {
+      (${modelVar} as any).id = String((${modelVar} as any)._id);
+    }`;
+    },
+  },
+
+  // --- Conditional update: "If X exists, update Y" ---
+  // Updates a single field on the previously-loaded record. Field defaults
+  // to lastLoginAt-style timestamp when the step says "update Y" without
+  // a "to <value>" clause.
+  {
+    name: 'conditional-update',
+    pattern: /^if\s+(\w+)\s+exists,?\s+update\s+(\w+)(?:\s+(.+))?$/i,
+    generateCall: (m, ctx) => {
+      const modelVar = toVar(m[1]);
+      const field = m[2];
+      const collection = toCollection(m[1]);
+      if (!ctx.declaredVars?.has(modelVar)) return '';
+      return `    // Step ${ctx.stepNum}: If ${modelVar} exists, update ${field}
+    if (${modelVar}) {
+      await (await getCollection('${collection}')).updateOne(
+        { _id: ${modelVar}._id },
+        { $set: { ${field}: new Date().toISOString() } }
+      );
+    }`;
+    },
+  },
+
+  // --- Auto-create / Bulk fan-out create ---
+  // Matches: "Auto-create player profiles for all available games"
+  //          "Create X records for all Y"
+  // Pure-mechanical: enumerate the source collection, build a record per
+  // item linking it to the most-recently-loaded model var (typically
+  // `user`), insertMany. No AI hop — domain-specific field defaults are
+  // limited to the link fields (userId, gameId) plus createdAt/updatedAt.
+  // Anything richer should be done in a follow-up step (e.g. "Set displayName...").
+  {
+    name: 'auto-create-loop',
+    pattern: /^(?:auto-create|bulk\s+create)\s+(\w+)\s+(?:profile|record|entry|entries)?s?\s+for\s+(?:all\s+)?(?:available\s+)?(\w+)$/i,
+    generateCall: (m, ctx) => {
+      const Model = pascal(m[1]);
+      const targetCollection = toCollection(Model);
+      const sourceCollection = m[2].toLowerCase();
+      // Identify the "owner" var. Owner is the FIRST-declared non-stepResult
+      // var (e.g. `user`); spec authors load the owner before enumerating
+      // sources of its children.
+      const declared = Array.from(ctx.declaredVars || []);
+      const ownerVar = declared.find((v) => !/^step\d+Result$/.test(v) && v !== 'args');
+      const sourceSingular = sourceCollection.replace(/s$/, '');
+      const linkField = sourceSingular + 'Id';
+      const ownerLinkField = ownerVar ? ownerVar + 'Id' : 'ownerId';
+
+      // Pull required-field defaults from the target model spec (#43K-A).
+      // Conventions can now read model attributes via ctx.models, so a
+      // Player record gets `level: 1, experience: 0, totalResources: '""'`
+      // automatically — no AI hop, no missing-required-field errors.
+      const modelDefaults = deriveModelDefaults(Model, ctx);
+      const defaultsBlock = modelDefaults.length > 0
+        ? modelDefaults.filter((d) => !d.startsWith(`${ownerLinkField}:`) && !d.startsWith(`${linkField}:`)).join(', ')
+        : '';
+
+      return `    // Step ${ctx.stepNum}: Auto-create ${m[1]} ${m[2]} for all ${m[2]}
+    {
+      const _allItems = await (await getCollection('${sourceCollection}')).find({}).toArray();
+      const _ownerId = ${ownerVar ? `(${ownerVar} as any)?.id ?? (${ownerVar} as any)?._id` : 'null'};
+      const _records = _allItems.map((_item: any) => ({
+        ${defaultsBlock ? defaultsBlock + ',' : ''}
+        ${ownerLinkField}: _ownerId,
+        ${linkField}: (_item as any).${sourceSingular}Id ?? (_item as any).id ?? String((_item as any)._id),
+        createdAt: new Date().toISOString(),
+        updatedAt: new Date().toISOString(),
+      }));
+      if (_records.length > 0) {
+        await (await getCollection('${targetCollection}')).insertMany(_records as any);
+      }
+    }`;
+    },
+  },
+
+  // --- "Otherwise create new X record" — pairs with prior conditional ---
+  // Emitted as an `else` branch attached to the conditional that came
+  // before. We don't enforce ordering at the convention level; if the
+  // author writes "Otherwise" without a prior "If ... does not exist,
+  // create" the emitted else lands without an if and tsc catches it.
+  {
+    name: 'otherwise-create',
+    pattern: /^otherwise\s+create\s+(?:new\s+)?(\w+)\s+record$/i,
+    generateCall: (m, ctx) => {
+      const Model = pascal(m[1]);
+      const modelVar = toVar(Model);
+      const collection = toCollection(Model);
+      // The model var was declared (as `let`) by the find that paired
+      // with the prior conditional-update; reassign it here so downstream
+      // steps see the new record.
+      const wasDeclared = ctx.declaredVars?.has(modelVar);
+      const declared = Array.from(ctx.declaredVars || []);
+      // Model-driven defaults from the spec — these may include FK fields
+      // (userId, gameId) that we'd ALSO derive from declaredVars below.
+      const defaults = deriveModelDefaults(Model, ctx);
+      // Track names already supplied by defaults so we don't double-emit.
+      const supplied = new Set<string>();
+      for (const entry of defaults) {
+        const colonIdx = entry.indexOf(':');
+        if (colonIdx > 0) supplied.add(entry.slice(0, colonIdx).trim());
+      }
+      // FK assignments from prior-declared model vars — only emit those
+      // not already provided by spec defaults (avoids TS1117 dup-keys).
+      const fkAssignments = declared
+        .filter((v) => v !== modelVar && !/^step\d+Result$/.test(v) && v !== 'args')
+        .filter((v) => !supplied.has(v + 'Id'))
+        .map((v) => {
+          supplied.add(v + 'Id');
+          return `${v}Id: (${v} as any)?._id ?? (${v} as any)?.id`;
+        })
+        .join(', ');
+      const defaultsBlock = defaults.length > 0 ? defaults.join(', ') + ',' : '';
+      ctx.declaredVars?.add(modelVar);
+      return `    // Step ${ctx.stepNum}: Otherwise create new ${Model} record
+    else {
+      const _newRecord = { ${defaultsBlock} ${fkAssignments ? fkAssignments + ',' : ''} ...args, createdAt: new Date().toISOString(), updatedAt: new Date().toISOString() };
+      const _ins = await (await getCollection('${collection}')).insertOne(_newRecord);
+      ${wasDeclared ? `${modelVar} = { _id: _ins.insertedId, id: String(_ins.insertedId), ..._newRecord } as any;` : `const ${modelVar} = { _id: _ins.insertedId, id: String(_ins.insertedId), ..._newRecord };
+      void ${modelVar};`}
+    }`;
+    },
+  },
+
   // --- 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;
@@ -383,41 +678,14 @@ export function matchMongoStep(
   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,
-  };
+  // Mongo's AI-fallback uses `args.X` for parameter inputs because the
+  // mongo-native controller-generator wraps the action body with a single
+  // `args` parameter (e.g. `register(args)`) and indexes through it
+  // rather than destructuring at function entry. Declared variables stay
+  // bare (they were declared inside the body by previous steps).
+  const aiArgsExpr = (inputs: string[], paramNames: string[]) =>
+    inputs.length > 0
+      ? `{ ${inputs.map((n) => paramNames.includes(n) ? `${n}: args.${n}` : n).join(', ')} }`
+      : '{}';
+  return matchAgainstConventions(step, ctx, MONGO_STEP_CONVENTIONS, aiArgsExpr);
 }

package/libs/instance-factories/services/templates/postgres-native/__tests__/controller-generator.test.ts

@@ -0,0 +1,193 @@
+/**
+ * Regression tests for the PostgreSQL native (pg) controller generator.
+ *
+ * Mirrors the mongodb-native suite — the conventions are intentionally
+ * the same shape so spec authors can swap factories without rewriting
+ * .specly text. These tests pin shape, not full compilation:
+ *
+ *   - CURVED ops emit pg helper calls (insertOne / findOneByField /
+ *     updateOneById / deleteOneById / findAll / query)
+ *   - Lifecycle transitions decode flow shorthand and emit a transition map
+ *   - Behaviour-derived actions colliding with CRUD names emit a warning
+ *     and are dropped (shared with mongo)
+ *   - Custom action steps run through `matchPgStep` (CRUD-shape steps
+ *     map to inline helper calls, the rest delegate to aiBehaviors)
+ */
+import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest';
+import generatePgNativeController from '../controller-generator.js';
+
+const baseModel = {
+  name: 'Todo',
+  attributes: {
+    id: { name: 'id', type: 'UUID', required: true, auto: 'uuid4' },
+    title: { name: 'title', type: 'String', required: true },
+    completed: { name: 'completed', type: 'Boolean', default: false },
+  },
+};
+
+const baseController = {
+  name: 'TodoController',
+  description: 'Controller for Todo',
+  cured: { create: true, retrieve: true, update: true, evolve: true, delete: true },
+};
+
+describe('Postgres native — controller-generator', () => {
+  it('emits all CURVED ops via pgClient helpers', () => {
+    const out = generatePgNativeController({
+      controller: baseController,
+      model: baseModel,
+    } as any);
+    expect(out).toContain(`TABLE_NAME = 'todos'`);
+    expect(out).toContain('insertOne');
+    expect(out).toContain('findOneByField');
+    expect(out).toContain('updateOneById');
+    expect(out).toContain('deleteOneById');
+    expect(out).toContain('findAll');
+    expect(out).not.toContain('PrismaClient');
+    expect(out).not.toContain('prisma.');
+    expect(out).not.toContain('getCollection');
+  });
+
+  it('does NOT import ObjectId — pg uses string ids end-to-end', () => {
+    const out = generatePgNativeController({
+      controller: baseController,
+      model: baseModel,
+    } as any);
+    expect(out).not.toContain('ObjectId');
+    expect(out).not.toContain('mongodb');
+  });
+
+  it('emits lifecycle transition map for `flow:` shorthand', () => {
+    const out = generatePgNativeController({
+      controller: baseController,
+      model: {
+        ...baseModel,
+        lifecycles: { status: { name: 'status', flow: 'pending -> done' } },
+      },
+    } as any);
+    expect(out).toContain('public async evolve(');
+    expect(out).toContain('"pending":["done"]');
+    expect(out).toContain('Invalid transition');
+  });
+
+  it('emits a working multi-state transition map for explicit states', () => {
+    const out = generatePgNativeController({
+      controller: baseController,
+      model: {
+        ...baseModel,
+        lifecycles: {
+          status: {
+            name: 'status',
+            states: ['draft', 'open', 'closed'],
+            transitions: { open: 'draft -> open', close: 'open -> closed' },
+          },
+        },
+      },
+    } as any);
+    expect(out).toContain('"draft":["open"]');
+    expect(out).toContain('"open":["closed"]');
+  });
+
+  it('uses model.storage.table override when present', () => {
+    const out = generatePgNativeController({
+      controller: baseController,
+      model: { ...baseModel, storage: { table: 'custom_todos' } },
+    } as any);
+    expect(out).toContain(`TABLE_NAME = 'custom_todos'`);
+    expect(out).toContain('TABLE_NAME');
+  });
+
+  it('omits CURVED ops not declared on the controller', () => {
+    const out = generatePgNativeController({
+      controller: { ...baseController, cured: { retrieve: true } },
+      model: baseModel,
+    } as any);
+    expect(out).toContain('public async retrieve(');
+    expect(out).not.toContain('public async create(');
+    expect(out).not.toContain('public async update(');
+    expect(out).not.toContain('public async delete(');
+    expect(out).not.toContain('public async evolve(');
+  });
+
+  describe('behaviour-derived actions', () => {
+    let warnSpy: ReturnType<typeof vi.spyOn>;
+    beforeEach(() => {
+      warnSpy = vi.spyOn(console, 'warn').mockImplementation(() => {});
+    });
+    afterEach(() => {
+      warnSpy.mockRestore();
+    });
+
+    it('warns + drops behaviour-derived actions colliding with CRUD names', () => {
+      const out = generatePgNativeController({
+        controller: {
+          ...baseController,
+          actions: {
+            delete: {
+              description: 'Soft-delete a todo',
+              parameters: { id: 'String' },
+              steps: ['Set deletedAt to now'],
+            },
+          },
+        },
+        model: baseModel,
+      } as any);
+      // The custom delete should NOT be emitted (collides with CRUD delete).
+      // Generator emits exactly one `public async delete(` (the CRUD op).
+      const deleteMatches = out.match(/public async delete\(/g) || [];
+      expect(deleteMatches.length).toBe(1);
+      expect(warnSpy).toHaveBeenCalledTimes(1);
+      const warnMsg = String(warnSpy.mock.calls[0]?.[0] ?? '');
+      expect(warnMsg).toContain('TodoController.delete');
+      expect(warnMsg).toContain('collides');
+    });
+
+    it('runs steps through matchPgStep — CRUD-shape steps inline pg helpers', () => {
+      const out = generatePgNativeController({
+        controller: {
+          ...baseController,
+          actions: {
+            archive: {
+              description: 'Archive a todo by id',
+              parameters: { id: 'String' },
+              steps: [
+                'Find Todo by id or fail with 404',
+                'Update Todo completed to true',
+                'Emit TodoArchived event',
+              ],
+            },
+          },
+        },
+        model: baseModel,
+      } as any);
+      expect(out).toContain('public async archive(');
+      // Step 1: find-by-field convention
+      expect(out).toContain(`findOneByField('todos', 'id', args.id)`);
+      // Step 2: update-field convention
+      expect(out).toContain(`updateOneById('todos', todo.id, { completed: true })`);
+      // Step 3: send-event convention
+      expect(out).toContain(`eventBus.publish('TodoArchived'`);
+    });
+
+    it('falls back to AI-behaviors for unmatched steps', () => {
+      const out = generatePgNativeController({
+        controller: {
+          ...baseController,
+          actions: {
+            score: {
+              description: 'Compute a todo priority score',
+              parameters: { id: 'String' },
+              steps: [
+                'Compute priority score from urgency and effort',
+                'Return score',
+              ],
+            },
+          },
+        },
+        model: baseModel,
+      } as any);
+      expect(out).toContain(`aiBehaviors.computePriorityScoreFromUrgencyAndEffort`);
+      expect(out).toContain(`from '../behaviors/TodoController.ai.js'`);
+    });
+  });
+});