@specverse/engines 6.42.3 → 6.60.1

package/dist/realize/post-emit-verify/feedback-runner.js

@@ -0,0 +1,232 @@
+/**
+ * Post-emit feedback runner.
+ *
+ * After all per-owner emits complete, this orchestrator:
+ *   1. Runs all applicable verifiers against the realized output
+ *   2. Groups errors by source file → owning entity
+ *   3. For each owner with errors, asks the caller to re-emit the
+ *      file via the provided `reemit` callback (with errors + previous
+ *      content as context — the caller builds the LLM prompt)
+ *   4. Re-runs verifiers + records per-pass deltas
+ *   5. Bounded retries (default 1 pass)
+ *
+ * The runner is intentionally framework-agnostic: it does NOT call any
+ * specific LLM provider or import the per-owner-emit module. The
+ * caller wires `reemit` to whatever re-emission path makes sense for
+ * the project. This keeps the runner testable in isolation and
+ * forward-compatible with future re-emit strategies.
+ *
+ * Rollback policy: if a re-emit INCREASES error count for that file,
+ * the runner rolls back to the previous content. The LLM doesn't get
+ * to make things worse.
+ */
+import { readFileSync, writeFileSync } from 'fs';
+import { join } from 'path';
+import { runAllVerifiers } from './verifier-manifest.js';
+/**
+ * Default file→owner mapping for the SpecVerse TypeScript layout:
+ *   `backend/src/behaviors/<Owner>.ai.ts` → `<Owner>`
+ *   `<anything>/<Owner>.ai.ts` → `<Owner>` (relaxed fallback)
+ * Returns null for files that don't match.
+ */
+export function defaultMapFileToOwner(file) {
+    const m = /(?:^|\/)([A-Za-z_][\w-]*)\.ai\.ts$/.exec(file);
+    return m ? m[1] : null;
+}
+/**
+ * Default treatment policy (Phase 2 of
+ * 2026-05-13-VERIFIER-DIAGNOSTIC-TREATMENT-SPLIT):
+ *
+ *   - `STUB002` (LLM-throw stubs) → `surface-spec-gap`. The LLM already
+ *     signaled "I lack context for this action" via the throw message;
+ *     re-prompting either no-ops or hallucinates cross-file regressions.
+ *     Better to tell the user about the gap so they can adjust the
+ *     spec / manifest / provider choice.
+ *
+ *   - Everything else (tsc errors, STUB001 γ-fallback, STUB003 trivial-
+ *     return, STUB004 empty-body, future codes) → `auto-reemit`.
+ *
+ * Override at the call site for testing or for advanced policies.
+ */
+export function defaultTreatmentSelector(error) {
+    if (error.code === 'STUB002')
+        return 'surface-spec-gap';
+    return 'auto-reemit';
+}
+/**
+ * Group verifier errors by file (preserving error order within each
+ * file). Files with no errors are absent from the map.
+ */
+function groupErrorsByFile(errors) {
+    const out = new Map();
+    for (const e of errors) {
+        let bucket = out.get(e.file);
+        if (!bucket) {
+            bucket = [];
+            out.set(e.file, bucket);
+        }
+        bucket.push(e);
+    }
+    return out;
+}
+/**
+ * Sum the error count for a specific file across a result set.
+ */
+function errorCountForFile(errors, file) {
+    let n = 0;
+    for (const e of errors)
+        if (e.file === file)
+            n++;
+    return n;
+}
+export async function runPostEmitFeedback(ctx, reemit, options = {}) {
+    const maxPasses = options.maxPasses ?? 1;
+    const maxFilesPerPass = options.maxFilesPerPass ?? 20;
+    const mapFileToOwner = options.mapFileToOwner ?? defaultMapFileToOwner;
+    const enabledOverrides = options.enabledOverrides;
+    const treatmentSelector = options.treatmentSelector ?? defaultTreatmentSelector;
+    const passes = [];
+    const verifierNotes = [];
+    const specGaps = [];
+    const seenSpecGaps = new Set();
+    /** Pull out spec-gap classified errors into the result's specGaps[]
+     *  while leaving auto-reemit errors in place for the loop. Dedups
+     *  across passes (same error from re-running verifiers shouldn't
+     *  appear twice in the sidecar). */
+    function partitionErrors(errors) {
+        const actionable = [];
+        for (const e of errors) {
+            const strategy = treatmentSelector(e);
+            if (strategy === 'surface-spec-gap') {
+                const key = `${e.file}:${e.line ?? 0}:${e.col ?? 0}:${e.code}`;
+                if (!seenSpecGaps.has(key)) {
+                    seenSpecGaps.add(key);
+                    specGaps.push({
+                        ownerName: mapFileToOwner(e.file),
+                        file: e.file,
+                        ...(e.line !== undefined ? { line: e.line } : {}),
+                        ...(e.col !== undefined ? { col: e.col } : {}),
+                        code: e.code,
+                        message: e.message,
+                    });
+                }
+                continue;
+            }
+            if (strategy === 'skip')
+                continue;
+            actionable.push(e);
+        }
+        return actionable;
+    }
+    // Initial verifier pass.
+    let currentResults = await runAllVerifiers(ctx, enabledOverrides);
+    for (const r of currentResults) {
+        if (r.notes.length > 0)
+            verifierNotes.push({ verifierId: r.verifierId, notes: r.notes });
+    }
+    const initialErrorsRaw = currentResults.flatMap((r) => r.errors);
+    const initialErrors = partitionErrors(initialErrorsRaw);
+    let currentErrors = initialErrors;
+    for (let pass = 1; pass <= maxPasses; pass++) {
+        const errorsBefore = currentErrors.length;
+        if (errorsBefore === 0)
+            break;
+        const byFile = groupErrorsByFile(currentErrors);
+        const passResult = {
+            passNumber: pass,
+            errorsBefore,
+            errorsAfter: errorsBefore,
+            ownersAttempted: 0,
+            ownersImproved: 0,
+            ownersUnchanged: 0,
+            ownersRolledBack: 0,
+            ownersUnmappable: 0,
+            ownersReemitFailed: 0,
+            ownersOverBudget: 0,
+        };
+        // Per-file backup so we can roll back if the LLM makes it worse.
+        const backups = new Map();
+        // Apply the per-pass file budget. Iteration order over Map mirrors
+        // insertion order — which mirrors verifier emit order — so the
+        // first N files are deterministic across runs.
+        const fileEntries = [...byFile.entries()];
+        const allowed = fileEntries.slice(0, maxFilesPerPass);
+        const overBudget = fileEntries.slice(maxFilesPerPass);
+        passResult.ownersOverBudget = overBudget.length;
+        for (const [file, fileErrors] of allowed) {
+            const ownerName = mapFileToOwner(file);
+            if (!ownerName) {
+                passResult.ownersUnmappable++;
+                continue;
+            }
+            const absFile = join(ctx.outputDir, file);
+            let previousContent;
+            try {
+                previousContent = readFileSync(absFile, 'utf8');
+            }
+            catch {
+                passResult.ownersReemitFailed++;
+                continue;
+            }
+            passResult.ownersAttempted++;
+            const newContent = await reemit({
+                ownerName,
+                file,
+                errors: fileErrors,
+                previousContent,
+            });
+            if (!newContent) {
+                passResult.ownersReemitFailed++;
+                continue;
+            }
+            backups.set(file, previousContent);
+            writeFileSync(absFile, newContent);
+        }
+        // Re-run verifiers, then compare per-file error counts.
+        const newResults = await runAllVerifiers(ctx, enabledOverrides);
+        let newErrors = partitionErrors(newResults.flatMap((r) => r.errors));
+        // Rollback pass: any file whose error count INCREASED gets restored.
+        // Only consider files we actually attempted (within the budget).
+        const filesToRestore = [];
+        for (const [file, fileErrors] of allowed) {
+            const before = fileErrors.length;
+            const after = errorCountForFile(newErrors, file);
+            if (after > before && backups.has(file)) {
+                filesToRestore.push(file);
+                passResult.ownersRolledBack++;
+            }
+            else if (after < before) {
+                passResult.ownersImproved++;
+            }
+            else if (after === before && after > 0) {
+                passResult.ownersUnchanged++;
+            }
+        }
+        if (filesToRestore.length > 0) {
+            for (const file of filesToRestore) {
+                const absFile = join(ctx.outputDir, file);
+                writeFileSync(absFile, backups.get(file));
+            }
+            // Re-run verifiers one more time so the reported `errorsAfter`
+            // reflects the post-rollback state.
+            const finalResults = await runAllVerifiers(ctx, enabledOverrides);
+            newErrors = partitionErrors(finalResults.flatMap((r) => r.errors));
+        }
+        passResult.errorsAfter = newErrors.length;
+        passes.push(passResult);
+        currentResults = newResults;
+        currentErrors = newErrors;
+        // Early exit: if a pass produced no improvement, more passes
+        // unlikely to help.
+        if (passResult.errorsAfter >= passResult.errorsBefore)
+            break;
+    }
+    return {
+        initialErrors,
+        finalErrors: currentErrors,
+        passes,
+        verifierNotes,
+        specGaps,
+    };
+}
+//# sourceMappingURL=feedback-runner.js.map

