@oscharko-dev/keiko 0.1.0-beta.0

package/dist/audit/report.js

@@ -0,0 +1,50 @@
+// Final-report payload + renderer (ADR-0010 D9). buildEvidenceReport produces a structured,
+// JSON-serializable summary of a persisted manifest; renderEvidenceReport renders it for the CLI.
+// Both are PURE (no IO). knownLimitations is static text stating the Wave-1 evidence bounds
+// (no tamper-evidence, no encryption at rest, per-run cost attribution) so a reviewer reads the
+// honest trust boundary alongside the evidence.
+const KNOWN_LIMITATIONS = [
+    "Evidence files are developer-writable: no tamper-evidence or immutability (out of scope).",
+    "Evidence is stored as plaintext JSON: no encryption at rest; redaction removes known shapes only.",
+    "Cost attribution is per-run (the declared model's class), not per model call.",
+];
+function statusFromHarnessResults(results) {
+    if (results === undefined || results.length === 0) {
+        return "not-run";
+    }
+    return results.every((result) => result.passed) ? "passed" : "failed";
+}
+function verificationStatus(manifest) {
+    return (manifest.verification?.overallStatus ?? statusFromHarnessResults(manifest.verificationResults));
+}
+export function buildEvidenceReport(manifest, location) {
+    return {
+        evidenceLocation: location,
+        runId: manifest.run.runId,
+        fingerprint: manifest.run.fingerprint,
+        taskType: manifest.run.taskType,
+        outcome: manifest.run.outcome,
+        changedFiles: manifest.patch?.changedFiles ?? 0,
+        usageTotals: manifest.usageTotals,
+        costClass: manifest.model.costClass,
+        verificationStatus: verificationStatus(manifest),
+        knownLimitations: KNOWN_LIMITATIONS,
+    };
+}
+export function renderEvidenceReport(report) {
+    const { usageTotals: u } = report;
+    const lines = [
+        `Evidence: ${report.evidenceLocation}`,
+        `  run            ${report.runId} (fingerprint ${report.fingerprint})`,
+        `  task           ${report.taskType}`,
+        `  outcome        ${report.outcome}`,
+        `  changed files  ${String(report.changedFiles)}`,
+        `  usage          ${String(u.promptTokens)} prompt / ${String(u.completionTokens)} completion tokens, ` +
+            `${String(u.requestCount)} request(s), ${String(u.totalLatencyMs)}ms`,
+        `  cost class     ${report.costClass}`,
+        `  verification   ${report.verificationStatus}`,
+        "  known limitations:",
+        ...report.knownLimitations.map((limitation) => `    - ${limitation}`),
+    ];
+    return `${lines.join("\n")}\n`;
+}

package/dist/audit/retention.d.ts

@@ -0,0 +1,3 @@
+import type { EvidenceStore } from "./store.js";
+import type { RetentionPolicy } from "./types.js";
+export declare function applyRetention(store: EvidenceStore, policy: RetentionPolicy): void;

package/dist/audit/retention.js

