@specverse/engines 6.53.1 → 6.63.0

package/dist/realize/realize-context-snapshot.js

@@ -0,0 +1,96 @@
+/**
+ * Per-owner realize-context snapshot.
+ *
+ * Phase 3 of 2026-05-13-VERIFIER-DIAGNOSTIC-TREATMENT-SPLIT.
+ *
+ * The per-owner emit prompt has TARGET RUNTIME, [PRE-BAKED] step bullets,
+ * cross-service operation signatures, available capabilities, library
+ * whitelist — everything the LLM needs to emit a real action body. The
+ * post-emit feedback runner's `buildLlmReemit` historically had NONE of
+ * this; the reemit prompt provided only the previous bad output + the
+ * verifier errors.
+ *
+ * Empirical consequence: sonnet still bridged the gap via inference;
+ * smaller models (Ollama qwen3-coder:30b, MarrBox) drifted further from
+ * the realize-emit skill's contract, introducing cross-file tsc
+ * regressions when asked to fix STUB002 stubs (measured 2026-05-13 at
+ * engines 6.54.0 on idle-meta).
+ *
+ * Phase 3 closes the gap by SNAPSHOTTING the per-owner context to disk
+ * at emit time and READING it at reemit time. The snapshot lives at
+ * `<outputDir>/.realize-context/<OwnerName>.md` and contains a compact
+ * markdown blob — directly embeddable in the reemit user prompt.
+ *
+ * Decoupling: the snapshot writer (called from per-owner-runner)
+ * doesn't know about reemit; the snapshot loader (called from reemit
+ * factory) doesn't know about per-owner-emit. They share only the
+ * file layout convention.
+ */
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'fs';
+import { dirname, join } from 'path';
+const CONTEXT_DIR_NAME = '.realize-context';
+/**
+ * Render the context as a compact markdown blob suitable for direct
+ * embedding in the reemit prompt body. Mirrors the section headings
+ * used in the per-owner-emit prompt template so the LLM sees the same
+ * structural cues.
+ */
+export function formatContextSnapshot(ctx) {
+    const lines = [];
+    lines.push(`# Realize context for owner: ${ctx.ownerName}`);
+    lines.push('');
+    lines.push(`## TARGET RUNTIME`);
+    lines.push(ctx.targetRuntime);
+    lines.push('');
+    lines.push(`## AVAILABLE SPEC SURFACE`);
+    lines.push(ctx.availableSpecSurface);
+    lines.push('');
+    lines.push(`## AVAILABLE CAPABILITIES`);
+    lines.push(ctx.availableCapabilities);
+    lines.push('');
+    lines.push(`## AVAILABLE CLIENTS`);
+    lines.push(ctx.availableClients);
+    lines.push('');
+    lines.push(`## ACTIONS`);
+    lines.push(ctx.perActionScaffolding);
+    return lines.join('\n');
+}
+/** Resolve the per-owner snapshot path. Owner names are
+ *  always TypeScript identifiers, so no path-sanitization concerns. */
+function snapshotPath(outputDir, ownerName) {
+    return join(outputDir, CONTEXT_DIR_NAME, `${ownerName}.md`);
+}
+/**
+ * Persist a context snapshot to disk. Best-effort — caller should
+ * never crash on snapshot failure (the reemit prompt degrades to the
+ * pre-Phase-3 behavior cleanly).
+ */
+export function writeContextSnapshot(outputDir, ctx) {
+    try {
+        const path = snapshotPath(outputDir, ctx.ownerName);
+        const dir = dirname(path);
+        if (!existsSync(dir))
+            mkdirSync(dir, { recursive: true });
+        writeFileSync(path, formatContextSnapshot(ctx));
+    }
+    catch {
+        // best-effort; reemit falls back to the Phase 1/2 prompt shape
+    }
+}
+/**
+ * Load a previously-written snapshot. Returns the raw markdown blob,
+ * or `null` if no snapshot exists for the owner. Callers (the reemit
+ * factory) include the blob in the prompt body when present.
+ */
+export function loadContextSnapshot(outputDir, ownerName) {
+    try {
+        const path = snapshotPath(outputDir, ownerName);
+        if (!existsSync(path))
+            return null;
+        return readFileSync(path, 'utf8');
+    }
+    catch {
+        return null;
+    }
+}
+//# sourceMappingURL=realize-context-snapshot.js.map