package/dist/realize/post-emit-verify/feedback-runner.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"feedback-runner.js","sourceRoot":"","sources":["../../../src/realize/post-emit-verify/feedback-runner.ts"],"names":[],"mappings":"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"}

package/dist/realize/post-emit-verify/index.d.ts

@@ -0,0 +1,19 @@
+/**
+ * @specverse/engines/realize/post-emit-verify — post-emit verification
+ * + feedback runner.
+ *
+ * Generic framework for running compile / lint / typecheck verifiers
+ * on the realized output and feeding errors back to the LLM for a
+ * surgical fix pass.
+ *
+ * See `specverse-self/docs/proposals/...` (TBD) for the design rationale
+ * + empirical evidence from idle-meta 2026-05-13.
+ */
+export { type PostEmitVerifier, type VerifyContext, type VerifyError, type VerifyResult, type OwnerMapping, type TreatmentStrategy, type TreatmentSelector, type SpecGapEntry, } from './types.js';
+export { VERIFIERS, runAllVerifiers, findVerifier, } from './verifier-manifest.js';
+export { runPostEmitFeedback, defaultMapFileToOwner, defaultTreatmentSelector, type Reemit, type ReemitRequest, type FeedbackRunOptions, type FeedbackRunResult, type PassResult, } from './feedback-runner.js';
+export { TSC_VERIFIER } from './verifiers/tsc.js';
+export { buildLlmReemit, formatFeedbackPrompt, type BuildReemitOptions, } from './reemit.js';
+export { runDiagnostics, formatSummaryLine, appendSpecGaps, formatSpecGapLine, type RealizeQualitySidecar, type RealizeQualitySummary, type OwnerQualityEntry, type OwnerStubIssue, } from './diagnostics.js';
+export { STUB_COMPLETENESS_VERIFIER } from './verifiers/stub-completeness.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/realize/post-emit-verify/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/realize/post-emit-verify/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,OAAO,EACL,KAAK,gBAAgB,EACrB,KAAK,aAAa,EAClB,KAAK,WAAW,EAChB,KAAK,YAAY,EACjB,KAAK,YAAY,EACjB,KAAK,iBAAiB,EACtB,KAAK,iBAAiB,EACtB,KAAK,YAAY,GAClB,MAAM,YAAY,CAAC;AAEpB,OAAO,EACL,SAAS,EACT,eAAe,EACf,YAAY,GACb,MAAM,wBAAwB,CAAC;AAEhC,OAAO,EACL,mBAAmB,EACnB,qBAAqB,EACrB,wBAAwB,EACxB,KAAK,MAAM,EACX,KAAK,aAAa,EAClB,KAAK,kBAAkB,EACvB,KAAK,iBAAiB,EACtB,KAAK,UAAU,GAChB,MAAM,sBAAsB,CAAC;AAE9B,OAAO,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAElD,OAAO,EACL,cAAc,EACd,oBAAoB,EACpB,KAAK,kBAAkB,GACxB,MAAM,aAAa,CAAC;AAErB,OAAO,EACL,cAAc,EACd,iBAAiB,EACjB,cAAc,EACd,iBAAiB,EACjB,KAAK,qBAAqB,EAC1B,KAAK,qBAAqB,EAC1B,KAAK,iBAAiB,EACtB,KAAK,cAAc,GACpB,MAAM,kBAAkB,CAAC;AAE1B,OAAO,EAAE,0BAA0B,EAAE,MAAM,kCAAkC,CAAC"}

