@oscharko-dev/keiko 0.1.0-beta.0

package/dist/workspace/fs.js

@@ -0,0 +1,36 @@
+// The single filesystem boundary for the workspace layer (ADR-0005 D1). Every other module
+// depends on the `WorkspaceFs` port, never on `node:fs` directly, so discovery/detection are
+// testable with an in-memory fake and all real IO is auditable in one place. Synchronous, to
+// mirror the existing `loadConfigFromFile`/`readFileSync` usage in the gateway.
+import { lstatSync, readdirSync, readFileSync, realpathSync, statSync } from "node:fs";
+function isSymlink(absolutePath) {
+    return lstatSync(absolutePath, { throwIfNoEntry: false })?.isSymbolicLink() ?? false;
+}
+export const nodeWorkspaceFs = {
+    readFileUtf8: (absolutePath) => readFileSync(absolutePath, "utf8"),
+    stat: (absolutePath) => {
+        const stats = statSync(absolutePath, { throwIfNoEntry: true });
+        return {
+            size: stats.size,
+            isFile: stats.isFile(),
+            isDirectory: stats.isDirectory(),
+            isSymbolicLink: isSymlink(absolutePath),
+            hardLinkCount: stats.nlink,
+        };
+    },
+    readDir: (absolutePath) => readdirSync(absolutePath, { withFileTypes: true }).map((entry) => ({
+        name: entry.name,
+        isDirectory: entry.isDirectory(),
+        isFile: entry.isFile(),
+        isSymbolicLink: entry.isSymbolicLink(),
+    })),
+    realPath: (absolutePath) => realpathSync(absolutePath),
+    exists: (absolutePath) => {
+        try {
+            return statSync(absolutePath, { throwIfNoEntry: false }) !== undefined;
+        }
+        catch {
+            return false;
+        }
+    },
+};

package/dist/workspace/ignore.d.ts

@@ -0,0 +1,14 @@
+export declare const DEFAULT_DENY_PATTERNS: readonly string[];
+export declare function isDenied(relPath: string): boolean;
+interface IgnoreRule {
+    readonly regex: RegExp;
+    readonly dirEntryRegex: RegExp | null;
+    readonly negated: boolean;
+    readonly dirOnly: boolean;
+}
+export interface IgnoreMatcher {
+    readonly rules: readonly IgnoreRule[];
+}
+export declare function compileIgnore(lines: readonly string[]): IgnoreMatcher;
+export declare function isIgnored(matcher: IgnoreMatcher, relPath: string, isDir: boolean): boolean;
+export {};

package/dist/workspace/ignore.js

