@specverse/engines 6.42.3 → 6.60.1

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

@@ -0,0 +1,187 @@
+/**
+ * Post-emit verification framework — generic interface.
+ *
+ * SpecVerse realize emits one or more LLM-authored source files per
+ * owner (e.g. `backend/src/behaviors/<Owner>.ai.ts` for the TypeScript
+ * stack). LLM emissions sometimes carry compile errors / lint issues
+ * that don't show up at per-rule validation time (the realize-rules
+ * manifest catches forbidden APIs, missing `.js` extensions, etc., but
+ * not type mismatches or runtime semantics).
+ *
+ * A `PostEmitVerifier` runs AFTER all owners have emitted, on the
+ * fully-realized output tree. It produces structured errors that the
+ * feedback runner uses to drive a per-file re-emit pass.
+ *
+ * The interface is intentionally language-agnostic. The first
+ * implementation is `tsc` for TypeScript stacks; future verifiers can
+ * target Python (`mypy`/`ruff`), Go (`go vet`), Java (`mvn compile`),
+ * Rust (`cargo check`), etc. Each verifier knows whether it `applies`
+ * given the realized target (the manifest's stack tells you).
+ *
+ * Empirical motivation: 2026-05-13 idle-meta realize at engines 6.50.1
+ * produced 48 backend tsc errors. Two hand-crafted feedback prompts
+ * (AuthController.ai.ts + FormatNumberService.ai.ts) reduced this to
+ * 37 errors with zero regressions. Extrapolation: a full feedback
+ * sweep brings idle-meta from ~48 → ~5-10 errors per realize.
+ */
+/**
+ * Single error reported by a verifier. Position-optional (some
+ * verifiers — Go vet, formatters — emit errors without precise
+ * line/col).
+ */
+export interface VerifyError {
+    /** Path to the source file, relative to the realized output dir. */
+    file: string;
+    line?: number;
+    col?: number;
+    /** Verifier-specific code, e.g. "TS2554", "py:E501", "go:S1000". */
+    code: string;
+    /** Human-readable description, suitable for inclusion in a feedback
+     *  prompt. Verifier-specific; the framework doesn't interpret it. */
+    message: string;
+    severity: 'error' | 'warning';
+}
+/**
+ * Result of running a single verifier on the realized output.
+ */
+export interface VerifyResult {
+    /** Verifier id (matches `PostEmitVerifier.id`). */
+    verifierId: string;
+    /** Wall-time. Useful for tuning verifier order + budget. */
+    durationMs: number;
+    /** Whether the verifier ran successfully. False indicates a tool-level
+     *  failure (tsc not installed, npm install needed first, etc.) — the
+     *  feedback runner SKIPS the verifier when not ok, not when errors > 0. */
+    ok: boolean;
+    errors: VerifyError[];
+    /** Non-fatal warnings from the verifier itself (separate from
+     *  per-error severity), e.g. "tsc emitted 200 errors but we truncated
+     *  to 100". */
+    notes: string[];
+}
+/**
+ * Context passed to verifiers — describes the realize target so each
+ * verifier can decide whether it `applies`.
+ *
+ * Minimal for now; extends as new verifiers need additional signal.
+ */
+export interface VerifyContext {
+    /** Absolute path to the realized output root (the dir that contains
+     *  e.g. `backend/`, `frontend/`, `tests/`). */
+    outputDir: string;
+    /** Realize target tag, e.g. 'typescript', 'python', 'go'. Set by the
+     *  realize pipeline based on the manifest's primary stack. */
+    targetLanguage?: string;
+    /** Optional: explicit subpath within outputDir to verify. tsc would
+     *  typically scope to `backend/`. Defaults to outputDir itself. */
+    subpath?: string;
+    /**
+     * When true (the default), verifiers MAY run dependency installation
+     * (`npm install` / `pip install` / etc.) before running their actual
+     * checks. Required for the in-pipeline `spv realize` invocation:
+     * realize emits a scaffolded project but doesn't install deps, so
+     * tsc/mypy/etc. wouldn't otherwise be available.
+     *
+     * Set to false in test harnesses or when the caller has already
+     * installed deps. Each verifier decides whether to honour the hint —
+     * a stub-only verifier might ignore it.
+     */
+    autoInstall?: boolean;
+}
+/**
+ * A verifier runs a quality check on the realized output. Each
+ * verifier is independent — the framework collects results from
+ * applicable verifiers, then the feedback runner decides what to do.
+ *
+ * Implementations must NOT throw on tool-level failures; return
+ * `{ ok: false, errors: [], notes: ['…'] }` instead. The framework
+ * surfaces notes to the user; throws crash the realize pipeline.
+ */
+export interface PostEmitVerifier {
+    /** Stable identifier — kebab-case. e.g. 'tsc', 'mypy', 'go-vet'. */
+    id: string;
+    /** Human-readable name for logs and audit. */
+    name: string;
+    /**
+     * Whether this verifier runs unless explicitly disabled. Mature
+     * stable verifiers ship `enabledByDefault: true` (tsc); experimental
+     * or third-party verifiers ship `false` to require an opt-in via
+     * `SPECVERSE_REALIZE_POST_VERIFY_ENABLE=<id>,<id>` env (future).
+     *
+     * Optional for backwards compatibility — missing field is treated
+     * as `true` (the original behavior).
+     */
+    enabledByDefault?: boolean;
+    /** Predicate: does this verifier apply to the given context? */
+    applies: (ctx: VerifyContext) => boolean;
+    /** Run the verifier. MUST NOT throw on tool failure (return ok:false). */
+    verify: (ctx: VerifyContext) => Promise<VerifyResult>;
+}
+/**
+ * After all verifiers have run, the feedback runner needs to map
+ * each errored file to its owning spec entity (e.g.
+ * `backend/src/behaviors/AuthController.ai.ts` → ownerName=AuthController).
+ *
+ * Each verifier MAY contribute a mapping hint via `mapFileToOwner`,
+ * but the framework falls back to a generic regex
+ * (`behaviors/(.+)\\.ai\\.ts$` for TypeScript). Verifiers for other
+ * stacks would override the mapping.
+ */
+export interface OwnerMapping {
+    /** Source file path (relative to outputDir). */
+    file: string;
+    /** Inferred owner name. null if the file can't be mapped (e.g.
+     *  shared infrastructure files generated by the framework, not by
+     *  per-owner LLM emit — those should NOT receive feedback re-emits). */
+    ownerName: string | null;
+}
+/**
+ * Per-error fix strategy. Phase 2 of
+ * 2026-05-13-VERIFIER-DIAGNOSTIC-TREATMENT-SPLIT — different verifier
+ * errors need different fix strategies, not a single "always reemit"
+ * path:
+ *
+ *   - `auto-reemit`: include this error in the file's reemit prompt;
+ *     the LLM should try to fix it. Right for tsc errors (unambiguous
+ *     fix) + γ-fallback / trivial-return / empty-body stubs (LLM never
+ *     produced real output the first time; a second try with focused
+ *     context is high-success).
+ *
+ *   - `surface-spec-gap`: do NOT reemit; surface the error to the user
+ *     via the `realize-quality.json` sidecar (`specGaps` field).
+ *     Right for STUB002 (LLM-throw stubs) where the LLM already
+ *     signaled a context gap on the original emit — re-prompting
+ *     either no-ops or hallucinates cross-file regressions (measured
+ *     on idle-meta 2026-05-13 at engines 6.54.0).
+ *
+ *   - `skip`: ignore entirely. Right for unmappable errors (already
+ *     filtered) and for future categories the framework doesn't know
+ *     how to treat.
+ */
+export type TreatmentStrategy = 'auto-reemit' | 'surface-spec-gap' | 'skip';
+/**
+ * Decides how each verifier error should be treated. The default
+ * selector lives in `feedback-runner.ts::defaultTreatmentSelector`;
+ * callers may override for advanced cases (testing, custom verifiers,
+ * different LLM tolerance profiles).
+ */
+export type TreatmentSelector = (error: VerifyError) => TreatmentStrategy;
+/**
+ * A single spec-level gap surfaced from a verifier error that the
+ * framework chose NOT to auto-fix. Goes into the realize-quality.json
+ * sidecar's `specGaps` array; users read it and decide whether to
+ * adjust the spec/manifest, switch providers, or hand-edit.
+ */
+export interface SpecGapEntry {
+    /** Owner name (e.g. "AuthController"). null when unmappable. */
+    ownerName: string | null;
+    /** Source file path, relative to outputDir. */
+    file: string;
+    line?: number;
+    col?: number;
+    /** Verifier code (e.g. "STUB002"). */
+    code: string;
+    /** Verifier-formatted message — directly suitable for user reading. */
+    message: string;
+}
+//# sourceMappingURL=types.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../src/realize/post-emit-verify/types.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AAEH;;;;GAIG;AACH,MAAM,WAAW,WAAW;IAC1B,oEAAoE;IACpE,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,oEAAoE;IACpE,IAAI,EAAE,MAAM,CAAC;IACb;yEACqE;IACrE,OAAO,EAAE,MAAM,CAAC;IAChB,QAAQ,EAAE,OAAO,GAAG,SAAS,CAAC;CAC/B;AAED;;GAEG;AACH,MAAM,WAAW,YAAY;IAC3B,mDAAmD;IACnD,UAAU,EAAE,MAAM,CAAC;IACnB,4DAA4D;IAC5D,UAAU,EAAE,MAAM,CAAC;IACnB;;+EAE2E;IAC3E,EAAE,EAAE,OAAO,CAAC;IACZ,MAAM,EAAE,WAAW,EAAE,CAAC;IACtB;;mBAEe;IACf,KAAK,EAAE,MAAM,EAAE,CAAC;CACjB;AAED;;;;;GAKG;AACH,MAAM,WAAW,aAAa;IAC5B;mDAC+C;IAC/C,SAAS,EAAE,MAAM,CAAC;IAClB;kEAC8D;IAC9D,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB;uEACmE;IACnE,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB;;;;;;;;;;OAUG;IACH,WAAW,CAAC,EAAE,OAAO,CAAC;CACvB;AAED;;;;;;;;GAQG;AACH,MAAM,WAAW,gBAAgB;IAC/B,oEAAoE;IACpE,EAAE,EAAE,MAAM,CAAC;IACX,8CAA8C;IAC9C,IAAI,EAAE,MAAM,CAAC;IACb;;;;;;;;OAQG;IACH,gBAAgB,CAAC,EAAE,OAAO,CAAC;IAC3B,gEAAgE;IAChE,OAAO,EAAE,CAAC,GAAG,EAAE,aAAa,KAAK,OAAO,CAAC;IACzC,0EAA0E;IAC1E,MAAM,EAAE,CAAC,GAAG,EAAE,aAAa,KAAK,OAAO,CAAC,YAAY,CAAC,CAAC;CACvD;AAED;;;;;;;;;GASG;AACH,MAAM,WAAW,YAAY;IAC3B,gDAAgD;IAChD,IAAI,EAAE,MAAM,CAAC;IACb;;4EAEwE;IACxE,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;CAC1B;AAED;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,MAAM,MAAM,iBAAiB,GAAG,aAAa,GAAG,kBAAkB,GAAG,MAAM,CAAC;AAE5E;;;;;GAKG;AACH,MAAM,MAAM,iBAAiB,GAAG,CAAC,KAAK,EAAE,WAAW,KAAK,iBAAiB,CAAC;AAE1E;;;;;GAKG;AACH,MAAM,WAAW,YAAY;IAC3B,gEAAgE;IAChE,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;IACzB,+CAA+C;IAC/C,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,sCAAsC;IACtC,IAAI,EAAE,MAAM,CAAC;IACb,uEAAuE;IACvE,OAAO,EAAE,MAAM,CAAC;CACjB"}

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