package/dist/realize/realize-context-snapshot.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"realize-context-snapshot.js","sourceRoot":"","sources":["../../src/realize/realize-context-snapshot.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AAEH,OAAO,EAAE,UAAU,EAAE,SAAS,EAAE,YAAY,EAAE,aAAa,EAAE,MAAM,IAAI,CAAC;AACxE,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,MAAM,MAAM,CAAC;AAErC,MAAM,gBAAgB,GAAG,kBAAkB,CAAC;AAyB5C;;;;;GAKG;AACH,MAAM,UAAU,qBAAqB,CAAC,GAAwB;IAC5D,MAAM,KAAK,GAAa,EAAE,CAAC;IAC3B,KAAK,CAAC,IAAI,CAAC,gCAAgC,GAAG,CAAC,SAAS,EAAE,CAAC,CAAC;IAC5D,KAAK,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;IACf,KAAK,CAAC,IAAI,CAAC,mBAAmB,CAAC,CAAC;IAChC,KAAK,CAAC,IAAI,CAAC,GAAG,CAAC,aAAa,CAAC,CAAC;IAC9B,KAAK,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;IACf,KAAK,CAAC,IAAI,CAAC,2BAA2B,CAAC,CAAC;IACxC,KAAK,CAAC,IAAI,CAAC,GAAG,CAAC,oBAAoB,CAAC,CAAC;IACrC,KAAK,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;IACf,KAAK,CAAC,IAAI,CAAC,2BAA2B,CAAC,CAAC;IACxC,KAAK,CAAC,IAAI,CAAC,GAAG,CAAC,qBAAqB,CAAC,CAAC;IACtC,KAAK,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;IACf,KAAK,CAAC,IAAI,CAAC,sBAAsB,CAAC,CAAC;IACnC,KAAK,CAAC,IAAI,CAAC,GAAG,CAAC,gBAAgB,CAAC,CAAC;IACjC,KAAK,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;IACf,KAAK,CAAC,IAAI,CAAC,YAAY,CAAC,CAAC;IACzB,KAAK,CAAC,IAAI,CAAC,GAAG,CAAC,oBAAoB,CAAC,CAAC;IACrC,OAAO,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;AAC1B,CAAC;AAED;uEACuE;AACvE,SAAS,YAAY,CAAC,SAAiB,EAAE,SAAiB;IACxD,OAAO,IAAI,CAAC,SAAS,EAAE,gBAAgB,EAAE,GAAG,SAAS,KAAK,CAAC,CAAC;AAC9D,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,oBAAoB,CAClC,SAAiB,EACjB,GAAwB;IAExB,IAAI,CAAC;QACH,MAAM,IAAI,GAAG,YAAY,CAAC,SAAS,EAAE,GAAG,CAAC,SAAS,CAAC,CAAC;QACpD,MAAM,GAAG,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;QAC1B,IAAI,CAAC,UAAU,CAAC,GAAG,CAAC;YAAE,SAAS,CAAC,GAAG,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;QAC1D,aAAa,CAAC,IAAI,EAAE,qBAAqB,CAAC,GAAG,CAAC,CAAC,CAAC;IAClD,CAAC;IAAC,MAAM,CAAC;QACP,+DAA+D;IACjE,CAAC;AACH,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,mBAAmB,CACjC,SAAiB,EACjB,SAAiB;IAEjB,IAAI,CAAC;QACH,MAAM,IAAI,GAAG,YAAY,CAAC,SAAS,EAAE,SAAS,CAAC,CAAC;QAChD,IAAI,CAAC,UAAU,CAAC,IAAI,CAAC;YAAE,OAAO,IAAI,CAAC;QACnC,OAAO,YAAY,CAAC,IAAI,EAAE,MAAM,CAAC,CAAC;IACpC,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,IAAI,CAAC;IACd,CAAC;AACH,CAAC"}

package/dist/realize/structural-validator.d.ts

