@oscharko-dev/keiko 0.1.0-beta.0

package/dist/workflows/unit-tests/model-loop.js

@@ -0,0 +1,95 @@
+// The bounded model/validate/production-guard retry loop (ADR-0008 D6/D8). Each attempt builds the
+// prompt, calls the injected ModelPort, parses the output, validates the diff through #6, and
+// applies the production-code guard. The loop stops on the first accepted patch, after maxRetries
+// rejections, or when model calls reach the maxModelCalls hard ceiling — whichever comes first. The
+// model call is the one IO boundary here; its failure propagates to the workflow catch boundary.
+import { nodeWorkspaceFs } from "../../workspace/fs.js";
+import { validatePatch } from "../../tools/index.js";
+import { isTestPath } from "./conventions.js";
+import { parseModelOutput } from "./parse.js";
+import { buildPrompt } from "./prompt.js";
+// The production-code guard (D6): every changed path must satisfy isTestPath. Returns "out-of-scope"
+// when any path is a non-test/traversal path, or undefined when all pass. The guard runs on
+// validation.files[].path — the SAME string #6 resolves and would write.
+function productionGuard(workspace, validation) {
+    const offending = validation.files.some((file) => !isTestPath(workspace, file.path));
+    return offending ? "out-of-scope" : undefined;
+}
+function emitValidation(state, validation, code) {
+    const ok = code === undefined && validation.ok;
+    state.emitter.emit({
+        type: "patch:validated",
+        ok,
+        patchBytes: validation.totalBytes,
+        filesChanged: validation.files.length,
+        ...(ok ? {} : { rejectionCode: code ?? validation.reasons[0]?.code }),
+    });
+}
+function emptyPatchRejection(parsedDiff, validation) {
+    return parsedDiff.trim().length === 0 || validation.files.length === 0 ? "empty" : undefined;
+}
+async function callModel(state, messages, attempt, contextBytes) {
+    state.progress.modelCallCount = Math.max(state.progress.modelCallCount, attempt);
+    state.emitter.emit({ type: "workflow:model:call:started", attempt, contextBytes });
+    const response = await state.deps.model.call({ modelId: state.input.modelId, messages }, state.signal);
+    state.emitter.emit({
+        type: "workflow:model:call:completed",
+        attempt,
+        finishReason: response.finishReason,
+        promptTokens: response.usage.promptTokens,
+        completionTokens: response.usage.completionTokens,
+        latencyMs: response.usage.latencyMs,
+    });
+    return response.content;
+}
+// One attempt: prompt -> model -> parse -> validate -> guard.
+async function attemptOnce(state, workspace, conventions, pack, attempt, rejectionReason) {
+    const messages = buildPrompt(state.input, conventions, pack, rejectionReason);
+    const content = await callModel(state, messages, attempt, pack.usedBytes);
+    const parsed = parseModelOutput(content);
+    const validation = validatePatch(workspace, parsed.diff, {
+        fs: state.deps.fs ?? nodeWorkspaceFs,
+    });
+    const effectiveDiff = validation.normalizedDiff ?? parsed.diff;
+    const guardCode = validation.ok
+        ? emptyPatchRejection(effectiveDiff, validation) ?? productionGuard(workspace, validation)
+        : validation.reasons[0]?.code;
+    emitValidation(state, validation, guardCode);
+    if (validation.ok && guardCode === undefined) {
+        const accepted = {
+            diff: effectiveDiff,
+            validation,
+            coveredBehavior: parsed.coveredBehavior,
+            knownGaps: parsed.knownGaps,
+        };
+        return { accepted, rejectionCode: undefined };
+    }
+    return { accepted: undefined, rejectionCode: guardCode ?? "malformed" };
+}
+export async function runModelLoop(state, workspace, conventions, pack) {
+    let modelCallCount = 0;
+    let patchRetryCount = 0;
+    let rejectionReason;
+    while (modelCallCount < state.limits.maxModelCalls &&
+        patchRetryCount <= state.limits.maxRetries) {
+        modelCallCount += 1;
+        const result = await attemptOnce(state, workspace, conventions, pack, modelCallCount, rejectionReason);
+        if (result.accepted !== undefined) {
+            return {
+                accepted: result.accepted,
+                modelCallCount,
+                patchRetryCount,
+                lastRejectionCode: undefined,
+            };
+        }
+        patchRetryCount += 1;
+        state.progress.patchRetryCount = patchRetryCount;
+        rejectionReason = result.rejectionCode;
+    }
+    return {
+        accepted: undefined,
+        modelCallCount,
+        patchRetryCount,
+        lastRejectionCode: rejectionReason,
+    };
+}

