@specverse/engines 6.32.0 → 6.33.0

package/dist/realize/per-action-emitter.d.ts

@@ -0,0 +1,235 @@
+/**
+ * Per-action body emitter — Phase 1 scaffolding for the Realize L3
+ * per-action redesign (proposal: 2026-05-07-REALIZE-L3-PER-ACTION).
+ *
+ * Reframes the unit of work for action body emission from per-step
+ * (one helper per spec step bullet, glued by step1Result → step2Result
+ * envelopes) to per-action (one coherent method body per action, with
+ * step bullets as spec input rather than code-output structure).
+ *
+ * Three branches, in priority order:
+ *
+ * 1. **Full-convention coverage** — the L2 convention matcher returns
+ *    a non-AI-fallback `MatchResult` for every step in the action.
+ *    The matched per-step TS snippets are assembled deterministically
+ *    into the method body (no LLM call).
+ *
+ * 2. **LLM-driven emission** — at least one step lacks convention
+ *    coverage AND a real LLM is available. We delegate to the
+ *    microcall-orchestrator hook with the convention-matched scaffolding
+ *    as pre-baked context (DR3-A: pre-baked TS shown to LLM as
+ *    scaffolding, structural validator post-emission). Phase 1 stubs
+ *    the prompt name (`realize-action.prompt.yaml`) — that asset lands
+ *    in Phase 2; here we just thread the call site.
+ *
+ * 3. **Stub-mode body** (DR4-γ) — when neither full-convention nor LLM
+ *    is available, emit a body that:
+ *      a. Throws `Error("<action>: not implemented")` at function entry
+ *         so the failure is unambiguous at runtime.
+ *      b. Preserves the convention-matched scaffolding as a code-block
+ *         comment beneath the throw, with explicit "Gaps:" entries
+ *         enumerating the steps the matcher couldn't cover.
+ *    Captures stub-mode review value without misleading partial execution.
+ *
+ * Phase 1 scope:
+ *   - Just the orchestrator + emitter scaffolding. The realize-time
+ *     wiring (replacing the per-step `.ai.ts` emission path), the
+ *     `realize-action.prompt.yaml` asset, and the actual LLM call
+ *     plumbing all land in subsequent phases (3, 2, and 3 respectively).
+ *   - Out of scope: `.ai.ts` deletion (DR2: keep the filename, repurpose
+ *     content shape — Phase 3 work).
+ */
+import type { runPrompt as runPromptFn } from '../ai/prompt-runner.js';
+/** Mirror of `SharedStepContext` (libs/_shared/step-matching.ts:33). */
+export interface SharedStepContext {
+    modelName: string;
+    serviceName: string;
+    operationName: string;
+    stepNum: number;
+    parameterNames?: string[];
+    declaredVars?: Set<string>;
+    resultName?: string;
+}
+/** Mirror of `SharedConvention` (libs/_shared/step-matching.ts:43). */
+export interface SharedConvention<C extends SharedStepContext = SharedStepContext> {
+    name: string;
+    pattern: RegExp;
+    generateCall: (match: RegExpMatchArray, ctx: C) => string;
+    generateMethod?: (match: RegExpMatchArray, ctx: C) => string;
+}
+/** Mirror of `MatchResult` (libs/_shared/step-matching.ts:54). */
+export interface MatchResult {
+    matched: boolean;
+    call: string;
+    helperMethod?: string;
+    functionName?: string;
+    inputs?: string[];
+    resultVar?: string;
+}
+/**
+ * Signature of the shared step matcher
+ * (`engines/libs/instance-factories/services/templates/_shared/step-matching.ts`).
+ * Re-declared here so the emitter doesn't have to static-import the
+ * libs path (which is outside `rootDir: 'src'`).
+ */
+export type MatcherFn = <C extends SharedStepContext>(step: string, ctx: C, conventions: ReadonlyArray<SharedConvention<C>>, aiArgsExpr: (inputs: string[], paramNames: string[]) => string) => MatchResult;
+/**
+ * The unit of work the emitter is asked to fill. A spec-derived view of
+ * an action / operation. Mirrors the AST `ExecutablePropertiesSpec`
+ * shape but kept local + plain so callers in different phases of the
+ * realize pipeline can construct it without coupling to AST internals.
+ */
+export interface ActionSpec {
+    /** Action / operation name as it appears in the spec (e.g. `processOrder`). */
+    name: string;
+    /** Owning component / class — for prompt context + identity. */
+    ownerName: string;
+    /** Whether this owner is a controller, service, or model.behaviors host. */
+    ownerKind: 'controller' | 'service' | 'model';
+    /** The spec step bullets — what the LLM (or matcher) is filling in. */
+    steps: string[];
+    /** Action-level metadata, threaded into both the matcher and the LLM. */
+    description?: string;
+    parameters?: Record<string, string>;
+    returns?: string;
+    requires?: string[];
+    ensures?: string[];
+    publishes?: string[];
+}
+/**
+ * Per-action emission context. Carries everything the emitter needs to
+ * dispatch a step against the L2 matcher and / or hand off to the LLM.
+ *
+ * Phase 1 keeps this minimal + additive — Phases 2/3 will add fields
+ * (cross-action sibling context, processContextByMethodKey, manifest
+ * resolved factory, …) without breaking existing call sites.
+ */
+export interface RealizeContext {
+    /** Component name the owning entity lives in. */
+    componentName: string;
+    /** Spec model name powering this controller / service (e.g. `OrderProcessor`). */
+    modelName: string;
+    /**
+     * The shared matcher walker (`matchAgainstConventions`) lives under
+     * `engines/libs/instance-factories/services/templates/_shared/` —
+     * outside `rootDir: 'src'`. Phase 1 keeps the emitter decoupled from
+     * the libs path by accepting the matcher as an injected callable.
+     * The realize-time wire-in (Phase 3) will dynamic-import it the same
+     * way `realize/index.ts` does for the per-step matcher; tests inject
+     * a lightweight stand-in.
+     *
+     * Optional in Phase 1: when omitted, every step is treated as
+     * "unmatched", exercising the LLM / stub branches uniformly.
+     */
+    matcher?: MatcherFn;
+    /**
+     * The convention list to walk. The shared matcher
+     * (`matchAgainstConventions`) is library-agnostic but the conventions
+     * array carries the ORM / driver-specific patterns. Caller passes the
+     * resolved factory's conventions (prisma / mongodb-native /
+     * postgres-native / future).
+     */
+    conventions?: ReadonlyArray<SharedConvention<SharedStepContext>>;
+    /**
+     * When the matcher leaves a step unmatched it computes an AI-fallback
+     * call site shape. The expression for that call's input object varies
+     * per-ORM (prisma uses bare `{ a, b, c }`; pg-native uses
+     * `{ args: { a, b, c } }`). Caller passes its ORM's expression. Phase
+     * 1 default keeps things ORM-neutral.
+     */
+    aiArgsExpr?: (inputs: string[], paramNames: string[]) => string;
+    /**
+     * Hook for the per-action LLM emission. Phase 1 threads this through
+     * but does NOT wire into a real prompt (the `realize-action.prompt.yaml`
+     * asset is a Phase 2 deliverable). Tests inject a stub; production
+     * Phase 3 will inject a microcall-orchestrator-backed implementation.
+     *
+     * Returning `null` is equivalent to "LLM unavailable" → falls through
+     * to the stub-mode γ branch.
+     */
+    llmEmit?: LlmEmitFn;
+    /**
+     * Override for "is the LLM available?". Default: respects
+     * `SPECVERSE_AI_PROVIDER` — `stub` → false, anything else → true.
+     * Tests use this to deterministically force the stub-γ branch.
+     */
+    canCallLLM?: () => boolean;
+}
+/**
+ * The LLM emission hook. Phase 1 is a thin pass-through to a microcall-
+ * orchestrator-style handler; Phase 3 will replace this with a wrapper
+ * around `runActionMicrocalls` (or a direct `runPrompt` call) using the
+ * `realize-action.prompt.yaml` asset.
+ */
+export type LlmEmitFn = (request: LlmEmitRequest) => Promise<string | null>;
+/**
+ * Inputs handed to the LLM emission hook. Carries the action's full
+ * spec body plus the per-step scaffolding produced by the L2 matcher
+ * (DR3-A pre-baked TS shown to LLM).
+ */
+export interface LlmEmitRequest {
+    action: ActionSpec;
+    context: RealizeContext;
+    /** Matcher output for each step, in spec order. `null` means unmatched. */
+    perStepMatches: Array<MatchResult | null>;
+    /**
+     * The pre-baked TS scaffolding (matched steps' `.call` strings joined).
+     * Phase 2's prompt feeds this to the LLM verbatim alongside the spec
+     * step bullets.
+     */
+    scaffoldingSnippet: string;
+    /**
+     * Phase 1 placeholder. The prompt name the orchestrator should use.
+     * The asset itself doesn't exist yet (Phase 2 deliverable); Phase 3
+     * implementations should pin this to `realize-action.prompt.yaml`.
+     */
+    promptName: string;
+    /**
+     * Optional thread-through to the underlying `runPrompt`. Lets tests
+     * assert the call shape without standing up an LLM provider.
+     */
+    runPromptOverride?: typeof runPromptFn;
+}
+/**
+ * When every step is convention-matched, assemble the method body
+ * deterministically by joining the matcher's `.call` strings.
+ *
+ * The call strings come pre-indented (4 spaces — enough for "inside a
+ * method body") and trailing-newline-free. We wrap them with a
+ * try-block + a `return` at the end where possible (last step's
+ * resultVar). Phase 3 will refine the assembly (typed signatures,
+ * error-flow shapes) once the realize-time wiring decides on a single
+ * controller / service template path; Phase 1 keeps it minimal so the
+ * emitter's contract is stable.
+ */
+export declare function assembleFromConventions(action: ActionSpec, perStepMatches: MatchResult[]): string;
+/**
+ * Emit the γ-shaped stub body (DR4 resolution). The function body opens
+ * with a `throw new Error("<action>: not implemented")` so the failure
+ * surfaces unambiguously at runtime, and the convention-matched
+ * scaffolding is preserved as a code-block comment beneath the throw
+ * for reviewer context.
+ *
+ * Format:
+ *   throw new Error("processOrder: not implemented");
+ *   /* Convention-matched scaffolding (preserved for review):
+ *    *   <pre-baked TS for matched steps>
+ *    * Gaps:
+ *    *   - <step text for unmatched steps>
+ *    *\/
+ */
+export declare function emitStubGammaBody(action: ActionSpec, perStepMatches: Array<MatchResult | null>): string;
+/**
+ * Emit the body for a single action.
+ *
+ * Branch order:
+ *   1. Full-convention coverage  → assembled deterministically.
+ *   2. Mixed coverage + LLM available + `llmEmit` returns text → LLM result.
+ *   3. Otherwise (stub mode, no LLM, or `llmEmit` returned null) → γ stub.
+ *
+ * The signature returns just the body (not the wrapping method
+ * declaration / params / return type); Phase 3 will integrate this
+ * with the controller / service template emitters.
+ */
+export declare function emitActionBody(action: ActionSpec, context: RealizeContext): Promise<string>;
+//# sourceMappingURL=per-action-emitter.d.ts.map

