@specverse/engines 6.42.3 → 6.60.1

package/dist/realize/post-emit-verify/verifiers/stub-completeness.js

@@ -0,0 +1,298 @@
+/**
+ * Stub-completeness verifier — detects placeholder/stub bodies in
+ * emitted `.ai.ts` files and reports them as VerifyErrors so the
+ * existing feedback runner re-emits real bodies.
+ *
+ * Why this exists:
+ *   The tsc verifier catches code that DOESN'T COMPILE. It says nothing
+ *   about code that compiles but ships no behavior — the dominant
+ *   failure mode for smaller/open LLMs on per-owner emit:
+ *     - Engine γ-stubs (LLM declined → fallback placeholder file)
+ *     - LLM-emitted throw stubs ("not implemented", "TODO: ...")
+ *     - LLM-emitted trivial returns (`return null as any`)
+ *
+ *   Empirical at 2026-05-13:
+ *     - idle-meta Ollama: 58% real-LLM fill, 80 tsc errors → 0 tsc
+ *       errors looks clean but 42% of bodies are stubs.
+ *     - idle-meta MarrBox: 69% real-LLM fill, 40 → ? tsc errors,
+ *       31% bodies still stubs.
+ *
+ *   Reporting stubs as VerifyErrors lets the feedback runner re-emit
+ *   them with a targeted prompt. The existing rollback machinery
+ *   prevents regressions if the LLM can't do better.
+ *
+ * Design:
+ *   - Regex-only — no TS compiler API import. The `.ai.ts` files have
+ *     a narrow shape: top-level `export async function NAME(...):
+ *     Promise<X> { ... }` declarations. Brace-balanced extraction with
+ *     a single line scanner is enough.
+ *   - Conservative: ONLY flags single-statement bodies that match
+ *     stub patterns. A real function body with a stub-shaped throw
+ *     inside a conditional is NOT flagged.
+ *   - Severity `warning` not `error` — these don't break the build,
+ *     but the feedback runner counts them as errors-to-fix.
+ *
+ * Initial release: `enabledByDefault: false` — opt in via
+ * `SPECVERSE_REALIZE_POST_VERIFY_ENABLE=stub-completeness`. Once the
+ * empirical hit-rate is measured we flip default-on.
+ */
+import { existsSync, readdirSync, readFileSync, statSync } from 'fs';
+import { join, relative } from 'path';
+/** Stub error codes — surfaced to the feedback prompt as the verifier
+ *  code; the LLM doesn't see them directly but they appear in the
+ *  audit sidecar + logs. */
+export const STUB_CODES = {
+    GAMMA_FALLBACK: 'STUB001', // engine wrote the placeholder file
+    LLM_THROW: 'STUB002', // LLM emitted "throw not implemented"
+    TRIVIAL_RETURN: 'STUB003', // LLM emitted `return null|undefined|{}|[]`
+    EMPTY_BODY: 'STUB004', // body is whitespace/comments only
+};
+/** Resolve the behaviors directory tsc + this verifier scan. */
+function resolveBehaviorsDir(ctx) {
+    const sub = ctx.subpath ?? 'backend';
+    return join(ctx.outputDir, sub, 'src', 'behaviors');
+}
+export function extractAsyncFunctions(source) {
+    const lines = source.split('\n');
+    const out = [];
+    // Pattern: line starts (after optional `export ` + `async `) with
+    // `async function NAME(`. We accept `export async function` (the
+    // canonical case) plus the alternate `async function NAME(...){...}`
+    // followed by `export { NAME as ... }` re-export form used for
+    // reserved-word action names in the engine γ-fallback file.
+    const declRe = /^(export\s+)?async\s+function\s+(\w+)\s*\(/;
+    for (let i = 0; i < lines.length; i++) {
+        const line = lines[i];
+        const m = declRe.exec(line);
+        if (!m)
+            continue;
+        const name = m[2];
+        // Walk forward to find the first `{` that opens the body. Skip
+        // anything inside the parameter list / return-type annotation.
+        let openIdx = -1;
+        let parenDepth = 0;
+        let lineCursor = i;
+        let colCursor = m.index + m[0].length; // just past `(`
+        // We've consumed up to the `(` of params; start at depth 1.
+        parenDepth = 1;
+        scanHeader: while (lineCursor < lines.length) {
+            const s = lines[lineCursor];
+            while (colCursor < s.length) {
+                const ch = s[colCursor];
+                if (parenDepth > 0) {
+                    if (ch === '(')
+                        parenDepth++;
+                    else if (ch === ')')
+                        parenDepth--;
+                }
+                else {
+                    // After params closed: look for `{`.
+                    if (ch === '{') {
+                        openIdx = colCursor;
+                        break scanHeader;
+                    }
+                }
+                colCursor++;
+            }
+            lineCursor++;
+            colCursor = 0;
+        }
+        if (openIdx === -1)
+            continue;
+        // Now brace-count forward from just past `{` until we hit the
+        // matching `}`.
+        let depth = 1;
+        let bodyStartLineIdx = lineCursor;
+        let bodyStartColIdx = openIdx + 1;
+        let endLineIdx = -1;
+        let endColIdx = -1;
+        walkBody: for (let li = lineCursor; li < lines.length; li++) {
+            const s = lines[li];
+            const startCol = li === lineCursor ? openIdx + 1 : 0;
+            for (let ci = startCol; ci < s.length; ci++) {
+                const ch = s[ci];
+                if (ch === '{')
+                    depth++;
+                else if (ch === '}') {
+                    depth--;
+                    if (depth === 0) {
+                        endLineIdx = li;
+                        endColIdx = ci;
+                        break walkBody;
+                    }
+                }
+            }
+        }
+        if (endLineIdx === -1)
+            continue; // unbalanced; bail on this fn
+        // Slice the body content (exclusive of the outer braces).
+        let body;
+        if (bodyStartLineIdx === endLineIdx) {
+            body = lines[bodyStartLineIdx].slice(bodyStartColIdx, endColIdx);
+        }
+        else {
+            const first = lines[bodyStartLineIdx].slice(bodyStartColIdx);
+            const middle = lines.slice(bodyStartLineIdx + 1, endLineIdx).join('\n');
+            const last = lines[endLineIdx].slice(0, endColIdx);
+            body = [first, middle, last].filter((x) => x !== '').join('\n');
+        }
+        out.push({
+            name,
+            body,
+            declLine: i + 1,
+            bodyStartLine: bodyStartLineIdx + 1,
+        });
+        // Skip past the end so we don't re-scan content inside the body.
+        i = endLineIdx;
+    }
+    return out;
+}
+/**
+ * Strip line + block comments and blank lines, then trim.
+ * Used to normalize bodies before stub-pattern matching.
+ */
+export function stripCommentsAndBlanks(body) {
+    // Block comments first (greedy, multi-line capable).
+    let s = body.replace(/\/\*[\s\S]*?\*\//g, '');
+    // Line comments.
+    s = s.replace(/(^|\n)\s*\/\/[^\n]*/g, (_, p1) => p1 ?? '');
+    // Collapse multiple newlines + trim.
+    s = s.split('\n').map((l) => l.trimEnd()).filter((l) => l.trim() !== '').join('\n').trim();
+    return s;
+}
+// γ-fallback engine placeholders. Two producers:
+//   - per-owner-runner.renderFallbackPlaceholderFile → "(per-owner emit fell back)"
+//   - per-action-recovery.renderActionGammaStub      → "(per-action recovery fell back)"
+// Both are ENGINE placeholders (STUB001, auto-reemit-eligible), NOT the
+// LLM's own "not implemented" throw (STUB002, surface-spec-gap).
+const GAMMA_FALLBACK_RE = /^throw new Error\s*\(\s*["'`].*?not implemented \((?:per-owner emit|per-action recovery) fell back\).*?["'`]\s*\)\s*;?$/s;
+const LLM_THROW_RE = /^throw new Error\s*\(\s*["'`][^"'`]*\b(not\s+implement\w*|not\s+yet|todo|placeholder|stub|requires|fallback|missing|unimplement\w*)\b[^"'`]*["'`]\s*\)\s*;?$/is;
+const TRIVIAL_RETURN_RE = /^return\s+(?:null|undefined|\{\s*\}|\[\s*\])(\s+as\s+\w+)?\s*;?$/s;
+/**
+ * Classify a function body as a stub (or not). Conservative: requires
+ * the body to be a single-statement match to avoid false positives on
+ * real bodies that happen to contain a throw deep inside a conditional.
+ */
+export function classifyBody(body) {
+    const stripped = stripCommentsAndBlanks(body);
+    if (stripped === '') {
+        return { kind: 'empty', code: STUB_CODES.EMPTY_BODY };
+    }
+    // Single-statement check: count semicolons + ensure no control-flow
+    // keywords at the top level. We don't try to detect every multi-
+    // statement function; instead, we use the simplest signal — if the
+    // stripped body matches a single-statement stub regex end-to-end,
+    // it's a stub.
+    if (GAMMA_FALLBACK_RE.test(stripped)) {
+        return { kind: 'gamma-fallback', code: STUB_CODES.GAMMA_FALLBACK };
+    }
+    if (LLM_THROW_RE.test(stripped)) {
+        return { kind: 'llm-throw', code: STUB_CODES.LLM_THROW };
+    }
+    if (TRIVIAL_RETURN_RE.test(stripped)) {
+        return { kind: 'trivial-return', code: STUB_CODES.TRIVIAL_RETURN };
+    }
+    return null;
+}
+/** Render a feedback-prompt-friendly message for a stub match. */
+function messageFor(kind, fnName) {
+    switch (kind) {
+        case 'gamma-fallback':
+            return (`Function '${fnName}' is a γ-stub placeholder (per-owner emit fell back). ` +
+                `Emit a real implementation per the [PRE-BAKED] action contract in the spec.`);
+        case 'llm-throw':
+            return (`Function '${fnName}' has a placeholder body that throws 'not implemented' ` +
+                `(or similar). Emit a real implementation per the [PRE-BAKED] action contract.`);
+        case 'trivial-return':
+            return (`Function '${fnName}' returns a trivial placeholder (null/undefined/{}). ` +
+                `Emit a real implementation per the [PRE-BAKED] action contract.`);
+        case 'empty':
+            return (`Function '${fnName}' has an empty body. ` +
+                `Emit a real implementation per the [PRE-BAKED] action contract.`);
+    }
+}
+/** Recursively list `*.ai.ts` files under a directory. Defensive — the
+ *  behaviors dir is normally flat but engines may add subdirs later. */
+function listAiTsFiles(dir) {
+    if (!existsSync(dir))
+        return [];
+    const out = [];
+    for (const name of readdirSync(dir)) {
+        const p = join(dir, name);
+        let st;
+        try {
+            st = statSync(p);
+        }
+        catch {
+            continue;
+        }
+        if (st.isDirectory())
+            out.push(...listAiTsFiles(p));
+        else if (st.isFile() && p.endsWith('.ai.ts'))
+            out.push(p);
+    }
+    return out;
+}
+export const STUB_COMPLETENESS_VERIFIER = {
+    id: 'stub-completeness',
+    name: 'Stub Body Completeness',
+    // Default-on as of engines 6.56.0 (Phase 2 of
+    // 2026-05-13-VERIFIER-DIAGNOSTIC-TREATMENT-SPLIT). Safe to flip
+    // because the feedback runner's defaultTreatmentSelector routes
+    // STUB002 to surface-spec-gap (no reemit), preventing the cross-
+    // file regressions measured at engines 6.54.0 on idle-meta.
+    // STUB001/003/004 still auto-reemit (high-success on γ-fallback
+    // recovery, measured at engines 6.54.0 on nestjs-billing: 7/7 fixed).
+    enabledByDefault: true,
+    applies: (ctx) => {
+        if (ctx.targetLanguage && ctx.targetLanguage !== 'typescript')
+            return false;
+        const dir = resolveBehaviorsDir(ctx);
+        return existsSync(dir) && listAiTsFiles(dir).length > 0;
+    },
+    verify: async (ctx) => {
+        const start = Date.now();
+        const dir = resolveBehaviorsDir(ctx);
+        const files = listAiTsFiles(dir);
+        const errors = [];
+        const notes = [];
+        let totalFunctions = 0;
+        let totalStubs = 0;
+        for (const absFile of files) {
+            let source;
+            try {
+                source = readFileSync(absFile, 'utf8');
+            }
+            catch (e) {
+                notes.push(`could not read ${absFile}: ${e?.message ?? String(e)}`);
+                continue;
+            }
+            const fns = extractAsyncFunctions(source);
+            totalFunctions += fns.length;
+            for (const fn of fns) {
+                const match = classifyBody(fn.body);
+                if (!match)
+                    continue;
+                totalStubs++;
+                errors.push({
+                    file: relative(ctx.outputDir, absFile),
+                    line: fn.declLine,
+                    col: 1,
+                    severity: 'warning',
+                    code: match.code,
+                    message: messageFor(match.kind, fn.name),
+                });
+            }
+        }
+        notes.push(`scanned ${files.length} .ai.ts file(s), ${totalFunctions} function(s); ` +
+            `flagged ${totalStubs} stub(s)`);
+        return {
+            verifierId: 'stub-completeness',
+            durationMs: Date.now() - start,
+            ok: true,
+            errors,
+            notes,
+        };
+    },
+};
+//# sourceMappingURL=stub-completeness.js.map

package/dist/realize/post-emit-verify/verifiers/stub-completeness.js.map

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

package/dist/realize/post-emit-verify/verifiers/tsc.d.ts

@@ -0,0 +1,24 @@
+/**
+ * TypeScript verifier — runs `tsc --noEmit` on the realized backend
+ * tree, parses error output, and returns structured `VerifyError`s.
+ *
+ * The first concrete implementation of the `PostEmitVerifier` interface.
+ * Used for any TypeScript realize target (the default stack today).
+ *
+ * Design notes:
+ *   - We rely on the realized project's own `node_modules/.bin/tsc`
+ *     and `tsconfig.json` (installed by the realize-emit step).
+ *     The framework doesn't bundle a tsc — the user's project owns
+ *     its own TypeScript version.
+ *   - `applies` checks for the presence of `tsconfig.json` in
+ *     `<outputDir>/<subpath>/`. Future stacks (e.g. a Java target)
+ *     would have their own verifier with their own `applies`.
+ *   - Output parsing matches the standard tsc message format:
+ *       `path/to/file.ts(line,col): error TSXXXX: Message text.`
+ *   - tsc tool-failure (binary missing, install needed) → ok=false
+ *     + notes explain. The feedback runner skips the verifier; the
+ *     realize pipeline does NOT crash.
+ */
+import type { PostEmitVerifier } from '../types.js';
+export declare const TSC_VERIFIER: PostEmitVerifier;
+//# sourceMappingURL=tsc.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"tsc.d.ts","sourceRoot":"","sources":["../../../../src/realize/post-emit-verify/verifiers/tsc.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAKH,OAAO,KAAK,EACV,gBAAgB,EAIjB,MAAM,aAAa,CAAC;AAcrB,eAAO,MAAM,YAAY,EAAE,gBA8H1B,CAAC"}

package/dist/realize/post-emit-verify/verifiers/tsc.js

@@ -0,0 +1,148 @@
+/**
+ * TypeScript verifier — runs `tsc --noEmit` on the realized backend
+ * tree, parses error output, and returns structured `VerifyError`s.
+ *
+ * The first concrete implementation of the `PostEmitVerifier` interface.
+ * Used for any TypeScript realize target (the default stack today).
+ *
+ * Design notes:
+ *   - We rely on the realized project's own `node_modules/.bin/tsc`
+ *     and `tsconfig.json` (installed by the realize-emit step).
+ *     The framework doesn't bundle a tsc — the user's project owns
+ *     its own TypeScript version.
+ *   - `applies` checks for the presence of `tsconfig.json` in
+ *     `<outputDir>/<subpath>/`. Future stacks (e.g. a Java target)
+ *     would have their own verifier with their own `applies`.
+ *   - Output parsing matches the standard tsc message format:
+ *       `path/to/file.ts(line,col): error TSXXXX: Message text.`
+ *   - tsc tool-failure (binary missing, install needed) → ok=false
+ *     + notes explain. The feedback runner skips the verifier; the
+ *     realize pipeline does NOT crash.
+ */
+import { existsSync } from 'fs';
+import { join, relative } from 'path';
+import { spawnSync } from 'child_process';
+const TSC_LINE_RE = /^(.+?)\((\d+),(\d+)\):\s+(error|warning)\s+(TS\d+):\s+(.+)$/;
+/**
+ * Resolve the directory tsc should run in. Defaults to
+ * `<outputDir>/backend` (the canonical SpecVerse TypeScript target).
+ * Caller can override via `ctx.subpath`.
+ */
+function resolveSubpath(ctx) {
+    if (ctx.subpath)
+        return join(ctx.outputDir, ctx.subpath);
+    return join(ctx.outputDir, 'backend');
+}
+export const TSC_VERIFIER = {
+    id: 'tsc',
+    name: 'TypeScript Compiler',
+    enabledByDefault: true,
+    applies: (ctx) => {
+        if (ctx.targetLanguage && ctx.targetLanguage !== 'typescript')
+            return false;
+        const dir = resolveSubpath(ctx);
+        return existsSync(join(dir, 'tsconfig.json'));
+    },
+    verify: async (ctx) => {
+        const dir = resolveSubpath(ctx);
+        const start = Date.now();
+        const notes = [];
+        // Auto-install deps if needed. The realize pipeline emits a
+        // scaffolded project tree (package.json + tsconfig.json) but does
+        // not run `npm install`, so node_modules/.bin/tsc is missing on
+        // first verify. Without auto-install the framework would silently
+        // no-op default-on (after the engines 6.52 flip). Run `npm install`
+        // once when:
+        //   - `package.json` exists
+        //   - `node_modules/.bin/tsc` is missing
+        //   - `ctx.autoInstall !== false` (defaults to true)
+        // Bounded by a 5-min timeout — pathological dep trees fail loudly
+        // rather than hang the realize pipeline.
+        const localTsc = join(dir, 'node_modules', '.bin', 'tsc');
+        const pkgJson = join(dir, 'package.json');
+        const autoInstall = ctx.autoInstall !== false;
+        if (!existsSync(localTsc) && existsSync(pkgJson) && autoInstall) {
+            const installResult = spawnSync('npm', ['install', '--no-audit', '--no-fund', '--silent'], {
+                cwd: dir,
+                encoding: 'utf8',
+                maxBuffer: 50 * 1024 * 1024,
+                timeout: 5 * 60_000,
+            });
+            if (installResult.error || installResult.status !== 0) {
+                return {
+                    verifierId: 'tsc',
+                    durationMs: Date.now() - start,
+                    ok: false,
+                    errors: [],
+                    notes: [
+                        `tsc verifier auto-install failed in ${dir}: ${installResult.error?.message ?? `npm exit ${installResult.status}`}. Hint: run \`npm install\` manually before realize, or set ctx.autoInstall=false.`,
+                    ],
+                };
+            }
+            notes.push(`auto-installed deps in ${dir} for tsc verifier`);
+        }
+        // Locate the project-local tsc. Fall back to PATH `npx tsc` only if
+        // node_modules/.bin/tsc isn't installed yet.
+        let cmd;
+        let args;
+        if (existsSync(localTsc)) {
+            cmd = localTsc;
+            args = ['--noEmit'];
+        }
+        else {
+            cmd = 'npx';
+            args = ['--no-install', 'tsc', '--noEmit'];
+        }
+        const result = spawnSync(cmd, args, {
+            cwd: dir,
+            encoding: 'utf8',
+            maxBuffer: 50 * 1024 * 1024, // 50MB — error output on a heavy
+            // realize can be megabytes.
+        });
+        const durationMs = Date.now() - start;
+        if (result.error) {
+            return {
+                verifierId: 'tsc',
+                durationMs,
+                ok: false,
+                errors: [],
+                notes: [
+                    ...notes,
+                    `tsc could not be invoked: ${result.error.message}. ` +
+                        `Hint: run \`npm install\` in ${dir} before realizing, or ensure ` +
+                        `tsc is on PATH.`,
+                ],
+            };
+        }
+        const combined = (result.stdout ?? '') + (result.stderr ?? '');
+        const errors = [];
+        // tsc reports file paths relative to its CWD (the subpath). Convert
+        // those to paths relative to outputDir so the feedback runner's
+        // `join(outputDir, file)` resolves correctly.
+        const subpathRel = relative(ctx.outputDir, dir);
+        const toOutputRel = (file) => subpathRel === '' ? file : `${subpathRel}/${file}`;
+        for (const line of combined.split('\n')) {
+            const m = TSC_LINE_RE.exec(line.trimEnd());
+            if (!m)
+                continue;
+            errors.push({
+                file: toOutputRel(m[1]),
+                line: parseInt(m[2], 10),
+                col: parseInt(m[3], 10),
+                severity: m[4],
+                code: m[5],
+                message: m[6],
+            });
+        }
+        return {
+            verifierId: 'tsc',
+            durationMs,
+            // ok: true even when errors > 0 — that's the EXPECTED path.
+            // ok: false reserved for tool-level failures (binary missing, etc.).
+            ok: true,
+            errors,
+            notes,
+        };
+    },
+};
+//# sourceMappingURL=tsc.js.map

package/dist/realize/post-emit-verify/verifiers/tsc.js.map

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

package/dist/realize/realize-context-snapshot.d.ts

@@ -0,0 +1,70 @@
+/**
+ * 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.
+ */
+/** Input data for snapshotting an owner's realize context. Mirrors the
+ *  subset of PerOwnerEmitRequest that's directly useful for fixing
+ *  bodies — TARGET RUNTIME + per-action [PRE-BAKED] scaffolding +
+ *  cross-service signatures + available capabilities. */
+export interface OwnerRealizeContext {
+    ownerName: string;
+    /** e.g. "Node.js (backend)" — short, structurally useful for choosing
+     *  imports + identifying forbidden APIs. */
+    targetRuntime: string;
+    /** The full per-action scaffolding rendered by `buildPerActionScaffolding`
+     *  — already formatted with `[PRE-BAKED] "<step>" → <snippet>` blocks
+     *  and `[WRITE] "<step>"` markers. Reusing the same render keeps the
+     *  reemit prompt aligned with the original per-owner prompt. */
+    perActionScaffolding: string;
+    /** AVAILABLE SPEC SURFACE — signatures of cross-service operations.
+     *  Empty-fallback formatted by the per-owner-runner. */
+    availableSpecSurface: string;
+    /** AVAILABLE CAPABILITIES — clients / repos the LLM may call. */
+    availableCapabilities: string;
+    /** AVAILABLE CLIENTS — generated client classes the LLM may instantiate. */
+    availableClients: string;
+}
+/**
+ * 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 declare function formatContextSnapshot(ctx: OwnerRealizeContext): string;
+/**
+ * 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 declare function writeContextSnapshot(outputDir: string, ctx: OwnerRealizeContext): void;
+/**
+ * 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 declare function loadContextSnapshot(outputDir: string, ownerName: string): string | null;
+//# sourceMappingURL=realize-context-snapshot.d.ts.map

package/dist/realize/realize-context-snapshot.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"realize-context-snapshot.d.ts","sourceRoot":"","sources":["../../src/realize/realize-context-snapshot.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AAOH;;;yDAGyD;AACzD,MAAM,WAAW,mBAAmB;IAClC,SAAS,EAAE,MAAM,CAAC;IAClB;gDAC4C;IAC5C,aAAa,EAAE,MAAM,CAAC;IACtB;;;oEAGgE;IAChE,oBAAoB,EAAE,MAAM,CAAC;IAC7B;4DACwD;IACxD,oBAAoB,EAAE,MAAM,CAAC;IAC7B,iEAAiE;IACjE,qBAAqB,EAAE,MAAM,CAAC;IAC9B,4EAA4E;IAC5E,gBAAgB,EAAE,MAAM,CAAC;CAC1B;AAED;;;;;GAKG;AACH,wBAAgB,qBAAqB,CAAC,GAAG,EAAE,mBAAmB,GAAG,MAAM,CAmBtE;AAQD;;;;GAIG;AACH,wBAAgB,oBAAoB,CAClC,SAAS,EAAE,MAAM,EACjB,GAAG,EAAE,mBAAmB,GACvB,IAAI,CASN;AAED;;;;GAIG;AACH,wBAAgB,mBAAmB,CACjC,SAAS,EAAE,MAAM,EACjB,SAAS,EAAE,MAAM,GAChB,MAAM,GAAG,IAAI,CAQf"}