@oscharko-dev/keiko 0.1.0-beta.0

package/dist/audit/aggregate.js

@@ -0,0 +1,25 @@
+// Usage/cost aggregation (ADR-0010 D7). aggregateUsage is a PURE fold over model:call:completed
+// events; resolveCostClass recovers the cost class from the gateway capability registry rather than
+// the event (the harness model:call:completed event omits costClass by design and we do NOT add it —
+// no harness edit). One model per run is assumed (RunManifest.modelId is single-valued); the
+// multi-model caveat is documented in the ADR Consequences, not silently mis-aggregated.
+import { findCapability } from "../gateway/capabilities.js";
+export function aggregateUsage(events) {
+    let promptTokens = 0;
+    let completionTokens = 0;
+    let requestCount = 0;
+    let totalLatencyMs = 0;
+    for (const event of events) {
+        if (event.type !== "model:call:completed") {
+            continue;
+        }
+        promptTokens += event.usage.promptTokens;
+        completionTokens += event.usage.completionTokens;
+        totalLatencyMs += event.usage.latencyMs;
+        requestCount += 1;
+    }
+    return { promptTokens, completionTokens, requestCount, totalLatencyMs };
+}
+export function resolveCostClass(modelId) {
+    return findCapability(modelId)?.costClass ?? "unknown";
+}

package/dist/audit/build.d.ts

@@ -0,0 +1,2 @@
+import type { EvidenceBuildInput, EvidenceDeps, EvidenceManifest } from "./types.js";
+export declare function buildEvidenceManifest(input: EvidenceBuildInput, deps: EvidenceDeps): EvidenceManifest;

package/dist/audit/build.js

