rea-agents 6.0.0 → 6.1.0

package/bridge/process/ProcessRunTokenReader.swift

@@ -112,6 +112,31 @@ enum RunTokenReadError: Error {
   case ambiguousEnvironmentBoundary
 }
 
+@_silgen_name("csops")
+private func csops(
+  _ pid: Int32,
+  _ ops: UInt32,
+  _ addr: UnsafeMutableRawPointer?,
+  _ size: Int
+) -> Int32
+
+private let csOpsStatus: UInt32 = 0
+private let csPlatformBinary: UInt32 = 0x0400_0000
+
+/**
+ * Whether the target image is an Apple platform binary. Current macOS omits
+ * the environment of platform binaries from KERN_PROCARGS2 for every caller,
+ * so this distinguishes a policy-withheld environment from a process whose
+ * environment is genuinely absent or transiently unreadable.
+ */
+func isPlatformBinary(pid: Int32) -> Bool {
+  var flags: UInt32 = 0
+  let result = withUnsafeMutablePointer(to: &flags) { pointer in
+    csops(pid, csOpsStatus, UnsafeMutableRawPointer(pointer), MemoryLayout<UInt32>.size)
+  }
+  return result == 0 && (flags & csPlatformBinary) != 0
+}
+
 private func readRunToken(pid: Int32, pointerSize: Int) -> RunTokenObservation {
   var mib = [CTL_KERN, KERN_PROCARGS2, Int32(pid)]
   var size = 0
@@ -127,13 +152,25 @@ private func readRunToken(pid: Int32, pointerSize: Int) -> RunTokenObservation {
   }
   bytes = Array(bytes.prefix(size))
   do {
-    return RunTokenObservation(pid: pid, state: "readable", run_id: try token(in: bytes, pointerSize: pointerSize), reason: nil)
+    let runId = try token(in: bytes, pointerSize: pointerSize)
+    // A complete empty environment is readable for an ordinary image. Apple
+    // platform images can expose the same layout after the kernel withholds
+    // their environment, so they remain explicitly unverified without a token.
+    if runId == nil && isPlatformBinary(pid: pid) {
+      return unavailable(pid: pid, reason: "platform_binary_environment_withheld")
+    }
+    return RunTokenObservation(pid: pid, state: "readable", run_id: runId, reason: nil)
   } catch RunTokenReadError.duplicateToken {
     return unavailable(pid: pid, reason: "duplicate_run_token")
   } catch RunTokenReadError.invalidTokenEncoding {
     return unavailable(pid: pid, reason: "invalid_run_token_encoding")
   } catch RunTokenReadError.environmentUnavailable {
-    return unavailable(pid: pid, reason: "environment_unavailable")
+    return unavailable(
+      pid: pid,
+      reason: isPlatformBinary(pid: pid)
+        ? "platform_binary_environment_withheld"
+        : "environment_unavailable"
+    )
   } catch RunTokenReadError.appleVectorUnavailable {
     return unavailable(pid: pid, reason: "apple_vector_unavailable")
   } catch RunTokenReadError.ambiguousEnvironmentBoundary {
@@ -229,9 +266,6 @@ func token(in bytes: [UInt8], pointerSize: Int = MemoryLayout<UnsafeRawPointer>.
     throw RunTokenReadError.ambiguousEnvironmentBoundary
   }
   let environmentEntries = trailingEntries[..<appleVectorStart]
-  guard !environmentEntries.isEmpty else {
-    throw RunTokenReadError.environmentUnavailable
-  }
   var found: String?
   for entry in environmentEntries {
     if entry.starts(with: Array("REA_PROCESS_RUN_ID=".utf8)) {

package/bridge/pwntools/recorded_crash_impl.py

@@ -43,6 +43,10 @@ def inspect_core(path, cache):
         raise CoreFailure("unsupported-target", "Initial recorded-core profile requires ELF64 little-endian.")
     if len(content) < 64:
         raise CoreFailure("format", "Selected ELF64 core header is truncated.")
+    if content[6] != 1:
+        raise CoreFailure("format", "ELF identification version is not EV_CURRENT.")
+    if int.from_bytes(content[20:24], "little") != 1:
+        raise CoreFailure("format", "ELF header version is not EV_CURRENT.")
     # Linux commonly emits ELFOSABI_NONE (0), also accepted as GNU/Linux (3).
     # Other declared OSABIs must never select Linux note ctypes.
     if content[7] not in (0, 3) or content[8] != 0:

package/dist/android/JadxConfiguration.js

@@ -1,44 +1,130 @@
-import { access, realpath, stat } from "node:fs/promises";
 import { constants } from "node:fs";
+import { access, realpath, stat } from "node:fs/promises";
 import { isAbsolute, join } from "node:path";
 import { AnalysisCapabilityUnavailableError } from "../domain/analysisErrorCore.js";
+import { execFileOutput, execFileOutputFailure, } from "../process/ExecFileOutput.js";
 import { JADX_JAR_CONFIGURATION_REMEDIATION } from "./JadxRelease.js";
-/** Admit explicit local tooling without installing or changing host configuration. */
-export const resolveJadxConfiguration = async (environment, operation) => {
-    const unavailable = (reason) => new AnalysisCapabilityUnavailableError("jadx", operation, reason);
-    if (process.platform !== "linux" && process.platform !== "darwin")
-        throw unavailable(`Android JADX subprocess ownership is unsupported on ${process.platform}; use Linux or macOS. The metadata bridge has real-provider verification on macOS arm64.`);
+const JAVA_MODULE_LISTING_TIMEOUT_MS = 10_000;
+const JAVA_MODULE_LISTING_MAX_OUTPUT_BYTES = 1024 * 1024;
+class JadxConfigurationFailure extends Error {
+    code;
+    diagnostics;
+    constructor(code, message, diagnostics, options) {
+        super(message, options);
+        this.code = code;
+        this.diagnostics = diagnostics;
+    }
+}
+/** Inspect the same JAR and Java prerequisites that gate actual execution. */
+export const inspectJadxAvailability = async (environment, signal) => {
+    try {
+        const configuration = await readJadxConfiguration(environment, signal);
+        return {
+            status: "available",
+            code: null,
+            reason: null,
+            diagnostics: {
+                configured: true,
+                java_executable: configuration.java,
+                jdk_compiler: true,
+                jar_path: configuration.jar,
+            },
+        };
+    }
+    catch (cause) {
+        if (signal?.aborted === true)
+            throw cause;
+        if (cause instanceof JadxConfigurationFailure)
+            return {
+                status: "unavailable",
+                code: cause.code,
+                reason: cause.message,
+                diagnostics: cause.diagnostics,
+            };
+        throw cause;
+    }
+};
+/** Resolve caller-selected tools and preserve the same prerequisite diagnostics. */
+export const resolveJadxConfiguration = async (environment, operation, signal) => {
+    try {
+        return await readJadxConfiguration(environment, signal);
+    }
+    catch (cause) {
+        if (signal?.aborted === true)
+            throw cause;
+        if (!(cause instanceof JadxConfigurationFailure))
+            throw cause;
+        const output = cause.diagnostics;
+        throw new AnalysisCapabilityUnavailableError("jadx", operation, cause.message, {
+            cause,
+            userMessage: cause.message,
+            ...(typeof output.stdout === "string" &&
+                typeof output.stderr === "string"
+                ? {
+                    capturedOutput: {
+                        stdout: output.stdout,
+                        stderr: output.stderr,
+                        truncated: output.output_truncated === true,
+                    },
+                }
+                : {}),
+        });
+    }
+};
+const readJadxConfiguration = async (environment, signal) => {
+    requireSupportedHost();
+    const jar = await resolveJar(environment);
+    const java = resolveJava(environment);
+    await requireJavaHomeExecutable(environment.JAVA_HOME, java);
+    const jvmArguments = resolveJvmArguments(environment);
+    await inspectJavaRuntime(java, environment, signal);
+    return { jar, java, jvmArguments };
+};
+const requireSupportedHost = () => {
+    if (process.platform === "linux" || process.platform === "darwin")
+        return;
+    throw configurationFailure("unsupported_host", `Android JADX subprocess ownership is unsupported on ${process.platform}; use Linux or macOS. The metadata bridge has real-provider verification on macOS arm64.`, { platform: process.platform });
+};
+const resolveJar = async (environment) => {
     const jar = environment.REA_JADX_MCP_JAR;
-    if (environment.JAVA_HOME !== undefined && !isAbsolute(environment.JAVA_HOME))
-        throw unavailable("JAVA_HOME must select an existing JDK by absolute path; omit it to use java on PATH.");
     if (jar === undefined || !isAbsolute(jar))
-        throw unavailable(JADX_JAR_CONFIGURATION_REMEDIATION);
-    const java = environment.JAVA_HOME === undefined
-        ? "java"
-        : join(environment.JAVA_HOME, "bin", "java");
+        throw configurationFailure("not_configured", JADX_JAR_CONFIGURATION_REMEDIATION, { jar_configured: false });
     try {
         await access(jar, constants.R_OK);
         if (!(await stat(jar)).isFile())
-            throw unavailable(`REA_JADX_MCP_JAR is not a regular file: ${jar}`);
+            throw configurationFailure("executable_missing", `REA_JADX_MCP_JAR is not a regular file: ${jar}`, { jar_path: jar });
+        return await realpath(jar);
     }
     catch (cause) {
-        if (cause instanceof AnalysisCapabilityUnavailableError)
+        if (cause instanceof JadxConfigurationFailure)
             throw cause;
-        throw unavailable(`Cannot read REA_JADX_MCP_JAR ${jar}: ${cause instanceof Error ? cause.message : String(cause)}`);
-    }
-    if (environment.JAVA_HOME !== undefined) {
-        try {
-            await access(java, constants.R_OK | constants.X_OK);
-            if (!(await stat(java)).isFile())
-                throw unavailable(`JAVA_HOME java is not a regular file: ${java}`);
-        }
-        catch (cause) {
-            if (cause instanceof AnalysisCapabilityUnavailableError)
-                throw cause;
-            throw unavailable(`Cannot execute JAVA_HOME java ${java}: ${cause instanceof Error ? cause.message : String(cause)}`);
-        }
-    }
-    const jvmArguments = [];
+        throw configurationFailure("executable_missing", `Cannot read REA_JADX_MCP_JAR ${jar}: ${cause instanceof Error ? cause.message : String(cause)}`, { jar_path: jar }, cause);
+    }
+};
+const resolveJava = (environment) => {
+    if (environment.JAVA_HOME === undefined)
+        return "java";
+    if (isAbsolute(environment.JAVA_HOME))
+        return join(environment.JAVA_HOME, "bin", "java");
+    throw configurationFailure("open_options_invalid", "JAVA_HOME must select an existing JDK by absolute path; omit it to use java on PATH.", { java_home: environment.JAVA_HOME });
+};
+const requireJavaHomeExecutable = async (javaHome, java) => {
+    if (javaHome === undefined)
+        return;
+    try {
+        await access(java, constants.R_OK | constants.X_OK);
+        if ((await stat(java)).isFile())
+            return;
+        throw configurationFailure("runtime_missing", `JAVA_HOME java is not a regular file: ${java}`, { java_executable: java });
+    }
+    catch (cause) {
+        if (cause instanceof JadxConfigurationFailure)
+            throw cause;
+        throw configurationFailure("runtime_missing", `Cannot execute JAVA_HOME java ${java}: ${cause instanceof Error ? cause.message : String(cause)}`, { java_executable: java }, cause);
+    }
+};
+const resolveJvmArguments = (environment) => {
+    const result = [];
     for (const [name, prefix, suffix] of [
         ["REA_JADX_HEAP_MIB", "-Xmx", "m"],
         ["REA_JADX_ACTIVE_PROCESSOR_COUNT", "-XX:ActiveProcessorCount=", ""],
@@ -47,11 +133,88 @@ export const resolveJadxConfiguration = async (environment, operation) => {
         if (value === undefined)
             continue;
         if (!/^[1-9]\d*$/u.test(value) || !Number.isSafeInteger(Number(value)))
-            throw unavailable(`${name} must be a positive safe integer; received ${value}.`);
+            throw configurationFailure("open_options_invalid", `${name} must be a positive safe integer; received ${value}.`, { setting: name, value });
         if (name === "REA_JADX_ACTIVE_PROCESSOR_COUNT" &&
             Number(value) > 2_147_483_647)
-            throw unavailable(`${name} exceeds the JVM's signed 32-bit processor-count range.`);
-        jvmArguments.push(`${prefix}${value}${suffix}`);
+            throw configurationFailure("open_options_invalid", `${name} exceeds the JVM's signed 32-bit processor-count range.`, { setting: name, value });
+        result.push(`${prefix}${value}${suffix}`);
+    }
+    return result;
+};
+const inspectJavaRuntime = async (java, environment, signal) => {
+    let stdout;
+    let stderr;
+    try {
+        ({ stdout, stderr } = await execFileOutput(java, ["--list-modules"], {
+            env: { ...environment },
+            timeout: JAVA_MODULE_LISTING_TIMEOUT_MS,
+            maxBuffer: JAVA_MODULE_LISTING_MAX_OUTPUT_BYTES,
+            ...(signal === undefined ? {} : { signal }),
+        }));
+    }
+    catch (cause) {
+        if (signal?.aborted === true)
+            throw cause;
+        const output = execFileOutputFailure(cause);
+        if (output === undefined)
+            throw cause;
+        const diagnostics = {
+            java_executable: java,
+            phase: "module-inspection",
+            exit_code: typeof output.code === "number" ? output.code : null,
+            process_error_code: typeof output.code === "string" ? output.code : null,
+            signal: output.signal,
+            killed: output.killed,
+            stdout: output.stdout,
+            stderr: output.stderr,
+            output_truncated: output.outputTruncated,
+        };
+        if (output.outputTruncated)
+            throw configurationFailure("version_unresolved", `The selected Java launcher ${java} exceeded the ${JAVA_MODULE_LISTING_MAX_OUTPUT_BYTES / (1024 * 1024)} MiB output budget while listing modules. REA retained partial output but could not establish compiler or version availability. Inspect the selected launcher for verbose or unbounded output; ` +
+                "java --list-modules should return a concise module listing.", {
+                ...diagnostics,
+                failure: "output_limit",
+                output_limit_bytes: JAVA_MODULE_LISTING_MAX_OUTPUT_BYTES,
+            }, cause);
+        if (output.killed)
+            throw configurationFailure("version_unresolved", `The selected Java launcher ${java} was terminated or did not finish the module-listing probe within ${JAVA_MODULE_LISTING_TIMEOUT_MS / 1000} seconds. Inspect the launcher and its startup responsiveness, then verify it returns compiler and version modules with java --list-modules.`, {
+                ...diagnostics,
+                failure: "probe_terminated",
+                deadline_ms: JAVA_MODULE_LISTING_TIMEOUT_MS,
+            }, cause);
+        throw configurationFailure("runtime_missing", `Cannot inspect selected Java runtime ${java}: ${output.stderr.trim() || errorText(cause)}. Select a full JDK including jdk.compiler via JAVA_HOME or PATH; verify it with java --list-modules.`, diagnostics, cause);
     }
-    return { jar: await realpath(jar), java, jvmArguments };
+    const compiler = /^jdk\.compiler(?:@|$)/mu.test(stdout);
+    if (!compiler)
+        throw configurationFailure("runtime_missing", `Selected Java runtime ${java} does not provide jdk.compiler. Select a full JDK including jdk.compiler via JAVA_HOME or PATH; verify it with java --list-modules. A JRE cannot compile REA's source bridge.`, {
+            java_executable: java,
+            phase: "module-inspection",
+            jdk_compiler: false,
+            stdout,
+            stderr,
+            output_truncated: false,
+        });
+    const major = /^java\.base@(\d+)(?:[.+_-]|$)/mu.exec(stdout)?.[1];
+    if (major === undefined)
+        throw configurationFailure("version_unresolved", `The selected Java launcher ${java} did not report a parseable java.base version in its module listing. Inspect the launcher output and verify it with java --list-modules.`, {
+            java_executable: java,
+            phase: "module-inspection",
+            jdk_compiler: true,
+            java_major: null,
+            stdout,
+            stderr,
+            output_truncated: false,
+        });
+    if (Number(major) < 17)
+        throw configurationFailure("unsupported_version", `Selected Java runtime ${java} must be JDK 17 or newer and include jdk.compiler; verify it with java --list-modules.`, {
+            java_executable: java,
+            phase: "module-inspection",
+            jdk_compiler: true,
+            java_major: major ?? null,
+            stdout,
+            stderr,
+            output_truncated: false,
+        });
 };
+const configurationFailure = (code, message, diagnostics, cause) => new JadxConfigurationFailure(code, message, diagnostics, cause === undefined ? undefined : { cause });
+const errorText = (cause) => cause instanceof Error ? cause.message : String(cause);

package/dist/android/JadxMcpTransport.js

@@ -78,6 +78,10 @@ export class JadxMcpTransport {
     diagnostics() {
         return this.#supervisor?.snapshot().stderr.text ?? "";
     }
+    /** Whether the retained startup/operation diagnostics lost bytes. */
+    diagnosticsTruncated() {
+        return this.#supervisor?.snapshot().diagnosticTruncated ?? false;
+    }
     /** Preserve the failed protocol/resource constraint after the SDK closes requests. */
     failureReason() {
         return this.#failure;

package/dist/android/JadxProtocol.js

@@ -2,6 +2,12 @@ import { z } from "zod";
 import { AnalysisOutputError } from "../domain/analysisErrorCore.js";
 import { jsonValueSchema } from "../domain/jsonValue.js";
 const count = z.number().int().nonnegative();
+/** Selector failures authored by REA's bridge, separate from arbitrary engine errors. */
+export const jadxInputFailureSchema = z.strictObject({
+    kind: z.literal("invalid-input"),
+    field: z.enum(["class_name", "method_name", "overload_index"]),
+    message: z.string().min(1),
+});
 /** Values observed inside the exact JVM producing the analysis. */
 export const jadxRuntimeSchema = z.object({
     engine_reported_version: z.string().min(1),

package/dist/android/JadxProvider.js

@@ -9,7 +9,7 @@ import { ProviderCleanupError } from "../domain/providerCleanupError.js";
 import { err, ok } from "../domain/result.js";
 import { PrivateRuntimeRoot } from "../process/PrivateRuntimeRoot.js";
 import { snapshotAndroidEngine, hashAndroidFile, snapshotAndroidTarget, } from "./AndroidTargetSnapshot.js";
-import { resolveJadxConfiguration } from "./JadxConfiguration.js";
+import { inspectJadxAvailability, resolveJadxConfiguration, } from "./JadxConfiguration.js";
 import { JadxSession } from "./JadxSession.js";
 const OPERATION_TIMEOUT_MS = 120_000;
 const BRIDGE_SOURCE = fileURLToPath(new URL("../../bridge/android/ReaJadxBridge.java", import.meta.url));
@@ -38,6 +38,19 @@ const executionError = (context) => {
         });
     if (cause instanceof z.ZodError)
         return new AnalysisOutputError(request.operation, "JADX response violated the pinned upstream protocol", { cause });
+    if (session !== undefined && !session.initialized()) {
+        const stderr = session.transport.diagnostics();
+        const reason = `Java could not start REA's Android bridge using ${session.transport.options.command}: ${cause instanceof Error ? cause.message : String(cause)}.${stderr.length === 0 ? "" : ` Java diagnostics: ${stderr}`} Select a full JDK including jdk.compiler via JAVA_HOME, or a working java on PATH; verify it with java --list-modules. A JRE cannot compile REA's source bridge. If the JDK works, verify the REA bridge and configured JADX JAR installation.`;
+        return new AnalysisCapabilityUnavailableError("jadx", request.operation, reason, {
+            cause,
+            userMessage: reason,
+            capturedOutput: {
+                stdout: "",
+                stderr,
+                truncated: session.transport.diagnosticsTruncated(),
+            },
+        });
+    }
     return new ProviderAdapterError("jadx", request.operation, {
         cause,
         diagnostics: {
@@ -93,6 +106,10 @@ export class JadxProvider {
         this.environment = environment;
         this.launcher = launcher;
     }
+    /** Report actual local prerequisites without starting JADX or opening a target. */
+    inspectAvailability(signal) {
+        return inspectJadxAvailability(this.environment, signal);
+    }
     /** Serialize expensive work and bind both raw and normalized results to the APK. */
     async execute(target, request, options) {
         if (this.#shutdown.signal.aborted)
@@ -165,7 +182,7 @@ export class JadxProvider {
         try {
             if (target.format !== "apk")
                 throw new AnalysisCapabilityUnavailableError("jadx", request.operation, `Target ${target.path} is ${target.format}; provide one standalone APK.`);
-            const configuration = await resolveJadxConfiguration(this.environment, request.operation);
+            const configuration = await resolveJadxConfiguration(this.environment, request.operation, signal);
             signal.throwIfAborted();
             const jarHash = await hashAndroidFile(configuration.jar);
             const bridgeHash = await hashAndroidFile(BRIDGE_SOURCE);

package/dist/android/JadxSession.js

@@ -1,17 +1,18 @@
 import { Client } from "@modelcontextprotocol/client";
 import { createAnalysisExecution, } from "../application/AnalysisProvider.js";
-import { AnalysisCapabilityUnavailableError, AnalysisOutputError, } from "../domain/analysisErrorCore.js";
+import { AnalysisCapabilityUnavailableError, AnalysisInputError, AnalysisOutputError, } from "../domain/analysisErrorCore.js";
 import { jsonValueSchema } from "../domain/jsonValue.js";
 import { ProviderAdapterError } from "../domain/providerAdapterError.js";
 import { analyzeJadxRequest } from "./JadxAnalysis.js";
 import { JadxMcpTransport } from "./JadxMcpTransport.js";
-import { jadxLoadSchema, jadxRuntimeSchema, parseJadxEnvelope, parseJadxJson, } from "./JadxProtocol.js";
+import { jadxLoadSchema, jadxInputFailureSchema, jadxRuntimeSchema, parseJadxEnvelope, parseJadxJson, } from "./JadxProtocol.js";
 import { JADX_BRIDGE_IDENTITY, JADX_RELEASE, JADX_PROVIDER_IDENTITY, JADX_LIMITATIONS, } from "./JadxRelease.js";
 /** One owned engine connection; its wire protocol stays inside the Android adapter. */
 export class JadxSession {
     transport;
     #client = new Client({ name: "rea-android-adapter", version: "1" });
     #loaded;
+    #connected = false;
     constructor(options, launcher) {
         this.transport = new JadxMcpTransport(options, launcher);
     }
@@ -26,8 +27,10 @@ export class JadxSession {
             signal.throwIfAborted();
             this.transport.beginOperation();
             const raw = [];
-            if (this.#loaded === undefined)
+            if (!this.#connected) {
                 await this.#client.connect(this.transport, { timeout: 30_000 });
+                this.#connected = true;
+            }
             const server = this.#client.getServerVersion();
             if (server?.name !== JADX_BRIDGE_IDENTITY.name ||
                 server.version !== JADX_BRIDGE_IDENTITY.version)
@@ -73,6 +76,10 @@ export class JadxSession {
             signal.removeEventListener("abort", abort);
         }
     }
+    /** Whether the selected Java runtime established the REA bridge protocol. */
+    initialized() {
+        return this.#connected;
+    }
     /** Join owned cleanup even if SDK connection teardown itself fails. */
     async close() {
         try {
@@ -92,7 +99,18 @@ export class JadxSession {
                 input,
                 response: jsonValueSchema.parse(response),
             });
-            if (envelope.failed)
+            if (envelope.failed) {
+                if (envelope.text.startsWith("{")) {
+                    const failure = jadxInputFailureSchema.safeParse(parseJadxJson(envelope.text, request.operation));
+                    if (failure.success)
+                        throw new AnalysisInputError(request.operation, undefined, [
+                            {
+                                path: [failure.data.field],
+                                reason: "invalid_value",
+                                message: failure.data.message,
+                            },
+                        ]);
+                }
                 throw new ProviderAdapterError("jadx", request.operation, {
                     diagnostics: {
                         upstream_operation: name,
@@ -101,6 +119,7 @@ export class JadxSession {
                         target_sha256: target.sha256,
                     },
                 });
+            }
             return envelope.text;
         };
         return {

package/dist/application/AnalysisContextQueries.js

@@ -1,6 +1,7 @@
-import { AnalysisCapabilityUnavailableError, AnalysisOutputError, } from "../domain/analysisErrorCore.js";
+import { AnalysisOutputError } from "../domain/analysisErrorCore.js";
 import {} from "../domain/analysisErrorBase.js";
-import { parseDocuments } from "../domain/hopperValues.js";
+import { analysisBookmarkSchema } from "../domain/hopperValues.js";
+import { resolveAnalysisDocument } from "./AnalysisDocument.js";
 import { err, ok } from "../domain/result.js";
 const parameters = (document, address) => ({
     ...(document === undefined ? {} : { document }),
@@ -42,7 +43,7 @@ export const getNavigationContext = async (analysis, input, signal) => {
 };
 /** Inspect bounded provider-neutral facets at one explicit reproducible address. */
 export const inspectAddressContext = async (analysis, input, signal) => {
-    const document = await resolveDocument(analysis, input.document, signal);
+    const document = await resolveAnalysisDocument(analysis, input.document, signal);
     if (!document.ok)
         return document;
     const args = parameters(document.value, input.address);
@@ -75,30 +76,6 @@ export const inspectAddressContext = async (analysis, input, signal) => {
             : bookmarks,
     });
 };
-const resolveDocument = async (analysis, document, signal) => {
-    if (document !== undefined)
-        return ok(document);
-    const current = await analysis.execute("current_document", {}, executionOptions(signal));
-    if (!current.ok) {
-        if (!(current.error instanceof AnalysisCapabilityUnavailableError))
-            return current;
-        const listed = await analysis.execute("list_documents", {}, executionOptions(signal));
-        if (!listed.ok)
-            return listed;
-        const parsed = parseDocuments(listed.value.result);
-        if (!parsed.ok)
-            return err(new AnalysisOutputError("list_documents", "expected one document identity when resolving a headless provider", { cause: parsed.error }));
-        if (parsed.value.length !== 1)
-            return err(new AnalysisOutputError("list_documents", `expected exactly one document identity for a provider without current-document selection, received ${parsed.value.length}`));
-        const [documentName] = parsed.value;
-        if (documentName === undefined)
-            return err(new AnalysisOutputError("list_documents", "provider returned no document identity"));
-        return ok(documentName);
-    }
-    return typeof current.value.result === "string"
-        ? ok(current.value.result)
-        : err(new AnalysisOutputError("current_document", "expected a document identity string"));
-};
 const facet = (result, operation) => result?.ok === true
     ? { state: "available", value: result.value.result }
     : {
@@ -139,19 +116,15 @@ const matchingBookmarks = (value, address) => {
             reason: "list_bookmarks returned malformed output; expected an array.",
             remediation: "Retry list_bookmarks directly and report the provider output shape if it remains malformed.",
         };
-    if (!value.every(isBookmark))
+    const parsed = analysisBookmarkSchema.array().safeParse(value);
+    if (!parsed.success)
         return {
             state: "unavailable",
-            reason: "list_bookmarks returned malformed entries; expected address and name strings.",
+            reason: "list_bookmarks returned malformed entries; expected an address string and a string or null name.",
             remediation: "Retry list_bookmarks directly and report the provider output shape if it remains malformed.",
         };
     return {
         state: "available",
-        value: value.filter((bookmark) => bookmark.address === address),
+        value: parsed.data.filter((bookmark) => bookmark.address === address),
     };
 };
-const isBookmark = (value) => typeof value === "object" &&
-    value !== null &&
-    !Array.isArray(value) &&
-    typeof value.address === "string" &&
-    typeof value.name === "string";

package/dist/application/AnalysisDocument.js

@@ -0,0 +1,32 @@
+import { AnalysisCancelledError, AnalysisCapabilityUnavailableError, AnalysisOutputError, } from "../domain/analysisErrorCore.js";
+import { parseDocuments } from "../domain/hopperValues.js";
+import { err, ok } from "../domain/result.js";
+const executionOptions = (signal) => signal === undefined ? undefined : { signal };
+/** Resolve an explicit or provider-selected document without guessing among candidates. */
+export const resolveAnalysisDocument = async (analysis, document, signal) => {
+    if (document !== undefined)
+        return ok(document);
+    if (signal?.aborted === true)
+        return err(new AnalysisCancelledError("current_document"));
+    const current = await analysis.execute("current_document", {}, executionOptions(signal));
+    if (!current.ok) {
+        if (!(current.error instanceof AnalysisCapabilityUnavailableError))
+            return current;
+        const listed = await analysis.execute("list_documents", {}, executionOptions(signal));
+        if (!listed.ok)
+            return listed;
+        const parsed = parseDocuments(listed.value.result);
+        if (!parsed.ok)
+            return err(new AnalysisOutputError("list_documents", "expected one document identity when resolving a headless provider", { cause: parsed.error }));
+        if (parsed.value.length !== 1)
+            return err(new AnalysisOutputError("list_documents", `expected exactly one document identity for a provider without current-document selection, received ${parsed.value.length}`));
+        const [documentName] = parsed.value;
+        if (documentName === undefined || documentName.length === 0)
+            return err(new AnalysisOutputError("list_documents", "provider returned no document identity"));
+        return ok(documentName);
+    }
+    return typeof current.value.result === "string" &&
+        current.value.result.length > 0
+        ? ok(current.value.result)
+        : err(new AnalysisOutputError("current_document", "expected a nonempty document identity string"));
+};