package/dist/workflows/unit-tests/parse.d.ts

@@ -0,0 +1,6 @@
+export interface ParsedModelOutput {
+    readonly diff: string;
+    readonly coveredBehavior: string | undefined;
+    readonly knownGaps: string | undefined;
+}
+export declare function parseModelOutput(content: string): ParsedModelOutput;

package/dist/workflows/unit-tests/parse.js

@@ -0,0 +1,68 @@
+// Defensive parser for the model-output contract (ADR-0008 steering note B). The model is
+// instructed (see prompt.ts) to emit the unified diff inside a fenced ```diff ... ``` block,
+// optionally followed by labeled prose sections (## Covered behavior, ## Known gaps). This
+// parser extracts those parts WITHOUT trusting the model to comply: if no fence is present the
+// whole content is treated as the diff; prose sections are extracted only when their headings
+// appear. All extraction uses plain string ops (line splitting, startsWith, trim) — zero regex,
+// so there is no ReDoS surface (steering note F). Redaction happens at the workflow boundary,
+// not here: this module is pure string parsing.
+const FENCE = "```";
+const COVERED_HEADING = "## covered behavior";
+const GAPS_HEADING = "## known gaps";
+// Returns the contents of the FIRST fenced block (```diff ... ``` or a bare ``` ... ```) and the
+// text that follows the closing fence. When no fenced block is found, returns the whole input as
+// the diff and an empty remainder (the no-fence fallback).
+function extractFencedDiff(content) {
+    const lines = content.split("\n");
+    const openIndex = lines.findIndex((line) => line.trimStart().startsWith(FENCE));
+    if (openIndex === -1) {
+        return { diff: content.trim(), rest: "" };
+    }
+    const closeIndex = lines.findIndex((line, idx) => idx > openIndex && line.trimStart().startsWith(FENCE));
+    if (closeIndex === -1) {
+        // An opening fence with no close: treat everything after the opener as the diff.
+        return {
+            diff: lines
+                .slice(openIndex + 1)
+                .join("\n")
+                .trim(),
+            rest: "",
+        };
+    }
+    return {
+        diff: lines
+            .slice(openIndex + 1, closeIndex)
+            .join("\n")
+            .trim(),
+        rest: lines.slice(closeIndex + 1).join("\n"),
+    };
+}
+// Extracts the body of a labeled section: every line after the matching `## heading` up to the
+// next `## ` heading (or end of input). Returns undefined when the heading is absent. Returns
+// undefined when the section body is empty after trimming.
+function extractSection(text, heading) {
+    const lines = text.split("\n");
+    const start = lines.findIndex((line) => line.trim().toLowerCase() === heading);
+    if (start === -1) {
+        return undefined;
+    }
+    const body = [];
+    for (const line of lines.slice(start + 1)) {
+        if (line.trim().startsWith("## ")) {
+            break;
+        }
+        body.push(line);
+    }
+    const joined = body.join("\n").trim();
+    return joined.length === 0 ? undefined : joined;
+}
+export function parseModelOutput(content) {
+    const { diff, rest } = extractFencedDiff(content);
+    // Prose may follow the fenced diff; when there is no fence the whole content is the diff and
+    // there is no prose to scan, so `rest` is empty and both sections resolve to undefined.
+    return {
+        diff,
+        coveredBehavior: extractSection(rest, COVERED_HEADING),
+        knownGaps: extractSection(rest, GAPS_HEADING),
+    };
+}

package/dist/workflows/unit-tests/prompt.d.ts

@@ -0,0 +1,4 @@
+import type { ChatMessage } from "../../gateway/types.js";
+import type { ContextPack } from "../../workspace/index.js";
+import type { TestConventions, UnitTestWorkflowInput } from "./types.js";
+export declare function buildPrompt(input: UnitTestWorkflowInput, conventions: TestConventions, pack: ContextPack, rejectionReason?: string): readonly ChatMessage[];

package/dist/workflows/unit-tests/prompt.js

