@oscharko-dev/keiko 0.1.0-beta.0

package/dist/workflows/unit-tests/verify-stage.js

@@ -0,0 +1,56 @@
+// The verification stage (ADR-0008 D5, steering note C). Runs ONLY after a successful apply: it
+// resolves a verification plan by deriving the just-created test from the target SOURCE file(s) via
+// #7 resolveTargetedTests, falling back to the full `test` script, and records an explicit skip
+// reason when neither resolves or the framework is unknown. Verification reuses the #7 orchestrator
+// unchanged; this stage only wires the plan and projects an output-text-free audit summary.
+import { nodeSpawnFn } from "../../tools/index.js";
+import {} from "../../workspace/index.js";
+import { buildVerificationPlan, detectScripts, resolveTargetedTests, runVerification, summarizeForAudit, DEFAULT_VERIFICATION_LIMITS, } from "../../verification/index.js";
+export const SKIP_UNRESOLVED = "verification skipped: framework unknown or no test files resolved";
+// The source files the target points at — passed to resolveTargetedTests so it can find the
+// just-created sibling/mirrored test (steering note C). Test files are NOT passed here.
+function targetSourceFiles(target) {
+    if (target.kind === "file") {
+        return [target.filePath];
+    }
+    if (target.kind === "changedFiles") {
+        return target.filePaths;
+    }
+    return [target.moduleDir];
+}
+function buildPlanFallback(workspace, fs) {
+    const catalog = detectScripts(workspace, fs);
+    return buildVerificationPlan(workspace, catalog, { only: ["test"] }, fs);
+}
+function resolveVerificationPlan(workspace, target, fs) {
+    const targeted = resolveTargetedTests(workspace, targetSourceFiles(target), fs, DEFAULT_VERIFICATION_LIMITS);
+    if (targeted.length > 0) {
+        return { workspaceRoot: workspace.root, steps: targeted };
+    }
+    const fallback = buildPlanFallback(workspace, fs);
+    const runnable = fallback.steps.filter((step) => step.skipReason === undefined);
+    return runnable.length > 0 ? { workspaceRoot: workspace.root, steps: runnable } : undefined;
+}
+export async function runWorkflowVerification(state, workspace, fs) {
+    const plan = resolveVerificationPlan(workspace, state.input.target, fs);
+    if (plan === undefined) {
+        return { summary: undefined, skipReason: SKIP_UNRESOLVED };
+    }
+    const report = await runVerification(plan, {
+        workspace,
+        signal: state.signal,
+        spawn: state.deps.spawn ?? nodeSpawnFn,
+        processEnv: state.deps.processEnv ?? process.env,
+        now: state.now,
+        fs,
+    });
+    const summary = summarizeForAudit(report);
+    state.emitter.emit({
+        type: "workflow:verification:result",
+        overallStatus: summary.overallStatus,
+        stepCount: summary.results.length,
+        passedCount: summary.results.filter((r) => r.status === "passed").length,
+        durationMs: summary.durationMs,
+    });
+    return { summary, skipReason: undefined };
+}

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

@@ -0,0 +1,2 @@
+import type { UnitTestWorkflowDeps, UnitTestWorkflowInput, UnitTestWorkflowReport } from "./types.js";
+export declare function generateUnitTests(input: UnitTestWorkflowInput, deps: UnitTestWorkflowDeps): Promise<UnitTestWorkflowReport>;

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

