rea-agents 1.2.0 → 1.3.0

package/dist/application/CrossVersionInvestigation.js

@@ -0,0 +1,295 @@
+import { compareArtifacts } from "../domain/artifactComparison.js";
+import { findChangedBehavior } from "../domain/changedBehavior.js";
+import { createEvidence } from "../domain/evidence.js";
+import { createEvidenceBundle, } from "../domain/evidenceBundle.js";
+import { AnalysisInputError, EvidenceIntegrityError, InvestigationWorkspaceError, } from "../domain/errors.js";
+import { createInvestigationRunIdentity, createInvestigationWorkspace, crossVersionInvestigationInputSchema, investigationRunSchema, investigationRunSummarySchema, reviseInvestigationWorkspace, } from "../domain/investigationWorkspace.js";
+import { jsonValueSchema } from "../domain/jsonValue.js";
+import { err, ok } from "../domain/result.js";
+import { AUTOMATIC_RUN_LIMITATION, createInventoryEvidencePages, runLimitations, scanVersions, targetFor, } from "./CrossVersionInventory.js";
+import { readInvestigationWorkspace, writeInvestigationWorkspace, } from "./InvestigationWorkspaceStore.js";
+import { ARTIFACT_COMPARISON_PROVIDER, CHANGED_BEHAVIOR_PROVIDER, } from "./InvestigationProviders.js";
+/** Run or resume a deterministic cross-version artifact investigation. */
+export const runCrossVersionInvestigation = async (input, policy, execution) => {
+    const parsed = crossVersionInvestigationInputSchema.safeParse(input);
+    if (!parsed.success)
+        return err(new AnalysisInputError("find_changed_behavior", {
+            cause: parsed.error,
+        }));
+    const initial = await readInvestigationWorkspace(parsed.data.workspace_path, policy);
+    if (!initial.ok)
+        return initial;
+    const preflight = validateWorkspaceRequest(initial.value, parsed.data);
+    if (!preflight.ok)
+        return preflight;
+    const snapshots = await scanVersions(parsed.data, execution.inputRoots, execution.signal);
+    if (!snapshots.ok)
+        return snapshots;
+    return continueInvestigation({
+        input: parsed.data,
+        initial: initial.value,
+        snapshots: snapshots.value,
+        policy,
+        session: execution.session,
+    });
+};
+const continueInvestigation = async (context) => {
+    const left = targetFor(context.snapshots.left);
+    const right = targetFor(context.snapshots.right);
+    const identity = createInvestigationRunIdentity({
+        left,
+        right,
+        options: context.input.options,
+    });
+    const existing = context.initial?.runs.find(({ run_id: id }) => id === identity.runId);
+    if (context.initial !== null && existing?.status === "complete")
+        return completeOutcome(context.initial, existing, true, context.session);
+    const pages = createInventoryEvidencePages(context.input, context.snapshots);
+    if (!pages.ok)
+        return pages;
+    const inventoried = await ensureInventoryCheckpoint({
+        input: context.input,
+        current: context.initial,
+        existing,
+        pages: pages.value,
+        snapshots: context.snapshots,
+        policy: context.policy,
+    });
+    if (!inventoried.ok)
+        return inventoried;
+    const compared = await ensureComparisonCheckpoint(context.input, inventoried.value, context.policy);
+    if (!compared.ok)
+        return compared;
+    return finalizeInvestigation(context.input, compared.value, context.policy, context.session);
+};
+const ensureInventoryCheckpoint = async (input) => {
+    if (input.existing !== undefined) {
+        const consistent = validateInventoryCheckpoint(input.existing, input.pages);
+        if (!consistent.ok)
+            return consistent;
+        return input.current === null
+            ? err(new EvidenceIntegrityError("Investigation workspace is missing"))
+            : ok({ workspace: input.current, run: input.existing });
+    }
+    const left = targetFor(input.snapshots.left);
+    const right = targetFor(input.snapshots.right);
+    const identity = createInvestigationRunIdentity({
+        left,
+        right,
+        options: input.input.options,
+    });
+    const run = investigationRunSchema.parse({
+        schema_version: 1,
+        run_id: identity.runId,
+        request_sha256: identity.requestSha256,
+        left,
+        right,
+        options: input.input.options,
+        status: "running",
+        completed_stages: ["inventory_left", "inventory_right"],
+        left_inventory_evidence_ids: evidenceIds(input.pages.left),
+        right_inventory_evidence_ids: evidenceIds(input.pages.right),
+        comparison_evidence_id: null,
+        result_evidence_id: null,
+        limitations: runLimitations(input.snapshots),
+    });
+    const saved = await checkpoint({
+        path: input.input.workspace_path,
+        name: input.input.workspace_name,
+        current: input.current,
+        records: [...input.pages.left, ...input.pages.right],
+        run,
+        policy: input.policy,
+    });
+    return saved.ok ? ok({ workspace: saved.value, run }) : saved;
+};
+const ensureComparisonCheckpoint = async (input, state, policy) => {
+    if (state.run.comparison_evidence_id !== null)
+        return ok(state);
+    const inventory = inventoryEvidence(state.workspace, state.run);
+    if (!inventory.ok)
+        return inventory;
+    const evidence = createArtifactComparisonEvidence(inventory.value, input.options.change_limit);
+    const run = investigationRunSchema.parse({
+        ...state.run,
+        completed_stages: [
+            "inventory_left",
+            "inventory_right",
+            "compare_artifacts",
+        ],
+        comparison_evidence_id: evidence.evidence_id,
+    });
+    const saved = await checkpoint({
+        path: input.workspace_path,
+        name: input.workspace_name,
+        current: state.workspace,
+        records: [evidence],
+        run,
+        policy,
+    });
+    return saved.ok ? ok({ workspace: saved.value, run }) : saved;
+};
+const createArtifactComparisonEvidence = (inventory, limit) => {
+    const comparison = compareArtifacts(inventory.left, inventory.right, 0, limit);
+    const leftIds = evidenceIds(inventory.left);
+    const rightIds = evidenceIds(inventory.right);
+    return createEvidence(undefined, ARTIFACT_COMPARISON_PROVIDER, {
+        predicateType: "rea.artifact-comparison/v1",
+        operation: "compare_artifacts",
+        parameters: {
+            left_evidence_ids: leftIds,
+            right_evidence_ids: rightIds,
+            offset: 0,
+            limit,
+        },
+        result: jsonValueSchema.parse(comparison),
+        confidence: "derived",
+        authority: "analyst-inference",
+        limitations: comparison.limitations,
+        evidenceLinks: [...leftIds, ...rightIds],
+    });
+};
+const finalizeInvestigation = async (input, state, policy, session) => {
+    const comparison = comparisonEvidenceFor(state.workspace, state.run);
+    if (!comparison.ok)
+        return comparison;
+    const evidence = createChangedBehaviorEvidence(state, comparison.value);
+    const run = investigationRunSchema.parse({
+        ...state.run,
+        status: "complete",
+        completed_stages: [
+            "inventory_left",
+            "inventory_right",
+            "compare_artifacts",
+            "find_changed_behavior",
+        ],
+        result_evidence_id: evidence.evidence_id,
+    });
+    const saved = await checkpoint({
+        path: input.workspace_path,
+        name: input.workspace_name,
+        current: state.workspace,
+        records: [evidence],
+        run,
+        policy,
+    });
+    return saved.ok ? completeOutcome(saved.value, run, false, session) : saved;
+};
+const createChangedBehaviorEvidence = (state, comparison) => {
+    const limit = Math.min(state.run.options.change_limit, 100);
+    const changed = findChangedBehavior([comparison], 0, limit);
+    const summary = investigationRunSummarySchema.parse({
+        schema_version: 1,
+        workspace_id: state.workspace.workspace_id,
+        run_id: state.run.run_id,
+        left_manifest_id: state.run.left.manifest_id,
+        right_manifest_id: state.run.right.manifest_id,
+        inventory_evidence_count: state.run.left_inventory_evidence_ids.length +
+            state.run.right_inventory_evidence_ids.length,
+        comparison_evidence_id: comparison.evidence_id,
+        limitations: state.run.limitations,
+    });
+    return createEvidence(undefined, CHANGED_BEHAVIOR_PROVIDER, {
+        predicateType: "rea.changed-behavior/v1",
+        operation: "find_changed_behavior",
+        parameters: {
+            workspace_id: state.workspace.workspace_id,
+            run_id: state.run.run_id,
+            comparison_evidence_ids: [comparison.evidence_id],
+            offset: 0,
+            limit,
+        },
+        result: jsonValueSchema.parse({
+            ...changed,
+            investigation_run: summary,
+        }),
+        confidence: "derived",
+        authority: "analyst-inference",
+        limitations: [...changed.limitations, AUTOMATIC_RUN_LIMITATION],
+        evidenceLinks: changed.evidence_links,
+    });
+};
+const comparisonEvidenceFor = (workspace, run) => {
+    const evidence = workspace.bundle.records.find(({ evidence_id: id }) => id === run.comparison_evidence_id);
+    return evidence === undefined
+        ? err(new EvidenceIntegrityError("Investigation comparison checkpoint is missing Evidence"))
+        : ok(evidence);
+};
+const checkpoint = async (input) => {
+    const records = mergeEvidence(input.current?.bundle.records ?? [], input.records);
+    const bundle = createEvidenceBundle(records, input.current?.bundle.unknowns ?? []);
+    const runs = replaceRun(input.current?.runs ?? [], input.run);
+    const next = input.current === null
+        ? createInvestigationWorkspace(input.name, bundle, runs)
+        : reviseInvestigationWorkspace(input.current, bundle, runs);
+    const written = await writeInvestigationWorkspace(next, input.path, input.current?.revision ?? null, input.policy);
+    return written.ok ? ok(next) : written;
+};
+const completeOutcome = (workspace, run, reused, session) => {
+    if (run.result_evidence_id === null)
+        return err(new EvidenceIntegrityError("Completed investigation has no result"));
+    const evidence = workspace.bundle.records.find(({ evidence_id: id }) => id === run.result_evidence_id);
+    if (evidence === undefined)
+        return err(new EvidenceIntegrityError("Completed investigation result Evidence is missing"));
+    if (session !== undefined) {
+        const records = recordsForRun(workspace, run);
+        const imported = session.importEvidenceBundle(createEvidenceBundle(records));
+        if (!imported.ok)
+            return imported;
+    }
+    return ok({ evidence, workspace, reused });
+};
+const validateWorkspaceRequest = (workspace, input) => {
+    if (workspace !== null && workspace.name !== input.workspace_name)
+        return err(new InvestigationWorkspaceError("update", "name-conflict"));
+    if (input.expected_workspace_revision !== undefined &&
+        workspace?.revision !== input.expected_workspace_revision)
+        return err(new InvestigationWorkspaceError("update", "revision-conflict"));
+    return ok(null);
+};
+const validateInventoryCheckpoint = (run, pages) => JSON.stringify(run.left_inventory_evidence_ids) ===
+    JSON.stringify(evidenceIds(pages.left)) &&
+    JSON.stringify(run.right_inventory_evidence_ids) ===
+        JSON.stringify(evidenceIds(pages.right))
+    ? ok(null)
+    : err(new EvidenceIntegrityError("Investigation inventory checkpoint disagrees with current content"));
+const inventoryEvidence = (workspace, run) => {
+    if (workspace === null)
+        return err(new EvidenceIntegrityError("Investigation workspace is missing"));
+    const byId = new Map(workspace.bundle.records.map((record) => [record.evidence_id, record]));
+    const left = run.left_inventory_evidence_ids.flatMap((id) => {
+        const evidence = byId.get(id);
+        return evidence === undefined ? [] : [evidence];
+    });
+    const right = run.right_inventory_evidence_ids.flatMap((id) => {
+        const evidence = byId.get(id);
+        return evidence === undefined ? [] : [evidence];
+    });
+    return left.length === run.left_inventory_evidence_ids.length &&
+        right.length === run.right_inventory_evidence_ids.length
+        ? ok({ left, right })
+        : err(new EvidenceIntegrityError("Investigation inventory checkpoint is incomplete"));
+};
+const recordsForRun = (workspace, run) => {
+    const ids = new Set([
+        ...run.left_inventory_evidence_ids,
+        ...run.right_inventory_evidence_ids,
+        ...(run.comparison_evidence_id === null
+            ? []
+            : [run.comparison_evidence_id]),
+        ...(run.result_evidence_id === null ? [] : [run.result_evidence_id]),
+    ]);
+    return workspace.bundle.records.filter(({ evidence_id: id }) => ids.has(id));
+};
+const mergeEvidence = (current, additions) => {
+    const records = new Map(current.map((record) => [record.evidence_id, record]));
+    for (const record of additions)
+        if (!records.has(record.evidence_id))
+            records.set(record.evidence_id, record);
+    return [...records.values()];
+};
+const replaceRun = (runs, replacement) => [
+    ...runs.filter(({ run_id: id }) => id !== replacement.run_id),
+    replacement,
+];
+const evidenceIds = (records) => records.map(({ evidence_id: id }) => id);

