rea-agents 3.2.0 → 4.0.0

package/bridge/hopper_bridge.py

@@ -128,6 +128,10 @@ class CapabilityUnavailableError(Exception):
     """The active Hopper build lacks one admitted public API operation."""
 
 
+class InvalidRequestError(Exception):
+    """Caller input failed bridge request or operation validation."""
+
+
 EXHAUSTIVE_ANALYSIS_METHODS = frozenset(
     (
         "analyze_function",
@@ -150,6 +154,11 @@ EXHAUSTIVE_ANALYSIS_METHODS = frozenset(
 
 
 def _hex(value):
+    if not isinstance(value, int) or isinstance(value, bool):
+        try:
+            value = int(str(value), 16)
+        except ValueError as error:
+            raise ValueError("Hopper returned a non-hexadecimal address") from error
     return "0x%x" % value
 
 
@@ -177,8 +186,8 @@ def _document(name=None):
             current = api.current_document()
             if current is not None and current.getDocumentName() == name:
                 return current
-            raise ValueError("Hopper document name is ambiguous")
-        raise ValueError("Unknown Hopper document")
+            raise InvalidRequestError("Hopper document name is ambiguous")
+        raise InvalidRequestError("Unknown Hopper document")
     if _selected_document is not None:
         for candidate in documents:
             if candidate.getDocumentName() == _selected_document:
@@ -188,7 +197,7 @@ def _document(name=None):
         return session_document
     current = api.current_document()
     if current is None:
-        raise ValueError("No Hopper document is loaded")
+        raise CapabilityUnavailableError("No Hopper document is loaded")
     return current
 
 
@@ -197,20 +206,20 @@ def _address(document, value=None):
     if value is None:
         return document.getCurrentAddress()
     if not isinstance(value, str):
-        raise ValueError("Address must be a string")
+        raise InvalidRequestError("Address must be a string")
     try:
         return int(value, 16)
     except ValueError:
         result = document.getAddressForName(value)
         if result in BAD_ADDRESSES:
-            raise ValueError("Unknown Hopper address or name")
+            raise InvalidRequestError("Unknown Hopper address or name")
         return result
 
 
 def _segment(document, address):
     result = document.getSegmentAtAddress(address)
     if result is None:
-        raise ValueError("Address is outside every segment")
+        raise InvalidRequestError("Address is outside every segment")
     return result
 
 
@@ -218,7 +227,7 @@ def _procedure(document, value=None):
     address = document.getCurrentAddress() if value is None else _address(document, value)
     result = _segment(document, address).getProcedureAtAddress(address)
     if result is None:
-        raise ValueError("No procedure exists at the requested address")
+        raise InvalidRequestError("No procedure exists at the requested address")
     return result
 
 
@@ -232,6 +241,10 @@ def _procedure_identity(procedure):
         "address": _hex(procedure.getEntryPoint()),
         "name": _procedure_name(procedure),
         "classification": None,
+        "body": {
+            "available": False,
+            "reason": "Hopper's public Python API does not expose complete function body ranges",
+        },
     }
 
 
@@ -278,7 +291,7 @@ def _procedure_references(document, params):
     procedure = _procedure(document, params.get("procedure"))
     direction = params.get("direction", "outgoing")
     if direction not in ("incoming", "outgoing"):
-        raise ValueError("direction must be incoming or outgoing")
+        raise InvalidRequestError("direction must be incoming or outgoing")
     addresses = _instruction_addresses(procedure)
     edges = set()
     for address in addresses:
@@ -300,6 +313,12 @@ def _procedure_references(document, params):
         })
     return {
         "procedure": _procedure_identity(procedure), "direction": direction,
+        "reference_kinds_available": False,
+        # The public Hopper API returns observed references but does not expose
+        # enough flow metadata to enumerate calls with no resolved target.
+        # Keep the required list field explicit; the provider records this as
+        # unknown coverage rather than claiming the list is exhaustive.
+        "unresolved_calls": [],
         "references": items,
     }
 