@@ -0,0 +1,58 @@
+// The single public entry: generateUnitTests (ADR-0008 D2/D5/D6). A deterministic linear pipeline
+// (NOT the harness loop): intake -> detect -> context -> conventions -> [prompt -> model -> parse ->
+// validate -> production-guard] (bounded retries) -> [dry-run | apply -> verify] -> report. It
+// composes #3-#7 UNCHANGED and emits redacted progress events. The model loop, verify stage, and
+// report stages live in sibling files to keep each under the LOC limit; this file owns only the
+// stage sequencing and the single top-level catch boundary that maps an unexpected IO failure to a
+// redacted "failed" report (and a CancelledError to a "cancelled" report).
+import { CancelledError } from "../../gateway/errors.js";
+import { detectWorkspace } from "../../workspace/index.js";
+import { nodeWorkspaceFs } from "../../workspace/fs.js";
+import { buildTestGenContext } from "./context.js";
+import { detectConventions } from "./conventions.js";
+import { computeFingerprint } from "./emit.js";
+import { runModelLoop } from "./model-loop.js";
+import { cancelledReport, emitCompleted, failedReport, finishPipeline } from "./stages.js";
+import { buildRunState, EMPTY_LOOP } from "./internal.js";
+async function runPipeline(state) {
+    const fs = state.deps.fs ?? nodeWorkspaceFs;
+    const workspace = detectWorkspace(state.input.workspaceRoot, fs);
+    state.emitter.emit({
+        type: "workflow:started",
+        workflowId: "unit-test-generation",
+        modelId: state.input.modelId,
+        applyEnabled: state.input.apply === true,
+        limits: state.limits,
+    });
+    const pack = buildTestGenContext(workspace, state.input, state.limits, { fs });
+    const conventions = detectConventions(workspace, pack);
+    state.emitter.emit({
+        type: "conventions:detected",
+        framework: conventions.framework,
+        testDirs: conventions.testDirs,
+        fileNamingStyle: conventions.fileNamingStyle,
+    });
+    state.emitter.emit({
+        type: "context:selected",
+        entryCount: pack.selected.length,
+        usedBytes: pack.usedBytes,
+        budgetBytes: pack.budgetBytes,
+        droppedForBudget: pack.droppedForBudget,
+    });
+    const loop = await runModelLoop(state, workspace, conventions, pack);
+    return finishPipeline(state, workspace, loop);
+}
+export async function generateUnitTests(input, deps) {
+    const state = buildRunState(input, deps, computeFingerprint(input.target, input.modelId));
+    let report;
+    try {
+        report = await runPipeline(state);
+    }
+    catch (error) {
+        report =
+            error instanceof CancelledError
+                ? cancelledReport(state, EMPTY_LOOP, undefined)
+                : failedReport(state, error);
+    }
+    return emitCompleted(state, report);
+}

package/dist/workspace/contextPack.d.ts

@@ -0,0 +1,9 @@
+import { type WorkspaceFs } from "./fs.js";
+import { type RetrievalStrategy } from "./retrieval.js";
+import { type ContextPack, type ContextRequest, type DiscoveredFile, type WorkspaceInfo } from "./types.js";
+export interface ContextPackDeps {
+    readonly fs: WorkspaceFs;
+    readonly strategy: RetrievalStrategy;
+}
+export declare function buildContextPack(workspace: WorkspaceInfo, request: ContextRequest, deps?: ContextPackDeps): ContextPack;
+export declare function buildContextPackFromFiles(workspace: WorkspaceInfo, request: ContextRequest, candidates: readonly DiscoveredFile[], deps?: ContextPackDeps): ContextPack;

package/dist/workspace/contextPack.js

