@specverse/engines 6.42.3 → 6.60.1

package/dist/realize/structural-validator.js

@@ -50,6 +50,27 @@ function canonicalise(code) {
         .replace(/\s+/g, ' ')
         .trim();
 }
+/**
+ * Default drop-fraction threshold: an owner may drop up to (and
+ * including) HALF of its pre-baked snippets and still be accepted
+ * (with the drops surfaced as warnings). Above half → γ-fallback.
+ *
+ * Rationale (2026-05-14, Phase 5 first target of
+ * `2026-05-13-VERIFIER-DIAGNOSTIC-TREATMENT-SPLIT.md`): pre-fix the
+ * validator rejected an ENTIRE owner if it dropped a SINGLE snippet.
+ * For sonnet this rarely fires; for openai-compatible models (Ollama
+ * qwen3-coder:30b, MarrBox) it fired on ~13/36 owners in the idle-meta
+ * trial — every paraphrased snippet nuked the whole owner to γ-stub.
+ * The post-emit feedback loop then recovered those owners anyway via
+ * context-complete reemit (which does NOT run this validator), so the
+ * strictness bought an extra LLM round-trip and STILL lost determinism.
+ * A threshold keeps the gross-failure guard ("the LLM basically
+ * ignored the scaffolding") while letting a minority of paraphrases
+ * through — they ride the normal tsc + stub-completeness gates instead.
+ *
+ * Overridable via `SPECVERSE_REALIZE_STRUCTURAL_DROP_THRESHOLD`.
+ */
+export const DEFAULT_STRUCTURAL_DROP_THRESHOLD = 0.5;
 /**
  * Validate that every pre-baked snippet appears in the LLM-emitted body.
  *
@@ -58,19 +79,29 @@ function canonicalise(code) {
  * step number, step text, and the closest near-match found in the body
  * (or `null` if there's no token-overlap candidate).
  *
+ * `dropThreshold` is the fraction of countable snippets that may be
+ * dropped before the result flips to `ok: false`. At or below the
+ * threshold, the result is `ok: true` with the dropped snippets in
+ * `warnings`. Above it, `ok: false` with the full `missing` list.
+ *
  * Empty `prebakedSnippets` is a vacuous pass — when no convention
  * matched, there's nothing to preserve.
  */