@@ -0,0 +1,71 @@
+// Prompt construction (ADR-0008 D1/D7). Builds the system + user ChatMessage array for the single
+// generation call. PURE: no IO, no clock, no randomness — the same inputs always yield the same
+// messages. The system message specifies the model-output contract (a fenced ```diff block plus
+// optional labeled prose) that parse.ts consumes (steering note B). Context excerpts handed in are
+// already redacted by #5; this module does no redaction.
+const OUTPUT_CONTRACT = "Respond with the unified diff that adds the tests inside a single fenced code block opened " +
+    "with ```diff and closed with ```. After the block you MAY add `## Covered behavior` and " +
+    "`## Known gaps` sections in prose. Output ONLY a unified diff for test files — never modify " +
+    "source files. The first non-empty line inside the fence MUST be `--- /dev/null` for a new " +
+    "test file or `--- a/<existing-test-path>` for an existing test file, followed by " +
+    "`+++ b/<test-path>` and at least one `@@` hunk. Do not output `*** Begin Patch`, file trees, " +
+    "plain prose, markdown bullets, or escaped newline markers like `\\n+`/`\\n-` inside the diff " +
+    "fence; every diff line must be separated by a real newline.";
+function systemContent(conventions) {
+    const lines = [
+        "You are a senior engineer writing rigorous, deterministic unit tests for existing code.",
+        `Test framework: ${conventions.framework}.`,
+        `Place new tests using the project's "${conventions.fileNamingStyle}" naming convention.`,
+        conventions.testDirs.length > 0
+            ? `Project test directories: ${conventions.testDirs.join(", ")}.`
+            : "No dedicated test directory detected; place tests beside their source.",
+        "Cover edge cases explicitly: null, undefined, empty, zero, boundary, negative, and error paths.",
+        OUTPUT_CONTRACT,
+    ];
+    return `${lines.join("\n")}${assertionStyleBlock(conventions)}`;
+}
+function assertionStyleBlock(conventions) {
+    if (conventions.assertionStyleSamples.length === 0) {
+        return "";
+    }
+    const samples = conventions.assertionStyleSamples
+        .map((sample, idx) => `Example test ${String(idx + 1)}:\n${sample}`)
+        .join("\n\n");
+    return `\n\nMatch the assertion and structure style of these existing tests:\n${samples}`;
+}
+function targetDescription(target) {
+    if (target.kind === "file") {
+        return target.targetFunction === undefined
+            ? `Write unit tests for the public API in ${target.filePath}.`
+            : `Write unit tests for the function ${target.targetFunction} in ${target.filePath}.`;
+    }
+    if (target.kind === "module") {
+        return `Write unit tests for the source files in the module directory ${target.moduleDir}.`;
+    }
+    return `Write unit tests for these changed files: ${target.filePaths.join(", ")}.`;
+}
+function contextBlock(pack) {
+    if (pack.selected.length === 0) {
+        return "";
+    }
+    const entries = pack.selected
+        .map((entry) => `--- ${entry.path} ---\n${entry.excerpt}`)
+        .join("\n\n");
+    return `\n\nRepository context:\n${entries}`;
+}
+function userContent(input, pack, rejectionReason) {
+    const retry = rejectionReason === undefined
+        ? ""
+        : `\n\nThe previous diff was rejected: ${rejectionReason}. Produce a corrected diff that ` +
+            "modifies ONLY test files.";
+    return `${targetDescription(input.target)}${contextBlock(pack)}${retry}`;
+}
+// rejectionReason is appended on a retry (D8) so the model can correct an invalid/out-of-scope
+// diff; it is undefined on the first attempt. The documented core signature is (input, conventions,
+// pack); the optional 4th argument carries retry state without breaking that contract.
+export function buildPrompt(input, conventions, pack, rejectionReason) {
+    return [
+        { role: "system", content: systemContent(conventions) },
+        { role: "user", content: userContent(input, pack, rejectionReason) },
+    ];
+}

package/dist/workflows/unit-tests/report.d.ts