@@ -0,0 +1,28 @@
+/**
+ * Post-emit verification framework — generic interface.
+ *
+ * SpecVerse realize emits one or more LLM-authored source files per
+ * owner (e.g. `backend/src/behaviors/<Owner>.ai.ts` for the TypeScript
+ * stack). LLM emissions sometimes carry compile errors / lint issues
+ * that don't show up at per-rule validation time (the realize-rules
+ * manifest catches forbidden APIs, missing `.js` extensions, etc., but
+ * not type mismatches or runtime semantics).
+ *
+ * A `PostEmitVerifier` runs AFTER all owners have emitted, on the
+ * fully-realized output tree. It produces structured errors that the
+ * feedback runner uses to drive a per-file re-emit pass.
+ *
+ * The interface is intentionally language-agnostic. The first
+ * implementation is `tsc` for TypeScript stacks; future verifiers can
+ * target Python (`mypy`/`ruff`), Go (`go vet`), Java (`mvn compile`),
+ * Rust (`cargo check`), etc. Each verifier knows whether it `applies`
+ * given the realized target (the manifest's stack tells you).
+ *
+ * Empirical motivation: 2026-05-13 idle-meta realize at engines 6.50.1
+ * produced 48 backend tsc errors. Two hand-crafted feedback prompts
+ * (AuthController.ai.ts + FormatNumberService.ai.ts) reduced this to
+ * 37 errors with zero regressions. Extrapolation: a full feedback
+ * sweep brings idle-meta from ~48 → ~5-10 errors per realize.
+ */
+export {};
+//# sourceMappingURL=types.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../../src/realize/post-emit-verify/types.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG"}

