rea-agents 1.4.0 → 1.6.0

package/dist/application/ClientConfigPath.js

@@ -0,0 +1,33 @@
+import { lstat, realpath } from "node:fs/promises";
+const systemFileSystem = { lstat, realpath };
+/**
+ * Resolve an existing, user-owned config symlink to one stable transaction
+ * path. Missing regular paths remain eligible for first-run creation.
+ */
+export const resolveClientConfigTransactionPath = async (requestedPath, fileSystem = systemFileSystem) => {
+    let requestedStats;
+    try {
+        requestedStats = await fileSystem.lstat(requestedPath);
+    }
+    catch (cause) {
+        return isMissing(cause) ? requestedPath : undefined;
+    }
+    if (!requestedStats.isSymbolicLink())
+        return requestedPath;
+    const currentUid = typeof process.getuid === "function" ? process.getuid() : undefined;
+    if (currentUid === undefined ||
+        requestedStats.uid !== currentUid ||
+        fileSystem.realpath === undefined)
+        return undefined;
+    try {
+        const canonicalPath = await fileSystem.realpath(requestedPath);
+        const targetStats = await fileSystem.lstat(canonicalPath);
+        return targetStats.isFile?.() === true && targetStats.uid === currentUid
+            ? canonicalPath
+            : undefined;
+    }
+    catch {
+        return undefined;
+    }
+};
+const isMissing = (cause) => cause instanceof Error && "code" in cause && cause.code === "ENOENT";

package/dist/application/ConfiguredRoots.js

@@ -0,0 +1,19 @@
+import { realpath } from "node:fs/promises";
+/** Canonicalize configured policy roots while ignoring stale missing entries. */
+export const canonicalizeConfiguredRoots = async (roots) => {
+    const canonical = [];
+    for (const root of roots) {
+        try {
+            canonical.push(await realpath(root));
+        }
+        catch (cause) {
+            if (!isMissingPath(cause))
+                throw cause;
+        }
+    }
+    return canonical;
+};
+const isMissingPath = (cause) => typeof cause === "object" &&
+    cause !== null &&
+    "code" in cause &&
+    cause.code === "ENOENT";

package/dist/application/CrossVersionInventory.js

@@ -7,6 +7,14 @@ import { paginateArtifactInventory, } from "./ArtifactInventory.js";
 import { scanAuthorizedArtifactInventory } from "./AuthorizedArtifactInventory.js";
 import { ARTIFACT_GRAPH_PROVIDER } from "./InvestigationProviders.js";
 export const AUTOMATIC_RUN_LIMITATION = "Automatic cross-version runs compare shipped artifact structure only; they do not execute either version.";