@@ -0,0 +1,21 @@
+import type { PatchFileChange } from "../../tools/index.js";
+import type { VerificationAuditSummary } from "../../verification/index.js";
+import type { UnitTestWorkflowReport, WorkflowStatus } from "./types.js";
+export interface ReportParts {
+    readonly status: WorkflowStatus;
+    readonly modelId: string;
+    readonly durationMs: number;
+    readonly patchFiles: readonly PatchFileChange[];
+    readonly dryRunPreview: string | undefined;
+    readonly proposedDiff: string | undefined;
+    readonly coveredBehavior: string | undefined;
+    readonly knownGaps: string | undefined;
+    readonly nextActions: readonly string[];
+    readonly failureReason?: string | undefined;
+    readonly verificationSummary: VerificationAuditSummary | undefined;
+    readonly verificationSkipReason: string | undefined;
+    readonly modelCallCount: number;
+    readonly patchRetryCount: number;
+}
+export declare function assembleReport(parts: ReportParts): UnitTestWorkflowReport;
+export declare function renderMarkdownReport(report: UnitTestWorkflowReport): string;

package/dist/workflows/unit-tests/report.js

@@ -0,0 +1,90 @@
+// Report assembly and Markdown rendering (ADR-0008 D3, steering note A). assembleReport composes
+// the JSON-serializable UnitTestWorkflowReport from pipeline stage outputs; renderMarkdownReport
+// produces the CLI text path. ALL prose (coveredBehavior, knownGaps, nextActions), the dry-run
+// preview, the proposed diff, verificationSkipReason, and addedTestFiles[].path are redacted via
+// redact() here so nothing the report carries can leak a secret — defence in depth on top of the
+// redaction already applied upstream. Pure: no IO, no clock; the caller injects durationMs and counters.
+import { redact } from "../../gateway/redaction.js";
+const TEST_CASE_PREFIXES = ["test(", "it(", "describe("];
+// Best-effort count of added test cases: added (`+`) lines whose trimmed text begins with a known
+// test-case opener. Not authoritative — purely informational for the report.
+function estimateTestCount(file) {
+    let count = 0;
+    for (const hunk of file.hunks) {
+        for (const line of hunk.lines) {
+            if (!line.startsWith("+")) {
+                continue;
+            }
+            const trimmed = line.slice(1).trimStart();
+            if (TEST_CASE_PREFIXES.some((prefix) => trimmed.startsWith(prefix))) {
+                count += 1;
+            }
+        }
+    }
+    return count;
+}
+function toAddedTestFiles(files) {
+    return files.map((file) => ({
+        path: redact(file.path),
+        estimatedTestCount: estimateTestCount(file),
+    }));
+}
+function redactOptional(value) {
+    return value === undefined ? undefined : redact(value);
+}
+export function assembleReport(parts) {
+    return {
+        workflowId: "unit-test-generation",
+        status: parts.status,
+        modelId: parts.modelId,
+        durationMs: parts.durationMs,
+        dryRunPreview: redactOptional(parts.dryRunPreview),
+        proposedDiff: redactOptional(parts.proposedDiff),
+        addedTestFiles: toAddedTestFiles(parts.patchFiles),
+        coveredBehavior: redactOptional(parts.coveredBehavior),
+        knownGaps: redactOptional(parts.knownGaps),
+        nextActions: parts.nextActions.map((action) => redact(action)),
+        failureReason: redactOptional(parts.failureReason),
+        verificationSummary: parts.verificationSummary,
+        verificationSkipReason: redactOptional(parts.verificationSkipReason),
+        modelCallCount: parts.modelCallCount,
+        patchRetryCount: parts.patchRetryCount,
+    };
+}
+function sectionIf(heading, body) {
+    return body === undefined ? [] : [`## ${heading}`, body, ""];
+}
+function fileLines(report) {
+    if (report.addedTestFiles.length === 0) {
+        return [];
+    }
+    const rows = report.addedTestFiles.map((f) => `- ${f.path} (~${String(f.estimatedTestCount)} test case(s))`);
+    return ["## Test files", ...rows, ""];
+}
+function verificationLine(report) {
+    if (report.verificationSummary !== undefined) {
+        return [`## Verification`, `Status: ${report.verificationSummary.overallStatus}`, ""];
+    }
+    if (report.verificationSkipReason !== undefined) {
+        return [`## Verification`, report.verificationSkipReason, ""];
+    }
+    return [];
+}
+// A human-readable Markdown report for the CLI text path. Every field is already redacted by
+// assembleReport, so rendering is plain string composition.
+export function renderMarkdownReport(report) {
+    return [
+        `# Unit-test generation: ${report.status}`,
+        `Model: ${report.modelId} · ${String(report.durationMs)}ms · ` +
+            `${String(report.modelCallCount)} model call(s) · ${String(report.patchRetryCount)} retry(ies)`,
+        "",
+        ...fileLines(report),
+        ...sectionIf("Covered behavior", report.coveredBehavior),
+        ...sectionIf("Known gaps", report.knownGaps),
+        ...sectionIf("Failure", report.failureReason),
+        ...verificationLine(report),
+        ...(report.nextActions.length > 0
+            ? ["## Next actions", ...report.nextActions.map((a) => `- ${a}`), ""]
+            : []),
+    ].join("\n");
+}