package/dist/realize/post-emit-verify/verifier-manifest.d.ts

@@ -0,0 +1,29 @@
+/**
+ * Post-emit verifier manifest — single source of truth for which
+ * verifiers ship with the realize pipeline.
+ *
+ * Adding a new verifier: append to VERIFIERS, then it auto-runs on
+ * matching realize targets via `applies`.
+ */
+import type { PostEmitVerifier, VerifyContext, VerifyResult } from './types.js';
+export declare const VERIFIERS: PostEmitVerifier[];
+/**
+ * Run all applicable verifiers against the realized output. Verifiers
+ * run in series (most are heavyweight enough that parallel doesn't
+ * help much, and series gives predictable log output). Each verifier's
+ * tool-level failures are isolated — one failure doesn't stop the
+ * others.
+ *
+ * Verifier filtering order:
+ *   1. `enabledByDefault === false` AND id NOT in `enabledOverrides` → SKIP
+ *   2. `applies(ctx)` returns false → SKIP
+ *   3. Otherwise → run
+ *
+ * Missing `enabledByDefault` field is treated as `true` (backwards-
+ * compatible default). The `enabledOverrides` parameter lets callers
+ * opt-in to experimental verifiers at run-time without changing the
+ * manifest.
+ */
+export declare function runAllVerifiers(ctx: VerifyContext, enabledOverrides?: Set<string>): Promise<VerifyResult[]>;
+export declare function findVerifier(id: string): PostEmitVerifier | undefined;
+//# sourceMappingURL=verifier-manifest.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"verifier-manifest.d.ts","sourceRoot":"","sources":["../../../src/realize/post-emit-verify/verifier-manifest.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AACH,OAAO,KAAK,EAAE,gBAAgB,EAAE,aAAa,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC;AAIhF,eAAO,MAAM,SAAS,EAAE,gBAAgB,EAQvC,CAAC;AAEF;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAsB,eAAe,CACnC,GAAG,EAAE,aAAa,EAClB,gBAAgB,CAAC,EAAE,GAAG,CAAC,MAAM,CAAC,GAC7B,OAAO,CAAC,YAAY,EAAE,CAAC,CAqBzB;AAED,wBAAgB,YAAY,CAAC,EAAE,EAAE,MAAM,GAAG,gBAAgB,GAAG,SAAS,CAErE"}

