@specverse/engines 6.53.1 → 6.63.0

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

@@ -2,6 +2,7 @@ import {
   toVar,
   matchAgainstConventions
 } from "../_shared/step-matching.js";
+import { safeEntityName } from "@specverse/types";
 function deriveModelDefaults(modelName, ctx) {
   if (!ctx.models) return [];
   const model = ctx.models[modelName] || ctx.models[modelName.charAt(0).toUpperCase() + modelName.slice(1)];
@@ -88,7 +89,8 @@ const PG_STEP_CONVENTIONS = [
     generateCall: (m, ctx) => {
       const model = m[1];
       const field = m[2];
-      const modelVar = toVar(model);
+      const modelVar = safeEntityName(model);
+      if (!modelVar) return "";
       const table = toTable(model);
       const params = ctx.parameterNames || [];
       const declared = ctx.declaredVars || /* @__PURE__ */ new Set();
@@ -111,7 +113,8 @@ const PG_STEP_CONVENTIONS = [
       const model = m[1];
       const f1 = m[2];
       const f2 = m[3];
-      const modelVar = toVar(model);
+      const modelVar = safeEntityName(model);
+      if (!modelVar) return "";
       const table = toTable(model);
       const declared = ctx.declaredVars || /* @__PURE__ */ new Set();
       if (declared.has(modelVar)) {
@@ -137,10 +140,13 @@ const PG_STEP_CONVENTIONS = [
   // --- Create model record ---
   {
     name: "create",
-    pattern: /^create\s+(?:new\s+)?(\w+)(?:\s+(?:with\s+)?(.+))?/i,
+    // Leading-adjective skip (NL_LEADING_ADJECTIVES) + isUnsafeEntityName
+    // safety net — see comment in prisma/step-conventions.ts "find" block.
+    pattern: /^create\s+(?:(?:new|existing|current|the|a|an)\s+)?(\w+)(?:\s+(?:with\s+)?(.+))?/i,
     generateCall: (m, ctx) => {
       const model = m[1];
-      const modelVar = toVar(model);
+      const modelVar = safeEntityName(model);
+      if (!modelVar) return "";
       const table = toTable(model);
       const params = ctx.parameterNames || [];
       const declared = ctx.declaredVars || /* @__PURE__ */ new Set();
@@ -153,12 +159,13 @@ const PG_STEP_CONVENTIONS = [
   // --- Update specific field on previously-loaded model ---
   {
     name: "update-field",
-    pattern: /^update\s+(\w+)\s+(\w+)\s+to\s+(.+)/i,
+    pattern: /^update\s+(?:(?:new|existing|current|the|a|an)\s+)?(\w+)\s+(\w+)\s+to\s+(.+)/i,
     generateCall: (m, ctx) => {
       const model = m[1];
+      const modelVar = safeEntityName(model);
+      if (!modelVar) return "";
       const field = m[2];
       const rawValue = m[3];
-      const modelVar = toVar(model);
       if (!ctx.declaredVars?.has(modelVar)) return "";
       const table = toTable(model);
       const val = resolveValue(rawValue, ctx);
@@ -169,11 +176,12 @@ const PG_STEP_CONVENTIONS = [
   // --- Update field timestamp ---
   {
     name: "update-field-timestamp",
-    pattern: /^update\s+(\w+)\s+(\w+)\s+timestamp$/i,
+    pattern: /^update\s+(?:(?:new|existing|current|the|a|an)\s+)?(\w+)\s+(\w+)\s+timestamp$/i,
     generateCall: (m, ctx) => {
       const model = m[1];
+      const modelVar = safeEntityName(model);
+      if (!modelVar) return "";
       const field = m[2];
-      const modelVar = toVar(model);
       if (!ctx.declaredVars?.has(modelVar)) return "";
       const table = toTable(model);
       return `    // Step ${ctx.stepNum}: Update ${model}.${field} timestamp
@@ -183,10 +191,11 @@ const PG_STEP_CONVENTIONS = [
   // --- Generic "Update X" (writes args back) ---
   {
     name: "update",
-    pattern: /^update\s+(\w+)(?:\s+(.+))?$/i,
+    pattern: /^update\s+(?:(?:new|existing|current|the|a|an)\s+)?(\w+)(?:\s+(.+))?$/i,
     generateCall: (m, ctx) => {
       const model = m[1];
-      const modelVar = toVar(model);
+      const modelVar = safeEntityName(model);
+      if (!modelVar) return "";
       if (!ctx.declaredVars?.has(modelVar)) return "";
       const table = toTable(model);
       return `    // Step ${ctx.stepNum}: Update ${model}
@@ -196,10 +205,11 @@ const PG_STEP_CONVENTIONS = [
   // --- Delete model record ---
   {
     name: "delete",
-    pattern: /^delete\s+(\w+)/i,
+    pattern: /^delete\s+(?:(?:new|existing|current|the|a|an)\s+)?(\w+)/i,
     generateCall: (m, ctx) => {
       const model = m[1];
-      const modelVar = toVar(model);
+      const modelVar = safeEntityName(model);
+      if (!modelVar) return "";
       if (!ctx.declaredVars?.has(modelVar)) return "";
       const table = toTable(model);
       return `    // Step ${ctx.stepNum}: Delete ${model}
@@ -213,7 +223,8 @@ const PG_STEP_CONVENTIONS = [
     generateCall: (m, ctx) => {
       const model = m[1];
       const state = m[2];
-      const modelVar = toVar(model);
+      const modelVar = safeEntityName(model);
+      if (!modelVar) return "";
       if (!ctx.declaredVars?.has(modelVar)) return "";
       const table = toTable(model);
       return `    // Step ${ctx.stepNum}: Transition ${model} to ${state}
@@ -265,7 +276,8 @@ const PG_STEP_CONVENTIONS = [
     name: "persist",
     pattern: /^(?:persist|save|store)\s+(\w+(?:\s+\w+)?)(?:\s+(?:for|to|record).*)?$/i,
     generateCall: (m, ctx) => {
-      const target = toVar(m[1].replace(/\s+(.)/g, (_, c) => c.toUpperCase()));
+      const target = safeEntityName(m[1].replace(/\s+(.)/g, (_, c) => c.toUpperCase()));
+      if (!target) return "";
       const table = toTable(target);
       const recordSrc = mostRecentStepResult(ctx) ?? "args";
       return `    // Step ${ctx.stepNum}: Persist ${m[1]}
@@ -281,7 +293,8 @@ const PG_STEP_CONVENTIONS = [
     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 modelVar = safeEntityName(m[1]);
+      if (!modelVar) return "";
       const Model = pascal(m[2]);
       const table = toTable(Model);
       if (!ctx.declaredVars?.has(modelVar)) return "";
@@ -299,7 +312,8 @@ const PG_STEP_CONVENTIONS = [
     name: "conditional-update",
     pattern: /^if\s+(\w+)\s+exists,?\s+update\s+(\w+)(?:\s+(.+))?$/i,
     generateCall: (m, ctx) => {
-      const modelVar = toVar(m[1]);
+      const modelVar = safeEntityName(m[1]);
+      if (!modelVar) return "";
       const field = m[2];
       const table = toTable(m[1]);
       if (!ctx.declaredVars?.has(modelVar)) return "";
@@ -347,7 +361,8 @@ const PG_STEP_CONVENTIONS = [
     pattern: /^otherwise\s+create\s+(?:new\s+)?(\w+)\s+record$/i,
     generateCall: (m, ctx) => {
       const Model = pascal(m[1]);
-      const modelVar = toVar(Model);
+      const modelVar = safeEntityName(Model);
+      if (!modelVar) return "";
       const table = toTable(Model);
       const wasDeclared = ctx.declaredVars?.has(modelVar);
       const declared = Array.from(ctx.declaredVars || []);
@@ -391,9 +406,11 @@ const PG_STEP_CONVENTIONS = [
     generateCall: (m, ctx) => {
       const service = m[1];
       const method = m[2];
+      const serviceVar = safeEntityName(service);
+      if (!serviceVar) return "";
       const args = (ctx.parameterNames || []).join(", ");
       return `    // Step ${ctx.stepNum}: Call ${service}.${method}
-    await (${toVar(service)} as any).${method}({ ${args} });`;
+    await (${serviceVar} as any).${method}({ ${args} });`;
     }
   },
   // --- Return ---

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

@@ -1,3 +1,4 @@
+import { safeFunctionName } from "@specverse/types";
 import { matchStep } from "./step-conventions.js";
 import { validateImportWhitelist } from "@specverse/engines/ai";
 import { createHash } from "crypto";
@@ -190,6 +191,7 @@ async function generateAiBehaviorsFile(opts) {
   let cacheHits = 0;
   let cacheMisses = 0;
   for (const { functionName, step, operationName, parameterNames, inputs, returns, modelName } of unmatchedFunctions) {
+    const { name: safeName, reserved: nameReserved } = safeFunctionName(functionName);
     const stripLiteralsAndComments = (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]);
       out = out.replace(/`((?:\\.|\$\{[^}]*\}|(?!`).)*)`/g, (full, content) => {
@@ -246,13 +248,18 @@ async function generateAiBehaviorsFile(opts) {
       const fields = Object.entries(returns).map(([k, v]) => `${k}: ${v}`).join("; ");
       returnType = `{ ${fields} }`;
     }
+    const buildTestCode = (rawBody) => {
+      const { signature, destructure } = buildSignatureAndDestructure(rawBody);
+      const destructureLine = destructure ? destructure + "\n" : "";
+      return `export async function ${safeName}(${signature}): Promise<${returnType}> {
+${destructureLine}${rawBody}
+}`;
+    };
     const key = cacheKey(step, modelName, operationName, functionName, inputs);
     let body = cacheRead(key);
     let source = body ? "AI-CACHED" : "STUB";
     if (body) {
-      const testCode = `export async function ${functionName}(input: any): Promise<any> {
-${body}
-}`;
+      const testCode = buildTestCode(body);
       const syntaxError = await validateTypeScript(testCode);
       const typeError = syntaxError ? null : await validateTypeScriptTypes(testCode);
       const importError = syntaxError || typeError ? null : validateImports(testCode);
@@ -280,9 +287,7 @@ ${body}
           // Pass declared return type to Claude
         });
         if (body) {
-          const testCode = `export async function ${functionName}(input: any): Promise<any> {
-${body}
-}`;
+          const testCode = buildTestCode(body);
           const syntaxError = await validateTypeScript(testCode);
           if (syntaxError) {
             console.warn(`      [ai-validate] ${functionName} has syntax error: ${syntaxError}`);
@@ -324,9 +329,7 @@ ${retryHint}`,
                   returnType
                 });
                 if (retried) {
-                  const retryCode = `export async function ${functionName}(input: any): Promise<any> {
-${retried}
-}`;
+                  const retryCode = buildTestCode(retried);
                   const retrySyntaxError = await validateTypeScript(retryCode);
                   const retryTypeError = retrySyntaxError ? null : await validateTypeScriptTypes(retryCode);
                   const retryImportError = retrySyntaxError || retryTypeError ? null : validateImports(retryCode);
@@ -364,6 +367,8 @@ ${retried}
 ` : "";
     const returnsDoc = returnType !== "any" ? ` * Returns: ${returnType}
 ` : "";
+    const reExportLine = nameReserved ? `
+export { ${safeName} as ${functionName} };` : "";
     functions.push(`/**
  * ${functionName}
  *
@@ -376,7 +381,7 @@ ${inputsDoc}${returnsDoc} * Source: ${source}
  * All data comes in via \`input\`; all effects happen in the calling controller.
  * ${source === "AI-GENERATED" ? "AI-generated implementation. Review and test before deploying." : source === "AI-CACHED" ? "Restored from AI cache (.specverse/ai-cache/). Delete cache entry to regenerate." : source === "AI-INVALID" ? "AI returned code with syntax errors \u2014 function throws at runtime. Fix or regenerate." : "STUB \u2014 Claude CLI unavailable. Install Claude Code or implement manually."}
  */
-export async function ${functionName}(${(() => {
+${nameReserved ? "async" : "export async"} function ${safeName}(${(() => {
       const { signature: sig } = buildSignatureAndDestructure(body);
       return sig;
     })()}): Promise<${returnType}> {
@@ -384,7 +389,7 @@ ${(() => {
       const { destructure } = buildSignatureAndDestructure(body);
       return destructure ? destructure + "\n" : "";
     })()}${body}
-}`);
+}${reExportLine}`);
   }
   if (aiService?.endSession) aiService.endSession();
   if (cacheHits > 0 || cacheMisses > 0) {

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

@@ -30,7 +30,7 @@ function generatePrismaController(context) {
   ].filter(Boolean).join("\n  ");
   const usesPrisma = /\bprisma\b/.test(classBody);
   const usesParseId = /\bparseId\(/.test(classBody);
-  const usesEventBus = hasEventPublishing(curedOps, controller);
+  const usesEventBus = /\beventBus\./.test(classBody);
   const usesAiBehaviors = customActions.needsAiBehaviors;
   const imports = [
     usesPrisma ? `import { PrismaClient } from '@prisma/client';` : "",

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

@@ -3,6 +3,7 @@ import {
   toVar,
   matchAgainstConventions
 } from "../_shared/step-matching.js";
+import { safeEntityName } from "@specverse/types";
 function resolveValue(rawValue, ctx) {
   const value = rawValue.trim().replace(/^['"]|['"]$/g, "");
   if (/^(current\s*time|now|timestamp)$/i.test(value)) {
@@ -60,13 +61,27 @@ const STEP_CONVENTIONS = [
     }
   },
   // --- Find / Lookup ---
+  //
+  // All entity-targeting patterns (find / create / update / delete) share
+  // two safeguards:
+  //   1. A pattern-level leading-adjective skip
+  //      `(?:(?:new|existing|current|the|a|an)\s+)?` so NL phrasings like
+  //      "Find existing Player by id" or "Create new Player with ..."
+  //      extract the noun, not the adjective. Kept in sync with
+  //      `NL_LEADING_ADJECTIVES` in `_shared/step-matching.ts`.
+  //   2. `safeEntityName(m[1])` — the reserved-word-safe primitive from
+  //      `@specverse/types`. Returns the lowerCamel identifier, or `null`
+  //      when the extraction would emit a TS reserved word
+  //      (e.g. `prisma.new.create`). On null, generateCall returns `''` so
+  //      the matcher falls through to the AI [WRITE] fallback.
   {
     name: "find",
-    pattern: /^find\s+(\w+)\s+by\s+(\w+)/i,
+    pattern: /^find\s+(?:(?:new|existing|current|the|a|an)\s+)?(\w+)\s+by\s+(\w+)/i,
     generateCall: (m, ctx) => {
       const model = m[1];
+      const modelVar = safeEntityName(model);
+      if (!modelVar) return "";
       const field = m[2];
-      const modelVar = toVar(model);
       const params = ctx.parameterNames || [];
       const declared = ctx.declaredVars || /* @__PURE__ */ new Set();
       const idParam = field === "id" ? params.find((p) => p === `${modelVar}Id`) || params.find((p) => p === "id") || `${modelVar}Id` : params.find((p) => p === field) || `params.${field}`;
@@ -81,10 +96,11 @@ const STEP_CONVENTIONS = [
   // --- Create ---
   {
     name: "create",
-    pattern: /^create\s+(\w+)(?:\s+(?:with\s+)?(.+))?/i,
+    pattern: /^create\s+(?:(?:new|existing|current|the|a|an)\s+)?(\w+)(?:\s+(?:with\s+)?(.+))?/i,
     generateCall: (m, ctx) => {
       const model = m[1];
-      const modelVar = toVar(model);
+      const modelVar = safeEntityName(model);
+      if (!modelVar) return "";
       const paramNames = ctx.parameterNames || [];
       const dataFields = paramNames.length > 0 ? `{ ${paramNames.join(", ")} }` : "data";
       return `    // Step ${ctx.stepNum}: Create ${model}
@@ -94,12 +110,13 @@ const STEP_CONVENTIONS = [
   // --- Update field ---
   {
     name: "update-field",
-    pattern: /^update\s+(\w+)\s+(\w+)\s+to\s+(.+)/i,
+    pattern: /^update\s+(?:(?:new|existing|current|the|a|an)\s+)?(\w+)\s+(\w+)\s+to\s+(.+)/i,
     generateCall: (m, ctx) => {
       const model = m[1];
+      const modelVar = safeEntityName(model);
+      if (!modelVar) return "";
       const field = m[2];
       const rawValue = m[3];
-      const modelVar = toVar(model);
       const val = resolveValue(rawValue, ctx);
       return `    // Step ${ctx.stepNum}: Update ${model} ${field} to ${rawValue.trim()}
     await prisma.${modelVar}.update({
@@ -111,10 +128,11 @@ const STEP_CONVENTIONS = [
   // --- Generic update ---
   {
     name: "update",
-    pattern: /^update\s+(\w+)(?:\s+(.+))?/i,
+    pattern: /^update\s+(?:(?:new|existing|current|the|a|an)\s+)?(\w+)(?:\s+(.+))?/i,
     generateCall: (m, ctx) => {
       const model = m[1];
-      const modelVar = toVar(model);
+      const modelVar = safeEntityName(model);
+      if (!modelVar) return "";
       return `    // Step ${ctx.stepNum}: Update ${model}
     await prisma.${modelVar}.update({
       where: { id: ${modelVar}.id },
@@ -125,10 +143,11 @@ const STEP_CONVENTIONS = [
   // --- Delete ---
   {
     name: "delete",
-    pattern: /^delete\s+(\w+)/i,
+    pattern: /^delete\s+(?:(?:new|existing|current|the|a|an)\s+)?(\w+)/i,
     generateCall: (m, ctx) => {
       const model = m[1];
-      const modelVar = toVar(model);
+      const modelVar = safeEntityName(model);
+      if (!modelVar) return "";
       return `    // Step ${ctx.stepNum}: Delete ${model}
     await prisma.${modelVar}.delete({ where: { id: ${modelVar}.id } });`;
     }
@@ -140,7 +159,8 @@ const STEP_CONVENTIONS = [
     generateCall: (m, ctx) => {
       const model = m[1];
       const state = m[2];
-      const modelVar = toVar(model);
+      const modelVar = safeEntityName(model);
+      if (!modelVar) return "";
       return `    // Step ${ctx.stepNum}: Transition ${model} to ${state}
     if (${modelVar}.status === '${state}') throw new Error('${model} is already ${state}');
     await prisma.${modelVar}.update({
@@ -227,8 +247,10 @@ const STEP_CONVENTIONS = [
     generateCall: (m, ctx) => {
       const service = m[1];
       const method = m[2];
+      const serviceVar = safeEntityName(service);
+      if (!serviceVar) return "";
       return `    // Step ${ctx.stepNum}: Call ${service}.${method}
-    await ${toVar(service)}.${method}({ ${(ctx.parameterNames || []).join(", ")} });`;
+    await ${serviceVar}.${method}({ ${(ctx.parameterNames || []).join(", ")} });`;
     }
   },
   // --- Return ---

package/dist/libs/instance-factories/services/templates/shared-patterns.js

@@ -2,13 +2,13 @@ const CONVENTION_PATTERNS = [
   { name: "validate", pattern: /^validate\s+(.+)/i, description: "Validate input data" },
   { name: "check-no-existing", pattern: /^check\s+(?:no\s+existing|.*has\s+no\s+existing)\s+(\w+)\s+for\s+(\w+)\s+in\s+(\w+)/i, description: "Check no duplicate entity exists for a pair" },
   { name: "check", pattern: /^check\s+(.+)/i, description: "Check a condition" },
-  { name: "find", pattern: /^find\s+(\w+)\s+by\s+(\w+)/i, description: "Find entity by field" },
+  { name: "find", pattern: /^find\s+(?:(?:new|existing|current|the|a|an)\s+)?(\w+)\s+by\s+(\w+)/i, description: "Find entity by field" },
   { name: "find-all-for", pattern: /^find\s+(?:all\s+)?(\w+?)s?\s+(?:for|of|belonging\s+to)\s+(\w+)/i, description: "Cross-model query via foreign key" },
   { name: "count-per", pattern: /^count\s+(\w+?)s?\s+(?:per|by|for\s+each)\s+(\w+)/i, description: "Group-by aggregation count" },
-  { name: "create", pattern: /^create\s+(\w+)(?:\s+record)?/i, description: "Create a new entity" },
-  { name: "update-field", pattern: /^update\s+(\w+)\s+(\w+)\s+to\s+(.+)/i, description: "Update specific field to value" },
-  { name: "update", pattern: /^update\s+(\w+)$/i, description: "Update entity with params" },
-  { name: "delete", pattern: /^delete\s+(\w+)/i, description: "Delete an entity" },
+  { name: "create", pattern: /^create\s+(?:(?:new|existing|current|the|a|an)\s+)?(\w+)(?:\s+record)?/i, description: "Create a new entity" },
+  { name: "update-field", pattern: /^update\s+(?:(?:new|existing|current|the|a|an)\s+)?(\w+)\s+(\w+)\s+to\s+(.+)/i, description: "Update specific field to value" },
+  { name: "update", pattern: /^update\s+(?:(?:new|existing|current|the|a|an)\s+)?(\w+)$/i, description: "Update entity with params" },
+  { name: "delete", pattern: /^delete\s+(?:(?:new|existing|current|the|a|an)\s+)?(\w+)/i, description: "Delete an entity" },
   { name: "transition", pattern: /^transition\s+(\w+)\s+to\s+(\w+)/i, description: "Lifecycle state transition" },
   { name: "set", pattern: /^set\s+(\w+)\s+to\s+(.+)/i, description: "Set a field value" },
   { name: "increment", pattern: /^increment\s+(\w+)\s+by\s+(\w+)/i, description: "Increment numeric field" },

package/dist/realize/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/realize/index.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAGH,cAAc,kBAAkB,CAAC;AAGjC,cAAc,kBAAkB,CAAC;AAGjC,cAAc,uBAAuB,CAAC;AAItC,OAAO,EAAE,sBAAsB,EAAE,oBAAoB,EAAE,MAAM,sBAAsB,CAAC;AACpF,OAAO,EAAE,cAAc,EAAE,MAAM,uBAAuB,CAAC;AAGvD,OAAO,EAAE,mBAAmB,EAAE,MAAM,6BAA6B,CAAC;AAClE,OAAO,EACL,wCAAwC,EACxC,eAAe,EACf,KAAK,YAAY,GAClB,MAAM,2BAA2B,CAAC;AAMnC,OAAO,KAAK,EAAE,aAAa,EAAE,UAAU,EAAE,eAAe,EAAE,MAAM,kBAAkB,CAAC;AA2DnF,cAAM,sBAAuB,YAAW,aAAa;IACnD,IAAI,SAAa;IACjB,OAAO,SAAW;IAClB,YAAY,WAA+E;IAE3F,OAAO,CAAC,OAAO,CAAa;IAC5B,OAAO,CAAC,QAAQ,CAAa;IAC7B,OAAO,CAAC,aAAa,CAAa;IAClC,OAAO,CAAC,QAAQ,CAAa;IAC7B,OAAO,CAAC,WAAW,CAAS;IAEtB,UAAU,CAAC,MAAM,CAAC,EAAE;QACxB,YAAY,CAAC,EAAE,MAAM,CAAC;QACtB,UAAU,CAAC,EAAE,MAAM,CAAC;KACrB,GAAG,OAAO,CAAC,IAAI,CAAC;IAwDjB,OAAO,IAAI,UAAU;IAIrB,OAAO,CAAC,UAAU,EAAE,MAAM,GAAG,GAAG;IAK1B,QAAQ,CAAC,QAAQ,EAAE,GAAG,EAAE,QAAQ,EAAE,MAAM,EAAE,OAAO,EAAE,GAAG,GAAG,OAAO,CAAC,eAAe,CAAC;IAKvF;;;OAGG;IACG,UAAU,CAAC,IAAI,EAAE,GAAG,EAAE,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC;QAAE,KAAK,EAAE,MAAM,EAAE,CAAC;QAAC,MAAM,EAAE,MAAM,EAAE,CAAA;KAAE,CAAC;IAyxC9F;;;OAGG;YACW,UAAU;IA8DxB,OAAO,CAAC,oBAAoB;CAuB7B;AAED,eAAO,MAAM,MAAM,wBAA+B,CAAC;AACnD,eAAe,MAAM,CAAC;AACtB,OAAO,EAAE,sBAAsB,EAAE,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/realize/index.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAGH,cAAc,kBAAkB,CAAC;AAGjC,cAAc,kBAAkB,CAAC;AAGjC,cAAc,uBAAuB,CAAC;AAItC,OAAO,EAAE,sBAAsB,EAAE,oBAAoB,EAAE,MAAM,sBAAsB,CAAC;AACpF,OAAO,EAAE,cAAc,EAAE,MAAM,uBAAuB,CAAC;AAGvD,OAAO,EAAE,mBAAmB,EAAE,MAAM,6BAA6B,CAAC;AAClE,OAAO,EACL,wCAAwC,EACxC,eAAe,EACf,KAAK,YAAY,GAClB,MAAM,2BAA2B,CAAC;AAMnC,OAAO,KAAK,EAAE,aAAa,EAAE,UAAU,EAAE,eAAe,EAAE,MAAM,kBAAkB,CAAC;AA2DnF,cAAM,sBAAuB,YAAW,aAAa;IACnD,IAAI,SAAa;IACjB,OAAO,SAAW;IAClB,YAAY,WAA+E;IAE3F,OAAO,CAAC,OAAO,CAAa;IAC5B,OAAO,CAAC,QAAQ,CAAa;IAC7B,OAAO,CAAC,aAAa,CAAa;IAClC,OAAO,CAAC,QAAQ,CAAa;IAC7B,OAAO,CAAC,WAAW,CAAS;IAEtB,UAAU,CAAC,MAAM,CAAC,EAAE;QACxB,YAAY,CAAC,EAAE,MAAM,CAAC;QACtB,UAAU,CAAC,EAAE,MAAM,CAAC;KACrB,GAAG,OAAO,CAAC,IAAI,CAAC;IAwDjB,OAAO,IAAI,UAAU;IAIrB,OAAO,CAAC,UAAU,EAAE,MAAM,GAAG,GAAG;IAK1B,QAAQ,CAAC,QAAQ,EAAE,GAAG,EAAE,QAAQ,EAAE,MAAM,EAAE,OAAO,EAAE,GAAG,GAAG,OAAO,CAAC,eAAe,CAAC;IAKvF;;;OAGG;IACG,UAAU,CAAC,IAAI,EAAE,GAAG,EAAE,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC;QAAE,KAAK,EAAE,MAAM,EAAE,CAAC;QAAC,MAAM,EAAE,MAAM,EAAE,CAAA;KAAE,CAAC;IAu2C9F;;;OAGG;YACW,UAAU;IA8DxB,OAAO,CAAC,oBAAoB;CAuB7B;AAED,eAAO,MAAM,MAAM,wBAA+B,CAAC;AACnD,eAAe,MAAM,CAAC;AACtB,OAAO,EAAE,sBAAsB,EAAE,CAAC"}

package/dist/realize/index.js

@@ -423,26 +423,67 @@ class SpecVerseRealizeEngine {
                 // savings, warm cache, and skill state persists across calls).
                 const { runPerOwnerEmission, buildAvailableCapabilitiesString } = await import('./per-owner-runner.js');
                 const { createRealizeOwnerLlmEmit } = await import('./per-owner-emit.js');
+                const { createPerActionRecovery } = await import('./per-action-recovery.js');
+                const { resolveProviderId: resolveProviderIdForRecovery } = await import('../ai/model-resolver.js');
                 const perOwnerEmit = createRealizeOwnerLlmEmit({ model: sharedModel });
+                // Tier 2 — per-action recovery (Phase 5a of
+                // 2026-05-14-PER-ACTION-RECOVERY-TIER.md). When the whole-owner
+                // emit fails, the runner retries the owner action-by-action with
+                // full owner context before γ-stubbing. Default-on; the runner
+                // honours SPECVERSE_REALIZE_NO_RECOVERY_TIER=1 + the action-count
+                // cap. Stub provider has no LLM — skip wiring it then.
+                const perActionRecovery = resolveProviderIdForRecovery() === 'stub'
+                    ? undefined
+                    : createPerActionRecovery({ model: sharedModel });
                 const availableCapabilities = buildAvailableCapabilitiesString(this.manifest);
                 const ownerResult = await runPerOwnerEmission({
                     spec, outputDir,
                     matcher: sharedMatcher,
                     conventions,
                     perOwnerEmit,
+                    perActionRecovery,
                     availableClientsByOwner,
                     availableCapabilities,
                     silent: false,
                 });
                 if (ownerResult.totals.actionCount > 0) {
                     const llmCount = ownerResult.totals.ownersEmittedByLLM;
+                    const tier2Count = ownerResult.totals.ownersRecoveredByTier2;
                     const fallbackCount = ownerResult.totals.ownersFellBack;
-                    const tail = fallbackCount > 0
-                        ? ` (${llmCount} LLM-emitted, ${fallbackCount} fell back to placeholder)`
-                        : '';
+                    const tailParts = [];
+                    if (llmCount > 0)
+                        tailParts.push(`${llmCount} LLM-emitted`);
+                    if (tier2Count > 0)
+                        tailParts.push(`${tier2Count} via per-action recovery`);
+                    if (fallbackCount > 0)
+                        tailParts.push(`${fallbackCount} fell back to placeholder`);
+                    const tail = tailParts.length > 0 ? ` (${tailParts.join(', ')})` : '';
                     console.log(`   ✅ Per-OWNER AI behaviors: ${ownerResult.totals.actionCount} action(s) across ${ownerResult.totals.ownerCount} owner(s)${tail}`);
                 }
-                // 2.5b Post-emit feedback (engines 6.53.0 — DEFAULT-ON, env hatch retired).
+                // 2.5a Diagnostic sidecar (default-on; opt-out via SPECVERSE_REALIZE_NO_DIAGNOSTICS=1).
+                //
+                // Phase 1 of 2026-05-13-VERIFIER-DIAGNOSTIC-TREATMENT-SPLIT.
+                // Runs the stub-completeness verifier in diagnostic-only mode
+                // (separate from the feedback runner), writes a sidecar with
+                // per-owner stub breakdown, prints a one-line CLI summary if
+                // there's anything to flag. Zero LLM calls, milliseconds runtime.
+                if (process.env.SPECVERSE_REALIZE_NO_DIAGNOSTICS !== '1') {
+                    try {
+                        const { runDiagnostics, formatSummaryLine } = await import('./post-emit-verify/index.js');
+                        const summary = await runDiagnostics({
+                            outputDir,
+                            targetLanguage: 'typescript',
+                        });
+                        const line = formatSummaryLine(summary);
+                        if (line)
+                            console.log(line);
+                    }
+                    catch (e) {
+                        // Diagnostic failure must never crash the realize pipeline.
+                        errors.push(`Realize diagnostics: ${e?.message ?? String(e)}`);
+                    }
+                }
+                // 2.5b Post-emit feedback (default-on; escape hatch retained).
                 //
                 // After all per-owner emits complete, run language-specific
                 // verifiers (tsc, mypy, etc.) on the realized output and feed
@@ -453,7 +494,12 @@ class SpecVerseRealizeEngine {
                 // Flip history:
                 //   6.51.0 — opt-in via SPECVERSE_REALIZE_POST_VERIFY=1
                 //   6.52.0 — default-on; opt-out via SPECVERSE_REALIZE_NO_POST_VERIFY=1
-                //   6.53.0 — env hatch retired (this version)
+                //   6.53.0 — env hatch retired
+                //   6.53.2 — escape hatch restored (this version) after
+                //            real-npm publish surfaced the need for a safety
+                //            valve. Default-on stays; users with a genuine
+                //            regression can set SPECVERSE_REALIZE_NO_POST_VERIFY=1
+                //            until upstream ships a fix.
                 //
                 // Empirical evidence at flip time (Phase A corpus harness):
                 //   - scoremyclays-ollama: 9 → 0 tsc errors
@@ -462,12 +508,31 @@ class SpecVerseRealizeEngine {
                 //     generator errors as unmappable; no spurious re-emits)
                 //   - zero regressions across the corpus
                 //
-                // Env tuning still available:
+                // Env tuning:
+                //   SPECVERSE_REALIZE_NO_POST_VERIFY=1        — opt out (escape hatch)
                 //   SPECVERSE_REALIZE_POST_VERIFY_PASSES=N    — tune retry count (default 1)
                 //   SPECVERSE_REALIZE_POST_VERIFY_MAX_FILES=N — cap LLM spend per pass (default 20)
+                //   SPECVERSE_REALIZE_POST_VERIFY_ENABLE=id,…  — opt in to verifiers
+                //                                              with enabledByDefault: false
+                //                                              (e.g. stub-completeness)
+                //
+                // Gate: run feedback whenever there are owners AT ALL — not just
+                // LLM-emitted ones. Pre-6.58.0 the gate was
+                // `ownersEmittedByLLM > 0`, which skipped feedback entirely when
+                // EVERY owner γ-fell-back (structural-preservation rejection,
+                // parse failure, etc.). That defeated the stub-completeness
+                // verifier (engines 6.54.0+) in its single highest-value case:
+                // an all-fallback realize is ALL STUB001 γ-stubs, exactly what
+                // auto-reemit-with-context (Phase 3) is built to recover. The
+                // Phase 3 trial (2026-05-14, nestjs-billing × MarrBox/Ollama)
+                // surfaced this: both providers had all owners rejected by
+                // structural-preservation → 0 LLM-emitted → feedback skipped →
+                // 7 STUB001 stubs shipped unfixed. Now: `ownerCount > 0`. The
+                // only true skip is "no behaviors at all" (validate-only
+                // backends) — and the stub provider is still skipped below.
                 //
                 // Stub provider is auto-skipped (no LLM → can't fix).
-                if (ownerResult.totals.ownersEmittedByLLM > 0) {
+                if (process.env.SPECVERSE_REALIZE_NO_POST_VERIFY !== '1' && ownerResult.totals.ownerCount > 0) {
                     // Detect stub provider early — there's no LLM, so feedback
                     // can't fire. Stub returns the prompt verbatim which would
                     // appear as a "fix" but is garbage. Log + skip cleanly.
@@ -478,11 +543,27 @@ class SpecVerseRealizeEngine {
                     }
                     else {
                         try {
-                            const { runPostEmitFeedback, buildLlmReemit } = await import('./post-emit-verify/index.js');
+                            const { runPostEmitFeedback, buildLlmReemit, appendSpecGaps, formatSpecGapLine } = await import('./post-emit-verify/index.js');
                             const maxPasses = parseInt(process.env.SPECVERSE_REALIZE_POST_VERIFY_PASSES ?? '1', 10) || 1;
                             const maxFilesPerPass = parseInt(process.env.SPECVERSE_REALIZE_POST_VERIFY_MAX_FILES ?? '20', 10) || 20;
-                            const reemit = buildLlmReemit({ model: sharedModel });
-                            const feedbackResult = await runPostEmitFeedback({ outputDir, targetLanguage: 'typescript' }, reemit, { maxPasses, maxFilesPerPass });
+                            const enableCsv = process.env.SPECVERSE_REALIZE_POST_VERIFY_ENABLE ?? '';
+                            const enabledOverrides = enableCsv
+                                ? new Set(enableCsv.split(',').map((s) => s.trim()).filter(Boolean))
+                                : undefined;
+                            const { loadContextSnapshot } = await import('./realize-context-snapshot.js');
+                            const reemit = buildLlmReemit({
+                                model: sharedModel,
+                                contextLoader: (ownerName) => loadContextSnapshot(outputDir, ownerName),
+                            });
+                            const feedbackResult = await runPostEmitFeedback({ outputDir, targetLanguage: 'typescript' }, reemit, { maxPasses, maxFilesPerPass, enabledOverrides });
+                            // Phase 2: surface spec gaps (STUB002s the treatment selector
+                            // routed away from auto-reemit) into the diagnostic sidecar.
+                            if (feedbackResult.specGaps.length > 0) {
+                                appendSpecGaps(outputDir, feedbackResult.specGaps);
+                                const line = formatSpecGapLine(feedbackResult.specGaps.length);
+                                if (line)
+                                    console.log(line);
+                            }
                             const before = feedbackResult.initialErrors.length;
                             const after = feedbackResult.finalErrors.length;
                             if (before > 0) {