@@ -0,0 +1,224 @@
+// The redacted-by-construction manifest builder (ADR-0010 D2/D3/D7/D8). It maps a harness
+// RunResult/RunManifest (+ optional #5/#7 audit summaries) into an EvidenceManifest, applying the
+// audit redactor at the moment each sensitive value is copied in — there is no intermediate "raw
+// manifest" object. The persist layer (D3 defense-in-depth) additionally deep-redacts every string
+// leaf before serialization, so a builder bug that missed a field cannot silently persist a secret.
+import { aggregateUsage, resolveCostClass } from "./aggregate.js";
+import { createAuditRedactor, deepRedactStrings } from "./redaction.js";
+import { EVIDENCE_SCHEMA_VERSION } from "./types.js";
+function buildIdentity(input) {
+    const { result, manifest } = input;
+    return {
+        runId: result.runId,
+        fingerprint: result.fingerprint,
+        harnessVersion: manifest.harnessVersion,
+        taskType: result.taskType,
+        outcome: result.outcome,
+        startedAt: result.startedAt,
+        finishedAt: result.finishedAt,
+        durationMs: result.finishedAt - result.startedAt,
+    };
+}
+function mapStateTransition(e, redact) {
+    return { seq: e.seq, ts: e.ts, from: e.from, to: e.to, reason: redact(e.reason) };
+}
+function mapToolCompleted(e) {
+    return {
+        seq: e.seq,
+        ts: e.ts,
+        toolName: e.toolName,
+        toolCallId: e.toolCallId,
+        outcome: "completed",
+        durationMs: e.durationMs,
+    };
+}
+function mapToolFailed(e) {
+    // The redacted message is dropped (D3); only the stable errorCode is retained.
+    return {
+        seq: e.seq,
+        ts: e.ts,
+        toolName: e.toolName,
+        toolCallId: e.toolCallId,
+        outcome: "failed",
+        errorCode: e.errorCode,
+    };
+}
+function mapCommand(e) {
+    return {
+        seq: e.seq,
+        ts: e.ts,
+        executable: e.executable,
+        argCount: e.argCount,
+        exitCode: e.exitCode,
+        timedOut: e.timedOut,
+        durationMs: e.durationMs,
+    };
+}
+function mapSandbox(e) {
+    return {
+        seq: e.seq,
+        ts: e.ts,
+        envAllowlist: e.envAllowlist,
+        network: e.network,
+        maxOutputBytes: e.maxOutputBytes,
+        timeoutMs: e.timeoutMs,
+        terminationGraceMs: e.terminationGraceMs,
+        cwdRequested: e.cwdRequested,
+    };
+}
+function mapVerificationResult(e, redact) {
+    return { seq: e.seq, ts: e.ts, passed: e.passed, detail: redact(e.detail) };
+}
+function mapReasoning(e, redact) {
+    return {
+        seq: e.seq,
+        ts: e.ts,
+        phase: e.phase,
+        rationale: redact(e.rationale),
+        ...(e.modelResponse === undefined ? {} : { modelResponse: redact(e.modelResponse) }),
+    };
+}
+function newPatchAccumulator() {
+    return {
+        seen: false,
+        proposed: false,
+        applied: false,
+        targetFileCount: 0,
+        patchBytes: 0,
+        changedFiles: 0,
+        created: 0,
+        deleted: 0,
+        redactedDiff: undefined,
+    };
+}
+function foldPatchProposed(acc, e, redact, includeDiff) {
+    acc.seen = true;
+    acc.proposed = true;
+    acc.targetFileCount += 1;
+    acc.patchBytes += e.patchBytes;
+    if (includeDiff) {
+        acc.redactedDiff = redact(e.diff);
+    }
+}
+function foldPatchApplied(acc, e) {
+    acc.seen = true;
+    acc.applied = true;
+    acc.changedFiles += e.changedFiles;
+    acc.created += e.created;
+    acc.deleted += e.deleted;
+}
+function toPatch(acc) {
+    if (!acc.seen) {
+        return undefined;
+    }
+    return {
+        proposed: acc.proposed,
+        applied: acc.applied,
+        targetFileCount: acc.targetFileCount,
+        patchBytes: acc.patchBytes,
+        changedFiles: acc.changedFiles,
+        created: acc.created,
+        deleted: acc.deleted,
+        ...(acc.redactedDiff === undefined ? {} : { redactedDiff: acc.redactedDiff }),
+    };
+}
+function toFailure(result, redact) {
+    if (result.failure === undefined) {
+        return undefined;
+    }
+    return { category: result.failure.category, message: redact(result.failure.message) };
+}
+function foldRecordEvent(state, event, redact) {
+    if (event.type === "state:transition") {
+        state.stateTransitions.push(mapStateTransition(event, redact));
+        return true;
+    }
+    else if (event.type === "tool:call:completed") {
+        state.toolCalls.push(mapToolCompleted(event));
+        return true;
+    }
+    else if (event.type === "tool:call:failed") {
+        state.toolCalls.push(mapToolFailed(event));
+        return true;
+    }
+    else if (event.type === "command:executed") {
+        state.commandExecutions.push(mapCommand(event));
+        return true;
+    }
+    else if (event.type === "sandbox:configured") {
+        state.sandboxConfigurations.push(mapSandbox(event));
+        return true;
+    }
+    else if (event.type === "verification:result") {
+        state.verificationResults.push(mapVerificationResult(event, redact));
+        return true;
+    }
+    return false;
+}
+function foldEvent(state, event, redact, options) {
+    if (foldRecordEvent(state, event, redact)) {
+        return;
+    }
+    if (event.type === "patch:proposed") {
+        foldPatchProposed(state.patch, event, redact, options.includeDiff);
+    }
+    else if (event.type === "patch:applied") {
+        foldPatchApplied(state.patch, event);
+    }
+    else if (event.type === "reasoning:trace" && options.includeReasoning) {
+        state.reasoning.push(mapReasoning(event, redact));
+    }
+}
+// Assembles the optional sections (undefined-when-absent, never an empty object/array masquerading
+// as "ran but produced nothing" — D2). exactOptionalPropertyTypes means each key is only present
+// when its value exists; reasoning is keyed only under its opt-in.
+function optionalSections(input, state, redact, includeReasoning) {
+    const patch = toPatch(state.patch);
+    const failure = toFailure(input.result, redact);
+    return {
+        ...(input.context === undefined ? {} : { context: input.context }),
+        ...(patch === undefined ? {} : { patch }),
+        ...(input.verification === undefined ? {} : { verification: input.verification }),
+        ...(failure === undefined ? {} : { failure }),
+        ...(includeReasoning ? { reasoning: state.reasoning } : {}),
+    };
+}
+export function buildEvidenceManifest(input, deps) {
+    const redact = createAuditRedactor(input.redaction ?? {}, deps.env ?? {});
+    const includeDiff = input.options?.includeDiff ?? false;
+    const includeReasoning = input.options?.includeReasoning ?? false;
+    const state = {
+        stateTransitions: [],
+        toolCalls: [],
+        commandExecutions: [],
+        sandboxConfigurations: [],
+        verificationResults: [],
+        reasoning: [],
+        patch: newPatchAccumulator(),
+    };
+    for (const event of input.result.events) {
+        foldEvent(state, event, redact, { includeDiff, includeReasoning });
+    }
+    const manifest = {
+        evidenceSchemaVersion: EVIDENCE_SCHEMA_VERSION,
+        run: buildIdentity(input),
+        model: { modelId: input.manifest.modelId, costClass: resolveCostClass(input.manifest.modelId) },
+        usageTotals: aggregateUsage(input.result.events),
+        stateTransitions: state.stateTransitions,
+        toolCalls: state.toolCalls,
+        commandExecutions: state.commandExecutions,
+        ...(state.sandboxConfigurations.length === 0
+            ? {}
+            : { sandboxConfigurations: state.sandboxConfigurations }),
+        ...(state.verificationResults.length === 0
+            ? {}
+            : { verificationResults: state.verificationResults }),
+        ...optionalSections(input, state, redact, includeReasoning),
+    };
+    // C2: the #5 context and #7 verification summaries are embedded VERBATIM above, so per-field
+    // redaction during the fold does not reach them. Apply the audit redactor over every string leaf so
+    // a DIRECT builder caller (not only via persistEvidence) gets a truly redacted-by-construction
+    // manifest. Idempotent, so the fold's per-field redaction still stands and persist's DiD pass is a
+    // no-op on already-redacted tokens.
+    return deepRedactStrings(manifest, redact);
+}