@@ -0,0 +1,95 @@
+// Retention and rotation (ADR-0010 D6). The single most dangerous operation in the layer, so it is
+// the most tightly bounded: it deletes ONLY ledger-created `<runId>.json` files (every runId the
+// store enumerates already passed assertValidRunId), inside the contained base dir, via
+// EvidenceStore.delete. It computes the delete set then deletes that set (no recursion). "Oldest" is
+// read from each manifest's finishedAt header — never filesystem mtime, which a developer touch
+// could perturb. When disabled, deletion is a no-op. An unparseable manifest is left untouched
+// rather than risking deletion of a file we cannot read a header from.
+function readHeader(json) {
+    try {
+        const parsed = JSON.parse(json);
+        const finishedAt = parsed.run?.finishedAt;
+        if (typeof finishedAt !== "number") {
+            return undefined;
+        }
+        return { finishedAt, bytes: Buffer.byteLength(json, "utf8") };
+    }
+    catch {
+        return undefined;
+    }
+}
+// Newest-first ordering by finishedAt; ties broken by runId so the order is deterministic.
+function collectCandidates(store) {
+    const candidates = [];
+    for (const runId of store.list()) {
+        const json = store.get(runId);
+        if (json === undefined) {
+            continue;
+        }
+        const header = readHeader(json);
+        if (header === undefined) {
+            continue;
+        }
+        candidates.push({ runId, finishedAt: header.finishedAt, bytes: header.bytes });
+    }
+    candidates.sort((a, b) => b.finishedAt - a.finishedAt || a.runId.localeCompare(b.runId));
+    return candidates;
+}
+function beyondMaxRuns(sorted, maxRuns) {
+    return sorted.slice(Math.max(maxRuns, 0)).map((c) => c.runId);
+}
+function olderThanAge(sorted, maxAgeMs) {
+    const newest = sorted[0]?.finishedAt;
+    if (newest === undefined) {
+        return [];
+    }
+    const cutoff = newest - maxAgeMs;
+    return sorted.filter((c) => c.finishedAt < cutoff).map((c) => c.runId);
+}
+function overByteCap(sorted, maxTotalBytes) {
+    const doomed = [];
+    let running = 0;
+    // Walk newest-first, keeping manifests until the cap is reached; the rest (oldest) are deleted.
+    // The newest manifest (index 0) is ALWAYS kept even if it alone exceeds the cap — retention must
+    // never delete the just-written run, and "delete oldest until under the cap" cannot apply to a
+    // single most-recent file.
+    for (let i = 0; i < sorted.length; i += 1) {
+        const candidate = sorted[i];
+        if (candidate === undefined) {
+            continue;
+        }
+        running += candidate.bytes;
+        if (i > 0 && running > maxTotalBytes) {
+            doomed.push(candidate.runId);
+        }
+    }
+    return doomed;
+}
+function computeDeleteSet(sorted, policy) {
+    const doomed = new Set();
+    if (policy.maxRuns !== undefined) {
+        for (const id of beyondMaxRuns(sorted, policy.maxRuns)) {
+            doomed.add(id);
+        }
+    }
+    if (policy.maxAgeMs !== undefined) {
+        for (const id of olderThanAge(sorted, policy.maxAgeMs)) {
+            doomed.add(id);
+        }
+    }
+    if (policy.maxTotalBytes !== undefined) {
+        for (const id of overByteCap(sorted, policy.maxTotalBytes)) {
+            doomed.add(id);
+        }
+    }
+    return doomed;
+}
+export function applyRetention(store, policy) {
+    if (policy.disabled === true) {
+        return;
+    }
+    const sorted = collectCandidates(store);
+    for (const runId of computeDeleteSet(sorted, policy)) {
+        store.delete(runId);
+    }
+}

package/dist/audit/runid.d.ts

@@ -0,0 +1 @@
+export declare function assertValidRunId(runId: string): void;

package/dist/audit/runid.js

@@ -0,0 +1,29 @@
+// PURE, bounded runId validation (ADR-0010 D4 iii). The manifest filename is ALWAYS derived from a
+// validated runId, so a malicious runId cannot escape the contained base dir or overwrite an
+// arbitrary file. We accept only a bounded [A-Za-z0-9._-] character set with a length cap and reject
+// a leading dot (no dotfiles, no `..`). NO REGEX is used (D3 no-new-regex rule) — validation is a
+// per-character class check, which is also trivially linear-time.
+import { InvalidRunIdError } from "./errors.js";
+const MAX_RUN_ID_LENGTH = 256;
+// Inclusive ASCII code-point ranges for the allowed class, plus the three allowed punctuation
+// characters. A leading dot is rejected separately so `.` is allowed only in non-leading position.
+function isAllowedChar(code) {
+    const isDigit = code >= 48 && code <= 57; // 0-9
+    const isUpper = code >= 65 && code <= 90; // A-Z
+    const isLower = code >= 97 && code <= 122; // a-z
+    const isPunct = code === 46 || code === 95 || code === 45; // . _ -
+    return isDigit || isUpper || isLower || isPunct;
+}
+export function assertValidRunId(runId) {
+    if (runId.length === 0 || runId.length > MAX_RUN_ID_LENGTH) {
+        throw new InvalidRunIdError(`invalid runId length: ${String(runId.length)}`);
+    }
+    if (runId.startsWith(".")) {
+        throw new InvalidRunIdError("runId must not start with a dot");
+    }
+    for (let i = 0; i < runId.length; i += 1) {
+        if (!isAllowedChar(runId.charCodeAt(i))) {
+            throw new InvalidRunIdError("runId contains a disallowed character");
+        }
+    }
+}