@@ -366,13 +385,13 @@ def _search_inventory(document, kind):
 def _search_results(document, kind, params):
     pattern = params.get("pattern")
     if not isinstance(pattern, str) or not pattern:
-        raise ValueError("pattern must be a non-empty string")
+        raise InvalidRequestError("pattern must be a non-empty string")
     mode = params.get("mode", "literal")
     if mode not in ("literal", "regex"):
-        raise ValueError("mode must be literal or regex")
+        raise InvalidRequestError("mode must be literal or regex")
     case_sensitive = params.get("case_sensitive", False)
     if not isinstance(case_sensitive, bool):
-        raise ValueError("case_sensitive must be a boolean")
+        raise InvalidRequestError("case_sensitive must be a boolean")
 
     if mode == "literal":
         needle = pattern if case_sensitive else pattern.casefold()
@@ -381,7 +400,7 @@ def _search_results(document, kind, params):
         try:
             expression = re.compile(pattern, 0 if case_sensitive else re.IGNORECASE)
         except (re.error, OverflowError) as error:
-            raise ValueError("Invalid regex pattern") from error
+            raise InvalidRequestError("Invalid regex pattern") from error
         matches = lambda value: expression.search(value) is not None
 
     selected = []
@@ -544,7 +563,11 @@ def _analyze_function(document, params):
     referenced_strings.sort(key=lambda item: (int(item["address"], 16), int(item["source_address"], 16)))
     referenced_names.sort(key=lambda item: (int(item["address"], 16), int(item["source_address"], 16)))
     return {
-        "procedure": {"address": _hex(procedure.getEntryPoint()), "name": _procedure_name(procedure), "classification": None, "signature": procedure.signatureString(), "locals": _procedure_locals(procedure)},
+        "procedure": {
+            **_procedure_identity(procedure),
+            "signature": procedure.signatureString(),
+            "locals": _procedure_locals(procedure),
+        },
         "pseudocode": pseudo,
         "assembly": assembly_lines,
         "comments": comments,
@@ -618,9 +641,9 @@ def _dispatch(method, params):
     if method == "read_bytes":
         length = params.get("length", 256)
         if isinstance(length, bool) or not isinstance(length, int):
-            raise ValueError("Byte-read length must be an integer")
+            raise InvalidRequestError("Byte-read length must be an integer")
         if length < 1:
-            raise ValueError("Byte-read length must be at least 1")
+            raise InvalidRequestError("Byte-read length must be at least 1")
         reader = getattr(document, "readBytes", None)
         if not callable(reader):
             raise CapabilityUnavailableError(
@@ -654,7 +677,7 @@ def _dispatch(method, params):
             or offset in BAD_ADDRESSES
             or offset < 0
         ):
-            raise ValueError("Address has no authoritative file-offset mapping")
+            raise InvalidRequestError("Address has no authoritative file-offset mapping")
         return {"address": _hex(address), "file_offset": offset}
     if method == "resolve_containing_procedure":
         address = _address(document, params.get("address"))
@@ -690,7 +713,7 @@ def _dispatch(method, params):
         else:
             result = document.getInstructionStart(max(0, target - 1))
         if result in BAD_ADDRESSES:
-            raise ValueError("No adjacent address")
+            raise InvalidRequestError("No adjacent address")
         return _hex(result)
     if method == "list_segments":
         result = []
@@ -729,14 +752,14 @@ def _dispatch(method, params):
         if requested is not None:
             key = _hex(_address(document, requested))
             values = {key: values[key]} if key in values else {}
-        return [{"address": _hex(address), "value": value} for address, value in sorted(values.items())]
+        return [{"address": address, "value": value} for address, value in values.items()]
     if method == "list_names":
         result = dict(_search_inventory(document, "name"))
         requested = params.get("address")
         if requested is not None:
             key = _hex(_address(document, requested))
             result = {key: result[key]} if key in result else {}
-        return [{"address": _hex(address), "value": value} for address, value in sorted(result.items(), key=lambda item: int(item[0]))]
+        return [{"address": address, "value": value} for address, value in result.items()]
     if method in ("search_procedures", "search_strings"):
         kind = "procedure" if method == "search_procedures" else "string"
         return _search_results(document, kind, params)
@@ -755,7 +778,16 @@ def _dispatch(method, params):
         if method == "procedure_info":
             blocks = list(procedure.basicBlockIterator())
             length = sum(max(0, block.getEndingAddress() - block.getStartingAddress()) for block in blocks)
-            return {"name": _procedure_name(procedure), "entrypoint": _hex(procedure.getEntryPoint()), "basicblock_count": procedure.getBasicBlockCount(), "length": length, "signature": procedure.signatureString(), "locals": _procedure_locals(procedure), "classification": None}
+            return {
+                "name": _procedure_name(procedure),
+                "entrypoint": _hex(procedure.getEntryPoint()),
+                "basicblock_count": procedure.getBasicBlockCount(),
+                "length": length,
+                "signature": procedure.signatureString(),
+                "locals": _procedure_locals(procedure),
+                "classification": None,
+                "body": _procedure_identity(procedure)["body"],
+            }
     if method == "set_address_name":
         address = _address(document, params.get("address"))
         try:
@@ -789,7 +821,7 @@ def _dispatch(method, params):
         address = _address(document, params.get("address"))
         document.removeBookmarkAtAddress(address)
         return not document.hasBookmarkAtAddress(address)
-    raise ValueError("Unknown bridge method")
+    raise InvalidRequestError("Unknown bridge method")
 
 
 def _serve_connection(connection):
@@ -803,13 +835,24 @@ def _serve_connection(connection):
         authenticated = False
         should_stop = False
         try:
-            request = json.loads(line.decode("utf-8"))
-            if set(request) != {"id", "token", "method", "params"}:
-                raise ValueError("Invalid bridge request shape")
+            try:
+                request = json.loads(line.decode("utf-8"))
+            except (UnicodeDecodeError, json.JSONDecodeError) as error:
+                raise InvalidRequestError("Invalid bridge request JSON") from error
+            if not isinstance(request, dict) or set(request) != {"id", "token", "method", "params"}:
+                raise InvalidRequestError("Invalid bridge request shape")
             request_id = request["id"]
             if isinstance(request_id, bool) or not isinstance(request_id, int) or request_id < 0:
-                raise ValueError("Invalid bridge request id")
-            if not isinstance(request["token"], str) or not hmac.compare_digest(request["token"], REA_TOKEN):
+                raise InvalidRequestError("Invalid bridge request id")
+            if (
+                not isinstance(request["method"], str) or not request["method"]
+                or not isinstance(request["params"], dict)
+            ):
+                raise InvalidRequestError("Invalid bridge method or parameters")
+            if (
+                not isinstance(request["token"], str) or not request["token"].isascii()
+                or not hmac.compare_digest(request["token"], REA_TOKEN)
+            ):
                 raise PermissionError("Invalid bridge capability")
             authenticated = True
             _write_message(file, {"id": request_id, "event": {
@@ -864,7 +907,7 @@ def _diagnostic_type(error):
         return "capability_unavailable"
     if isinstance(error, PermissionError):
         return "authorization"
-    if isinstance(error, (ValueError, TypeError, KeyError)):
+    if isinstance(error, InvalidRequestError):
         return "invalid_request"
     return "bridge_exception"
 

package/bridge/native/ReaNativeUI.swift

@@ -0,0 +1,157 @@
+import AppKit
+import ApplicationServices
+import CryptoKit
+import ScreenCaptureKit
+import Darwin
+
+struct Request: Decodable {
+  var pid: Int32
+  var window_id: UInt32
+  var executable: String
+  var sha256: String
+  var launch_time: Double?
+  var screenshot: Bool
+  var accessibility: Bool
+  var max_nodes: Int
+  var action: Action?
+}
+struct Action: Decodable { var kind: String; var path: [Int]?; var direction: String?; var text: String? }
+struct BoundaryFailure: Error { var code: String; var message: String }
+func fail(_ code: String, _ message: String) throws -> Never { throw BoundaryFailure(code: code, message: message) }
+func attribute(_ element: AXUIElement, _ key: String) -> CFTypeRef? {
+  var value: CFTypeRef?
+  return AXUIElementCopyAttributeValue(element, key as CFString, &value) == .success ? value : nil
+}
+func childCount(_ element: AXUIElement) -> Int {
+  var count = 0
+  return AXUIElementGetAttributeValueCount(element, kAXChildrenAttribute as CFString, &count) == .success ? count : 0
+}
+func children(_ element: AXUIElement, limit: Int) -> [AXUIElement] {
+  var value: CFArray?
+  let count = min(limit, childCount(element))
+  if count == 0 { return [] }
+  return AXUIElementCopyAttributeValues(element, kAXChildrenAttribute as CFString, 0, count, &value) == .success ? value as? [AXUIElement] ?? [] : []
+}
+func text(_ element: AXUIElement, _ key: String) -> Any { (attribute(element, key) as? String) ?? NSNull() as Any }
+func windowBounds(_ element: AXUIElement) -> CGRect? {
+  guard let p = attribute(element, kAXPositionAttribute), let s = attribute(element, kAXSizeAttribute),
+    CFGetTypeID(p) == AXValueGetTypeID(), CFGetTypeID(s) == AXValueGetTypeID() else { return nil }
+  var point = CGPoint.zero; var size = CGSize.zero
+  guard AXValueGetValue(p as! AXValue, .cgPoint, &point), AXValueGetValue(s as! AXValue, .cgSize, &size) else { return nil }
+  return CGRect(origin: point, size: size)
+}
+func observe(_ request: Request) async throws -> [String: Any] {
+  guard let app = NSRunningApplication(processIdentifier: request.pid), let url = app.executableURL else {
+    try fail("target-mismatch", "Selected PID does not expose an application executable URL")
+  }
+  guard let canonicalPointer = realpath(url.path, nil) else { try fail("target-mismatch", "Running executable path cannot be resolved") }
+  defer { free(canonicalPointer) }
+  let canonicalExecutable = String(cString: canonicalPointer)
+  guard canonicalExecutable == request.executable else {
+    try fail("target-mismatch", "Selected PID executable \(canonicalExecutable) differs from active target \(request.executable)")
+  }
+  guard let launch = app.launchDate?.timeIntervalSince1970 else {
+    try fail("process-identity-unavailable", "Selected application does not expose a launch time; stable PID reuse checks are unavailable")
+  }
+  if let expected = request.launch_time, expected != launch { try fail("process-replaced", "Selected process was replaced") }
+  let executableSize = (try FileManager.default.attributesOfItem(atPath: url.path)[.size] as? NSNumber)?.int64Value ?? -1
+  guard executableSize >= 0 && executableSize <= 256 * 1024 * 1024 else { try fail("target-limit", "Running executable exceeds the 256 MiB identity-check budget") }
+  let executableBytes = try Data(contentsOf: url, options: .mappedIfSafe)
+  guard SHA256.hash(data: executableBytes).map({ String(format: "%02x", $0) }).joined() == request.sha256 else {
+    try fail("target-mismatch", "Running executable bytes differ from the active target digest")
+  }
+  guard let windows = CGWindowListCopyWindowInfo([.optionIncludingWindow], request.window_id) as? [[String: Any]],
+    windows.count == 1, let window = windows.first,
+    (window[kCGWindowOwnerPID as String] as? NSNumber)?.int32Value == request.pid,
+    (window[kCGWindowLayer as String] as? NSNumber)?.intValue == 0,
+    let boundsDictionary = window[kCGWindowBounds as String] as? [String: Any],
+    let bounds = CGRect(dictionaryRepresentation: boundsDictionary as CFDictionary) else {
+    try fail("window-mismatch", "Selected window is absent or belongs to another process")
+  }
+  if request.screenshot && !CGPreflightScreenCaptureAccess() {
+    try fail("screen-recording-denied", "Grant Screen Recording to the REA host in System Settings > Privacy & Security, then retry; no broad capture fallback is used")
+  }
+  var selected: AXUIElement?
+  if request.accessibility || request.action != nil {
+    guard AXIsProcessTrusted() else { try fail("accessibility-denied", "Grant Accessibility to the REA host in System Settings > Privacy & Security, then retry") }
+    let application = AXUIElementCreateApplication(request.pid)
+    AXUIElementSetMessagingTimeout(application, 2)
+    guard let axWindows = attribute(application, kAXWindowsAttribute) as? [AXUIElement] else {
+      try fail("accessibility-unavailable", "Selected application does not expose accessibility windows")
+    }
+    let matches = axWindows.filter { windowBounds($0) == bounds }
+    guard matches.count == 1 else { try fail("ambiguous-window", "Accessibility window geometry does not identify exactly one selected window; selected CG bounds \(bounds), AX candidates \(axWindows.map { String(describing: windowBounds($0)) })") }
+    selected = matches[0]
+  }
+  if let action = request.action, let root = selected {
+    var element = root
+    for index in action.path ?? [] {
+      var selectedChild: CFArray?
+      guard index >= 0 && index < childCount(element),
+        AXUIElementCopyAttributeValues(element, kAXChildrenAttribute as CFString, index, 1, &selectedChild) == .success,
+        let item = (selectedChild as? [AXUIElement])?.first else { try fail("element-missing", "Selected accessibility path no longer exists") }
+      element = item
+    }
+    var owner: pid_t = 0
+    guard AXUIElementGetPid(element, &owner) == .success && owner == request.pid else { try fail("element-owner-mismatch", "Selected element belongs to another process") }
+    let outcome: AXError
+    switch action.kind {
+    case "click": outcome = AXUIElementPerformAction(element, kAXPressAction as CFString)
+    case "scroll": outcome = AXUIElementPerformAction(element, (action.direction == "increment" ? kAXIncrementAction : kAXDecrementAction) as CFString)
+    case "key-entry": outcome = AXUIElementSetAttributeValue(element, kAXValueAttribute as CFString, (action.text ?? "") as CFString)
+    default: try fail("unsupported-action", "Only selected-element press, increment/decrement and text-value entry are admitted")
+    }
+    guard outcome == .success else { try fail("action-failed", "Accessibility action failed with AXError \(outcome.rawValue)") }
+  }
+  var nodes: [[String: Any]] = []; var truncated = false
+  if request.accessibility, let root = selected {
+    var pending: [(AXUIElement, [Int])] = [(root, [])]
+    while let (element, path) = pending.popLast() {
+      if nodes.count >= request.max_nodes { truncated = true; break }
+      let totalChildren = childCount(element)
+      var actions: CFArray?
+      AXUIElementCopyActionNames(element, &actions)
+      nodes.append(["path": path, "role": text(element, kAXRoleAttribute), "title": text(element, kAXTitleAttribute), "value": text(element, kAXValueAttribute), "actions": actions as? [String] ?? [], "children_count": totalChildren])
+      if path.count >= 32 { if totalChildren > 0 { truncated = true }; continue }
+      let available = max(0, request.max_nodes - nodes.count - pending.count)
+      let count = min(available, totalChildren)
+      let items = children(element, limit: count)
+      if totalChildren > count { truncated = true }
+      for index in (0..<count).reversed() { pending.append((items[index], path + [index])) }
+    }
+  }
+  var screenshot: Any = NSNull()
+  if request.screenshot {
+    guard #available(macOS 14, *) else { try fail("unsupported-host", "Selected-window screenshots require macOS 14 or later") }
+    let content = try await SCShareableContent.excludingDesktopWindows(true, onScreenWindowsOnly: false)
+    guard let scWindow = content.windows.first(where: { $0.windowID == request.window_id && $0.owningApplication?.processID == request.pid }) else {
+      try fail("capture-window-missing", "Selected window disappeared before capture")
+    }
+    guard bounds.width > 0 && bounds.height > 0 && bounds.width <= 100000 && bounds.height <= 100000 else { try fail("window-bounds", "Selected window has invalid or oversized geometry") }
+    let filter = SCContentFilter(desktopIndependentWindow: scWindow)
+    let configuration = SCStreamConfiguration()
+    let scale = min(1, 2048 / max(bounds.width, bounds.height))
+    configuration.width = max(1, Int(bounds.width * scale)); configuration.height = max(1, Int(bounds.height * scale))
+    configuration.showsCursor = false
+    let image = try await SCScreenshotManager.captureImage(contentFilter: filter, configuration: configuration)
+    guard let png = NSBitmapImageRep(cgImage: image).representation(using: .png, properties: [:]) else {
+      try fail("capture-failed", "Selected-window PNG encoding failed")
+    }
+    screenshot = ["mime_type": "image/png", "base64": png.base64EncodedString(), "sha256": SHA256.hash(data: png).map({ String(format: "%02x", $0) }).joined(), "width": image.width, "height": image.height]
+  }
+  return ["window": ["pid": request.pid, "window_id": request.window_id, "executable": request.executable, "launch_time": launch, "title": window[kCGWindowName as String] as? String ?? ""], "nodes": nodes, "truncated": truncated, "screenshot": screenshot, "gaps": request.accessibility ? [] : ["Accessibility capture was disabled"]]
+}
+Task { @MainActor in
+  do {
+    let request = try JSONDecoder().decode(Request.self, from: Data(CommandLine.arguments[1].utf8))
+    let result = try await observe(request)
+    let output = try JSONSerialization.data(withJSONObject: ["ok": true, "result": result], options: [.sortedKeys])
+    FileHandle.standardOutput.write(output)
+  } catch {
+    let failure = error as? BoundaryFailure
+    let output: [String: Any] = ["ok": false, "code": failure?.code ?? "capture-failed", "message": failure?.message ?? error.localizedDescription]
+    if let data = try? JSONSerialization.data(withJSONObject: output, options: [.sortedKeys]) { FileHandle.standardOutput.write(data) }
+  }
+  exit(0)
+}
+RunLoop.main.run()

package/dist/application/AnalysisContextQueries.js

@@ -1,4 +1,5 @@
-import { AnalysisOutputError } from "../domain/errors.js";
+import { AnalysisCapabilityUnavailableError, AnalysisOutputError, } from "../domain/errors.js";
+import { parseDocuments } from "../domain/hopperValues.js";
 import { err, ok } from "../domain/result.js";
 const parameters = (document, address) => ({
     ...(document === undefined ? {} : { document }),
@@ -77,8 +78,22 @@ const resolveDocument = async (analysis, document, signal) => {
     if (document !== undefined)
         return ok(document);
     const current = await analysis.execute("current_document", {}, executionOptions(signal));
-    if (!current.ok)
-        return current;
+    if (!current.ok) {
+        if (!(current.error instanceof AnalysisCapabilityUnavailableError))
+            return current;
+        const listed = await analysis.execute("list_documents", {}, executionOptions(signal));
+        if (!listed.ok)
+            return listed;
+        const parsed = parseDocuments(listed.value.result);
+        if (!parsed.ok)
+            return err(new AnalysisOutputError("list_documents", "expected one document identity when resolving a headless provider", { cause: parsed.error }));
+        if (parsed.value.length !== 1)
+            return err(new AnalysisOutputError("list_documents", `expected exactly one document identity for a provider without current-document selection, received ${parsed.value.length}`));
+        const [documentName] = parsed.value;
+        if (documentName === undefined)
+            return err(new AnalysisOutputError("list_documents", "provider returned no document identity"));
+        return ok(documentName);
+    }
     return typeof current.value.result === "string"
         ? ok(current.value.result)
         : err(new AnalysisOutputError("current_document", "expected a document identity string"));
@@ -93,8 +108,7 @@ const facet = (result, operation) => result?.ok === true
 const isMissingCurrentProcedure = (error) => /(?:no procedure exists|not in a procedure)/iu.test(error.message);
 const isRequestLevelFailure = (error) => error._tag === "AnalysisCancelledError" ||
     error._tag === "AnalysisTimeoutError" ||
-    error._tag === "NoBinaryOpenError" ||
-    error._tag === "PermissionRequiredError";
+    error._tag === "NoBinaryOpenError";
 const containingProcedureName = (value) => {
     if (typeof value !== "object" || value === null || Array.isArray(value))
         return null;

package/dist/application/AnalysisSnapshotCache.js

@@ -1,6 +1,6 @@
 import { EvidenceIntegrityError, NoBinaryOpenError, } from "../domain/errors.js";
 import { err, ok } from "../domain/result.js";
-import { analysisQueryId, createAnalysisSnapshotEntry, snapshotBinding, snapshotMatchesProfile, snapshotMatchesTarget, snapshotTarget, } from "../domain/analysisSnapshot.js";
+import { analysisQueryId, createAnalysisSnapshotEntry, snapshotBinding, snapshotMatchesProfile, snapshotMatchesTarget, snapshotTarget, parseAnalysisSnapshot, } from "../domain/analysisSnapshot.js";
 import { GENERATED_MCP_TOOL_CATALOG } from "../generatedMcpToolCatalog.js";
 const STATEFUL_OPERATIONS = new Set([
     "health",
@@ -75,21 +75,40 @@ export class AnalysisSnapshotCache {
     export(target, profile, evidenceBundle) {
         if (target === undefined || profile === undefined)
             return err(new NoBinaryOpenError());
-        return ok({
-            target: snapshotTarget(target),
-            binding: snapshotBinding(profile),
-            entries: this.entries(),
-            evidence_bundle: structuredClone(evidenceBundle),
-        });
+        try {
+            const snapshotTargetIdentity = snapshotTarget(target);
+            const binding = snapshotBinding(profile);
+            const retainedEvidence = structuredClone(evidenceBundle);
+            return ok(parseAnalysisSnapshot({
+                target: snapshotTargetIdentity,
+                binding,
+                entries: this.entries(),
+                evidence_bundle: retainedEvidence,
+            }));
+        }
+        catch (cause) {
+            return err(new EvidenceIntegrityError("Analysis snapshot validation failed", {
+                cause,
+            }));
+        }
     }
     /** Validate target identity, merge evidence atomically, then stage entries. */
     import(snapshot, active, mergeEvidence) {
+        let validated;
+        try {
+            validated = parseAnalysisSnapshot(snapshot);
+        }
+        catch (cause) {
+            return err(new EvidenceIntegrityError("Analysis snapshot validation failed", {
+                cause,
+            }));
+        }
         if (active !== undefined &&
-            (!snapshotMatchesTarget(snapshot.target, active.target) ||
-                !snapshotMatchesProfile(snapshot.binding, active.profile)))
+            (!snapshotMatchesTarget(validated.target, active.target) ||
+                !snapshotMatchesProfile(validated.binding, active.profile)))
             return err(new EvidenceIntegrityError("Analysis snapshot profile_mismatch: target, provider, or analysis profile does not match the active binary"));
-        const importedEvidence = mergeEvidence(snapshot.evidence_bundle);
-        return importedEvidence.ok ? ok(this.stage(snapshot)) : importedEvidence;
+        const importedEvidence = mergeEvidence(validated.evidence_bundle);
+        return importedEvidence.ok ? ok(this.stage(validated)) : importedEvidence;
     }
     /** Return canonical entries for persistence. */
     entries() {