@@ -0,0 +1,94 @@
+// Deterministic, explainable context-pack assembly (ADR-0005 D4). Resolution order:
+//   discover -> filter (deny/ignore/boundary, already applied by discovery) -> rank by an
+//   explainable category heuristic (selectionReason, stable path tie-break) -> greedily add
+//   excerpts until the byte budget is exhausted -> truncate each to maxBytesPerFile and
+//   redact() it -> record per-entry metadata.
+// No clock, no RNG: the same workspace + request always yields the same pack.
+import { nodeWorkspaceFs } from "./fs.js";
+import { discoverFiles, readWorkspaceFile } from "./discovery.js";
+import { lexicalRetrievalStrategy } from "./retrieval.js";
+import { DEFAULT_READ_OPTIONS, } from "./types.js";
+const DEFAULT_DEPS = {
+    fs: nodeWorkspaceFs,
+    strategy: lexicalRetrievalStrategy,
+};
+function utf8Bytes(value) {
+    return Buffer.byteLength(value, "utf8");
+}
+// Clamps a string to at most `maxBytes` UTF-8 bytes without splitting a multi-byte char.
+function clampToBytes(text, maxBytes) {
+    if (maxBytes <= 0) {
+        return { excerpt: "", truncated: true };
+    }
+    if (utf8Bytes(text) <= maxBytes) {
+        return { excerpt: text, truncated: false };
+    }
+    const buffer = Buffer.from(text, "utf8").subarray(0, maxBytes);
+    const excerpt = new TextDecoder("utf-8", { fatal: false }).decode(buffer).replace(/�+$/u, "");
+    return { excerpt, truncated: true };
+}
+// The read cap is the file-size safety ceiling, NOT the per-file excerpt budget: a large
+// file is read up to the ceiling and then excerpted by clampToBytes. Using the small
+// per-file budget here would wrongly reject any file bigger than the excerpt size.
+function readEntry(workspace, relPath, request, deps) {
+    const readCap = Math.max(request.maxBytesPerFile, DEFAULT_READ_OPTIONS.maxBytes);
+    try {
+        const content = readWorkspaceFile(workspace, relPath, { maxBytes: readCap }, deps.fs);
+        return { text: content.text, sizeBytes: content.sizeBytes, truncated: content.truncated };
+    }
+    catch {
+        // A file that is too large, denied, or unreadable is simply not packed.
+        return null;
+    }
+}
+function buildEntry(workspace, ranked, request, deps, remaining) {
+    const content = readEntry(workspace, ranked.file.relativePath, request, deps);
+    if (content === null) {
+        return null;
+    }
+    const perFileCap = Math.min(request.maxBytesPerFile, remaining);
+    const { excerpt, truncated } = clampToBytes(content.text, perFileCap);
+    if (excerpt.length === 0) {
+        return null;
+    }
+    return {
+        path: ranked.file.relativePath,
+        sizeBytes: content.sizeBytes,
+        excerptBytes: utf8Bytes(excerpt),
+        selectionReason: ranked.selectionReason,
+        truncated: truncated || content.truncated,
+        excerpt,
+    };
+}
+function tryAddEntry(workspace, ranked, request, deps, state) {
+    const remaining = request.budgetBytes - state.usedBytes;
+    if (remaining <= 0) {
+        state.droppedForBudget += 1;
+        return;
+    }
+    const entry = buildEntry(workspace, ranked, request, deps, remaining);
+    if (entry === null) {
+        return;
+    }
+    state.entries.push(entry);
+    state.usedBytes += entry.excerptBytes;
+}
+export function buildContextPack(workspace, request, deps = DEFAULT_DEPS) {
+    const candidates = discoverFiles(workspace, request.discovery, deps.fs);
+    return buildContextPackFromFiles(workspace, request, candidates, deps);
+}
+export function buildContextPackFromFiles(workspace, request, candidates, deps = DEFAULT_DEPS) {
+    const ranked = deps.strategy.rank(candidates, request.task);
+    const state = { entries: [], usedBytes: 0, droppedForBudget: 0 };
+    for (const item of ranked) {
+        tryAddEntry(workspace, item, request, deps, state);
+    }
+    return {
+        workspaceRoot: workspace.root,
+        totalCandidates: candidates.length,
+        selected: state.entries,
+        usedBytes: state.usedBytes,
+        budgetBytes: request.budgetBytes,
+        droppedForBudget: state.droppedForBudget,
+    };
+}

package/dist/workspace/detect.d.ts