package/dist/audit/errors.d.ts

@@ -0,0 +1,25 @@
+export declare const AUDIT_CODES: {
+    readonly INVALID_RUN_ID: "AUDIT_INVALID_RUN_ID";
+    readonly WRITE: "AUDIT_WRITE";
+    readonly SCHEMA: "AUDIT_SCHEMA";
+    readonly READ: "AUDIT_READ";
+};
+export type AuditCode = (typeof AUDIT_CODES)[keyof typeof AUDIT_CODES];
+export declare abstract class AuditError extends Error {
+    abstract readonly code: AuditCode;
+    constructor(message: string, secrets?: readonly string[]);
+}
+export declare class InvalidRunIdError extends AuditError {
+    readonly code: "AUDIT_INVALID_RUN_ID";
+}
+export declare class EvidenceWriteError extends AuditError {
+    readonly code: "AUDIT_WRITE";
+}
+export declare class EvidenceReadError extends AuditError {
+    readonly code: "AUDIT_READ";
+}
+export declare class EvidenceSchemaError extends AuditError {
+    readonly code: "AUDIT_SCHEMA";
+    readonly foundVersion: string;
+    constructor(message: string, foundVersion: string, secrets?: readonly string[]);
+}

package/dist/audit/errors.js

@@ -0,0 +1,39 @@
+// Audit error taxonomy, mirroring gateway/harness/workspace/tools (ADR-0003..0006). Errors carry a
+// stable `code` discriminant; callers switch on `code`, never parse `message`. Every message is
+// redacted at construction (D11: typed errors with redacted messages) so errors are always safe to
+// log or surface.
+import { redact } from "../gateway/redaction.js";
+export const AUDIT_CODES = {
+    INVALID_RUN_ID: "AUDIT_INVALID_RUN_ID",
+    WRITE: "AUDIT_WRITE",
+    SCHEMA: "AUDIT_SCHEMA",
+    READ: "AUDIT_READ",
+};
+export class AuditError extends Error {
+    constructor(message, secrets = []) {
+        super(redact(message, secrets));
+        this.name = new.target.name;
+    }
+}
+// A runId failed the bounded character-class / length validation (D4 iii). Nothing was written.
+export class InvalidRunIdError extends AuditError {
+    code = AUDIT_CODES.INVALID_RUN_ID;
+}
+// A write or delete at the filesystem boundary failed, or a path escaped the contained base dir.
+export class EvidenceWriteError extends AuditError {
+    code = AUDIT_CODES.WRITE;
+}
+// A persisted manifest could not be parsed as JSON (truncated, hand-edited, or corrupt). Surfaced as
+// a typed error so the CLI maps it to a clean exit code instead of leaking a raw SyntaxError (C1).
+export class EvidenceReadError extends AuditError {
+    code = AUDIT_CODES.READ;
+}
+// A persisted manifest carried an unrecognised evidenceSchemaVersion (D5) — not silently coerced.
+export class EvidenceSchemaError extends AuditError {
+    code = AUDIT_CODES.SCHEMA;
+    foundVersion;
+    constructor(message, foundVersion, secrets = []) {
+        super(message, secrets);
+        this.foundVersion = foundVersion;
+    }
+}