package/dist/audit/side-file.d.ts

@@ -0,0 +1,12 @@
+import { type WorkspaceFs } from "../workspace/fs.js";
+export interface SideFileWriteResult {
+    readonly relativePath: string;
+    readonly sha256: string;
+    readonly bytes: number;
+    readonly absolutePath: string;
+}
+export interface SideFileWriterOptions {
+    readonly fs?: WorkspaceFs;
+    readonly randomSuffix?: () => string;
+}
+export declare function writeSideFile(baseDir: string, runId: string, name: string, data: Buffer, options?: SideFileWriterOptions): SideFileWriteResult;

package/dist/audit/side-file.js

@@ -0,0 +1,82 @@
+// ADR-0017 D5 — side-file writer for binary evidence (e.g. screenshots) that does NOT fit the
+// text-only EvidenceManifest JSON. Atomic O_EXCL temp + rename, realpath-contained against the
+// per-run subdirectory of evidenceDir, SHA-256 computed over the raw bytes. Reuses the workspace
+// realpath-containment primitive — no new path-safety mechanism is introduced. `evidenceSchemaVersion`
+// stays "1" (additive manifest field consumed by callers).
+import { createHash, randomUUID } from "node:crypto";
+import { mkdirSync, renameSync, rmSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { nodeWorkspaceFs } from "../workspace/fs.js";
+import { resolveWithinWorkspace } from "../workspace/paths.js";
+import { assertContainedRealPath } from "../workspace/realpath.js";
+import { assertValidRunId } from "./runid.js";
+import { EvidenceWriteError } from "./errors.js";
+const MAX_NAME_LENGTH = 128;
+// Validates a side-file basename. The set is intentionally narrower than runId's: a name segment
+// is a single non-empty path component with no separators, no leading dot, no `..`, length cap. No
+// regex — character-class check stays linear-time.
+function assertValidName(name) {
+    if (name.length === 0 || name.length > MAX_NAME_LENGTH) {
+        throw new EvidenceWriteError("side-file name length is invalid");
+    }
+    if (name.startsWith(".")) {
+        throw new EvidenceWriteError("side-file name must not start with a dot");
+    }
+    for (let i = 0; i < name.length; i += 1) {
+        if (!isAllowedNameChar(name.charCodeAt(i))) {
+            throw new EvidenceWriteError("side-file name contains a disallowed character");
+        }
+    }
+}
+function isAllowedNameChar(code) {
+    const isDigit = code >= 48 && code <= 57;
+    const isUpper = code >= 65 && code <= 90;
+    const isLower = code >= 97 && code <= 122;
+    const isPunct = code === 46 || code === 95 || code === 45;
+    return isDigit || isUpper || isLower || isPunct;
+}
+function ensureDir(absolute) {
+    try {
+        mkdirSync(absolute, { recursive: true });
+    }
+    catch (error) {
+        throw new EvidenceWriteError(`cannot create evidence subdirectory: ${error instanceof Error ? error.message : "unknown"}`);
+    }
+}
+function atomicWriteBytes(target, data, randomSuffix) {
+    const temp = `${target}.${randomSuffix()}.tmp`;
+    try {
+        // O_EXCL ("wx") refuses to open through a pre-planted symlink at the temp path. The randomUUID
+        // suffix never collides so "wx" never spuriously fails.
+        writeFileSync(temp, data, { flag: "wx" });
+        renameSync(temp, target);
+    }
+    catch (error) {
+        rmSync(temp, { force: true });
+        throw new EvidenceWriteError(`side-file write failed: ${error instanceof Error ? error.message : "unknown"}`);
+    }
+}
+// Writes a binary side-file under `<baseDir>/<runId>/<name>` atomically. Containment is enforced
+// by realpath-resolving the per-run directory after creation, then checking the final lexical path
+// against that real root via assertContainedRealPath. Returns the relative path to embed in the
+// manifest plus the SHA-256 of the raw bytes (tamper-evidence).
+export function writeSideFile(baseDir, runId, name, data, options = {}) {
+    assertValidRunId(runId);
+    assertValidName(name);
+    const fs = options.fs ?? nodeWorkspaceFs;
+    const randomSuffix = options.randomSuffix ?? randomUUID;
+    ensureDir(baseDir);
+    const runDir = join(baseDir, runId);
+    ensureDir(runDir);
+    const realRunDir = fs.realPath(runDir);
+    const lexicalTarget = resolveWithinWorkspace(realRunDir, name);
+    const absoluteTarget = assertContainedRealPath(fs, realRunDir, lexicalTarget, name);
+    const sha256 = createHash("sha256").update(data).digest("hex");
+    atomicWriteBytes(absoluteTarget, data, randomSuffix);
+    return {
+        relativePath: name,
+        sha256,
+        bytes: data.length,
+        absolutePath: absoluteTarget,
+    };
+}

package/dist/audit/store.d.ts

@@ -0,0 +1,12 @@
+import { type WorkspaceFs } from "../workspace/fs.js";
+export declare const DEFAULT_EVIDENCE_DIR = "./.keiko/evidence";
+export declare function resolveEvidenceDir(explicit: string | undefined, env: Readonly<Record<string, string | undefined>> | undefined): string;
+export interface EvidenceStore {
+    readonly put: (runId: string, json: string) => string;
+    readonly list: () => readonly string[];
+    readonly get: (runId: string) => string | undefined;
+    readonly location?: ((runId: string) => string) | undefined;
+    readonly delete: (runId: string) => void;
+}
+export declare function createInMemoryEvidenceStore(): EvidenceStore;
+export declare function createNodeEvidenceStore(baseDir: string, fs?: WorkspaceFs, randomSuffix?: () => string): EvidenceStore;

package/dist/audit/store.js

@@ -0,0 +1,198 @@
+// The EvidenceStore PORT + node adapter (ADR-0010 D4). A single manifest-record-typed port
+// (read+write+list+delete) keeps all real IO in one auditable place and makes the layer testable
+// with an in-memory store. We deliberately introduce a new port rather than reuse the #6
+// WorkspaceWriter, which has no read/list capability that D5 requires.
+//
+// Safety: the node adapter realpath-contains its base dir once at construction (reusing the #5/#6
+// primitives), every filename is derived from a VALIDATED runId (assertValidRunId), and the
+// resolved child path is re-checked to remain inside the contained base dir before any write,
+// read, or delete. Writes are atomic (temp + rename, same dir = same filesystem). list() returns
+// only real `<runId>.json` files and never follows a symlink (lstat skip).
+import { readdirSync, readFileSync, lstatSync, mkdirSync, renameSync, rmSync, writeFileSync, } from "node:fs";
+import { randomUUID } from "node:crypto";
+import { join, resolve } from "node:path";
+import { nodeWorkspaceFs } from "../workspace/fs.js";
+import { resolveWithinWorkspace } from "../workspace/paths.js";
+import { assertContainedRealPath } from "../workspace/realpath.js";
+import { EvidenceReadError, EvidenceWriteError } from "./errors.js";
+import { assertValidRunId } from "./runid.js";
+const MANIFEST_SUFFIX = ".json";
+// The workspace-relative default evidence base dir (ADR-0010 D4): predictable, local, .gitignored.
+export const DEFAULT_EVIDENCE_DIR = "./.keiko/evidence";
+// Single source of the output-location precedence (ADR-0010 D4): an explicit value (CLI
+// --evidence-dir) wins over the KEIKO_EVIDENCE_DIR env var, which wins over the default. Shared by
+// the CLI run command and the SDK persistEvidence default so both resolve identically.
+export function resolveEvidenceDir(explicit, env) {
+    return explicit ?? env?.KEIKO_EVIDENCE_DIR ?? DEFAULT_EVIDENCE_DIR;
+}
+// ─── In-memory store (tests) ──────────────────────────────────────────────────────
+export function createInMemoryEvidenceStore() {
+    const data = new Map();
+    return {
+        put: (runId, json) => {
+            assertValidRunId(runId);
+            data.set(runId, json);
+            return `${runId}${MANIFEST_SUFFIX}`;
+        },
+        list: () => [...data.keys()].sort(),
+        get: (runId) => {
+            assertValidRunId(runId);
+            return data.get(runId);
+        },
+        location: (runId) => {
+            assertValidRunId(runId);
+            return `${runId}${MANIFEST_SUFFIX}`;
+        },
+        delete: (runId) => {
+            assertValidRunId(runId);
+            data.delete(runId);
+        },
+    };
+}
+// ─── Node adapter ──────────────────────────────────────────────────────────────────
+// Resolves the base dir, creates it if absent, then realpath-contains it against itself so the
+// returned path is the canonical (symlink-followed) base every child path is checked against.
+function prepareBaseDir(baseDir, fs) {
+    try {
+        mkdirSync(baseDir, { recursive: true });
+        return fs.realPath(baseDir);
+    }
+    catch (error) {
+        throw new EvidenceWriteError(`cannot create evidence directory: ${error instanceof Error ? error.message : "unknown"}`);
+    }
+}
+function existingBaseDir(baseDir, fs) {
+    if (!fs.exists(baseDir)) {
+        return undefined;
+    }
+    try {
+        return fs.realPath(baseDir);
+    }
+    catch (error) {
+        throw new EvidenceReadError(`cannot read evidence directory: ${error instanceof Error ? error.message : "unknown"}`);
+    }
+}
+// Returns the realpath-contained absolute path of <runId>.json inside the base dir, or throws if it
+// would escape. The runId is validated first so no separator/`..`/NUL can reach the join.
+function containedManifestPath(runId, realBase, fs) {
+    assertValidRunId(runId);
+    const lexical = resolveWithinWorkspace(realBase, `${runId}${MANIFEST_SUFFIX}`);
+    return assertContainedRealPath(fs, realBase, lexical, `${runId}${MANIFEST_SUFFIX}`);
+}
+function isManifestName(name) {
+    if (!name.endsWith(MANIFEST_SUFFIX)) {
+        return false;
+    }
+    const runId = name.slice(0, name.length - MANIFEST_SUFFIX.length);
+    try {
+        assertValidRunId(runId);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+function isSingleLinkRegularFile(path, fs) {
+    try {
+        const stat = fs.stat(path);
+        return stat.isFile && (stat.hardLinkCount ?? 1) <= 1;
+    }
+    catch (error) {
+        throw new EvidenceReadError(`cannot inspect evidence manifest: ${error instanceof Error ? error.message : "unknown"}`);
+    }
+}
+function listManifestRunIds(realBase, fs) {
+    const runIds = [];
+    try {
+        for (const entry of readdirSync(realBase, { withFileTypes: true })) {
+            // Never follow a symlink: only count entries the ledger itself wrote as regular files.
+            if (entry.isSymbolicLink() ||
+                !entry.isFile() ||
+                !isManifestName(entry.name) ||
+                !isSingleLinkRegularFile(join(realBase, entry.name), fs)) {
+                continue;
+            }
+            runIds.push(entry.name.slice(0, entry.name.length - MANIFEST_SUFFIX.length));
+        }
+    }
+    catch (error) {
+        throw new EvidenceReadError(`cannot list evidence manifests: ${error instanceof Error ? error.message : "unknown"}`);
+    }
+    return runIds.sort();
+}
+function atomicWrite(target, json, randomSuffix) {
+    const temp = `${target}.${randomSuffix()}.tmp`;
+    try {
+        // O_EXCL ("wx"): refuse to open through a pre-planted symlink at the temp path, closing the
+        // temp-vs-final containment asymmetry (the final target is realpath-contained, the temp was
+        // not). A randomUUID suffix never collides, so "wx" never spuriously fails.
+        writeFileSync(temp, json, { encoding: "utf8", flag: "wx" });
+        renameSync(temp, target);
+    }
+    catch (error) {
+        rmSync(temp, { force: true });
+        throw new EvidenceWriteError(`evidence write failed: ${error instanceof Error ? error.message : "unknown"}`);
+    }
+}
+function reportLocation(baseDir, fs, runId) {
+    assertValidRunId(runId);
+    const realBase = existingBaseDir(baseDir, fs);
+    return realBase === undefined
+        ? join(resolve(baseDir), `${runId}${MANIFEST_SUFFIX}`)
+        : containedManifestPath(runId, realBase, fs);
+}
+function putManifest(baseDir, fs, randomSuffix, runId, json) {
+    const realBase = prepareBaseDir(baseDir, fs);
+    const target = containedManifestPath(runId, realBase, fs);
+    atomicWrite(target, json, randomSuffix);
+    return target;
+}
+function listManifests(baseDir, fs) {
+    const realBase = existingBaseDir(baseDir, fs);
+    return realBase === undefined ? [] : listManifestRunIds(realBase, fs);
+}
+function getManifest(baseDir, fs, runId) {
+    assertValidRunId(runId);
+    const realBase = existingBaseDir(baseDir, fs);
+    if (realBase === undefined) {
+        return undefined;
+    }
+    const target = join(realBase, `${runId}${MANIFEST_SUFFIX}`);
+    try {
+        if (lstatSync(target, { throwIfNoEntry: false })?.isFile() !== true) {
+            return undefined;
+        }
+        if (!isSingleLinkRegularFile(target, fs)) {
+            return undefined;
+        }
+        return readFileSync(target, "utf8");
+    }
+    catch (error) {
+        throw new EvidenceReadError(`cannot read evidence manifest: ${error instanceof Error ? error.message : "unknown"}`);
+    }
+}
+function deleteManifest(baseDir, fs, runId) {
+    const realBase = existingBaseDir(baseDir, fs);
+    if (realBase === undefined) {
+        return;
+    }
+    const target = containedManifestPath(runId, realBase, fs);
+    if (lstatSync(target, { throwIfNoEntry: false })?.isFile() !== true) {
+        return;
+    }
+    if (!isSingleLinkRegularFile(target, fs)) {
+        return;
+    }
+    rmSync(target, { force: true });
+}
+export function createNodeEvidenceStore(baseDir, fs = nodeWorkspaceFs, randomSuffix = randomUUID) {
+    return {
+        put: (runId, json) => putManifest(baseDir, fs, randomSuffix, runId, json),
+        list: () => listManifests(baseDir, fs),
+        get: (runId) => getManifest(baseDir, fs, runId),
+        location: (runId) => reportLocation(baseDir, fs, runId),
+        delete: (runId) => {
+            deleteManifest(baseDir, fs, runId);
+        },
+    };
+}

package/dist/audit/types.d.ts

@@ -0,0 +1,188 @@
+import type { CostClass } from "../gateway/types.js";
+import type { HarnessCode, HarnessStateName, RunManifest, RunOutcome, RunResult, TaskType } from "../harness/types.js";
+import type { AuditSummary } from "../workspace/types.js";
+import type { VerificationAuditSummary } from "../verification/summary.js";
+import type { EvidenceStore } from "./store.js";
+export declare const EVIDENCE_SCHEMA_VERSION: "1";
+export interface EvidenceRunIdentity {
+    readonly runId: string;
+    readonly fingerprint: string;
+    readonly harnessVersion: string;
+    readonly taskType: EvidenceTaskType;
+    readonly outcome: RunOutcome;
+    readonly startedAt: number;
+    readonly finishedAt: number;
+    readonly durationMs: number;
+}
+export interface EvidenceModel {
+    readonly modelId: string;
+    readonly costClass: CostClass | "unknown";
+}
+export interface EvidenceUsageTotals {
+    readonly promptTokens: number;
+    readonly completionTokens: number;
+    readonly requestCount: number;
+    readonly totalLatencyMs: number;
+}
+export interface EvidenceStateTransition {
+    readonly seq: number;
+    readonly ts: number;
+    readonly from: HarnessStateName;
+    readonly to: HarnessStateName;
+    readonly reason: string;
+}
+export interface EvidenceToolCall {
+    readonly seq: number;
+    readonly ts: number;
+    readonly toolName: string;
+    readonly toolCallId: string;
+    readonly outcome: "completed" | "failed";
+    readonly durationMs?: number | undefined;
+    readonly errorCode?: string | undefined;
+}
+export interface EvidenceCommandExecution {
+    readonly seq: number;
+    readonly ts: number;
+    readonly executable: string;
+    readonly argCount: number;
+    readonly exitCode: number | null;
+    readonly timedOut: boolean;
+    readonly durationMs: number;
+}
+export interface EvidenceSandboxConfiguration {
+    readonly seq: number;
+    readonly ts: number;
+    readonly envAllowlist: readonly string[];
+    readonly network: "inherit" | "none";
+    readonly maxOutputBytes: number;
+    readonly timeoutMs: number;
+    readonly terminationGraceMs: number;
+    readonly cwdRequested: boolean;
+}
+export interface EvidenceVerificationResult {
+    readonly seq: number;
+    readonly ts: number;
+    readonly passed: boolean;
+    readonly detail: string;
+}
+export interface EvidencePatch {
+    readonly proposed: boolean;
+    readonly applied: boolean;
+    readonly targetFileCount: number;
+    readonly patchBytes: number;
+    readonly changedFiles: number;
+    readonly created: number;
+    readonly deleted: number;
+    readonly redactedDiff?: string | undefined;
+}
+export interface EvidenceReasoningEntry {
+    readonly seq: number;
+    readonly ts: number;
+    readonly phase: HarnessStateName;
+    readonly rationale: string;
+    readonly modelResponse?: string | undefined;
+}
+export interface EvidenceFailure {
+    readonly category: HarnessCode;
+    readonly message: string;
+}
+export type EvidenceTaskType = TaskType | "browser-capture" | "terminal-execution";
+export interface EvidenceBrowserViewportPx {
+    readonly width: number;
+    readonly height: number;
+}
+export type EvidenceBrowserEventType = "browser:session-opened" | "browser:navigated" | "browser:screenshot-captured" | "browser:page-content-captured" | "browser:session-closed" | "browser:trust-warning" | "browser:error";
+export interface EvidenceBrowserEvent {
+    readonly schemaVersion: "1";
+    readonly type: EvidenceBrowserEventType;
+    readonly sessionId: string;
+    readonly seq: number;
+    readonly ts: number;
+    readonly originOnly?: string | undefined;
+    readonly httpStatus?: number | null | undefined;
+    readonly captureSeq?: number | undefined;
+    readonly persisted?: boolean | undefined;
+    readonly viewportPx?: EvidenceBrowserViewportPx | undefined;
+    readonly path?: string | undefined;
+    readonly sha256?: string | undefined;
+    readonly bytes?: number | undefined;
+    readonly byteLength?: number | undefined;
+    readonly reason?: string | undefined;
+    readonly warning?: string | undefined;
+    readonly code?: string | undefined;
+    readonly message?: string | undefined;
+}
+export interface EvidenceBrowserScreenshot {
+    readonly seq: number;
+    readonly path: string;
+    readonly sha256: string;
+    readonly bytes: number;
+    readonly capturedAt: number;
+    readonly viewportPx: EvidenceBrowserViewportPx;
+}
+export interface EvidenceBrowserContentCapture {
+    readonly seq: number;
+    readonly byteLength: number;
+    readonly capturedAt: number;
+    readonly redactedHtml: string;
+}
+export interface EvidenceBrowserCapture {
+    readonly sessionId: string;
+    readonly cdpPort: number;
+    readonly targetId: string;
+    readonly status: "open" | "closed";
+    readonly startedAt: number;
+    readonly closedAt?: number | undefined;
+    readonly closeReason?: string | undefined;
+    readonly lastOriginOnly?: string | undefined;
+    readonly events: readonly EvidenceBrowserEvent[];
+    readonly screenshots?: readonly EvidenceBrowserScreenshot[] | undefined;
+    readonly contentCaptures?: readonly EvidenceBrowserContentCapture[] | undefined;
+}
+export interface EvidenceManifest {
+    readonly evidenceSchemaVersion: "1";
+    readonly run: EvidenceRunIdentity;
+    readonly model: EvidenceModel;
+    readonly usageTotals: EvidenceUsageTotals;
+    readonly context?: AuditSummary | undefined;
+    readonly stateTransitions: readonly EvidenceStateTransition[];
+    readonly toolCalls: readonly EvidenceToolCall[];
+    readonly commandExecutions: readonly EvidenceCommandExecution[];
+    readonly sandboxConfigurations?: readonly EvidenceSandboxConfiguration[] | undefined;
+    readonly verificationResults?: readonly EvidenceVerificationResult[] | undefined;
+    readonly patch?: EvidencePatch | undefined;
+    readonly verification?: VerificationAuditSummary | undefined;
+    readonly failure?: EvidenceFailure | undefined;
+    readonly reasoning?: readonly EvidenceReasoningEntry[] | undefined;
+    readonly browser?: EvidenceBrowserCapture | undefined;
+}
+export interface AuditRedactionConfig {
+    readonly additionalSecrets?: readonly string[] | undefined;
+    readonly redactEnvValues?: readonly string[] | undefined;
+    readonly sensitiveLiterals?: readonly string[] | undefined;
+}
+export interface RetentionPolicy {
+    readonly maxRuns?: number | undefined;
+    readonly maxAgeMs?: number | undefined;
+    readonly maxTotalBytes?: number | undefined;
+    readonly disabled?: boolean | undefined;
+}
+export declare const DEFAULT_RETENTION: RetentionPolicy;
+export interface BuildOptions {
+    readonly includeReasoning?: boolean | undefined;
+    readonly includeDiff?: boolean | undefined;
+}
+export interface EvidenceBuildInput {
+    readonly result: RunResult;
+    readonly manifest: RunManifest;
+    readonly context?: AuditSummary | undefined;
+    readonly verification?: VerificationAuditSummary | undefined;
+    readonly redaction?: AuditRedactionConfig | undefined;
+    readonly options?: BuildOptions | undefined;
+}
+export interface EvidenceDeps {
+    readonly env?: Readonly<Record<string, string | undefined>> | undefined;
+    readonly store?: EvidenceStore | undefined;
+    readonly randomSuffix?: (() => string) | undefined;
+    readonly now?: (() => number) | undefined;
+}