@specverse/engines 6.39.3 → 6.41.0

package/libs/instance-factories/services/templates/prisma/__tests__/step-conventions-return.test.ts

@@ -0,0 +1,124 @@
+/**
+ * Step-conventions — `return` pattern safety tests.
+ *
+ * The 2026-05-11 per-owner trial surfaced a defect: when a spec step
+ * like `Return logout confirmation` matched the `^return\s+(.+)/i`
+ * pattern, the convention emitted `return logout confirmation;` —
+ * two bare identifiers after `return`, a parse error. Per-action
+ * passed this through because each body parsed in isolation only
+ * checked the wrapping body, not the surrounding file. Per-owner
+ * caught it because the whole-file parse check failed. Either way,
+ * runtime would have broken.
+ *
+ * Fix: the convention now ONLY emits when the value is a single
+ * bareword identifier (or simple property accessor) AND was
+ * previously declared in the action's emitted body. Otherwise
+ * returns the empty string so the matcher falls through to the AI
+ * fallback (LLM authors the return).
+ */
+
+import { describe, it, expect } from 'vitest';
+import { STEP_CONVENTIONS } from '../step-conventions.js';
+import type { StepContext } from '../step-conventions.js';
+
+function findReturnConvention() {
+  const c = STEP_CONVENTIONS.find((x) => x.name === 'return');
+  expect(c).toBeDefined();
+  return c!;
+}
+
+function makeCtx(overrides: Partial<StepContext> = {}): StepContext {
+  return {
+    modelName: 'Order',
+    serviceName: 'OrderService',
+    operationName: 'createOrder',
+    stepNum: 7,
+    parameterNames: [],
+    declaredVars: new Set<string>(),
+    ...overrides,
+  } as any;
+}
+
+describe("prisma step-convention `return` — only emits parseable TS", () => {
+  it("emits the model var for `Return updated order` (model-pattern matches)", () => {
+    const convention = findReturnConvention();
+    const m = 'Return updated order'.match(convention.pattern)!;
+    const call = convention.generateCall(m, makeCtx());
+    expect(call).toContain('return order;');
+  });
+
+  it("emits `return <name>;` when the value is a single identifier already declared", () => {
+    const convention = findReturnConvention();
+    const m = 'Return user'.match(convention.pattern)!;
+    const ctx = makeCtx({ declaredVars: new Set(['user']) });
+    const call = convention.generateCall(m, ctx);
+    expect(call).toContain('return user;');
+  });
+
+  it("emits `return <obj>.<prop>;` for a simple property accessor when head is declared", () => {
+    const convention = findReturnConvention();
+    const m = 'Return result.payload'.match(convention.pattern)!;
+    const ctx = makeCtx({ declaredVars: new Set(['result']) });
+    const call = convention.generateCall(m, ctx);
+    expect(call).toContain('return result.payload;');
+  });
+
+  it("REGRESSION: prose phrase 'logout confirmation' returns empty (bounces to LLM)", () => {
+    // Pre-fix this emitted `return logout confirmation;` — two bare
+    // identifiers, parse error. New behaviour: empty string → matcher
+    // treats as no match → AI fallback path.
+    const convention = findReturnConvention();
+    const m = 'Return logout confirmation'.match(convention.pattern)!;
+    const call = convention.generateCall(m, makeCtx());
+    expect(call).toBe('');
+  });
+
+  it("REGRESSION: '204 No Content' returns empty (number + identifiers is a parse error)", () => {
+    const convention = findReturnConvention();
+    const m = 'Return 204 No Content'.match(convention.pattern)!;
+    const call = convention.generateCall(m, makeCtx());
+    expect(call).toBe('');
+  });
+
+  it("REGRESSION: a PascalCase type name that was NEVER declared returns empty", () => {
+    // `return AuthRegisterResponse;` looks like valid TS but references
+    // a type as a value — won't resolve at runtime. Only emit when the
+    // identifier was actually declared in the body.
+    const convention = findReturnConvention();
+    const m = 'Return AuthRegisterResponse'.match(convention.pattern)!;
+    const call = convention.generateCall(m, makeCtx()); // declaredVars empty
+    expect(call).toBe('');
+  });
+
+  it("when the identifier IS declared, it WILL emit (the LLM put the value in scope)", () => {
+    const convention = findReturnConvention();
+    const m = 'Return AuthRegisterResponse'.match(convention.pattern)!;
+    const ctx = makeCtx({ declaredVars: new Set(['AuthRegisterResponse']) });
+    const call = convention.generateCall(m, ctx);
+    expect(call).toContain('return AuthRegisterResponse;');
+  });
+
+  it("falls back for whitespace-y multi-word values that aren't valid identifiers", () => {
+    const convention = findReturnConvention();
+    const m = 'Return the cached invoice if still fresh'.match(convention.pattern)!;
+    const call = convention.generateCall(m, makeCtx());
+    // "the cached invoice..." DOES start with "the" so model-pattern
+    // applies — emits the model var. That's the existing behaviour
+    // and intentional.
+    expect(call).toContain('return order;');
+  });
+
+  it("regression: empty result string causes the matcher to fall through", async () => {
+    // Smoke-test the integration: import the shared matcher and feed
+    // it a prose 'Return X' step. Expect matched: false (AI fallback).
+    const { matchAgainstConventions } = await import('../../_shared/step-matching.js');
+    const ctx = makeCtx();
+    const result = matchAgainstConventions(
+      'Return logout confirmation',
+      ctx,
+      STEP_CONVENTIONS as any,
+      (inputs: string[]) => (inputs.length > 0 ? `{ ${inputs.join(', ')} }` : '{}'),
+    );
+    expect(result.matched).toBe(false);
+  });
+});

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