package/dist/realize/per-action-emitter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"per-action-emitter.d.ts","sourceRoot":"","sources":["../../src/realize/per-action-emitter.ts"],"names":[],"mappings":"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"}

package/dist/realize/per-action-emitter.js

@@ -0,0 +1,229 @@
+/**
+ * Per-action body emitter — Phase 1 scaffolding for the Realize L3
+ * per-action redesign (proposal: 2026-05-07-REALIZE-L3-PER-ACTION).
+ *
+ * Reframes the unit of work for action body emission from per-step
+ * (one helper per spec step bullet, glued by step1Result → step2Result
+ * envelopes) to per-action (one coherent method body per action, with
+ * step bullets as spec input rather than code-output structure).
+ *
+ * Three branches, in priority order:
+ *
+ * 1. **Full-convention coverage** — the L2 convention matcher returns
+ *    a non-AI-fallback `MatchResult` for every step in the action.
+ *    The matched per-step TS snippets are assembled deterministically
+ *    into the method body (no LLM call).
+ *
+ * 2. **LLM-driven emission** — at least one step lacks convention
+ *    coverage AND a real LLM is available. We delegate to the
+ *    microcall-orchestrator hook with the convention-matched scaffolding
+ *    as pre-baked context (DR3-A: pre-baked TS shown to LLM as
+ *    scaffolding, structural validator post-emission). Phase 1 stubs
+ *    the prompt name (`realize-action.prompt.yaml`) — that asset lands
+ *    in Phase 2; here we just thread the call site.
+ *
+ * 3. **Stub-mode body** (DR4-γ) — when neither full-convention nor LLM
+ *    is available, emit a body that:
+ *      a. Throws `Error("<action>: not implemented")` at function entry
+ *         so the failure is unambiguous at runtime.
+ *      b. Preserves the convention-matched scaffolding as a code-block
+ *         comment beneath the throw, with explicit "Gaps:" entries
+ *         enumerating the steps the matcher couldn't cover.
+ *    Captures stub-mode review value without misleading partial execution.
+ *
+ * Phase 1 scope:
+ *   - Just the orchestrator + emitter scaffolding. The realize-time
+ *     wiring (replacing the per-step `.ai.ts` emission path), the
+ *     `realize-action.prompt.yaml` asset, and the actual LLM call
+ *     plumbing all land in subsequent phases (3, 2, and 3 respectively).
+ *   - Out of scope: `.ai.ts` deletion (DR2: keep the filename, repurpose
+ *     content shape — Phase 3 work).
+ */
+/**
+ * Default LLM-availability check. Mirrors `model-resolver.resolveProviderId`'s
+ * logic without importing it (avoids dragging the AI subpath into
+ * realize for a cheap predicate). When a real implementation lands in
+ * Phase 3, it will likely just call `resolveProviderId() !== 'stub'`.
+ */
+function defaultCanCallLLM() {
+    const explicit = process.env.SPECVERSE_AI_PROVIDER;
+    if (explicit === 'stub')
+        return false;
+    if (process.env.MCP_SERVER === '1')
+        return false;
+    // If unset, we can't be sure — be conservative (false) so realize
+    // doesn't accidentally fire LLM calls in environments that aren't
+    // configured for AI. Tests inject `canCallLLM` explicitly.
+    return Boolean(explicit) || Boolean(process.env.ANTHROPIC_API_KEY);
+}
+/**
+ * Run every step in the action through the L2 convention matcher.
+ * Returns `MatchResult | null` per step in spec order (`null` when the
+ * action has no steps to dispatch).
+ *
+ * The matcher walks conventions in order; first match wins. Unmatched
+ * steps compute the AI-fallback shape (`functionName + inputs + resultVar`)
+ * deterministically — they're still part of `MatchResult`, just with
+ * `matched: false`. We rely on that flag to detect coverage.
+ */
+function matchSteps(action, context) {
+    if (!action.steps || action.steps.length === 0)
+        return [];
+    if (!context.matcher || !context.conventions) {
+        // No matcher / no conventions → every step is "unmatched" for
+        // emitter purposes. We still return MatchResult shapes so the LLM /
+        // stub branches see the same per-step structure as a real ORM
+        // dispatch.
+        return action.steps.map((_step, i) => ({
+            matched: false,
+            call: `    // Step ${i + 1}: ${action.steps[i]} [unmatched]`,
+            functionName: undefined,
+            inputs: undefined,
+            resultVar: undefined,
+        }));
+    }
+    const aiArgsExpr = context.aiArgsExpr ??
+        ((inputs) => (inputs.length > 0 ? `{ ${inputs.join(', ')} }` : '{}'));
+    const declaredVars = new Set();
+    const parameterNames = action.parameters ? Object.keys(action.parameters) : [];
+    const results = [];
+    for (let i = 0; i < action.steps.length; i++) {
+        const step = action.steps[i];
+        const ctx = {
+            modelName: context.modelName,
+            serviceName: action.ownerName,
+            operationName: action.name,
+            stepNum: i + 1,
+            parameterNames,
+            declaredVars,
+        };
+        const result = context.matcher(step, ctx, context.conventions, aiArgsExpr);
+        results.push(result);
+    }
+    return results;
+}
+/**
+ * When every step is convention-matched, assemble the method body
+ * deterministically by joining the matcher's `.call` strings.
+ *
+ * The call strings come pre-indented (4 spaces — enough for "inside a
+ * method body") and trailing-newline-free. We wrap them with a
+ * try-block + a `return` at the end where possible (last step's
+ * resultVar). Phase 3 will refine the assembly (typed signatures,
+ * error-flow shapes) once the realize-time wiring decides on a single
+ * controller / service template path; Phase 1 keeps it minimal so the
+ * emitter's contract is stable.
+ */
+export function assembleFromConventions(action, perStepMatches) {
+    const lines = [];
+    for (const m of perStepMatches) {
+        // m.call already carries indentation. Strip a trailing newline if any.
+        lines.push(m.call.replace(/\n$/, ''));
+    }
+    // Best-effort return statement: when the last step produced a
+    // resultVar, return it. The matcher's `.call` for matched conventions
+    // doesn't include a return; we add one here so the body is
+    // syntactically complete. Unmatched fallbacks still set resultVar
+    // but we'd never reach this assembler with an unmatched step.
+    const last = perStepMatches[perStepMatches.length - 1];
+    if (last?.resultVar) {
+        lines.push(`    return ${last.resultVar};`);
+    }
+    return lines.join('\n');
+}
+/**
+ * Emit the γ-shaped stub body (DR4 resolution). The function body opens
+ * with a `throw new Error("<action>: not implemented")` so the failure
+ * surfaces unambiguously at runtime, and the convention-matched
+ * scaffolding is preserved as a code-block comment beneath the throw
+ * for reviewer context.
+ *
+ * Format:
+ *   throw new Error("processOrder: not implemented");
+ *   /* Convention-matched scaffolding (preserved for review):
+ *    *   <pre-baked TS for matched steps>
+ *    * Gaps:
+ *    *   - <step text for unmatched steps>
+ *    *\/
+ */
+export function emitStubGammaBody(action, perStepMatches) {
+    const matchedLines = [];
+    const gaps = [];
+    for (let i = 0; i < perStepMatches.length; i++) {
+        const result = perStepMatches[i];
+        const step = action.steps[i] ?? '';
+        if (result?.matched) {
+            // Indent for readability inside the comment block.
+            const callLines = result.call.split('\n').map((ln) => '   *   ' + ln.trimStart());
+            matchedLines.push(...callLines);
+        }
+        else {
+            gaps.push(`   *   - ${step}`);
+        }
+    }
+    const lines = [];
+    lines.push(`    throw new Error(${JSON.stringify(`${action.name}: not implemented`)});`);
+    lines.push('    /* Convention-matched scaffolding (preserved for review):');
+    if (matchedLines.length > 0) {
+        lines.push(...matchedLines);
+    }
+    else {
+        lines.push('   *   (no steps matched any convention)');
+    }
+    if (gaps.length > 0) {
+        lines.push('   * Gaps:');
+        lines.push(...gaps);
+    }
+    lines.push('   */');
+    return lines.join('\n');
+}
+/**
+ * Emit the body for a single action.
+ *
+ * Branch order:
+ *   1. Full-convention coverage  → assembled deterministically.
+ *   2. Mixed coverage + LLM available + `llmEmit` returns text → LLM result.
+ *   3. Otherwise (stub mode, no LLM, or `llmEmit` returned null) → γ stub.
+ *
+ * The signature returns just the body (not the wrapping method
+ * declaration / params / return type); Phase 3 will integrate this
+ * with the controller / service template emitters.
+ */
+export async function emitActionBody(action, context) {
+    const perStepMatches = matchSteps(action, context);
+    const allMatched = perStepMatches.length > 0 &&
+        perStepMatches.every((m) => m !== null && m.matched === true);
+    // Branch 1 — every step has a convention match.
+    if (allMatched) {
+        return assembleFromConventions(action, perStepMatches);
+    }
+    // Branch 2 — at least one gap. Try the LLM if available + hook present.
+    const canCall = (context.canCallLLM ?? defaultCanCallLLM)();
+    if (canCall && context.llmEmit) {
+        const matched = perStepMatches.filter((m) => m !== null && m.matched === true);
+        const scaffoldingSnippet = matched.map((m) => m.call.replace(/\n$/, '')).join('\n');
+        try {
+            const llmBody = await context.llmEmit({
+                action,
+                context,
+                perStepMatches,
+                scaffoldingSnippet,
+                // PLACEHOLDER (Phase 1) — the prompt asset doesn't exist yet.
+                // Phase 2 ships `realize-action.prompt.yaml` and Phase 3 wires
+                // this constant up to the actual call site.
+                promptName: 'realize-action.prompt.yaml',
+            });
+            if (llmBody && llmBody.trim().length > 0) {
+                return llmBody;
+            }
+            // Fall through to stub when LLM returned null / empty.
+        }
+        catch {
+            // Any LLM error → stub. Phase 3 will add structured logging +
+            // surgical-retry semantics here; Phase 1 keeps the contract simple.
+        }
+    }
+    // Branch 3 — γ stub.
+    return emitStubGammaBody(action, perStepMatches);
+}
+//# sourceMappingURL=per-action-emitter.js.map

