rea-agents 0.2.1 → 0.4.0

package/README.md

@@ -10,15 +10,15 @@
 
 [![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)
-[![50 MCP tools](https://img.shields.io/badge/MCP_tools-50-5c4ee5?style=flat-square)](#50-tools-for-investigation)
+[![68 MCP tools](https://img.shields.io/badge/MCP_tools-68-5c4ee5?style=flat-square)](#68-tools-for-investigation)
 [![Node.js 24](https://img.shields.io/badge/Node.js-24.18.x-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) · [50 tools](#50-tools-for-investigation) · [Roadmap](#roadmap) · [How it works](#how-it-works)
+[Quick start](#quick-start) · [Current status](#current-status) · [Investigation model](#the-investigation-model) · [68 tools](#68-tools-for-investigation) · [Roadmap](#roadmap) · [How it works](#how-it-works)
 
 <br />
 
-<code>npx skills add morluto/rea</code>
+<code>curl -fsSL https://raw.githubusercontent.com/morluto/rea/main/install.sh | bash</code>
 
 </div>
 
@@ -41,8 +41,8 @@ npx skills add morluto/rea
 Then ask:
 
 ```text
-Set up REA and reverse engineer the Notes app. Explain how search works,
-show me how you know, and build a similar feature for my project.
+Use REA to understand how search works in the Notes app, show me the
+evidence, and build a similar feature for my project.
 ```
 
 Notes is only an example. Name any app you want to understand, or ask the agent to start with an overview.
@@ -81,6 +81,16 @@ REA shows how it reached its conclusions. It does not claim to recover original
 
 ## Quick start
 
+### One-command install — recommended
+
+```bash
+curl -fsSL https://raw.githubusercontent.com/morluto/rea/main/install.sh | bash
+```
+
+The installer supports macOS 12+, Ubuntu 24.04+, Fedora 41+, and 64-bit Arch Linux. It installs compatible Node.js 24/npm 11 prerequisites, the exact latest `rea-agents-*` release, the official Hopper package, detected client registrations, and the bundled skill, then verifies the result. macOS uses Homebrew; Linux uses the native package manager and may show a system authorization prompt. Pin a reproducible release with `REA_VERSION=0.3.0`; `REA_VERSION` is the only supported installer environment override.
+
+REA detects Claude Code, Claude Desktop, Codex, Cursor, Gemini CLI, Windsurf, and Devin. It configures detected clients with documented local MCP files; Devin is reported as skipped because its public documentation does not define a local configuration file. You can safely rerun the installer or `rea setup --yes`. If REA's local analysis engine needs one-time activation, installation remains intact and setup reports the exact remaining action rather than claiming full readiness.
+
 ### With a coding agent — recommended
 
 ```bash
@@ -89,22 +99,36 @@ npx skills add morluto/rea
 
 Ask your agent to set up REA. It will check your Mac, explain anything it needs to install, ask for approval, and guide you through system prompts. After setup, restart the agent if it asks you to load the full REA toolset.
 
-### From Terminal
+Approve installation if needed, complete the one-time activation when prompted, then describe the app or feature you want to understand. REA handles the binary-analysis tools behind the scenes.
+
+### From Terminal — no installation
 
 ```bash
 npx -y rea-agents setup --yes
+npx -y rea-agents doctor
+npx -y rea-agents analyze /Applications/Notes.app
 ```
 
 If macOS or an installer asks for confirmation, complete the prompt and run the same command again. Restart a configured coding agent so it loads REA.
 
-### What setup handles
+### From Terminal — install the `rea` command
 
-- macOS 12 or newer
-- Node.js 24.18.x with npm 11.16.x (`nvm use` selects the pinned version)
+```bash
+npm install --global rea-agents
+rea setup --yes
+rea doctor
+rea analyze /Applications/Notes.app
+```
+
+Choose either the no-install commands or the global installation. You do not need both.
+
+### Requirements
 
-If process capture reports that its native PTY backend is unavailable, install Xcode command-line tools and run `npm run rebuild:native`. Linux source builds require Python, `make`, and a C++ toolchain. Compatible packaged binaries do not require this rebuild.
+- macOS 12 or newer
+- Ubuntu 24.04+, Fedora 41+, or 64-bit Arch Linux
+- Node.js 24.18.x with npm 11.16.x
 
-You do not need to install the reverse-engineering tools manually. Setup installs Homebrew and [Hopper](https://www.hopperapp.com/) when needed, configures detected Claude Desktop and Cursor installations, and installs the REA skill. Hopper is separate software and requires its own license; setup installs it but does not provide a license.
+You do not need to choose or install binary-analysis tools yourself. REA setup handles them when needed. Deep binary analysis currently uses [Hopper](https://www.hopperapp.com/), a separate desktop application with its own license. REA can install the official macOS or Linux package, but you must approve installation and complete its one-time activation.
 
 If something is not working, run:
 
@@ -112,12 +136,63 @@ If something is not working, run:
 npx -y rea-agents doctor
 ```
 
+`rea doctor --json` is read-only and distinguishes unsupported hosts, missing dependencies, a missing local analysis engine, configuration drift, and healthy checks. Fresh-install activation is reported by setup because Hopper does not expose a reliable noninteractive activation probe.
+
+### Linux installation and troubleshooting
+
+On Ubuntu 24.04+, Fedora 41+, and 64-bit Arch Linux, setup downloads the matching official Hopper package, restricts downloads to Hopper's public origin, verifies the published size and checksum, and invokes `apt-get`, `dnf`, or `pacman`. When REA is not already running as root, `pkexec` presents the system authorization prompt. REA never invokes `sudo`.
+
+The normal Linux launcher is `/opt/hopper/bin/Hopper`. If Hopper was installed elsewhere:
+
+```bash
+export HOPPER_LAUNCHER_PATH=/absolute/path/to/Hopper
+rea doctor --json
+```
+
+If doctor reports a missing analysis engine even though the file exists, inspect shared-library resolution with:
+
+```bash
+ldd /opt/hopper/bin/Hopper | grep 'not found'
+```
+
+Install the missing distribution packages and rerun `rea setup --yes`. Hopper is a desktop application: real analysis requires an active `DISPLAY` or `WAYLAND_DISPLAY`, plus one-time license activation. The curl installer places the `rea` command in `~/.local/bin` on Linux; add that directory to future shell `PATH` values if it is not already present.
+
+REA defaults `HOPPER_LAUNCHER_PATH` to `/Applications/Hopper Disassembler.app/Contents/MacOS/hopper` on macOS and `/opt/hopper/bin/Hopper` on Linux. Explicit configuration always takes precedence.
+
+To remove only REA-owned MCP registrations and the managed skill:
+
+```bash
+rea uninstall
+rea uninstall --purge-data # also removes only ~/.rea/cache and ~/.rea/state
+```
+
+Uninstall preserves Hopper, Homebrew, Node.js, evidence, captures, external evidence roots, unrelated skills, and other MCP servers. It refuses malformed client configuration and never follows purge-data symlinks.
+
 ### CLI or coding agent?
 
-| If you want to…                                           | Use                                        |
-| --------------------------------------------------------- | ------------------------------------------ |
-| Ask an agent to investigate an app and build a feature    | Install the skill, then talk to your agent |
-| Inspect or decompile one part of an app from the Terminal | `rea analyze` or `rea decompile`           |
+| If you want to…                                           | Use                                            |
+| --------------------------------------------------------- | ---------------------------------------------- |
+| Ask an agent to investigate an app and build a feature    | Install the skill, then talk to your agent     |
+| Inspect or decompile one part of an app from the Terminal | `rea analyze` or `rea decompile`               |
+| Validate or canonicalize an Evidence v2 bundle            | `rea evidence-import` or `rea evidence-export` |
+| Import source as historical reference                     | `rea import-reference-source`                  |
+
+Filesystem evidence commands and MCP file tools are disabled until the operator approves absolute roots:
+
+```bash
+export REA_EVIDENCE_ROOTS_JSON='["/absolute/path/to/evidence"]'
+rea evidence-import /absolute/path/to/evidence/bundle.json
+rea evidence-export /absolute/path/to/evidence/bundle.json /absolute/path/to/evidence/canonical.json
+```
+
+Historical source import requires a separate allowlist and never treats source as current behavioral authority:
+
+```bash
+export REA_REFERENCE_ROOTS_JSON='["/absolute/path/to/source"]'
+rea import-reference-source /absolute/path/to/source
+```
+
+Exports never replace an existing file unless `--overwrite` is explicit. Imports are size/depth bounded, validate every Evidence v2 ID and manifest, and never execute bundle content.
 
 ## One prompt, a full investigation
 
@@ -151,26 +226,38 @@ 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.
 
-## 50 tools for investigation
+## 68 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 |
-| Workspace and observation |     7 | target lifecycle, Evidence v2 bundle import/export, deterministic process capture and comparison                        |
+| 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      |
+| 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. Hopper currently implements the native-analysis capabilities; the process harness implements controlled behavioral capture. Future providers can satisfy the same capability without changing the agent's investigation workflow.
+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.
 
 ## Current status
 
 REA is already useful for native application investigation on macOS:
 
-- Open Mach-O, ELF, PE, `.app`, and Hopper database targets.
+- Open Mach-O, ELF, PE, `.app`, ZIP, APK, IPA, ASAR, plist, JavaScript, source-map, and Hopper database targets.
+- Traverse content-addressed artifact graphs without extraction; 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.
 - Record every successful result as deterministic Evidence v2 with artifact and provider identity, confidence, authority, limitations, and locations.
 - Export and import evidence bundles across sessions.
 - Capture approved PTY scenarios, child processes, filesystem changes, and loopback HTTP/WebSocket exchanges, then compare normalized captures.
+- Compare complete artifact inventories by stable path, content, metadata, and relations; incomplete evidence never implies equivalence.
+- Compare explicit function dossiers across text, calls, references, strings, and address-normalized CFG topology with per-facet unknowns.
+- Compare canonical Evidence bundles by exact membership, explicit observation pairs, and residual-unknown histories without turning omissions into behavioral absence.
+- Aggregate runtime comparisons into observed behavior changes while keeping static artifact/function differences labeled as candidates.
+- Build bounded, Evidence-cited direct call paths by exact address without treating missing dossiers as graph leaves.
+- Correlate exact static/runtime findings through explicit hypotheses without claiming causality from cochange.
+- Verify finite behavioral and structural reconstruction specifications with pass, fail, and unknown kept distinct.
+- Track residual unknowns through immutable CAS revisions, evidence-qualified resolution, contradictions, probes, and validated dependency relationships.
+- With explicit `unknown_registry_approved: true`, record bounded trace/capture residuals, typed provider unavailability, and capture disagreements automatically.
 
 Hopper is the first provider, not the boundary of the project. Some current workflows still require Hopper and macOS; every evidence record identifies the provider and limitations behind its result.
 
@@ -215,10 +302,14 @@ flowchart LR
     REA --> Workspace["Investigation workspace<br/>evidence + artifacts + captures"]
     Workspace --> Router["Capability router"]
     Router --> Hopper["Hopper provider"]
+    Router --> Native["Native macOS provider"]
+    Router --> Artifact["Artifact graph provider"]
     Router --> Process["Process capture provider"]
-    Router -. roadmap .-> More["Artifact, browser, dynamic,<br/>and additional static providers"]
+    Router -. roadmap .-> More["Browser, dynamic,<br/>and additional static providers"]
     Hopper --> Target["Target software"]
     Process --> Target
+    Native --> Target
+    Artifact --> Target
 ```
 
 The CLI and MCP server use the same application workflows and evidence contracts. A provider declares which capabilities it supports and the side effects those capabilities may have. Terminal commands are short-lived; an MCP session can retain an active target and evidence ledger across an investigation.
@@ -251,6 +342,19 @@ REA derives explicit format and architecture arguments to prevent common FAT and
 
 Closing a REA session shuts down its bridge and removes its private socket directory. It does not quit a Hopper application the user may be using.
 
+## Advanced process-capture setup
+
+Process capture is disabled by default. Enabling it requires
+`REA_PROCESS_CAPTURE_ENABLED=true`, approved executable and working roots in
+`REA_PROCESS_EXECUTABLE_ROOTS_JSON` and `REA_PROCESS_WORKING_ROOTS_JSON`, and an
+environment allowlist in `REA_PROCESS_ALLOWED_ENV_JSON`. Because the current PTY
+adapter uses host networking, it also requires
+`REA_PROCESS_ALLOW_EXTERNAL_NETWORK=true`.
+
+If the native PTY backend is unavailable, install Xcode command-line tools and
+run `npm run rebuild:native`. Linux source builds require Python, `make`, and a
+C++ toolchain. Compatible packaged binaries do not require this rebuild.
+
 ## Security model
 
 REA does not provide a hosted analysis service. Hopper communication uses an authenticated private local socket. Dynamic capabilities are disabled by default and require both operator policy and explicit per-call approval. REA is not a security sandbox: providers and launched targets run with the current user's permissions, and each capability reports its side effects and limitations. Report vulnerabilities through the private process in [SECURITY.md](SECURITY.md).

package/bridge/hopper_bridge.py

@@ -9,11 +9,15 @@ import json
 import hmac
 import os
 import re
+import sre_parse
 import socket
 
 MAX_LINE_BYTES = 10 * 1024 * 1024
 BAD_ADDRESSES = (-1, 0xFFFFFFFFFFFFFFFF, None)
 _selected_document = None
+_search_inventory_cache = {}
+MAX_SEARCH_PATTERN_LENGTH = 256
+MAX_SEARCH_VALUE_LENGTH = 4096
 
 
 def _hex(value):
@@ -89,6 +93,17 @@ def _procedure_identity(procedure):
     return {"address": _hex(procedure.getEntryPoint()), "name": _procedure_name(procedure)}
 
 
+def _procedure_locals(procedure):
+    """Project opaque Hopper local-variable objects into an exact public shape."""
+    return [
+        {
+            "description": str(local),
+            "provenance": "hopper-public-python-api",
+        }
+        for local in procedure.getLocalVariableList()
+    ]
+
+
 def _containing_procedure(document, address):
     segment = document.getSegmentAtAddress(address)
     if segment is None:
@@ -182,6 +197,105 @@ def _strings(document):
     return result
 
 
+def _invalidate_search_inventory(document):
+    """Discard derived names after analysis metadata changes."""
+    document_id = id(document)
+    for key in list(_search_inventory_cache):
+        if key[0] == document_id:
+            del _search_inventory_cache[key]
+
+
+def _search_inventory(document, kind):
+    """Cache an immutable, address-sorted inventory for an unchanged document."""
+    key = (id(document), kind)
+    inventory = _search_inventory_cache.get(key)
+    if inventory is None:
+        values = _procedure_map(document) if kind == "procedure" else _strings(document)
+        inventory = tuple(sorted(values.items(), key=lambda item: int(item[0], 16)))
+        _search_inventory_cache[key] = inventory
+    return inventory
+
+
+def _validate_regex_node(node, inside_repeat=False):
+    """Reject regex structures with disproportionate or non-local evaluation cost."""
+    forbidden = {
+        sre_parse.ASSERT,
+        sre_parse.ASSERT_NOT,
+        sre_parse.GROUPREF,
+        sre_parse.GROUPREF_EXISTS,
+    }
+    repeat_tokens = {sre_parse.MAX_REPEAT, sre_parse.MIN_REPEAT}
+    possessive = getattr(sre_parse, "POSSESSIVE_REPEAT", None)
+    if possessive is not None:
+        repeat_tokens.add(possessive)
+    for operation, argument in node:
+        if operation in forbidden:
+            raise ValueError("Regex lookarounds and backreferences are not supported")
+        if operation in repeat_tokens:
+            if inside_repeat:
+                raise ValueError("Nested regex repetitions are not supported")
+            minimum, maximum, child = argument
+            if maximum == sre_parse.MAXREPEAT or maximum > 1000:
+                raise ValueError("Unbounded or excessive regex repetitions are not supported")
+            _validate_regex_node(child, True)
+        elif operation == sre_parse.SUBPATTERN:
+            _validate_regex_node(argument[-1], inside_repeat)
+        elif operation == sre_parse.BRANCH:
+            for branch in argument[1]:
+                _validate_regex_node(branch, inside_repeat)
+
+
+def _search_page(document, kind, params):
+    pattern = params.get("pattern")
+    if not isinstance(pattern, str) or not pattern or len(pattern) > MAX_SEARCH_PATTERN_LENGTH:
+        raise ValueError("pattern must contain between 1 and 256 characters")
+    mode = params.get("mode", "literal")
+    if mode not in ("literal", "regex"):
+        raise ValueError("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")
+    offset = params.get("offset", 0)
+    limit = params.get("limit", 100)
+    if not isinstance(offset, int) or isinstance(offset, bool) or offset < 0:
+        raise ValueError("offset must be a non-negative integer")
+    if not isinstance(limit, int) or isinstance(limit, bool) or limit < 1 or limit > 100:
+        raise ValueError("limit must be an integer between 1 and 100")
+
+    if mode == "literal":
+        needle = pattern if case_sensitive else pattern.casefold()
+        matches = lambda value: needle in (value if case_sensitive else value.casefold())
+    else:
+        try:
+            parsed = sre_parse.parse(pattern)
+            _validate_regex_node(parsed)
+            expression = re.compile(pattern, 0 if case_sensitive else re.IGNORECASE)
+        except re.error as error:
+            raise ValueError("Invalid regex pattern") from error
+        matches = lambda value: expression.search(value) is not None
+
+    matching = [item for item in _search_inventory(document, kind) if matches(item[1])]
+    selected = matching[offset:offset + limit]
+    total = len(matching)
+    next_offset = offset + len(selected)
+    has_more = next_offset < total
+    return {
+        "items": [
+            {
+                "address": address,
+                "value": value[:MAX_SEARCH_VALUE_LENGTH],
+                "value_truncated": len(value) > MAX_SEARCH_VALUE_LENGTH,
+            }
+            for address, value in selected
+        ],
+        "offset": offset,
+        "limit": limit,
+        "total": total,
+        "next_offset": next_offset if has_more else None,
+        "has_more": has_more,
+    }
+
+
 def _page(values, offset, limit):
     """Return one deterministically address-sorted page without crossing an unbounded map."""
     if not isinstance(offset, int) or isinstance(offset, bool) or offset < 0:
@@ -354,7 +468,7 @@ def _analyze_function(document, params):
     def collection(name, items, scan_limited=False):
         return _bounded(items, _collection_offset(params, name), limit, None, scan_limited)
     return {
-        "procedure": {"address": _hex(procedure.getEntryPoint()), "name": _procedure_name(procedure), "signature": procedure.signatureString(), "locals": _json_safe(procedure.getLocalVariableList())},
+        "procedure": {"address": _hex(procedure.getEntryPoint()), "name": _procedure_name(procedure), "signature": procedure.signatureString(), "locals": _procedure_locals(procedure)},
         "pseudocode": {"text": pseudo_text, "total_chars": len(pseudo), "returned_chars": len(pseudo_text), "truncated": pseudo_next < len(pseudo), "next_offset": pseudo_next if pseudo_next < len(pseudo) else None},
         "assembly": _bounded(assembly_lines, assembly_offset, max_instructions),
         "comments": collection("comments", comments, instruction_scan_truncated),
@@ -372,7 +486,7 @@ def _dispatch(method, params):
     """Dispatch only the closed operation set implemented by REA's public tools."""
     global _selected_document
     if method == "health":
-        return {"name": "REA Hopper bridge", "version": "1.0.0"}
+        return {"name": "REA Hopper bridge", "version": "1.0.0", "run_id": REA_RUN_ID}
     if method == "shutdown":
         return {"shutdown": True}
     if method == "list_documents":
@@ -426,18 +540,30 @@ def _dispatch(method, params):
         return _hex(result)
     if method == "list_segments":
         result = []
+        permission_limitation = _unavailable(
+            "Hopper's public Python API does not expose segment or section permissions"
+        )
         for segment in document.getSegmentsList():
             start = segment.getStartingAddress()
-            sections = [{"name": section.getName(), "start": _hex(section.getStartingAddress()), "end": _hex(section.getStartingAddress() + section.getLength())} for section in segment.getSectionsList()]
+            sections = [{
+                "name": section.getName(),
+                "start": _hex(section.getStartingAddress()),
+                "end": _hex(section.getStartingAddress() + section.getLength()),
+                "readable": None,
+                "writable": None,
+                "executable": None,
+                "permissions": permission_limitation,
+                "provenance": "hopper-public-python-api",
+            } for section in segment.getSectionsList()]
             result.append({
                 "name": segment.getName(),
                 "start": _hex(start),
                 "end": _hex(start + segment.getLength()),
+                "readable": None,
                 "writable": None,
                 "executable": None,
-                "permissions": _unavailable(
-                    "Hopper's public Python API does not expose segment permissions"
-                ),
+                "permissions": permission_limitation,
+                "provenance": "hopper-public-python-api",
                 "sections": sections,
             })
         return result
@@ -461,10 +587,8 @@ def _dispatch(method, params):
             result = {key: result[key]} if key in result else {}
         return _page(result, params.get("offset", 0), params.get("limit", 100))
     if method in ("search_procedures", "search_strings"):
-        flags = 0 if params.get("case_sensitive", False) else re.IGNORECASE
-        expression = re.compile(params["pattern"], flags)
-        values = _procedure_map(document) if method == "search_procedures" else _strings(document)
-        return {key: value for key, value in values.items() if expression.search(value)}
+        kind = "procedure" if method == "search_procedures" else "string"
+        return _search_page(document, kind, params)
     if method.startswith("procedure_"):
         procedure = _procedure(document, params.get("procedure"))
         if method == "procedure_address":
@@ -480,12 +604,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.getLocalVariableList()}
+            return {"name": _procedure_name(procedure), "entrypoint": _hex(procedure.getEntryPoint()), "basicblock_count": procedure.getBasicBlockCount(), "length": length, "signature": procedure.signatureString(), "locals": _procedure_locals(procedure)}
     if method == "set_address_name":
         address = _address(document, params.get("address"))
-        return document.setNameAtAddress(address, params["name"])
+        result = document.setNameAtAddress(address, params["name"])
+        _invalidate_search_inventory(document)
+        return result
     if method == "set_addresses_names":
-        return {key: document.setNameAtAddress(_address(document, key), value) for key, value in params["names"].items()}
+        result = {key: document.setNameAtAddress(_address(document, key), value) for key, value in params["names"].items()}
+        _invalidate_search_inventory(document)
+        return result
     if method in ("set_comment", "set_inline_comment"):
         address = _address(document, params.get("address"))
         segment = _segment(document, address)

package/dist/application/AnalysisProvider.js

@@ -1 +1,12 @@
-export {};
+import { jsonValueSchema } from "../domain/jsonValue.js";
+/** Build a validated atomic provider observation at an adapter boundary. */
+export const createAnalysisExecution = (result, provider, options = {}) => ({
+    result: jsonValueSchema.parse(result),
+    rawResult: options.rawResult === undefined
+        ? jsonValueSchema.parse(result)
+        : jsonValueSchema.parse(options.rawResult),
+    provider,
+    limitations: [...(options.limitations ?? [])],
+    locations: [...(options.locations ?? [])],
+    subject: options.subject ?? null,
+});

package/dist/application/ArtifactExtraction.js

@@ -0,0 +1,166 @@
+import { lstat, realpath } from "node:fs/promises";
+import { AsarArtifactReader } from "../artifacts/AsarArtifactReader.js";
+import { ArtifactPathRegistry, normalizeArtifactPath, } from "../artifacts/ArtifactPaths.js";
+import { ArtifactReaderFailure, } from "../artifacts/ArtifactReader.js";
+import { DirectoryArtifactReader } from "../artifacts/DirectoryArtifactReader.js";
+import { SafeOutputTree } from "../artifacts/SafeOutputTree.js";
+import { ZipArtifactReader } from "../artifacts/ZipArtifactReader.js";
+import { MachOSliceArtifactReader } from "../artifacts/MachOSliceArtifactReader.js";
+import { artifactExtractionResultSchema, } from "../domain/artifactGraph.js";
+import { scanArtifactInventory } from "./ArtifactInventory.js";
+import { digestCanonical, pageOf, toOutputLimits, } from "./ArtifactGraphConstruction.js";
+const PAGE_SIZE = 500;
+/** Extract selected inventory occurrences into an exclusively owned absent root. */
+export const extractArtifact = async (input, signal) => {
+    validateSelection(input.occurrenceIds);
+    const sourcePath = await realpath(input.inputPath);
+    const selectedIds = new Set(input.occurrenceIds);
+    const inventory = await loadInventory(sourcePath, input.limits, selectedIds, signal);
+    const selected = input.occurrenceIds.map((id) => {
+        const occurrence = inventory.occurrences.get(id);
+        if (occurrence === undefined)
+            throw new ArtifactReaderFailure("unavailable", `Selected artifact occurrence was not found: ${id}`);
+        if ((occurrence.entry_kind !== "file" && occurrence.entry_kind !== "slice") ||
+            occurrence.artifact_id === null ||
+            occurrence.encrypted ||
+            occurrence.logical_path === ".")
+            throw new ArtifactReaderFailure("format", `Selected occurrence is not an extractable regular child file: ${id}`);
+        const node = inventory.nodes.get(occurrence.artifact_id);
+        if (node === undefined)
+            throw new ArtifactReaderFailure("integrity", `Selected occurrence has no inventory node: ${id}`);
+        return { occurrence, node };
+    });
+    return materializeSelection({
+        input,
+        sourcePath,
+        inventory,
+        selected,
+        signal,
+    });
+};
+const materializeSelection = async ({ input, sourcePath, inventory, selected, signal, }) => {
+    const byPath = new Map(selected.map((item) => [item.occurrence.logical_path, item]));
+    const reader = await createReader(sourcePath, input.inputFormat);
+    const output = await SafeOutputTree.create(input.outputRoot, input.limits);
+    let readerClosed = false;
+    const extracted = [];
+    try {
+        const found = new Set();
+        const registry = new ArtifactPathRegistry();
+        let entryCount = 0;
+        for await (const entry of reader.entries(signal)) {
+            entryCount += 1;
+            if (entryCount > input.limits.maxEntries)
+                throw new ArtifactReaderFailure("limit", "Artifact entry limit exceeded during extraction");
+            const path = normalizeArtifactPath(entry.path, input.limits);
+            registry.add(path, entry.kind);
+            const selectedItem = byPath.get(path);
+            if (selectedItem === undefined)
+                continue;
+            preflight(entry, input.limits);
+            const stream = await reader.open(entry, signal);
+            const written = await output.write(path, stream, selectedItem.node.sha256, signal);
+            extracted.push({
+                artifact_id: selectedItem.node.artifact_id,
+                relative_path: written.relativePath,
+                sha256: written.sha256,
+                bytes_written: written.bytesWritten,
+                created: true,
+            });
+            found.add(path);
+        }
+        if (found.size !== selected.length)
+            throw new ArtifactReaderFailure("integrity", "Selected inventory occurrence disappeared before extraction");
+        await reader.close();
+        readerClosed = true;
+        extracted.sort((left, right) => left.relative_path.localeCompare(right.relative_path, "en"));
+        const result = createExtractionResult(input, inventory, selected, extracted);
+        await output.commit();
+        return result;
+    }
+    catch (cause) {
+        if (!readerClosed)
+            await reader.close().catch(() => undefined);
+        await output.rollback();
+        throw cause;
+    }
+};
+const createExtractionResult = (input, inventory, selected, extracted) => {
+    const extractionSemantic = {
+        schema_version: 1,
+        source_manifest_id: inventory.manifest.manifest_id,
+        selected_occurrence_ids: selected
+            .map(({ occurrence }) => occurrence.occurrence_id)
+            .sort((left, right) => left.localeCompare(right)),
+        files_sha256: digestCanonical(extracted),
+        output_root_alias: "$OUTPUT_ROOT",
+    };
+    return artifactExtractionResultSchema.parse({
+        manifest: inventory.manifest,
+        extraction_manifest: {
+            ...extractionSemantic,
+            extraction_id: `aex_${digestCanonical(extractionSemantic)}`,
+        },
+        output_root: "$OUTPUT_ROOT",
+        artifacts: pageOf(extracted, input.offset, input.limit),
+        containment_verified: true,
+        cleanup: { attempted: false, verified: true, residual_paths: [] },
+        limits: toOutputLimits(input.limits),
+        provenance: [],
+        limitations: [
+            "Only caller-selected regular file occurrences were materialized.",
+        ],
+    });
+};
+const loadInventory = async (path, limits, selectedIds, signal) => {
+    const snapshot = await scanArtifactInventory(path, limits, signal);
+    const occurrences = new Map();
+    const neededNodes = new Set();
+    collectOccurrences(snapshot.occurrences, selectedIds, occurrences, neededNodes);
+    const nodes = new Map();
+    collectNodes(snapshot.nodes, neededNodes, nodes);
+    return { manifest: snapshot.manifest, occurrences, nodes };
+};
+const collectOccurrences = (items, selected, output, neededNodes) => {
+    for (const item of items) {
+        if (!selected.has(item.occurrence_id))
+            continue;
+        output.set(item.occurrence_id, item);
+        if (item.artifact_id !== null)
+            neededNodes.add(item.artifact_id);
+    }
+};
+const collectNodes = (items, selected, output) => {
+    for (const item of items)
+        if (selected.has(item.artifact_id))
+            output.set(item.artifact_id, item);
+};
+const createReader = async (path, format) => {
+    if ((await lstat(path)).isDirectory())
+        return new DirectoryArtifactReader(path);
+    if (format === "asar")
+        return new AsarArtifactReader(path);
+    if (format === "ipa" || format === "apk" || format === "zip")
+        return new ZipArtifactReader(path, format);
+    if (format === "mach-o")
+        return new MachOSliceArtifactReader(path);
+    throw new ArtifactReaderFailure("unavailable", `Artifact format has no extraction reader: ${format}`);
+};
+const validateSelection = (ids) => {
+    if (ids.length === 0 || ids.length > PAGE_SIZE)
+        throw new ArtifactReaderFailure("limit", "Extraction requires 1 to 500 explicitly selected occurrences");
+    if (new Set(ids).size !== ids.length)
+        throw new ArtifactReaderFailure("path", "Extraction occurrence selection contains duplicates");
+};
+const preflight = (entry, limits) => {
+    if ((entry.kind !== "file" && entry.kind !== "slice") || entry.encrypted)
+        throw new ArtifactReaderFailure("format", `Selected artifact entry cannot be read: ${entry.path}`);
+    if (entry.declaredSize !== null && entry.declaredSize > limits.maxEntryBytes)
+        throw new ArtifactReaderFailure("limit", `Selected artifact exceeds byte limit: ${entry.path}`);
+    if (entry.declaredSize !== null &&
+        entry.compressedSize !== null &&
+        (entry.compressedSize === 0
+            ? entry.declaredSize > 0
+            : entry.declaredSize / entry.compressedSize > limits.maxCompressionRatio))
+        throw new ArtifactReaderFailure("limit", `Selected artifact exceeds compression ratio limit: ${entry.path}`);
+};