-export function validateLlmOutputPreservesConventions(llmBody, prebakedSnippets) {
+export function validateLlmOutputPreservesConventions(llmBody, prebakedSnippets, dropThreshold = DEFAULT_STRUCTURAL_DROP_THRESHOLD) {
     if (prebakedSnippets.length === 0) {
         return { ok: true };
     }
     const llmCanonical = canonicalise(llmBody);
     const missing = [];
+    // Countable = snippets with a non-empty canonical form. Comment-only
+    // snippets are skipped (they're vacuously "preserved") and must NOT
+    // inflate the denominator, or the drop fraction would understate.
+    let countable = 0;
     for (const snippet of prebakedSnippets) {
         const expected = canonicalise(snippet.snippet);
         if (expected.length === 0)
             continue; // skip comment-only snippets
+        countable++;
         if (llmCanonical.includes(expected)) {
             continue;
         }
@@ -103,7 +134,14 @@ export function validateLlmOutputPreservesConventions(llmBody, prebakedSnippets)
     if (missing.length === 0) {
         return { ok: true };
     }
-    const reason = formatMissingReport(missing);
+    // Below/at threshold → accept with warnings; above → γ-fallback.
+    // countable is guaranteed > 0 here (missing is non-empty, and every
+    // entry in missing incremented countable).
+    const dropFraction = missing.length / countable;
+    if (dropFraction <= dropThreshold) {
+        return { ok: true, warnings: missing };
+    }
+    const reason = formatMissingReport(missing, countable, dropThreshold);
     return { ok: false, missing, reason };
 }
 /**
@@ -143,11 +181,14 @@ function extractDistinctiveTokens(snippet) {
 }
 /**
  * Format a human-readable diff report for the realize pipeline to print
- * when the structural validator rejects an LLM output.
+ * when the structural validator rejects an LLM output (drop fraction
+ * exceeded the threshold).
  */
-function formatMissingReport(missing) {
+function formatMissingReport(missing, countable, dropThreshold) {
     const lines = [];
-    lines.push(`LLM output dropped or rewrote ${missing.length} pre-baked convention snippet${missing.length === 1 ? '' : 's'}:`);
+    const pct = Math.round((missing.length / countable) * 100);
+    lines.push(`LLM output dropped or rewrote ${missing.length}/${countable} pre-baked convention snippet${countable === 1 ? '' : 's'} ` +
+        `(${pct}%, over the ${Math.round(dropThreshold * 100)}% threshold):`);
     for (const m of missing) {
         lines.push('');
         lines.push(`  Step ${m.stepNum}: ${m.stepText}`);
@@ -160,8 +201,10 @@ function formatMissingReport(missing) {
         }
     }
     lines.push('');
-    lines.push('The convention matcher is deterministic; pre-baked snippets must be preserved verbatim. ' +
-        'If you believe the matcher is wrong for this case, fix the convention pattern in step-conventions.ts.');
+    lines.push('The convention matcher is deterministic; pre-baked snippets should be preserved verbatim. ' +
+        'A minority of drops is tolerated (see SPECVERSE_REALIZE_STRUCTURAL_DROP_THRESHOLD); this owner ' +
+        'exceeded that. If you believe the matcher is wrong for this case, fix the convention pattern ' +
+        'in step-conventions.ts.');
     return lines.join('\n');
 }
 //# sourceMappingURL=structural-validator.js.map

package/dist/realize/structural-validator.js.map

@@ -1 +1 @@
-{"version":3,"file":"structural-validator.js","sourceRoot":"","sources":["../../src/realize/structural-validator.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"structural-validator.js","sourceRoot":"","sources":["../../src/realize/structural-validator.ts"],"names":[],"mappings":"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"}

package/libs/instance-factories/cli/templates/commander/cli-entry-generator.ts

@@ -67,20 +67,19 @@ import { fileURLToPath } from 'url';
 import { dirname, join } from 'path';
 ${imports}
 
-// Read version: env var (set by bin entry point) or walk up to find package.json
+// Read version: walk up to find the @specverse/self package.json,
+// fall back to the build-time interpolation when not found.
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = dirname(__filename);
-let _version = process.env.SPECVERSE_VERSION || '${version}';
-if (_version === '${version}') {
-  try {
-    for (const rel of ['../../package.json', '../../../package.json', '../../../../package.json', '../../../../../package.json']) {
-      try {
-        const pkg = JSON.parse(readFileSync(join(__dirname, rel), 'utf8'));
-        if (pkg.name === '@specverse/self' && pkg.version) { _version = pkg.version; break; }
-      } catch { /* try next */ }
-    }
-  } catch { /* use fallback */ }
-}
+let _version = '${version}';
+try {
+  for (const rel of ['../../package.json', '../../../package.json', '../../../../package.json', '../../../../../package.json']) {
+    try {
+      const pkg = JSON.parse(readFileSync(join(__dirname, rel), 'utf8'));
+      if (pkg.name === '@specverse/self' && pkg.version) { _version = pkg.version; break; }
+    } catch { /* try next */ }
+  }
+} catch { /* use fallback */ }
 
 const program = new Command();
 

package/libs/instance-factories/cli/templates/commander/command-generator.ts

@@ -208,7 +208,7 @@ import type { ParserEngine } from '@specverse/types';`,
         } catch (qe: any) {
           // Don't let quint-gen module-loading issues block normal
           // validate (e.g. running against a much older engines version).
-          if (process.env.SPECVERSE_DEBUG) {
+          if (process.env.SPECVERSE_VERBOSE === '2') {
             console.warn('quint-gen check skipped:', qe?.message ?? String(qe));
           }
         }
@@ -377,7 +377,7 @@ import type { ParserEngine, InferenceEngine, RealizeEngine } from '@specverse/ty
             process.exit(1);
           }
         } catch (qe: any) {
-          if (process.env.SPECVERSE_DEBUG) {
+          if (process.env.SPECVERSE_VERBOSE === '2') {
             console.warn('quint-gen check skipped:', qe?.message ?? String(qe));
           }
         }

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

@@ -25,8 +25,10 @@ export default function generateFastifyRoutes(context: TemplateContext): string
   const isModelController = !!modelName;
   const handlerName = isModelController ? `${modelName}Controller` : controllerName;
 
-  // Generate imports
-  const imports = generateImports(controller, modelName, handlerName, isModelController, implType);
+  // Generate imports — defer until after handlers are built so we
+  // know whether FastifyRequest/FastifyReply are referenced.
+  // (Variable populated below.)
+  let imports: string;
 
   // Convert CURED operations to endpoints if endpoints don't exist
   let endpoints = controller.endpoints;
@@ -85,13 +87,30 @@ export default function generateFastifyRoutes(context: TemplateContext): string
     .map((endpoint: any) => generateRouteHandler(endpoint, modelName, handlerName, isModelController, implType, controllerName))
     .join('\n\n');
 
-  const externalRoutesExport = externalEndpoints.length > 0 ? `
+  // When there are no internal handlers, suppress unused-param TS6133 by
+  // prefixing `fastify`/`options` with `_` and skip the `handler` decl
+  // entirely. Same for the external-routes export.
+  const hasInternalHandlers = internalEndpoints.length > 0;
+  const hasExternalHandlers = externalEndpoints.length > 0;
+
+  // Determine which fastify types the emitted body actually references.
+  // FastifyInstance is always used (function signatures). FastifyRequest +
+  // FastifyReply only appear inside individual route handlers.
+  const handlersText = internalHandlers + '\n' + externalHandlers;
+  const usesFastifyRequest = /\bFastifyRequest\b/.test(handlersText);
+  const usesFastifyReply = /\bFastifyReply\b/.test(handlersText);
+  imports = generateImports(
+    controller, modelName, handlerName, isModelController, implType,
+    { usesFastifyRequest, usesFastifyReply },
+  );
+
+  const externalRoutesExport = hasExternalHandlers ? `
 /**
  * Mount the external (root-prefix) routes for this controller.
  *
  * Called by the generated main.ts at root scope (no prefix) so action.path
  * declarations like '/api/v2/auth/register' land at exactly that URL,
- * bypassing the controller's '/api/<plural>' prefix.
+ * bypassing the controller's '/api/<prefix>' prefix.
  */
 export async function registerExternalRoutes(
   fastify: FastifyInstance,
@@ -103,6 +122,15 @@ ${externalHandlers.split('\n').map(line => '  ' + line).join('\n')}
 }
 ` : '';
 
+  // Body fragments — only declare `handler` when there are handlers to
+  // reference it; suppress unused-param TS6133 by underscore-prefixing
+  // when the function body is empty.
+  const mainBody = hasInternalHandlers
+    ? `  const handler = ${isModelController ? 'options.controllers' : 'options.services'}.${handlerName};\n\n${internalHandlers.split('\n').map(line => '  ' + line).join('\n')}`
+    : '  // No endpoints declared on this controller — empty routes plugin.';
+  const mainFastifyParam = hasInternalHandlers ? 'fastify' : '_fastify';
+  const mainOptionsParam = hasInternalHandlers ? 'options' : '_options';
+
   // Generate the complete route file
   return `${imports}
 
@@ -114,28 +142,34 @@ ${externalHandlers.split('\n').map(line => '  ' + line).join('\n')}
  * Operations: ${controller.endpoints?.map((e: any) => e.operation).join(', ') || 'CURED'}
  */
 export default async function ${routeName.replace('Controller', '')}Routes(
-  fastify: FastifyInstance,
-  options: any
+  ${mainFastifyParam}: FastifyInstance,
+  ${mainOptionsParam}: any
 ) {
-  const handler = ${isModelController ? 'options.controllers' : 'options.services'}.${handlerName};
-
-${internalHandlers.split('\n').map(line => '  ' + line).join('\n')}
+${mainBody}
 }
 ${externalRoutesExport}`;
 }
 
 /**
- * Generate imports for the route file
+ * Generate imports for the route file. The fastify type imports are
+ * gated on actual handler usage to avoid unused-import TS6133 on
+ * empty-routes plugins (e.g. backend-only ProductController without
+ * any CURVED ops or custom actions).
  */
 function generateImports(
-  controller: any,
+  _controller: any,
   modelName: string,
-  handlerName: string,
-  isModelController: boolean,
-  implType: any
+  _handlerName: string,
+  _isModelController: boolean,
+  implType: any,
+  usage: { usesFastifyRequest: boolean; usesFastifyReply: boolean } =
+    { usesFastifyRequest: true, usesFastifyReply: true },
 ): string {
+  const fastifyTypes = ['FastifyInstance'];
+  if (usage.usesFastifyRequest) fastifyTypes.push('FastifyRequest');
+  if (usage.usesFastifyReply) fastifyTypes.push('FastifyReply');
   const imports = [
-    `import { FastifyInstance, FastifyRequest, FastifyReply } from 'fastify';`,
+    `import { ${fastifyTypes.join(', ')} } from 'fastify';`,
   ];
 
   // Don't import controller/service - they're passed via options

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

@@ -471,6 +471,22 @@ export async function generateAiBehaviorsFile(opts: {
       returnType = `{ ${fields} }`;
     }
 
+    // Build the validation harness EXACTLY as the function is finally
+    // emitted: real signature + the wrapper-added destructure + real
+    // return type. Pre-fix the harness was a bare
+    // `export async function X(input: any)` with NO destructure — but
+    // the LLM is explicitly told (see the retry-hint prose below) to
+    // emit ONLY the body that goes AFTER `const { ... } = input;`. So a
+    // valid body using bare input references (`return userId + 1`)
+    // would spuriously fail re-validation with "Cannot find name
+    // 'userId'", forcing regeneration / STUB. The harness must match
+    // emission or the gate rejects its own correct output.
+    const buildTestCode = (rawBody: string): string => {
+      const { signature, destructure } = buildSignatureAndDestructure(rawBody);
+      const destructureLine = destructure ? destructure + '\n' : '';
+      return `export async function ${functionName}(${signature}): Promise<${returnType}> {\n${destructureLine}${rawBody}\n}`;
+    };
+
     // Check cache first — skip Claude if we've generated this exact step before
     const key = cacheKey(step, modelName, operationName, functionName, inputs);
     let body: string | null = cacheRead(key);
@@ -480,7 +496,7 @@ export async function generateAiBehaviorsFile(opts: {
       // corrupted on disk OR the validation rules may have tightened
       // (e.g. tsc type checks added). A cache hit must still be re-validated
       // through both gates so old bodies don't leak past the new bar.
-      const testCode = `export async function ${functionName}(input: any): Promise<any> {\n${body}\n}`;
+      const testCode = buildTestCode(body);
       const syntaxError = await validateTypeScript(testCode);
       const typeError = syntaxError ? null : await validateTypeScriptTypes(testCode);
       const importError = (syntaxError || typeError) ? null : validateImports(testCode);
@@ -516,7 +532,7 @@ export async function generateAiBehaviorsFile(opts: {
           //      with the error message appended; only ONE retry to bound
           //      cost. If that still fails we keep the body but mark it
           //      AI-INVALID so the user sees it needs review.
-          const testCode = `export async function ${functionName}(input: any): Promise<any> {\n${body}\n}`;
+          const testCode = buildTestCode(body);
           const syntaxError = await validateTypeScript(testCode);
           if (syntaxError) {
             console.warn(`      [ai-validate] ${functionName} has syntax error: ${syntaxError}`);
@@ -547,7 +563,7 @@ export async function generateAiBehaviorsFile(opts: {
                   returnType,
                 });
                 if (retried) {
-                  const retryCode = `export async function ${functionName}(input: any): Promise<any> {\n${retried}\n}`;
+                  const retryCode = buildTestCode(retried);
                   const retrySyntaxError = await validateTypeScript(retryCode);
                   const retryTypeError = retrySyntaxError ? null : await validateTypeScriptTypes(retryCode);
                   const retryImportError = (retrySyntaxError || retryTypeError) ? null : validateImports(retryCode);

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

@@ -128,6 +128,14 @@ export function generateBehaviorWithHelpers(
 
   let body = parts.join('\n\n');
 
+  // Rename precondition-fetched `const X = await prisma.X.findUniqueOrThrow(...)`
+  // bindings to `_X` when the body has no other reference to `X`. The
+  // existence-check pattern emits a const for "{Model} exists" preconditions;
+  // if no subsequent precondition / step / postcondition references it, tsc
+  // raises TS6133 unused-decl. Renaming to _-prefix suppresses tsc's check
+  // while preserving the throw-on-missing semantics.
+  body = renameUnusedFindUniqueBindings(body);
+
   // Wrap in transaction if flagged
   if (behavior.transactional) {
     body = generateTransactionWrapper(body, context);
@@ -136,6 +144,50 @@ export function generateBehaviorWithHelpers(
   return { body, helperMethods, unmatchedSteps };
 }
 
+/**
+ * Post-process a method body string: find each `const X = await prisma.X.findUniqueOrThrow(...)`
+ * binding, count downstream references to `X`, and DROP the `const X =`
+ * binding entirely when the var is otherwise unused (keeping just the
+ * `await prisma.X.findUniqueOrThrow(...)` expression statement). The
+ * throw-on-missing semantic is preserved; tsc's noUnusedLocals stops
+ * complaining because there's no local to be unused.
+ *
+ * Why drop instead of rename to `_X`: TypeScript's `_`-prefix
+ * exemption only applies to `noUnusedParameters` (function arg names),
+ * NOT to `noUnusedLocals` (var decls). A `_invoice` const still trips
+ * TS6133 — dropping the binding is the actual fix.
+ *
+ * The `prisma.X` namespace reference inside the call is a model
+ * lookup — DO NOT touch it.
+ */
+function renameUnusedFindUniqueBindings(body: string): string {
+  const declRe = /\bconst\s+([a-zA-Z_][\w$]*)\s*=\s*await\s+prisma\.[\w.$]+\.findUniqueOrThrow\b/g;
+  const declared: string[] = [];
+  let m: RegExpExecArray | null;
+  while ((m = declRe.exec(body)) !== null) declared.push(m[1]!);
+  if (declared.length === 0) return body;
+
+  let out = body;
+  for (const name of declared) {
+    // Count occurrences of the bare identifier as a USAGE reference.
+    // The declaration line contributes 2: the `const NAME` binding
+    // and the `prisma.NAME` model reference. So 2 total = unused; 3+
+    // means at least one downstream reference.
+    const refRe = new RegExp(`\\b${name}\\b`, 'g');
+    const count = (out.match(refRe) ?? []).length;
+    if (count <= 2) {
+      // Drop the `const NAME =` prefix from the declaration line,
+      // leaving the `await prisma.NAME.findUniqueOrThrow(...);` as a
+      // pure side-effect statement.
+      out = out.replace(
+        new RegExp(`\\bconst\\s+${name}\\s*=\\s*(await\\s+prisma\\.)`),
+        `$1`,
+      );
+    }
+  }
+  return out;
+}
+
 /**
  * Generate precondition checks from natural-language strings.
  * Tracks declared variables to avoid duplicates and reuses fetched entities.
@@ -304,14 +356,22 @@ function inferLogicFromOperationName(context: BehaviorContext): string {
 
   if (op.startsWith('handle')) {
     const event = op.replace('handle', '');
+    // Use the first declared parameter name (typically `event`) instead
+    // of the hard-coded `params`. The method signature uses the spec-
+    // derived param name, so referencing `params` produces TS2304
+    // "Cannot find name" errors at compile time.
+    const eventParam = context.parameterNames?.[0] ?? '_event';
     return `    // Event handler: ${op}
-    console.log('[${context.serviceName}] Processing ${event}', params);
+    console.log('[${context.serviceName}] Processing ${event}', ${eventParam});
     return { handled: true, event: '${event}' };`;
   }
 
   if (op.startsWith('validate')) {
+    // Same fix as handle*: use the actual first parameter name. For
+    // validateX patterns the first param is conventionally `id`.
+    const idParam = context.parameterNames?.[0] ?? 'id';
     return `    // Validation: ${op}
-    const records = await prisma.${modelVar}.findMany({ where: { id: params.id } });
+    const records = await prisma.${modelVar}.findMany({ where: { id: ${idParam} } });
     return { valid: records.length > 0, checked: records.length };`;
   }
 

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

@@ -46,34 +46,61 @@ export default function generatePrismaController(context: TemplateContext): stri
   // Generate custom actions and collect AI behavior stubs
   const customActions = generateCustomActions(controller, modelName, modelVar);
 
+  // Build the class body first, then introspect to decide which
+  // top-of-file declarations are actually needed. Controllers with no
+  // CURVED ops and no prisma-using custom actions (e.g. a controller
+  // that only delegates to .ai.ts behaviour) end up with empty
+  // bodies — emitting `prisma` / `parseId` / `PrismaClient` import
+  // unconditionally produced TS6133 unused-decl errors at every
+  // realize run. Gating on actual body content drops those.
+  const classBody = [
+    generateValidateMethod(model, modelName),
+    curedOps.create ? generateCreateMethod(model, modelName, modelVar, prismaDelegate, controller, allModels) : '',
+    curedOps.retrieve ? generateRetrieveMethod(model, modelName, modelVar, prismaDelegate) : '',
+    curedOps.update ? generateUpdateMethod(model, modelName, modelVar, prismaDelegate, controller, allModels) : '',
+    curedOps.evolve ? generateEvolveMethod(model, modelName, modelVar, prismaDelegate, controller) : '',
+    curedOps.delete ? generateDeleteMethod(model, modelName, modelVar, prismaDelegate, controller) : '',
+    customActions.code,
+  ].filter(Boolean).join('\n  ');
+
+  const usesPrisma = /\bprisma\b/.test(classBody);
+  const usesParseId = /\bparseId\(/.test(classBody);
+  // Symbol-presence check on the actual class body — matches the
+  // `usesPrisma` pattern. Pre-fix this was a stub `hasEventPublishing`
+  // that returned true unconditionally, producing an unused-import
+  // TS6133 on every backend-only ProductController (validate-only,
+  // no CRUD, no eventBus.publish in the body).
+  const usesEventBus = /\beventBus\./.test(classBody);
+  const usesAiBehaviors = customActions.needsAiBehaviors;
+
+  // Build top-of-file declarations conditionally.
+  const imports = [
+    usesPrisma ? `import { PrismaClient } from '@prisma/client';` : '',
+    usesEventBus ? `import { eventBus } from '../events/eventBus.js';` : '',
+    usesAiBehaviors ? `import * as aiBehaviors from '../behaviors/${modelName}Controller.ai.js';` : '',
+  ].filter(Boolean).join('\n');
+
+  const declarations = [
+    usesPrisma ? `const prisma = new PrismaClient();` : '',
+    usesParseId
+      ? `/** Parse ID from string to the correct type for this model */
+function parseId(id: string): ${needsIntParse ? 'number' : 'string'} {
+  ${needsIntParse ? 'return parseInt(id, 10);' : 'return id;'}
+}`
+      : '',
+  ].filter(Boolean).join('\n\n');
+
   return `/**
  * ${controllerName}
  * Model-specific business logic for ${modelName}
  * ${controller.description || ''}
  */
-
-import { PrismaClient } from '@prisma/client';
-${hasEventPublishing(curedOps, controller) ? `import { eventBus } from '../events/eventBus.js';` : ''}
-${customActions.needsAiBehaviors ? `import * as aiBehaviors from '../behaviors/${modelName}Controller.ai.js';` : ''}
-
-const prisma = new PrismaClient();
-
-/** Parse ID from string to the correct type for this model */
-function parseId(id: string): ${needsIntParse ? 'number' : 'string'} {
-  ${needsIntParse ? 'return parseInt(id, 10);' : 'return id;'}
-}
-
-/**
+${imports ? '\n' + imports + '\n' : ''}
+${declarations ? declarations + '\n\n' : ''}/**
  * ${controllerName} class
  */
 export class ${controllerName} {
-  ${generateValidateMethod(model, modelName)}
-  ${curedOps.create ? generateCreateMethod(model, modelName, modelVar, prismaDelegate, controller, allModels) : ''}
-  ${curedOps.retrieve ? generateRetrieveMethod(model, modelName, modelVar, prismaDelegate) : ''}
-  ${curedOps.update ? generateUpdateMethod(model, modelName, modelVar, prismaDelegate, controller, allModels) : ''}
-  ${curedOps.evolve ? generateEvolveMethod(model, modelName, modelVar, prismaDelegate, controller) : ''}
-  ${curedOps.delete ? generateDeleteMethod(model, modelName, modelVar, prismaDelegate, controller) : ''}
-  ${customActions.code}
+  ${classBody}
 }
 
 // Export singleton instance

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@specverse/engines",
-  "version": "6.42.3",
+  "version": "6.60.1",
   "description": "SpecVerse toolchain — parser, inference, realize, generators, AI, registry, bundles",
   "type": "module",
   "main": "dist/index.js",
@@ -35,6 +35,14 @@
       "types": "./dist/realize/index.d.ts",
       "import": "./dist/realize/index.js"
     },
+    "./realize/post-emit-verify": {
+      "types": "./dist/realize/post-emit-verify/index.d.ts",
+      "import": "./dist/realize/post-emit-verify/index.js"
+    },
+    "./normalise": {
+      "types": "./dist/normalise/index.d.ts",
+      "import": "./dist/normalise/index.js"
+    },
     "./generators": {
       "types": "./dist/generators/index.d.ts",
       "import": "./dist/generators/index.js"