package/dist/audit/index-api.d.ts

@@ -0,0 +1,14 @@
+import type { RunOutcome } from "../harness/types.js";
+import type { EvidenceStore } from "./store.js";
+import type { EvidenceManifest, EvidenceTaskType } from "./types.js";
+export interface EvidenceListEntry {
+    readonly runId: string;
+    readonly taskType: EvidenceTaskType;
+    readonly outcome: RunOutcome;
+    readonly startedAt: number;
+    readonly finishedAt: number;
+    readonly modelId: string;
+    readonly workspaceRoot?: string | undefined;
+}
+export declare function listEvidence(store: EvidenceStore): readonly EvidenceListEntry[];
+export declare function loadEvidence(store: EvidenceStore, runId: string): EvidenceManifest | undefined;

package/dist/audit/index-api.js

@@ -0,0 +1,131 @@
+// Evidence index/list API (ADR-0010 D5). listEvidence enumerates and loadEvidence loads past runs
+// reading ONLY the contained base dir via the EvidenceStore — never scanning arbitrary workspace
+// files. Because the persisted JSON is redacted by construction (D3), the loaded data is
+// redacted-by-construction: there is no un-redaction path. A manifest whose evidenceSchemaVersion is
+// not a recognised version is reported with a typed error (D5), not silently coerced. This is the
+// #13 UI seam.
+import { EvidenceReadError, EvidenceSchemaError } from "./errors.js";
+import { EVIDENCE_SCHEMA_VERSION } from "./types.js";
+// Parses raw JSON and verifies the schema version before trusting the shape. We narrow on the
+// version discriminant exactly as harness consumers narrow on the event schemaVersion (D2).
+// JSON.parse can throw a raw SyntaxError on a truncated/hand-edited manifest; the parse is a system
+// boundary (reading developer-writable files), so catching it and re-throwing a typed AuditError is
+// correct — the CLI maps AuditError to an exit code instead of leaking an unhandled stack (C1).
+function parseJson(json, runId) {
+    try {
+        return JSON.parse(json);
+    }
+    catch {
+        throw new EvidenceReadError(`evidence manifest is not valid JSON: ${runId}`);
+    }
+}
+function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function requireRecord(parent, key, runId) {
+    const value = parent[key];
+    if (!isRecord(value)) {
+        throw new EvidenceSchemaError(`evidence manifest is missing object field ${key}: ${runId}`, "1");
+    }
+    return value;
+}
+function requireArray(parent, key, runId) {
+    if (!Array.isArray(parent[key])) {
+        throw new EvidenceSchemaError(`evidence manifest is missing array field ${key}: ${runId}`, "1");
+    }
+}
+function requireString(parent, key, runId) {
+    if (typeof parent[key] !== "string") {
+        throw new EvidenceSchemaError(`evidence manifest is missing string field ${key}: ${runId}`, "1");
+    }
+}
+function requireNumber(parent, key, runId) {
+    if (typeof parent[key] !== "number" || !Number.isFinite(parent[key])) {
+        throw new EvidenceSchemaError(`evidence manifest is missing numeric field ${key}: ${runId}`, "1");
+    }
+}
+function requireOptionalRecord(parent, key, runId) {
+    const value = parent[key];
+    if (value !== undefined && !isRecord(value)) {
+        throw new EvidenceSchemaError(`evidence manifest has invalid object field ${key}: ${runId}`, "1");
+    }
+}
+function requireOptionalArray(parent, key, runId) {
+    const value = parent[key];
+    if (value !== undefined && !Array.isArray(value)) {
+        throw new EvidenceSchemaError(`evidence manifest has invalid array field ${key}: ${runId}`, "1");
+    }
+}
+function validateManifestShape(parsed, runId) {
+    const run = requireRecord(parsed, "run", runId);
+    requireString(run, "runId", runId);
+    requireString(run, "fingerprint", runId);
+    requireString(run, "harnessVersion", runId);
+    requireString(run, "taskType", runId);
+    requireString(run, "outcome", runId);
+    requireNumber(run, "startedAt", runId);
+    requireNumber(run, "finishedAt", runId);
+    requireNumber(run, "durationMs", runId);
+    const model = requireRecord(parsed, "model", runId);
+    requireString(model, "modelId", runId);
+    requireString(model, "costClass", runId);
+    const usage = requireRecord(parsed, "usageTotals", runId);
+    requireNumber(usage, "promptTokens", runId);
+    requireNumber(usage, "completionTokens", runId);
+    requireNumber(usage, "requestCount", runId);
+    requireNumber(usage, "totalLatencyMs", runId);
+    requireArray(parsed, "stateTransitions", runId);
+    requireArray(parsed, "toolCalls", runId);
+    requireArray(parsed, "commandExecutions", runId);
+    requireOptionalArray(parsed, "sandboxConfigurations", runId);
+    requireOptionalArray(parsed, "verificationResults", runId);
+    requireOptionalArray(parsed, "reasoning", runId);
+    requireOptionalRecord(parsed, "context", runId);
+    requireOptionalRecord(parsed, "patch", runId);
+    requireOptionalRecord(parsed, "verification", runId);
+    requireOptionalRecord(parsed, "failure", runId);
+    requireOptionalRecord(parsed, "browser", runId);
+}
+function parseManifest(json, runId) {
+    const parsed = parseJson(json, runId);
+    if (!isRecord(parsed)) {
+        throw new EvidenceSchemaError(`evidence manifest is not an object: ${runId}`, "none");
+    }
+    const version = parsed.evidenceSchemaVersion;
+    if (version !== EVIDENCE_SCHEMA_VERSION) {
+        throw new EvidenceSchemaError(`unrecognised evidence schema version for ${runId}`, typeof version === "string" ? version : "none");
+    }
+    validateManifestShape(parsed, runId);
+    return parsed;
+}
+function toListEntry(manifest) {
+    return {
+        runId: manifest.run.runId,
+        taskType: manifest.run.taskType,
+        outcome: manifest.run.outcome,
+        startedAt: manifest.run.startedAt,
+        finishedAt: manifest.run.finishedAt,
+        modelId: manifest.model.modelId,
+        ...(manifest.context?.workspaceRoot === undefined
+            ? {}
+            : { workspaceRoot: manifest.context.workspaceRoot }),
+    };
+}
+export function listEvidence(store) {
+    const entries = [];
+    for (const runId of store.list()) {
+        const json = store.get(runId);
+        if (json === undefined) {
+            continue;
+        }
+        entries.push(toListEntry(parseManifest(json, runId)));
+    }
+    return entries;
+}
+export function loadEvidence(store, runId) {
+    const json = store.get(runId);
+    if (json === undefined) {
+        return undefined;
+    }
+    return parseManifest(json, runId);
+}