package/dist/workflows/unit-tests/stages.d.ts

@@ -0,0 +1,9 @@
+import type { WorkspaceInfo } from "../../workspace/index.js";
+import { type AcceptedPatch, type ModelLoopResult, type RunState } from "./internal.js";
+import type { UnitTestWorkflowReport } from "./types.js";
+export declare function rejectedReport(state: RunState, loop: ModelLoopResult): UnitTestWorkflowReport;
+export declare function dryRunReport(state: RunState, loop: ModelLoopResult, accepted: AcceptedPatch): UnitTestWorkflowReport;
+export declare function cancelledReport(state: RunState, loop: ModelLoopResult, accepted: AcceptedPatch | undefined): UnitTestWorkflowReport;
+export declare function failedReport(state: RunState, error: unknown): UnitTestWorkflowReport;
+export declare function emitCompleted(state: RunState, report: UnitTestWorkflowReport): UnitTestWorkflowReport;
+export declare function finishPipeline(state: RunState, workspace: WorkspaceInfo, loop: ModelLoopResult): Promise<UnitTestWorkflowReport>;

package/dist/workflows/unit-tests/stages.js

@@ -0,0 +1,155 @@
+// Terminal-report stages (ADR-0008 D3/D5). Each function maps a pipeline outcome — rejected,
+// dry-run, applied+verified, cancelled, or failed — to the redacted UnitTestWorkflowReport via
+// assembleReport. applyPatch (apply mode) is the one IO boundary here and is fail-closed in #6
+// (applyEnabled gates the write). finishPipeline selects the branch; emitCompleted stamps the
+// terminal event. All prose/diff redaction happens inside assembleReport.
+import { redact } from "../../gateway/redaction.js";
+import { applyPatch, CommandCancelledError, renderDryRun, } from "../../tools/index.js";
+import { nodeWorkspaceFs } from "../../workspace/fs.js";
+import { assembleReport } from "./report.js";
+import { runWorkflowVerification } from "./verify-stage.js";
+import { nextActionsFor, } from "./internal.js";
+export function rejectedReport(state, loop) {
+    return assembleReport({
+        status: "rejected",
+        modelId: state.input.modelId,
+        durationMs: state.now() - state.startedAt,
+        patchFiles: [],
+        dryRunPreview: undefined,
+        proposedDiff: undefined,
+        coveredBehavior: undefined,
+        knownGaps: undefined,
+        nextActions: [
+            `The model did not produce an in-scope test patch (${loop.lastRejectionCode ?? "unknown"})`,
+        ],
+        failureReason: undefined,
+        verificationSummary: undefined,
+        verificationSkipReason: undefined,
+        modelCallCount: loop.modelCallCount,
+        patchRetryCount: loop.patchRetryCount,
+    });
+}
+export function dryRunReport(state, loop, accepted) {
+    const files = accepted.validation.files.map((f) => f.path);
+    return assembleReport({
+        status: "dry-run",
+        modelId: state.input.modelId,
+        durationMs: state.now() - state.startedAt,
+        patchFiles: accepted.validation.files,
+        dryRunPreview: renderDryRun(accepted.validation),
+        proposedDiff: accepted.diff,
+        coveredBehavior: accepted.coveredBehavior,
+        knownGaps: accepted.knownGaps,
+        nextActions: nextActionsFor(false, files),
+        failureReason: undefined,
+        verificationSummary: undefined,
+        verificationSkipReason: "verification skipped: dry-run, no files written",
+        modelCallCount: loop.modelCallCount,
+        patchRetryCount: loop.patchRetryCount,
+    });
+}
+export function cancelledReport(state, loop, accepted) {
+    return assembleReport({
+        status: "cancelled",
+        modelId: state.input.modelId,
+        durationMs: state.now() - state.startedAt,
+        patchFiles: accepted?.validation.files ?? [],
+        dryRunPreview: accepted === undefined ? undefined : renderDryRun(accepted.validation),
+        proposedDiff: accepted?.diff,
+        coveredBehavior: undefined,
+        knownGaps: undefined,
+        nextActions: ["The workflow was cancelled before completion"],
+        failureReason: undefined,
+        verificationSummary: undefined,
+        verificationSkipReason: "verification skipped: cancelled",
+        modelCallCount: loop.modelCallCount,
+        patchRetryCount: loop.patchRetryCount,
+    });
+}
+export function failedReport(state, error) {
+    const message = redact(error instanceof Error ? error.message : "unexpected workflow failure");
+    const errorCode = error instanceof Error ? error.name : "UNKNOWN";
+    state.emitter.emit({ type: "workflow:failed", errorCode, message });
+    return assembleReport({
+        status: "failed",
+        modelId: state.input.modelId,
+        durationMs: state.now() - state.startedAt,
+        patchFiles: [],
+        dryRunPreview: undefined,
+        proposedDiff: undefined,
+        coveredBehavior: undefined,
+        knownGaps: undefined,
+        nextActions: [`Inspect the error and retry: ${message}`],
+        failureReason: message,
+        verificationSummary: undefined,
+        verificationSkipReason: undefined,
+        modelCallCount: state.progress.modelCallCount,
+        patchRetryCount: state.progress.patchRetryCount,
+    });
+}
+async function applyAndVerify(state, workspace, loop, accepted) {
+    const fs = state.deps.fs ?? nodeWorkspaceFs;
+    let applyResult;
+    try {
+        applyResult = applyPatch(workspace, accepted.diff, {
+            applyEnabled: true,
+            signal: state.signal,
+            fs,
+            ...(state.deps.writer === undefined ? {} : { writer: state.deps.writer }),
+        });
+    }
+    catch (error) {
+        if (error instanceof CommandCancelledError) {
+            return cancelledReport(state, loop, accepted);
+        }
+        throw error;
+    }
+    state.emitter.emit({
+        type: "workflow:patch:applied",
+        changedFiles: applyResult.changedFiles.length,
+        created: applyResult.created.length,
+        deleted: applyResult.deleted.length,
+    });
+    if (state.signal.aborted) {
+        return cancelledReport(state, loop, accepted);
+    }
+    const verification = await runWorkflowVerification(state, workspace, fs);
+    return assembleReport({
+        status: "completed",
+        modelId: state.input.modelId,
+        durationMs: state.now() - state.startedAt,
+        patchFiles: accepted.validation.files,
+        dryRunPreview: renderDryRun(accepted.validation),
+        proposedDiff: accepted.diff,
+        coveredBehavior: accepted.coveredBehavior,
+        knownGaps: accepted.knownGaps,
+        nextActions: nextActionsFor(true, applyResult.changedFiles),
+        failureReason: undefined,
+        verificationSummary: verification.summary,
+        verificationSkipReason: verification.skipReason,
+        modelCallCount: loop.modelCallCount,
+        patchRetryCount: loop.patchRetryCount,
+    });
+}
+export function emitCompleted(state, report) {
+    state.emitter.emit({
+        type: "workflow:completed",
+        status: report.status,
+        durationMs: report.durationMs,
+    });
+    return report;
+}
+// Selects the terminal branch from the model-loop result: rejected (no patch), cancelled (abort
+// before apply), apply+verify (apply mode), or dry-run (default).
+export async function finishPipeline(state, workspace, loop) {
+    if (loop.accepted === undefined) {
+        return rejectedReport(state, loop);
+    }
+    if (state.signal.aborted) {
+        return cancelledReport(state, loop, loop.accepted);
+    }
+    if (state.input.apply === true) {
+        return applyAndVerify(state, workspace, loop, loop.accepted);
+    }
+    return dryRunReport(state, loop, loop.accepted);
+}