@@ -0,0 +1,176 @@
+// PURE filtering. Two tiers (ADR-0005 D3):
+//   1. isDenied()  — ALWAYS-ON security deny list. Enforced before every read regardless
+//      of .gitignore. Secret/dep/build/cache/vcs/log/os files are never discovered or read.
+//   2. compileIgnore()/isIgnored() — best-effort noise reduction over a DOCUMENTED, bounded
+//      .gitignore subset. Never relaxes the deny list.
+// Glob translation produces only linear regex pieces (`[^/]*`, `.*`) so there is no
+// catastrophic backtracking (no ReDoS).
+export const DEFAULT_DENY_PATTERNS = Object.freeze([
+    // secrets
+    ".env",
+    ".env.*",
+    "*.pem",
+    "*.key",
+    "id_rsa",
+    "id_ed25519",
+    "id_ecdsa",
+    "id_dsa",
+    "*.p12",
+    "*.pfx",
+    ".npmrc",
+    // deps
+    "node_modules",
+    // build
+    "dist",
+    "build",
+    "out",
+    "coverage",
+    // caches
+    ".cache",
+    ".next",
+    ".turbo",
+    // vcs
+    ".git",
+    // logs
+    "*.log",
+    // os
+    ".DS_Store",
+]);
+// Iterates from the end rather than using /\/+$/ to avoid quadratic ReDoS on
+// inputs with many consecutive trailing slashes (CodeQL js/polynomial-redos).
+function stripTrailingSlashes(value) {
+    let end = value.length;
+    while (end > 0 && value.charCodeAt(end - 1) === 47 /* "/" */) {
+        end -= 1;
+    }
+    return value.slice(0, end);
+}
+function normalize(relPath) {
+    return stripTrailingSlashes(relPath.replace(/\\/g, "/").replace(/^\.\//, ""));
+}
+function segments(relPath) {
+    return normalize(relPath)
+        .split("/")
+        .filter((part) => part.length > 0);
+}
+const EXAMPLE_ENV = ".env.example";
+// Always-on security check. Denied if ANY path segment matches a deny pattern (a denied
+// directory denies everything under it). `.env.example` is the single documented exception.
+// Matching is CASE-INSENSITIVE: on case-insensitive filesystems (macOS, Windows) `.ENV` and
+// `.env` name the same file, so a case-only variant must not bypass the deny list.
+export function isDenied(relPath) {
+    for (const part of segments(relPath)) {
+        const lower = part.toLowerCase();
+        if (lower === EXAMPLE_ENV) {
+            continue;
+        }
+        for (const matcher of PRECOMPILED_DENY_MATCHERS) {
+            if (matcher.regex.test(lower)) {
+                return true;
+            }
+        }
+    }
+    return false;
+}
+function globBody(glob) {
+    let body = "";
+    let i = 0;
+    while (i < glob.length) {
+        // charAt returns "" past the end; the loop bound guarantees a real char here, so there is
+        // no dead nullish fallback. charAt(i + 1)/(i + 2) safely return "" at the boundary.
+        const char = glob.charAt(i);
+        if (char === "*" && glob.charAt(i + 1) === "*") {
+            body += ".*";
+            i += glob.charAt(i + 2) === "/" ? 3 : 2;
+            continue;
+        }
+        if (char === "*") {
+            body += "[^/]*";
+        }
+        else if (char === "?") {
+            body += "[^/]";
+        }
+        else {
+            body += escapeLiteral(char);
+        }
+        i += 1;
+    }
+    return body;
+}
+function globToRegExp(glob, anchored) {
+    const prefix = anchored ? "^" : "^(?:.*/)?";
+    return new RegExp(`${prefix}${globBody(glob)}(?:/.*)?$`);
+}
+const PRECOMPILED_DENY_MATCHERS = DEFAULT_DENY_PATTERNS.map((pattern) => ({
+    regex: globToRegExp(pattern.toLowerCase(), false),
+}));
+// Matches the path that names the directory itself (no nested suffix), used so a `dir/` rule
+// can distinguish a real subdirectory from a same-named file at another depth.
+function globToDirEntryRegExp(glob, anchored) {
+    const prefix = anchored ? "^" : "^(?:.*/)?";
+    return new RegExp(`${prefix}${globBody(glob)}$`);
+}
+function escapeLiteral(char) {
+    return /[.*+?^${}()|[\]\\]/.test(char) ? `\\${char}` : char;
+}
+function stripAnchors(value, anchored, dirOnly) {
+    let core = value;
+    if (anchored) {
+        core = core.slice(1);
+    }
+    if (dirOnly) {
+        core = core.slice(0, -1);
+    }
+    return core;
+}
+function buildRule(rawLine) {
+    const line = rawLine.trim();
+    if (line.length === 0 || line.startsWith("#")) {
+        return null;
+    }
+    const negated = line.startsWith("!");
+    const afterBang = negated ? line.slice(1) : line;
+    const anchored = afterBang.startsWith("/");
+    const dirOnly = afterBang.endsWith("/");
+    const core = stripAnchors(afterBang, anchored, dirOnly);
+    if (core.length === 0) {
+        return null;
+    }
+    return {
+        regex: globToRegExp(core, anchored),
+        dirEntryRegex: dirOnly ? globToDirEntryRegExp(core, anchored) : null,
+        negated,
+        dirOnly,
+    };
+}
+export function compileIgnore(lines) {
+    const rules = [];
+    for (const line of lines) {
+        const rule = buildRule(line);
+        if (rule !== null) {
+            rules.push(rule);
+        }
+    }
+    return { rules };
+}
+export function isIgnored(matcher, relPath, isDir) {
+    const target = normalize(relPath);
+    let ignored = false;
+    for (const rule of matcher.rules) {
+        if (ruleMatches(rule, target, isDir)) {
+            ignored = !rule.negated;
+        }
+    }
+    return ignored;
+}
+// A `dir/` rule ignores either the matching directory entry itself (only when it IS a
+// directory), or any path genuinely nested under it. A same-named FILE is not ignored.
+function ruleMatches(rule, target, isDir) {
+    if (!rule.dirOnly) {
+        return rule.regex.test(target);
+    }
+    if (rule.dirEntryRegex?.test(target) === true) {
+        return isDir;
+    }
+    return rule.regex.test(target);
+}

package/dist/workspace/index.d.ts

@@ -0,0 +1,11 @@
+export type { AuditEntry, AuditSummary, ContextEntry, ContextEntrySummary, ContextPack, ContextPackSummary, ContextRequest, DiscoveredFile, DiscoveryOptions, DiscoveryStats, FileContent, ReadOptions, SelectionReason, TestFramework, WorkspaceInfo, WorkspaceLanguage, WorkspaceSummary, } from "./types.js";
+export { DEFAULT_CONTEXT_REQUEST, DEFAULT_DISCOVERY_OPTIONS, DEFAULT_READ_OPTIONS, SELECTION_REASON_PRIORITY, } from "./types.js";
+export { FileTooLargeError, PathDeniedError, PathEscapeError, WORKSPACE_CODES, WorkspaceError, WorkspaceNotFoundError, WorkspaceReadError, type WorkspaceCode, } from "./errors.js";
+export { type WorkspaceDirEntry, type WorkspaceFs, type WorkspaceStat } from "./fs.js";
+export { isWithinWorkspace, resolveWithinWorkspace } from "./paths.js";
+export { compileIgnore, DEFAULT_DENY_PATTERNS, isDenied, isIgnored, type IgnoreMatcher, } from "./ignore.js";
+export { detectWorkspace } from "./detect.js";
+export { discoverFiles, discoverWithStats, readWorkspaceFile, type DiscoveryResult, } from "./discovery.js";
+export { lexicalRetrievalStrategy, type RankedFile, type RetrievalStrategy } from "./retrieval.js";
+export { buildContextPack, buildContextPackFromFiles, type ContextPackDeps, } from "./contextPack.js";
+export { buildWorkspaceSummary, summarizeForAudit } from "./summary.js";

package/dist/workspace/index.js

@@ -0,0 +1,13 @@
+// Public barrel for the repository-context & workspace-access layer (ADR-0005). The only
+// file-read path exposed is the boundary-checked one; no export returns raw arbitrary file
+// content. Explicit named re-exports, `type` keyword for type-only, double quotes, `.js`.
+export { DEFAULT_CONTEXT_REQUEST, DEFAULT_DISCOVERY_OPTIONS, DEFAULT_READ_OPTIONS, SELECTION_REASON_PRIORITY, } from "./types.js";
+export { FileTooLargeError, PathDeniedError, PathEscapeError, WORKSPACE_CODES, WorkspaceError, WorkspaceNotFoundError, WorkspaceReadError, } from "./errors.js";
+export {} from "./fs.js";
+export { isWithinWorkspace, resolveWithinWorkspace } from "./paths.js";
+export { compileIgnore, DEFAULT_DENY_PATTERNS, isDenied, isIgnored, } from "./ignore.js";
+export { detectWorkspace } from "./detect.js";
+export { discoverFiles, discoverWithStats, readWorkspaceFile, } from "./discovery.js";
+export { lexicalRetrievalStrategy } from "./retrieval.js";
+export { buildContextPack, buildContextPackFromFiles, } from "./contextPack.js";
+export { buildWorkspaceSummary, summarizeForAudit } from "./summary.js";

package/dist/workspace/paths.d.ts

@@ -0,0 +1,2 @@
+export declare function resolveWithinWorkspace(root: string, candidate: string): string;
+export declare function isWithinWorkspace(root: string, candidate: string): boolean;

package/dist/workspace/paths.js

@@ -0,0 +1,38 @@
+// PURE, security-critical lexical path containment. This module performs NO filesystem
+// access: it decides whether a candidate path lexically resolves inside a workspace root.
+// Symlink/realpath containment (which DOES touch the filesystem) is enforced separately at
+// the IO edge in discovery.ts — see ADR-0005 D2 for the split.
+import { isAbsolute, relative, resolve, sep } from "node:path";
+import { PathEscapeError } from "./errors.js";
+function hasNul(value) {
+    return value.includes("\u0000");
+}
+// Returns the normalized absolute path of `candidate` inside `root`, or throws
+// PathEscapeError. The returned value is the ONLY path that downstream IO should read, so
+// a static analyser's path sanitizer sits on this boundary.
+export function resolveWithinWorkspace(root, candidate) {
+    if (hasNul(root) || hasNul(candidate)) {
+        throw new PathEscapeError("path contains a NUL byte", candidate);
+    }
+    const absoluteRoot = resolve(root);
+    const absoluteCandidate = isAbsolute(candidate)
+        ? resolve(candidate)
+        : resolve(absoluteRoot, candidate);
+    const rel = relative(absoluteRoot, absoluteCandidate);
+    if (rel === "") {
+        return absoluteRoot;
+    }
+    if (rel === ".." || rel.startsWith(`..${sep}`) || isAbsolute(rel)) {
+        throw new PathEscapeError(`path escapes the workspace boundary: ${candidate}`, candidate);
+    }
+    return absoluteCandidate;
+}
+export function isWithinWorkspace(root, candidate) {
+    try {
+        resolveWithinWorkspace(root, candidate);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}

package/dist/workspace/realpath.d.ts

@@ -0,0 +1,7 @@
+import type { WorkspaceFs } from "./fs.js";
+export interface ContainedRealPathInfo {
+    readonly path: string;
+    readonly realRelative: string;
+}
+export declare function containedRealPathInfo(fs: WorkspaceFs, root: string, absolutePath: string): ContainedRealPathInfo;
+export declare function assertContainedRealPath(fs: WorkspaceFs, root: string, absolutePath: string, _label: string): string;

package/dist/workspace/realpath.js

@@ -0,0 +1,72 @@
+// PURE-at-the-port symlink containment. After lexical resolveWithinWorkspace has proven a path is
+// lexically inside the root, this gate defends against the symlink class of escape: a path whose
+// real (symlink-followed) location is outside the root, or a not-yet-existing create target whose
+// nearest existing parent escapes via a symlink. Every filesystem touch goes through the injected
+// WorkspaceFs port (realPath only) so the logic stays testable with an in-memory fake and all real
+// IO is auditable in one place (ADR-0005 D2, ADR-0006 D2). The read path (discovery.ts) and the
+// write/cwd paths (tools/patch.ts, tools/exec.ts) share this single primitive — no duplicated logic.
+import { dirname } from "node:path";
+import { isWithinWorkspace } from "./paths.js";
+import { PathEscapeError } from "./errors.js";
+// Resolves `root` through any platform symlinks (e.g. macOS /var -> /private/var) so the
+// containment comparison is symlink-consistent on both sides. Falls back to the lexical root.
+function realRoot(fs, root) {
+    try {
+        return fs.realPath(root);
+    }
+    catch {
+        return root;
+    }
+}
+// Walks up from `absolutePath` to the nearest ancestor that exists on disk and returns its real
+// path. A create target does not exist yet, so we must realpath the deepest existing parent to
+// catch a symlinked parent directory (e.g. `link/evil` where `link` -> /outside). Bounded by the
+// path depth; terminates at the filesystem root where dirname is a fixpoint.
+function realNearestExisting(fs, absolutePath) {
+    let current = absolutePath;
+    for (;;) {
+        try {
+            return fs.realPath(current);
+        }
+        catch {
+            const parent = dirname(current);
+            if (parent === current) {
+                return absolutePath; // reached the root with nothing resolvable; lexical check stands
+            }
+            current = parent;
+        }
+    }
+}
+function toRelative(root, absolutePath) {
+    return absolutePath.slice(root.length).replace(/^[/\\]/, "");
+}
+export function containedRealPathInfo(fs, root, absolutePath) {
+    const realBase = realRoot(fs, root);
+    try {
+        const target = fs.realPath(absolutePath);
+        if (!isWithinWorkspace(realBase, target)) {
+            throw new PathEscapeError(`path escapes the workspace boundary via symlink: ${absolutePath}`, absolutePath);
+        }
+        return { path: target, realRelative: toRelative(realBase, target) };
+    }
+    catch (error) {
+        if (error instanceof PathEscapeError) {
+            throw error;
+        }
+        const parentReal = realNearestExisting(fs, absolutePath);
+        if (!isWithinWorkspace(realBase, parentReal)) {
+            throw new PathEscapeError(`path escapes the workspace boundary via symlink: ${absolutePath}`, absolutePath);
+        }
+        return { path: absolutePath, realRelative: toRelative(realBase, parentReal) };
+    }
+}
+// Asserts that `absolutePath` (already lexically contained) does not escape `root` via a symlink.
+// For an existing target, the target's own realpath must stay within the real root. For a
+// not-yet-existing target (create), the nearest existing ancestor's realpath must stay within it,
+// which blocks `create through a symlinked directory` (the S-H1 .git/hooks escalation).
+// Returns the canonical real path to hand to IO (existing case) or the lexically-resolved path
+// (pure-create case where the target itself has no realpath yet).
+export function assertContainedRealPath(fs, root, absolutePath, _label) {
+    const info = containedRealPathInfo(fs, root, absolutePath);
+    return info.path;
+}

package/dist/workspace/retrieval.d.ts

@@ -0,0 +1,9 @@
+import { type DiscoveredFile, type SelectionReason } from "./types.js";
+export interface RankedFile {
+    readonly file: DiscoveredFile;
+    readonly selectionReason: SelectionReason;
+}
+export interface RetrievalStrategy {
+    readonly rank: (files: readonly DiscoveredFile[], task: string | undefined) => readonly RankedFile[];
+}
+export declare const lexicalRetrievalStrategy: RetrievalStrategy;

package/dist/workspace/retrieval.js

@@ -0,0 +1,74 @@
+// Retrieval seam (ADR-0005 D5). `RetrievalStrategy` is the typed extension point a future
+// embedding ranker (e.g. `multilingual-e5-large`) plugs into. Wave-1 ships ONLY the seam and
+// a deterministic lexical default — no embeddings, no vector DB, no new dependency. The
+// default ranker is pure and clock/RNG-free so context packs are reproducible.
+import { SELECTION_REASON_PRIORITY } from "./types.js";
+const ENTRYPOINT_BASENAMES = new Set([
+    "index.ts",
+    "index.js",
+    "main.ts",
+    "main.js",
+    "cli.ts",
+    "cli.js",
+]);
+const MANIFEST_BASENAMES = new Set([
+    "package.json",
+    "tsconfig.json",
+    "tsconfig.build.json",
+]);
+const DOC_EXTENSIONS = new Set([".md", ".mdx", ".rst", ".txt"]);
+const CONFIG_EXTENSIONS = new Set([".json", ".yml", ".yaml", ".toml"]);
+const CONFIG_BASENAME_HINTS = [".config.", "eslint", "prettier", "vitest"];
+function basename(path) {
+    const idx = path.lastIndexOf("/");
+    return idx === -1 ? path : path.slice(idx + 1);
+}
+function extension(name) {
+    const idx = name.lastIndexOf(".");
+    return idx <= 0 ? "" : name.slice(idx);
+}
+function isTest(name) {
+    return /\.(test|spec)\.[cm]?[jt]sx?$/.test(name);
+}
+function isConfig(name) {
+    return (CONFIG_EXTENSIONS.has(extension(name)) || CONFIG_BASENAME_HINTS.some((h) => name.includes(h)));
+}
+function classify(path) {
+    const name = basename(path);
+    if (isTest(name) || path.startsWith("tests/") || path.startsWith("test/")) {
+        return "test";
+    }
+    if (ENTRYPOINT_BASENAMES.has(name)) {
+        return "entrypoint";
+    }
+    if (MANIFEST_BASENAMES.has(name)) {
+        return "manifest";
+    }
+    if (DOC_EXTENSIONS.has(extension(name))) {
+        return "documentation";
+    }
+    if (isConfig(name)) {
+        return "config";
+    }
+    return "source";
+}
+function priorityIndex(reason) {
+    return SELECTION_REASON_PRIORITY.indexOf(reason);
+}
+// Deterministic lexical ranking: by selection-reason priority, then by path (ascending).
+export const lexicalRetrievalStrategy = {
+    rank: (files) => {
+        const ranked = files.map((file) => ({ file, selectionReason: classify(file.relativePath) }));
+        return [...ranked].sort((a, b) => {
+            const byReason = priorityIndex(a.selectionReason) - priorityIndex(b.selectionReason);
+            if (byReason !== 0) {
+                return byReason;
+            }
+            if (a.file.relativePath < b.file.relativePath)
+                return -1;
+            if (a.file.relativePath > b.file.relativePath)
+                return 1;
+            return 0;
+        });
+    },
+};

package/dist/workspace/summary.d.ts

@@ -0,0 +1,3 @@
+import type { AuditSummary, ContextPack, DiscoveryStats, WorkspaceInfo, WorkspaceSummary } from "./types.js";
+export declare function buildWorkspaceSummary(workspace: WorkspaceInfo, pack?: ContextPack, stats?: DiscoveryStats): WorkspaceSummary;
+export declare function summarizeForAudit(pack: ContextPack): AuditSummary;

package/dist/workspace/summary.js

@@ -0,0 +1,54 @@
+// The structured, redacted view CLI/SDK/UI render WITHOUT touching the filesystem. Every
+// string that could carry file content is already redacted upstream (context excerpts pass
+// through redact() in discovery/contextPack). This module only reshapes already-safe data;
+// it performs no IO and adds no raw file contents. Pure and deterministic.
+function toContextSummary(pack) {
+    return {
+        totalCandidates: pack.totalCandidates,
+        usedBytes: pack.usedBytes,
+        budgetBytes: pack.budgetBytes,
+        droppedForBudget: pack.droppedForBudget,
+        entries: pack.selected.map((entry) => ({
+            path: entry.path,
+            sizeBytes: entry.sizeBytes,
+            excerptBytes: entry.excerptBytes,
+            selectionReason: entry.selectionReason,
+            truncated: entry.truncated,
+            excerpt: entry.excerpt,
+        })),
+    };
+}
+function statsFor(pack) {
+    return { discovered: pack?.totalCandidates ?? 0, denied: 0, ignored: 0 };
+}
+export function buildWorkspaceSummary(workspace, pack, stats) {
+    return {
+        root: workspace.root,
+        name: workspace.name,
+        version: workspace.version,
+        testFramework: workspace.testFramework,
+        sourceDirs: workspace.sourceDirs,
+        testDirs: workspace.testDirs,
+        languages: workspace.languages,
+        counts: stats ?? statsFor(pack),
+        context: pack === undefined ? undefined : toContextSummary(pack),
+    };
+}
+// Selected-context metadata for audit evidence: paths, sizes, reasons, and budget usage.
+// Deliberately excludes excerpt TEXT so an audit record carries no file content at all.
+export function summarizeForAudit(pack) {
+    return {
+        workspaceRoot: pack.workspaceRoot,
+        totalCandidates: pack.totalCandidates,
+        usedBytes: pack.usedBytes,
+        budgetBytes: pack.budgetBytes,
+        droppedForBudget: pack.droppedForBudget,
+        entries: pack.selected.map((entry) => ({
+            path: entry.path,
+            sizeBytes: entry.sizeBytes,
+            excerptBytes: entry.excerptBytes,
+            selectionReason: entry.selectionReason,
+            truncated: entry.truncated,
+        })),
+    };
+}

package/dist/workspace/types.d.ts

@@ -0,0 +1,103 @@
+export type WorkspaceLanguage = "typescript" | "javascript";
+export type TestFramework = "vitest" | "jest" | "mocha" | "unknown";
+export interface WorkspaceInfo {
+    readonly root: string;
+    readonly name: string | undefined;
+    readonly version: string | undefined;
+    readonly testFramework: TestFramework;
+    readonly sourceDirs: readonly string[];
+    readonly testDirs: readonly string[];
+    readonly languages: readonly WorkspaceLanguage[];
+    readonly ignoreLines: readonly string[];
+}
+export interface DiscoveredFile {
+    readonly relativePath: string;
+    readonly sizeBytes: number;
+}
+export interface DiscoveryOptions {
+    readonly maxDepth: number;
+    readonly maxFiles: number;
+    readonly applyGitignore: boolean;
+}
+export declare const DEFAULT_DISCOVERY_OPTIONS: DiscoveryOptions;
+export interface DiscoveryStats {
+    readonly discovered: number;
+    readonly denied: number;
+    readonly ignored: number;
+}
+export interface ReadOptions {
+    readonly maxBytes: number;
+}
+export declare const DEFAULT_READ_OPTIONS: ReadOptions;
+export interface FileContent {
+    readonly relativePath: string;
+    readonly sizeBytes: number;
+    readonly text: string;
+    readonly truncated: boolean;
+}
+export type SelectionReason = "entrypoint" | "manifest" | "documentation" | "config" | "source" | "test";
+export declare const SELECTION_REASON_PRIORITY: readonly SelectionReason[];
+export interface ContextRequest {
+    readonly task: string | undefined;
+    readonly budgetBytes: number;
+    readonly maxBytesPerFile: number;
+    readonly discovery: DiscoveryOptions;
+}
+export declare const DEFAULT_CONTEXT_REQUEST: ContextRequest;
+export interface ContextEntry {
+    readonly path: string;
+    readonly sizeBytes: number;
+    readonly excerptBytes: number;
+    readonly selectionReason: SelectionReason;
+    readonly truncated: boolean;
+    readonly excerpt: string;
+}
+export interface ContextPack {
+    readonly workspaceRoot: string;
+    readonly totalCandidates: number;
+    readonly selected: readonly ContextEntry[];
+    readonly usedBytes: number;
+    readonly budgetBytes: number;
+    readonly droppedForBudget: number;
+}
+export interface ContextEntrySummary {
+    readonly path: string;
+    readonly sizeBytes: number;
+    readonly excerptBytes: number;
+    readonly selectionReason: SelectionReason;
+    readonly truncated: boolean;
+    readonly excerpt: string;
+}
+export interface ContextPackSummary {
+    readonly totalCandidates: number;
+    readonly usedBytes: number;
+    readonly budgetBytes: number;
+    readonly droppedForBudget: number;
+    readonly entries: readonly ContextEntrySummary[];
+}
+export interface WorkspaceSummary {
+    readonly root: string;
+    readonly name: string | undefined;
+    readonly version: string | undefined;
+    readonly testFramework: TestFramework;
+    readonly sourceDirs: readonly string[];
+    readonly testDirs: readonly string[];
+    readonly languages: readonly WorkspaceLanguage[];
+    readonly counts: DiscoveryStats;
+    readonly context: ContextPackSummary | undefined;
+}
+export interface AuditEntry {
+    readonly path: string;
+    readonly sizeBytes: number;
+    readonly excerptBytes: number;
+    readonly selectionReason: SelectionReason;
+    readonly truncated: boolean;
+}
+export interface AuditSummary {
+    readonly workspaceRoot: string;
+    readonly totalCandidates: number;
+    readonly usedBytes: number;
+    readonly budgetBytes: number;
+    readonly droppedForBudget: number;
+    readonly entries: readonly AuditEntry[];
+}

package/dist/workspace/types.js

@@ -0,0 +1,27 @@
+// All workspace-layer interfaces and the frozen default tables. No runtime logic lives
+// here beyond the frozen constant tables the type layer must expose as values, mirroring
+// the ADR-0003/ADR-0004 `types.ts` precedent. `readonly` everywhere; optional props are
+// `| undefined` because exactOptionalPropertyTypes is on.
+export const DEFAULT_DISCOVERY_OPTIONS = {
+    maxDepth: 12,
+    maxFiles: 5_000,
+    applyGitignore: true,
+};
+export const DEFAULT_READ_OPTIONS = {
+    maxBytes: 262_144,
+};
+// Priority order used to rank candidates: lower index wins. Ties break on lexical path.
+export const SELECTION_REASON_PRIORITY = [
+    "entrypoint",
+    "manifest",
+    "documentation",
+    "config",
+    "source",
+    "test",
+];
+export const DEFAULT_CONTEXT_REQUEST = {
+    task: undefined,
+    budgetBytes: 65_536,
+    maxBytesPerFile: 8_192,
+    discovery: DEFAULT_DISCOVERY_OPTIONS,
+};