package/dist/audit/index.d.ts

@@ -0,0 +1,12 @@
+export { buildEvidenceManifest } from "./build.js";
+export { persistEvidence, type PersistResult } from "./persist.js";
+export { createAuditRedactor, deepRedactStrings } from "./redaction.js";
+export { aggregateUsage, resolveCostClass } from "./aggregate.js";
+export { listEvidence, loadEvidence, type EvidenceListEntry } from "./index-api.js";
+export { applyRetention } from "./retention.js";
+export { buildEvidenceReport, renderEvidenceReport, type EvidenceReport } from "./report.js";
+export { assertValidRunId } from "./runid.js";
+export { buildWorkflowManifest, foldWorkflowUsage, persistWorkflowEvidence, type EvidencePersistContext, type WorkflowEventLike, type WorkflowRunIdentity, type WorkflowRunKind, type WorkflowTerminalStatus, } from "./workflow-evidence.js";
+export { createInMemoryEvidenceStore, createNodeEvidenceStore, resolveEvidenceDir, type EvidenceStore, } from "./store.js";
+export { AUDIT_CODES, AuditError, EvidenceReadError, EvidenceSchemaError, EvidenceWriteError, InvalidRunIdError, type AuditCode, } from "./errors.js";
+export { EVIDENCE_SCHEMA_VERSION, DEFAULT_RETENTION, type AuditRedactionConfig, type BuildOptions, type EvidenceBuildInput, type EvidenceCommandExecution, type EvidenceDeps, type EvidenceFailure, type EvidenceManifest, type EvidenceModel, type EvidenceBrowserCapture, type EvidenceBrowserContentCapture, type EvidenceBrowserEvent, type EvidenceBrowserEventType, type EvidenceBrowserScreenshot, type EvidenceBrowserViewportPx, type EvidencePatch, type EvidenceReasoningEntry, type EvidenceRunIdentity, type EvidenceStateTransition, type EvidenceTaskType, type EvidenceToolCall, type EvidenceUsageTotals, type EvidenceVerificationResult, type RetentionPolicy, } from "./types.js";