@@ -39,9 +39,17 @@ export interface PrebakedSnippet {
     /** The pre-baked TypeScript snippet. The matcher's `.call` string. */
     snippet: string;
 }
-/** Outcome of the structural-preservation check. */
+/** Outcome of the structural-preservation check.
+ *
+ *  `ok: true` with a non-empty `warnings` array means the LLM dropped
+ *  SOME pre-baked snippets but stayed at or under the drop-fraction
+ *  threshold — the output is accepted (no γ-fallback) but the dropped
+ *  snippets are surfaced so the caller can log them. `ok: false` means
+ *  the drop fraction exceeded the threshold: the LLM substantially
+ *  ignored the scaffolding and the owner should γ-fall-back. */
 export type StructuralValidationResult = {
     ok: true;
+    warnings?: MissingSnippet[];
 } | {
     ok: false;
     missing: MissingSnippet[];
@@ -56,6 +64,27 @@ export interface MissingSnippet {
     /** The closest match found in the LLM body, or null when no near-match. */
     closestMatch: string | null;
 }
+/**
+ * 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 declare const DEFAULT_STRUCTURAL_DROP_THRESHOLD = 0.5;
 /**
  * Validate that every pre-baked snippet appears in the LLM-emitted body.
  *
@@ -64,8 +93,13 @@ export interface MissingSnippet {
  * 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 declare function validateLlmOutputPreservesConventions(llmBody: string, prebakedSnippets: PrebakedSnippet[]): StructuralValidationResult;
+export declare function validateLlmOutputPreservesConventions(llmBody: string, prebakedSnippets: PrebakedSnippet[], dropThreshold?: number): StructuralValidationResult;
 //# sourceMappingURL=structural-validator.d.ts.map

package/dist/realize/structural-validator.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"structural-validator.d.ts","sourceRoot":"","sources":["../../src/realize/structural-validator.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AAEH,2EAA2E;AAC3E,MAAM,WAAW,eAAe;IAC9B,0EAA0E;IAC1E,OAAO,EAAE,MAAM,CAAC;IAChB,qDAAqD;IACrD,QAAQ,EAAE,MAAM,CAAC;IACjB,sEAAsE;IACtE,OAAO,EAAE,MAAM,CAAC;CACjB;AAED,oDAAoD;AACpD,MAAM,MAAM,0BAA0B,GAClC;IAAE,EAAE,EAAE,IAAI,CAAA;CAAE,GACZ;IAAE,EAAE,EAAE,KAAK,CAAC;IAAC,OAAO,EAAE,cAAc,EAAE,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,CAAC;AAE7D,kCAAkC;AAClC,MAAM,WAAW,cAAc;IAC7B,OAAO,EAAE,MAAM,CAAC;IAChB,QAAQ,EAAE,MAAM,CAAC;IACjB,sDAAsD;IACtD,QAAQ,EAAE,MAAM,CAAC;IACjB,2EAA2E;IAC3E,YAAY,EAAE,MAAM,GAAG,IAAI,CAAC;CAC7B;AAuBD;;;;;;;;;;GAUG;AACH,wBAAgB,qCAAqC,CACnD,OAAO,EAAE,MAAM,EACf,gBAAgB,EAAE,eAAe,EAAE,GAClC,0BAA0B,CAiD5B"}
+{"version":3,"file":"structural-validator.d.ts","sourceRoot":"","sources":["../../src/realize/structural-validator.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AAEH,2EAA2E;AAC3E,MAAM,WAAW,eAAe;IAC9B,0EAA0E;IAC1E,OAAO,EAAE,MAAM,CAAC;IAChB,qDAAqD;IACrD,QAAQ,EAAE,MAAM,CAAC;IACjB,sEAAsE;IACtE,OAAO,EAAE,MAAM,CAAC;CACjB;AAED;;;;;;;gEAOgE;AAChE,MAAM,MAAM,0BAA0B,GAClC;IAAE,EAAE,EAAE,IAAI,CAAC;IAAC,QAAQ,CAAC,EAAE,cAAc,EAAE,CAAA;CAAE,GACzC;IAAE,EAAE,EAAE,KAAK,CAAC;IAAC,OAAO,EAAE,cAAc,EAAE,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,CAAC;AAE7D,kCAAkC;AAClC,MAAM,WAAW,cAAc;IAC7B,OAAO,EAAE,MAAM,CAAC;IAChB,QAAQ,EAAE,MAAM,CAAC;IACjB,sDAAsD;IACtD,QAAQ,EAAE,MAAM,CAAC;IACjB,2EAA2E;IAC3E,YAAY,EAAE,MAAM,GAAG,IAAI,CAAC;CAC7B;AAuBD;;;;;;;;;;;;;;;;;;;GAmBG;AACH,eAAO,MAAM,iCAAiC,MAAM,CAAC;AAErD;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,qCAAqC,CACnD,OAAO,EAAE,MAAM,EACf,gBAAgB,EAAE,eAAe,EAAE,EACnC,aAAa,GAAE,MAA0C,GACxD,0BAA0B,CA8D5B"}

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/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/_shared/step-matching.ts

@@ -30,6 +30,49 @@ export function toVar(name: string): string {
   return name.charAt(0).toLowerCase() + name.slice(1);
 }
 
+/**
+ * Common English adjectives/articles that can leak into entity-noun
+ * extraction from NL spec steps. The matcher's pattern fragments use
+ * this to skip a leading adjective when capturing the entity noun, so
+ * "Create new Player with…" extracts `Player`, not `new`.
+ *
+ * Concern-separation note: this is NL-input-side. The TS-output-side
+ * counterpart is `TS_RESERVED_WORDS` from `@specverse/types`. Don't
+ * merge the two lists — they have distinct consumers and tuning
+ * lifecycles. NL adjectives are open-ended (extend as we see leakage);
+ * reserved identifiers are fixed by the target language spec.
+ */
+export const NL_LEADING_ADJECTIVES: readonly string[] = [
+  'new', 'existing', 'current', 'the', 'a', 'an',
+];
+
+/**
+ * Regex fragment for the optional leading-adjective skip, e.g.
+ *   pattern: new RegExp(`^create\\s+${NL_ADJECTIVE_PREFIX}(\\w+)…`, 'i')
+ *
+ * Patterns that prefer regex literals can inline the equivalent group:
+ *   /^create\s+(?:(?:new|existing|current|the|a|an)\s+)?(\w+)…/i
+ * — keep this in sync if you do.
+ */
+export const NL_ADJECTIVE_PREFIX = `(?:(?:${NL_LEADING_ADJECTIVES.join('|')})\\s+)?`;
+
+// Safe-identifier primitives live in `@specverse/types`:
+//   - `safeEntityName(name)`   → returns the lowerCamel identifier, or
+//                                 null when the name would emit a TS
+//                                 reserved word as an entity reference
+//                                 (`prisma.<X>.create`). Use this in
+//                                 step-conventions' `generateCall` to
+//                                 replace the toVar+predicate pair.
+//   - `safeFunctionName(name)` → returns `{ name, reserved }`; on
+//                                 reserved input, name is suffix-renamed
+//                                 (`delete` → `delete_`) and the caller
+//                                 emits a re-export so consumers
+//                                 importing the original name still
+//                                 resolve. Used by the γ-stub renderers.
+// Import directly from `@specverse/types`; this file no longer
+// re-exports the predicate (was `isUnsafeEntityName`, retired in favour
+// of the more expressive primitives).
+
 // #54 (2026-05-10): SharedStepContext, SharedConvention, MatchResult
 // and MatcherFn are now canonical in @specverse/types. Re-exported here
 // so existing dynamic-import call sites that grab types from this path

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

@@ -21,6 +21,7 @@ import {
   type SharedConvention,
   type SharedStepContext,
 } from '../_shared/step-matching.js';
+import { safeEntityName } from '@specverse/types';
 
 export type MongoStepConvention = SharedConvention<MongoStepContext>;
 
@@ -178,7 +179,8 @@ export const MONGO_STEP_CONVENTIONS: MongoStepConvention[] = [
     generateCall: (m, ctx) => {
       const model = m[1];
       const field = m[2];
-      const modelVar = toVar(model);
+      const modelVar = safeEntityName(model);
+      if (!modelVar) return '';
       const collection = toCollection(model);
       const params = ctx.parameterNames || [];
       const declared = ctx.declaredVars || new Set();
@@ -212,7 +214,8 @@ export const MONGO_STEP_CONVENTIONS: MongoStepConvention[] = [
       const model = m[1];
       const f1 = m[2];
       const f2 = m[3];
-      const modelVar = toVar(model);
+      const modelVar = safeEntityName(model);
+      if (!modelVar) return '';
       const collection = toCollection(model);
       const declared = ctx.declaredVars || new Set();
       if (declared.has(modelVar)) {
@@ -246,13 +249,19 @@ export const MONGO_STEP_CONVENTIONS: MongoStepConvention[] = [
   },
 
   // --- Create model record ---
-  // Matches: "Create X", "Create new X with ..."
+  // Matches: "Create X", "Create new X with ...", "Create existing X with ...".
+  // Leading-adjective skip kept in sync with NL_LEADING_ADJECTIVES in
+  // _shared/step-matching.ts. Reserved-word safety net via
+  // safeEntityName from @specverse/types — returns null when the extracted noun would emit a TS reserved word
+  // (e.g. mis-parsed adjectives) by returning '' so the matcher falls
+  // through to the AI [WRITE] fallback.
   {
     name: 'create',
-    pattern: /^create\s+(?:new\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 collection = toCollection(model);
       const params = ctx.parameterNames || [];
       const declared = ctx.declaredVars || new Set();
@@ -272,12 +281,13 @@ export const MONGO_STEP_CONVENTIONS: MongoStepConvention[] = [
   // lets the AI layer handle it.
   {
     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 '';  // signal "not really matched"
       const collection = toCollection(model);
       const val = resolveValue(rawValue, ctx);
@@ -292,11 +302,12 @@ export const MONGO_STEP_CONVENTIONS: MongoStepConvention[] = [
   // --- Update field timestamp (e.g. "Update device lastLoginAt 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 collection = toCollection(model);
       return `    // Step ${ctx.stepNum}: Update ${model}.${field} timestamp
@@ -310,10 +321,11 @@ export const MONGO_STEP_CONVENTIONS: MongoStepConvention[] = [
   // --- Generic "Update X" (writes args back to record) ---
   {
     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 collection = toCollection(model);
       return `    // Step ${ctx.stepNum}: Update ${model}
@@ -327,10 +339,11 @@ export const MONGO_STEP_CONVENTIONS: MongoStepConvention[] = [
   // --- 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 collection = toCollection(model);
       return `    // Step ${ctx.stepNum}: Delete ${model}
@@ -349,7 +362,8 @@ export const MONGO_STEP_CONVENTIONS: MongoStepConvention[] = [
     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 collection = toCollection(model);
       return `    // Step ${ctx.stepNum}: Transition ${model} to ${state}
@@ -424,7 +438,8 @@ export const MONGO_STEP_CONVENTIONS: MongoStepConvention[] = [
     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 target = safeEntityName(m[1].replace(/\s+(.)/g, (_, c) => c.toUpperCase()));
+      if (!target) return '';
       const collection = toCollection(target);
       const recordSrc = mostRecentStepResult(ctx) ?? 'args';
       return `    // Step ${ctx.stepNum}: Persist ${m[1]}
@@ -442,7 +457,8 @@ export const MONGO_STEP_CONVENTIONS: MongoStepConvention[] = [
     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 collection = toCollection(Model);
       if (!ctx.declaredVars?.has(modelVar)) return '';  // need prior find
@@ -472,7 +488,8 @@ export const MONGO_STEP_CONVENTIONS: MongoStepConvention[] = [
     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 collection = toCollection(m[1]);
       if (!ctx.declaredVars?.has(modelVar)) return '';
@@ -547,7 +564,8 @@ export const MONGO_STEP_CONVENTIONS: MongoStepConvention[] = [
     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 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
@@ -612,9 +630,11 @@ export const MONGO_STEP_CONVENTIONS: MongoStepConvention[] = [
     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} });`;
     },
   },