package/dist/workflows/unit-tests/types.d.ts

@@ -0,0 +1,70 @@
+import type { ModelPort } from "../../harness/ports.js";
+import type { SpawnFn, WorkspaceWriter } from "../../tools/index.js";
+import type { TestFramework, WorkspaceFs } from "../../workspace/index.js";
+import type { VerificationAuditSummary } from "../../verification/index.js";
+import type { WorkflowEventSink } from "./events.js";
+export type WorkflowStatus = "completed" | "dry-run" | "rejected" | "cancelled" | "failed";
+export type UnitTestTarget = {
+    readonly kind: "file";
+    readonly filePath: string;
+    readonly targetFunction?: string | undefined;
+} | {
+    readonly kind: "module";
+    readonly moduleDir: string;
+} | {
+    readonly kind: "changedFiles";
+    readonly filePaths: readonly string[];
+};
+export type FileNamingStyle = "sibling" | "mirrored" | "unknown";
+export interface TestConventions {
+    readonly framework: TestFramework;
+    readonly testDirs: readonly string[];
+    readonly fileNamingStyle: FileNamingStyle;
+    readonly assertionStyleSamples: readonly string[];
+}
+export interface WorkflowLimits {
+    readonly maxModelCalls: number;
+    readonly maxRetries: number;
+    readonly contextBudgetBytes: number;
+    readonly maxBytesPerFile: number;
+}
+export declare const DEFAULT_WORKFLOW_LIMITS: WorkflowLimits;
+export interface UnitTestWorkflowInput {
+    readonly workspaceRoot: string;
+    readonly target: UnitTestTarget;
+    readonly apply?: boolean | undefined;
+    readonly modelId: string;
+    readonly limits?: Partial<WorkflowLimits> | undefined;
+}
+export interface UnitTestWorkflowDeps {
+    readonly model: ModelPort;
+    readonly fs?: WorkspaceFs | undefined;
+    readonly writer?: WorkspaceWriter | undefined;
+    readonly spawn?: SpawnFn | undefined;
+    readonly now?: (() => number) | undefined;
+    readonly idSource?: (() => string) | undefined;
+    readonly sink?: WorkflowEventSink | undefined;
+    readonly processEnv?: NodeJS.ProcessEnv | undefined;
+    readonly signal?: AbortSignal | undefined;
+}
+export interface AddedTestFile {
+    readonly path: string;
+    readonly estimatedTestCount: number;
+}
+export interface UnitTestWorkflowReport {
+    readonly workflowId: "unit-test-generation";
+    readonly status: WorkflowStatus;
+    readonly modelId: string;
+    readonly durationMs: number;
+    readonly dryRunPreview?: string | undefined;
+    readonly proposedDiff?: string | undefined;
+    readonly addedTestFiles: readonly AddedTestFile[];
+    readonly coveredBehavior?: string | undefined;
+    readonly knownGaps?: string | undefined;
+    readonly nextActions: readonly string[];
+    readonly failureReason?: string | undefined;
+    readonly verificationSummary?: VerificationAuditSummary | undefined;
+    readonly verificationSkipReason?: string | undefined;
+    readonly modelCallCount: number;
+    readonly patchRetryCount: number;
+}