+/** Start both independent version scans while preserving left/right identity. */
+export const scanVersionInventories = async (options, scanner = scanAuthorizedArtifactInventory) => {
+    const [left, right] = await Promise.all([
+        scanner(options.leftPath, options.inputRoots, options.limits, options.signal, options.integrity),
+        scanner(options.rightPath, options.inputRoots, options.limits, options.signal, options.integrity),
+    ]);
+    return { left, right };
+};
 /** Authorize and scan both inputs once under the same bounded traversal policy. */
 export const scanVersions = async (input, inputRoots, signal, integrityContinueEnabled = false) => {
     try {
@@ -19,9 +27,14 @@ export const scanVersions = async (input, inputRoots, signal, integrityContinueE
             enabled: integrityContinueEnabled,
             maxMismatches: input.max_integrity_mismatches,
         };
-        const left = await scanAuthorizedArtifactInventory(input.left_path, inputRoots, limits, signal, integrity);
-        const right = await scanAuthorizedArtifactInventory(input.right_path, inputRoots, limits, signal, integrity);
-        return ok({ left, right });
+        return ok(await scanVersionInventories({
+            leftPath: input.left_path,
+            rightPath: input.right_path,
+            inputRoots,
+            limits,
+            ...(signal === undefined ? {} : { signal }),
+            integrity,
+        }));
     }
     catch (cause) {
         if (cause instanceof ArtifactReaderFailure)

package/dist/application/CrossVersionInvestigation.js

@@ -1,14 +1,12 @@
-import { compareArtifacts } from "../domain/artifactComparison.js";
-import { findChangedBehavior } from "../domain/changedBehavior.js";
-import { createEvidence } from "../domain/evidence.js";
+import {} from "../domain/evidence.js";
 import { createEvidenceBundle, } from "../domain/evidenceBundle.js";
 import { AnalysisCancelledError, AnalysisInputError, EvidenceIntegrityError, InvestigationWorkspaceError, } from "../domain/errors.js";
-import { createLegacyInvestigationRunIdentity, createInvestigationRunIdentity, createInvestigationWorkspace, crossVersionInvestigationInputSchema, investigationRunSchema, investigationRunSummarySchema, reviseInvestigationWorkspace, } from "../domain/investigationWorkspace.js";
-import { jsonValueSchema } from "../domain/jsonValue.js";
+import { createLegacyInvestigationRunIdentity, createInvestigationRunIdentity, createInvestigationWorkspace, crossVersionInvestigationInputSchema, investigationRunSchema, reviseInvestigationWorkspace, } from "../domain/investigationWorkspace.js";
 import { err, ok } from "../domain/result.js";
-import { AUTOMATIC_RUN_LIMITATION, createInventoryEvidencePages, runLimitations, scanVersions, targetFor, } from "./CrossVersionInventory.js";
+import { createInventoryEvidencePages, runLimitations, scanVersions, targetFor, } from "./CrossVersionInventory.js";
 import { readInvestigationWorkspace, writeInvestigationWorkspace, } from "./InvestigationWorkspaceStore.js";
-import { ARTIFACT_COMPARISON_PROVIDER, CHANGED_BEHAVIOR_PROVIDER, } from "./InvestigationProviders.js";
+import { createArtifactComparisonEvidence, createChangedBehaviorEvidence, } from "./CrossVersionInvestigationEvidence.js";
+import { selectCompletedInvestigationReplay } from "./CrossVersionInvestigationReplay.js";
 /** Run or resume a deterministic cross-version artifact investigation. */
 export const runCrossVersionInvestigation = async (input, policy, execution) => {
     const parsed = crossVersionInvestigationInputSchema.safeParse(input);
@@ -24,6 +22,17 @@ export const runCrossVersionInvestigation = async (input, policy, execution) =>
         return preflight;
     if (isCancelled(execution.signal))
         return err(new AnalysisCancelledError("find_changed_behavior"));
+    if (parsed.data.replay_run_id !== undefined) {
+        const replay = selectCompletedInvestigationReplay(initial.value, parsed.data);
+        if (!replay.ok)
+            return replay;
+        return completeOutcome(replay.value.workspace, replay.value.run, true, execution.session);
+    }
+    if (execution.authorizeInputRead !== undefined) {
+        const authorized = await execution.authorizeInputRead();
+        if (!authorized.ok)
+            return authorized;
+    }
     await execution.progress?.report({
         phase: "scan_versions",
         completed: 0,
@@ -47,6 +56,7 @@ export const runCrossVersionInvestigation = async (input, policy, execution) =>
         session: execution.session,
         signal: execution.signal,
         progress: execution.progress,
+        authorizeWorkspaceWrite: execution.authorizeWorkspaceWrite,
     });
 };
 const continueInvestigation = async (context) => {
@@ -74,6 +84,11 @@ const continueInvestigation = async (context) => {
             run.run_id === legacyIdentity.runId));
     if (context.initial !== null && existing?.status === "complete")
         return completeOutcome(context.initial, existing, true, context.session);
+    if (context.authorizeWorkspaceWrite !== undefined) {
+        const authorized = await context.authorizeWorkspaceWrite();
+        if (!authorized.ok)
+            return authorized;
+    }
     const pages = createInventoryEvidencePages(context.input, context.snapshots);
     if (!pages.ok)
         return pages;
@@ -192,31 +207,11 @@ const ensureComparisonCheckpoint = async (input, state, 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 evidence = createChangedBehaviorEvidence(state.workspace, state.run, comparison.value);
     const run = investigationRunSchema.parse({
         ...state.run,
         status: "complete",
@@ -238,40 +233,6 @@ const finalizeInvestigation = async (input, state, policy, session) => {
     });
     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

package/dist/application/CrossVersionInvestigationEvidence.js

@@ -0,0 +1,64 @@
+import { compareArtifacts } from "../domain/artifactComparison.js";
+import { findChangedBehavior } from "../domain/changedBehavior.js";
+import { createEvidence } from "../domain/evidence.js";
+import { investigationRunSummarySchema, } from "../domain/investigationWorkspace.js";
+import { jsonValueSchema } from "../domain/jsonValue.js";
+import { AUTOMATIC_RUN_LIMITATION } from "./CrossVersionInventory.js";
+import { ARTIFACT_COMPARISON_PROVIDER, CHANGED_BEHAVIOR_PROVIDER, } from "./InvestigationProviders.js";
+/** Derive deterministic artifact-comparison Evidence from inventory pages. */
+export 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],
+    });
+};
+/** Derive the deterministic final report for one comparison checkpoint. */
+export const createChangedBehaviorEvidence = (workspace, run, comparison) => {
+    const limit = Math.min(run.options.change_limit, 100);
+    const changed = findChangedBehavior([comparison], 0, limit);
+    const summary = investigationRunSummarySchema.parse({
+        schema_version: 1,
+        workspace_id: workspace.workspace_id,
+        run_id: run.run_id,
+        left_manifest_id: run.left.manifest_id,
+        right_manifest_id: run.right.manifest_id,
+        inventory_evidence_count: run.left_inventory_evidence_ids.length +
+            run.right_inventory_evidence_ids.length,
+        comparison_evidence_id: comparison.evidence_id,
+        limitations: run.limitations,
+    });
+    return createEvidence(undefined, CHANGED_BEHAVIOR_PROVIDER, {
+        predicateType: "rea.changed-behavior/v1",
+        operation: "find_changed_behavior",
+        parameters: {
+            workspace_id: workspace.workspace_id,
+            run_id: 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 evidenceIds = (records) => records.map(({ evidence_id: id }) => id);

package/dist/application/CrossVersionInvestigationReplay.js

@@ -0,0 +1,170 @@
+import { isDeepStrictEqual } from "node:util";
+import { artifactInventoryResultSchema, } from "../domain/artifactGraph.js";
+import { parseArtifactInventoryEvidence } from "../domain/artifactInventoryEvidence.js";
+import { EvidenceIntegrityError, InvestigationWorkspaceError, } from "../domain/errors.js";
+import { err, ok } from "../domain/result.js";
+import { createArtifactComparisonEvidence, createChangedBehaviorEvidence, } from "./CrossVersionInvestigationEvidence.js";
+import { AUTOMATIC_RUN_LIMITATION } from "./CrossVersionInventory.js";
+import { ARTIFACT_GRAPH_PROVIDER } from "./InvestigationProviders.js";
+/** Select and verify one caller-identified complete run without input access. */
+export const selectCompletedInvestigationReplay = (workspace, input) => {
+    const run = workspace?.runs.find(({ run_id: runId }) => runId === input.replay_run_id);
+    if (workspace === null ||
+        run === undefined ||
+        run.status !== "complete" ||
+        !controlsMatch(run, input))
+        return replayConflict();
+    const records = new Map(workspace.bundle.records.map((record) => [record.evidence_id, record]));
+    const left = inventoryRecords(records, run.left_inventory_evidence_ids);
+    const right = inventoryRecords(records, run.right_inventory_evidence_ids);
+    if (!left.ok)
+        return left;
+    if (!right.ok)
+        return right;
+    if (!pathsMatch(left.value, input.left_path) ||
+        !pathsMatch(right.value, input.right_path))
+        return replayConflict();
+    const validated = validateLinkedEvidence(workspace, run, left.value, right.value);
+    return validated.ok ? ok({ workspace, run }) : validated;
+};
+const controlsMatch = (run, input) => isDeepStrictEqual(run.options, input.options) &&
+    run.integrity_policy === input.integrity_policy &&
+    run.integrity_continue_approved === input.integrity_continue_approved &&
+    run.max_integrity_mismatches === input.max_integrity_mismatches;
+const inventoryRecords = (records, evidenceIds) => {
+    if (new Set(evidenceIds).size !== evidenceIds.length)
+        return replayIntegrity("Investigation replay repeats inventory Evidence");
+    const selected = evidenceIds.flatMap((evidenceId) => {
+        const evidence = records.get(evidenceId);
+        return evidence === undefined ? [] : [evidence];
+    });
+    return selected.length === evidenceIds.length
+        ? ok(selected)
+        : replayIntegrity("Investigation replay is missing inventory Evidence");
+};
+const pathsMatch = (records, path) => records.every(({ subject }) => subject?.local_path === path);
+const validateLinkedEvidence = (workspace, run, leftRecords, rightRecords) => {
+    try {
+        const left = validateInventory(leftRecords, run.left, run);
+        const right = validateInventory(rightRecords, run.right, run);
+        if (!left.ok)
+            return left;
+        if (!right.ok)
+            return right;
+        const expectedLimitations = runLimitations(left.value, right.value);
+        if (!isDeepStrictEqual(run.limitations, expectedLimitations))
+            return replayIntegrity("Investigation replay limitations disagree with inventory Evidence");
+        const comparison = createArtifactComparisonEvidence({ left: left.value.records, right: right.value.records }, run.options.change_limit);
+        const storedComparison = evidenceFor(workspace, run.comparison_evidence_id);
+        if (storedComparison === undefined ||
+            !isDeepStrictEqual(storedComparison, comparison))
+            return replayIntegrity("Investigation replay comparison Evidence is inconsistent");
+        const result = createChangedBehaviorEvidence(workspace, run, comparison);
+        const storedResult = evidenceFor(workspace, run.result_evidence_id);
+        return storedResult !== undefined && isDeepStrictEqual(storedResult, result)
+            ? ok(null)
+            : replayIntegrity("Investigation replay result Evidence is inconsistent");
+    }
+    catch (cause) {
+        return replayIntegrity("Investigation replay linked Evidence is invalid", cause);
+    }
+};
+const validateInventory = (records, target, run) => {
+    const pages = records.map((record) => artifactInventoryResultSchema.parse(record.normalized_result));
+    const expectedPageCount = Math.max(1, Math.ceil((pages[0]?.manifest.node_count ?? 0) / run.options.page_size), Math.ceil((pages[0]?.manifest.occurrence_count ?? 0) / run.options.page_size), Math.ceil((pages[0]?.manifest.edge_count ?? 0) / run.options.page_size));
+    if (records.length !== expectedPageCount)
+        return replayIntegrity("Investigation replay inventory Evidence pagination is inconsistent");
+    if (!sameSnapshotMetadata(pages))
+        return replayIntegrity("Investigation replay inventory pages disagree on snapshot metadata");
+    for (const [index, record] of records.entries()) {
+        const page = pages[index];
+        if (page === undefined || !inventoryRecordMatches(record, page, run, index))
+            return replayIntegrity("Investigation replay inventory Evidence is inconsistent");
+    }
+    const result = parseArtifactInventoryEvidence(records);
+    if (!result.inventory.complete || !targetMatches(result.inventory, target))
+        return replayIntegrity("Investigation replay inventory commitment is inconsistent");
+    return ok({ records, result });
+};
+const inventoryRecordMatches = (record, page, run, index) => {
+    const offset = index * run.options.page_size;
+    const parameters = {
+        node_offset: offset,
+        node_limit: run.options.page_size,
+        occurrence_offset: offset,
+        occurrence_limit: run.options.page_size,
+        edge_offset: offset,
+        edge_limit: run.options.page_size,
+        max_entries: run.options.max_entries,
+        max_total_bytes: run.options.max_total_bytes,
+        max_entry_bytes: run.options.max_entry_bytes,
+        max_compression_ratio: run.options.max_compression_ratio,
+        max_depth: run.options.max_depth,
+        max_path_bytes: run.options.max_path_bytes,
+        integrity_policy: run.integrity_policy,
+        integrity_continue_approved: run.integrity_continue_approved,
+        max_integrity_mismatches: run.max_integrity_mismatches,
+    };
+    const locations = page.occurrences.items.map(({ logical_path: path }) => ({
+        kind: "artifact-path",
+        path,
+    }));
+    return (record.subject !== null &&
+        record.subject.name === record.subject.local_path.split("/").at(-1) &&
+        record.subject.digest.sha256 === page.manifest.root_sha256 &&
+        record.subject.format === page.manifest.root_format &&
+        record.subject.architecture === null &&
+        isDeepStrictEqual(record.provider, ARTIFACT_GRAPH_PROVIDER) &&
+        record.predicate_type === "rea.analysis/v2" &&
+        record.operation === "inventory_artifact" &&
+        isDeepStrictEqual(record.parameters, parameters) &&
+        record.raw_result === null &&
+        record.confidence === "observed" &&
+        record.authority === "shipped-artifact" &&
+        record.environment === null &&
+        isDeepStrictEqual(record.limitations, page.limitations) &&
+        isDeepStrictEqual(record.locations, locations) &&
+        record.evidence_links.length === 0 &&
+        isDeepStrictEqual(page.limits, traversalLimits(run)) &&
+        pageMatches(page.nodes, offset, run.options.page_size, page.manifest.node_count) &&
+        pageMatches(page.occurrences, offset, run.options.page_size, page.manifest.occurrence_count) &&
+        pageMatches(page.edges, offset, run.options.page_size, page.manifest.edge_count));
+};
+const sameSnapshotMetadata = (pages) => {
+    const first = pages[0];
+    return (first !== undefined &&
+        pages.every((page) => isDeepStrictEqual(page.manifest, first.manifest) &&
+            isDeepStrictEqual(page.limits, first.limits) &&
+            isDeepStrictEqual(page.provenance, first.provenance) &&
+            isDeepStrictEqual(page.integrity_contradictions, first.integrity_contradictions) &&
+            isDeepStrictEqual(page.limitations, first.limitations)));
+};
+const pageMatches = (page, offset, limit, total) => page.offset === offset &&
+    page.limit === limit &&
+    page.total === total &&
+    page.items.length === Math.max(0, Math.min(limit, page.total - offset)) &&
+    page.next_offset === (offset + limit < page.total ? offset + limit : null);
+const traversalLimits = (run) => ({
+    max_entries: run.options.max_entries,
+    max_total_bytes: run.options.max_total_bytes,
+    max_entry_bytes: run.options.max_entry_bytes,
+    max_compression_ratio: run.options.max_compression_ratio,
+    max_depth: run.options.max_depth,
+    max_path_bytes: run.options.max_path_bytes,
+});
+const targetMatches = (inventory, target) => inventory.manifest.root_sha256 === target.root_sha256 &&
+    inventory.manifest.graph_sha256 === target.graph_sha256 &&
+    inventory.manifest.manifest_id === target.manifest_id &&
+    inventory.manifest.root_format === target.format;
+const runLimitations = (left, right) => [
+    ...new Set([
+        ...left.result.inventory.limitations.map((item) => `Left: ${item}`),
+        ...right.result.inventory.limitations.map((item) => `Right: ${item}`),
+        AUTOMATIC_RUN_LIMITATION,
+    ]),
+].sort((first, second) => first.localeCompare(second));
+const evidenceFor = (workspace, evidenceId) => evidenceId === null
+    ? undefined
+    : workspace.bundle.records.find(({ evidence_id: current }) => current === evidenceId);
+const replayConflict = () => err(new InvestigationWorkspaceError("read", "revision-conflict"));
+const replayIntegrity = (message, cause) => err(new EvidenceIntegrityError(message, cause === undefined ? undefined : { cause }));

package/dist/application/DeferredFileAuthorization.js

@@ -0,0 +1,61 @@
+import { AnalysisProtocolError, PermissionRequiredError, } from "../domain/errors.js";
+import { err, ok } from "../domain/result.js";
+import { PermissionPathError, } from "./PermissionAuthority.js";
+/** Authorize one root-scoped operation and project policy path failures. */
+export const authorizeRootPermission = async (authority, request) => {
+    const authorized = await authority.authorize({
+        capability: request.capability,
+        roots: request.roots,
+        executables: [],
+        environment_names: [],
+        network: "none",
+        mount: false,
+        operation_identity: `${request.operation}:${request.capability}:${request.roots.join(":")}`,
+    }, request.access);
+    return authorized.ok
+        ? ok(null)
+        : err(authorized.error instanceof PermissionRequiredError
+            ? authorized.error
+            : new AnalysisProtocolError(authorized.error.message, {
+                cause: authorized.error,
+            }));
+};
+/** Authorize an existing file read and defer write authority until requested. */
+export const authorizeFileReadWithDeferredWrite = async (authority, input) => {
+    const read = await authority.authorize({
+        capability: input.readCapability,
+        roots: [input.path],
+        executables: [],
+        environment_names: [],
+        network: "none",
+        mount: false,
+        operation_identity: `${input.operation}:${input.readCapability}:${input.path}`,
+    }, "read");
+    let writeAuthorization;
+    if (!read.ok) {
+        if (!(read.error instanceof PermissionPathError) ||
+            read.error.reason !== "not_found")
+            return err(read.error instanceof PermissionRequiredError
+                ? read.error
+                : new AnalysisProtocolError(read.error.message, {
+                    cause: read.error,
+                }));
+        writeAuthorization = authorizeRootPermission(authority, {
+            capability: input.writeCapability,
+            roots: [input.path],
+            access: "write",
+            operation: input.operation,
+        });
+        const authorized = await writeAuthorization;
+        if (!authorized.ok)
+            return authorized;
+    }
+    return ok({
+        authorizeWrite: () => (writeAuthorization ??= authorizeRootPermission(authority, {
+            capability: input.writeCapability,
+            roots: [input.path],
+            access: "write",
+            operation: input.operation,
+        })),
+    });
+};

package/dist/application/DirectAnalysis.js

@@ -12,6 +12,7 @@ import { parseBinaryTarget } from "../domain/binaryTarget.js";
 import { snapshotEvidenceForQuery, snapshotMatchesTarget, } from "../domain/analysisSnapshot.js";
 import { err, ok } from "../domain/result.js";
 import { loadConfiguredPermissionAuthority } from "./PermissionConfiguration.js";
+import { authorizeFileReadWithDeferredWrite, } from "./DeferredFileAuthorization.js";
 const WORKFLOW_PROVIDER = {
     id: "rea-workflow",
     name: "REA composed investigation workflow",
@@ -26,6 +27,9 @@ export const runDirectAnalysis = async (path, tool, arguments_, options = {}) =>
     logger: options.logger ?? silentLogger,
     snapshotPath: options.snapshotPath,
     signal,
+    ...(options.permissionAuthority === undefined
+        ? {}
+        : { permissionAuthority: options.permissionAuthority }),
 }));
 /** Execute one provider-native semantic operation with atomic provenance. */
 export const runProviderAnalysis = async (path, tool, arguments_, logger = silentLogger, signal) => withProcessCancellation(signal, (operationSignal) => runAnalysis(path, tool, arguments_, {
@@ -51,19 +55,8 @@ export const runSessionStatus = async (logger = silentLogger) => {
         await session.close();
     }
 };
-const authorizeAnalysis = async (authority, tool, arguments_, snapshotPath) => {
+const authorizeAnalysis = async (authority, tool, arguments_) => {
     const requests = [];
-    if (snapshotPath !== undefined) {
-        requests.push({
-            capability: "snapshot_read",
-            path: snapshotPath,
-            access: "write",
-        }, {
-            capability: "snapshot_write",
-            path: snapshotPath,
-            access: "write",
-        });
-    }
     if (tool === "extract_artifact" && typeof arguments_.output_root === "string")
         requests.push({
             capability: "artifact_extract",
@@ -107,17 +100,41 @@ const authorizeAnalysis = async (authority, tool, arguments_, snapshotPath) => {
     }
     return ok(null);
 };
+const permissionAuthorityFor = (config, supplied) => supplied === undefined
+    ? loadConfiguredPermissionAuthority(config)
+    : Promise.resolve(ok(supplied));
+const authorizeSnapshotAccess = async (authority, tool, snapshotPath) => snapshotPath === undefined
+    ? ok(undefined)
+    : authorizeFileReadWithDeferredWrite(authority, {
+        path: snapshotPath,
+        readCapability: "snapshot_read",
+        writeCapability: "snapshot_write",
+        operation: tool,
+    });
+const authorizeDeferredWrite = (authorization) => authorization?.authorizeWrite() ?? Promise.resolve(ok(null));
+const authorizeAnalysisRun = async (input) => {
+    const authority = await permissionAuthorityFor(input.config, input.suppliedAuthority);
+    if (!authority.ok)
+        return authority;
+    const operation = await authorizeAnalysis(authority.value, input.tool, input.arguments);
+    if (!operation.ok)
+        return operation;
+    return authorizeSnapshotAccess(authority.value, input.tool, input.snapshotPath);
+};
 const runAnalysis = async (path, tool, arguments_, options) => {
     const { logger, signal, snapshotPath } = options;
     const config = parseConfig(process.env);
     if (!config.ok)
         return cliError(config.error);
-    const permissionAuthority = await loadConfiguredPermissionAuthority(config.value);
-    if (!permissionAuthority.ok)
-        return cliError(permissionAuthority.error);
-    const authorized = await authorizeAnalysis(permissionAuthority.value, tool, arguments_, snapshotPath);
-    if (!authorized.ok)
-        return cliError(authorized.error);
+    const authorization = await authorizeAnalysisRun({
+        config: config.value,
+        suppliedAuthority: options.permissionAuthority,
+        tool,
+        arguments: arguments_,
+        snapshotPath,
+    });
+    if (!authorization.ok)
+        return cliError(authorization.error);
     const unavailable = snapshotUnavailable(snapshotPath, config.value.hopperLoaderArgs);
     if (unavailable !== undefined)
         return cliError(unavailable);
@@ -135,6 +152,9 @@ const runAnalysis = async (path, tool, arguments_, options) => {
             return cliError(prepared.error);
         if (prepared.value.evidence !== undefined)
             return prepared.value.evidence;
+        const writable = await authorizeDeferredWrite(authorization.value);
+        if (!writable.ok)
+            return cliError(writable.error);
         const { snapshot } = prepared.value;
         const opened = await session.open(path, snapshot === undefined ? { signal } : { signal, snapshot });
         if (!opened.ok)

package/dist/application/Doctor.js

@@ -37,23 +37,28 @@ export const runDoctor = async (target, host = systemDoctorHost()) => {
         remediation: "REA supports macOS 12+, Ubuntu 24.04+, Fedora 41+, and 64-bit Arch Linux.",
         classification: "unsupported_host",
     }));
-    const candidates = [
-        host.configuredHopperPath,
-        DEFAULT_HOPPER,
-        SYSTEM_LINUX_HOPPER,
-        linuxHopperLauncherPath(homedir()),
-        ...(await host.manualHopperPaths()),
-        await host.brewHopperPath(),
-    ].filter((value) => value !== undefined);
+    const candidates = host.configuredHopperPath === undefined
+        ? [
+            DEFAULT_HOPPER,
+            SYSTEM_LINUX_HOPPER,
+            linuxHopperLauncherPath(homedir()),
+            ...(await host.manualHopperPaths()),
+            await host.brewHopperPath(),
+        ].filter((value) => value !== undefined)
+        : [host.configuredHopperPath];
     let hopperPath;
     for (const candidate of new Set(candidates))
         if (await host.executable(candidate)) {
             hopperPath = candidate;
             break;
         }
-    checks.push(check("hopper", hopperPath !== undefined, hopperPath, {
-        remediation: "Run rea setup to install Hopper, or set HOPPER_LAUNCHER_PATH.",
-        classification: "missing_analysis_engine",
+    checks.push(check("hopper", hopperPath !== undefined, hopperPath ?? host.configuredHopperPath, {
+        remediation: host.configuredHopperPath === undefined
+            ? "Run rea setup to install Hopper, or set HOPPER_LAUNCHER_PATH."
+            : "Unset or update HOPPER_LAUNCHER_PATH to an executable Hopper launcher.",
+        classification: host.configuredHopperPath === undefined
+            ? "missing_analysis_engine"
+            : "config_drift",
     }));
     if (host.platform === "linux" && hopperPath !== undefined)
         checks.push(check("hopper-version", await host.supportedLinuxHopper(hopperPath), hopperPath, {