package/dist/audit/index.js

@@ -0,0 +1,17 @@
+// Audit ledger barrel (ADR-0010 D12). Re-exports the public surface of the audit layer: the builder,
+// the persist orchestration, the redactor, the store port + adapters, aggregation, the index/list
+// API, retention, the report, and runId validation, plus the schema/types. None of these names
+// collides with an existing layer export (D9) — in particular the layer does NOT export a bare
+// `summarizeForAudit` or `redact` (it composes them internally).
+export { buildEvidenceManifest } from "./build.js";
+export { persistEvidence } from "./persist.js";
+export { createAuditRedactor, deepRedactStrings } from "./redaction.js";
+export { aggregateUsage, resolveCostClass } from "./aggregate.js";
+export { listEvidence, loadEvidence } from "./index-api.js";
+export { applyRetention } from "./retention.js";
+export { buildEvidenceReport, renderEvidenceReport } from "./report.js";
+export { assertValidRunId } from "./runid.js";
+export { buildWorkflowManifest, foldWorkflowUsage, persistWorkflowEvidence, } from "./workflow-evidence.js";
+export { createInMemoryEvidenceStore, createNodeEvidenceStore, resolveEvidenceDir, } from "./store.js";
+export { AUDIT_CODES, AuditError, EvidenceReadError, EvidenceSchemaError, EvidenceWriteError, InvalidRunIdError, } from "./errors.js";
+export { EVIDENCE_SCHEMA_VERSION, DEFAULT_RETENTION, } from "./types.js";

package/dist/audit/persist.d.ts