package/dist/realize/post-emit-verify/index.js

@@ -0,0 +1,18 @@
+/**
+ * @specverse/engines/realize/post-emit-verify — post-emit verification
+ * + feedback runner.
+ *
+ * Generic framework for running compile / lint / typecheck verifiers
+ * on the realized output and feeding errors back to the LLM for a
+ * surgical fix pass.
+ *
+ * See `specverse-self/docs/proposals/...` (TBD) for the design rationale
+ * + empirical evidence from idle-meta 2026-05-13.
+ */
+export { VERIFIERS, runAllVerifiers, findVerifier, } from './verifier-manifest.js';
+export { runPostEmitFeedback, defaultMapFileToOwner, defaultTreatmentSelector, } from './feedback-runner.js';
+export { TSC_VERIFIER } from './verifiers/tsc.js';
+export { buildLlmReemit, formatFeedbackPrompt, } from './reemit.js';
+export { runDiagnostics, formatSummaryLine, appendSpecGaps, formatSpecGapLine, } from './diagnostics.js';
+export { STUB_COMPLETENESS_VERIFIER } from './verifiers/stub-completeness.js';
+//# sourceMappingURL=index.js.map

package/dist/realize/post-emit-verify/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/realize/post-emit-verify/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAaH,OAAO,EACL,SAAS,EACT,eAAe,EACf,YAAY,GACb,MAAM,wBAAwB,CAAC;AAEhC,OAAO,EACL,mBAAmB,EACnB,qBAAqB,EACrB,wBAAwB,GAMzB,MAAM,sBAAsB,CAAC;AAE9B,OAAO,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAElD,OAAO,EACL,cAAc,EACd,oBAAoB,GAErB,MAAM,aAAa,CAAC;AAErB,OAAO,EACL,cAAc,EACd,iBAAiB,EACjB,cAAc,EACd,iBAAiB,GAKlB,MAAM,kBAAkB,CAAC;AAE1B,OAAO,EAAE,0BAA0B,EAAE,MAAM,kCAAkC,CAAC"}