package/dist/realize/per-action-emitter.js.map

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

package/dist/realize/per-action-llm-emit.d.ts

@@ -0,0 +1,87 @@
+/**
+ * Per-action LLM emit hook — Phase 3 of the L3 redesign.
+ *
+ * Builds an `LlmEmitFn` (the dependency-injection seam exposed by
+ * `per-action-emitter.ts`) that loads `realize-action.prompt.yaml`,
+ * calls `runPrompt` with the assembled per-action context, runs the
+ * structural validator over the LLM output, and surgically retries
+ * once on parse failure (DR3-aligned).
+ *
+ * Three quality gates run on every LLM emission:
+ *   1. Markdown extraction — pull the ```typescript fenced block out of
+ *      the LLM response. Empty / missing block → null (caller falls
+ *      through to γ stub).
+ *   2. Structural preservation (DR3) — every pre-baked snippet must
+ *      appear verbatim in the body. A rewritten snippet is a loud
+ *      failure; we throw with a diff so the user knows the LLM
+ *      misbehaved.
+ *   3. esbuild parse check — the body must be syntactically valid TS.
+ *      On parse failure we run ONE surgical retry with the parse error
+ *      fed back as a userPrefix; if it fails again we return null and
+ *      the caller emits the γ stub.
+ *
+ * The realize-action.prompt.yaml asset (Phase 2 deliverable) lives in
+ * `@specverse/assets/prompts/core/standard/default/realize-action.prompt.yaml`
+ * once that package is republished. Until then, we fall back to a
+ * filesystem path under specverse-self/assets/ so Phase 3 doesn't have
+ * to wait on a registry roundtrip.
+ */
+import { runPrompt as runPromptFn, type PromptYaml } from '../ai/prompt-runner.js';
+import type { LlmEmitFn } from './per-action-emitter.js';
+/** Options for {@link createRealizeActionLlmEmit}. */
+export interface CreateRealizeActionLlmEmitOptions {
+    /** Override `runPrompt` for tests. */
+    runPromptOverride?: typeof runPromptFn;
+    /** Override `loadPrompt` for tests; default is loadPrompt('realize-action'). */
+    loadPromptOverride?: () => PromptYaml;
+    /** Override the parse-check for tests. Must return null on success
+     *  and an error message string on failure. */
+    parseCheckOverride?: (code: string) => Promise<string | null>;
+    /** Override the model passed to runPrompt (rare). */
+    model?: any;
+    /** Per-call timeout. Default 5min — same as microcall-orchestrator. */
+    timeoutMs?: number;
+    /** Disable the surgical retry (tests). */
+    disableSurgicalRetry?: boolean;
+    /**
+     * Available clients string passed into the prompt's `availableClients`
+     * variable. Caller (the realize runner) builds this from the
+     * component's `import:` block + the action's `uses:`. When omitted,
+     * the prompt receives a "(none)" placeholder.
+     */
+    availableClients?: string;
+    /** Sibling-action signatures string. Same convention. */
+    siblingActions?: string;
+    /** Cross-method process context string. Same convention. */
+    processContext?: string;
+}
+/**
+ * Build an {@link LlmEmitFn} for use in per-action realize emission.
+ *
+ * The returned function:
+ *   1. Builds the prompt input from the per-action emitter's request.
+ *   2. Calls runPrompt({ operation: 'realize-action', ... }).
+ *   3. Extracts the ```typescript block from the response.
+ *   4. Runs the structural validator (DR3); throws on rewrite.
+ *   5. Runs an esbuild parse check; surgical-retries once on failure.
+ *   6. Returns the body string, or null when all attempts fail (caller
+ *      falls through to γ stub).
+ */
+export declare function createRealizeActionLlmEmit(opts?: CreateRealizeActionLlmEmitOptions): LlmEmitFn;
+/**
+ * Filesystem fallback for realize-action.prompt.yaml when the installed
+ * @specverse/assets package predates Phase 2's prompt addition.
+ *
+ * Searches a small fixed set of candidate paths relative to the engines
+ * package's installed location and the worktree layout used in
+ * specverse-self repo. Returns null when none are found; runPrompt then
+ * surfaces the canonical "prompt file not found" error.
+ */
+export declare function loadRealizeActionPromptFromFallback(): PromptYaml | null;
+/**
+ * Pull the first ```typescript fenced block out of an LLM response.
+ * Tolerates plain ``` (no language tag) when the body starts with
+ * recognisably-TS content. Returns null if no block is found.
+ */
+export declare function extractTypescriptBlock(text: string): string | null;
+//# sourceMappingURL=per-action-llm-emit.d.ts.map