@@ -0,0 +1,3 @@
+import { type WorkspaceFs } from "./fs.js";
+import type { WorkspaceInfo } from "./types.js";
+export declare function detectWorkspace(startDir: string, fs?: WorkspaceFs): WorkspaceInfo;

package/dist/workspace/detect.js

@@ -0,0 +1,135 @@
+// Workspace detection: walk up from a start directory to the nearest root containing a
+// `.git` entry or a `package.json`, then read safe metadata. The only JSON parse in the
+// module is wrapped in a single try/catch at this IO boundary (ADR-0005). No clock, no RNG.
+import { dirname, join, relative, resolve } from "node:path";
+import { nodeWorkspaceFs } from "./fs.js";
+import { WorkspaceNotFoundError } from "./errors.js";
+import { isDenied } from "./ignore.js";
+import { assertContainedRealPath } from "./realpath.js";
+const MARKERS = [".git", "package.json"];
+function isRoot(dir, fs) {
+    return MARKERS.some((marker) => fs.exists(join(dir, marker)));
+}
+function findRoot(startDir, fs) {
+    let current = resolve(startDir);
+    // Bounded by the filesystem: dirname() reaches a fixed point at the volume root.
+    for (;;) {
+        if (isRoot(current, fs)) {
+            return current;
+        }
+        const parent = dirname(current);
+        if (parent === current) {
+            throw new WorkspaceNotFoundError(`no workspace root (.git or package.json) found above ${startDir}`, startDir);
+        }
+        current = parent;
+    }
+}
+function asString(value) {
+    return typeof value === "string" ? value : undefined;
+}
+function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function depKeys(value) {
+    return isRecord(value) ? Object.keys(value) : [];
+}
+function detectFramework(record) {
+    const names = new Set([
+        ...depKeys(record.devDependencies),
+        ...depKeys(record.dependencies),
+    ]);
+    if (names.has("vitest")) {
+        return "vitest";
+    }
+    if (names.has("jest")) {
+        return "jest";
+    }
+    if (names.has("mocha")) {
+        return "mocha";
+    }
+    return "unknown";
+}
+const EMPTY_META = { name: undefined, version: undefined, testFramework: "unknown" };
+function toRelative(root, absolutePath) {
+    return relative(root, absolutePath).split("\\").join("/");
+}
+function toRealRelative(root, fs, absolutePath) {
+    try {
+        return toRelative(fs.realPath(root), absolutePath);
+    }
+    catch {
+        return toRelative(root, absolutePath);
+    }
+}
+function readContainedText(root, path, fs) {
+    if (!fs.exists(path)) {
+        return undefined;
+    }
+    try {
+        const containedPath = assertContainedRealPath(fs, root, path, path);
+        if (isDenied(toRealRelative(root, fs, containedPath))) {
+            return undefined;
+        }
+        return fs.readFileUtf8(containedPath);
+    }
+    catch {
+        return undefined;
+    }
+}
+function readPackageMeta(root, fs) {
+    const path = join(root, "package.json");
+    try {
+        const raw = readContainedText(root, path, fs);
+        if (raw === undefined) {
+            return EMPTY_META;
+        }
+        const parsed = JSON.parse(raw);
+        if (!isRecord(parsed)) {
+            return EMPTY_META;
+        }
+        return {
+            name: asString(parsed.name),
+            version: asString(parsed.version),
+            testFramework: detectFramework(parsed),
+        };
+    }
+    catch {
+        return EMPTY_META;
+    }
+}
+function readIgnoreLines(root, fs) {
+    const path = join(root, ".gitignore");
+    const raw = readContainedText(root, path, fs);
+    if (raw === undefined) {
+        return [];
+    }
+    return raw.split(/\r?\n/);
+}
+function isExistingDir(absolutePath, fs) {
+    return fs.exists(absolutePath) && fs.stat(absolutePath).isDirectory;
+}
+function detectDirs(root, fs, candidates) {
+    return candidates.filter((dir) => isExistingDir(join(root, dir), fs));
+}
+function detectLanguages(root, fs) {
+    const languages = [];
+    if (fs.exists(join(root, "tsconfig.json"))) {
+        languages.push("typescript");
+    }
+    languages.push("javascript");
+    return languages;
+}
+export function detectWorkspace(startDir, fs = nodeWorkspaceFs) {
+    const root = findRoot(startDir, fs);
+    const meta = readPackageMeta(root, fs);
+    return {
+        root,
+        name: meta.name,
+        version: meta.version,
+        testFramework: meta.testFramework,
+        sourceDirs: detectDirs(root, fs, ["src"]),
+        testDirs: detectDirs(root, fs, ["tests", "test", "__tests__"]),
+        languages: detectLanguages(root, fs),
+        ignoreLines: readIgnoreLines(root, fs),
+    };
+}