package/dist/realize/post-emit-verify/verifier-manifest.js

@@ -0,0 +1,57 @@
+import { TSC_VERIFIER } from './verifiers/tsc.js';
+import { STUB_COMPLETENESS_VERIFIER } from './verifiers/stub-completeness.js';
+export const VERIFIERS = [
+    TSC_VERIFIER,
+    STUB_COMPLETENESS_VERIFIER,
+    // Future:
+    //   PY_MYPY_VERIFIER  — `mypy --strict src/`
+    //   GO_VET_VERIFIER   — `go vet ./...`
+    //   JAVA_MVN_VERIFIER — `mvn -q compile`
+    //   RUST_CARGO_CHECK_VERIFIER — `cargo check`
+];
+/**
+ * Run all applicable verifiers against the realized output. Verifiers
+ * run in series (most are heavyweight enough that parallel doesn't
+ * help much, and series gives predictable log output). Each verifier's
+ * tool-level failures are isolated — one failure doesn't stop the
+ * others.
+ *
+ * Verifier filtering order:
+ *   1. `enabledByDefault === false` AND id NOT in `enabledOverrides` → SKIP
+ *   2. `applies(ctx)` returns false → SKIP
+ *   3. Otherwise → run
+ *
+ * Missing `enabledByDefault` field is treated as `true` (backwards-
+ * compatible default). The `enabledOverrides` parameter lets callers
+ * opt-in to experimental verifiers at run-time without changing the
+ * manifest.
+ */
+export async function runAllVerifiers(ctx, enabledOverrides) {
+    const out = [];
+    for (const v of VERIFIERS) {
+        const enabledByDefault = v.enabledByDefault !== false;
+        const explicitlyEnabled = enabledOverrides?.has(v.id) ?? false;
+        if (!enabledByDefault && !explicitlyEnabled)
+            continue;
+        if (!v.applies(ctx))
+            continue;
+        try {
+            const result = await v.verify(ctx);
+            out.push(result);
+        }
+        catch (err) {
+            out.push({
+                verifierId: v.id,
+                durationMs: 0,
+                ok: false,
+                errors: [],
+                notes: [`Verifier "${v.id}" threw: ${err?.message ?? String(err)}`],
+            });
+        }
+    }
+    return out;
+}
+export function findVerifier(id) {
+    return VERIFIERS.find((v) => v.id === id);
+}
+//# sourceMappingURL=verifier-manifest.js.map