package/dist/realize/per-action-llm-emit.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"per-action-llm-emit.d.ts","sourceRoot":"","sources":["../../src/realize/per-action-llm-emit.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AAOH,OAAO,EAEL,SAAS,IAAI,WAAW,EAGxB,KAAK,UAAU,EAGhB,MAAM,wBAAwB,CAAC;AAKhC,OAAO,KAAK,EACV,SAAS,EAKV,MAAM,yBAAyB,CAAC;AAIjC,sDAAsD;AACtD,MAAM,WAAW,iCAAiC;IAChD,sCAAsC;IACtC,iBAAiB,CAAC,EAAE,OAAO,WAAW,CAAC;IACvC,gFAAgF;IAChF,kBAAkB,CAAC,EAAE,MAAM,UAAU,CAAC;IACtC;kDAC8C;IAC9C,kBAAkB,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAAC;IAC9D,qDAAqD;IACrD,KAAK,CAAC,EAAE,GAAG,CAAC;IACZ,uEAAuE;IACvE,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,0CAA0C;IAC1C,oBAAoB,CAAC,EAAE,OAAO,CAAC;IAC/B;;;;;OAKG;IACH,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,yDAAyD;IACzD,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,4DAA4D;IAC5D,cAAc,CAAC,EAAE,MAAM,CAAC;CACzB;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,0BAA0B,CACxC,IAAI,GAAE,iCAAsC,GAC3C,SAAS,CAuFX;AA4ED;;;;;;;;GAQG;AACH,wBAAgB,mCAAmC,IAAI,UAAU,GAAG,IAAI,CAqDvE;AAsID;;;;GAIG;AACH,wBAAgB,sBAAsB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAalE"}