rea-agents 1.5.0 → 1.6.0

package/README.md

@@ -10,11 +10,11 @@
 
 [![npm version](https://img.shields.io/npm/v/rea-agents?style=flat-square&color=cb3837)](https://www.npmjs.com/package/rea-agents)
 [![CI](https://img.shields.io/github/actions/workflow/status/morluto/rea/ci.yml?branch=main&style=flat-square&label=CI)](https://github.com/morluto/rea/actions/workflows/ci.yml)
-[![70 MCP tools](https://img.shields.io/badge/MCP_tools-70-5c4ee5?style=flat-square)](#70-tools-for-investigation)
+[![78 MCP tools](https://img.shields.io/badge/MCP_tools-78-5c4ee5?style=flat-square)](#78-tools-for-investigation)
 [![Node.js 22+](https://img.shields.io/badge/Node.js-22.19%2B-339933?style=flat-square&logo=nodedotjs&logoColor=white)](https://nodejs.org/)
 [![MIT license](https://img.shields.io/badge/license-MIT-f4c430?style=flat-square)](LICENSE)
 
-[Quick start](#quick-start) · [Current status](#current-status) · [Investigation model](#the-investigation-model) · [70 tools](#70-tools-for-investigation) · [Roadmap](#roadmap) · [How it works](#how-it-works)
+[Quick start](#quick-start) · [Current status](#current-status) · [Investigation model](#the-investigation-model) · [78 tools](#78-tools-for-investigation) · [Roadmap](#roadmap) · [How it works](#how-it-works)
 
 <br />
 
@@ -30,7 +30,7 @@
 
 See a feature in an app that you want in your own product? Give the app to your agent—even without its source code. With REA, the agent can investigate the feature, explain how it works, show its evidence, and build a version adapted to your stack and requirements.
 
-REA gives agents one consistent way to investigate software. Today that includes deep native analysis through Hopper, complete function dossiers, reproducible Evidence v2 records, and controlled process capture. The longer-term toolkit extends the same agent workflow to packaged apps, JavaScript bundles, websites, APIs, protocols, mobile artifacts, firmware, runtime behavior, and differences between versions.
+REA gives agents one consistent way to investigate software. Today that includes deep native analysis through Hopper, complete function dossiers, reproducible Evidence v2 records, controlled process capture, passive website and Electron observation, and bounded JavaScript/source-map reconstruction. The longer-term toolkit extends the same agent workflow to APIs, protocols, mobile artifacts, firmware, richer runtime behavior, and differences between versions.
 
 Reverse engineering normally makes the operator choose a tool, learn its API, move evidence between programs, and decide what to inspect next. REA gives that work to the agent through commands, skills, structured results, and repeatable investigation workflows.
 
@@ -294,16 +294,17 @@ REA handles the app analysis in steps 1–5. The agent performs step 6 with its
 - Analyze Swift and Objective-C metadata without manually untangling every mangled symbol.
 - Leave names, comments, and bookmarks in Hopper so human and agent analysis reinforce each other.
 
-## 70 tools for investigation
+## 78 tools for investigation
 
-| Tool family               | Count | Examples                                                                                                                           |
-| ------------------------- | ----: | ---------------------------------------------------------------------------------------------------------------------------------- |
-| Native inspection         |    33 | procedures, pseudocode, assembly, strings, names, segments, callers, callees, xrefs, annotations                                   |
-| Investigation workflows   |    10 | `binary_overview`, `analyze_function`, `batch_decompile`, `trace_feature`, call graphs, Swift and Objective-C discovery            |
-| Native macOS utilities    |     5 | Mach-O metadata, code signatures, plists, architectures, Swift demangling; Hopper-free and provenance-bearing                      |
-| Artifact graph            |     2 | deterministic directory, ZIP/APK/IPA, and ASAR inventory; explicitly selected extraction into an absent owned tree                 |
-| Browser observation       |     2 | exact-origin CDP page discovery and passive DOM, accessibility, script, resource, network, console, worker, and storage inspection |
-| Workspace and observation |    18 | target lifecycle, Evidence v2 bundles, process/artifact/function comparison, evidence-linked residual-unknown lifecycle            |
+| Tool family               | Count | Examples                                                                                                                         |
+| ------------------------- | ----: | -------------------------------------------------------------------------------------------------------------------------------- |
+| Native inspection         |    33 | procedures, pseudocode, assembly, strings, names, segments, callers, callees, xrefs, annotations                                 |
+| Investigation workflows   |    10 | `binary_overview`, `analyze_function`, `batch_decompile`, `trace_feature`, call graphs, Swift and Objective-C discovery          |
+| Native macOS utilities    |     5 | Mach-O metadata, code signatures, plists, architectures, Swift demangling; Hopper-free and provenance-bearing                    |
+| Artifact graph            |     2 | deterministic directory, ZIP/APK/IPA, and ASAR inventory; explicitly selected extraction into an absent owned tree               |
+| Browser observation       |     8 | exact-origin CDP capture, bundle and source-map analysis, WebMCP discovery, session timelines, capture diff, and visual evidence |
+| Electron observation      |     2 | canonical-root-confined file-page discovery and passive DOM, resource, and optionally approved script-source inspection          |
+| Workspace and observation |    18 | target lifecycle, Evidence v2 bundles, process/artifact/function comparison, evidence-linked residual-unknown lifecycle          |
 
 The public interface describes what the agent is trying to learn. Providers decide how to answer. macOS utilities handle common semantic inspection without launching Hopper; Hopper handles deeper native analysis; the process harness implements controlled behavioral capture.
 
@@ -312,7 +313,8 @@ The public interface describes what the agent is trying to learn. Providers deci
 REA is already useful for native application investigation on macOS:
 
 - Open Mach-O, ELF, PE, `.app`, ZIP, APK, IPA, ASAR, plist, JavaScript, source-map, and Hopper database targets.
-- Attach to a user-owned Chrome-family browser over a configured loopback CDP endpoint, list only pages on approved exact origins, and capture bounded passive web evidence without navigation or JavaScript evaluation.
+- Attach to a user-owned Chrome-family browser over a configured loopback CDP endpoint; capture exact-origin web structure, safe metadata, approved value-free payload shapes, bundle/source-map evidence, WebMCP declarations, user-action timelines, capture diffs, and explicitly approved screenshots without navigation or JavaScript evaluation.
+- Inspect Electron `file://` renderer pages through a separate canonical-root permission boundary without invoking Electron APIs; script contents remain separately approved and byte bounded.
 - Traverse content-addressed artifact graphs without extraction; on macOS, read-only DMG traversal additionally requires `native_mount_approved: true` and `REA_ARTIFACT_NATIVE_MOUNT_ENABLED=true`. Materialize only approved occurrences into absent output roots.
 - Build bounded function dossiers with pseudocode, assembly, CFG edges, comments, calls, references, strings, and names.
 - Search and trace features across symbols, strings, metadata, references, and call paths.
@@ -346,14 +348,14 @@ rea list-browser-targets http://127.0.0.1:9222 --approved --json
 rea inspect-web-page http://127.0.0.1:9222 TARGET_ID --approved --json
 ```
 
-`list_browser_targets` and `inspect_web_page` expose the same Evidence v2 contracts over MCP. Inspection is passive: REA does not evaluate page JavaScript, navigate, click, close the page, or close the browser. It redacts query values and never retains headers, bodies, cookies, storage values, console argument values, or WebSocket payloads. Existing activity before attach is explicitly unavailable. See [Website observation with CDP](docs/browser-observation.md) for browser startup, schemas, limits, and the threat model.
+All eight browser tools expose the same Evidence v2 contracts over CLI and MCP. Inspection is passive: REA does not evaluate page JavaScript, navigate, click, close the page, or close the browser. Query values, credentials, cookies, authorization headers, storage values, and raw JSON or WebSocket values are never retained. Separately approved captures can retain bounded redacted console primitives, value-free JSON/WebSocket shapes, script sources, accessibility text, or screenshot pixels. Existing activity before attach is explicitly unavailable. See [Website observation with CDP](docs/browser-observation.md) for browser startup, schemas, limits, and the threat model.
 
 ## Roadmap
 
 REA is growing into a toolkit for understanding software across static artifacts and observed behavior. The next capability families are:
 
 1. **Artifact decomposition** — DMG, ASAR, ZIP, packages, universal-binary slices, application resources, embedded frameworks, mobile packages, and artifact graphs.
-2. **Web and Electron investigation** — extend the shipped passive CDP observation with approved interaction, screenshots, Electron IPC, route discovery, controlled replay, and visual or structural differences.
+2. **Web and Electron investigation** — extend the shipped passive CDP, bundle, visual-diff, and file-page observation with approved interaction, controlled replay, Electron IPC observation, semantic UI differences, and deeper JavaScript reconstruction.
 3. **Deterministic behavior harnesses** — stronger process-tree ownership, protocol fixtures, network policy, filesystem tracing, signals, reconnects, and cross-version comparison.
 4. **JavaScript and source recovery** — bundle indexing, AST/module reconstruction, source-map discovery, historical-source matching, and CodeDB-backed cross-references.
 5. **Runtime observation** — approval-gated LLDB, Frida, system logs, process and filesystem observers, and native API tracing.

package/dist/application/BinarySession.js

@@ -7,7 +7,7 @@ import { EvidenceLedger } from "./EvidenceLedger.js";
 import { UnknownRegistryError } from "../domain/errors.js";
 import { enhancedToolNameSchema } from "../contracts/enhancedInputs.js";
 import { OFFICIAL_TOOL_CONTRACTS } from "../contracts/toolContracts.js";
-import { snapshotMatchesTarget } from "../domain/analysisSnapshot.js";
+import { snapshotMatchesTarget, snapshotTarget, } from "../domain/analysisSnapshot.js";
 import { AnalysisSnapshotCache, isSnapshotCacheable, } from "./AnalysisSnapshotCache.js";
 import { UNKNOWN_REGISTRY_PROVIDER, unknownEvidenceLinks, unknownMutationEvidence, } from "./UnknownEvidence.js";
 import { parseInvestigationWorkspace, } from "../domain/investigationWorkspace.js";
@@ -194,7 +194,8 @@ export class BinarySession {
                 return err(new EvidenceIntegrityError("Analysis snapshot target does not match the requested binary"));
             if (isAborted(options.signal))
                 return err(new AnalysisCancelledError("open_binary"));
-            if (this.#active?.target.path === parsed.value.path) {
+            if (this.#active?.target.path === parsed.value.path &&
+                snapshotMatchesTarget(snapshotTarget(this.#active.target), parsed.value)) {
                 if (options.snapshot !== undefined) {
                     const imported = this.importAnalysisSnapshot(options.snapshot);
                     if (!imported.ok)
@@ -401,8 +402,17 @@ export class BinarySession {
         this.#emitAvailabilityChanged();
     }
     #emitAvailabilityChanged() {
-        for (const listener of this.#availabilityListeners)
-            listener();
+        for (const listener of this.#availabilityListeners) {
+            try {
+                const notification = listener();
+                if (notification !== undefined)
+                    void notification.catch(() => undefined);
+            }
+            catch {
+                // External observers are best-effort notifications. Contain only the
+                // callback failure so state transitions and other listeners continue.
+            }
+        }
     }
     #serialize(operation) {
         const result = this.#transition.then(operation, operation);

package/dist/application/BrowserEvidence.js

@@ -2,15 +2,13 @@ import { createEvidence, } from "../domain/evidence.js";
 import { jsonValueSchema } from "../domain/jsonValue.js";
 /** Create Evidence v2 for a policy-scoped external browser observation. */
 export const createBrowserEvidence = (operation, input, result, provider) => createEvidence(undefined, provider, {
-    predicateType: operation === "list_browser_targets"
-        ? "rea.browser-target-list/v1"
-        : "rea.web-page-inspection/v1",
+    predicateType: browserPredicate(operation),
     operation,
     parameters: browserParameters(input),
     result: jsonValueSchema.parse(result),
     confidence: "observed",
     authority: "external-service",
-    environment: "target" in result
+    environment: "browser" in result
         ? {
             id: `${result.browser.product}@${result.browser.revision}`,
             platform: process.platform,
@@ -20,16 +18,90 @@ export const createBrowserEvidence = (operation, input, result, provider) => cre
         : null,
     limitations: result.limitations,
 });
-const browserParameters = (input) => ({
-    cdp_endpoint: input.cdp_endpoint,
-    allowed_origins: input.allowed_origins,
-    ...("target_id" in input
-        ? {
+const browserParameters = (input) => {
+    if (!("cdp_endpoint" in input)) {
+        if ("max_changes" in input)
+            return {
+                before_target_id: input.before.inspection.target.target_id,
+                before_capture_ended_at: input.before.inspection.capture_window.ended_at,
+                after_target_id: input.after.inspection.target.target_id,
+                after_capture_ended_at: input.after.inspection.capture_window.ended_at,
+                max_changes: input.max_changes,
+            };
+        return {
+            before_artifact_uri: input.before.uri,
+            after_artifact_uri: input.after.uri,
+            channel_threshold: input.channel_threshold,
+            maximum_pixels: input.maximum_pixels,
+        };
+    }
+    const scope = {
+        cdp_endpoint: input.cdp_endpoint,
+        allowed_origins: input.allowed_origins,
+    };
+    if (!("target_id" in input))
+        return { ...scope, offset: input.offset, limit: input.limit };
+    if ("screenshot_approved" in input)
+        return {
+            ...scope,
+            target_id: input.target_id,
+            maximum_image_bytes: input.maximum_image_bytes,
+        };
+    if ("max_tools" in input)
+        return {
+            ...scope,
             target_id: input.target_id,
             observation_ms: input.observation_ms,
-            include_script_sources: input.include_script_sources,
-            include_storage_keys: input.include_storage_keys,
-            limits: input.limits,
-        }
-        : { offset: input.offset, limit: input.limit }),
-});
+            max_tools: input.max_tools,
+            max_schema_bytes: input.max_schema_bytes,
+            max_schema_nodes: input.max_schema_nodes,
+            max_schema_depth: input.max_schema_depth,
+        };
+    if (!("include_accessibility_text" in input))
+        return {
+            ...scope,
+            target_id: input.target_id,
+            observation_ms: input.observation_ms,
+            max_timeline_events: input.max_timeline_events,
+        };
+    return {
+        ...scope,
+        target_id: input.target_id,
+        observation_ms: input.observation_ms,
+        include_accessibility_text: input.include_accessibility_text,
+        include_console_text: input.include_console_text,
+        include_json_body_shapes: input.include_json_body_shapes,
+        include_websocket_shapes: input.include_websocket_shapes,
+        include_script_sources: input.include_script_sources,
+        include_storage_keys: input.include_storage_keys,
+        limits: input.limits,
+        ...(input.include_script_sources && "source_capture_approved" in input
+            ? {
+                source_capture_approved: input.source_capture_approved,
+                fetch_source_maps: input.fetch_source_maps,
+                source_map_fetch_approved: input.source_map_fetch_approved,
+                analysis_limits: input.analysis_limits,
+            }
+            : {}),
+    };
+};
+const browserPredicate = (operation) => {
+    switch (operation) {
+        case "list_browser_targets":
+            return "rea.browser-target-list/v1";
+        case "inspect_web_page":
+            return "rea.web-page-inspection/v2";
+        case "analyze_web_bundle":
+            return "rea.web-bundle-analysis/v1";
+        case "observe_web_session":
+            return "rea.web-observation-session/v1";
+        case "discover_webmcp_tools":
+            return "rea.webmcp-discovery/v1";
+        case "compare_web_captures":
+            return "rea.web-capture-diff/v1";
+        case "capture_web_screenshot":
+            return "rea.web-screenshot/v1";
+        case "compare_web_screenshots":
+            return "rea.web-screenshot-diff/v1";
+    }
+};

package/dist/application/BrowserObservationService.js

@@ -1,3 +1,4 @@
+import { isLiteralLoopbackHostname, } from "../domain/browserObservation.js";
 import { AnalysisCapabilityUnavailableError, AnalysisProtocolError, PermissionRequiredError, } from "../domain/errors.js";
 import { err, ok } from "../domain/result.js";
 import { createBrowserEvidence } from "./BrowserEvidence.js";
@@ -21,6 +22,66 @@ export const inspectWebPage = async (browser, authority, input, options = {}) =>
         ? ok(createBrowserEvidence("inspect_web_page", input, result.value, ready.value.identity()))
         : result;
 };
+/** Capture approved sources and derive bounded static web-bundle evidence. */
+export const analyzeWebBundle = async (browser, authority, input, options = {}) => {
+    const ready = await prepare(browser, authority, input, "analyze_web_bundle");
+    if (!ready.ok)
+        return ready;
+    const analyzed = await ready.value.analyzeBundle(input, options);
+    if (!analyzed.ok)
+        return analyzed;
+    return ok(createBrowserEvidence("analyze_web_bundle", input, analyzed.value, ready.value.identity()));
+};
+/** Observe navigation caused by external user actions during one armed window. */
+export const observeWebSession = async (browser, authority, input, options = {}) => {
+    const ready = await prepare(browser, authority, input, "observe_web_session");
+    if (!ready.ok)
+        return ready;
+    const observed = await ready.value.observeSession(input, options);
+    return observed.ok
+        ? ok(createBrowserEvidence("observe_web_session", input, observed.value, ready.value.identity()))
+        : observed;
+};
+/** Discover WebMCP declarations without exposing an invocation surface. */
+export const discoverWebMcpTools = async (browser, authority, input, options = {}) => {
+    const ready = await prepare(browser, authority, input, "discover_webmcp_tools");
+    if (!ready.ok)
+        return ready;
+    const discovered = await ready.value.discoverWebMcpTools(input, options);
+    return discovered.ok
+        ? ok(createBrowserEvidence("discover_webmcp_tools", input, discovered.value, ready.value.identity()))
+        : discovered;
+};
+/** Compare two already-normalized web captures without external access. */
+export const compareWebCaptureEvidence = async (browser, input) => {
+    const ready = requireBrowser(browser, "compare_web_captures");
+    if (!ready.ok)
+        return ready;
+    const compared = await ready.value.compareCaptures(input);
+    return compared.ok
+        ? ok(createBrowserEvidence("compare_web_captures", input, compared.value, ready.value.identity()))
+        : compared;
+};
+/** Capture one explicitly approved visible-viewport screenshot. */
+export const captureWebScreenshot = async (browser, authority, input, options = {}) => {
+    const ready = await prepare(browser, authority, input, "capture_web_screenshot");
+    if (!ready.ok)
+        return ready;
+    const captured = await ready.value.captureScreenshot(input, options);
+    return captured.ok
+        ? ok(createBrowserEvidence("capture_web_screenshot", input, captured.value, ready.value.identity()))
+        : captured;
+};
+/** Compare two self-verifying PNG artifacts without external access. */
+export const compareWebScreenshotEvidence = async (browser, input) => {
+    const ready = requireBrowser(browser, "compare_web_screenshots");
+    if (!ready.ok)
+        return ready;
+    const compared = await ready.value.compareScreenshots(input);
+    return compared.ok
+        ? ok(createBrowserEvidence("compare_web_screenshots", input, compared.value, ready.value.identity()))
+        : compared;
+};
 const prepare = async (browser, authority, input, operation) => {
     if (authority === undefined)
         return err(new AnalysisCapabilityUnavailableError("rea-cdp-browser", operation, "browser observation permission policy is not configured"));
@@ -44,9 +105,12 @@ const prepare = async (browser, authority, input, operation) => {
         ? err(new AnalysisCapabilityUnavailableError("rea-cdp-browser", operation, "browser observation provider is not configured"))
         : ok(browser);
 };
+const requireBrowser = (browser, operation) => browser === undefined
+    ? err(new AnalysisCapabilityUnavailableError("rea-cdp-browser", operation, "browser comparison provider is not configured"))
+    : ok(browser);
 const browserNetworkScope = (allowedOrigins) => allowedOrigins.every((origin) => {
     const hostname = new URL(origin).hostname;
-    return hostname === "127.0.0.1" || hostname === "[::1]";
+    return isLiteralLoopbackHostname(hostname);
 })
     ? "loopback"
     : "external";

package/dist/application/CapabilityInventory.js

@@ -71,6 +71,13 @@ const availabilityFor = (name, kind, targetOpen, targetKind, descriptors, policy
                 reason: "policy_disabled",
                 remediation: "Enable browser observation and configure exact CDP endpoint and page origins.",
             };
+    if (kind === "electron-provider")
+        return policy.electronObservationEnabled === true
+            ? { reason: "available", remediation: null }
+            : {
+                reason: "policy_disabled",
+                remediation: "Enable Electron observation and configure a loopback CDP endpoint and canonical file roots.",
+            };
     if (kind === "session")
         return { reason: "available", remediation: null };
     if (!targetOpen)

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/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,
@@ -198,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",
@@ -244,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);