package/dist/realize/post-emit-verify/verifier-manifest.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"verifier-manifest.js","sourceRoot":"","sources":["../../../src/realize/post-emit-verify/verifier-manifest.ts"],"names":[],"mappings":"AAQA,OAAO,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAClD,OAAO,EAAE,0BAA0B,EAAE,MAAM,kCAAkC,CAAC;AAE9E,MAAM,CAAC,MAAM,SAAS,GAAuB;IAC3C,YAAY;IACZ,0BAA0B;IAC1B,UAAU;IACV,6CAA6C;IAC7C,uCAAuC;IACvC,yCAAyC;IACzC,8CAA8C;CAC/C,CAAC;AAEF;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,CAAC,KAAK,UAAU,eAAe,CACnC,GAAkB,EAClB,gBAA8B;IAE9B,MAAM,GAAG,GAAmB,EAAE,CAAC;IAC/B,KAAK,MAAM,CAAC,IAAI,SAAS,EAAE,CAAC;QAC1B,MAAM,gBAAgB,GAAG,CAAC,CAAC,gBAAgB,KAAK,KAAK,CAAC;QACtD,MAAM,iBAAiB,GAAG,gBAAgB,EAAE,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC,IAAI,KAAK,CAAC;QAC/D,IAAI,CAAC,gBAAgB,IAAI,CAAC,iBAAiB;YAAE,SAAS;QACtD,IAAI,CAAC,CAAC,CAAC,OAAO,CAAC,GAAG,CAAC;YAAE,SAAS;QAC9B,IAAI,CAAC;YACH,MAAM,MAAM,GAAG,MAAM,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;YACnC,GAAG,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC;QACnB,CAAC;QAAC,OAAO,GAAQ,EAAE,CAAC;YAClB,GAAG,CAAC,IAAI,CAAC;gBACP,UAAU,EAAE,CAAC,CAAC,EAAE;gBAChB,UAAU,EAAE,CAAC;gBACb,EAAE,EAAE,KAAK;gBACT,MAAM,EAAE,EAAE;gBACV,KAAK,EAAE,CAAC,aAAa,CAAC,CAAC,EAAE,YAAY,GAAG,EAAE,OAAO,IAAI,MAAM,CAAC,GAAG,CAAC,EAAE,CAAC;aACpE,CAAC,CAAC;QACL,CAAC;IACH,CAAC;IACD,OAAO,GAAG,CAAC;AACb,CAAC;AAED,MAAM,UAAU,YAAY,CAAC,EAAU;IACrC,OAAO,SAAS,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,EAAE,KAAK,EAAE,CAAC,CAAC;AAC5C,CAAC"}

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