package/dist/realize/post-emit-verify/reemit.d.ts

@@ -0,0 +1,82 @@
+/**
+ * Default `Reemit` implementation — builds a feedback prompt from
+ * verifier errors + previous file content and calls the LLM to
+ * re-emit a single file.
+ *
+ * The realize-emit skill (at ~/.claude/skills/realize-emit/) is
+ * auto-loaded by claude-cli when its description matches the prompt
+ * shape — that carries all the per-owner emission conventions
+ * (typing rules, _input convention, γ-stub shape, etc.) so the
+ * feedback re-emit benefits from the same guidance as the original
+ * emission.
+ *
+ * The prompt is intentionally minimal:
+ *   - Errors (verifier-formatted)
+ *   - Previous file content
+ *   - A request to re-emit
+ *
+ * Future iterations may augment with AVAILABLE SPEC SURFACE (cross-
+ * service signatures) when the errors are arity-shape — empirically,
+ * the skill + basic prompt suffices for most null-safety / type
+ * mismatch / unused-decl cases.
+ */
+import type { LanguageModel } from 'ai';
+import type { Reemit, ReemitRequest } from './feedback-runner.js';
+export interface BuildReemitOptions {
+    /** LLM model — same shared model used by per-owner-emit. */
+    model: LanguageModel;
+    /** Max retries per file when the LLM produces empty / unparseable
+     *  output. Default 1. */
+    maxAttempts?: number;
+    /** Per-call timeout. Default 3min — feedback re-emits are typically
+     *  faster than fresh emissions because the LLM has the previous
+     *  content to anchor on. */
+    timeoutMs?: number;
+    /**
+     * Skills whose content should be inlined into the system prompt for
+     * non-claude-cli providers. claude-cli auto-loads skills via
+     * filesystem-based resolution; other providers (`openai-compatible`,
+     * `anthropic`, `stub`) need explicit inlining of the skill content.
+     *
+     * Defaults to `['realize-emit']` — the realize-emit skill carries the
+     * per-owner emission CONSTRAINTS / GUIDANCE / EXAMPLE that's directly
+     * relevant to the feedback re-emit task (typing conventions, _input
+     * convention, γ-stub shape).
+     */
+    skills?: string[];
+    /**
+     * Optional context loader (Phase 3 of
+     * 2026-05-13-VERIFIER-DIAGNOSTIC-TREATMENT-SPLIT).
+     *
+     * For each owner whose file is being re-emitted, return the per-owner
+     * realize-context snapshot (TARGET RUNTIME + [PRE-BAKED] step bullets
+     * + cross-service surface + capabilities) as a markdown blob, or null
+     * if no snapshot exists. The returned blob is prepended to the
+     * reemit user prompt — same shape the original per-owner emit used.
+     *
+     * The default-built loader (in realize/index.ts) reads from
+     * `<outputDir>/.realize-context/<Owner>.md`. Tests may inject fakes.
+     */
+    contextLoader?: (ownerName: string) => string | null;
+}
+/**
+ * Build a `Reemit` callback that uses the provided LLM model.
+ *
+ * The returned closure can be passed straight to `runPostEmitFeedback`.
+ */
+export declare function buildLlmReemit(options: BuildReemitOptions): Reemit;
+/**
+ * Format the feedback prompt body. Caller's LLM provider (e.g.
+ * claude-cli) loads the realize-emit skill as system context.
+ *
+ * The optional `ownerContext` (Phase 3) is the per-owner realize-context
+ * snapshot — TARGET RUNTIME + [PRE-BAKED] step bullets + cross-service
+ * surface + capabilities — prepended to the prompt so the LLM sees the
+ * same input the original per-owner emit had. Without this, smaller
+ * models (Ollama / MarrBox) hallucinate cross-file calls; with it,
+ * they have the canonical contract to anchor against.
+ *
+ * Exported for tests + so callers can override the prompt shape.
+ */
+export declare function formatFeedbackPrompt(req: ReemitRequest, ownerContext?: string | null): string;
+//# sourceMappingURL=reemit.d.ts.map