package/dist/application/DirectAnalysis.js

@@ -3,6 +3,12 @@ import { EnhancedTools } from "./EnhancedTools.js";
 import { createBinarySession } from "./runtime.js";
 import { silentLogger } from "../logger.js";
 import { createEvidence } from "../domain/evidence.js";
+import { EvidenceIntegrityError, projectAnalysisError, } from "../domain/errors.js";
+import { access } from "node:fs/promises";
+import { readAnalysisSnapshot, writeAnalysisSnapshot, } from "./AnalysisSnapshotFiles.js";
+import { parseBinaryTarget } from "../domain/binaryTarget.js";
+import { snapshotEvidenceForQuery, snapshotMatchesTarget, } from "../domain/analysisSnapshot.js";
+import { err, ok } from "../domain/result.js";
 const WORKFLOW_PROVIDER = {
     id: "rea-workflow",
     name: "REA composed investigation workflow",
@@ -13,14 +19,17 @@ const WORKFLOW_PROVIDER = {
  * Unlike MCP mode, every CLI invocation is intentionally isolated and does not
  * retain a target or bridge resources for a subsequent command.
  */
-export const runDirectAnalysis = async (path, tool, arguments_, logger = silentLogger) => runAnalysis(path, tool, arguments_, logger);
+export const runDirectAnalysis = async (path, tool, arguments_, options = {}) => runAnalysis(path, tool, arguments_, {
+    logger: options.logger ?? silentLogger,
+    snapshotPath: options.snapshotPath,
+});
 /** Execute one provider-native semantic operation with atomic provenance. */
-export const runProviderAnalysis = async (path, tool, arguments_, logger = silentLogger) => runAnalysis(path, tool, arguments_, logger);
+export const runProviderAnalysis = async (path, tool, arguments_, logger = silentLogger) => runAnalysis(path, tool, arguments_, { logger, snapshotPath: undefined });
 /** Describe configured providers without opening a target or launching Hopper. */
 export const runSessionStatus = async (logger = silentLogger) => {
     const config = parseConfig(process.env);
     if (!config.ok)
-        return { error: config.error._tag, message: config.error.message };
+        return cliError(config.error);
     const session = createBinarySession(config.value, logger);
     try {
         return session.status();
@@ -29,21 +38,42 @@ export const runSessionStatus = async (logger = silentLogger) => {
         await session.close();
     }
 };
-const runAnalysis = async (path, tool, arguments_, logger) => {
+const runAnalysis = async (path, tool, arguments_, options) => {
+    const { logger, snapshotPath } = options;
     const config = parseConfig(process.env);
     if (!config.ok)
-        return { error: config.error._tag, message: config.error.message };
+        return cliError(config.error);
+    const unavailable = snapshotUnavailable(snapshotPath, config.value.hopperLoaderArgs);
+    if (unavailable !== undefined)
+        return cliError(unavailable);
     const session = createBinarySession(config.value, logger);
     try {
-        const opened = await session.open(path);
+        const prepared = await prepareSnapshot({
+            path,
+            tool,
+            arguments: arguments_,
+            snapshotPath,
+            policy: config.value.analysisSnapshotFilePolicy,
+            provider: replayProviderFor(session, tool),
+        });
+        if (!prepared.ok)
+            return cliError(prepared.error);
+        if (prepared.value.evidence !== undefined)
+            return prepared.value.evidence;
+        const { snapshot } = prepared.value;
+        const opened = await session.open(path, snapshot === undefined ? {} : { snapshot });
         if (!opened.ok)
-            return { error: opened.error._tag, message: opened.error.message };
+            return cliError(opened.error);
+        let output;
+        let evidence;
         if (tool === "binary_overview" ||
             tool === "analyze_function" ||
             tool === "trace_feature") {
             const result = await new EnhancedTools(session).execute(tool, arguments_);
-            return result.ok
-                ? createEvidence(opened.value, tool === "analyze_function"
+            if (!result.ok)
+                output = cliError(result.error);
+            else {
+                evidence = createEvidence(opened.value, tool === "analyze_function"
                     ? session.providerIdentity(tool)
                     : WORKFLOW_PROVIDER, {
                     operation: tool,
@@ -51,22 +81,85 @@ const runAnalysis = async (path, tool, arguments_, logger) => {
                     result: result.value,
                     confidence: "derived",
                     limitations: ["Derived by an REA composed workflow."],
-                })
-                : { error: result.error._tag, message: result.error.message };
+                });
+                output = evidence;
+            }
         }
-        const result = await session.execute(tool, arguments_);
-        return result.ok
-            ? createEvidence(result.value.subject ?? opened.value, result.value.provider, {
-                operation: tool,
-                parameters: arguments_,
-                result: result.value.result,
-                rawResult: result.value.rawResult,
-                limitations: result.value.limitations,
-                locations: result.value.locations,
-            })
-            : { error: result.error._tag, message: result.error.message };
+        else {
+            const result = await session.execute(tool, arguments_);
+            if (!result.ok)
+                output = cliError(result.error);
+            else {
+                evidence = createEvidence(result.value.subject ?? opened.value, result.value.provider, {
+                    operation: tool,
+                    parameters: arguments_,
+                    result: result.value.result,
+                    rawResult: result.value.rawResult,
+                    limitations: result.value.limitations,
+                    locations: result.value.locations,
+                });
+                output = evidence;
+            }
+        }
+        if (evidence !== undefined)
+            session.recordEvidence(evidence);
+        if (snapshotPath !== undefined && evidence !== undefined) {
+            const snapshot = session.exportAnalysisSnapshot();
+            if (!snapshot.ok)
+                return cliError(snapshot.error);
+            const written = await writeAnalysisSnapshot(snapshot.value, snapshotPath, true, config.value.analysisSnapshotFilePolicy);
+            if (!written.ok)
+                return cliError(written.error);
+        }
+        return output;
     }
     finally {
         await session.close();
     }
 };
+const prepareSnapshot = async (options) => {
+    const { path, tool, arguments: arguments_, snapshotPath, policy, provider, } = options;
+    if (snapshotPath === undefined || !(await fileExists(snapshotPath)))
+        return ok({});
+    const loaded = await readAnalysisSnapshot(snapshotPath, policy);
+    if (!loaded.ok)
+        return loaded;
+    const target = await parseBinaryTarget(path);
+    if (!target.ok)
+        return target;
+    if (!snapshotMatchesTarget(loaded.value.target, target.value))
+        return err(new EvidenceIntegrityError("Analysis snapshot target does not match the requested binary"));
+    const evidence = snapshotEvidenceForQuery(loaded.value, {
+        target: target.value,
+        operation: tool,
+        parameters: arguments_,
+        provider,
+    });
+    return ok(evidence === undefined
+        ? { snapshot: loaded.value }
+        : { snapshot: loaded.value, evidence });
+};
+const snapshotUnavailable = (snapshotPath, loaderArgs) => snapshotPath !== undefined && loaderArgs.length > 0
+    ? new EvidenceIntegrityError("Analysis snapshots are unavailable with custom Hopper loader arguments")
+    : undefined;
+const replayProviderFor = (session, tool) => tool === "binary_overview" || tool === "trace_feature"
+    ? WORKFLOW_PROVIDER
+    : session.providerIdentity(tool);
+const fileExists = async (path) => {
+    try {
+        await access(path);
+        return true;
+    }
+    catch (cause) {
+        if (typeof cause === "object" &&
+            cause !== null &&
+            "code" in cause &&
+            cause.code === "ENOENT")
+            return false;
+        throw cause;
+    }
+};
+const cliError = (error) => ({
+    error: "Analysis failed",
+    ...projectAnalysisError(error),
+});

package/dist/application/Doctor.js

@@ -8,7 +8,7 @@ import { promisify } from "node:util";
 import { parseBinaryTarget } from "../domain/binaryTarget.js";
 import { supportsNodeVersion } from "../domain/runtimeVersion.js";
 import { probeHomebrew } from "./homebrew.js";
-import { linuxHopperLauncherPath, linuxSharedLibrariesAvailable, readLinuxDistribution, } from "./LinuxHopper.js";
+import { linuxHopperBinarySupported, linuxHopperLauncherPath, linuxSharedLibrariesAvailable, readLinuxDistribution, } from "./LinuxHopper.js";
 const execFileAsync = promisify(execFile);
 const DEFAULT_HOPPER = "/Applications/Hopper Disassembler.app/Contents/MacOS/hopper";
 const SYSTEM_LINUX_HOPPER = "/opt/hopper/bin/Hopper";
@@ -53,6 +53,16 @@ export const runDoctor = async (target, host = systemDoctorHost()) => {
         remediation: "Run rea setup to install Hopper, or set HOPPER_LAUNCHER_PATH.",
         classification: "missing_analysis_engine",
     }));
+    if (host.platform === "linux" && hopperPath !== undefined)
+        checks.push(check("hopper-version", await host.supportedLinuxHopper(hopperPath), hopperPath, {
+            remediation: unsupportedHopperRemediation(host.configuredHopperPath === hopperPath),
+            classification: "config_drift",
+        }));
+    if (host.platform === "linux" && hopperPath !== undefined)
+        checks.push(check("hopper-demo-runtime", await host.linuxDemoRuntimeReady(), undefined, {
+            remediation: "Rerun rea setup to install the Xvfb, xauth, Python, X11, and XTEST packages required for Linux demo sessions.",
+            classification: "missing_dependency",
+        }));
     if (target !== undefined)
         checks.push(check("target", await host.validTarget(target), target, {
             remediation: "Supply a readable local app or program path.",
@@ -64,6 +74,9 @@ export const runDoctor = async (target, host = systemDoctorHost()) => {
         checks,
     };
 };
+const unsupportedHopperRemediation = (configured) => configured
+    ? "Unset or update HOPPER_LAUNCHER_PATH, install the Hopper build supported by this REA release, or update REA."
+    : "Install the Hopper build supported by this REA release, or update REA for a newer Hopper build.";
 /** Create diagnostics backed by the current process and host commands. */
 export const systemDoctorHost = () => ({
     platform: process.platform,
@@ -97,6 +110,22 @@ export const systemDoctorHost = () => ({
             return false;
         }
     },
+    async linuxDemoRuntimeReady() {
+        try {
+            await access("/usr/bin/Xvfb", constants.X_OK);
+            await access("/usr/bin/xauth", constants.X_OK);
+            await access("/usr/bin/python3", constants.X_OK);
+            await execFileAsync("/usr/bin/python3", [
+                "-c",
+                "import ctypes; ctypes.CDLL('libX11.so.6'); ctypes.CDLL('libXtst.so.6')",
+            ]);
+            return true;
+        }
+        catch {
+            return false;
+        }
+    },
+    supportedLinuxHopper: linuxHopperBinarySupported,
     async brewHopperPath() {
         return probeHomebrew(async (command) => {
             try {

package/dist/application/EvidenceBundleFiles.js

@@ -1,54 +1,29 @@
-import { lstat, readFile, realpath } from "node:fs/promises";
-import { basename, dirname, isAbsolute, relative, resolve } from "node:path";
-import writeFileAtomic from "write-file-atomic";
 import { parseEvidenceBundle, serializeEvidenceBundle, } from "../domain/evidenceBundle.js";
 import { EvidenceFileError, EvidenceIntegrityError } from "../domain/errors.js";
 import { err, ok } from "../domain/result.js";
 import { LEGACY_PROCESS_CAPTURE_MESSAGE, parseProcessCapture, } from "../domain/processCapture.js";
+import { readBoundedJson, writeBoundedText } from "./BoundedJsonFiles.js";
 /** Read and validate a bounded evidence bundle inside an approved root. */
 export const readEvidenceBundle = async (path, policy) => {
     if (policy.roots.length === 0)
         return err(new EvidenceFileError("read", "disabled"));
+    const loaded = await readBoundedJson(path, policy);
+    if (!loaded.ok)
+        return loaded;
     try {
-        const canonicalPath = await realpath(resolve(path));
-        if (!(await isApproved(canonicalPath, policy.roots)))
-            return err(new EvidenceFileError("read", "outside-root"));
-        const stats = await lstat(canonicalPath);
-        if (!stats.isFile())
-            return err(new EvidenceFileError("read", "not-file"));
-        if (stats.size > policy.maxBytes)
-            return err(new EvidenceFileError("read", "too-large"));
-        const encoded = await readFile(canonicalPath);
-        if (encoded.byteLength > policy.maxBytes)
-            return err(new EvidenceFileError("read", "too-large"));
-        let decoded;
-        try {
-            decoded = JSON.parse(encoded.toString("utf8"));
-        }
-        catch (cause) {
-            return err(new EvidenceFileError("read", "invalid-json", { cause }));
-        }
-        const limits = validateJsonLimits(decoded, policy);
-        if (!limits.ok)
-            return limits;
-        try {
-            const bundle = parseEvidenceBundle(decoded);
-            for (const record of bundle.records) {
-                if (record.predicate_type === "rea.process-capture/v3")
-                    throw new TypeError(LEGACY_PROCESS_CAPTURE_MESSAGE);
-                if (record.predicate_type === "rea.process-capture/v4")
-                    parseProcessCapture(record.normalized_result);
-            }
-            return ok(bundle);
-        }
-        catch (cause) {
-            return err(new EvidenceIntegrityError("Evidence bundle validation failed", {
-                cause,
-            }));
+        const bundle = parseEvidenceBundle(loaded.value);
+        for (const record of bundle.records) {
+            if (record.predicate_type === "rea.process-capture/v3")
+                throw new TypeError(LEGACY_PROCESS_CAPTURE_MESSAGE);
+            if (record.predicate_type === "rea.process-capture/v4")
+                parseProcessCapture(record.normalized_result);
         }
+        return ok(bundle);
     }
     catch (cause) {
-        return err(new EvidenceFileError("read", "io", { cause }));
+        return err(new EvidenceIntegrityError("Evidence bundle validation failed", {
+            cause,
+        }));
     }
 };
 /** Atomically write deterministic evidence JSON inside an approved root. */
@@ -64,73 +39,5 @@ export const writeEvidenceBundle = async (bundle, path, overwrite, policy) => {
             cause,
         }));
     }
-    const bytes = Buffer.byteLength(encoded, "utf8");
-    if (bytes > policy.maxBytes)
-        return err(new EvidenceFileError("write", "too-large"));
-    try {
-        const requestedPath = resolve(path);
-        const canonicalParent = await realpath(dirname(requestedPath));
-        const destination = resolve(canonicalParent, basename(requestedPath));
-        if (!(await isApproved(destination, policy.roots)))
-            return err(new EvidenceFileError("write", "outside-root"));
-        const existing = await lstat(destination).catch((cause) => {
-            if (isFileNotFound(cause))
-                return undefined;
-            throw cause;
-        });
-        if (existing !== undefined) {
-            if (!overwrite)
-                return err(new EvidenceFileError("write", "exists"));
-            if (!existing.isFile() || existing.isSymbolicLink())
-                return err(new EvidenceFileError("write", "not-file"));
-        }
-        await writeFileAtomic(destination, encoded, {
-            encoding: "utf8",
-            mode: 0o600,
-            fsync: true,
-        });
-        return ok({ path: requestedPath, bytes });
-    }
-    catch (cause) {
-        return err(new EvidenceFileError("write", "io", { cause }));
-    }
-};
-const isApproved = async (candidate, roots) => {
-    for (const configuredRoot of roots) {
-        const root = await realpath(resolve(configuredRoot));
-        const relation = relative(root, candidate);
-        if (relation === "" ||
-            (!relation.startsWith("..") && !isAbsolute(relation)))
-            return true;
-    }
-    return false;
-};
-const validateJsonLimits = (root, policy) => {
-    const pending = [
-        { value: root, depth: 0 },
-    ];
-    let nodes = 0;
-    while (pending.length > 0) {
-        const current = pending.pop();
-        if (current === undefined)
-            break;
-        nodes += 1;
-        if (nodes > policy.maxNodes || current.depth > policy.maxDepth)
-            return err(new EvidenceFileError("read", "too-large"));
-        if (typeof current.value === "string" &&
-            current.value.length > policy.maxStringLength)
-            return err(new EvidenceFileError("read", "too-large"));
-        if (typeof current.value !== "object" || current.value === null)
-            continue;
-        for (const [key, value] of Object.entries(current.value)) {
-            if (key.length > policy.maxStringLength)
-                return err(new EvidenceFileError("read", "too-large"));
-            pending.push({ value, depth: current.depth + 1 });
-        }
-    }
-    return ok(null);
+    return writeBoundedText(encoded, path, overwrite, policy);
 };
-const isFileNotFound = (cause) => typeof cause === "object" &&
-    cause !== null &&
-    "code" in cause &&
-    cause.code === "ENOENT";