Compare commits

..
Author SHA1 Message Date
Kaoru0822 b180055aab feat(setup): expose explicit MCP catalog profile selection 2026-11-08 05:32:12 -08:00
613 changed files with 4378 additions and 18454 deletions

No files matched your search

@@ -1,8 +1,8 @@
---
name: reverse-engineer-anything
description: Reverse engineer native, managed, Electron/JavaScript, packaged, firmware, and browser targets with REA, and build agent environments (AgentEnv bundles) of web applications from a live instance or a capture, and of Linux desktop apps with a task from a request. Use shipped-artifact or requested runtime evidence to explain features, compare versions, decompile code, or guide a reconstruction. Skip REA for ordinary source-repository architecture analysis.
description: Reverse engineer native, managed, Electron/JavaScript, packaged, firmware, and browser targets with REA, and build agent environments (AgentEnv bundles) of web applications from a live instance or a capture. Use shipped-artifact or requested runtime evidence to explain features, compare versions, decompile code, or guide a reconstruction. Skip REA for ordinary source-repository architecture analysis.
metadata:
version: "61"
version: "60"
---
# REA
@@ -140,10 +140,6 @@ explicit path or endpoint and do not need it.
- Task for a desktop application's exported environment, from a
`capture-desktop-application` folder: read
[desktop application tasks](references/environments.md#tasks-for-a-desktop-application-environment).
- Environment of a Linux desktop app with a task, from a request such as
"build me an Inkscape environment where the agent changes a poster's
headline": read [desktop builds](references/desktop-build.md). You drive the
app on a build computer from `start_build_computer`, then export and witness.
- Fiddler Everywhere traffic or a native `.saz` capture: read the
[Fiddler workflow](references/runtime-observation.md#fiddler-everywhere-traffic-debugging).
Inspect saved SAZ with `inspect_web_network_capture` and `format: "saz"`;
@@ -214,15 +210,11 @@ explicit path or endpoint and do not need it.
`parent_evidence_id` for exact function or `bytecode_hex`/stdout/stderr pages.
Candidate coverage does not establish interface completeness. See the
[EVM bytecode guide](https://github.com/morluto/rea/blob/main/docs/guides/evm/evm-bytecode.md).
- Embedded Go compiler, module, build-setting metadata, or static `(ptr, len)`
string literals: `inspect_go_binary` with the explicit local file (pass
`include_string_literals: true` and optional `max_string_literals` for bounded
inferred static string-header recovery, and page retained rows with
`inspect_analysis_view` kind `go` collection `string_literals`). This built-in
target-free inspection requires no Go installation or disassembler. Preserve
raw module bytes and source ranges; absent metadata does not prove a binary is
not Go, static string recovery excludes compiler-inlined stack or immediate
strings, and unparsed text records remain explicit. See the
- Embedded Go compiler, module or build-setting metadata: `inspect_go_binary`
with the explicit local file. This built-in target-free inspection requires no
Go installation or disassembler. Preserve raw module bytes and source ranges;
absent metadata does not prove a binary is not Go, and unparsed text records
remain explicit. See the
[Go binary guide](https://github.com/morluto/rea/blob/main/docs/guides/native/go-binaries.md).
- Embedded CUDA/HIP code objects: `inspect_gpu_code_objects`; inventory targets
first, then decode selected payloads and query retained GPU Evidence.
@@ -547,8 +539,6 @@ as complete while required questions remain open.
[references/environments.md](references/environments.md)
- Tasks for a desktop application's exported environment:
[references/environments.md](references/environments.md#tasks-for-a-desktop-application-environment)
- A desktop app environment from a request, built and witnessed on build
computers: [references/desktop-build.md](references/desktop-build.md)
## Finish the task
@@ -1,294 +0,0 @@
# Desktop app environments from a request
Use this when someone asks for an environment of a Linux desktop app with a
task, such as "Build me an Inkscape environment where the agent changes a
poster's headline and saves it". You are the building agent: you drive the
app on a build computer through REA's MCP tools, write the task, export the
bundle and witness it in a fresh computer. REA runs no model. The tools are
MCP-only and need Docker, `REA_AGENT_ENV_COMMAND` and
`REA_BUILD_COMPUTER_REA_ARCHIVE` where the REA server starts; when a start
reports one missing, tell the person what to set and stop.
For the whole build:
- Drive the app only with `act_on_build_computer`. Never script it, run
commands in the computer or write its files another way.
- Ask the upfront questions once, then work on your own. Pause only when
blocked.
- The seed's content is synthetic. Never put real personal data in it.
- Close every computer you start, on success and on failure.
- Note the time you start; the report gives the build time.
## Ask once, upfront
In one message, ask only what the request leaves open, and keep the list for
the report:
1. The app and the task, if either is unclear: what changes, in which
document.
2. Whether they have a starting file of their own; otherwise you make one.
3. Whether they want solver runs after the witness: how many (the budget)
and with which model.
4. If so, whether they want to review the task before those runs.
## When you are blocked
Stop, say what you need and wait only for:
- a licence the app or its installer asks someone to accept: never accept it
yourself; name it and where to read it, and go on only once the person
says they accept it;
- credentials: they may only be typed as handles you never see, and the
build tools have none yet, so say the app needs a sign-in and stop. Never
ask for a password in chat;
- a signed-in state in the seed: ask before seeding one;
- an install this flow cannot do, below.
Decide everything else yourself and note it in the report.
## Choose the install
The computer is Ubuntu 24.04 (noble) on this host's architecture only. Use
the first source that has the app:
| Source | `install` |
| ---------------------------- | --------------------------------------------------------------------------------- |
| Ubuntu archive | `{"kind": "archive", "package": "inkscape"}` |
| PPA or vendor apt repository | `{"kind": "apt_repository", "package", "uri", "suite", "components", "key_file"}` |
| `.deb` by URL | `{"kind": "package_file", "url", "sha256", "architecture", "dependencies"}` |
- A PPA's `uri` is `https://ppa.launchpadcontent.net/OWNER/NAME/ubuntu`,
`suite` `noble`, `components` `["main"]`. `key_file` is the repository's
signing key saved on this host; for a PPA, fetch it from
keyserver.ubuntu.com by the fingerprint its Launchpad page shows.
- For a `.deb`, ask the requester for its URL and SHA-256; do not fetch a
vendor's download page yourself. List its `Depends` as `dependencies`:
it installs with the network off.
- Flatpak, AppImage and snaps are not supported yet: say so and stop. An
archive package that only installs a snap, such as noble's `firefox`,
counts as a snap. A package with no build for this host's architecture
(some PPAs are amd64 only) cannot be installed either.
- `desktop_entry` is the package's `.desktop` file name under
`/usr/share/applications` without `.desktop`, such as
`org.inkscape.Inkscape`. Add `window_class` when you know it; Inkscape's
is `Inkscape`. AbiWord's entry is `abiword` and its class `Abiword`.
## Drive the app
- Pass `computer_id` and the action's fields at the top level: click
`{x, y, count}`, scroll `{x, y, direction, amount}`, a screenshot region
`[x0, y0, x1, y1]`. The rest are in
[the build-computer guide](https://github.com/morluto/rea/blob/main/docs/desktop-build-computer.md).
- Take a `screenshot` before pointing: points are pixels of the latest
frame. If a response is too large, ask for a `region`, or `jpeg` with a
lower `quality`. A region crops the latest frame and becomes it: take a
full screenshot before pointing again.
- A drawn caret does not prove keyboard focus. After using a toolbar
control, click into the document, then type a few characters and look
before a long text.
- Confirm a dialog with `key` Return, not a trailing `\n` in `type`.
- An action's own screenshot is taken at once. After opening a menu, a
dialog or a window, look with
`{"action": "wait", "ms": 500, "screenshot": true}`.
- On a computer started from a request the app is not open at first, and
`start_build_capture` opens it: never open it yourself before that. Do not
close it while capturing; the capture ends when the app exits. When the
app is closed at any other time, open it from Applications → Other → the
environment's name.
- Prefer shortcuts and typing to long pointer paths: `key` takes `keys`, an
array holding one chord's keys, such as
`{"action": "key", "keys": ["ctrl", "s"]}`, and `type` turns `\n` into
Enter.
- Before `type`, check in a screenshot that a text cursor or a focused
field is there. In apps with single-key shortcuts, such as Inkscape, text
typed without one runs as commands.
- Save As opens in the home: click Documents in its sidebar and type only
the file name. Answer the app's save questions, such as keeping the
format, then check the saved path in the title or status bar, or the
dialog's folder when the app shows only the name, and that it shows no
unsaved mark, before you mark a checkpoint or check.
- What the app saved under the home before `seed`, such as a document in
`~/Documents` or its settings, is part of the seed. A file you move to the
Trash is left out, and the export lists it in `limitations`. Trash a stray
file rather than starting over.
- Dismiss first-run dialogs, such as a welcome screen, before `seed`. A
choice the app saves only later, such as Inkscape's "show this every
time", may not reach the seed, so expect the dialog in the witness too.
- Give what the task changes a stable name where the app has one, such as an
id in Inkscape's Object Properties, so a check can select it.
- Expect apps to split text into runs: Writer's revision ids split an
edited paragraph into spans and may give it an automatic style such as
`P1`, and AbiWord wraps each insertion in `<c>`. Check such text whole
with `text_equals` (see Write the task), and find the paragraph by
something the edit keeps, such as AbiWord's `xid`.
## Build the seed and the edit
1. `start_build_computer` with
`{"source": {"kind": "request", "desktop_entry": ..., "install": ...}}`.
The first start of an app builds its image and can take minutes. A
failed start returns the build's error: fix the request, or stop when the
install cannot work, and close any `computer_id` the error names.
2. `start_build_capture`. It returns once the app's window is open. A
`package_lists_error` may stop the capture finding the package's
sources; the export says when that matters.
3. Make the seed through the app and save it from the app under
`~/Documents`: build the document in the app, or write its source where
the app edits its format as text, then save it again from the app. Make
it look real but synthetic: the thing the task changes, plus a few things
the change must leave alone. Keep it to one document: the bundle's app
opens the seed's document at launch only when there is exactly one, and
otherwise starts on its own screen. For a starting file of the requester's,
read it here and rebuild it in the app with synthetic data in place of
personal data; REA cannot copy a file into the computer.
4. Only once the seed is saved, `mark_build_checkpoint` with name `seed`.
5. Make the change the task asks for, as a user would, and save it.
6. Only once the change is saved, `mark_build_checkpoint` with name `end`.
7. `stop_build_capture`. Read `draft.files` (each file that changed, with
its net change), `draft.task.checks` (suggested checks) and
`limitations`. When `draft` is null, read `draft_refusal` first: a
missing `seed` or `end` checkpoint means capturing again on a new build
computer, while a failed draft command names its own cause to fix.
## Write the task
Write `{"name", "prompt", "checks"}` from the draft and what you did.
- `name`: lowercase letters, digits and hyphens, not `smoke`.
- `prompt`: what the requester wants, in their words and the app's terms,
naming the document as a user would and ending with saving it: "Change the
poster's headline in Documents/poster.svg to Summer Bake Sale and save
it." Never say how the file stores it, and never give the checks.
- Checks are file-based: content checks that prove the edit, never only that
a file exists or changed. Start from the suggestions; keep those that say
what the user did and drop what follows from how the app saves.
- Compare exact values, so a typo or a wrong number fails.
- Select elements by what they hold, never by position: SVG text by id,
`/root/children/[name=g][@inkscape:label=Layer 1]/children/[name=text][@id=headline]/children/[name=tspan]/children/0`,
or an ODF paragraph by style,
`/entries/[name=content.xml]/view/root/children/[name=office:body]/children/[name=office:text]/children/[name=text:p][@text:style-name=Title]/children/0`.
A selector must match exactly one element, so give the target a unique id
or style in the seed. The draft may suggest positional pointers; rewrite
them. Only an element's text is read by position, as `children/0`.
- When an app may split an element's text into runs, check it whole:
`text_equals` (or `text_contains` for a value inside a sentence) on the
element compares all its text, however it is split. Add
`normalize_whitespace: true` when the app may reflow spaces. Example, an
AbiWord paragraph by its stable id:
`{"kind": "text_contains", "file": "Documents/memo.abw", "pointer": "/root/children/[name=section]/children/[name=p][@xid=6]", "value": "at 3:30 PM"}`.
Point a text check at the paragraph or another element the edit keeps,
never at a run such as AbiWord's `[name=c]`: a reopened document splits
the text into several runs. The draft lists only what changed; to name an
unchanged element, such as another paragraph's `xid`, use the app's usual
numbering and let the export confirm it, or read it in the exported
bundle's `envs/<env>/seed/`.
- Where easy, add one check that the rest is untouched, such as another
text's value the edit must leave alone. It is the one unchanged value
worth checking; it passes on the seed too, which is fine, since the export
needs only one check to fail there.
- Give `value_equals` a `tolerance` for a number the app writes as text.
- When the draft shows an XML document's changes as `lines`, REA read it
as text, for example because its DOCTYPE declares entities. Selectors are
impossible there, and `line_count` with `contains` only approximates a
value: `3:30` also matches `13:30`. Bound it with neighbouring text and
name the check as approximate in the report's limitations.
- Some apps save a document reloaded from disk differently from one typed
in the same session: AbiWord wraps each new insertion in its own markup.
Your build's end state hides this, which is why whole-text checks matter;
expect the witness to show the real format.
The kinds and pointer rules are in
[the desktop tasks section](environments.md#pick-the-checks).
## Export
`export_build_environment` with `task` and `directory`, the absolute path of
a new or empty folder here, such as `<home>/rea-builds/poster/bundle`. The
export seeds what was saved at `seed`, replaces the computer's host name,
`user@host` and home path (a bare user name, such as AbiWord's author
`user`, stays), and checks the task against `seed` and `end`. It refuses a task
unless at least one check fails on the seed and every check passes at the
end, and says why, such as a pointer that names nothing at the end. A
check that the rest is untouched passes on the seed too, which is fine. On
a refusal, fix the task and export again, into another folder if that one
is no longer empty. Keep
`seed_files`, `scrubbed_files`, `unscrubbed_files` and `limitations` for the
report.
Keep the build computer open until the witness holds: a task fix exports
again from it.
## Witness
Witness in a fresh computer of the bundle, from the prompt, as a solving
agent would. Do not replay the build's actions or coordinates, and do not
check between stages to steer the edit: a solving agent never sees the
checks. Give every `check_build_task` the task exactly as exported.
1. `start_build_computer` with
`{"source": {"kind": "bundle", "path": "<bundle>"}}`. The app starts
with the seed's files in place and opens the seed's document when the
seed holds exactly one and the app takes a file. When the export's
`limitations` say it opens no document, open it from the prompt's path,
as a solving agent would. Take a `wait` screenshot first, since the
desktop may not have drawn yet.
2. `check_build_task` with `stage: "seed"` and `directory`, the absolute
path of a new or empty folder for the record. A check must fail.
Recording starts. Later stages take no `directory`.
3. Do the task from the prompt with `act_on_build_computer` and save.
`check_build_task` with `stage: "after_edit"`: every check must pass.
4. Make a near miss on top of it: a plausible wrong edit, such as a typo or
a wrong number, and save. `check_build_task` with `stage: "near_miss"`:
a check must fail.
5. `act_on_build_computer` with `action: "reset"`, then `check_build_task`
with `stage: "after_reset"`: a check must fail again.
6. The last stage ends the witness: `witness.record` has the verdict, the
path of `witness.json` and the recording's segments in `directory`.
`close_build_computer` on the witness computer.
A stage that does not hold ends the witness as `failed`. Read each check's
result and decide:
- `after_edit` failed though the saved file is right: the check is brittle.
Fix it, export again and witness in a new computer.
- `after_edit` failed because your edit was wrong: witness again in a new
computer; a computer is witnessed once.
- `near_miss` passed: the checks are too loose. Tighten them, export again
and witness again.
- `after_reset` passed: the reset did not restore the seed. Report it as a
limitation.
Stop after three witnesses and report what still fails.
## Solver runs
Only if the requester asked for them. If they wanted to review the task
first, show them its prompt and checks and wait for their approval. Then run
the bundle within the budget, one run at a time, with the runner
`REA_AGENT_ENV_COMMAND` names:
`agent-env run <bundle> --task <name> --agent claude-code --model <model>`.
Count runs reported `passed`. A run `scored below 1` is a miss; one reported
`failed` did not finish, so run it again if the budget allows instead of
counting it. Never run past the budget.
## Close and report
`close_build_computer` on every computer still open, also after a failure.
If a close fails, call it again; if it still fails, tell the requester what
is left.
Report:
- the bundle path and the environment name;
- the task's name and prompt;
- each check, and why it proves the edit and fails the near miss;
- each witness stage with its result, the verdict, and the paths of
`witness.json` and the recording;
- the seed's contents: `seed_files` and what each holds;
- `scrubbed_files` and `unscrubbed_files`; an unscrubbed file still names
the host or user, so it needs review before sharing;
- limitations: the capture's, the export's and anything you could not do;
- solver runs, if any: the model, the runs and the passes;
- the build time and the questions you asked.
Never publish or share the bundle yourself.
@@ -294,9 +294,7 @@ Use this when the user has a folder from `rea capture-desktop-application` and
wants a task for the environment `rea export-desktop-application` makes from
it: a prompt for a computer-use agent and checks that grade what the agent
left in the app's files. You write the prompt and the checks; REA validates
the task against the capture and exports it. These commands are CLI only. To
build the environment and its task from a request instead, follow
[desktop builds](desktop-build.md).
the task against the capture and exports it. These commands are CLI only.
### Describe the change
@@ -67,18 +67,11 @@ See [desktop installations](https://github.com/morluto/rea/blob/main/docs/deskto
Use `inspect_go_binary` for an explicit local ELF, PE or Mach-O (universal
files need `architecture`) when the
question concerns the embedded compiler version, module/dependency versions,
local replacements, build settings, or static Go string literals packed without
NUL terminators. Pass `include_string_literals: true`
(`--include-string-literals`, optional `max_string_literals` /
`--max-string-literals`) to recover bounded inferred word-aligned `(ptr, len)`
UTF-8 string slices from read-only data and page them through `go`
`string_literals` views. No `open_binary`, Go installation or
local replacements or build settings. No `open_binary`, Go installation or
target execution is required. The CLI equivalent is `inspect-go-binary PATH`.
Preserve artifact SHA-256, original file ranges, framed module bytes and every
unparsed module-text line. A missing record is an unknown, not proof of a
non-Go binary; observed metadata does not authenticate its claims, and static
`(ptr, len)` string recovery excludes compiler-inlined stack/immediate strings
without proving runtime reachability. Function,
non-Go binary; observed metadata does not authenticate its claims. Function,
source and type recovery remain a separate native-analysis question.
## Model files
+27 -111
View File
@@ -4,117 +4,6 @@
Security fixes are provided for the latest published version of REA. Upgrade to the latest release before reporting a problem that may already have been resolved.
## Security boundary
REA is a local reverse-engineering and automation tool. CLI and MCP use the
same application workflows and run with the host process's permissions.
REA is not a general-purpose sandbox or a multi-tenant authorization service.
### Threat model
- **Trusted authority:** the operating-system account running REA, the caller
or agent host that selects operations, and configured analysis providers,
their executables and extensions, and service endpoints. An MCP client can
invoke the operations exposed to it; its host must enforce the user's tool
permissions and approvals.
- **Untrusted data:** target binaries, archives, source files, project contents,
captures, web pages and returned target content can be malicious. Selecting
an input for static inspection does not authorize commands embedded in that
input. Agents must treat target text and Evidence as data rather
than instructions granting additional authority.
- **Operation-specific effects:** static inspection parses target data and may
launch an analysis engine. Runtime, debugger, instrumentation, browser,
desktop and environment workflows can deliberately execute code, attach to
processes, make network requests, write files or interact with applications
and devices. Review the selected operation's effects and limitations; static
inspection does not authorize launching or interacting with the target
application. See
[runtime and network responsibilities](DISCLAIMER.md#runtime-network-and-device-operations).
Standard client registrations use a dedicated stdio process. Opt-in
[HTTP MCP](docs/reference/mcp-contracts.md#transports) uses plain HTTP without
TLS or client authentication and shares provider/active-target state across
protocol sessions. Its session ID is not a user-authentication or isolation
boundary. Keep this endpoint within a trusted local or isolated environment.
### Intended security properties
Static JavaScript and .NET inspection do not run the target application.
Unexpected execution of input code through a data-only analysis path is a
security concern. Analysis engines themselves are executable software trusted
with the host account's permissions; parsing an input in an external engine
does not isolate that engine from the host.
REA authenticates its managed Hopper and Ghidra bridges with per-session random
capability tokens transferred through private session files, rather than
process arguments or environment variables. POSIX uses current-user Unix
sockets. Windows Ghidra uses authenticated loopback TCP and a private NTFS
runtime whose DACL admits only the current user and SYSTEM. These controls
protect the managed session boundary, not every external provider or debugger
endpoint. See [Windows Ghidra transport and lifecycle](docs/providers/windows-ghidra-p0.md#private-runtime-transport-and-lifecycle).
Provider ownership and mutation rules remain specific to each workflow:
- Ghidra's working projects are temporary and owned by REA. Opt-in
[checkpoints](docs/getting-started/installation.md#automatically-checkpoint-an-owned-ghidra-program)
retain REA-owned Program state. A
[caller-selected existing project](docs/getting-started/installation.md#reuse-an-existing-ghidra-project)
is fingerprinted and copied into an owned runtime for read-only processing;
Ghidra does not open or save the original database through that workflow.
- [IDA analysis](docs/providers/ida-provider.md) is read-only. An attached GUI
database is never saved or closed by REA; owned headless sessions have a
separate lifecycle.
- Cleanup must stay within resources REA owns. Failed or unverified cleanup
can retain a workspace or session for retry; closing a session
does not imply that every investigation artifact has been erased.
`rea setup` shows planned configuration and installation changes and requires
approval before applying them. Ghidra, Java and IDA are user-managed. Approved
Linux Hopper installation authenticates the package's detached PGP signature
against the pinned publisher identity and checks the signed launcher against
the selected release's digest. The release feed's display version is separate
from that authenticated identity. See [installation and publisher verification](docs/getting-started/installation.md#hopper).
### Limits and caller responsibilities
- **Host isolation:** private runtimes and capability tokens do not protect
against malicious software already running as the same operating-system
user, or a compromised trusted client or provider. Use an appropriately
isolated account, VM or restricted environment when handling hostile targets.
- **Resource bounds:** timeouts, cancellation, streaming and size limits are
operation-specific. They are not a universal CPU, memory, disk or wall-time
limit on every target and third-party tool. Enforce hard host resource limits
externally when needed. Failures of a documented boundary or cancellation
control still warrant investigation.
- **Data and network exposure:** Evidence, caches, checkpoints, exports and
captures can retain private target data, paths, URLs and memory contents.
Local execution does not make these outputs safe to publish. Requested
network operations, agent hosts and provider features such as
[IDA Free's cloud decompiler](docs/providers/ida-provider.md) can communicate
outside the host. Review their data handling and secure any exposed endpoint.
- **Interpretation:** analysis, reconstruction and generated environments can
be incomplete or incorrect. Identity checks, signatures and successful
analysis do not establish that a target, provider or generated program is
safe to execute. Review the Evidence and proposed actions before relying on
them.
### Vulnerability scope
Please report suspected violations of these boundaries privately. Examples
include unintended code execution during data-only inspection, escaping a
documented extraction/output boundary, bypassing bridge authentication or
target/session identity checks, unauthorized effects on an unrelated resource,
and disclosure of transport credentials or explicitly marked sensitive values.
An attacker-triggered bypass of a documented resource or cancellation control
can also be security-relevant without code execution.
Incorrect analysis, unsupported formats, crashes, hangs and high resource use
without a security-boundary impact are generally ordinary bug reports. Effects
explicitly requested through an execution or interaction workflow are not by
themselves a vulnerability. A dependency advisory needs its actual REA exposure
assessed; a complete exploit or diagnosis is not required to report a concern.
If you are unsure whether a boundary is affected, use the private channel below.
## Reporting a vulnerability
Do not disclose vulnerabilities, proof-of-concept exploits, credentials,
@@ -132,3 +21,30 @@ unrelated local paths from logs or examples.
The maintainer will acknowledge the report, assess its scope, and coordinate
remediation and disclosure timing with the reporter. Please allow time for
provider-dependent behavior to be reproduced safely.
## Security boundary
REA authenticates its Hopper and Ghidra bridges with per-session random
capability tokens. POSIX uses current-user Unix sockets; Windows Ghidra uses
authenticated loopback TCP with a private NTFS runtime whose DACL admits only
the current user and SYSTEM. See [Windows Ghidra P0](docs/providers/windows-ghidra-p0.md#private-runtime-transport-and-lifecycle).
Tokens are transferred through private session descriptors rather than process
arguments or environment variables.
This is not a sandbox and does not protect against malicious processes already
running as the same operating-system user. Opening an untrusted binary
delegates parsing and analysis to the selected local provider with that user's
permissions.
Ghidra sessions use a packaged Java `HeadlessScript`, an isolated temporary
project, and private home, cache, and runtime directories. REA imports only the
requested target, bounds startup and protocol messages, requests bounded CPU
and heap settings, and deletes the temporary project when the session closes.
These controls limit accidental persistence and resource use; they do not make
Ghidra a sandbox. REA does not open or modify user-owned Ghidra projects.
`GHIDRA_INSTALL_DIR` and optional `JAVA_HOME` identify user-managed
installations. Setup can add those values to detected client configuration only
after showing its plan and receiving approval. REA does not download, install,
upgrade, or modify Ghidra or Java.
On Linux, REA accepts release metadata only from Hopper's HTTPS endpoint, restricts package URLs to Hopper's public download origin, bounds the package size, and compares the downloaded bytes with Hopper's published checksum before requesting installation. The published SHA-1 value is a corruption check, not a modern package signature; HTTPS origin validation remains part of the trust boundary. Dependency installation is delegated without shell evaluation to `apt-get`, `dnf`, or `pacman`, directly as root or through `pkexec`. REA never invokes `sudo`.
+1 -12
View File
@@ -213,7 +213,6 @@ def run(arguments: dict) -> int:
rea = shutil.which("rea")
if rea is None:
return _say({"error": "REA is not installed in this computer"})
os.makedirs(os.path.dirname(arguments["stdout"]), exist_ok=True)
for path, text in arguments.get("files", {}).items():
os.makedirs(os.path.dirname(path), exist_ok=True)
with open(path, "w", encoding="utf-8") as handle:
@@ -237,18 +236,8 @@ def listing(arguments: dict) -> int:
"""
home = os.path.expanduser("~")
files, skipped = [], []
def fail_walk(error: OSError) -> None:
raise error
for directory, folders, names in os.walk(os.path.abspath(arguments["root"]), onerror=fail_walk):
for directory, folders, names in os.walk(os.path.abspath(arguments["root"])):
folders.sort()
# os.walk does not follow directory symlinks; disclose them to the consumer.
for name in folders[:]:
path = os.path.join(directory, name)
if os.path.islink(path):
skipped.append(os.path.relpath(path, home))
folders.remove(name)
for name in sorted(names):
path = os.path.join(directory, name)
relative = os.path.relpath(path, home)
-64
View File
@@ -1,64 +0,0 @@
"""Exercise the capture controller's filesystem inventory boundary."""
import json
import os
from pathlib import Path
import subprocess
import sys
import tempfile
import unittest
CONTROLLER = Path(__file__).with_name("capture.py")
class CaptureListingTest(unittest.TestCase):
def run_listing(self, root, output):
return subprocess.run(
[
sys.executable,
str(CONTROLLER),
"list",
json.dumps({"root": str(root), "output": str(output)}),
],
text=True,
capture_output=True,
check=False,
)
def test_directory_symlink_is_disclosed_without_following_it(self):
with tempfile.TemporaryDirectory() as parent:
parent = Path(parent)
root = parent / "root"
target = parent / "target"
output = parent / "listing.json"
root.mkdir()
target.mkdir()
(root / "present.txt").write_text("present")
(target / "outside.txt").write_text("outside")
try:
(root / "linked").symlink_to(target, target_is_directory=True)
except OSError as error:
self.skipTest(f"directory symlinks unavailable: {error}")
result = self.run_listing(root, output)
self.assertEqual(result.returncode, 0, result.stderr)
listing = json.loads(output.read_text())
self.assertEqual(
[item["path"] for item in listing["files"]],
[os.path.relpath(root / "present.txt", Path.home())],
)
self.assertEqual(
listing["skipped"], [os.path.relpath(root / "linked", Path.home())]
)
def test_missing_root_does_not_produce_an_empty_successful_inventory(self):
with tempfile.TemporaryDirectory() as parent:
parent = Path(parent)
output = parent / "listing.json"
result = self.run_listing(parent / "missing", output)
self.assertNotEqual(result.returncode, 0)
self.assertFalse(output.exists())
if __name__ == "__main__":
unittest.main()
-3
View File
@@ -1961,9 +1961,6 @@ public final class ReaGhidraBridge extends HeadlessScript {
limitations.add(
"Def-use links do not cross function boundaries and may omit memory aliasing, call side effects, or unresolved indirect flow."
);
limitations.add(
"Memory read/write effects cover high-p-code LOAD and STORE operations only; direct memory address varnodes in other operations are not included. An empty effect list does not establish that no memory is accessed. Recorded instruction references may provide complementary evidence."
);
limitations.add(
"Memory read/write effects include stack and temporary memory operations; they do not identify persistent state or business meaning."
);
-4
View File
@@ -358,10 +358,6 @@ remaining content budget is not read, unless stored content of the same size
could make it a duplicate. Files that could not be
retained are listed with the reason: too large, over the content budget,
changed since the walk, changed during the read, or unreadable.
The baseline also records the paths and types of non-file entries it observed,
including symlinks, without following them. This is required to distinguish an
unreadable SQLite sidecar from an absent one. Captures made before this field
was added must be made again before state inspection, task drafting or export.
Directories the application held files open in, but whose starting content was
not retained, are listed so a second capture can pass them with
`--state-path`.
+1 -26
View File
@@ -25,9 +25,6 @@ a `.deb` file; see [Applications from a .deb file](#applications-from-a-deb-file
`--seed-checkpoint` names the checkpoint whose state seeds the bundle, the
baseline by default, and `--end-checkpoint` the one a task must pass on, the
capture's last by default; see [The seed checkpoint](#the-seed-checkpoint).
`--synthetic-seed` says the seed was made for the task, as a build agent makes
it in a [build computer](desktop-build-witness.md), rather than taken from the
user's own data; see [A seed made for the task](#a-seed-made-for-the-task).
The command returns Evidence with operation `export_desktop_application` and
predicate type `rea.desktop-application-export`, listing the environment name,
@@ -127,17 +124,6 @@ The class declares:
desktop entry without `Path`), which a relative argument or program path
such as `./app` also needs, and still starts if that folder is missing. The
export refuses a capture that saw no application window.
- The seed's document, opened at launch, so the app shows it rather than its
start screen: when the seed holds exactly one file the state view gives the
`document` role, and the desktop entry's `Exec` takes files (a `%f`, `%F`,
`%u` or `%U` field code), its path under `$HOME` is appended to the command.
A command that already names a document, absolute or from its working
directory, as one captured with `--argument <file>` does, is kept as it is;
a settings path under the home does not count. A seed with no document launches
as captured. With several, no desktop entry or an `Exec` that takes no file,
the app launches as captured and the README and the result's limitations say
why. A reset
relaunches the app, so it opens the document again.
- For an Electron application (the capture found its fuse sentinel or a
`resources/app.asar`), `--no-sandbox` right after the program unless the
command already has it: Chromium's sandbox needs user namespaces the
@@ -199,16 +185,6 @@ The export refuses a name the capture does not hold exactly once, and an end
checkpoint taken before the seed checkpoint; `inspect-desktop-application-state`
lists the names in `capture.checkpoints`.
## A seed made for the task
By default the seed is the user's real data: the README and the result's
limitations say to keep the bundle local and not publish it. With
`--synthetic-seed` they say instead that the seed was made for the task, and
to read `envs/<name>/seed/` before publishing the bundle; the export cannot
tell the two apart, so the flag is the caller's word. `export_build_environment`
passes it, since the building agent makes the seed in the build computer. The
Evidence records it as `synthetic_seed`.
## Host name and user
A seed can hold the capture host's name and the user's: Geany saved its mail
@@ -361,7 +337,6 @@ when a DOCTYPE names a DTD. Known differences remain:
and then gives the file an `error`, and so does a table or column name that
is not UTF-8.
Unless it was [made for the task](#a-seed-made-for-the-task), the seed is the
user's real data. Keep the bundle local and do not publish it.
The seed is the user's real data. Keep the bundle local and do not publish it.
The class was checked against agentenv-framework 0.9.1431 with
`python -m agentenv_protocol.computer._declare` and `agent-env run --dry-run`.
+1 -9
View File
@@ -128,15 +128,7 @@ could misstate its committed rows. The capture records them under its content
roots, which include both beside a database selected on its own, when its
baseline walk listed every directory, read every path, entered no other
device, did not stop early and recorded what it left out, and wherever they change; an excluded log, and any elsewhere, is
unknown, since an unchanged file and a missing one look alike. After an
incomplete checkpoint, a database or sidecar without an explicit
later change remains unconfirmed even if a later walk completes. REA does not
combine that older file with a newly recorded member of the SQLite set. The
historical versions remain listed; the affected SQLite view has a `view_error`.
A baseline non-file at a sidecar path, or a non-directory ancestor, cannot
establish an absent file. Captures without the required baseline non-file
inventory must be made again before inspection.
A table
unknown, since an unchanged file and a missing one look alike. A table
that cannot be read keeps its `error` in place of its rows, and changes to that
database are marked incomplete. dconf
databases are read with `dconf dump /` against a private file profile, so the
+1 -4
View File
@@ -141,10 +141,7 @@ The rules both evaluators follow:
- A check decided by what a view leaves out (`lines_absent`, `value_absent`,
`row_absent`, the counts, `value_equals` of a whole object or array, and
the text checks of an element) fails when that view is truncated; a check
satisfied by what the view holds is decided on it. An element's text is not:
the reader may have dropped text from between the runs it kept, so
`text_contains` fails on a truncated view even where the kept runs hold its
value. A text node or attribute value is whole, and decided.
satisfied by what the view holds is decided on it.
The export refuses, naming the check, a file outside the owned paths, a file
spelled with a leading slash, `.` or `..`, a pointer into a file that is text
+1 -3
View File
@@ -14,9 +14,7 @@ agent's computer-use actions to it through three MCP tools:
The tools are MCP-only, like the debugger sessions: the computer lives as long
as the REA MCP server that started it, or until it is closed. Capturing the
app, exporting its bundle and witnessing the task on such a computer are in
[Building and witnessing an environment](desktop-build-witness.md), and REA's
skill for doing all of it from a request is
[desktop builds](https://github.com/morluto/rea/blob/main/.agents/skills/reverse-engineer-anything/references/desktop-build.md).
[Building and witnessing an environment](desktop-build-witness.md).
## Requirements
+12 -29
View File
@@ -18,19 +18,10 @@ grades the witness with the same checks the exported verifier runs.
Like the computer tools, these are MCP-only and act on a `computer_id` from
`start_build_computer`.
REA's skill walks an agent from a request such as "build me an Inkscape
environment where the agent changes a poster's headline" to a witnessed
bundle with these tools: the questions it asks first, when it stops for the
person, the install, the seed, the task, the witness and its final report.
See [desktop builds](https://github.com/morluto/rea/blob/main/.agents/skills/reverse-engineer-anything/references/desktop-build.md).
## Build
1. `start_build_computer` from a request. REA is installed in the computer.
2. `start_build_capture`. REA first checks the installed runtime's export
schema for synthetic-seed support. If the archive is too old, repack a
current REA, update `REA_BUILD_COMPUTER_REA_ARCHIVE`, restart the REA MCP
server and start a new build computer. REA then writes an apt configuration under
2. `start_build_capture`. REA writes an apt configuration under
`~/.rea-build/apt` and runs `apt-get update` as the computer's user, so the
capture finds the package's sources (`package_lists` counts the lists,
and `package_lists_error` gives apt's exit status and last lines when the
@@ -58,12 +49,8 @@ See [desktop builds](https://github.com/morluto/rea/blob/main/.agents/skills/rev
--end-checkpoint end`, so it seeds what was saved at `seed`, scrubs the
computer's host name and user from it, and refuses a task whose checks
all pass on the seed. A task larger than 96 KiB as REA passes it to the
computer is refused before anything runs. It also passes `--synthetic-seed`,
since the agent made the seed for the task, so the README does not call it
the user's real data. When the seed holds exactly one document and the
app's desktop entry takes files, the bundle's app opens that document at
launch. A file moved to the desktop Trash is not seeded, and the export's
limitations name what the Trash held at `seed`. For a
computer is refused before anything runs. A file moved to the desktop Trash is not seeded,
and the export's limitations name what the Trash held at `seed`. For a
`.deb` app that no apt source the capture found offers, the export takes
the request's URL with `--package-url`; one apt offers installs from apt. REA lists the bundle's files with their sizes
and SHA-256 in the computer, into a file beside the bundle that it reads
@@ -115,8 +102,7 @@ cancels the call in progress on it and refuses the calls still waiting.
## Witness
Start a fresh computer from the exported folder with `start_build_computer`
and `{"kind": "bundle", "path": ...}`; agentenv boots the app with the seed,
on the seed's document when the export opens one.
and `{"kind": "bundle", "path": ...}`; agentenv boots the app with the seed.
Then, with the task exactly as exported:
| `stage` | Before it | Its checks must |
@@ -151,17 +137,14 @@ SQLite file locked past the reader's wait, or because what it looks for may
lie in what its view cut, is `undecided` in its result: it shows nothing
about the task. That covers a line `lines_present` misses in a text view cut
at 5,000 lines, a row `row_present` misses in a table whose view keeps only
its first rows, a `value_equals` or text check pointer that names nothing
in a truncated view or past a cut zip listing, the absence checks and counts
on a cut view, and `text_equals` or `text_contains` of an element on one,
even where the element's kept text holds the value, since the cut may have
dropped text from between its runs. Any other check that passes on what the
view kept stays decided, and so does a value found there that differs from
the one expected.
The result's `passed` and description are the exported verifier's, which has
no undecided results. A stage that only undecided checks would settle, such
as a near miss whose one failing check could not read its file, files nothing
and is refused; check it again once the files read whole.
its first rows, a `value_equals` pointer that names nothing in a truncated
view or past a cut zip listing, and the absence checks and counts on a cut
view. A check that passes on what the view kept stays decided, and so does a
value found there that differs from the one expected. The result's `passed`
and description are the exported verifier's, which has no undecided results.
A stage that only undecided checks would settle, such as a near miss whose
one failing check could not read its file, files nothing and is refused;
check it again once the files read whole.
A stage whose checks do not show what it must ends the witness, and so does
`after_reset`. REA then ends the recording, fetches its segments through
+19 -1
View File
@@ -109,7 +109,25 @@ unfamiliar prefix. The unavailable fork reported in
For a client that supports MCP catalog refresh, set
`REA_MCP_TOOL_CATALOG_PROFILE=hot-cold` in REA's server environment and restart
the connection. REA then advertises a small initial catalog and loads other
named tools through `discover_tools`. Setup preserves this explicit setting.
named tools through `discover_tools`. Setup can record the explicit choice:
```bash
rea setup --client codex --tool-catalog-profile hot-cold --dry-run
rea setup --client codex --tool-catalog-profile hot-cold
```
The plan shows `REA_MCP_TOOL_CATALOG_PROFILE=hot-cold` before approval. This
selects server catalog loading; enable and verify the client's catalog refresh
separately. Setup preserves its existing feature flags and tool approval lists.
To restore upfront advertisement, use `--tool-catalog-profile full`, then
reconnect. Omitting the option preserves the saved profile and keeps `full` for
a new registration. Existing explicit environment selections are also retained.
Setup does not infer refresh from a client name or enable experimental client
features. The verified Codex trial below covers one version with an explicit
flag; FastMCP was tested with explicit refresh calls. Neither establishes
automatic refresh for every installed version or other client. Keep `full`
until refresh is established for the selected client and configuration.
See the [discovery contract](../reference/mcp-contracts.md#hotcold-catalog-discovery) for
pagination, identity and family-scope semantics.
@@ -114,8 +114,7 @@ caller cancellation still reports cancellation.
The direct observations are:
- `Debugger.scriptParsed`, establishing that a bounded script location was
parsed with the reported execution-context ID; association with a particular
context lifetime is known only when its creation was observed;
parsed in the observed execution context;
- `Debugger.scriptFailedToParse`, retained only as a bounded invalid-script
count in `scripts.parse_failed_total`. A well-formed parse-failure
event is distinct from malformed protocol data and does not make loaded
@@ -164,13 +163,8 @@ and collection overhead, and projected URL fields. Each CDP message also has a
16 MiB transport limit. A message over that limit fails with `payload_limit`;
when the aggregate budget is reached, later metadata events are dropped and
the partial result reports `events_dropped`, `truncated: true`, and
`retained_metadata_budget_exceeded`. Context records retain each observed lifetime, and scripts refer to the context
lifetime active when parsed. The reported numeric execution-context ID is
retained separately on both records; a script with no observed context creation
has an unknown context key. Repeated transitions within one lifetime update its
record; the state records the last observed lifecycle event and does not prove
that the context is still live. This changes context keys and Evidence identities from older captures;
recapture observations to obtain lifetime associations. Scripts are
`retained_metadata_budget_exceeded`. Repeated context transitions update the
current context record instead of accumulating duplicate objects. Scripts are
validated after capture, deduplicated by stable metadata, and canonically
sorted. Wall-clock timestamps and protocol script IDs are excluded from the
durable result, so identical inputs and captured metadata produce the same
+8 -26
View File
@@ -49,16 +49,14 @@ selected dependency versions without reopening the file:
}
```
Go views support `dependencies` (exact `paths`), `settings` (exact `keys`) and,
when collected with `include_string_literals: true`, `string_literals` (exact
`values` and substring `contains`), plus optional original `indices`, field
selection, and pagination. Filters intersect; empty filter arrays select no rows
and `fields: []` returns only row identity. Each row keeps its original `index`,
scoped to the parent Evidence and collection; duplicate module paths and setting
keys keep distinct indices. Page offsets count matching records. Exhausting
retained rows does not establish complete runtime dependencies or string
coverage. Original bytes, unknown lines and all complete metadata remain in the
parent and can be exported as an Evidence bundle.
Go views support `dependencies` (exact `paths`) and `settings` (exact `keys`),
optional original `indices`, field selection, and pagination. Filters intersect;
empty filter arrays select no rows and `fields: []` returns only row identity.
Each row keeps its original `index`, scoped to the parent Evidence and collection;
duplicate module paths and setting keys keep distinct indices. Page offsets
count matching records. Exhausting retained rows does not establish complete
runtime dependencies. Original bytes, unknown lines and all complete metadata
remain in the parent and can be exported as an Evidence bundle.
One-shot CLI summaries save complete Evidence before returning the projection:
@@ -115,22 +113,6 @@ their empty dependency array does not establish the absence of dependencies.
The result's limitations state this explicitly. A module-mode build with a main
module record and no dependency records has an observed empty dependency list.
When `include_string_literals: true` (CLI `--include-string-literals`, optional
`max_string_literals` / `--max-string-literals`, default `2000`, maximum `10000`)
is selected, `string_literals` reports `evidence_kind: "inferred"` alongside
deduplicated printable UTF-8 literals referenced by word-aligned two-word
`(ptr, len)` string headers in non-executable initialized data. Because Go packs
read-only string data contiguously without NUL terminators, slicing by `(ptr, len)`
recovers exact literal boundaries instead of concatenated C-string runs. Each
target slice (`1`–`4096` bytes) must stay within a single read-only mapped
section or segment, decode as printable UTF-8 (`\t`, `\n`, `\r`, joiners
`U+200C` / `U+200D` and printable Unicode scalar values, excluding control and
other format characters), and fit within
a 64 MiB header-scan budget and 512 KiB aggregate string budget
(`truncated: true` when capped). Compiler-inlined or
stack-constructed strings without static headers, unapplied relocation addends
and Mach-O `LC_DYLD_CHAINED_FIXUPS` pointer encodings are noted in `limitations`.
## Supported boundary
The built-in TypeScript reader supports ELF, PE and thin Mach-O images, and one
+2 -11
View File
@@ -574,17 +574,8 @@ The raw Java `is_dead` flag can remain set after Ghidra decodes a live block;
`block_membership` reports actual syntax-tree membership separately.
The provider dossier itself retains up to 3,000 p-code operations, 64 inputs per
operation and 12,000 def-use edges, with explicit omitted counts. Memory effects
cover high-p-code `LOAD` and `STORE` operations; direct memory address varnodes
in other operations are excluded, so an empty effect list does not establish
that the function accesses no memory. `procedure_references` can supply
complementary recorded instruction references, with its own coverage limits. A
`STORE` may describe stack memory and does not itself prove persistent state.
The Ghidra analysis profile commits to this effect scope. Snapshots from before
that commitment are rejected; analyze without the snapshot and save a fresh one.
To keep historical Evidence, copy the old snapshot's `evidence_bundle` object to
a separate JSON file and import that bundle. Import validates the Evidence; it
does not replay the old provider analysis.
operation and 12,000 def-use edges, with explicit omitted counts. A `STORE`
may describe stack memory and does not itself prove persistent state.
Jump-table evidence keeps numeric `mappings`, explicit `default_targets`, and
backing `data_sources` separate. A null case value denotes an unresolved
+1 -1
View File
@@ -4,7 +4,7 @@ REA exposes Frida device and process discovery, attach or spawn sessions, and ca
For remote devices, pass a host with an optional port (`host[:port]`; bracket IPv6 addresses) and any token, certificate, origin, or keepalive options on that operation. The keepalive interval is measured in seconds, matching Frida Core 17.23.2. Authentication values are held only for the active call or session and are excluded from Evidence. Do not embed credentials in the endpoint address.
MCP exposes `list_frida_devices`, `list_frida_processes`, `start_frida_session`, `load_frida_script`, `resume_frida_session`, `unload_frida_script`, `frida_session_status`, and `close_frida_session`. A spawned process starts paused so scripts can load first. Closing unloads session scripts and detaches. If cleanup fails, the session remains available for cleanup retry but refuses new script loads and resume requests. If a spawn remains paused, REA resumes it only after script cleanup or session detach confirms the instrumentation is released; if both cleanup paths fail, the target stays paused and the cleanup error is retained. REA never kills the target. MCP sessions end with the server process. The one-shot CLI command `instrument-with-frida` accepts one inline script or script file, observes messages for a bounded duration, and returns Evidence with the source hash and captured messages.
MCP exposes `list_frida_devices`, `list_frida_processes`, `start_frida_session`, `load_frida_script`, `resume_frida_session`, `unload_frida_script`, `frida_session_status`, and `close_frida_session`. A spawned process starts paused so scripts can load first. Closing unloads session scripts and detaches. If a spawn remains paused, REA resumes it only after script cleanup or session detach confirms the instrumentation is released; if both cleanup paths fail, the target stays paused and the cleanup error is retained. REA never kills the target. MCP sessions end with the server process. The one-shot CLI command `instrument-with-frida` accepts one inline script or script file, observes messages for a bounded duration, and returns Evidence with the source hash and captured messages.
`instrument-with-frida --json` returns the Evidence record directly, matching MCP. Consumers of the earlier `{evidence, cleanup_error}` CLI wrapper should read the record at the JSON root and the session cleanup observation at `normalized_result.cleanup_error`. If final provider cleanup fails or cancellation arrives during it, the typed error retains completed Evidence in `details.partial_observation`. Discovery commands retain their device or process report in the same field.
+11 -22
View File
@@ -239,21 +239,10 @@ file for you.
`observe_web_session`, `discover_webmcp_tools`, and `capture_web_screenshot`
accept a browser socket. Website runtime attribution, Electron inspection,
and scenario attach mode still require HTTP discovery.
- An admitted browser socket is retained by the active browser provider across
calls to the same normalized browser WebSocket URL, and concurrent cold-start
calls share one handshake so MCP sessions do not re-open the browser socket on
every step. Scheme case, uncompressed IPv6 loopback spellings, and leading
port zeros normalize to one reuse key, while `127.0.0.1`, `[::1]`, and
distinct `/devtools/browser/<id>` paths remain separate sockets. Each target
operation detaches its flattened target session when finished: unconfirmed
target attach or detach cleanup closes the shared browser socket for session
containment, whereas a caller's own discovery deadline or cancellation
releases only its lease when transport state remains clean. Provider shutdown
closes the retained browser socket. One-shot CLI invocations close their
provider on exit, so Chrome may still ask you to approve each separate CLI
connection. Discovery (`Browser.getVersion`, `Target.getTargets`) defaults to
a 10-second deadline and can be adjusted per call with `discovery_timeout_ms`
(`--discovery-timeout-ms` on the CLI).
- Each call opens one WebSocket and uses it for discovery
(`Browser.getVersion`, `Target.getTargets`) and for the selected page.
Discovery must finish within the same 10-second deadline as HTTP discovery.
Chrome may ask you to approve each connection.
- The browser identifier controls access to the socket. Evidence records the
endpoint as `ws://127.0.0.1:9222/devtools/browser/[REDACTED]`.
- `browser.revision` is the socket's `Browser.getVersion` value, such as
@@ -609,13 +598,13 @@ an unknown size, comparison reports unknown rather than treating the observation
as a resource addition or removal; complete inventory coverage still establishes
when an entire group is absent.
CDP discovery defaults to a 10-second response deadline, configurable per call
on passive browser tools with `discovery_timeout_ms` (default 10000). HTTP
discovery documents use an 8 MiB budget. Browser-socket discovery
(`Browser.getVersion`, `Target.getTargets`) uses the 64 MiB protocol message
budget. Neither byte budget has a runtime override. `list_browser_targets`
accepts `discovery_timeout_ms` and no `command_timeout_ms`, because it performs
only discovery without a post-discovery target command. Other CDP tools use
CDP discovery has a 10-second response deadline. HTTP discovery documents
use an 8 MiB budget. Browser-socket discovery (`Browser.getVersion`,
`Target.getTargets`) uses the 64 MiB protocol message budget. Neither budget
nor the discovery deadline has a runtime override. `list_browser_targets` accepts no
`command_timeout_ms`: HTTP discovery and browser-socket discovery
(`Browser.getVersion`, `Target.getTargets`) stay on that fixed deadline, and
the socket closes without a later command. Other CDP tools use
`command_timeout_ms` (default 20000) for each WebSocket handshake and command
response, separate from the caller-selected observation window, discovery, and
the 5000 ms cleanup grace. A browser-level socket's handshake and the following
-8
View File
@@ -70,14 +70,6 @@ trailer is observed absence, not proof the module is unsigned.
When section names are incomplete, a missing named section is `unknown`
rather than `absent`. An empty file-backed section is present and empty.
`coverage.status` is `partial` when supported facts cannot all be examined or
interpreted, including incomplete section names, malformed or unsupported
metadata, and omitted duplicate named sections. When multiple `.modinfo`,
`__versions`, `.gnu.linkonce.this_module`, `.init.text`, or `.exit.text`
sections exist, the first is examined and a limitation identifies the omission.
`complete` covers the supported inspection described here; it does not claim
that `struct module`, symbol-table records, or certificate chains were decoded.
## Limits and failures
The selected file is limited to 64 MiB by default (512 MiB maximum). At most
+1 -10
View File
@@ -1358,15 +1358,6 @@ Native call tracing and process capture retain available observations in
`details.partial_observation` on failure, including when cleanup succeeds.
The observation reports its partial coverage; cleanup details describe host
state separately from the execution failure.
When a completed observation cannot be published because recording a source
failed, the original source failure remains the error. `partial_observation`
can carry the failed source and `completed_observation` carries the completed
result, with `source_closure: "not-established"`. A retained reference is
reported only when its owning ledger confirms it; an inline result with
`retention: "unknown"` makes no claim about ledger membership. If an
observation cannot fit the MCP response, its corresponding `_omitted` detail
reports the delivery limit. Cleanup failure and other completed source failures
remain visible separately.
For these tools, cancellation observed during result finalization or owned
cleanup also returns typed cancellation with the available observations.
A normal target exit does not establish request completion. Incomplete cleanup
@@ -1681,7 +1672,7 @@ procedure resolution returns typed unreadable output; provider errors never
become absence from their message text. `inspect_address_context` requires an explicit address and
returns name, procedure, comment, inline-comment, and bookmark facets;
unsupported facets are local `unavailable` outcomes. A facet rejected for
invalid input, source Evidence integrity or a resource constraint includes its canonical `error`
invalid input or a resource constraint includes its canonical `error`
projection, including structured issues or reported limits and recovery,
alongside the other facet outcomes. Use `current_document`,
`current_address`, and `current_procedure` for direct single-field lookups; use
-5
View File
@@ -10,8 +10,3 @@ for the specification lifecycle, roadmap granularity and producer-owned contract
- [Organization](documentation/organization/spec.md)
([plan](documentation/organization/plan.md), [tasks](documentation/organization/tasks.md))
## Native
- [Go static string-header literal recovery](native/go-string-literals/spec.md)
([plan](native/go-string-literals/plan.md), [tasks](native/go-string-literals/tasks.md))
@@ -84,12 +84,6 @@ and the recording and writes the record as Evidence.
and the export's limitations name what the Trash held at the seed; a
start from a bundle folder writes no bytecode into it; the first
screenshot waits, briefly and bounded, until the frame is not one colour.
- Gaps of the blind validation's solve runs: the exported app opens the
seed's one document at launch, when its desktop entry takes files, so a
solving agent starts in the document rather than on the app's start
screen; and `export_build_environment` passes `--synthetic-seed`, so the
README says the seed was made for the task instead of calling it the
user's real data.
- Gaps of the second review: calls on one computer (actions, capture
steps, checks and close) run one at a time in arrival order, so a stage's
@@ -100,12 +94,11 @@ and the recording and writes the record as Evidence.
want of a readable or whole view is `undecided` and proves nothing; a
stage only such checks would settle files nothing and can be checked
again. Undecided includes a failure to find a line, row or value that may
lie in what a cut view left out, and any text check of an element in a cut
view, which may have lost text from between the element's runs; any other
check that passes on what the view kept stays decided. The export likewise keeps a task only when a check
fails on what the seed's view shows. The controller writes a folder's file
list to a file that REA reads through `data/get`, so a large bundle's list
is not cut at the 1 MiB of a command's output.
lie in what a cut view left out; a check that passes on what the view kept
stays decided. The export likewise keeps a task only when a check fails on
what the seed's view shows. The controller writes a folder's file list to a
file that REA reads through `data/get`, so a large bundle's list is not cut
at the 1 MiB of a command's output.
- The witness reads the build computer's bounded action log: its stage rules
use the log's count and the last applied action of each kind, and the
record holds the entries the log keeps, `actions_dropped`, and a
@@ -11,4 +11,3 @@
- [x] Fix the blind validation run's gaps and the export's install source for a `.deb`.
- [x] Fix the second review's gaps: one call at a time per computer, the recording's request id, undecided checks and the bundle's file list.
- [x] Leave a failure that a cut view may have caused undecided: a missing line, row or value.
- [x] Open the seed's one document at launch, and word a seed made for the task as such.
@@ -245,41 +245,6 @@ tests added, and passes now.
- `DesktopBuildTurns.test.ts`: a running call that finishes after a close
keeps its result.
## Opening the seed's document
Run on 2026-11-05: source tests and gates on macOS; the desktop source tests
again on the Ubuntu 24.04 amd64 VM (40 files, 422 passed, none skipped).
- `seedDocument.test.ts`: the seed's one document is appended when `Exec`
holds `%F`, `%U`, `%f` or `%u`, and the launch respells it as
`"$HOME"/'Documents/poster.svg'`; two documents, none, an `Exec` without a
file field code and a capture without a desktop entry keep the command and
give the reason; a command already naming a file under the home is kept.
- `appExport.test.ts`: the README says what the launch opens, or why it
opens nothing; a seed made for the task is worded as such in the README
and the class, and a captured one as the user's real data.
- `DesktopApplicationExport.test.ts`: from a seed-and-end capture launched
through `notes %U`, the class launches `notes` with the note; through
`notes`, or without a desktop entry, and from a baseline seed with no
document, it launches as captured and a limitation says why;
`--synthetic-seed` changes the limitation and the README and is recorded
as `synthetic_seed`.
- `buildCaptureMcp.test.ts`: `export_build_environment` runs the export
with `--synthetic-seed`, and the real CLI's README for that capture says
the seed was made for the task.
The blind Inkscape build's capture was gone with its build computer, so the
bundle could not be exported again. Instead, a copy of that bundle had only
its `Launch` command replaced by the one this code renders for its seed (one
document, `Documents/poster.svg`; the image's `Exec=inkscape %F`). A computer
of it came up in 47 s with Inkscape showing `poster.svg` and no Welcome
screen, and `data/reset` relaunched it on the poster again. Three Claude Code
runs with Sonnet 5.5 all passed, in 11, 9 and 10 turns for $0.70, $0.46 and
$0.72 ($0.63 on average); the same bundle opening on the Welcome screen had
taken 18, 23 and 21 turns for $0.70, $1.55 and $0.51 ($0.92). Cache reads
fell from 585-714K tokens to 181-225K; the cost is mostly cache writes,
which varied from 17K to 189K tokens whatever the turns.
## Limits of this verification
- The witness acts were scripted by this agent from the task's prompt; no
@@ -13,10 +13,6 @@ folder to build the environment; this step builds nothing.
## Requirements
- The baseline records each observed non-file path and its type without
following symlinks, so a later state reader can distinguish an absent SQLite
sidecar from an observed non-file.
- The command is CLI only. A capture is a long interactive session whose
checkpoints come from stdin lines (empty, `checkpoint [name]` or other
text) and which ends on `stop` or the end of stdin, when the launched
@@ -27,12 +27,7 @@ state through `data/add`, `data/get` and `data/reset`.
class match with a window ready check, `paths` from the state view's roles
(state directories of application state files, or a folder beside one that
differs only in letter case in the files' spelling, and folders of
documents, nested ones collapsed) and the skill file. When the seed holds
exactly one document and the desktop entry's `Exec` takes files, the
launch appends its path under `$HOME`; a command that already names a
document, absolute or from its working directory, is kept, a seed with no document launches as captured,
and otherwise the README and the limitations say why the app opens no
document.
documents, nested ones collapsed) and the skill file.
- With paths, it declares all three data hooks and calls agentenv's helpers:
seed the home once per boot then `keep_initial`, `add`, `reset`, and `get`
plus a data part holding a typed JSON view of each file. Without paths it
@@ -43,8 +38,7 @@ state through `data/add`, `data/get` and `data/reset`.
application are compiled into the user's dconf database with `dconf-cli`,
without D-Bus.
- The README and the result state the agentenv-framework release the class was
checked against (0.9.1431), and that the seed is real user data, unless
`--synthetic-seed` says it was made for the task.
checked against (0.9.1431), and that the seed is real user data.
## Non-goals
@@ -12,9 +12,7 @@ generation reads the kinds of change.
- CLI only, like the capture. The folder's `capture.json` must be
`capture_desktop_application` Evidence from provider `rea-desktop` v1 with a
valid result, including its baseline non-file inventory; anything else is
refused as invalid input. Captures from before that inventory was recorded
must be made again.
valid result; anything else is refused as invalid input.
- Retained bytes are read without following links and used only when their
SHA-256 matches the name they are stored under.
- A path in a folder beside a state directory whose name differs from it only
@@ -29,11 +27,7 @@ generation reads the kinds of change.
refused when either existed but was not retained or the capture did not
record whether it existed (unknown is never read as absent; absence holds
only under content roots the baseline walked completely, with no truncation,
unreadable directory or unchecked path, outside recorded exclusions). A
later incomplete walk leaves a database or sidecar unconfirmed until an
explicit change records it; a subsequent complete walk alone cannot recover
a change the incomplete walk missed. Read SQLite only when the database and
both sidecars are confirmed at that version; dconf through
unreadable directory or unchecked path, outside recorded exclusions); dconf through
`dconf dump /` on a private file profile, keeping only
groups whose path names the application; JSON up to 4 MiB and 500 levels
with exact numbers; XML through the shared strict parser, a DOCTYPE read
@@ -55,11 +55,9 @@ verifier's, agree.
entry of another format; a value that is neither an element, a text node
(a string among an element's `children`) nor an attribute's value (one among
its `attributes`), so an element's `name` and the `doctype`'s fields fail;
and, as undecided, in a view that leaves something out, either check of an
element, even one whose kept text holds the value, since the cut may have
dropped text from between the runs it kept; a pointer naming nothing; or a
selector searching an array such a view may cut. A text node or an
attribute's value is whole, so it is decided on a truncated view.
and, as undecided, an element in a view that leaves something out, or a
selector searching an array such a view may cut. A text node is whole, so
it is decided on a truncated view.
- Refusals: the task parser refuses the empty pointer, a pointer not starting
with `/`, an empty `text_contains` value or one that is only whitespace
with `normalize_whitespace`, and a value that looks like a date and time,
@@ -1,40 +0,0 @@
# Implementation plan
## Boundary and contract
Extend `goBinarySchema` in `src/domain/go/goBinary.ts` with optional
`string_literals` (`evidence_kind: "inferred"`, `items`, `discovered_count`,
`aggregate_bytes`, `max_items`, `truncated`), plus `include_string_literals` and
`max_string_literals` on `src/contracts/go/goToolContracts.ts` and
`src/cli/goCommands.ts`. Add the `string_literals` view projection to
`src/domain/analysisView/goBinaryView.ts` so callers can page recovered literals
from retained Evidence without repeating file parsing.
Implement `recoverGoStringLiterals` in `src/go/GoStringLiterals.ts` on top of
`BinaryContainer` and `createFileMappingIndex`. Pre-index readable `LoadRegion`
intervals once in `O(R log R)` so Mach-O section eligibility runs in `O(log R)`
with periodic `checkActive` cancellation checks. Normalize header-scan spans by
pointer alignment phase, merge overlaps, and sort by ascending file offset so
`reference_count` counts each physical header once and `first_header_offset` is
minimal. Deduplicate target slices in memory with bounded candidate and rejection
caches before sorting deterministically by `(location.offset, location.bytes)`.
## Incremental work and validation
1. Define domain/MCP/CLI schemas, limitation notes and `string_literals` analysis
view behavior while preserving default omission when not requested.
2. Implement `recoverGoStringLiterals` and wire `GoBinaryImage`,
`GoBinaryProvider` and `GoBinaryService` with cooperative cancellation.
3. Add unit fixtures across ELF/PE/Mach-O, Unicode format-control filtering,
budget/cap truncation, overlapping ELF spans, bounded negative caching and
25,000-section Mach-O indexing/cancellation.
4. Extend `scripts/verify-go-binary.mjs` via `artifactMcpCall` so real compiled Go
targets verify both CLI and advertised MCP `outputSchema` parity.
5. Update the [Go binary guide](../../../guides/native/go-binaries.md), skill
guidance, generated catalogs and documentation route checks.
## Effects and compatibility
Default `inspect_go_binary` calls omit `string_literals` and preserve historical
Evidence compatibility. No external tool or target execution is introduced; only
bounded offline byte slicing over the already read `64 MiB` image buffer runs.
@@ -1,45 +0,0 @@
# Go static string-header literal recovery
## Problem and outcome
Go compilers pack static string contents contiguously in read-only sections
(`.rodata`, `__TEXT,__rodata` / `__TEXT,__const`, `.rdata`) without NUL
terminators. Generic C-string scans merge adjacent Go literals into multi-kilobyte
runs. Extend `inspect_go_binary` / `inspect-go-binary` with opt-in, bounded
`(ptr, len)` `reflect.StringHeader` recovery across ELF, PE and thin Mach-O
images so static string slices are recovered at their exact boundaries.
## Requirements
- Keep `include_string_literals` opt-in (`false` by default) so existing
build-metadata output and payload size are unchanged unless requested.
- Scan only pointer-aligned non-executable initialized data spans (with indexed
`O(log R)` readable segment checks on Mach-O and sectionless/unnamed-ELF
load-region fallbacks) in deduplicated ascending file-offset order.
- Admit candidate `[ptr, ptr + len)` slices only inside single read-only
non-executable mapped spans with `1 <= len <= 4096`, non-overlapping with the
header itself, and valid printable UTF-8 (allowing `\t`, `\n`, `\r`, `U+200C`
and `U+200D` while rejecting control, surrogate, noncharacter, private-use and
invisible/bidi `\p{Cf}` code points).
- Bound header-scan work (`64 MiB`), tracked candidates (`100,000`), negative
slice cache (`4,096`), returned items (`max_string_literals`, `1..10,000`,
default `2,000`), and aggregate returned UTF-8 bytes (`512 KiB`), reporting
`evidence_kind: "inferred"`, `discovered_count`, `aggregate_bytes` and
`truncated` honestly.
- Record limitation notes when Mach-O `LC_DYLD_CHAINED_FIXUPS` encodes rebases in
pointer slots or when truncation occurs, and expose a focused `string_literals`
projection in `inspect_analysis_view`.
## Acceptance
Unit, boundary and CLI acceptance tests cover ELF/PE/Mach-O (32/64-bit, little
and big endian), sectionless and unreadable-`.shstrtab` ELF images, overlapping
spans, `U+200C`/`U+200D` versus disallowed `\p{Cf}` controls, negative-cache and
output caps, and 25,000-region Mach-O indexing/cancellation. The real Go binary
verifier validates CLI and advertised-schema MCP parity across compiled targets.
## Out of scope
Instruction-operand immediate string recovery (stack/register `MOV`/`LEA` pairs
without static two-word headers), Mach-O chained-fixup rebase decoding, binary
execution, and non-UTF-8 byte-slice guessing.
@@ -1,8 +0,0 @@
# Tasks
- [x] Define single-feature scope, contracts and implementation plan (`spec.md`, `plan.md`).
- [x] Extend `goBinarySchema`, MCP contracts, CLI flags and `inspect_analysis_view` (`string_literals`).
- [x] Implement bounded `(ptr, len)` recovery in `src/go/GoStringLiterals.ts` with `O(R log R)` Mach-O region indexing and non-overlapping file-order header scanning.
- [x] Add unit, provider, MCP view and CLI acceptance tests for multi-format recovery, Unicode `\p{Cf}` / ZWNJ / ZWJ filtering, caps, negative-cache bounds and 25,000-section Mach-O scaling.
- [x] Verify CLI and `artifactMcpCall` advertised-schema MCP parity across compiled targets in `scripts/verify-go-binary.mjs`.
- [x] Update the Go binary guide, skill reference and generated catalogs; pass documentation route and static checks.
+20 -30
View File
@@ -2,7 +2,7 @@ REA npm dependency inventory
Prepared from the root package-lock.json; refresh this inventory when locked dependencies change.
License identifiers are upstream lockfile declarations, not a legal assessment.
Runtime includes transitive and optional platform packages; development includes build, test and website tooling.
Locked package entries: 966; runtime: 175.
Locked package entries: 964; runtime: 181.
Full runtime copyright/license/NOTICE texts: npm-runtime-notices.txt.
@algolia/[email protected] | development | MIT
@@ -395,12 +395,12 @@ [email protected] | development | MIT
Package: https://www.npmjs.com/package/@docsearch/react/v/3.8.2
Archive: https://registry.npmjs.org/@docsearch/react/-/react-3.8.2.tgz
Integrity: sha512-xCRrJQlTt8N9GU0DG4ptwHRkfnSnD/YpdeaXe02iKfqs97TkZJv60yE+1eq/tjPcVnTW8dP5qLP7itifFVV5eg==
@electron/[email protected] | development | MIT
@electron/[email protected] | runtime | MIT
Lockfile path: node_modules/@electron/asar
Package: https://www.npmjs.com/package/@electron/asar/v/4.2.0
Archive: https://registry.npmjs.org/@electron/asar/-/asar-4.2.0.tgz
Integrity: sha512-npW1NW5yy8EB9XY/vEw9sUdgmq0sJEhmSBb6bqyFOAw1CSkrhvAvO6QWlW8CdIMo8VN1lkdF345l/MeW0LrY0Q==
[email protected] | development | MIT
[email protected] | runtime | MIT
Lockfile path: node_modules/@electron/asar/node_modules/commander
Package: https://www.npmjs.com/package/commander/v/13.1.0
Archive: https://registry.npmjs.org/commander/-/commander-13.1.0.tgz
@@ -655,11 +655,6 @@ [email protected] | development | MIT
Package: https://www.npmjs.com/package/@inquirer/type/v/4.2.0
Archive: https://registry.npmjs.org/@inquirer/type/-/type-4.2.0.tgz
Integrity: sha512-2rnHX8RPo4glJYqnFc/v3nQeIhDcjyRRyaT7MGcfL/8xv/8K03SXYoA2tX06WVSKywWOE/ncbG3dtuzLjR5TCQ==
@isaacs/[email protected] | development | BlueOak-1.0.0
Lockfile path: node_modules/@isaacs/nonrecursive-glob-match
Package: https://www.npmjs.com/package/@isaacs/nonrecursive-glob-match/v/1.1.0
Archive: https://registry.npmjs.org/@isaacs/nonrecursive-glob-match/-/nonrecursive-glob-match-1.1.0.tgz
Integrity: sha512-GPm/Dbvk5RLmhRnxXIa7nTpK0xtl4E0wj0MslsuNiJ1FIROU+2+9lgUC/dgF7Ey4QCWhfEsgxilMRMCdHPfDfw==
@jridgewell/[email protected] | development | MIT
Lockfile path: node_modules/@jridgewell/gen-mapping
Package: https://www.npmjs.com/package/@jridgewell/gen-mapping/v/0.4.0-beta.0
@@ -2820,16 +2815,11 @@ [email protected] | runtime, optional | MIT
Package: https://www.npmjs.com/package/github-from-package/v/0.0.0
Archive: https://registry.npmjs.org/github-from-package/-/github-from-package-0.0.0.tgz
Integrity: sha512-SyHy3T1v2NUXn29OsWdxmK6RwHD+vkj3v8en8AOBZ1wBQ/hCAQ5bAQTD02kW4W9tUp/3Qh6J8r9EvntiyCmOOw==
glob@14.0.4 | development | BlueOak-1.0.0
glob@13.0.6 | runtime | BlueOak-1.0.0
Lockfile path: node_modules/glob
Package: https://www.npmjs.com/package/glob/v/14.0.4
Archive: https://registry.npmjs.org/glob/-/glob-14.0.4.tgz
Integrity: sha512-mMiwNKoJZ4HAIRVJxotO6LsNRReA30gQwP9E2/p94tfLv+jygCNpKDjhhSL6OLY6LE371EZm5EAf7RpYuUqlsw==
[email protected] | development | BlueOak-1.0.0
Lockfile path: node_modules/glob/node_modules/minimatch
Package: https://www.npmjs.com/package/minimatch/v/11.0.5
Archive: https://registry.npmjs.org/minimatch/-/minimatch-11.0.5.tgz
Integrity: sha512-snPlVppFcYWfLLFQGhDxUyBcHNtMlWmn3jtj7pEaO+DP8pqL0IvAzXhMYmn1z9ASNtgmwLBdFxSf4tMUB0OTKA==
Package: https://www.npmjs.com/package/glob/v/13.0.6
Archive: https://registry.npmjs.org/glob/-/glob-13.0.6.tgz
Integrity: sha512-Wjlyrolmm8uDpm/ogGyXZXb1Z+Ca2B8NbJwqBVg0axK9GbBeoS7yGV6vjXnYdGm6X53iehEuxxbyiKp8QmN4Vw==
[email protected] | runtime | MIT
Lockfile path: node_modules/gopd
Package: https://www.npmjs.com/package/gopd/v/1.2.0
@@ -3285,11 +3275,11 @@ [email protected] | runtime | MIT
Package: https://www.npmjs.com/package/lossless-json/v/4.3.1
Archive: https://registry.npmjs.org/lossless-json/-/lossless-json-4.3.1.tgz
Integrity: sha512-SqD/Bg3ZfltBJ2Z14hJ/BihnvtV553WO4g9/ePtlp4lrnl9jF3AdIJt53A/Wkg/0Li+LMfxaBqgx1MiFZdQlpQ==
[email protected].3 | development | BlueOak-1.0.0
[email protected].2 | runtime | BlueOak-1.0.0
Lockfile path: node_modules/lru-cache
Package: https://www.npmjs.com/package/lru-cache/v/11.5.3
Archive: https://registry.npmjs.org/lru-cache/-/lru-cache-11.5.3.tgz
Integrity: sha512-U4N8FgzmWxc8k1VH8Kr6lQg18U7Fjvby6wXHVRX/ZZ7IwWbRMgrRbP0Wrb5q5NVinryp4SQampHKdvtecItxUg==
Package: https://www.npmjs.com/package/lru-cache/v/11.5.2
Archive: https://registry.npmjs.org/lru-cache/-/lru-cache-11.5.2.tgz
Integrity: sha512-4pfM1Ff0x50o0tQwb5ucw/RzNyD0/YJME6IVcStalZuMWxdt3sR3huStTtxz4PUmvZfRguvDejasvQ2kifR11g==
[email protected] | development | MIT
Lockfile path: node_modules/magic-string
Package: https://www.npmjs.com/package/magic-string/v/1.4.3
@@ -3420,7 +3410,7 @@ [email protected] | runtime | MIT
Package: https://www.npmjs.com/package/minimisted/v/2.0.1
Archive: https://registry.npmjs.org/minimisted/-/minimisted-2.0.1.tgz
Integrity: sha512-1oPjfuLQa2caorJUM8HV8lGgWCc0qqAO1MNv/k05G4qslmsndV/5WdNZrqCiyqiz3wohia2Ij2B7w2Dr7/IyrA==
[email protected] | development | BlueOak-1.0.0
[email protected] | runtime | BlueOak-1.0.0
Lockfile path: node_modules/minipass
Package: https://www.npmjs.com/package/minipass/v/7.1.3
Archive: https://registry.npmjs.org/minipass/-/minipass-7.1.3.tgz
@@ -3680,11 +3670,11 @@ [email protected] | development | MIT
Package: https://www.npmjs.com/package/path-parse/v/1.0.7
Archive: https://registry.npmjs.org/path-parse/-/path-parse-1.0.7.tgz
Integrity: sha512-LDJzPVEEEPR+y48z93A0Ed0yXb8pAByGWo/k5YYdYgpY2/2EsOsksJrq7lOHxryrVOn1ejG6oAp8ahvOIQD8sw==
path-scurry@3.0.0 | development | BlueOak-1.0.0
path-scurry@2.0.2 | runtime | BlueOak-1.0.0
Lockfile path: node_modules/path-scurry
Package: https://www.npmjs.com/package/path-scurry/v/3.0.0
Archive: https://registry.npmjs.org/path-scurry/-/path-scurry-3.0.0.tgz
Integrity: sha512-1pTbQqH1wIwMi/eleQ5leFTTCkzFsPcgXNjwOA8YGGW/W4/kHT3dssE7Z6NH+zuqNLOzOB0uaD61yl7cAcVhgg==
Package: https://www.npmjs.com/package/path-scurry/v/2.0.2
Archive: https://registry.npmjs.org/path-scurry/-/path-scurry-2.0.2.tgz
Integrity: sha512-3O/iVVsJAPsOnpwWIeD+d6z/7PmqApyQePUtCndjatj/9I5LylHvt5qluFaBT3I5h3r1ejfR056c+FCv+NnNXg==
[email protected] | development | MIT
Lockfile path: node_modules/perfect-debounce
Package: https://www.npmjs.com/package/perfect-debounce/v/1.0.0
@@ -4680,11 +4670,11 @@ [email protected] | development | MIT
Package: https://www.npmjs.com/package/esbuild/v/0.25.12
Archive: https://registry.npmjs.org/esbuild/-/esbuild-0.25.12.tgz
Integrity: sha512-bbPBYYrtZbkt6Os6FiTLCTFxvq4tt3JKall1vRwshA3fdVztsLAatFaZobhkBC8/BrPetoa0oksYoKXoG4ryJg==
[email protected].5 | development | MIT
[email protected].4 | development | MIT
Lockfile path: node_modules/vitepress/node_modules/vite
Package: https://www.npmjs.com/package/vite/v/6.4.5
Archive: https://registry.npmjs.org/vite/-/vite-6.4.5.tgz
Integrity: sha512-4enwjFfi4IwtEh0w+jPzpLVOFQiPHmmzPxcHXQOyEur47o6u0jE573DmGpjA+7irXoMLYRZD5ZaFUEneS3abPg==
Package: https://www.npmjs.com/package/vite/v/6.4.4
Archive: https://registry.npmjs.org/vite/-/vite-6.4.4.tgz
Integrity: sha512-xGjU/SyjeNyb0E4KxXBvYz/1C+3JXuujvf2hXNOtnlcE+58o5ajd9N2/n2VhkiJvpCP2qQasnUpx5PXNeI+p1Q==
[email protected] | development | MIT
Lockfile path: node_modules/vitest
Package: https://www.npmjs.com/package/vitest/v/5.0.3
+331 -1
View File
@@ -1,7 +1,7 @@
REA third-party npm runtime copyright, license and NOTICE texts
Collected from integrity-verified locked npm archives. Release-specific supplements and upstream notice gaps are identified in their entries.
External engines are separately obtained; see THIRD_PARTY_NOTICES.md.
Runtime dependency fingerprint (SHA-256): 0119b7e66d63524f25c35f294b3264a901b764282b7d3bd1d0b493a9143498d0
Runtime dependency fingerprint (SHA-256): 13e2e43ee348b0cc210699dff53278d47e9e94c65934796c82eabc912f7c3938
===== @babel/[email protected] =====
Declared license: MIT
@@ -443,6 +443,68 @@ The above copyright notice and this permission notice shall be included in all c
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
===== @electron/[email protected] =====
Declared license: MIT
Archive: https://registry.npmjs.org/@electron/asar/-/asar-4.2.0.tgz
Integrity: sha512-npW1NW5yy8EB9XY/vEw9sUdgmq0sJEhmSBb6bqyFOAw1CSkrhvAvO6QWlW8CdIMo8VN1lkdF345l/MeW0LrY0Q==
Scope: npm runtime dependency, including optional platform packages.
--- package/LICENSE.md ---
Copyright (c) 2014 GitHub Inc.
Permission is hereby granted, free of charge, to any person obtaining
a copy of this software and associated documentation files (the
"Software"), to deal in the Software without restriction, including
without limitation the rights to use, copy, modify, merge, publish,
distribute, sublicense, and/or sell copies of the Software, and to
permit persons to whom the Software is furnished to do so, subject to
the following conditions:
The above copyright notice and this permission notice shall be
included in all copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
===== [email protected] =====
Declared license: MIT
Archive: https://registry.npmjs.org/commander/-/commander-13.1.0.tgz
Integrity: sha512-/rFeCpNJQbhSZjGVwO9RFV3xPqbnERS8MmIQzCtD/zl6gpJuV/bMLuN92oG3F7d8oDEHHRrujSXNUr8fpjntKw==
Scope: npm runtime dependency, including optional platform packages.
--- package/LICENSE ---
(The MIT License)
Copyright (c) 2011 TJ Holowaychuk <[email protected]>
Permission is hereby granted, free of charge, to any person obtaining
a copy of this software and associated documentation files (the
'Software'), to deal in the Software without restriction, including
without limitation the rights to use, copy, modify, merge, publish,
distribute, sublicense, and/or sell copies of the Software, and to
permit persons to whom the Software is furnished to do so, subject to
the following conditions:
The above copyright notice and this permission notice shall be
included in all copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED 'AS IS', WITHOUT WARRANTY OF ANY KIND,
EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY
CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT,
TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
===== @jridgewell/[email protected] =====
Declared license: MIT
Archive: https://registry.npmjs.org/@jridgewell/resolve-uri/-/resolve-uri-3.1.2.tgz
@@ -4060,6 +4122,79 @@ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.
===== [email protected] =====
Declared license: BlueOak-1.0.0
Archive: https://registry.npmjs.org/glob/-/glob-13.0.6.tgz
Integrity: sha512-Wjlyrolmm8uDpm/ogGyXZXb1Z+Ca2B8NbJwqBVg0axK9GbBeoS7yGV6vjXnYdGm6X53iehEuxxbyiKp8QmN4Vw==
Scope: npm runtime dependency, including optional platform packages.
--- package/LICENSE.md ---
All packages under `src/` are licensed according to the terms in
their respective `LICENSE` or `LICENSE.md` files.
The remainder of this project is licensed under the Blue Oak
Model License, as follows:
-----
# Blue Oak Model License
Version 1.0.0
## Purpose
This license gives everyone as much permission to work with
this software as possible, while protecting contributors
from liability.
## Acceptance
In order to receive this license, you must agree to its
rules. The rules of this license are both obligations
under that agreement and conditions to your license.
You must not do anything with this software that triggers
a rule that you cannot or will not follow.
## Copyright
Each contributor licenses you to do everything with this
software that would otherwise infringe that contributor's
copyright in it.
## Notices
You must ensure that everyone who gets a copy of
any part of this software from you, with or without
changes, also gets the text of this license or a link to
<https://blueoakcouncil.org/license/1.0.0>.
## Excuse
If anyone notifies you in writing that you have not
complied with [Notices](#notices), you can keep your
license by taking all practical steps to comply within 30
days after the notice. If you do not do so, your license
ends immediately.
## Patent
Each contributor licenses you to do everything with this
software that would otherwise infringe any patent claims
they can license or become able to license.
## Reliability
No contributor can revoke this license.
## No Liability
***As far as the law allows, this software comes as is,
without any warranty or condition, and no contributor
will be liable to anyone for any damages related to this
software or this license, under any kind of legal claim.***
===== [email protected] =====
Declared license: MIT
Archive: https://registry.npmjs.org/gopd/-/gopd-1.2.0.tgz
@@ -4965,6 +5100,71 @@ The above copyright notice and this permission notice shall be included in all c
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
===== [email protected] =====
Declared license: BlueOak-1.0.0
Archive: https://registry.npmjs.org/lru-cache/-/lru-cache-11.5.2.tgz
Integrity: sha512-4pfM1Ff0x50o0tQwb5ucw/RzNyD0/YJME6IVcStalZuMWxdt3sR3huStTtxz4PUmvZfRguvDejasvQ2kifR11g==
Scope: npm runtime dependency, including optional platform packages.
--- package/LICENSE.md ---
# Blue Oak Model License
Version 1.0.0
## Purpose
This license gives everyone as much permission to work with
this software as possible, while protecting contributors
from liability.
## Acceptance
In order to receive this license, you must agree to its
rules. The rules of this license are both obligations
under that agreement and conditions to your license.
You must not do anything with this software that triggers
a rule that you cannot or will not follow.
## Copyright
Each contributor licenses you to do everything with this
software that would otherwise infringe that contributor's
copyright in it.
## Notices
You must ensure that everyone who gets a copy of
any part of this software from you, with or without
changes, also gets the text of this license or a link to
<https://blueoakcouncil.org/license/1.0.0>.
## Excuse
If anyone notifies you in writing that you have not
complied with [Notices](#notices), you can keep your
license by taking all practical steps to comply within 30
days after the notice. If you do not do so, your license
ends immediately.
## Patent
Each contributor licenses you to do everything with this
software that would otherwise infringe any patent claims
they can license or become able to license.
## Reliability
No contributor can revoke this license.
## No Liability
***As far as the law allows, this software comes as is,
without any warranty or condition, and no contributor
will be liable to anyone for any damages related to this
software or this license, under any kind of legal claim.***
===== [email protected] =====
Declared license: MIT
Archive: https://registry.npmjs.org/math-intrinsics/-/math-intrinsics-1.1.0.tgz
@@ -5142,6 +5342,71 @@ IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTI
USE OR OTHER DEALINGS IN THE SOFTWARE.
===== [email protected] =====
Declared license: BlueOak-1.0.0
Archive: https://registry.npmjs.org/minipass/-/minipass-7.1.3.tgz
Integrity: sha512-tEBHqDnIoM/1rXME1zgka9g6Q2lcoCkxHLuc7ODJ5BxbP5d4c2Z5cGgtXAku59200Cx7diuHTOYfSBD8n6mm8A==
Scope: npm runtime dependency, including optional platform packages.
--- package/LICENSE.md ---
# Blue Oak Model License
Version 1.0.0
## Purpose
This license gives everyone as much permission to work with
this software as possible, while protecting contributors
from liability.
## Acceptance
In order to receive this license, you must agree to its
rules. The rules of this license are both obligations
under that agreement and conditions to your license.
You must not do anything with this software that triggers
a rule that you cannot or will not follow.
## Copyright
Each contributor licenses you to do everything with this
software that would otherwise infringe that contributor's
copyright in it.
## Notices
You must ensure that everyone who gets a copy of
any part of this software from you, with or without
changes, also gets the text of this license or a link to
<https://blueoakcouncil.org/license/1.0.0>.
## Excuse
If anyone notifies you in writing that you have not
complied with [Notices](#notices), you can keep your
license by taking all practical steps to comply within 30
days after the notice. If you do not do so, your license
ends immediately.
## Patent
Each contributor licenses you to do everything with this
software that would otherwise infringe any patent claims
they can license or become able to license.
## Reliability
No contributor can revoke this license.
## No Liability
***As far as the law allows, this software comes as is,
without any warranty or condition, and no contributor
will be liable to anyone for any damages related to this
software or this license, under any kind of legal claim.***
===== [email protected] =====
Declared license: MIT
Archive: https://registry.npmjs.org/on-exit-leak-free/-/on-exit-leak-free-2.1.2.tgz
@@ -5472,6 +5737,71 @@ The above copyright notice and this permission notice shall be included in all c
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
===== [email protected] =====
Declared license: BlueOak-1.0.0
Archive: https://registry.npmjs.org/path-scurry/-/path-scurry-2.0.2.tgz
Integrity: sha512-3O/iVVsJAPsOnpwWIeD+d6z/7PmqApyQePUtCndjatj/9I5LylHvt5qluFaBT3I5h3r1ejfR056c+FCv+NnNXg==
Scope: npm runtime dependency, including optional platform packages.
--- package/LICENSE.md ---
# Blue Oak Model License
Version 1.0.0
## Purpose
This license gives everyone as much permission to work with
this software as possible, while protecting contributors
from liability.
## Acceptance
In order to receive this license, you must agree to its
rules. The rules of this license are both obligations
under that agreement and conditions to your license.
You must not do anything with this software that triggers
a rule that you cannot or will not follow.
## Copyright
Each contributor licenses you to do everything with this
software that would otherwise infringe that contributor's
copyright in it.
## Notices
You must ensure that everyone who gets a copy of
any part of this software from you, with or without
changes, also gets the text of this license or a link to
<https://blueoakcouncil.org/license/1.0.0>.
## Excuse
If anyone notifies you in writing that you have not
complied with [Notices](#notices), you can keep your
license by taking all practical steps to comply within 30
days after the notice. If you do not do so, your license
ends immediately.
## Patent
Each contributor licenses you to do everything with this
software that would otherwise infringe any patent claims
they can license or become able to license.
## Reliability
No contributor can revoke this license.
## No Liability
***As far as the law allows, this software comes as is,
without any warranty or condition, and no contributor
will be liable to anyone for any damages related to this
software or this license, under any kind of legal claim.***
===== [email protected] =====
Declared license: MIT
Archive: https://registry.npmjs.org/pify/-/pify-4.0.1.tgz
+15 -48
View File
@@ -13,6 +13,7 @@
"@babel/types": "8.0.4",
"@bufbuild/protobuf": "2.16.0",
"@clack/prompts": "1.7.0",
"@electron/asar": "4.2.0",
"@jridgewell/trace-mapping": "0.3.31",
"@lydell/node-pty": "1.1.0",
"@modelcontextprotocol/client": "2.3.1",
@@ -57,7 +58,6 @@
"rea-agents": "scripts/rea.mjs"
},
"devDependencies": {
"@electron/asar": "4.2.0",
"@fast-check/vitest": "0.5.0",
"@stryker-mutator/core": "10.0.0",
"@stryker-mutator/typescript-checker": "10.0.0",
@@ -1252,7 +1252,6 @@
"version": "4.2.0",
"resolved": "https://registry.npmjs.org/@electron/asar/-/asar-4.2.0.tgz",
"integrity": "sha512-npW1NW5yy8EB9XY/vEw9sUdgmq0sJEhmSBb6bqyFOAw1CSkrhvAvO6QWlW8CdIMo8VN1lkdF345l/MeW0LrY0Q==",
"dev": true,
"license": "MIT",
"dependencies": {
"commander": "^13.1.0",
@@ -1270,7 +1269,6 @@
"version": "13.1.0",
"resolved": "https://registry.npmjs.org/commander/-/commander-13.1.0.tgz",
"integrity": "sha512-/rFeCpNJQbhSZjGVwO9RFV3xPqbnERS8MmIQzCtD/zl6gpJuV/bMLuN92oG3F7d8oDEHHRrujSXNUr8fpjntKw==",
"dev": true,
"license": "MIT",
"engines": {
"node": ">=18"
@@ -2157,13 +2155,6 @@
}
}
},
"node_modules/@isaacs/nonrecursive-glob-match": {
"version": "1.1.0",
"resolved": "https://registry.npmjs.org/@isaacs/nonrecursive-glob-match/-/nonrecursive-glob-match-1.1.0.tgz",
"integrity": "sha512-GPm/Dbvk5RLmhRnxXIa7nTpK0xtl4E0wj0MslsuNiJ1FIROU+2+9lgUC/dgF7Ey4QCWhfEsgxilMRMCdHPfDfw==",
"dev": true,
"license": "BlueOak-1.0.0"
},
"node_modules/@jridgewell/gen-mapping": {
"version": "0.4.0-beta.0",
"resolved": "https://registry.npmjs.org/@jridgewell/gen-mapping/-/gen-mapping-0.4.0-beta.0.tgz",
@@ -6224,7 +6215,6 @@
"version": "4.0.4",
"resolved": "https://registry.npmjs.org/balanced-match/-/balanced-match-4.0.4.tgz",
"integrity": "sha512-BLrgEcRTwX2o6gGxGOCNyMvGSp35YofuYzw9h1IMTRmKqttAZZVU67bdb9Pr2vUHA8+j3i2tJfjO6C6+4myGTA==",
"devOptional": true,
"license": "MIT",
"engines": {
"node": "18 || 20 || >=22"
@@ -6353,7 +6343,6 @@
"version": "5.0.12",
"resolved": "https://registry.npmjs.org/brace-expansion/-/brace-expansion-5.0.12.tgz",
"integrity": "sha512-YovQ3rzhaLMIrDjNDMkNS01tea93qhEhG5xy8f6+R0l+dw3Ki+5sCoIoI942iuLZTHWogWktgwVDhU09iNEimQ==",
"devOptional": true,
"license": "MIT",
"dependencies": {
"balanced-match": "^4.0.2"
@@ -8092,15 +8081,14 @@
"optional": true
},
"node_modules/glob": {
"version": "14.0.4",
"resolved": "https://registry.npmjs.org/glob/-/glob-14.0.4.tgz",
"integrity": "sha512-mMiwNKoJZ4HAIRVJxotO6LsNRReA30gQwP9E2/p94tfLv+jygCNpKDjhhSL6OLY6LE371EZm5EAf7RpYuUqlsw==",
"dev": true,
"version": "13.0.6",
"resolved": "https://registry.npmjs.org/glob/-/glob-13.0.6.tgz",
"integrity": "sha512-Wjlyrolmm8uDpm/ogGyXZXb1Z+Ca2B8NbJwqBVg0axK9GbBeoS7yGV6vjXnYdGm6X53iehEuxxbyiKp8QmN4Vw==",
"license": "BlueOak-1.0.0",
"dependencies": {
"minimatch": "^11.0.5",
"minimatch": "^10.2.2",
"minipass": "^7.1.3",
"path-scurry": "^3.0.0"
"path-scurry": "^2.0.2"
},
"engines": {
"node": "18 || 20 || >=22"
@@ -8109,23 +8097,6 @@
"url": "https://github.com/sponsors/isaacs"
}
},
"node_modules/glob/node_modules/minimatch": {
"version": "11.0.5",
"resolved": "https://registry.npmjs.org/minimatch/-/minimatch-11.0.5.tgz",
"integrity": "sha512-snPlVppFcYWfLLFQGhDxUyBcHNtMlWmn3jtj7pEaO+DP8pqL0IvAzXhMYmn1z9ASNtgmwLBdFxSf4tMUB0OTKA==",
"dev": true,
"license": "BlueOak-1.0.0",
"dependencies": {
"@isaacs/nonrecursive-glob-match": "^1.1.0",
"brace-expansion": "^5.0.12"
},
"engines": {
"node": "20 || >=22"
},
"funding": {
"url": "https://github.com/sponsors/isaacs"
}
},
"node_modules/gopd": {
"version": "1.2.0",
"resolved": "https://registry.npmjs.org/gopd/-/gopd-1.2.0.tgz",
@@ -9408,10 +9379,9 @@
"license": "MIT"
},
"node_modules/lru-cache": {
"version": "11.5.3",
"resolved": "https://registry.npmjs.org/lru-cache/-/lru-cache-11.5.3.tgz",
"integrity": "sha512-U4N8FgzmWxc8k1VH8Kr6lQg18U7Fjvby6wXHVRX/ZZ7IwWbRMgrRbP0Wrb5q5NVinryp4SQampHKdvtecItxUg==",
"dev": true,
"version": "11.5.2",
"resolved": "https://registry.npmjs.org/lru-cache/-/lru-cache-11.5.2.tgz",
"integrity": "sha512-4pfM1Ff0x50o0tQwb5ucw/RzNyD0/YJME6IVcStalZuMWxdt3sR3huStTtxz4PUmvZfRguvDejasvQ2kifR11g==",
"license": "BlueOak-1.0.0",
"engines": {
"node": "20 || >=22"
@@ -9719,7 +9689,6 @@
"version": "10.2.5",
"resolved": "https://registry.npmjs.org/minimatch/-/minimatch-10.2.5.tgz",
"integrity": "sha512-MULkVLfKGYDFYejP07QOurDLLQpcjk7Fw+7jXS2R2czRQzR56yHRveU5NDJEOviH+hETZKSkIk5c+T23GjFUMg==",
"devOptional": true,
"license": "BlueOak-1.0.0",
"dependencies": {
"brace-expansion": "^5.0.5"
@@ -9778,7 +9747,6 @@
"version": "7.1.3",
"resolved": "https://registry.npmjs.org/minipass/-/minipass-7.1.3.tgz",
"integrity": "sha512-tEBHqDnIoM/1rXME1zgka9g6Q2lcoCkxHLuc7ODJ5BxbP5d4c2Z5cGgtXAku59200Cx7diuHTOYfSBD8n6mm8A==",
"dev": true,
"license": "BlueOak-1.0.0",
"engines": {
"node": ">=16 || 14 >=14.17"
@@ -10474,10 +10442,9 @@
"license": "MIT"
},
"node_modules/path-scurry": {
"version": "3.0.0",
"resolved": "https://registry.npmjs.org/path-scurry/-/path-scurry-3.0.0.tgz",
"integrity": "sha512-1pTbQqH1wIwMi/eleQ5leFTTCkzFsPcgXNjwOA8YGGW/W4/kHT3dssE7Z6NH+zuqNLOzOB0uaD61yl7cAcVhgg==",
"dev": true,
"version": "2.0.2",
"resolved": "https://registry.npmjs.org/path-scurry/-/path-scurry-2.0.2.tgz",
"integrity": "sha512-3O/iVVsJAPsOnpwWIeD+d6z/7PmqApyQePUtCndjatj/9I5LylHvt5qluFaBT3I5h3r1ejfR056c+FCv+NnNXg==",
"license": "BlueOak-1.0.0",
"dependencies": {
"lru-cache": "^11.0.0",
@@ -13467,9 +13434,9 @@
}
},
"node_modules/vitepress/node_modules/vite": {
"version": "6.4.5",
"resolved": "https://registry.npmjs.org/vite/-/vite-6.4.5.tgz",
"integrity": "sha512-4enwjFfi4IwtEh0w+jPzpLVOFQiPHmmzPxcHXQOyEur47o6u0jE573DmGpjA+7irXoMLYRZD5ZaFUEneS3abPg==",
"version": "6.4.4",
"resolved": "https://registry.npmjs.org/vite/-/vite-6.4.4.tgz",
"integrity": "sha512-xGjU/SyjeNyb0E4KxXBvYz/1C+3JXuujvf2hXNOtnlcE+58o5ajd9N2/n2VhkiJvpCP2qQasnUpx5PXNeI+p1Q==",
"dev": true,
"license": "MIT",
"dependencies": {
+2 -5
View File
@@ -361,6 +361,7 @@
"@babel/types": "8.0.4",
"@bufbuild/protobuf": "2.16.0",
"@clack/prompts": "1.7.0",
"@electron/asar": "4.2.0",
"@jridgewell/trace-mapping": "0.3.31",
"@lydell/node-pty": "1.1.0",
"@modelcontextprotocol/client": "2.3.1",
@@ -401,18 +402,14 @@
"zod": "4.6.6"
},
"overrides": {
"@electron/asar": {
"glob": "14.0.4"
},
"typed-rest-client": {
"qs": "6.16.1"
},
"vitepress": {
"vite": "6.4.5"
"vite": "6.4.4"
}
},
"devDependencies": {
"@electron/asar": "4.2.0",
"@fast-check/vitest": "0.5.0",
"@stryker-mutator/core": "10.0.0",
"@stryker-mutator/typescript-checker": "10.0.0",
+2
View File
@@ -98,6 +98,8 @@ const PATH_SCOPES = {
"tests/boundary/providers/GdbCommandQueue.test.ts",
"tests/boundary/providers/gdbTestHelpers.ts",
"tests/boundary/providers/RizinDebugSessionCoverage.part*.test.ts",
"tests/boundary/providers/RizinCommandTimeout.test.ts",
"tests/boundary/providers/RizinTimeoutEvidence.test.ts",
"tests/boundary/providers/RizinDebugSession*.test.ts",
"tests/boundary/providers/RizinInferiorTty.test.ts",
"tests/boundary/providers/RizinDecoderInputs.test.ts",
@@ -1,123 +0,0 @@
import assert from "node:assert/strict";
import { randomUUID } from "node:crypto";
import { readFile, rm, writeFile } from "node:fs/promises";
import { join } from "node:path";
import { parseBinaryTarget } from "../../dist/application/BinaryTargetResolver.js";
import { createAnalysisProfile } from "../../dist/domain/analysisProfile.js";
import {
createAnalysisSnapshotEntry,
parseAnalysisSnapshot,
serializeAnalysisSnapshot,
snapshotBinding,
snapshotTarget,
} from "../../dist/domain/analysisSnapshot.js";
import { createEvidence } from "../../dist/domain/evidence.js";
import { createEvidenceBundle } from "../../dist/domain/evidenceBundle.js";
import {
requireMcpLifecycleResult,
requireMcpOutput,
requireMcpToolError,
} from "./mcp-verifier-results.mjs";
/** A pre-scope dossier must not be replayed into a newly qualified trace. */
export async function verifyLegacyValueScopeSnapshot(
client,
{ target, procedure, observed, env },
) {
const { value_flow_effect_scope: scope, ...legacyParameters } =
observed.analysis_profile.parameters;
const legacyProfile = createAnalysisProfile(
observed.provider,
legacyParameters,
);
const parsed = await parseBinaryTarget(target.path, {
cwd: process.cwd(),
hostArchitecture: process.arch,
});
if (!parsed.ok) throw parsed.error;
const nativeTarget = parsed.value;
const result = structuredClone(observed.normalized_result);
const flow = result.native_value_flow;
assert.equal(flow.available, true);
const describesScope = (value) =>
value.includes("LOAD and STORE") && value.includes("address varnodes");
assert.ok(flow.limitations.some(describesScope));
flow.limitations = flow.limitations.filter((value) => !describesScope(value));
const evidence = createEvidence(nativeTarget, observed.provider, {
operation: observed.operation,
parameters: observed.parameters,
result,
rawResult: result,
analysisProfile: legacyProfile,
limitations: observed.limitations,
locations: observed.locations,
});
const binding = snapshotBinding(legacyProfile);
const identity = snapshotTarget(nativeTarget);
const snapshot = parseAnalysisSnapshot({
target: identity,
binding,
entries: [
createAnalysisSnapshotEntry({
target: identity,
binding,
operation: observed.operation,
parameters: observed.parameters,
execution: {
result,
rawResult: result,
provider: observed.provider,
analysisProfile: legacyProfile,
limitations: observed.limitations,
locations: observed.locations,
subject: nativeTarget,
},
}),
],
workflow_entries: [],
evidence_bundle: createEvidenceBundle([evidence]),
});
const path = join(env.TMPDIR, `legacy-value-scope-${randomUUID()}.json`);
await writeFile(path, serializeAnalysisSnapshot(snapshot), { flag: "wx" });
try {
const bytes = await readFile(path);
const session = requireMcpLifecycleResult(
await client.callTool({ name: "binary_session", arguments: {} }),
"binary_session",
);
const reply = await client.callTool({
name: "open_binary",
arguments: {
path: target.path,
provider_id: "ghidra",
snapshot_path: path,
},
});
assert.equal(reply.isError, true);
assert.equal(scope, "pcode-load-store-explicit-v1");
const error = requireMcpToolError(reply);
assert.equal(error.code, "evidence_integrity_mismatch");
assert.deepEqual(error.details.binding_mismatch.profile_digest, {
snapshot: legacyProfile.digest,
selected: observed.analysis_profile.digest,
});
assert.deepEqual(
requireMcpLifecycleResult(
await client.callTool({ name: "binary_session", arguments: {} }),
"binary_session",
),
session,
);
const fresh = await client.callTool(
{ name: "trace_native_values", arguments: { procedure, max_depth: 0 } },
{ timeout: 180000 },
);
assert.notEqual(fresh.isError, true, JSON.stringify(fresh));
const trace = requireMcpOutput(fresh, "trace_native_values");
assert.ok(trace.normalized_result.limitations.some(describesScope));
assert.deepEqual(await readFile(path), bytes);
} finally {
await rm(path);
}
}
-35
View File
@@ -17,7 +17,6 @@ import {
requireMcpOutput,
} from "./mcp-verifier-results.mjs";
import { verifyGhidraBoundaries } from "./real-ghidra-boundaries.mjs";
import { verifyLegacyValueScopeSnapshot } from "./ghidra-value-scope-snapshot-e2e.mjs";
import { verifyGhidraProjectIdentity } from "./real-ghidra-project-identity.mjs";
import { verifyGhidraSocketBoundary } from "./real-ghidra-socket-boundary.mjs";
@@ -215,14 +214,6 @@ async function verifyNativeValueAdapters(
procedure,
globalAddress,
);
assert.ok(
mcpGraph.limitations.some(
(value) =>
value.includes("analyze_function") &&
value.includes("LOAD and STORE") &&
value.includes("address varnodes"),
),
);
assert.deepEqual(mcpEvidence.normalized_result, mcpGraph);
assert.deepEqual(mcpGraph, cliGraph);
const warmReply = await client.callTool(
@@ -252,26 +243,6 @@ async function verifyNativeValueAdapters(
);
assert.equal(functionEvidence.operation, "analyze_function");
assert.equal(functionEvidence.provider.id, "ghidra");
const flow = functionEvidence.normalized_result.native_value_flow;
assert.equal(flow.available, true);
const identifiesEffectScope = (value) =>
value.includes("LOAD and STORE") && value.includes("address varnodes");
assert.ok(flow.limitations.some(identifiesEffectScope));
const effectsView = await client.callTool({
name: "inspect_analysis_view",
arguments: {
source: {
kind: "retained-evidence",
evidence_id: functionEvidence.evidence_id,
},
view: { kind: "native", facet: "value_flow_effects" },
},
});
assert.notEqual(effectsView.isError, true, JSON.stringify(effectsView));
const effectsPage = requireMcpOutput(effectsView, "inspect_analysis_view");
assert.ok(
effectsPage.normalized_result.limitations.some(identifiesEffectScope),
);
assert.deepEqual(
functionEvidence.normalized_result.facet_availability,
Object.fromEntries(
@@ -297,12 +268,6 @@ async function verifyNativeValueAdapters(
functionEvidence.analysis_profile,
);
assert.deepEqual(functionProfile, upstreamProfile);
await verifyLegacyValueScopeSnapshot(client, {
target,
procedure,
observed: functionEvidence,
env,
});
const comparisonEvidence = await compareRetainedFunctionEvidence(
client,
functionEvidence,
+9 -54
View File
@@ -12,7 +12,6 @@ import { StdioClientTransport } from "@modelcontextprotocol/client/stdio";
import { parseEvidence } from "../dist/domain/evidence.js";
import { goBinarySchema } from "../dist/domain/go/goBinary.js";
import { PrivateRuntimeRoot } from "../dist/process/PrivateRuntimeRoot.js";
import { artifactMcpCall } from "./lib/artifact-e2e.mjs";
import { requireMcpOutput } from "./lib/mcp-verifier-results.mjs";
import { createVerifierRun, completeVerifierRun } from "./lib/verifier-run.mjs";
@@ -281,7 +280,7 @@ async function prepareFixture() {
);
await writeFile(
join(sourceRoot, "dependency", "dependency.go"),
'package dependency\nvar Endpoints = []string{"ListResourceProviders", "genai", "https://example.invalid/v1"}\nfunc Value() string { return "REA fixture:" + Endpoints[0] + Endpoints[1] + Endpoints[2] }\n',
'package dependency\nfunc Value() string { return "REA fixture" }\n',
);
await writeFile(
join(sourceRoot, "main.go"),
@@ -346,29 +345,18 @@ func main() {
);
}
async function inspect(mode, path, includeStringLiterals = false) {
async function inspect(mode, path) {
let envelope;
if (mode === "cli") {
const args = [
entrypoint,
"inspect-go-binary",
path,
...(includeStringLiterals ? ["--include-string-literals"] : []),
"--json",
];
const { stdout } = await execute(process.execPath, args, {
env: environment,
timeout: 30_000,
maxBuffer: 16 * 1024 * 1024,
});
const { stdout } = await execute(
process.execPath,
[entrypoint, "inspect-go-binary", path, "--json"],
{ env: environment, timeout: 30_000, maxBuffer: 8 * 1024 * 1024 },
);
envelope = JSON.parse(stdout);
} else {
const argumentsPayload = includeStringLiterals
? { path, include_string_literals: true }
: { path };
const response = await artifactMcpCall(
client,
{ name: "inspect_go_binary", arguments: argumentsPayload },
const response = await client.callTool(
{ name: "inspect_go_binary", arguments: { path } },
{ timeout: 30_000 },
);
envelope = requireMcpOutput(response, "inspect_go_binary");
@@ -380,37 +368,6 @@ async function inspect(mode, path, includeStringLiterals = false) {
return { evidence, report };
}
async function verifyStringLiterals(path, bytes) {
const cliResult = await inspect("cli", path, true);
const mcpResult = await inspect("mcp", path, true);
assert.deepEqual(
cliResult.report,
mcpResult.report,
"CLI and MCP string_literals projections disagree",
);
const literals = cliResult.report.string_literals;
assert.notEqual(literals, undefined);
assert.equal(literals.evidence_kind, "inferred");
for (const item of literals.items) {
const slice = bytes.subarray(
item.location.offset,
item.location.offset + item.location.bytes,
);
assert.equal(slice.toString("utf8"), item.value);
}
const values = new Set(literals.items.map((item) => item.value));
for (const expected of [
"ListResourceProviders",
"genai",
"https://example.invalid/v1",
])
assert.equal(
values.has(expected),
true,
`Missing expected Go string literal ${expected} in ${path}`,
);
}
async function verify(
path,
target,
@@ -449,7 +406,6 @@ async function verify(
report.artifact.sha256,
createHash("sha256").update(bytes).digest("hex"),
);
assert.equal(report.string_literals, undefined);
const info = report.build_info;
assert.notEqual(info, null);
assert.equal(info.go_version, expected.GoVersion);
@@ -487,7 +443,6 @@ async function verify(
reports[1],
"Public CLI and MCP projections disagree",
);
if (byteExpected === null) await verifyStringLiterals(path, bytes);
verified.push({
target: `${target[0]}/${target[1]}`,
file: byteExpected === null ? fileKind : "byte-valued-strings",
+2 -2
View File
@@ -32,9 +32,9 @@ const VERSION_TIMEOUT_MS = 10_000;
const ADB_VERSION_REMEDIATION = `Set ${ADB_BINARY_ENV} to an Android SDK Platform-Tools adb binary whose \`adb version\` reports its version, or put one on PATH.`;
/** Repair when the selected adb binary does not exist. */
const ADB_MISSING_REMEDIATION = `Set ${ADB_BINARY_ENV} to an absolute path to an existing adb binary.`;
export const ADB_MISSING_REMEDIATION = `Set ${ADB_BINARY_ENV} to an absolute path to an existing adb binary.`;
/** Repair when execution of the adb binary selected by the environment is denied. */
const ADB_NOT_EXECUTABLE_REMEDIATION = `Set ${ADB_BINARY_ENV} to an absolute path to the adb executable file, not a directory, and check execute permission on it and search permission on its parent directories.`;
export const ADB_NOT_EXECUTABLE_REMEDIATION = `Set ${ADB_BINARY_ENV} to an absolute path to the adb executable file, not a directory, and check execute permission on it and search permission on its parent directories.`;
const VERSION_MAX_OUTPUT_BYTES = 64 * 1024;
/** How the adb binary was selected for this provider instance. */
-41
View File
@@ -48,7 +48,6 @@ import { PrivateRuntimeRoot } from "../process/PrivateRuntimeRoot.js";
import { projectAnalysisError } from "../domain/analysisErrorProjection.js";
import { parseEvidence } from "../domain/evidence.js";
import type { AdbRequest } from "../domain/adb/adbDeviceAnalysis.js";
import { awaitAcknowledgement } from "../../tests/fixtures/lifecycleAcknowledgement.js";
const it = test.skipIf(process.platform === "win32");
@@ -130,46 +129,6 @@ it("inspects the adb client without contacting the server", async () => {
expect(result.contacted_adb_server).toBe(false);
});
it("joins an admitted availability probe before close and refuses later probes", async () => {
const { binary, root } = await writeAdbStub(
(directory) => `if [ "$1" = "version" ]; then
: > '${directory}/started'
while [ ! -f '${directory}/release' ]; do /bin/sleep 0.05; done
${VERSION_BLOCK}
fi`,
);
const provider = providerOver(binary);
const inspection = provider.inspectAvailability();
let closing: Promise<void> | undefined;
try {
await awaitAcknowledgement(
vi.waitFor(
async () => expect(await lstat(join(root, "started"))).toBeDefined(),
{ timeout: 10_000 },
),
inspection,
"ADB version probe",
10_000,
);
let closed = false;
closing = provider.close().then(() => {
closed = true;
});
await new Promise<void>((resolve) => setImmediate(resolve));
expect(closed).toBe(false);
await writeFile(join(root, "release"), "");
expect((await inspection).status).toBe("available");
await closing;
await expect(provider.inspectAvailability()).rejects.toMatchObject({
_tag: "AnalysisCancelledError",
});
} finally {
await writeFile(join(root, "release"), "");
await Promise.allSettled([inspection, closing]);
await provider.close();
}
}, 15_000);
it("fails closed when adb exits successfully without a recognized version", async () => {
const stdout = `unexpected adb output ${"x".repeat(700)}\n`;
const stderr = `probe stderr ${"y".repeat(700)}\n`;
+6 -21
View File
@@ -872,11 +872,6 @@ export class AdbProvider {
async inspectAvailability(
signal?: AbortSignal,
): Promise<ProviderAvailability> {
if (this.#closing)
throw new AnalysisCancelledError("inspect_adb_client", {
cause: signal?.reason,
});
const release = this.#beginOperation();
try {
const selection = await this.selection(signal);
await inspectAdbClient(selection, signal);
@@ -893,24 +888,9 @@ export class AdbProvider {
if (cause instanceof AdbConfigurationFailure)
return adbConfigurationAvailability(cause);
throw cause;
} finally {
release();
}
}
/** Keep admitted probes and requests owned until their final cleanup settles. */
#beginOperation(): () => void {
let release!: () => void;
const active = new Promise<void>((resolve) => {
release = resolve;
});
this.#activeOperations.add(active);
return () => {
this.#activeOperations.delete(active);
release();
};
}
/** Retry removal of owned output directories retained after failed cleanup. */
close(): Promise<void> {
this.#closing = true;
@@ -1264,7 +1244,11 @@ export class AdbProvider {
): Promise<Result<AnalysisExecution, AnalysisError>> {
if (this.#closing)
return err(new AnalysisCancelledError(request.operation));
const release = this.#beginOperation();
let release!: () => void;
const active = new Promise<void>((resolve) => {
release = resolve;
});
this.#activeOperations.add(active);
try {
try {
await this.#resources.retryCleanup();
@@ -1305,6 +1289,7 @@ export class AdbProvider {
}
return await this.#executeOperation(request, options);
} finally {
this.#activeOperations.delete(active);
release();
}
}
+5 -7
View File
@@ -31,11 +31,9 @@ const provider = () =>
environment: { REA_APKTOOL_COMMAND: "/authored/apktool" },
});
const version = {
stdout: { text: "2.9.3\n", bytes: 6, observedBytes: 6 },
stderr: { text: "", bytes: 0, observedBytes: 0 },
exitCode: 0,
signal: null,
};
stdout: { text: "2.9.3\n" },
stderr: { text: "" },
} as Awaited<ReturnType<typeof runOwnedCommand>>;
const inspect = (client: ApktoolProvider, signal?: AbortSignal) =>
client.execute(
{ operation: "inspect_apktool_client", input: {} },
@@ -257,8 +255,8 @@ it("attributes prerequisite cleanup to decode and preserves its live recovery",
try {
const result = await client.execute({
operation: "decode_android_resources",
input: { path: "/fixture/input.apk", include_strings: false },
});
input: {},
} as never);
if (result.ok) throw new Error("Expected prerequisite failure");
expect(result.error).toMatchObject({
operation: "decode_android_resources",
+2 -2
View File
@@ -48,9 +48,9 @@ const apktoolVersionProbeTimeoutGuidance = (): {
const APKTOOL_VERSION_REMEDIATION = `Set ${APKTOOL_COMMAND_ENV} to an Apktool 2.7.0 or newer launcher whose --version prints its version, or put one on PATH.`;
/** Repair when the selected apktool launcher does not exist. */
const APKTOOL_MISSING_REMEDIATION = `Set ${APKTOOL_COMMAND_ENV} to an absolute apktool launcher (the upstream wrapper or a java -jar script).`;
export const APKTOOL_MISSING_REMEDIATION = `Set ${APKTOOL_COMMAND_ENV} to an absolute apktool launcher (the upstream wrapper or a java -jar script).`;
/** Repair when execution of the selected apktool launcher is denied. */
const APKTOOL_NOT_EXECUTABLE_REMEDIATION = `Check file type and execute permission for ${APKTOOL_COMMAND_ENV} or select an executable apktool launcher.`;
export const APKTOOL_NOT_EXECUTABLE_REMEDIATION = `Check file type and execute permission for ${APKTOOL_COMMAND_ENV} or select an executable apktool launcher.`;
/** How the apktool launcher was selected for this provider instance. */
export interface ApktoolCommandSelection {
+5 -9
View File
@@ -49,15 +49,11 @@ afterEach(() => {
vi.mocked(runOwnedCommand).mockReset();
});
const completed = (text: string): ProviderProcessSnapshot => {
const bytes = Buffer.byteLength(text);
return {
stdout: { text, bytes, observedBytes: bytes },
stderr: { text: "", bytes: 0, observedBytes: 0 },
exitCode: 0,
signal: null,
};
};
const completed = (text: string): ProviderProcessSnapshot =>
({
stdout: { text },
stderr: { text: "" },
}) as ProviderProcessSnapshot;
const installLauncher = (): void => {
vi.mocked(runOwnedCommand).mockImplementation(async (spawn, limits) => {
+9 -10
View File
@@ -1555,12 +1555,12 @@ it("discloses qualified and unfamiliar strings tables while preserving exact loc
locale: locale ?? null,
coverage: "complete",
});
const otherTables = result.value.limitations.find((line) =>
line.includes("values-unknown_CONFIGURATION"),
expect(result.value.limitations).toContain(
`Other strings tables are not selected by locale; their resource configuration suffixes are preserved without inferring Android runtime matching: ${tables
.map((suffix) => JSON.stringify(`values-${suffix}`))
.sort()
.join(", ")}`,
);
expect(otherTables).toMatch(/without inferring.*runtime matching/iu);
for (const suffix of tables)
expect(otherTables).toContain(JSON.stringify(`values-${suffix}`));
if (locale === undefined)
expect(result.value.result).toMatchObject({
strings: [
@@ -1570,8 +1570,8 @@ it("discloses qualified and unfamiliar strings tables while preserving exact loc
});
else if (locale === "en-rUS") {
expect(result.value.result).toMatchObject({ strings: [] });
expect(result.value.limitations).toContainEqual(
expect.stringMatching(/strings\.xml.*locale en-rUS/iu),
expect(result.value.limitations).toContain(
"No strings.xml was found for locale en-rUS",
);
} else
expect(result.value.result).toMatchObject({
@@ -1691,9 +1691,8 @@ it.each([
});
const limitations = result.value.limitations.join("\n");
if (kind === "unsupported") {
expect(limitations).toMatch(/omitted[^\n]*2/iu);
expect(limitations).toMatch(
/omitted.*unsupported markup.*missing names/iu,
expect(limitations).toContain(
"String entries omitted due to unsupported markup or missing names: 2",
);
expect(limitations).not.toContain("entry counts are unknown");
} else {
+8 -12
View File
@@ -36,11 +36,9 @@ const owner = {
it("runs the version probe as an owned interpreter-script process group", async () => {
vi.mocked(runOwnedCommand).mockImplementationOnce(async (_spawn, limits) => {
const output = {
stdout: { text: "2.9.3\n", bytes: 6, observedBytes: 6 },
stderr: { text: "", bytes: 0, observedBytes: 0 },
exitCode: 0,
signal: null,
};
stdout: { text: "2.9.3\n" },
stderr: { text: "" },
} as Awaited<ReturnType<typeof runOwnedCommand>>;
limits.observeCompleted?.(output);
return output;
});
@@ -154,8 +152,8 @@ it("keeps unresolved probe cleanup typed when the launcher overflows its output"
vi.mocked(runOwnedCommand).mockRejectedValueOnce(overflow());
const result = await provider.execute({
operation: "decode_android_resources",
input: { path: "/fixture/input.apk", include_strings: false },
});
input: {},
} as never);
expect(result.ok ? null : result.error.cleanupIncomplete).toBe(true);
expect(result.ok ? null : projectAnalysisError(result.error)).toMatchObject({
code: "cleanup_incomplete",
@@ -171,11 +169,9 @@ it.each(["linux", "win32"] as const)(
vi.mocked(runOwnedCommand).mockImplementationOnce(
async (_spawn, limits) => {
const output = {
stdout: { text: "2.9.2\n", bytes: 6, observedBytes: 6 },
stderr: { text: "", bytes: 0, observedBytes: 0 },
exitCode: 0,
signal: null,
};
stdout: { text: "2.9.2\n" },
stderr: { text: "" },
} as Awaited<ReturnType<typeof runOwnedCommand>>;
limits.observeCompleted?.(output);
return output;
},
+13 -30
View File
@@ -14,12 +14,10 @@ import {
import {
omitUnretainedEvidenceFromError,
projectAnalysisError,
unretainedEvidenceCandidates,
type AnalysisErrorProjection,
} from "../domain/analysisErrorProjection.js";
import { analysisErrorWithCleanupFailure } from "../domain/analysisErrorCleanup.js";
import { analysisErrorWithCancellation } from "../domain/analysisErrorCancellation.js";
import { EvidenceIntegrityError } from "../domain/evidenceErrors.js";
import type { JsonValue } from "../domain/jsonValue.js";
import { analysisBookmarkSchema } from "../domain/native/nativeInventory.js";
import { parseContainingProcedureResolution } from "../domain/native/nativeObservation.js";
@@ -133,25 +131,18 @@ export function* omitContextEvidenceForDelivery(
const candidates = names.flatMap((name) => {
const facet = context[name];
if (facet.state !== "unavailable" || facet.error === undefined) return [];
return [...unretainedEvidenceCandidates(facet.error)].map((candidate) => {
const size = estimateJsonStorage(candidate.value, {
maximumValueBytes: budgetBytes,
includeSerialized: false,
}).valueBytes;
return { name, candidate, size };
});
const compact = omitUnretainedEvidenceFromError(facet.error, limit);
if (compact === undefined) return [];
const partial = facet.error.details?.partial_observation;
const size = estimateJsonStorage(partial, {
maximumValueBytes: budgetBytes,
includeSerialized: false,
}).valueBytes;
return [{ name, facet, compact, size }];
});
candidates.sort((left, right) => right.size - left.size);
let current = context;
for (const { name, candidate } of candidates) {
const facet = current[name];
if (facet.state !== "unavailable" || facet.error === undefined) continue;
const compact = omitUnretainedEvidenceFromError(
facet.error,
limit,
candidate,
);
if (compact === undefined) continue;
for (const { name, facet, compact } of candidates) {
current = {
...current,
[name]: {
@@ -293,15 +284,12 @@ const unavailableFacet = (
}
if (
error instanceof AnalysisInputError ||
error instanceof AnalysisResourceConstraintError ||
(error instanceof EvidenceIntegrityError &&
error.sourcePublicationRecovery !== undefined)
error instanceof AnalysisResourceConstraintError
) {
const projected = projectAnalysisError(error);
if (
projected.code === "invalid_request" ||
projected.code === "resource_constraint" ||
projected.code === "evidence_integrity_mismatch"
projected.code === "resource_constraint"
)
return {
state: "unavailable",
@@ -320,11 +308,7 @@ const unavailableFacet = (
const isRequestLevelFailure = (error: AnalysisError): boolean =>
error._tag === "AnalysisCancelledError" ||
error._tag === "AnalysisTimeoutError" ||
error._tag === "NoBinaryOpenError" ||
(error.sourcePublicationRecovery !== undefined &&
!(error instanceof AnalysisInputError) &&
!(error instanceof AnalysisResourceConstraintError) &&
!(error instanceof EvidenceIntegrityError));
error._tag === "NoBinaryOpenError";
/** Wait for all facets and retain every unresolved cleanup owner. */
const contextFailure = (
@@ -371,8 +355,7 @@ const contextFailure = (
).bindCleanupDependencies([previous, failure]);
} else if (
!(failure instanceof AnalysisCancelledError) &&
(isRequestLevelFailure(failure) ||
failure.sourcePublicationRecovery !== undefined)
isRequestLevelFailure(failure)
) {
combined.retainSecondaryFailure(failure);
}
@@ -3,6 +3,7 @@ import { join } from "node:path";
import { describe, expect, it } from "vitest";
import { plistNestingLimitMessage } from "../domain/apple/plistValue.js";
import { resolveAppBundleExecutable } from "./AppBundleExecutable.js";
import { createTestTempDirectory } from "../../tests/fixtures/temporaryDirectory.js";
@@ -33,7 +34,7 @@ describe("OpenStep Info.plist nesting during app target resolution", () => {
error: {
path: join(app, "Contents", "Info.plist"),
cause: expect.objectContaining({
message: expect.stringMatching(/128 nesting levels/iu),
message: plistNestingLimitMessage(),
}),
},
});
-4
View File
@@ -164,10 +164,6 @@ const browserParameters = (
: "target_id" in input && observedOrigin !== undefined
? [observedOrigin]
: [],
...("discovery_timeout_ms" in input &&
input.discovery_timeout_ms !== undefined
? { discovery_timeout_ms: input.discovery_timeout_ms }
: {}),
...("command_timeout_ms" in input && input.command_timeout_ms !== undefined
? { command_timeout_ms: input.command_timeout_ms }
: {}),
@@ -18,7 +18,7 @@ import {
expectKeptPartial,
expectOutputError,
expectOwnerError,
} from "../../tests/fixtures/ownerObservationExpectation.js";
} from "./ownerObservationExpectation.fixture.js";
import { BrowserObservationError } from "../domain/browserObservationError.js";
import { err, ok } from "../domain/result.js";
import { passiveNetworkCapture } from "../../tests/fixtures/passiveNetworkCapture.js";
@@ -20,7 +20,7 @@ import {
expectDroppedPartial,
expectKeptPartial,
expectOwnerError,
} from "../../tests/fixtures/ownerObservationExpectation.js";
} from "./ownerObservationExpectation.fixture.js";
const scenario = browserScenarioInputSchema.parse({
browser: { mode: "launch", executable_path: "/fixture/chrome" },
+4 -11
View File
@@ -698,7 +698,8 @@ describe("partial navigation availability", () => {
expect(availability).toMatchObject({
reason: "provider_missing",
remediation: expect.stringMatching(/configure.*provider/i),
remediation:
"Configure a provider for one of: current_document, current_address, resolve_containing_procedure.",
modes: [
{
name: "current_selection",
@@ -717,13 +718,6 @@ describe("partial navigation availability", () => {
},
],
});
for (const operation of [
"current_document",
"current_address",
"resolve_containing_procedure",
]) {
expect(availability.remediation?.split(operation)).toHaveLength(2);
}
});
});
@@ -826,9 +820,8 @@ describe("binary_overview capability requirements", () => {
).toMatchObject({
available: false,
reason: "provider_missing",
remediation: expect.stringMatching(
/configure.*provider.*current_document.*list_documents/i,
),
remediation:
"Configure a provider for one of: current_document, list_documents.",
});
});
@@ -1,32 +1,34 @@
import { describe, expect, it } from "vitest";
import {
ClientConfigurationShapeError,
parseClientConfiguration,
shadowedClientServers,
} from "./ClientConfigurationDocument.js";
describe("parseClientConfiguration shape diagnostics", () => {
it.each([
["null root", "null", "root"],
["array root", "[]", "root"],
["string root", '"x"', "root"],
["null server table", '{"mcpServers":null,"keep":1}', "mcpServers"],
["array server table", '{"mcpServers":[],"keep":1}', "mcpServers"],
["string server table", '{"mcpServers":"x","keep":1}', "mcpServers"],
])("reports a non-object %s", (_label, text, location) => {
let error: unknown;
try {
parseClientConfiguration(text, "json");
} catch (cause: unknown) {
error = cause;
}
expect(error).toBeInstanceOf(ClientConfigurationShapeError);
if (!(error instanceof Error)) throw new Error("Expected shape error");
expect(error.message).toContain(location);
expect(error.message).toContain("object");
["null", "null"],
["array", "[]"],
["string", '"x"'],
] as const)("names a non-object JSON root (%s)", (_label, text) => {
expect(() => parseClientConfiguration(text, "json")).toThrow(
new TypeError("The configuration root must be an object"),
);
});
it.each([
["null", "null"],
["array", "[]"],
["string", '"x"'],
] as const)(
'names a non-object "mcpServers" value (%s)',
(_label, servers) => {
expect(() =>
parseClientConfiguration(`{"mcpServers":${servers},"keep":1}`, "json"),
).toThrow(new TypeError('"mcpServers" must be an object'));
},
);
it("still rejects unparsable JSON with SyntaxError", () => {
expect(() => parseClientConfiguration("not-json", "json")).toThrow(
SyntaxError,
+32 -85
View File
@@ -1,4 +1,3 @@
import { admitCompletedAnalysis } from "./investigation/admitCompletedAnalysis.js";
import type { EspFlashSelection } from "../domain/firmware/espFlashLocation.js";
import type { ExecutableFormatHint } from "../domain/dosCom.js";
import { dispatchQueuedInterrupts } from "../process/queuedInterrupts.js";
@@ -21,7 +20,10 @@ import {
tryParseEvidence,
withEvidenceCallerInputPath,
} from "../domain/evidence.js";
import { createImmutableEvidenceBundle } from "../domain/evidenceBundle.js";
import {
createImmutableEvidenceBundle,
type EvidenceBundle,
} from "../domain/evidenceBundle.js";
import {
retainAnalysisResultSources,
type AnalysisResultWithSources,
@@ -46,7 +48,6 @@ import {
AnalysisSnapshotMismatchError,
type PublishedEvidenceFile,
} from "../domain/evidenceErrors.js";
import { analysisErrorWithCancellation } from "../domain/analysisErrorCancellation.js";
import type { AnalysisError } from "../domain/analysisErrorBase.js";
import { access, stat } from "node:fs/promises";
import { absoluteCallerPath } from "../filesystem/callerPath.js";
@@ -156,6 +157,8 @@ export const runDirectAnalysis = async (
readonly entryPoint?: string;
readonly espFlash?: EspFlashSelection;
readonly includeEvidenceSources?: boolean;
/** Capture the exact session Evidence available to a one-shot CLI adapter. */
readonly onEvidenceBundle?: (bundle: EvidenceBundle) => void;
} = {},
): Promise<AnalysisResultWithSources<Evidence, JsonValue>> =>
withProcessCancellation(options.signal, (signal) =>
@@ -166,6 +169,9 @@ export const runDirectAnalysis = async (
...(options.includeEvidenceSources === true
? { includeEvidenceSources: true }
: {}),
...(options.onEvidenceBundle === undefined
? {}
: { onEvidenceBundle: options.onEvidenceBundle }),
...targetSelection(options),
...(options.providerId === undefined
? {}
@@ -281,13 +287,7 @@ export const runProviderAnalysis = async (
operationSignal,
);
await dispatchQueuedInterrupts();
if (!original.ok)
return err(
cliError(
retainFinalCancellation(original.error, tool, operationSignal),
path,
),
);
if (!original.ok) return err(cliError(original.error, path));
const evidence = withEvidenceCallerInputPath(original.value, path);
if (operationSignal.aborted)
return err(
@@ -331,7 +331,6 @@ export const runManagedProviderExecution = async (
tool: ManagedToolName,
signal?: AbortSignal,
parameters: Readonly<Record<string, JsonValue>> = {},
recoveryParameters?: Readonly<Record<string, JsonValue>>,
): Promise<Result<AnalysisExecution, AnalysisError>> =>
withProcessCancellation(signal, async (operationSignal) => {
const session = await dependencies.createManagedBinarySession();
@@ -340,14 +339,9 @@ export const runManagedProviderExecution = async (
async () => {
const opened = await session.open(path, { signal: operationSignal });
if (!opened.ok) return opened;
return recoveryParameters === undefined
? await session.execute(tool, parameters, { signal: operationSignal })
: await session.executeForDirectObservation(
tool,
parameters,
recoveryParameters,
{ signal: operationSignal },
);
return await session.execute(tool, parameters, {
signal: operationSignal,
});
},
managedAnalysisCleanupFailure,
);
@@ -368,7 +362,6 @@ const runManagedProviderAnalysis = async (
tool,
signal,
arguments_,
evidenceParameters,
);
if (!execution.ok) return execution;
const value = execution.value;
@@ -397,6 +390,7 @@ const runAnalysis = async (
readonly snapshotPath: string | undefined;
readonly signal: AbortSignal;
readonly evidenceParameters?: Readonly<Record<string, JsonValue>>;
readonly onEvidenceBundle?: (bundle: EvidenceBundle) => void;
readonly createSession?: () => BinarySession | Promise<BinarySession>;
readonly includeEvidenceSources?: boolean;
readonly providerId?: AnalysisProviderSelector;
@@ -530,6 +524,7 @@ const runAnalysis = async (
);
if (!captured.ok)
return err(captured.error.retainPartialObservation(evidence));
options.onEvidenceBundle?.(snapshot.evidence_bundle);
return ok(evidence);
}
}
@@ -639,6 +634,7 @@ const runAnalysis = async (
return err(written.error.retainPartialObservation(evidence));
}
}
options.onEvidenceBundle?.(session.exportEvidenceBundle());
return ok(evidence);
};
const outcome = await withSessionCleanup<{
@@ -646,35 +642,13 @@ const runAnalysis = async (
readonly cleanupError?: AnalysisError;
}>(
session,
async () => {
const result = await execute();
if (
!result.ok &&
result.error.sourcePublicationRecovery?.completed.kind ===
"retained-evidence"
) {
const retained = session.evidenceForAnalysis(
result.error.sourcePublicationRecovery.completed.evidence_id,
);
if (retained !== undefined)
result.error.sourcePublicationRecovery = {
...result.error.sourcePublicationRecovery,
completed: {
kind: "inline-evidence",
retention: "one-shot-session",
source_closure: "not-established",
evidence: retained,
},
};
}
return { result };
},
async () => ({ result: await execute() }),
(value, cleanupError) => ({ ...value, cleanupError }),
);
await dispatchQueuedInterrupts();
const result = outcome.result.ok
? completeProviderEvidence(outcome.result.value, signal)
: err(retainFinalCancellation(outcome.result.error, tool, signal));
: outcome.result;
if (!result.ok && publishedSnapshot !== undefined)
result.error.retainDiagnostics({
analysis_snapshot: { ...publishedSnapshot },
@@ -696,19 +670,6 @@ const runAnalysis = async (
};
};
/** Preserve an earlier failure and a cancellation observed during final cleanup. */
const retainFinalCancellation = (
failure: AnalysisError,
tool: string,
signal: AbortSignal,
): AnalysisError =>
signal.aborted
? analysisErrorWithCancellation(
failure,
new AnalysisCancelledError(tool, { cause: signal.reason }),
)
: failure;
const executeAnalysisTool = async (input: {
readonly session: BinarySession;
readonly openedTarget: BinaryTarget;
@@ -786,17 +747,12 @@ const executeAnalysisTool = async (input: {
: { cachePolicy: result.value.cachePolicy }),
});
}
let result = await session.executeForDirectObservation(
tool,
input.arguments,
input.evidenceParameters,
{
signal,
...(input.saveSnapshot && tool === "procedure_pseudo_code"
? { snapshotContext: "one-shot-target" as const }
: {}),
},
);
let result = await session.execute(tool, input.arguments, {
signal,
...(input.saveSnapshot && tool === "procedure_pseudo_code"
? { snapshotContext: "one-shot-target" as const }
: {}),
});
if (
tool === "xrefs" &&
typeof input.arguments.address === "string" &&
@@ -818,32 +774,23 @@ const executeAnalysisTool = async (input: {
);
if (!address.ok) return address;
if (address.value !== input.arguments.address)
result = await session.executeForDirectObservation(
result = await session.execute(
tool,
{ ...input.arguments, address: address.value },
input.evidenceParameters,
{ signal },
);
}
if (!result.ok) return result;
const observation = {
...result.value,
subject:
result.value.subject === undefined
? input.openedTarget
: result.value.subject,
};
const admitted = admitCompletedAnalysis(
tool,
input.evidenceParameters,
observation,
session.admitRecoveryObservation.bind(session),
);
if (!admitted.ok) return admitted;
const evidence = createAnalysisExecutionEvidence(
tool,
input.evidenceParameters,
observation,
{
...result.value,
subject:
result.value.subject === undefined
? input.openedTarget
: result.value.subject,
},
"observed",
);
return ok({ evidence });
+6 -40
View File
@@ -1,7 +1,4 @@
import {
sourcePublicationRecoveryOf,
type AnalysisError,
} from "../domain/analysisErrorBase.js";
import type { AnalysisError } from "../domain/analysisErrorBase.js";
import {
childFailureDiagnostics,
projectAnalysisError,
@@ -43,46 +40,15 @@ export const projectDirectAnalysisFailure = (
!Array.isArray(partial) &&
partial.kind === "unretained-evidence";
const observation = tryParseEvidence(wrapped ? partial.evidence : partial);
const rebound =
observation === undefined
? undefined
: withEvidenceCallerInputPath(observation, callerInputPath);
const completed = sourcePublicationRecoveryOf(error)?.completed;
const completedWithPath =
completed?.kind === "unretained-evidence" ||
completed?.kind === "inline-evidence"
? {
...completed,
evidence: withEvidenceCallerInputPath(
completed.evidence,
callerInputPath,
),
}
: completed?.kind === "unretained-observation"
? {
...completed,
observation: {
...completed.observation,
caller_input_path: callerInputPath,
},
}
: undefined;
if (rebound === undefined && completedWithPath === undefined)
return projection;
if (observation === undefined) return projection;
const rebound = withEvidenceCallerInputPath(observation, callerInputPath);
return {
...projection,
details: {
...projection.details,
...(rebound === undefined
? {}
: {
partial_observation: wrapped
? { ...partial, evidence: rebound }
: rebound,
}),
...(completedWithPath === undefined
? {}
: { completed_observation: completedWithPath }),
partial_observation: wrapped
? { ...partial, evidence: rebound }
: rebound,
},
};
};
+10 -13
View File
@@ -255,9 +255,8 @@ describe("doctor native analysis configuration", () => {
expect.objectContaining({
name: "hopper-startup-timeout",
ok: false,
detail: expect.stringMatching(
/REA_HOPPER_STARTUP_TIMEOUT_MS.*positive decimal integer/i,
),
detail:
"REA_HOPPER_STARTUP_TIMEOUT_MS: must be a positive decimal integer",
}),
);
expect(result.scope_checks).toContainEqual(
@@ -651,9 +650,8 @@ describe("doctor", () => {
ok: false,
classification: "config_drift",
detail: "/missing/ilspycmd",
remediation: expect.stringMatching(
/REA_ILSPY_CMD_PATH.*runnable ilspycmd/i,
),
remediation:
"Unset REA_ILSPY_CMD_PATH or point it at a runnable ilspycmd executable.",
});
});
@@ -671,9 +669,8 @@ describe("doctor", () => {
ok: false,
classification: "config_drift",
detail: configuredPath,
remediation: expect.stringMatching(
/HOPPER_LAUNCHER_PATH.*executable Hopper launcher/i,
),
remediation:
"Unset or update HOPPER_LAUNCHER_PATH to an executable Hopper launcher.",
});
});
});
@@ -741,7 +738,7 @@ describe("doctor installation identity", () => {
skill: {
installed_version: "10",
state: "stale",
remediation: expect.stringMatching(/rea setup.*update.*skill/i),
remediation: "Run rea setup to update the installed REA skill.",
},
});
});
@@ -754,14 +751,14 @@ describe("doctor installation identity", () => {
expect(result.healthy).toBe(false);
expect(result.identity?.skill).toMatchObject({
state: "missing",
remediation: expect.stringMatching(/rea setup.*update.*skill/i),
remediation: "Run rea setup to update the installed REA skill.",
});
expect(result.checks).toContainEqual({
name: "skill:identity",
ok: false,
classification: "config_drift",
detail: expect.stringMatching(/skill identity.*missing/i),
remediation: result.identity?.skill.remediation,
detail: "Installed REA skill identity is missing.",
remediation: "Run rea setup to update the installed REA skill.",
});
});
it("classifies an unreadable installed skill as unknown, not drift", async () => {
+12 -23
View File
@@ -367,28 +367,6 @@ const providerSettingSelections = (
]),
];
/** Render what the registration comparison established without inferring its effective environment. */
export const registrationEnvironmentDetail = (
client: string,
{
unrecorded,
differing,
unresolved,
}: NonNullable<ClientRegistrationStatus["provider_settings"]>,
): string =>
[
`Provider checks used this terminal's environment; what the server ${client} starts receives is unknown.`,
...(unrecorded.length === 0
? []
: [`Its registration does not record ${unrecorded.join(", ")}.`]),
...(differing.length === 0
? []
: [`It records other values for ${differing.join(", ")}.`]),
...(unresolved.length === 0
? []
: [`REA could not resolve its ${unresolved.join(", ")}.`]),
].join(" ");
/**
* A healthy provider check describes this terminal, not the server a client
* starts. Report what the registration's file leaves out without gating health:
@@ -407,7 +385,18 @@ const registrationEnvironmentChecks = (
name: `registration_environment:${client}`,
ok: true,
classification: "unknown" as const,
detail: registrationEnvironmentDetail(client, settings),
detail: [
`Provider checks used this terminal's environment; what the server ${client} starts receives is unknown.`,
...(unrecorded.length === 0
? []
: [`Its registration does not record ${unrecorded.join(", ")}.`]),
...(differing.length === 0
? []
: [`It records other values for ${differing.join(", ")}.`]),
...(unresolved.length === 0
? []
: [`REA could not resolve its ${unresolved.join(", ")}.`]),
].join(" "),
details: {
effective_environment: "unknown",
providers: selections
@@ -4,12 +4,7 @@ import { expect, it } from "vitest";
import { createTestTempDirectory } from "../../tests/fixtures/temporaryDirectory.js";
import { createDoctorHostFixture as host } from "./Doctor.fixture.js";
import {
registrationEnvironmentDetail,
runDoctor,
systemDoctorHost,
type DoctorHost,
} from "./Doctor.js";
import { runDoctor, systemDoctorHost, type DoctorHost } from "./Doctor.js";
const inspection = (
id: string,
@@ -181,16 +176,9 @@ it("states each comparison result without a claim it did not establish", async (
]),
}),
);
const check = report.checks.find(({ name }) => name === CHECK);
expect(check).toMatchObject({
classification: "unknown",
details: { effective_environment: "unknown" },
});
expect(check?.detail).toBe(
registrationEnvironmentDetail("cursor", {
unrecorded: [],
differing: ["JAVA_HOME"],
unresolved: ["GHIDRA_INSTALL_DIR"],
}),
);
const detail = report.checks.find(({ name }) => name === CHECK)?.detail;
expect(detail).toContain("what the server cursor starts receives is unknown");
expect(detail).toContain("records other values for JAVA_HOME");
expect(detail).toContain("could not resolve its GHIDRA_INSTALL_DIR");
expect(detail).not.toContain("does not record");
});
@@ -7,9 +7,9 @@ import type { AnalysisInputError } from "../domain/analysisErrorCore.js";
import type { AnalysisError } from "../domain/analysisErrorBase.js";
import {
createEvidence,
evidenceSubjectTarget,
type Evidence,
type EvidenceProvider,
type EvidenceSubjectTarget,
} from "../domain/evidence.js";
import type { JsonValue } from "../domain/jsonValue.js";
import type { ParsedInventorySet } from "../domain/artifactInventoryEvidence.js";
@@ -42,6 +42,7 @@ interface InventoryProjectionOptions<
readonly operation: string;
readonly predicateType: string;
readonly provider: EvidenceProvider;
readonly subjectFormat: (first: Evidence) => EvidenceSubjectTarget["format"];
}
/** Resolve source inventory once, then wrap its family projection in Evidence. */
@@ -69,7 +70,13 @@ export const projectInventoryEvidence = <
const first = source.value.evidence[0];
return ok({
evidence: createEvidence(
evidenceSubjectTarget(first?.subject ?? null),
first?.subject === null || first?.subject === undefined
? undefined
: {
path: first.subject.local_path,
sha256: result.root_sha256,
format: options.subjectFormat(first),
},
options.provider,
{
predicateType: options.predicateType,
@@ -1,7 +1,6 @@
import { describe, expect, it } from "vitest";
import {
estimateJsonStorage,
estimateJsonArrayScalarEntry,
requireAuthenticationHeadroom,
} from "./JsonAuthenticationHeadroom.js";
import { AnalysisResourceConstraintError } from "../domain/analysisErrorCore.js";
@@ -20,56 +19,6 @@ it("stops a bounded representation scan before visiting an over-budget tail", ()
expect(measured.valueBytes).toBeGreaterThan(512);
});
describe("JSON authentication headroom", () => {
it("measures source IDs without first constructing their array", () => {
const values = ["ev_123", null, 'escaped\"\n😀'];
const empty = estimateJsonStorage({ evidence_links: [] });
const incremental = values.reduce((total, value, index) => {
const entry = estimateJsonArrayScalarEntry(value, index > 0);
return {
valueBytes: total.valueBytes + entry.valueBytes,
serializedUtf16Bytes:
total.serializedUtf16Bytes + entry.serializedUtf16Bytes,
};
}, empty);
expect(incremental).toEqual(
estimateJsonStorage({ evidence_links: values }),
);
});
it("accounts for a measured representation that has not yet been allocated", () => {
const value = { result: "small" };
const base = estimateJsonStorage(value);
const additional = { valueBytes: 8192, serializedUtf16Bytes: 2048 };
const total =
(base.valueBytes +
base.serializedUtf16Bytes +
additional.valueBytes +
additional.serializedUtf16Bytes) *
2;
const request = {
operation: "address_name",
path: "recovery",
description: "Cannot authenticate",
additional,
};
expect(
requireAuthenticationHeadroom(value, {
...request,
availableBytes: total - 1,
}),
).toMatchObject({
ok: false,
error: {
resource: "memory",
reportedLimits: { authentication_bytes: total },
},
});
expect(
requireAuthenticationHeadroom(value, {
...request,
availableBytes: total,
}),
).toEqual({ ok: true, value: undefined });
});
it("does not queue every row while deciding whether a wide report can fit", () => {
let pending = 0;
let peak = 0;
+1 -22
View File
@@ -6,18 +6,6 @@ import { err, ok, type Result } from "../domain/result.js";
/** Authentication clones parsed JSON and hashes its canonical commitment. */
const AUTHENTICATION_COPIES = 2;
/** Incremental storage of a string or null appended to an already measured array. */
export const estimateJsonArrayScalarEntry = (
value: string | null,
hasPrevious: boolean,
): { valueBytes: number; serializedUtf16Bytes: number } => ({
valueBytes: 16 + (value === null ? 16 : 64 + value.length * 2),
serializedUtf16Bytes:
((value === null ? 4 : jsonStringCodeUnits(value)) +
(hasPrevious ? 1 : 0)) *
2,
});
/**
* Parsed storage and optional UTF-16 serialization work. A bounded value scan
* returns only a lower bound after exceeding maximumValueBytes.
@@ -89,20 +77,11 @@ export const requireAuthenticationHeadroom = (
readonly path: string;
readonly description: string;
readonly availableBytes?: number;
readonly additional?: {
readonly valueBytes: number;
readonly serializedUtf16Bytes: number;
};
},
): Result<void, AnalysisResourceConstraintError> => {
const availableBytes =
options.availableBytes ?? getHeapStatistics().total_available_size;
const estimate = estimateJsonStorage(value);
const valueBytes =
estimate.valueBytes + (options.additional?.valueBytes ?? 0);
const serializedUtf16Bytes =
estimate.serializedUtf16Bytes +
(options.additional?.serializedUtf16Bytes ?? 0);
const { valueBytes, serializedUtf16Bytes } = estimateJsonStorage(value);
// Canonical hashing and manifest normalization can still encode scalars or
// metadata; account for their escaped representations before allocating them.
const requiredBytes =
+22 -21
View File
@@ -10,6 +10,8 @@ import {
} from "./HopperDownload.js";
import {
installMacHopper,
macHopperHostVersionDetail,
macHopperIncomparableMinimumDetail,
type MacHopperBundleVerification,
type MacHopperBundleInstallResult,
type MacHopperInstallHost,
@@ -307,19 +309,17 @@ describe("macOS Hopper release host requirements", () => {
host.feedBytes = macFeed(host, { deployment_target: "12.4" });
const result = await installMacHopper({}, host);
expect(result).toMatchObject({
expect(result).toEqual({
status: "failed",
reason: "incompatible_host_version",
diagnostic: macHopperHostVersionDetail({
source: "release_feed",
packageUrl: PACKAGE_URL,
minimumVersion: "12.4",
hostVersion,
}),
});
expectNamed(result, [
PACKAGE_URL,
"12.4",
hostVersion,
"deployment_target",
]);
if (result.status !== "failed")
throw new Error("Expected version refusal");
expect(result.diagnostic).toMatch(/not downloaded/i);
expectNamed(result, [PACKAGE_URL, "12.4", hostVersion]);
expect(host.packageDownloads).toBe(0);
expect(host.mounts).toBe(0);
expect(host.installs).toBe(0);
@@ -353,14 +353,16 @@ describe("macOS Hopper release host requirements", () => {
host.feedBytes = macFeed(host, fields);
const result = await installMacHopper({}, host);
expect(result).toMatchObject({
expect(result).toEqual({
status: "failed",
reason: "incompatible_host_version",
diagnostic: macHopperHostVersionDetail({
source: "signed_app",
minimumVersion: "12.4",
hostVersion: "12.0",
}),
});
expectNamed(result, ["LSMinimumSystemVersion", "12.4", "12.0"]);
if (result.status !== "failed")
throw new Error("Expected version refusal");
expect(result.diagnostic).toMatch(/nothing was copied/i);
expect(host.packageDownloads).toBe(1);
expect(host.installs).toBe(0);
expect(host.opens).toBe(0);
@@ -398,13 +400,12 @@ describe("macOS Hopper release host requirements", () => {
host.appMinimum = "12.x";
const result = await installMacHopper({}, host);
expect(result).toMatchObject({ status: "failed", reason: "bundle" });
if (result.status !== "failed") throw new Error("Expected bundle failure");
expect(result.diagnostic).toContain("LSMinimumSystemVersion");
expect(result.diagnostic).toContain("12.x");
expect(result.diagnostic).toContain("14.5");
expect(result.diagnostic).toMatch(/cannot compare/i);
expect(result.diagnostic).toMatch(/nothing was copied/i);
expect(result).toEqual({
status: "failed",
reason: "bundle",
diagnostic: macHopperIncomparableMinimumDetail("12.x", "14.5"),
});
expectNamed(result, ['"12.x"', "14.5"]);
expect(host.installs).toBe(0);
expect(host.unmounts).toBe(1);
expect(host.cleanups).toBe(1);
+2 -2
View File
@@ -576,7 +576,7 @@ export const systemMacHopperInstallHost = (
};
/** Installer detail naming the declared minimum this Mac's version does not meet. */
const macHopperHostVersionDetail = (
export const macHopperHostVersionDetail = (
refusal: (
| { readonly source: "release_feed"; readonly packageUrl: string }
| { readonly source: "signed_app" }
@@ -587,7 +587,7 @@ const macHopperHostVersionDetail = (
: `The signed Hopper application declares LSMinimumSystemVersion ${refusal.minimumVersion}; this Mac runs macOS ${refusal.hostVersion}. Nothing was copied.`;
/** Installer detail for a signed-app minimum REA cannot compare with this Mac's version. */
const macHopperIncomparableMinimumDetail = (
export const macHopperIncomparableMinimumDetail = (
declared: string,
hostVersion: string,
): string =>
@@ -185,20 +185,10 @@ describe("semantic uncertainty at the obligation candidate boundary", () => {
expect(ledger.obligations).toHaveLength(1);
expect(ledger.reports.residual_unknown_ids).toEqual([]);
expect(ledger.coverage.status).toBe("partial");
expect(ledger.limitations).toHaveLength(2);
expect(ledger.limitations).toContainEqual(
expect.stringMatching(
/coverage is unknown.*omitted candidates remain unknown/iu,
),
);
expect(
ledger.limitations.every((limitation) =>
limitation.includes(source.graph.graph_id),
),
).toBe(true);
expect(ledger.limitations).toContainEqual(
expect.stringContaining("Event source was not fully examined."),
);
expect(ledger.limitations).toEqual([
`Semantic graph ${source.graph.graph_id} coverage is unknown; omitted candidates remain unknown.`,
`Semantic graph ${source.graph.graph_id}: Event source was not fully examined.`,
]);
});
it("keeps a complete semantic source complete without fabricating uncertainty", () => {
@@ -79,32 +79,10 @@ const applicationWithUnknowns = (
],
}),
);
const root = createJavaScriptApplicationNode({
kind: "artifact",
identity: {
strategy: "content-digest",
stability: "global-exact",
sha256: APPLICATION_GRAPH_DIGESTS.asar,
},
observations: [
{
label: "managed root",
properties: {},
evidence: artifactEvidence(
APPLICATION_GRAPH_DIGESTS.asar,
"artifact-root",
),
},
],
});
const graph = createJavaScriptApplicationGraph({
schema: "JavaScriptApplicationGraph",
root_node_ids: [root.node_id],
nodes: [
...base.nodes.filter(({ node_id }) => node_id !== root.node_id),
...unknownNodes,
root,
],
root_node_ids: base.root_node_ids,
nodes: [...base.nodes, ...unknownNodes],
edges: base.edges,
coverage: completeCoverage,
limitations: base.limitations,
@@ -220,11 +198,8 @@ describe("reconstruction obligation candidates", () => {
const generated = deriveCandidates(createEvidenceBundle([evidence]), []);
expect(generated.candidates).toEqual([]);
const warning = generated.limitations.find((value) =>
value.includes(evidence.evidence_id),
);
expect(warning).toMatch(
/process capture.*no validated executable artifact identity.*lifecycle obligation.*not bound to an artifact/iu,
expect(generated.limitations).toContain(
`Process capture ${evidence.evidence_id} has no validated executable artifact identity; packaged-process lifecycle obligation was not bound to an artifact.`,
);
});
@@ -254,11 +229,9 @@ describe("reconstruction obligation candidates", () => {
});
const generated = deriveCandidates(createEvidenceBundle([evidence]), []);
expect(generated.limitations).toHaveLength(1);
expect(generated.limitations[0]).toContain(evidence.evidence_id);
expect(generated.limitations[0]).toMatch(
/Process Evidence.*could not generate candidates.*manifest\.completed_at/iu,
);
expect(generated.limitations).toEqual([
`Process Evidence ${evidence.evidence_id} could not generate candidates: at manifest.completed_at: Invalid input: expected string, received undefined (1 more issues)`,
]);
});
});
@@ -346,22 +319,10 @@ it("keeps each semantic candidate bound to its own file and authority context",
createEvidenceBundle([...sourceRecords, application]),
[],
);
expect(generated.limitations).toHaveLength(2);
expect(generated.limitations).toContainEqual(
expect.stringMatching(
/coverage is unknown.*omitted candidates remain unknown/iu,
),
);
expect(
generated.limitations.every((limitation) =>
limitation.includes(semanticGraph.graph_id),
),
).toBe(true);
expect(generated.limitations).toContainEqual(
expect.stringContaining(
"Semantic relations are unavailable in this minimal example.",
),
);
expect(generated.limitations).toEqual([
`Semantic graph ${semanticGraph.graph_id} coverage is unknown; omitted candidates remain unknown.`,
`Semantic graph ${semanticGraph.graph_id}: Semantic relations are unavailable in this minimal example.`,
]);
expect(generated.candidates).toHaveLength(requests.length);
for (const [index, node] of requests.entries()) {
const source = sourceRecords[Math.floor(index / 2)];
@@ -304,10 +304,8 @@ describe("reconstruction obligation manifest references", () => {
expect(result.status).toBe("unknown");
expect(result.coverage.status).toBe("partial");
expect(result.evidence_links).toContain(absent);
expect(result.limitations).toContainEqual(
expect.stringMatching(
/1 Evidence reference.*absent from the input bundle.*closure cannot be claimed/iu,
),
expect(result.limitations).toContain(
"The ledger retains 1 Evidence reference(s) absent from the input bundle; closure cannot be claimed.",
);
}
const contradiction = build({
@@ -92,10 +92,9 @@ it("keeps source entries when a module has an empty specifier", () => {
"other.txt",
]);
expect(parsed.relationships).toEqual([]);
expect(parsed.limitations).toHaveLength(1);
expect(parsed.limitations[0]).toContain("main.mjs");
expect(parsed.limitations[0]).toMatch(/empty.*specifier/iu);
expect(parsed.limitations[0]).toMatch(/not recorded.*relationship/iu);
expect(parsed.limitations).toEqual([
"Empty module specifier in main.mjs was not recorded as a relationship.",
]);
});
it("retains Kotlin source identity and language across the inventory projection", () => {
@@ -754,3 +754,26 @@ describe("setup tool family scope", () => {
);
});
});
it("discloses the selected catalog profile before applying it with the family scope", async () => {
const host = new FakeSetupHost();
host.doctorHealthy = true;
host.skill = "unchanged";
host.clients = [{ name: "cursor", configPath: "/cursor.json" }];
const selection = {
clientIds: ["cursor"],
toolCatalogProfile: "hot-cold" as const,
toolFamilies: "session,application",
};
const plan = await runSetup({ ...options(false), ...selection }, host);
expect(plan.plannedActions[0]?.detail).toContain(
"REA_MCP_TOOL_CATALOG_PROFILE=hot-cold",
);
expect(host.configuredProviderEnvironments).toEqual([]);
const applied = await runSetup({ ...options(true), ...selection }, host);
expect(applied.status).toBe("ready");
expect(host.configuredProviderEnvironments).toContainEqual({
REA_MCP_TOOL_FAMILIES: "session,application",
REA_MCP_TOOL_CATALOG_PROFILE: "hot-cold",
});
});
+7 -2
View File
@@ -131,14 +131,19 @@ const runSetupWorkflow = async (
options.proposeHopper ?? (confirm !== undefined && !options.structured),
initialDoctor: initialState.doctor,
});
// The advertised family scope is a registration setting, not a detected
// provider fact; merge it after discovery so it cannot suppress the
// Catalog loading and family scope are registration settings, not detected
// provider facts; merge them after discovery so they cannot suppress the
// Hopper installation offer on an otherwise unconfigured machine.
if (options.toolFamilies !== undefined)
providerEnvironment = {
...providerEnvironment,
REA_MCP_TOOL_FAMILIES: options.toolFamilies,
};
if (options.toolCatalogProfile !== undefined)
providerEnvironment = {
...providerEnvironment,
REA_MCP_TOOL_CATALOG_PROFILE: options.toolCatalogProfile,
};
clientStates = discovery.clientStates;
const clientSelectionAllowed =
options.clientIds === undefined &&
+11 -20
View File
@@ -5,27 +5,20 @@ import { setupInstallFailure } from "./SetupInstallFailure.js";
describe("macOS Hopper setup failure projection", () => {
it("projects a publisher mismatch onto its own code and recovery", () => {
const result = setupInstallFailure("publisher_verification_failed");
expect(result).toMatchObject({
expect(setupInstallFailure("publisher_verification_failed")).toEqual({
status: "failed",
code: "publisher_verification_failed",
remediation: `The mounted Hopper application is not signed by the publisher REA pins (${HOPPER_PUBLISHER.bundleIdentifier}, Apple team ${HOPPER_PUBLISHER.teamIdentifier}); nothing was copied or launched. Install Hopper yourself and set HOPPER_LAUNCHER_PATH to its launcher, then rerun rea setup.`,
});
for (const fact of [
HOPPER_PUBLISHER.bundleIdentifier,
HOPPER_PUBLISHER.teamIdentifier,
"HOPPER_LAUNCHER_PATH",
"rea setup",
])
expect(result.remediation).toContain(fact);
expect(result.remediation).toMatch(/nothing was copied or launched/i);
});
it("keeps a broken bundle distinct from a publisher mismatch", () => {
const result = setupInstallFailure("bundle");
expect(result).toMatchObject({ status: "failed", code: "bundle_invalid" });
expect(result.remediation).toMatch(/bundle/i);
expect(result.remediation).toMatch(/retry setup/i);
expect(result.remediation).toMatch(/update REA/i);
expect(setupInstallFailure("bundle")).toEqual({
status: "failed",
code: "bundle_invalid",
remediation:
"The mounted package did not contain the expected Hopper application bundle. Retry setup; if it repeats, update REA before installing.",
});
});
it("keeps a host below the release minimum distinct from an unsupported host", () => {
@@ -66,14 +59,12 @@ describe("Linux package-manager setup failure projection", () => {
});
it("preserves the established remediation if no package output exists", () => {
const result = setupInstallFailure("authorization_or_package_manager");
expect(result).toMatchObject({
expect(setupInstallFailure("authorization_or_package_manager")).toEqual({
status: "failed",
code: "authorization_or_package_manager_failed",
remediation:
"Allow the system package-manager operation or install the planned Hopper package and Linux runtime dependencies, then rerun rea setup.",
});
expect(result.remediation).toMatch(/package.manager/i);
expect(result.remediation).toMatch(/Linux runtime dependencies/i);
expect(result.remediation).toContain("rea setup");
});
it("keeps truncated package output within its excerpt budget", () => {
-1
View File
@@ -34,7 +34,6 @@ export const MANAGED_SKILL_FILES = [
"references/runtime-observation.md",
"references/evidence-workflows.md",
"references/environments.md",
"references/desktop-build.md",
] as const;
export const isManagedSkillManifest = (content: string): boolean =>
+3
View File
@@ -1,4 +1,5 @@
import type { ClientConfigurationWriteProblem } from "./ClientConfigurationPublication.js";
import type { McpToolCatalogProfile } from "../config/mcpToolCatalogProfile.js";
import type { DoctorReport, DoctorScope, runDoctor } from "./Doctor.js";
import type { LinuxDistribution } from "./LinuxHopper.js";
import type { HopperRequestFailure } from "./HopperDownload.js";
@@ -240,6 +241,8 @@ export interface SetupOptions {
readonly installSkill?: boolean;
/** Comma-separated tool families the MCP registration advertises. */
readonly toolFamilies?: string;
/** Explicit catalog loading policy; omitted preserves the saved selection. */
readonly toolCatalogProfile?: McpToolCatalogProfile;
readonly readinessScope?: DoctorScope;
readonly dryRun?: boolean;
readonly allDetectedClients?: boolean;
+2 -2
View File
@@ -232,8 +232,8 @@ export const runUninstall = async (
};
/**
* Reread each client when editing and refuse detected changes before publication.
* A client that fails still stops the remaining removals.
* Each client is reread when it is edited, so a concurrent change is never
* overwritten. A client that fails then still stops the remaining removals.
*/
const removeAll = async (
clients: readonly UninstallClient[],
+33 -63
View File
@@ -1,13 +1,13 @@
import { describe, expect, it, vi } from "vitest";
import { describe, expect, it } from "vitest";
import { err, ok, type Result } from "../domain/result.js";
import { err, ok } from "../domain/result.js";
import { safeParseJson } from "../domain/safeJson.js";
import { PRODUCT_IDENTITY } from "../identity.js";
import {
UpdateCommandRunner,
type UpdateCommandFailure,
} from "./UpdateCommandRunner.js";
import { systemUpdateHost } from "./UpdateRuntime.js";
npmLatestVersionCommand,
npmReleaseLookup,
parseNpmLatestVersion,
} from "./UpdateRuntime.js";
const installation = {
manager: "npm",
@@ -15,30 +15,14 @@ const installation = {
packageRoot: "/opt/rea/lib/node_modules/rea-agents",
} as const;
const lookup = async (
response: Result<string, UpdateCommandFailure>,
selected: typeof installation | null = installation,
) => {
const probe = vi
.spyOn(UpdateCommandRunner.prototype, "runProbe")
.mockResolvedValue(response);
const host = systemUpdateHost();
try {
const result = await host.latestVersion(selected ?? undefined);
return { result, command: probe.mock.calls[0]?.[0] };
} finally {
await host.close?.();
probe.mockRestore();
}
};
describe("npm latest release metadata", () => {
it.each(['"6.0.0"', '[\n "6.0.0"\n]\n'])(
"accepts a scalar or singleton-array response: %j",
async (metadata) => {
expect((await lookup(ok(metadata))).result).toEqual(ok("6.0.0"));
},
);
it("accepts npm 11's scalar JSON response", () => {
expect(parseNpmLatestVersion('"6.0.0"')).toEqual(ok("6.0.0"));
});
it("accepts npm 12's singleton-array JSON response", () => {
expect(parseNpmLatestVersion('[\n "6.0.0"\n]\n')).toEqual(ok("6.0.0"));
});
it.each([
["empty array", "[]"],
@@ -47,52 +31,39 @@ describe("npm latest release metadata", () => {
["number", "6"],
["object", '{"version":"6.0.0"}'],
["null", "null"],
])("rejects %s response data", async (_description, metadata) => {
const { result } = await lookup(ok(metadata));
expect(result).toMatchObject({
ok: false,
error: { kind: "invalid-metadata" },
});
if (result.ok || result.error.kind !== "invalid-metadata")
throw new Error("Expected invalid metadata");
expect(result.error.detail).toMatch(
/version string.*single-element version array/i,
])("rejects %s response data", (_description, metadata) => {
expect(parseNpmLatestVersion(metadata)).toEqual(
err(
"Invalid npm release metadata: expected a version string or a single-element version array.",
),
);
});
it("preserves malformed JSON separately from a wrong metadata shape", async () => {
it("preserves malformed JSON separately from a wrong metadata shape", () => {
const metadata = '"6.0.0';
const decoded = safeParseJson(metadata);
if (decoded.ok) throw new Error("Expected malformed JSON");
expect((await lookup(ok(metadata))).result).toEqual(
err({ kind: "invalid-metadata", detail: decoded.error }),
);
expect(decoded.ok).toBe(false);
if (decoded.ok) return;
expect(parseNpmLatestVersion(metadata)).toEqual(err(decoded.error));
expect(decoded.error).not.toContain("single-element version array");
});
it("keeps command failures distinct from rejected metadata", async () => {
expect(
(
await lookup(
err({ kind: "execution", detail: "npm registry returned HTTP 503" }),
)
).result,
).toEqual(
it("keeps command failures distinct from rejected metadata", () => {
expect(npmReleaseLookup(err("npm registry returned HTTP 503"))).toEqual(
err({ kind: "unavailable", detail: "npm registry returned HTTP 503" }),
);
expect(
(await lookup(err({ kind: "launch", detail: "npm missing" }))).result,
).toEqual(
expect(npmReleaseLookup(ok("[]"))).toEqual(
err({
kind: "package-manager-unavailable",
manager: "npm",
detail: "npm missing",
kind: "invalid-metadata",
detail:
"Invalid npm release metadata: expected a version string or a single-element version array.",
}),
);
expect(npmReleaseLookup(ok('["6.0.0"]'))).toEqual(ok("6.0.0"));
});
it("keeps the global registry query and adds the owning prefix", async () => {
const selected = await lookup(ok('"6.0.0"'));
expect(selected.command).toEqual([
it("keeps the global registry query and adds the owning prefix", () => {
expect(npmLatestVersionCommand(installation)).toEqual([
"npm",
"view",
"--global",
@@ -104,8 +75,7 @@ describe("npm latest release metadata", () => {
"--fetch-retries=0",
"--fetch-timeout=10000",
]);
const unspecified = await lookup(ok('"6.0.0"'), null);
expect(unspecified.command).toEqual([
expect(npmLatestVersionCommand(undefined)).toEqual([
"npm",
"view",
"--global",
+5 -3
View File
@@ -153,7 +153,7 @@ export const BUN_LATEST_VERSION_COMMAND: readonly string[] = [
];
/** npm view arguments for dist-tags.latest, scoped to the owning prefix when known. */
const npmLatestVersionCommand = (
export const npmLatestVersionCommand = (
installation: NpmInstallation | undefined,
): readonly string[] => [
"npm",
@@ -171,7 +171,9 @@ const npmLatestVersionCommand = (
* Read one latest version from `npm view --json`.
* npm 11 emits a JSON string. npm 12 emits that string as a one-element array.
*/
const parseNpmLatestVersion = (metadata: string): Result<string, string> => {
export const parseNpmLatestVersion = (
metadata: string,
): Result<string, string> => {
const decoded = safeParseJson(metadata);
if (!decoded.ok) return err(decoded.error);
const version = readNpmLatestVersion(decoded.value);
@@ -191,7 +193,7 @@ const nonemptyVersion = (value: string): string | undefined =>
value.length === 0 ? undefined : value;
/** Classify `npm view` or `bun info` output as a version or a lookup failure. */
const npmReleaseLookup = (
export const npmReleaseLookup = (
response: Result<string, string>,
): Result<string, ReleaseLookupFailure> => {
if (!response.ok) return err({ kind: "unavailable", detail: response.error });
@@ -17,7 +17,6 @@ import {
AnalysisCleanupLeaseGroup,
} from "../artifacts/AnalysisCleanupLease.js";
import { ProviderCleanupError } from "../domain/providerCleanupError.js";
import { analysisErrorWithCleanupFailure } from "../domain/analysisErrorCleanup.js";
it.each(["REDACTED", "[", "]", "/capture.har"])(
"excludes sensitive path text even when a replacement marker would collide: %s",
@@ -143,9 +142,6 @@ it("projects the unknown-subject explanation before generating its Evidence ID",
});
if (!result.ok) throw result.error;
expect(result.value.subject).toBeNull();
expect(result.value.limitations).toContainEqual(
expect.stringMatching(/digest.*unknown.*Evidence/u),
);
expect(result.value.limitations.every((text) => !text.includes("a"))).toBe(
true,
);
@@ -250,26 +246,6 @@ it("does not expose a malformed capture-shaped partial observation", async () =>
if (!result.ok) expect(result.error.partialObservation).toBeUndefined();
});
it("does not recover a rejected capture from a cleanup primary", async () => {
const malformed = fixture();
malformed.artifact.sha256 = "invalid";
malformed.limitations = ["rejected-capture-only-marker"];
const primary = new AnalysisCancelledError("inspect_web_network_capture", {
partialObservation: malformed,
});
const cleanup = new ProviderCleanupError("fixture", ["workspace"], {});
const error = analysisErrorWithCleanupFailure(primary, cleanup);
const result = await new WebNetworkCaptureService({
inspect: async () => err(error),
}).inspect({ capture_path: "/capture.har", format: "har" });
if (result.ok) throw new Error("expected rejected capture");
const projected = projectAnalysisError(result.error);
expect(projected.code).toBe("cleanup_incomplete");
expect(JSON.stringify(projected)).not.toContain(
"rejected-capture-only-marker",
);
});
it("keeps a redacted cleanup error linked to its live owner through service close", async () => {
const report = fixture();
const cleanupPath = "/tmp/private-marker-capture-root";
+1 -9
View File
@@ -98,15 +98,7 @@ export class WebNetworkCaptureService {
);
}
if (partialFailure !== undefined) {
const rejected = loaded.error.partialObservation;
for (
let owner: AnalysisError | undefined = loaded.error;
owner !== undefined;
owner = owner.cleanupPrimary
) {
if (owner.partialObservation === rejected)
owner.partialObservation = undefined;
}
loaded.error.partialObservation = undefined;
partialFailure.retainSecondaryFailure(loaded.error);
return failure(
loaded.error.cleanupIncomplete
+1 -1
View File
@@ -17,7 +17,7 @@ import {
expectDroppedPartial,
expectKeptPartial,
expectOwnerError,
} from "../../tests/fixtures/ownerObservationExpectation.js";
} from "./ownerObservationExpectation.fixture.js";
import type { AnalysisError } from "../domain/analysisErrorBase.js";
import { parseEvidence } from "../domain/evidence.js";
@@ -106,7 +106,8 @@ it.each([
path: ["generated_position", "line"],
minimum: 1,
maximum: 2,
message: expect.stringMatching(/line 3.*line 2.*one-based/i),
message:
"No line 3; the retained script ends at line 2 (one-based lines).",
},
},
{
@@ -115,9 +116,8 @@ it.each([
path: ["generated_position", "column"],
minimum: 0,
maximum: 3,
message: expect.stringMatching(
/column 4.*line 1.*column 3.*zero-based UTF-16/i,
),
message:
"No column 4 on line 1; it ends at column 3 (zero-based UTF-16 columns).",
},
},
{
+19 -31
View File
@@ -10,34 +10,22 @@ export const workflowAnalysisProfile = (
upstream: AnalysisProfileCommitment,
operation?: AnalysisOperation,
): AnalysisProfileCommitment =>
createAnalysisProfile(
REA_WORKFLOW_PROVIDER,
workflowAnalysisProfileParameters(upstream, operation),
);
/** The owned profile shape, with null allowed when estimating its envelope. */
export const workflowAnalysisProfileParameters = (
upstream: AnalysisProfileCommitment | null,
operation?: AnalysisOperation,
) => ({
upstream_analysis_profile: upstream,
source_limitations: "provider-operation-caveats-v1",
...(operation === "trace_native_values"
? {
value_flow_limitations: "provider-attributed-v1",
value_flow_absence: "recorded-versus-unavailable-v1",
}
: {}),
...(operation === "binary_overview"
? { workflow_revision: 5 }
: operation === "batch_decompile"
? { workflow_revision: 4 }
: operation === "trace_feature"
? { workflow_revision: 9 }
: operation === "get_call_graph"
? { workflow_revision: 3 }
: operation === "trace_call_path" ||
operation === "trace_native_values"
? { workflow_revision: 2 }
: { workflow_revision: 1 }),
});
createAnalysisProfile(REA_WORKFLOW_PROVIDER, {
upstream_analysis_profile: upstream,
source_limitations: "provider-operation-caveats-v1",
...(operation === "trace_native_values"
? { value_flow_absence: "recorded-versus-unavailable-v1" }
: {}),
...(operation === "binary_overview"
? { workflow_revision: 5 }
: operation === "batch_decompile"
? { workflow_revision: 4 }
: operation === "trace_feature"
? { workflow_revision: 9 }
: operation === "get_call_graph"
? { workflow_revision: 3 }
: operation === "trace_call_path" ||
operation === "trace_native_values"
? { workflow_revision: 2 }
: { workflow_revision: 1 }),
});
-122
View File
@@ -1,12 +1,9 @@
import { describe, expect, it } from "vitest";
import { z } from "zod";
import {
recordWorkflowUnknowns,
createWorkflowEvidence,
executeComposedWorkflow,
retainComposedWorkflowSources,
retainPartialWorkflowEvidence,
workflowSnapshotRecord,
} from "./WorkflowEvidence.js";
import { InvestigationRecords } from "./investigation/InvestigationRecords.js";
@@ -21,7 +18,6 @@ import {
AnalysisResourceConstraintError,
} from "../domain/analysisErrorCore.js";
import { projectAnalysisError } from "../domain/analysisErrorProjection.js";
import { estimateJsonStorage } from "./JsonAuthenticationHeadroom.js";
import { nativeApiBoundarySchema } from "../domain/native/nativeApiBoundary.js";
import { projectNativeApiInspection } from "./native/NativeApiInspection.js";
import { functionDossierSchema } from "../domain/native/functionDossier.js";
@@ -29,124 +25,6 @@ import { ghidraFunctionDossier } from "../domain/ghidraValues.fixture.js";
import { ANALYSIS_SNAPSHOT_PROFILE } from "../domain/analysisSnapshot.fixture.js";
import { createEvidence } from "../domain/evidence.js";
it("preserves cleanup and reports an omitted partial when authentication headroom is unavailable", () => {
const error = new AnalysisCancelledError("get_call_graph", {
cleanup: { reason: "close failed", resources: ["session:fixture"] },
});
const outcome = {
...err(error),
partial: { result: { nodes: ["observed"] }, limitations: [] },
sourceEvidence: [],
};
retainPartialWorkflowEvidence(
outcome,
{
target: undefined,
operation: "get_call_graph",
parameters: {},
upstreamProfile: undefined,
},
() =>
err(
new AnalysisResourceConstraintError(
"get_call_graph",
"capacity",
"no headroom",
null,
),
),
);
expect(projectAnalysisError(error)).toMatchObject({
code: "cleanup_incomplete",
details: {
cleanup: "incomplete",
resources: ["session:fixture"],
partial_observation: {
kind: "omitted-observation",
reason: "insufficient-authentication-headroom",
},
},
});
});
it.each([0, 1, 100])(
"admits enough recovery representation for %i completed batch items",
(count) => {
const provider = { id: "fixture", name: "Fixture", version: "1" };
const source = createEvidence(undefined, provider, {
operation: "health",
parameters: {},
result: "source",
});
const items = Array.from({ length: count }, (_, index) => ({
address: `input-${index}`,
procedure: {
status: "resolved",
address: `0x${(index + 1).toString(16)}`,
name: null,
},
status: "ok",
pseudocode: 'escaped " and Unicode α'.repeat((index % 3) + 1),
}));
const completed = {
...ok({
result: { items, total: count, succeeded: count, failed: 0 },
limitations: [],
evidenceLinks: [source.evidence_id],
}),
sourceEvidence: [source],
};
let admitted: ReturnType<typeof estimateJsonStorage> | undefined;
const outcome = retainComposedWorkflowSources(
() =>
err(
new AnalysisResourceConstraintError(
"record_evidence",
"capacity",
"full",
null,
),
),
completed,
{
target: {
path: "/tmp/example",
sha256: "a".repeat(64),
kind: "executable",
format: "mach-o",
architecture: "arm64",
availableArchitectures: ["arm64"],
},
operation: "batch_decompile",
parameters: { addresses: items.map((item) => item.address) },
upstreamProfile: ANALYSIS_SNAPSHOT_PROFILE,
},
() => undefined,
(input, _operation, additional) => {
const base = estimateJsonStorage(input);
admitted = {
valueBytes: base.valueBytes + additional.valueBytes,
serializedUtf16Bytes:
base.serializedUtf16Bytes + additional.serializedUtf16Bytes,
};
return ok(undefined);
},
);
expect(outcome.ok).toBe(false);
if (outcome.ok || admitted === undefined)
throw new Error("Expected admitted recovery");
const error = projectAnalysisError(outcome.error);
const completedEvidence = z
.object({ completed_observation: z.object({ evidence: z.unknown() }) })
.parse(error.details).completed_observation.evidence;
const actual = estimateJsonStorage(completedEvidence);
expect(admitted.valueBytes).toBeGreaterThanOrEqual(actual.valueBytes);
expect(admitted.serializedUtf16Bytes).toBeGreaterThanOrEqual(
actual.serializedUtf16Bytes,
);
},
);
it("links shared provider source Evidence once without copying its payload into the workflow", async () => {
const source = createEvidence(
undefined,
+8 -174
View File
@@ -3,10 +3,7 @@ import { compareUnicodeCodePoints } from "../domain/unicodeCodePointOrder.js";
import { jsonStringByteLength } from "../domain/jsonStringByteLength.js";
import { createAnalysisExecutionEvidence } from "../domain/analysisObservation.js";
import { REA_WORKFLOW_PROVIDER } from "../domain/investigationProviders.js";
import {
workflowAnalysisProfile,
workflowAnalysisProfileParameters,
} from "./WorkflowAnalysisProfile.js";
import { workflowAnalysisProfile } from "./WorkflowAnalysisProfile.js";
import type {
AnalysisOperation,
AnalysisOperationPort,
@@ -23,8 +20,6 @@ import {
import type { BinaryTarget } from "../domain/binaryTargetTypes.js";
import {
createEvidence,
MISSING_EVIDENCE_SUBJECT_LIMITATION,
evidenceEnvelopeForAdmission,
type Evidence,
type EvidenceLocation,
} from "../domain/evidence.js";
@@ -34,16 +29,9 @@ import { UnknownRegistryError } from "../domain/unknownRegistryError.js";
import { EvidenceLedger } from "./investigation/EvidenceLedger.js";
import {
recordEvidenceSources,
retainAnalysisResultSources,
withEvidenceSources,
type AnalysisResultWithSources,
} from "./investigation/recordEvidenceSources.js";
import { preserveCompletedSourceEvidence } from "./investigation/sourcePublicationRecovery.js";
import {
admitInvestigationAuthentication,
type RecoveryAdmission,
} from "./investigation/InvestigationRetention.js";
import { estimateJsonStorage } from "./JsonAuthenticationHeadroom.js";
import { workflowUnknownInput } from "./investigation/WorkflowUnknown.js";
import {
renderSourceLimitations,
@@ -221,7 +209,7 @@ export const TRACE_FEATURE_REFERENCE_LIMITATION =
"Reference queries cover only each matched start address, not interior bytes of strings and procedures. Empty references and truncated: false do not establish complete reference coverage.";
/** Build the shared Evidence record for a successful composed binary workflow. */
export interface WorkflowEvidenceInput {
export const createWorkflowEvidence = (input: {
readonly target: BinaryTarget | undefined;
readonly operation: AnalysisOperation;
readonly parameters: Readonly<Record<string, JsonValue>>;
@@ -229,20 +217,7 @@ export interface WorkflowEvidenceInput {
readonly upstreamProfile: AnalysisProfileCommitment | undefined;
readonly upstreamLimitations: readonly string[];
readonly upstreamEvidenceLinks?: readonly string[];
}
const WORKFLOW_DERIVATION_LIMITATION = "Derived by an REA composed workflow.";
const workflowLimitations = (
operation: AnalysisOperation,
): readonly string[] =>
operation === "trace_feature"
? [WORKFLOW_DERIVATION_LIMITATION, TRACE_FEATURE_REFERENCE_LIMITATION]
: [WORKFLOW_DERIVATION_LIMITATION];
export const createWorkflowEvidence = (
input: WorkflowEvidenceInput,
): Evidence =>
}): Evidence =>
createEvidence(input.target, REA_WORKFLOW_PROVIDER, {
operation: input.operation,
parameters: input.parameters,
@@ -260,7 +235,10 @@ export const createWorkflowEvidence = (
? {}
: { evidenceLinks: input.upstreamEvidenceLinks }),
limitations: [
...workflowLimitations(input.operation),
"Derived by an REA composed workflow.",
...(input.operation === "trace_feature"
? [TRACE_FEATURE_REFERENCE_LIMITATION]
: []),
...input.upstreamLimitations,
],
...(input.operation === "batch_decompile"
@@ -268,128 +246,6 @@ export const createWorkflowEvidence = (
: {}),
});
const admitWorkflowRecovery = (
observation: ComposedWorkflowObservation,
evidenceInput: Pick<
WorkflowEvidenceInput,
"target" | "operation" | "parameters" | "upstreamProfile"
>,
admitRecovery: RecoveryAdmission,
) => {
const admissionInput = {
operation: evidenceInput.operation,
parameters: evidenceInput.parameters,
target:
evidenceInput.target === undefined
? null
: {
path: evidenceInput.target.path,
sha256: evidenceInput.target.sha256,
format: evidenceInput.target.format,
architecture: evidenceInput.target.architecture ?? null,
},
profile: evidenceInput.upstreamProfile ?? null,
result: observation.result,
limitations: observation.limitations,
links: observation.evidenceLinks ?? [],
};
// The completed result can also generate a location per batch item and
// the workflow profile embeds the upstream profile. Admit these copies
// before constructing or hashing the recovery Evidence.
const shell = evidenceEnvelopeForAdmission(
evidenceInput.target,
REA_WORKFLOW_PROVIDER,
{
operation: evidenceInput.operation,
parameters: {},
result: null,
...(evidenceInput.upstreamProfile === undefined
? {}
: {
analysisProfile: {
provider: REA_WORKFLOW_PROVIDER,
parameters: workflowAnalysisProfileParameters(
null,
evidenceInput.operation,
),
digest: "0".repeat(64),
},
}),
confidence: "derived",
limitations: workflowLimitations(evidenceInput.operation),
locations: [],
evidenceLinks: [],
},
);
const additional = estimateJsonStorage([
observation.result,
evidenceInput.upstreamProfile ?? null,
shell,
...(evidenceInput.target === undefined
? [MISSING_EVIDENCE_SUBJECT_LIMITATION]
: []),
]);
return admitRecovery(admissionInput, evidenceInput.operation, additional);
};
/** Experimental shared recovery of a workflow that completed before source admission. */
export const retainComposedWorkflowSources = (
recordEvidence: Parameters<typeof retainAnalysisResultSources>[1],
result: Awaited<ReturnType<typeof executeComposedWorkflow>>,
evidenceInput: Omit<
WorkflowEvidenceInput,
"result" | "upstreamLimitations" | "upstreamEvidenceLinks"
>,
evidenceForAnalysis?: (id: string) => Evidence | undefined,
admitRecovery: RecoveryAdmission = (input, operation, additional) =>
admitInvestigationAuthentication(input, operation, {}, additional),
): ReturnType<
typeof retainAnalysisResultSources<{
readonly result: JsonValue;
readonly limitations: readonly string[];
readonly cachePolicy?: "live";
readonly evidenceLinks?: readonly string[];
}>
> => {
const retained = retainAnalysisResultSources(
evidenceInput.operation,
recordEvidence,
result,
);
if (result.ok && !retained.ok) {
const admitted = admitWorkflowRecovery(
result.value,
evidenceInput,
admitRecovery,
);
if (!admitted.ok) {
retained.error.retainSourcePublication({
kind: "omitted",
reason:
admitted.error._tag === "AnalysisResourceConstraintError"
? "insufficient-authentication-headroom"
: "recovery-input-invalid",
source_closure: "not-established",
});
return retained;
}
const evidence = createWorkflowEvidence({
...evidenceInput,
result: result.value.result,
upstreamLimitations: result.value.limitations,
...(result.value.evidenceLinks === undefined
? {}
: { upstreamEvidenceLinks: result.value.evidenceLinks }),
});
preserveCompletedSourceEvidence(
retained.error,
evidence,
evidenceForAnalysis,
);
}
return retained;
};
/** Retain a stopped workflow's admitted observation as partial workflow Evidence on its failure. */
export const retainPartialWorkflowEvidence = (
outcome: ComposedWorkflowResult,
@@ -397,30 +253,8 @@ export const retainPartialWorkflowEvidence = (
Parameters<typeof createWorkflowEvidence>[0],
"target" | "operation" | "parameters" | "upstreamProfile"
>,
admitRecovery: RecoveryAdmission = (input, operation, additional) =>
admitInvestigationAuthentication(input, operation, {}, additional),
): void => {
if (
outcome.ok ||
outcome.partial === undefined ||
outcome.error.partialObservation !== undefined
)
return;
const admitted = admitWorkflowRecovery(
outcome.partial,
context,
admitRecovery,
);
if (!admitted.ok) {
outcome.error.retainPartialObservation({
kind: "omitted-observation",
reason:
admitted.error._tag === "AnalysisResourceConstraintError"
? "insufficient-authentication-headroom"
: "recovery-input-invalid",
});
return;
}
if (outcome.ok || outcome.partial === undefined) return;
const evidence = createWorkflowEvidence({
...context,
result: outcome.partial.result,
@@ -21,7 +21,6 @@ import { EvidenceIntegrityError } from "../../domain/evidenceErrors.js";
import { safeParseEvidence } from "../../domain/evidenceValidation.js";
import {
createEvidence,
evidenceSubjectTarget,
rebindEvidenceToTargetPath,
type Evidence,
type EvidenceSubjectTarget,
@@ -328,11 +327,21 @@ export const projectRetainedAnalysis = (
if (!retained.ok) return retained;
// Duplicate semantic records retain their original ledger metadata. Detail
// selection changes presentation, not the historical lookup or payload owner.
const subject = evidence.subject;
return projectResolvedAnalysisView(
{ source, view },
prepareAnalysisViewProjection(view),
retained.value,
evidenceSubjectTarget(evidence.subject),
subject === null
? undefined
: {
path: subject.local_path,
sha256: subject.digest.sha256,
format: subject.format,
...(subject.architecture === null
? {}
: { architecture: subject.architecture }),
},
);
};
@@ -374,7 +383,17 @@ const createAnalysisViewEvidence = (
parent: Evidence,
result: AnalysisViewResult,
): Evidence => {
const target = evidenceSubjectTarget(parent.subject);
const target =
parent.subject === null
? undefined
: {
path: parent.subject.local_path,
sha256: parent.subject.digest.sha256,
format: parent.subject.format,
...(parent.subject.architecture === null
? {}
: { architecture: parent.subject.architecture }),
};
const nativeFunctionView =
result.kind === "native" ||
(result.kind === "summary" &&
@@ -262,10 +262,8 @@ describe("browser scenario analysis view pages", () => {
},
};
const summary = await view(dropped, { kind: "summary" });
expect(summary.unknowns).toContainEqual(
expect.stringMatching(
/3 events.*dropped.*counts and pages.*retained events only/iu,
),
expect(summary.unknowns).toContain(
"3 events were dropped by capture budgets; counts and pages cover retained events only.",
);
expect(summary).toMatchObject({
summary: {
@@ -4,10 +4,7 @@ import {
analysisViewResultSchema,
inspectAnalysisViewInputSchema,
} from "../../domain/analysisView/analysisView.js";
import {
RELOCATION_SYMBOL_UNRECORDED,
projectNativeLoadImageView,
} from "../../domain/analysisView/nativeLoadImageView.js";
import { projectNativeLoadImageView } from "../../domain/analysisView/nativeLoadImageView.js";
import type { NativeLoadImage } from "../../domain/native/nativeLoadImage.js";
import {
nativeDosLoadImageFixture,
@@ -83,7 +80,7 @@ it("distinguishes recorded, absent, and historical unrecorded relocation symbols
{ record: { symbol: "external_symbol" } },
{ record: { symbol: null } },
]);
expect(current.unknowns).not.toContain(RELOCATION_SYMBOL_UNRECORDED);
expect(current.unknowns.join(" ")).not.toContain("symbol was not recorded");
report.observations.relocations[1]!.symbol = "";
const emptyName = await view(report, request);
@@ -91,15 +88,15 @@ it("distinguishes recorded, absent, and historical unrecorded relocation symbols
if (emptyName.items.collection !== "relocations")
throw new Error("Expected relocations");
expect(emptyName.items.rows?.[1]?.record).toMatchObject({ symbol: "" });
expect(emptyName.unknowns).not.toContain(RELOCATION_SYMBOL_UNRECORDED);
expect(emptyName.unknowns.join(" ")).not.toContain("symbol was not recorded");
delete report.observations.relocations[0]!.symbol;
const historical = await view(report, request);
if (historical.kind !== "native-load-image") throw new Error("Expected page");
expect(historical.items.rows?.[0]?.record).not.toHaveProperty("symbol");
expect(historical.unknowns).toContain(RELOCATION_SYMBOL_UNRECORDED);
expect(historical.unknowns.join(" ")).toContain("symbol was not recorded");
const omitted = await view(report, { ...request, fields: ["address"] });
expect(omitted.unknowns).not.toContain(RELOCATION_SYMBOL_UNRECORDED);
expect(omitted.unknowns.join(" ")).not.toContain("symbol was not recorded");
});
it("summarizes measured ELF facts without upgrading unsupported verification", async () => {
@@ -2,33 +2,6 @@ import { expect, it, vi } from "vitest";
import { AndroidAnalysisService } from "./AndroidAnalysisService.js";
import type { AndroidAnalysisPort } from "./AndroidAnalysisPort.js";
import { projectAnalysisError } from "../../domain/analysisErrorProjection.js";
import { createEvidence } from "../../domain/evidence.js";
import { ok } from "../../domain/result.js";
import { summarizeRetainedAndroidSearch } from "./AndroidSearchEvidenceSummary.js";
it("retains the selected subject in bounded search Evidence", () => {
const source = createEvidence(
{
path: "/fixture/app.apk",
sha256: "a".repeat(64),
format: "apk",
name: "Selected app",
},
{ id: "fixture", name: "Fixture", version: "1" },
{
operation: "search_android_classes",
parameters: {},
result: { matches: [] },
rawResult: { complete: true },
},
);
const result = summarizeRetainedAndroidSearch(source, { pages: 1 }, () =>
ok("added"),
);
if (!result.ok) throw result.error;
expect(result.value.subject).toEqual(source.subject);
expect(result.value.evidence_links).toContain(source.evidence_id);
});
it("retains selector correction issues before target acquisition", async () => {
const execute = vi.fn<AndroidAnalysisPort["execute"]>();
@@ -25,5 +25,6 @@ export const projectAndroidApplicationEvidence = (
operation: OPERATION,
predicateType: "rea.android-application-graph",
provider: ANDROID_APPLICATION_PROVIDER,
subjectFormat: () => "apk",
});
};
@@ -1,9 +1,5 @@
import type { EvidenceWriter } from "../investigation/InvestigationRecordPort.js";
import {
createEvidence,
evidenceSubjectTarget,
type Evidence,
} from "../../domain/evidence.js";
import { createEvidence, type Evidence } from "../../domain/evidence.js";
import type { AnalysisError } from "../../domain/analysisErrorBase.js";
import type { JsonValue } from "../../domain/jsonValue.js";
import { ok, type Result } from "../../domain/result.js";
@@ -22,16 +18,30 @@ export const summarizeRetainedAndroidSearch = (
if (recordEvidence === undefined) return ok(evidence);
const recorded = recordEvidence(evidence);
if (!recorded.ok) return recorded;
const subject = evidence.subject;
return ok(
createEvidence(evidenceSubjectTarget(evidence.subject), evidence.provider, {
operation: evidence.operation,
parameters: evidence.parameters,
result: evidence.normalized_result,
rawResult: { ...summary, complete_evidence_id: evidence.evidence_id },
confidence: evidence.confidence,
limitations: evidence.limitations,
locations: evidence.locations,
evidenceLinks: [evidence.evidence_id],
}),
createEvidence(
subject === null
? undefined
: {
path: subject.local_path,
sha256: subject.digest.sha256,
format: subject.format,
...(subject.architecture === null
? {}
: { architecture: subject.architecture }),
},
evidence.provider,
{
operation: evidence.operation,
parameters: evidence.parameters,
result: evidence.normalized_result,
rawResult: { ...summary, complete_evidence_id: evidence.evidence_id },
confidence: evidence.confidence,
limitations: evidence.limitations,
locations: evidence.locations,
evidenceLinks: [evidence.evidence_id],
},
),
);
};
@@ -1,3 +1,4 @@
import { isAbsolute } from "node:path";
import { getHeapStatistics } from "node:v8";
import type { ArtifactResourceScope } from "../../artifacts/ArtifactResourceScope.js";
import { AnalysisError } from "../../domain/analysisErrorBase.js";
@@ -124,6 +125,10 @@ export const inspectApiContractEvidence = async (
);
if (!admitted.ok) return admitted;
const input = admitted.value;
if (!isAbsolute(input.path))
return err(
inputFailure("Expected an absolute filesystem path on this host."),
);
if (input.format === "graphql-sdl") {
const { importGraphqlContract } =
await import("./GraphqlContractImport.js");
@@ -1,3 +1,4 @@
import { isAbsolute } from "node:path";
import { getHeapStatistics } from "node:v8";
import { version } from "graphql";
import type { ArtifactResourceScope } from "../../artifacts/ArtifactResourceScope.js";
@@ -152,6 +153,13 @@ export const importGraphqlContract = async (
resources: ArtifactResourceScope,
signal?: AbortSignal,
) => {
if (input.operations_path !== undefined && !isAbsolute(input.operations_path))
return err(
inputFailure(
"operations_path",
"Expected an absolute filesystem path on this host.",
),
);
const loaded = await readApiContract(input, resources, signal);
if (!loaded.ok) return loaded;
const artifact = {
@@ -4,11 +4,15 @@ import {
projectRetainedAnalysis,
type AnalysisViewRetention,
} from "../analysisView/AnalysisViewService.js";
import { isAbsolute } from "node:path";
import type { ExecutionOptions } from "../AnalysisProvider.js";
import type { ApkSignaturePort } from "./ApkSignaturePort.js";
import type { AnalysisError } from "../../domain/analysisErrorBase.js";
import { AnalysisOutputError } from "../../domain/analysisErrorCore.js";
import {
AnalysisInputError,
AnalysisOutputError,
} from "../../domain/analysisErrorCore.js";
import {
apkSignatureMatchesSubject,
apkSignatureResultSchema,
@@ -44,6 +48,16 @@ export class ApkSignatureService {
options?.signal,
);
if (!input.ok) return input;
if (!isAbsolute(input.value.path))
return err(
new AnalysisInputError(OPERATION, undefined, [
{
path: ["path"],
reason: "invalid_format",
message: "Expected an absolute filesystem path on this host.",
},
]),
);
const { detail, view, ...parameters } = input.value;
if (detail === "summary") {
const ready = requireAnalysisViewRetention(OPERATION, retention);
@@ -25,5 +25,6 @@ export const projectAppleApplicationEvidence = (
operation: OPERATION,
predicateType: "rea.apple-application-graph",
provider: APPLE_APPLICATION_PROVIDER,
subjectFormat: (first) => first.subject?.format ?? "unknown",
});
};
@@ -1197,87 +1197,60 @@ describe("relationship coverage snapshot replay", () => {
});
});
it.each([
{
operation: "get_call_graph",
parameters: { address: "0x1000", direction: "forward" },
result: { "0": [] },
},
{
operation: "trace_native_values",
parameters: { procedure: "0x1000" },
result: {
seed: "0x1000",
target_sha256: ANALYSIS_SNAPSHOT_TARGET.sha256,
nodes: [],
edges: [],
procedures: [],
unknowns: [],
total_nodes: 0,
total_edges: 0,
decompilations: 1,
next_offset: null,
page_truncated: false,
traversal: { status: "complete" },
truncated: false,
limitations: [],
},
},
] as const)(
"does not replay old $operation results under the revised workflow profile",
({ operation, parameters, result: oldResult }) => {
const cache = new AnalysisSnapshotCache();
const target = ANALYSIS_SNAPSHOT_TARGET;
const profile = ANALYSIS_SNAPSHOT_PROFILE;
const oldProfile = workflowAnalysisProfile(profile);
const revisedProfile = workflowAnalysisProfile(profile, operation);
cache.recordWorkflow({
target,
profile,
operation,
parameters,
execution: {
...createAnalysisExecution(oldResult, REA_WORKFLOW_PROVIDER, {
subject: target,
rawResult: oldResult,
}),
analysisProfile: oldProfile,
},
});
const evidence = createEvidence(target, REA_WORKFLOW_PROVIDER, {
operation,
confidence: "derived",
parameters,
result: oldResult,
rawResult: oldResult,
analysisProfile: oldProfile,
});
const exported = cache.export(
target,
profile,
createEvidenceBundle([evidence]),
);
if (!exported.ok) throw exported.error;
const snapshot = parseAnalysisSnapshot(exported.value);
expect(
snapshotEvidenceForQuery(snapshot, {
target,
bindingProfile: profile,
operation,
parameters,
provider: REA_WORKFLOW_PROVIDER,
evidenceProfile: revisedProfile,
it("does not replay pre-envelope call graphs under the revised workflow profile", () => {
const cache = new AnalysisSnapshotCache();
const target = ANALYSIS_SNAPSHOT_TARGET;
const profile = ANALYSIS_SNAPSHOT_PROFILE;
const operation = "get_call_graph" as const;
const parameters = { address: "0x1000", direction: "forward" };
const oldProfile = workflowAnalysisProfile(profile);
const revisedProfile = workflowAnalysisProfile(profile, operation);
const oldResult = { "0": [] };
cache.recordWorkflow({
target,
profile,
operation,
parameters,
execution: {
...createAnalysisExecution(oldResult, REA_WORKFLOW_PROVIDER, {
subject: target,
rawResult: oldResult,
}),
).toBeUndefined();
if (operation === "get_call_graph")
expect(
enhancedOutputSchemas.get_call_graph.safeParse({
normalized_result: oldResult,
}).success,
).toBe(false);
},
);
analysisProfile: oldProfile,
},
});
const evidence = createEvidence(target, REA_WORKFLOW_PROVIDER, {
operation,
confidence: "derived",
parameters,
result: oldResult,
rawResult: oldResult,
analysisProfile: oldProfile,
});
const exported = cache.export(
target,
profile,
createEvidenceBundle([evidence]),
);
if (!exported.ok) throw exported.error;
const snapshot = parseAnalysisSnapshot(exported.value);
expect(
snapshotEvidenceForQuery(snapshot, {
target,
bindingProfile: profile,
operation,
parameters,
provider: REA_WORKFLOW_PROVIDER,
evidenceProfile: revisedProfile,
}),
).toBeUndefined();
expect(
enhancedOutputSchemas.get_call_graph.safeParse({
normalized_result: oldResult,
}).success,
).toBe(false);
});
it("keeps older value-trace Evidence as history without replaying its source IDs", () => {
const cache = new AnalysisSnapshotCache();
@@ -1401,41 +1374,6 @@ it("declines source-bearing snapshot entries while replaying omitted and empty s
expect(cache.entries()).toHaveLength(2);
});
it("distinguishes value-flow caveat propagation from source-ownership revisions", () => {
const upstream = ANALYSIS_SNAPSHOT_PROFILE;
const prior = {
...workflowAnalysisProfile(upstream).parameters,
value_flow_absence: "recorded-versus-unavailable-v1",
workflow_revision: 1,
};
const baseline = createAnalysisProfile(REA_WORKFLOW_PROVIDER, prior);
const ownership = createAnalysisProfile(REA_WORKFLOW_PROVIDER, {
...prior,
workflow_revision: 2,
});
const limitations = createAnalysisProfile(REA_WORKFLOW_PROVIDER, {
...prior,
value_flow_limitations: "provider-attributed-v1",
});
const combined = createAnalysisProfile(REA_WORKFLOW_PROVIDER, {
...limitations.parameters,
workflow_revision: 2,
});
const scoped = workflowAnalysisProfile(upstream, "trace_native_values");
expect(scoped.digest).toBe(combined.digest);
expect(scoped.parameters.value_flow_limitations).toBe(
"provider-attributed-v1",
);
expect(
new Set([
baseline.digest,
ownership.digest,
limitations.digest,
combined.digest,
]).size,
).toBe(4);
});
it("replays source-bearing entries only when their complete retained closure exists", () => {
const target = ANALYSIS_SNAPSHOT_TARGET;
const profile = ANALYSIS_SNAPSHOT_PROFILE;
+11 -72
View File
@@ -1,5 +1,3 @@
import { bindSessionEvidenceExecution } from "./SessionEvidenceReuse.js";
import { admitCompletedAnalysis } from "../investigation/admitCompletedAnalysis.js";
import { randomUUID } from "node:crypto";
import {
writeEvidenceBundle,
@@ -52,7 +50,6 @@ import {
} from "./SessionProviderPolicy.js";
import { InvestigationRecords } from "../investigation/InvestigationRecords.js";
import { recordEvidenceSources } from "../investigation/recordEvidenceSources.js";
import { recoverProviderSourceFailure } from "../investigation/sourcePublicationRecovery.js";
import { BinarySessionRecords } from "./BinarySessionRecords.js";
import { binarySessionStatus } from "./BinarySessionStatus.js";
import { SessionRuntimeAvailability } from "./SessionRuntimeAvailability.js";
@@ -1390,34 +1387,9 @@ export class BinarySession
name: Parameters<AnalysisOperationPort["execute"]>[0],
arguments_: Readonly<Record<string, JsonValue>>,
options?: ExecutionOptions,
): Promise<Result<AnalysisExecution, AnalysisError>> {
return this.#trackedExecute(name, arguments_, options);
}
/** Preserve the one-shot caller's Evidence identity if source retention fails. */
executeForDirectObservation(
name: Parameters<AnalysisOperationPort["execute"]>[0],
arguments_: Readonly<Record<string, JsonValue>>,
evidenceParameters: Readonly<Record<string, JsonValue>>,
options?: ExecutionOptions,
): Promise<Result<AnalysisExecution, AnalysisError>> {
return this.#trackedExecute(name, arguments_, options, evidenceParameters);
}
#trackedExecute(
name: Parameters<AnalysisOperationPort["execute"]>[0],
arguments_: Readonly<Record<string, JsonValue>>,
options?: ExecutionOptions,
recoveryParameters?: Readonly<Record<string, JsonValue>>,
): Promise<Result<AnalysisExecution, AnalysisError>> {
const generation = this.#transitionGeneration;
const call = this.#execute(
name,
arguments_,
options,
this.#transition,
recoveryParameters,
);
const call = this.#execute(name, arguments_, options, this.#transition);
this.#calls.set(call, generation);
return call.finally(() => this.#calls.delete(call));
}
@@ -1489,7 +1461,6 @@ export class BinarySession
arguments_: Readonly<Record<string, JsonValue>>,
options: ExecutionOptions | undefined,
transition: Promise<void>,
recoveryParameters?: Readonly<Record<string, JsonValue>>,
): Promise<Result<AnalysisExecution, AnalysisError>> {
const transitioned = await this.#waitForTransition(
name,
@@ -1576,24 +1547,7 @@ export class BinarySession
(source) => this.recordEvidence(source),
execution.value.sourceEvidence,
);
if (!sourcesRecorded.ok) {
recoverProviderSourceFailure({
error: sourcesRecorded.error,
operation: name,
parameters: recoveryParameters ?? arguments_,
execution: {
...execution.value,
sourceEvidence: execution.value.sourceEvidence,
subject:
execution.value.subject === undefined
? active.target
: execution.value.subject,
},
admit: this.admitRecoveryObservation.bind(this),
evidenceForAnalysis: this.evidenceForAnalysis.bind(this),
});
return sourcesRecorded;
}
if (!sourcesRecorded.ok) return sourcesRecorded;
}
if (
execution.ok &&
@@ -1603,25 +1557,17 @@ export class BinarySession
}) &&
profile !== undefined
) {
const evidenceExecution = {
...execution.value,
analysisProfile: profile,
subject:
execution.value.subject === undefined
? active.target
: execution.value.subject,
};
const admitted = admitCompletedAnalysis(
name,
arguments_,
evidenceExecution,
this.admitRecoveryObservation.bind(this),
);
if (!admitted.ok) return admitted;
const evidence = createAnalysisExecutionEvidence(
name,
arguments_,
evidenceExecution,
{
...execution.value,
analysisProfile: profile,
subject:
execution.value.subject === undefined
? active.target
: execution.value.subject,
},
"observed",
);
const recorded = this.recordEvidence(evidence);
@@ -1630,14 +1576,7 @@ export class BinarySession
recorded.error.retainPartialObservation(evidence);
return recorded;
}
const authenticated = this.evidenceForAnalysis(evidence.evidence_id);
const retained =
authenticated === undefined
? { ...execution.value, evidenceId: evidence.evidence_id }
: bindSessionEvidenceExecution(
{ ...execution.value, evidenceId: evidence.evidence_id },
authenticated,
);
const retained = { ...execution.value, evidenceId: evidence.evidence_id };
if (cacheable && execution.value.cachePolicy !== "live")
this.recordSnapshot({
target: active.target,
@@ -1,6 +1,5 @@
import type { EspFlashSelection } from "../../domain/firmware/espFlashLocation.js";
import type { InvestigationRecordPort } from "../investigation/InvestigationRecordPort.js";
import type { RecoveryAdmission } from "../investigation/InvestigationRetention.js";
import type { ResetInvestigationReceipt } from "../../domain/investigationLifecycle.js";
import type { ExecutableFormatHint } from "../../domain/dosCom.js";
import type {
@@ -58,7 +57,6 @@ export type BinaryOpenResult =
/** Target lifecycle used by CLI and MCP without exposing a concrete provider. */
export interface BinarySessionPort
extends AnalysisOperationPort, InvestigationRecordPort {
readonly admitRecoveryObservation: RecoveryAdmission;
/** Execute only against a positively ready, already-created provider client. */
executeIfProviderReady(
operation: AnalysisOperation,
@@ -126,17 +126,6 @@ export abstract class BinarySessionRecords {
return recorded;
}
admitRecoveryObservation(
input: unknown,
operation: string,
additional: {
readonly valueBytes: number;
readonly serializedUtf16Bytes: number;
},
): Result<void, AnalysisError> {
return this.#records.admitRecoveryObservation(input, operation, additional);
}
hasEvidence(evidenceId: string): boolean {
return this.#records.hasEvidence(evidenceId);
}
@@ -32,6 +32,7 @@ import { NATIVE_MACOS_PROVIDER_IDENTITY } from "../../native/NativeMacosProvider
import {
buildCapabilityInventory,
compactToolAvailability,
MULTI_MODE_REMEDIATION,
} from "../CapabilityInventory.js";
const projectedStatusSchema = z.object({
@@ -582,9 +583,7 @@ it.each([
: ["inspect_native_dispatch_metadata", "list_names"],
});
if (!route) {
expect(trace?.remediation).toMatch(
/no mode.*inspect each mode.*missing operations and remediation/iu,
);
expect(trace?.remediation).toBe(MULTI_MODE_REMEDIATION);
const authored = trace?.modes?.find(
(mode) => mode.name === "authored_ui_dispatch",
);
@@ -639,9 +638,7 @@ it("keeps distinct recovery for an unbound non-bundle session", async () => {
expect(trace).toMatchObject({
available: false,
reason: "provider_unavailable",
remediation: expect.stringMatching(
/no mode.*inspect each mode.*missing operations and remediation/iu,
),
remediation: MULTI_MODE_REMEDIATION,
});
const authored = trace?.modes?.find(
(mode) => mode.name === "authored_ui_dispatch",
Loaded 100 of 613 files, more files were not shown because too many files have changed in this diff. Show more