@specverse/engines 6.53.1 → 6.60.1

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":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AA2BH;;;;;;;;;;GAUG;AACH,SAAS,YAAY,CAAC,IAAY;IAChC,OAAO,IAAI;SACR,KAAK,CAAC,IAAI,CAAC;SACX,GAAG,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,IAAI,CAAC,IAAI,EAAE,CAAC;SAC1B,MAAM,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,IAAI,CAAC,MAAM,GAAG,CAAC,IAAI,CAAC,IAAI,CAAC,UAAU,CAAC,IAAI,CAAC,CAAC;SAC3D,IAAI,CAAC,GAAG,CAAC;SACT,OAAO,CAAC,MAAM,EAAE,GAAG,CAAC;SACpB,IAAI,EAAE,CAAC;AACZ,CAAC;AAED;;;;;;;;;;GAUG;AACH,MAAM,UAAU,qCAAqC,CACnD,OAAe,EACf,gBAAmC;IAEnC,IAAI,gBAAgB,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QAClC,OAAO,EAAE,EAAE,EAAE,IAAI,EAAE,CAAC;IACtB,CAAC;IAED,MAAM,YAAY,GAAG,YAAY,CAAC,OAAO,CAAC,CAAC;IAC3C,MAAM,OAAO,GAAqB,EAAE,CAAC;IAErC,KAAK,MAAM,OAAO,IAAI,gBAAgB,EAAE,CAAC;QACvC,MAAM,QAAQ,GAAG,YAAY,CAAC,OAAO,CAAC,OAAO,CAAC,CAAC;QAC/C,IAAI,QAAQ,CAAC,MAAM,KAAK,CAAC;YAAE,SAAS,CAAC,6BAA6B;QAElE,IAAI,YAAY,CAAC,QAAQ,CAAC,QAAQ,CAAC,EAAE,CAAC;YACpC,SAAS;QACX,CAAC;QAED,gEAAgE;QAChE,qEAAqE;QACrE,kEAAkE;QAClE,oEAAoE;QACpE,kEAAkE;QAClE,gEAAgE;QAChE,qBAAqB;QACrB,MAAM,iBAAiB,GAAG,wBAAwB,CAAC,OAAO,CAAC,OAAO,CAAC,CAAC;QACpE,IAAI,YAAY,GAAkB,IAAI,CAAC;QACvC,KAAK,MAAM,GAAG,IAAI,iBAAiB,EAAE,CAAC;YACpC,KAAK,MAAM,IAAI,IAAI,OAAO,CAAC,KAAK,CAAC,IAAI,CAAC,EAAE,CAAC;gBACvC,IAAI,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC,EAAE,CAAC;oBACvB,YAAY,GAAG,IAAI,CAAC,IAAI,EAAE,CAAC;oBAC3B,MAAM;gBACR,CAAC;YACH,CAAC;YACD,IAAI,YAAY;gBAAE,MAAM;QAC1B,CAAC;QAED,OAAO,CAAC,IAAI,CAAC;YACX,OAAO,EAAE,OAAO,CAAC,OAAO;YACxB,QAAQ,EAAE,OAAO,CAAC,QAAQ;YAC1B,QAAQ,EAAE,OAAO,CAAC,OAAO,CAAC,IAAI,EAAE;YAChC,YAAY;SACb,CAAC,CAAC;IACL,CAAC;IAED,IAAI,OAAO,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QACzB,OAAO,EAAE,EAAE,EAAE,IAAI,EAAE,CAAC;IACtB,CAAC;IAED,MAAM,MAAM,GAAG,mBAAmB,CAAC,OAAO,CAAC,CAAC;IAC5C,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,OAAO,EAAE,MAAM,EAAE,CAAC;AACxC,CAAC;AAED;;;;;;;;GAQG;AACH,SAAS,wBAAwB,CAAC,OAAe;IAC/C,uEAAuE;IACvE,MAAM,UAAU,GAAG,OAAO,CAAC,KAAK,CAAC,0CAA0C,CAAC,CAAC;IAC7E,MAAM,OAAO,GAAa,UAAU,CAAC,CAAC,CAAC,KAAK,CAAC,IAAI,CAAC,UAAU,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC;IACnE,IAAI,OAAO,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,EAAE,CAAC;IACpC,MAAM,GAAG,GAAa,EAAE,CAAC;IACzB,iEAAiE;IACjE,oEAAoE;IACpE,sDAAsD;IACtD,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,MAAM,GAAG,CAAC,CAAC,MAAM,CAAC,CAAC;IAC5C,MAAM,OAAO,GAAG,OAAO,CAAC,CAAC,CAAE,CAAC;IAC5B,GAAG,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;IAClB,MAAM,QAAQ,GAAG,OAAO,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC;IACpC,KAAK,IAAI,CAAC,GAAG,QAAQ,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC,IAAI,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC;QAC9C,GAAG,CAAC,IAAI,CAAC,QAAQ,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC;IAC3C,CAAC;IACD,iEAAiE;IACjE,iEAAiE;IACjE,kCAAkC;IAClC,KAAK,MAAM,CAAC,IAAI,OAAO,CAAC,KAAK,CAAC,CAAC,CAAC,EAAE,CAAC;QACjC,IAAI,CAAC,GAAG,CAAC,QAAQ,CAAC,CAAC,CAAC;YAAE,GAAG,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;IACpC,CAAC;IACD,OAAO,GAAG,CAAC;AACb,CAAC;AAED;;;GAGG;AACH,SAAS,mBAAmB,CAAC,OAAyB;IACpD,MAAM,KAAK,GAAa,EAAE,CAAC;IAC3B,KAAK,CAAC,IAAI,CACR,iCAAiC,OAAO,CAAC,MAAM,gCAAgC,OAAO,CAAC,MAAM,KAAK,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,GAAG,GAAG,CAClH,CAAC;IACF,KAAK,MAAM,CAAC,IAAI,OAAO,EAAE,CAAC;QACxB,KAAK,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;QACf,KAAK,CAAC,IAAI,CAAC,UAAU,CAAC,CAAC,OAAO,KAAK,CAAC,CAAC,QAAQ,EAAE,CAAC,CAAC;QACjD,KAAK,CAAC,IAAI,CAAC,4BAA4B,CAAC,CAAC,QAAQ,CAAC,OAAO,CAAC,KAAK,EAAE,UAAU,CAAC,EAAE,CAAC,CAAC;QAChF,IAAI,CAAC,CAAC,YAAY,EAAE,CAAC;YACnB,KAAK,CAAC,IAAI,CAAC,4BAA4B,CAAC,CAAC,YAAY,EAAE,CAAC,CAAC;QAC3D,CAAC;aAAM,CAAC;YACN,KAAK,CAAC,IAAI,CAAC,gDAAgD,CAAC,CAAC;QAC/D,CAAC;IACH,CAAC;IACD,KAAK,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;IACf,KAAK,CAAC,IAAI,CACR,0FAA0F;QAC1F,uGAAuG,CACxG,CAAC;IACF,OAAO,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;AAC1B,CAAC"}
+{"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/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/controller-generator.ts

@@ -65,7 +65,12 @@ export default function generatePrismaController(context: TemplateContext): stri
 
   const usesPrisma = /\bprisma\b/.test(classBody);
   const usesParseId = /\bparseId\(/.test(classBody);
-  const usesEventBus = hasEventPublishing(curedOps, controller);
+  // 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.

package/package.json

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