package/dist/workspace/discovery.d.ts

@@ -0,0 +1,9 @@
+import { type WorkspaceFs } from "./fs.js";
+import { type DiscoveredFile, type DiscoveryOptions, type DiscoveryStats, type FileContent, type ReadOptions, type WorkspaceInfo } from "./types.js";
+export interface DiscoveryResult {
+    readonly files: readonly DiscoveredFile[];
+    readonly stats: DiscoveryStats;
+}
+export declare function discoverFiles(workspace: WorkspaceInfo, opts: DiscoveryOptions, fs?: WorkspaceFs): readonly DiscoveredFile[];
+export declare function discoverWithStats(workspace: WorkspaceInfo, opts: DiscoveryOptions, fs?: WorkspaceFs): DiscoveryResult;
+export declare function readWorkspaceFile(workspace: WorkspaceInfo, relPath: string, opts?: ReadOptions, fs?: WorkspaceFs): FileContent;

package/dist/workspace/discovery.js

@@ -0,0 +1,167 @@
+// Recursive, bounded, deterministic file discovery and a single boundary-checked read path.
+// Security invariants (ADR-0005 D2/D3):
+//   - every directory descent and every read goes through resolveWithinWorkspace first;
+//   - always-on DENY patterns are applied before the optional .gitignore subset;
+//   - a symlink whose realpath escapes the root is skipped (never followed);
+//   - recursion is capped by maxDepth and total results by maxFiles.
+import { relative } from "node:path";
+import { nodeWorkspaceFs, } from "./fs.js";
+import { compileIgnore, isDenied, isIgnored } from "./ignore.js";
+import { resolveWithinWorkspace } from "./paths.js";
+import { assertContainedRealPath } from "./realpath.js";
+import { FileTooLargeError, PathDeniedError, WorkspaceReadError } from "./errors.js";
+import { redact } from "../gateway/redaction.js";
+import { DEFAULT_READ_OPTIONS, } from "./types.js";
+function toRelative(root, absolutePath) {
+    return relative(root, absolutePath).split("\\").join("/");
+}
+function toRealRelative(fs, root, absolutePath) {
+    try {
+        return toRelative(fs.realPath(root), absolutePath);
+    }
+    catch {
+        return toRelative(root, absolutePath);
+    }
+}
+// Returns false when the entry must be skipped for any security or noise reason, recording
+// which tier rejected it for the discovery stats.
+function isAllowed(walk, relPath, isDir) {
+    if (isDenied(relPath)) {
+        walk.denied += 1;
+        return false;
+    }
+    if (walk.applyGitignore && isIgnored(walk.matcher, relPath, isDir)) {
+        walk.ignored += 1;
+        return false;
+    }
+    return true;
+}
+function childRelative(root, absoluteDir, name) {
+    const dirRel = toRelative(root, absoluteDir);
+    return dirRel === "" ? name : `${dirRel}/${name}`;
+}
+function readDirSafe(walk, absoluteDir) {
+    try {
+        return walk.fs.readDir(absoluteDir);
+    }
+    catch {
+        return [];
+    }
+}
+function statSize(walk, absolutePath) {
+    try {
+        return walk.fs.stat(absolutePath).size;
+    }
+    catch {
+        return 0;
+    }
+}
+function handleEntry(walk, absoluteDir, entry, depth) {
+    const childAbs = resolveWithinWorkspace(walk.root, childRelative(walk.root, absoluteDir, entry.name));
+    const relPath = toRelative(walk.root, childAbs);
+    if (!isAllowed(walk, relPath, entry.isDirectory)) {
+        return;
+    }
+    // Symlinks are skipped unconditionally (for safety/simplicity). A non-symlink entry that
+    // reports neither isFile nor isDirectory is likewise treated as non-traversable noise.
+    // Only genuine files and directories are walked.
+    if (entry.isSymbolicLink) {
+        return;
+    }
+    if (entry.isDirectory) {
+        descend(walk, childAbs, depth + 1);
+        return;
+    }
+    if (entry.isFile) {
+        walk.out.push({ relativePath: relPath, sizeBytes: statSize(walk, childAbs) });
+    }
+}
+function descend(walk, absoluteDir, depth) {
+    if (depth > walk.opts.maxDepth || walk.out.length >= walk.opts.maxFiles) {
+        return;
+    }
+    const entries = [...readDirSafe(walk, absoluteDir)].sort((a, b) => (a.name < b.name ? -1 : 1));
+    for (const entry of entries) {
+        if (walk.out.length >= walk.opts.maxFiles) {
+            return;
+        }
+        handleEntry(walk, absoluteDir, entry, depth);
+    }
+}
+function runWalk(workspace, opts, fs) {
+    const walk = {
+        fs,
+        root: workspace.root,
+        matcher: compileIgnore(workspace.ignoreLines),
+        opts,
+        applyGitignore: opts.applyGitignore,
+        out: [],
+        denied: 0,
+        ignored: 0,
+    };
+    descend(walk, resolveWithinWorkspace(workspace.root, "."), 0);
+    return walk;
+}
+export function discoverFiles(workspace, opts, fs = nodeWorkspaceFs) {
+    return runWalk(workspace, opts, fs).out;
+}
+export function discoverWithStats(workspace, opts, fs = nodeWorkspaceFs) {
+    const walk = runWalk(workspace, opts, fs);
+    return {
+        files: walk.out,
+        stats: { discovered: walk.out.length, denied: walk.denied, ignored: walk.ignored },
+    };
+}
+function describe(error) {
+    return error instanceof Error ? error.message : "unknown error";
+}
+function statFile(fs, absolutePath, relPath) {
+    try {
+        return fs.stat(absolutePath);
+    }
+    catch (error) {
+        throw new WorkspaceReadError(`cannot stat file: ${relPath} (${describe(error)})`, relPath);
+    }
+}
+function assertNoHardLinkAlias(stats, relPath) {
+    if (stats.hardLinkCount !== undefined && stats.hardLinkCount > 1) {
+        throw new PathDeniedError(`refusing to read a hard-linked workspace alias: ${relPath}`, relPath);
+    }
+}
+function readContent(fs, absolutePath, relPath, opts) {
+    let raw;
+    try {
+        raw = fs.readFileUtf8(absolutePath);
+    }
+    catch (error) {
+        throw new WorkspaceReadError(`cannot read file: ${relPath} (${describe(error)})`, relPath);
+    }
+    const rawBytes = Buffer.byteLength(raw, "utf8");
+    const truncated = rawBytes > opts.maxBytes;
+    const text = truncated
+        ? Buffer.from(raw, "utf8").subarray(0, opts.maxBytes).toString("utf8")
+        : raw;
+    return { relativePath: relPath, sizeBytes: rawBytes, text: redact(text), truncated };
+}
+// The single read path. Order: boundary -> deny -> realpath containment -> size cap -> read -> redact.
+// Realpath containment is shared with the write/cwd paths via assertContainedRealPath: when the
+// path does not exist, it validates the nearest existing parent and returns absolutePath, so a
+// missing in-root file still surfaces as a WorkspaceReadError (not a false PathEscapeError).
+export function readWorkspaceFile(workspace, relPath, opts = DEFAULT_READ_OPTIONS, fs = nodeWorkspaceFs) {
+    const absolutePath = resolveWithinWorkspace(workspace.root, relPath);
+    const normalizedRel = toRelative(workspace.root, absolutePath);
+    if (isDenied(normalizedRel)) {
+        throw new PathDeniedError(`refusing to read a denied path: ${normalizedRel}`, normalizedRel);
+    }
+    const resolvedPath = assertContainedRealPath(fs, workspace.root, absolutePath, normalizedRel);
+    const resolvedRel = toRealRelative(fs, workspace.root, resolvedPath);
+    if (isDenied(resolvedRel)) {
+        throw new PathDeniedError(`refusing to read a denied path: ${normalizedRel}`, normalizedRel);
+    }
+    const stats = statFile(fs, resolvedPath, normalizedRel);
+    assertNoHardLinkAlias(stats, normalizedRel);
+    if (stats.size > opts.maxBytes) {
+        throw new FileTooLargeError(`file exceeds the read cap: ${normalizedRel}`, normalizedRel, stats.size, opts.maxBytes);
+    }
+    return readContent(fs, resolvedPath, normalizedRel, opts);
+}