@@ -0,0 +1,8 @@
+import { type EvidenceReport } from "./report.js";
+import type { EvidenceBuildInput, EvidenceDeps, EvidenceManifest, RetentionPolicy } from "./types.js";
+export interface PersistResult {
+    readonly manifest: EvidenceManifest;
+    readonly location: string;
+    readonly report: EvidenceReport;
+}
+export declare function persistEvidence(input: EvidenceBuildInput, deps: EvidenceDeps, retention?: RetentionPolicy): PersistResult;

package/dist/audit/persist.js

@@ -0,0 +1,40 @@
+// Top-level orchestration (ADR-0010 D11, D9): build -> deep re-redact (defense in depth) ->
+// store.put -> applyRetention -> buildEvidenceReport. This is the single entry the CLI and the SDK
+// call to write evidence. It is the supported SDK persist entry (the harness is NOT modified — the
+// reuse-unchanged rule is absolute; AC #6 "SDK runs write evidence" is satisfied here and at the CLI
+// layer, not by editing runAgent).
+//
+// Defense-in-depth redaction (coordinator refinement, replacing the ADR's serialized-string pass):
+// the builder is redacted-by-construction (primary), and this layer re-applies the redactor to EVERY
+// STRING LEAF of the assembled manifest object via a generic deep walk BEFORE JSON.stringify. This is
+// idempotent and cannot break JSON structure (a serialized-string re-redaction could miss
+// JSON-escaped secrets and risk corrupting the document). It catches a secret smuggled in through a
+// verbatim-embedded summary (context/verification) that the builder does not itself redact.
+import { isAbsolute, resolve } from "node:path";
+import { buildEvidenceManifest } from "./build.js";
+import { createAuditRedactor, deepRedactStrings } from "./redaction.js";
+import { buildEvidenceReport } from "./report.js";
+import { applyRetention } from "./retention.js";
+import { createNodeEvidenceStore, resolveEvidenceDir } from "./store.js";
+import { DEFAULT_RETENTION } from "./types.js";
+function defaultEvidenceDir(input, env) {
+    const configured = resolveEvidenceDir(undefined, env);
+    return isAbsolute(configured) ? configured : resolve(input.manifest.workingDirectory, configured);
+}
+export function persistEvidence(input, deps, retention = DEFAULT_RETENTION) {
+    const env = deps.env ?? {};
+    // The builder is already redacted-by-construction (incl. the deep-redact of embedded summaries);
+    // re-apply the redactor over every string leaf here as IDEMPOTENT defense in depth, so a builder
+    // bug that missed a field still cannot persist a secret.
+    const manifest = buildEvidenceManifest(input, deps);
+    const redact = createAuditRedactor(input.redaction ?? {}, env);
+    const safeManifest = deepRedactStrings(manifest, redact);
+    const json = JSON.stringify(safeManifest, null, 2);
+    // C5/AC#6: with no explicit store, persist to the predictable local node store (resolved dir incl.
+    // KEIKO_EVIDENCE_DIR), NOT an in-memory store that would silently discard the evidence. Tests
+    // inject createInMemoryEvidenceStore explicitly so they never write to the repository tree.
+    const store = deps.store ?? createNodeEvidenceStore(defaultEvidenceDir(input, deps.env));
+    const location = store.put(safeManifest.run.runId, json);
+    applyRetention(store, retention);
+    return { manifest: safeManifest, location, report: buildEvidenceReport(safeManifest, location) };
+}

package/dist/audit/redaction.d.ts

@@ -0,0 +1,3 @@
+import type { AuditRedactionConfig } from "./types.js";
+export declare function createAuditRedactor(config: AuditRedactionConfig, env: Readonly<Record<string, string | undefined>>): (input: string) => string;
+export declare function deepRedactStrings(value: unknown, redact: (input: string) => string): unknown;

package/dist/audit/redaction.js