@@ -377,24 +377,69 @@ function generateCustomActions(controller: any, modelName: string, modelVar: str
   const allUnmatchedSteps: Array<{ step: string; functionName: string; operationName: string }> = [];
 
   Object.entries(controller.actions).forEach(([actionName, action]: [string, any]) => {
-    const behavior: BehaviorMetadata = {
-      preconditions: action.requires || action.preconditions || [],
-      steps: action.steps || [],
-      postconditions: action.ensures || action.postconditions || [],
-      sideEffects: action.publishes || action.events || [],
-      transactional: action.transactional,
-    };
-
-    const ctx: BehaviorContext = {
-      modelName,
-      serviceName: `${modelName}Controller`,
-      operationName: actionName,
-      prismaModel: modelVar,
-      parameterNames: Object.keys(action.parameters || {}),
-    };
-
-    const result = generateBehaviorWithHelpers(behavior, {}, ctx);
-    allUnmatchedSteps.push(...result.unmatchedSteps);
+    const params = action.parameters || {};
+    const paramNames = Object.keys(params);
+    const hasSteps = Array.isArray(action.steps) && action.steps.length > 0;
+
+    // Realize L3 contract: when an action declares `steps:`, the
+    // implementation lives in `behaviors/<ModelName>Controller.ai.ts`
+    // as an exported async function named EXACTLY `actionName`. Both
+    // per-action and per-owner emitters honour this contract. The
+    // controller method here just delegates: collect the action's
+    // parameters into a single `input` object and forward to the
+    // per-action implementation.
+    //
+    // Pre-this-fix, the controller emitted a per-STEP chain
+    // (`step1Result = await aiBehaviors.<verboseStepName>(...)`,
+    // `step2Result = await aiBehaviors.<verboseStepName>(step1Result)`,
+    // ...) referencing function names that NO emitter produces anymore
+    // — per-action and per-owner both export per-action names only.
+    // Every controller method was broken at compile time. Surfaced by
+    // the 2026-05-11 per-owner trial v4 (TS2339 "Property
+    // 'throwImmediatelyIfNoRefreshTokenIsHeldInLocalState' does not
+    // exist on type 'typeof import("...")'").
+    //
+    // Actions WITHOUT steps still go through the legacy
+    // behavior-generator path (deterministic shell from
+    // requires/ensures/publishes only); they don't need an .ai.ts
+    // delegate.
+    let body: string;
+    let needsAi = false;
+    if (hasSteps) {
+      // Delegate path. `input` is the bag of declared params, even if
+      // the action has zero declared params (then `input = {}`).
+      const inputObj = paramNames.length > 0
+        ? `{ ${paramNames.join(', ')} }`
+        : '{}';
+      body = `    const input = ${inputObj};
+    return await aiBehaviors.${actionName}(input);`;
+      needsAi = true;
+    } else {
+      // No-steps path — use the legacy behavior-generator that
+      // emits requires/ensures/publishes scaffolding.
+      const behavior: BehaviorMetadata = {
+        preconditions: action.requires || action.preconditions || [],
+        steps: [],
+        postconditions: action.ensures || action.postconditions || [],
+        sideEffects: action.publishes || action.events || [],
+        transactional: action.transactional,
+      };
+      const ctx: BehaviorContext = {
+        modelName,
+        serviceName: `${modelName}Controller`,
+        operationName: actionName,
+        prismaModel: modelVar,
+        parameterNames: paramNames,
+      };
+      const result = generateBehaviorWithHelpers(behavior, {}, ctx);
+      allUnmatchedSteps.push(...result.unmatchedSteps);
+      body = result.body;
+      needsAi = result.unmatchedSteps.length > 0;
+
+      if (result.helperMethods.length > 0) {
+        actions.push(...result.helperMethods);
+      }
+    }
 
     actions.push(`
   /**
@@ -402,12 +447,15 @@ function generateCustomActions(controller: any, modelName: string, modelVar: str
    * ${action.description || ''}
    */
   public async ${actionName}(${generateActionParams(action)}): Promise<any> {
-${result.body}
+${body}
   }`);
 
-    if (result.helperMethods.length > 0) {
-      actions.push(...result.helperMethods);
-    }
+    // Aggregate the needsAi signal for the import-line decision below.
+    if (needsAi) allUnmatchedSteps.push({
+      step: '<delegate-to-ai-ts>',
+      functionName: actionName,
+      operationName: actionName,
+    });
   });
 
   return {

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

@@ -151,7 +151,7 @@ function generateOperations(service: any): string {
 function generateOperation(operationName: string, operation: any, service: any): string {
   const rawParams = generateOperationParams(operation);
   const hasPublish = service.publishes && service.publishes.length > 0;
-  const body = generateOperationLogic(operation, service);
+  const body = generateOperationLogic(operation, service, operationName);
   // Rename any operation parameter that the body doesn't reference so tsc's
   // noUnusedParameters doesn't trip on placeholder service stubs.
   const params = renameUnusedParams(rawParams, body);
@@ -221,7 +221,7 @@ function generateOperationParams(operation: any): string {
  * Generate operation logic from behavioral metadata (L3 generation).
  * Falls back to placeholder if no behavioral data available.
  */
-function generateOperationLogic(operation: any, service: any): string {
+function generateOperationLogic(operation: any, service: any, operationName?: string): string {
   // Check for behavioral metadata — supports both AI-optimized format (implementation.preconditions)
   // and SpecVerse convention format (requires/ensures/publishes)
   const impl = operation.implementation || {};
@@ -239,14 +239,60 @@ function generateOperationLogic(operation: any, service: any): string {
       .map((e: string) => `Publish event: ${e}`);
   }
 
-  if (impl.preconditions?.length || impl.postconditions?.length || impl.steps?.length || impl.transactional) {
-    // L3: Generate from behavioral specification
+  // Realize L3 contract (mirrors controller-generator.ts): when an
+  // operation declares `steps:`, the implementation lives in
+  // `behaviors/<ServiceName>.ai.ts` as an exported async function
+  // named EXACTLY `operation.name`. Both per-action and per-owner
+  // emitters honour this contract. The service method here delegates:
+  // collect the operation's parameters into a single `input` object
+  // and forward to the per-action implementation in the .ai.ts.
+  //
+  // Pre-this-fix, the service emitted a per-STEP chain
+  // (`step1Result = await aiBehaviors.<verboseStepName>(...)`,
+  // `step2Result = await aiBehaviors.<verboseStepName>(step1Result)`,
+  // ...) referencing function names that NO emitter produces anymore
+  // — per-action and per-owner both export per-action names only.
+  // Every service method was broken at compile time. Surfaced by the
+  // 2026-05-11 per-owner trial v5: 411 TS errors in src/services/
+  // tracing back to "Property '<verboseStepName>' does not exist on
+  // type 'typeof import('.../behaviors/<X>.ai.js')'". Same defect as
+  // the controller-side per-step mismatch.
+  //
+  // Operations WITHOUT steps still go through the legacy
+  // behavior-generator path (preconditions/postconditions only,
+  // no per-step chain to break).
+  const hasSteps = Array.isArray(impl.steps) && impl.steps.length > 0
+    || Array.isArray(operation.steps) && operation.steps.length > 0;
+  if (hasSteps) {
+    // operationName resolution: prefer the caller-supplied entry KEY
+    // (always correct when operations is a name-keyed object — the
+    // canonical spec shape), fall back to operation.name (array-shape
+    // operations), final fallback 'execute' for malformed input.
+    // Pre-this-fix line read `operation.name || 'execute'`, which
+    // landed every operation on the `execute` delegate when the spec
+    // keyed operations by name without a redundant inner `.name`
+    // (the analyse-pipeline's canonical output). Result: the service
+    // method delegated to `aiBehaviors.execute(input)` but the .ai.ts
+    // only exported the real operation names → 69 TS2339 errors per
+    // 2026-05-11 idle-meta stub trial.
+    const resolvedOpName = operationName || operation.name || 'execute';
+    const paramNames = Object.keys(operation.parameters || {});
+    const inputObj = paramNames.length > 0
+      ? `{ ${paramNames.join(', ')} }`
+      : '{}';
+    return `    const input = ${inputObj};
+    return await aiBehaviors.${resolvedOpName}(input);`;
+  }
+
+  if (impl.preconditions?.length || impl.postconditions?.length || impl.transactional) {
+    // L3: Generate from behavioral specification (no-steps path —
+    // only requires/ensures/publishes scaffolding).
     const modelName = inferModelFromServiceName(service.name);
     const parameterNames = Object.keys(operation.parameters || {});
     const context: BehaviorContext = {
       modelName,
       serviceName: service.name,
-      operationName: operation.name || 'execute',
+      operationName: operationName || operation.name || 'execute',
       prismaModel: modelName,
       parameterNames,
     };
@@ -255,7 +301,7 @@ function generateOperationLogic(operation: any, service: any): string {
       preconditions: impl.preconditions || [],
       postconditions: impl.postconditions || [],
       sideEffects: impl.sideEffects || [],
-      steps: impl.steps || operation.steps || [],
+      steps: [],  // steps path handled by the delegate branch above
       transactional: impl.transactional || false
     };
 

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

@@ -330,8 +330,40 @@ export const STEP_CONVENTIONS: StepConvention[] = [
         return `    // Step ${ctx.stepNum}: Return result
     return ${toVar(ctx.modelName)};`;
       }
-      return `    // Step ${ctx.stepNum}: Return ${value}
+      // Only emit a typed `return <expr>;` when `value` is a single
+      // bareword identifier (or a single dotted/bracketed accessor) —
+      // anything that's syntactically a valid TypeScript expression
+      // already declared in the action's scope. Spec text like
+      // "logout confirmation" or "204 No Content" produces a
+      // grammatical English phrase but unparseable TS:
+      //   return logout confirmation;        // two bare identifiers
+      //   return 204 No Content;             // number + identifiers
+      // Returning the empty string here makes the matcher treat this
+      // as "convention regex matched but no safe emission" — the
+      // matcher falls through to the AI-fallback ([WRITE]) shape so
+      // the per-action / per-owner LLM hook handles it. Verified
+      // empirically by the 2026-05-11 idle-meta per-owner trial:
+      // the LLM correctly stubbed actions where prose returns had
+      // been bound to broken pre-baked snippets.
+      const isSafeIdentifier = /^[A-Za-z_$][\w$]*$/.test(value);
+      const isSafePropertyAccess = /^[A-Za-z_$][\w$]*(?:\.[A-Za-z_$][\w$]*)+$/.test(value);
+      if (isSafeIdentifier || isSafePropertyAccess) {
+        // Reference a single in-scope variable — but only if it was
+        // declared earlier in this action's emitted body (via the
+        // matcher's declaredVars set). Otherwise we'd emit
+        // `return AuthRegisterResponse;` referencing a type name
+        // that never resolves at runtime.
+        const head = value.split('.')[0]!;
+        const declared = ctx.declaredVars instanceof Set
+          ? ctx.declaredVars.has(head)
+          : false;
+        if (declared) {
+          return `    // Step ${ctx.stepNum}: Return ${value}
     return ${value};`;
+        }
+      }
+      // Bounce to [WRITE] — LLM will author this return.
+      return '';
     },
   },
 ];

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@specverse/engines",
-  "version": "6.39.3",
+  "version": "6.41.0",
   "description": "SpecVerse toolchain — parser, inference, realize, generators, AI, registry, bundles",
   "type": "module",
   "main": "dist/index.js",