package/dist/workspace/errors.d.ts

@@ -0,0 +1,39 @@
+export declare const WORKSPACE_CODES: {
+    readonly PATH_ESCAPE: "WORKSPACE_PATH_ESCAPE";
+    readonly PATH_DENIED: "WORKSPACE_PATH_DENIED";
+    readonly NOT_FOUND: "WORKSPACE_NOT_FOUND";
+    readonly FILE_TOO_LARGE: "WORKSPACE_FILE_TOO_LARGE";
+    readonly READ_FAILED: "WORKSPACE_READ_FAILED";
+};
+export type WorkspaceCode = (typeof WORKSPACE_CODES)[keyof typeof WORKSPACE_CODES];
+export declare abstract class WorkspaceError extends Error {
+    abstract readonly code: WorkspaceCode;
+    constructor(message: string, secrets?: readonly string[]);
+}
+export declare class PathEscapeError extends WorkspaceError {
+    readonly code: "WORKSPACE_PATH_ESCAPE";
+    readonly requestedPath: string;
+    constructor(message: string, requestedPath: string, secrets?: readonly string[]);
+}
+export declare class PathDeniedError extends WorkspaceError {
+    readonly code: "WORKSPACE_PATH_DENIED";
+    readonly requestedPath: string;
+    constructor(message: string, requestedPath: string, secrets?: readonly string[]);
+}
+export declare class WorkspaceNotFoundError extends WorkspaceError {
+    readonly code: "WORKSPACE_NOT_FOUND";
+    readonly startDir: string;
+    constructor(message: string, startDir: string, secrets?: readonly string[]);
+}
+export declare class FileTooLargeError extends WorkspaceError {
+    readonly code: "WORKSPACE_FILE_TOO_LARGE";
+    readonly requestedPath: string;
+    readonly sizeBytes: number;
+    readonly limitBytes: number;
+    constructor(message: string, requestedPath: string, sizeBytes: number, limitBytes: number, secrets?: readonly string[]);
+}
+export declare class WorkspaceReadError extends WorkspaceError {
+    readonly code: "WORKSPACE_READ_FAILED";
+    readonly requestedPath: string;
+    constructor(message: string, requestedPath: string, secrets?: readonly string[]);
+}