@@ -0,0 +1,61 @@
+// The audit redaction surface (ADR-0010 D3). It COMPOSES the gateway redact() (imported, never
+// modified) with three additional literal-secret sources, producing one redactor the builder applies
+// to every sensitive field before the manifest is constructed (redacted-by-construction).
+//
+// ReDoS-safe by construction: env values and configured literals are passed to redact() as
+// `additionalSecrets`, which escapes each literal via escapeRegExp before building a RegExp. No
+// caller-controlled metacharacter reaches the regex engine and NO NEW REGEX is introduced here —
+// the layer reuses the gateway's audited linear patterns and the escaped-literal path only. This
+// keeps the CodeQL js/polynomial-redos required gate green (ADR-0002).
+import { redact } from "../gateway/redaction.js";
+// A literal shorter than this is too generic to scrub safely: redacting a 2-char value would
+// over-redact ordinary prose. redact() itself only skips empty strings, so the floor lives here.
+const MIN_LITERAL_LENGTH = 4;
+// Resolves the VALUES of the named env vars (never the names), keeping only non-empty values long
+// enough to be a plausible secret. The builder passes these as escaped literals to redact().
+function resolveEnvValues(names, env) {
+    const values = [];
+    for (const name of names) {
+        const value = env[name];
+        if (value !== undefined && value.length >= MIN_LITERAL_LENGTH) {
+            values.push(value);
+        }
+    }
+    return values;
+}
+function keepLongEnough(literals) {
+    return literals.filter((literal) => literal.length >= MIN_LITERAL_LENGTH);
+}
+// Returns a function string -> string applying gateway redact() with the union of all literal
+// secrets (additionalSecrets ∪ resolved env values ∪ sensitiveLiterals). Idempotent: redact() over
+// already-redacted text is a no-op on the redacted tokens.
+export function createAuditRedactor(config, env) {
+    const literals = [
+        ...keepLongEnough(config.additionalSecrets ?? []),
+        ...resolveEnvValues(config.redactEnvValues ?? [], env),
+        ...keepLongEnough(config.sensitiveLiterals ?? []),
+    ];
+    return (input) => redact(input, literals);
+}
+// Recursively re-applies a redactor to EVERY STRING LEAF of a plain-JSON value, rebuilding
+// arrays/objects so the input is never mutated and the JSON structure is preserved exactly. Bounded
+// by the (finite) nesting depth of an EvidenceManifest. Idempotent (redact over already-redacted
+// text is a no-op), so it is safe to apply at build time AND again as defense in depth at persist
+// time. This is what makes the builder truly redacted-by-construction even for the #5/#7 summaries it
+// embeds verbatim and the audit redactor (env-values/configured literals) would otherwise miss.
+export function deepRedactStrings(value, redact) {
+    if (typeof value === "string") {
+        return redact(value);
+    }
+    if (Array.isArray(value)) {
+        return value.map((item) => deepRedactStrings(item, redact));
+    }
+    if (typeof value === "object" && value !== null) {
+        const out = {};
+        for (const [key, child] of Object.entries(value)) {
+            out[key] = deepRedactStrings(child, redact);
+        }
+        return out;
+    }
+    return value;
+}

package/dist/audit/report.d.ts

@@ -0,0 +1,18 @@
+import type { CostClass } from "../gateway/types.js";
+import type { RunOutcome } from "../harness/types.js";
+import type { VerificationStatus } from "../verification/types.js";
+import type { EvidenceManifest, EvidenceTaskType, EvidenceUsageTotals } from "./types.js";
+export interface EvidenceReport {
+    readonly evidenceLocation: string;
+    readonly runId: string;
+    readonly fingerprint: string;
+    readonly taskType: EvidenceTaskType;
+    readonly outcome: RunOutcome;
+    readonly changedFiles: number;
+    readonly usageTotals: EvidenceUsageTotals;
+    readonly costClass: CostClass | "unknown";
+    readonly verificationStatus: VerificationStatus | "not-run";
+    readonly knownLimitations: readonly string[];
+}
+export declare function buildEvidenceReport(manifest: EvidenceManifest, location: string): EvidenceReport;
+export declare function renderEvidenceReport(report: EvidenceReport): string;