package/dist/realize/post-emit-verify/reemit.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"reemit.d.ts","sourceRoot":"","sources":["../../../src/realize/post-emit-verify/reemit.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AAGH,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,IAAI,CAAC;AAGxC,OAAO,KAAK,EAAE,MAAM,EAAE,aAAa,EAAE,MAAM,sBAAsB,CAAC;AAGlE,MAAM,WAAW,kBAAkB;IACjC,4DAA4D;IAC5D,KAAK,EAAE,aAAa,CAAC;IACrB;6BACyB;IACzB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB;;gCAE4B;IAC5B,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB;;;;;;;;;;OAUG;IACH,MAAM,CAAC,EAAE,MAAM,EAAE,CAAC;IAClB;;;;;;;;;;;;OAYG;IACH,aAAa,CAAC,EAAE,CAAC,SAAS,EAAE,MAAM,KAAK,MAAM,GAAG,IAAI,CAAC;CACtD;AAED;;;;GAIG;AACH,wBAAgB,cAAc,CAAC,OAAO,EAAE,kBAAkB,GAAG,MAAM,CA8ClE;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,oBAAoB,CAClC,GAAG,EAAE,aAAa,EAClB,YAAY,GAAE,MAAM,GAAG,IAAW,GACjC,MAAM,CAiCR"}

package/dist/realize/post-emit-verify/reemit.js