package/dist/workspace/errors.js

@@ -0,0 +1,66 @@
+// Workspace error taxonomy, mirroring the gateway/harness pattern (ADR-0003, ADR-0004).
+// Errors carry a stable `code` discriminant; callers switch on `code`, never parse
+// `message`. Every message is redacted at construction so errors are always safe to log.
+import { redact } from "../gateway/redaction.js";
+export const WORKSPACE_CODES = {
+    PATH_ESCAPE: "WORKSPACE_PATH_ESCAPE",
+    PATH_DENIED: "WORKSPACE_PATH_DENIED",
+    NOT_FOUND: "WORKSPACE_NOT_FOUND",
+    FILE_TOO_LARGE: "WORKSPACE_FILE_TOO_LARGE",
+    READ_FAILED: "WORKSPACE_READ_FAILED",
+};
+export class WorkspaceError extends Error {
+    constructor(message, secrets = []) {
+        super(redact(message, secrets));
+        this.name = new.target.name;
+    }
+}
+// Raised when a candidate path escapes the workspace root (NUL, `..`, or absolute escape).
+export class PathEscapeError extends WorkspaceError {
+    code = WORKSPACE_CODES.PATH_ESCAPE;
+    requestedPath;
+    constructor(message, requestedPath, secrets = []) {
+        super(message, secrets);
+        this.requestedPath = requestedPath;
+    }
+}
+// Raised when a path matches an always-on deny pattern (secrets, deps, build, vcs).
+export class PathDeniedError extends WorkspaceError {
+    code = WORKSPACE_CODES.PATH_DENIED;
+    requestedPath;
+    constructor(message, requestedPath, secrets = []) {
+        super(message, secrets);
+        this.requestedPath = requestedPath;
+    }
+}
+// Raised when no workspace root (`.git` or `package.json`) is found above startDir.
+export class WorkspaceNotFoundError extends WorkspaceError {
+    code = WORKSPACE_CODES.NOT_FOUND;
+    startDir;
+    constructor(message, startDir, secrets = []) {
+        super(message, secrets);
+        this.startDir = startDir;
+    }
+}
+// Raised when a file exceeds the configured read size cap.
+export class FileTooLargeError extends WorkspaceError {
+    code = WORKSPACE_CODES.FILE_TOO_LARGE;
+    requestedPath;
+    sizeBytes;
+    limitBytes;
+    constructor(message, requestedPath, sizeBytes, limitBytes, secrets = []) {
+        super(message, secrets);
+        this.requestedPath = requestedPath;
+        this.sizeBytes = sizeBytes;
+        this.limitBytes = limitBytes;
+    }
+}
+// Raised for an underlying filesystem read failure at the IO boundary.
+export class WorkspaceReadError extends WorkspaceError {
+    code = WORKSPACE_CODES.READ_FAILED;
+    requestedPath;
+    constructor(message, requestedPath, secrets = []) {
+        super(message, secrets);
+        this.requestedPath = requestedPath;
+    }
+}

package/dist/workspace/fs.d.ts

@@ -0,0 +1,21 @@
+export interface WorkspaceStat {
+    readonly size: number;
+    readonly isFile: boolean;
+    readonly isDirectory: boolean;
+    readonly isSymbolicLink: boolean;
+    readonly hardLinkCount?: number | undefined;
+}
+export interface WorkspaceDirEntry {
+    readonly name: string;
+    readonly isDirectory: boolean;
+    readonly isFile: boolean;
+    readonly isSymbolicLink: boolean;
+}
+export interface WorkspaceFs {
+    readonly readFileUtf8: (absolutePath: string) => string;
+    readonly stat: (absolutePath: string) => WorkspaceStat;
+    readonly readDir: (absolutePath: string) => readonly WorkspaceDirEntry[];
+    readonly realPath: (absolutePath: string) => string;
+    readonly exists: (absolutePath: string) => boolean;
+}
+export declare const nodeWorkspaceFs: WorkspaceFs;