package/dist/workflows/unit-tests/types.js

@@ -0,0 +1,11 @@
+// All interfaces, type aliases, and frozen constant tables for the unit-test generation
+// workflow (ADR-0008 D2/D3/D7). No runtime logic lives here beyond the frozen tables the type
+// layer exposes as values, mirroring the ADR-0003/0004/0005/0006/0007 `types.ts` precedent.
+// `readonly` everywhere; optional props are `| undefined` because exactOptionalPropertyTypes
+// is on. Every report shape is plain JSON-serializable so the #10 audit ledger can persist it.
+export const DEFAULT_WORKFLOW_LIMITS = {
+    maxModelCalls: 3,
+    maxRetries: 2,
+    contextBudgetBytes: 65_536,
+    maxBytesPerFile: 8_192,
+};

package/dist/workflows/unit-tests/verify-stage.d.ts

@@ -0,0 +1,9 @@
+import { type WorkspaceFs, type WorkspaceInfo } from "../../workspace/index.js";
+import { type VerificationAuditSummary } from "../../verification/index.js";
+import type { RunState } from "./internal.js";
+export declare const SKIP_UNRESOLVED = "verification skipped: framework unknown or no test files resolved";
+export interface VerificationOutcome {
+    readonly summary: VerificationAuditSummary | undefined;
+    readonly skipReason: string | undefined;
+}
+export declare function runWorkflowVerification(state: RunState, workspace: WorkspaceInfo, fs: WorkspaceFs): Promise<VerificationOutcome>;