@@ -0,0 +1,124 @@
+/**
+ * Default `Reemit` implementation — builds a feedback prompt from
+ * verifier errors + previous file content and calls the LLM to
+ * re-emit a single file.
+ *
+ * The realize-emit skill (at ~/.claude/skills/realize-emit/) is
+ * auto-loaded by claude-cli when its description matches the prompt
+ * shape — that carries all the per-owner emission conventions
+ * (typing rules, _input convention, γ-stub shape, etc.) so the
+ * feedback re-emit benefits from the same guidance as the original
+ * emission.
+ *
+ * The prompt is intentionally minimal:
+ *   - Errors (verifier-formatted)
+ *   - Previous file content
+ *   - A request to re-emit
+ *
+ * Future iterations may augment with AVAILABLE SPEC SURFACE (cross-
+ * service signatures) when the errors are arity-shape — empirically,
+ * the skill + basic prompt suffices for most null-safety / type
+ * mismatch / unused-decl cases.
+ */
+import { generateText } from 'ai';
+import { assembleSystemWithSkills } from '../../ai/prompt-runner.js';
+import { resolveProviderId } from '../../ai/model-resolver.js';
+/**
+ * Build a `Reemit` callback that uses the provided LLM model.
+ *
+ * The returned closure can be passed straight to `runPostEmitFeedback`.
+ */
+export function buildLlmReemit(options) {
+    const maxAttempts = options.maxAttempts ?? 1;
+    const timeoutMs = options.timeoutMs ?? 3 * 60_000;
+    const skills = options.skills ?? ['realize-emit'];
+    const contextLoader = options.contextLoader;
+    // Provider-aware skill inlining: claude-cli auto-loads skills via the
+    // CLI's filesystem resolution; everyone else needs the skill content
+    // prepended to the system prompt. Compute once at build time — the
+    // provider can't change mid-loop.
+    const providerId = resolveProviderId();
+    const systemPrompt = assembleSystemWithSkills('', providerId, skills);
+    return async (req) => {
+        const ownerContext = contextLoader?.(req.ownerName) ?? null;
+        const prompt = formatFeedbackPrompt(req, ownerContext);
+        for (let attempt = 0; attempt < maxAttempts; attempt++) {
+            try {
+                const result = await Promise.race([
+                    generateText({
+                        model: options.model,
+                        prompt,
+                        // For non-claude-cli providers, `systemPrompt` carries the
+                        // skill content; for claude-cli it's empty and the CLI
+                        // auto-loads.
+                        ...(systemPrompt ? { system: systemPrompt } : {}),
+                    }),
+                    new Promise((_, reject) => setTimeout(() => reject(new Error('reemit timeout')), timeoutMs)),
+                ]);
+                const extracted = extractTypeScriptBlock(result.text ?? '');
+                if (!extracted) {
+                    if (attempt + 1 < maxAttempts)
+                        continue;
+                    return null;
+                }
+                return extracted;
+            }
+            catch (err) {
+                if (attempt + 1 < maxAttempts)
+                    continue;
+                return null;
+            }
+        }
+        return null;
+    };
+}
+/**
+ * Format the feedback prompt body. Caller's LLM provider (e.g.
+ * claude-cli) loads the realize-emit skill as system context.
+ *
+ * The optional `ownerContext` (Phase 3) is the per-owner realize-context
+ * snapshot — TARGET RUNTIME + [PRE-BAKED] step bullets + cross-service
+ * surface + capabilities — prepended to the prompt so the LLM sees the
+ * same input the original per-owner emit had. Without this, smaller
+ * models (Ollama / MarrBox) hallucinate cross-file calls; with it,
+ * they have the canonical contract to anchor against.
+ *
+ * Exported for tests + so callers can override the prompt shape.
+ */
+export function formatFeedbackPrompt(req, ownerContext = null) {
+    const errorLines = req.errors
+        .map(formatError)
+        .join('\n');
+    const parts = [];
+    if (ownerContext) {
+        parts.push(ownerContext);
+        parts.push('');
+        parts.push('---');
+        parts.push('');
+    }
+    parts.push(`Re-emit the entire contents of \`${req.file}\`.`, '', `Your previous emission had the following compile / lint errors:`, '', errorLines, '', `Previous file content (re-emit this with the errors fixed):`, '', '```typescript', req.previousContent, '```', '', `Fix the errors and emit the ENTIRE updated file inside one \`\`\`typescript code block.`, `Honour the [PRE-BAKED] step bodies above verbatim where present; do not paraphrase.`, `Do not change any logic beyond what's needed to fix the errors.`);
+    return parts.join('\n');
+}
+function formatError(e) {
+    const pos = e.line !== undefined
+        ? `:${e.line}${e.col !== undefined ? `:${e.col}` : ''}`
+        : '';
+    return `  ${e.file}${pos} [${e.code}] ${e.message}`;
+}
+/**
+ * Pull the TypeScript code out of the LLM response. Matches the
+ * canonical ```typescript ... ``` block; falls back to ``` ... ``` if
+ * the LLM omitted the language tag.
+ */
+function extractTypeScriptBlock(text) {
+    if (!text)
+        return null;
+    const tsMatch = /```typescript\s*\n([\s\S]*?)\n```/.exec(text);
+    if (tsMatch)
+        return tsMatch[1];
+    const anyMatch = /```\s*\n([\s\S]*?)\n```/.exec(text);
+    if (anyMatch)
+        return anyMatch[1];
+    return null;
+}
+//# sourceMappingURL=reemit.js.map

package/dist/realize/post-emit-verify/reemit.js.map

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