@@ -0,0 +1,85 @@
+/**
+ * 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 type { PostEmitVerifier } from '../types.js';
+/** 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 declare const STUB_CODES: {
+    readonly GAMMA_FALLBACK: "STUB001";
+    readonly LLM_THROW: "STUB002";
+    readonly TRIVIAL_RETURN: "STUB003";
+    readonly EMPTY_BODY: "STUB004";
+};
+/**
+ * Find every top-level `export async function NAME(...): Promise<X> {`
+ * declaration in a file and return its name + body + start-line.
+ *
+ * Brace counting handles nested blocks and template-literal expression
+ * holes. We don't try to parse strings/regexes/comments precisely; the
+ * narrow shape of `.ai.ts` files makes this safe in practice (each
+ * function is independent and bodies don't contain `}` in odd places
+ * at the start of a line at depth 0).
+ */
+interface ExtractedFunction {
+    name: string;
+    body: string;
+    /** 1-based line number of the `export async function` declaration. */
+    declLine: number;
+    /** 1-based line number of the first body line (after the opening `{`). */
+    bodyStartLine: number;
+}
+export declare function extractAsyncFunctions(source: string): ExtractedFunction[];
+/**
+ * Strip line + block comments and blank lines, then trim.
+ * Used to normalize bodies before stub-pattern matching.
+ */
+export declare function stripCommentsAndBlanks(body: string): string;
+export interface StubMatch {
+    kind: 'gamma-fallback' | 'llm-throw' | 'trivial-return' | 'empty';
+    code: string;
+}
+/**
+ * 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 declare function classifyBody(body: string): StubMatch | null;
+export declare const STUB_COMPLETENESS_VERIFIER: PostEmitVerifier;
+export {};
+//# sourceMappingURL=stub-completeness.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"stub-completeness.d.ts","sourceRoot":"","sources":["../../../../src/realize/post-emit-verify/verifiers/stub-completeness.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqCG;AAIH,OAAO,KAAK,EACV,gBAAgB,EAIjB,MAAM,aAAa,CAAC;AAErB;;4BAE4B;AAC5B,eAAO,MAAM,UAAU;;;;;CAKb,CAAC;AAQX;;;;;;;;;GASG;AACH,UAAU,iBAAiB;IACzB,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,sEAAsE;IACtE,QAAQ,EAAE,MAAM,CAAC;IACjB,0EAA0E;IAC1E,aAAa,EAAE,MAAM,CAAC;CACvB;AAED,wBAAgB,qBAAqB,CAAC,MAAM,EAAE,MAAM,GAAG,iBAAiB,EAAE,CAuFzE;AAED;;;GAGG;AACH,wBAAgB,sBAAsB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAQ3D;AAaD,MAAM,WAAW,SAAS;IACxB,IAAI,EAAE,gBAAgB,GAAG,WAAW,GAAG,gBAAgB,GAAG,OAAO,CAAC;IAClE,IAAI,EAAE,MAAM,CAAC;CACd;AAED;;;;GAIG;AACH,wBAAgB,YAAY,CAAC,IAAI,EAAE,MAAM,GAAG,SAAS,GAAG,IAAI,CAwB3D;AA2CD,eAAO,MAAM,0BAA0B,EAAE,gBAoExC,CAAC"}