rea-agents 6.3.0 → 6.4.0

package/dist/jeb/JebMcpConnection.js

@@ -0,0 +1,179 @@
+import { Client, StreamableHTTPClientTransport, } from "@modelcontextprotocol/client";
+import { z } from "zod";
+import { jsonValueSchema } from "../domain/jsonValue.js";
+import { AnalysisCancelledError, AnalysisProtocolError, } from "../domain/analysisErrorCore.js";
+const toolResultSchema = z.object({
+    isError: z.boolean().optional(),
+    structuredContent: z.record(z.string(), z.unknown()).optional(),
+    content: z
+        .array(z.object({ type: z.string(), text: z.string().optional() }).passthrough())
+        .default([]),
+});
+/** Decode a JEB MCP tool result without inventing an empty observation. */
+export const decodeJebToolResult = (input) => {
+    const result = toolResultSchema.parse(input);
+    const blocks = result.content.flatMap((block) => block.type === "text" && block.text !== undefined ? [block.text] : []);
+    if (result.structuredContent !== undefined) {
+        // isError envelopes carry JEB's {success:false, message} refusal semantics;
+        // decode them so the provider can preserve the engine's own reason.
+        return jsonValueSchema.parse(result.structuredContent);
+    }
+    if (blocks.length !== 1)
+        throw new AnalysisProtocolError("JEB MCP omitted a single structured or text result; unsupported content cannot establish an empty observation.");
+    try {
+        return jsonValueSchema.parse(JSON.parse(blocks[0] ?? "null"));
+    }
+    catch {
+        if (result.isError === true)
+            throw new AnalysisProtocolError(`JEB MCP tool failed: ${blocks[0] ?? "unexplained engine failure"}`);
+        return blocks[0] ?? null;
+    }
+};
+/** Serve JEB requests from a running engine client over streamable HTTP. */
+export const createStreamableHttpJebMcpConnection = (endpoint) => {
+    let state;
+    let closing;
+    let closed = false;
+    const waitForCaller = (promise, signal) => {
+        if (signal?.aborted === true)
+            return Promise.reject(new AnalysisCancelledError("jeb_mcp"));
+        if (signal === undefined)
+            return promise;
+        return new Promise((resolve, reject) => {
+            const abort = () => {
+                signal.removeEventListener("abort", abort);
+                reject(new AnalysisCancelledError("jeb_mcp"));
+            };
+            signal.addEventListener("abort", abort, { once: true });
+            void promise.then((value) => {
+                signal.removeEventListener("abort", abort);
+                resolve(value);
+            }, (cause) => {
+                signal.removeEventListener("abort", abort);
+                reject(cause);
+            });
+        });
+    };
+    const dispose = async (owner) => {
+        if (owner.disposal !== undefined)
+            return owner.disposal;
+        const cleanup = (async () => {
+            const settled = await Promise.allSettled([
+                owner.client.close(),
+                owner.transport.close(),
+            ]);
+            const failures = settled.flatMap((result) => result.status === "rejected" ? [result.reason] : []);
+            if (failures.length > 0)
+                throw new AggregateError(failures, "JEB MCP connection cleanup failed");
+            if (state === owner)
+                state = undefined;
+        })();
+        owner.disposal = cleanup;
+        try {
+            await cleanup;
+        }
+        catch (cause) {
+            owner.disposal = undefined;
+            throw cause;
+        }
+    };
+    const connect = async (signal) => {
+        if (signal?.aborted === true)
+            throw new AnalysisCancelledError("jeb_mcp");
+        if (closing !== undefined)
+            await closing;
+        if (closed) {
+            if (state !== undefined)
+                await dispose(state);
+            throw new AnalysisProtocolError("JEB MCP connection is closed");
+        }
+        if (state?.tools !== undefined && state.disposal === undefined)
+            return state.tools;
+        if (state?.acquisition !== undefined)
+            return waitForCaller(state.acquisition, signal);
+        if (state !== undefined) {
+            await dispose(state);
+            if (state !== undefined || closing !== undefined)
+                return connect(signal);
+        }
+        const owner = {
+            client: new Client({
+                name: "rea-jeb",
+                version: "0.0.0",
+            }),
+            transport: new StreamableHTTPClientTransport(endpoint, {
+                requestInit: { redirect: "error" },
+            }),
+            signal: new AbortController(),
+            tools: undefined,
+            acquisition: undefined,
+            disposal: undefined,
+        };
+        state = owner;
+        const acquisition = (async () => {
+            try {
+                await owner.client.connect(owner.transport, {
+                    signal: owner.signal.signal,
+                });
+                const listing = await owner.client.listTools({}, { signal: owner.signal.signal });
+                const tools = listing.tools.map((tool) => tool.name);
+                owner.tools = tools;
+                return tools;
+            }
+            catch (cause) {
+                owner.signal.abort(cause);
+                try {
+                    await dispose(owner);
+                }
+                catch (cleanupCause) {
+                    throw new AggregateError([cause, cleanupCause], "JEB MCP connection acquisition and cleanup failed", { cause });
+                }
+                throw cause;
+            }
+        })();
+        owner.acquisition = acquisition;
+        void acquisition.then(() => {
+            if (owner.acquisition === acquisition)
+                owner.acquisition = undefined;
+        }, () => {
+            if (owner.acquisition === acquisition)
+                owner.acquisition = undefined;
+        });
+        return waitForCaller(acquisition, signal);
+    };
+    return {
+        connect,
+        async call(name, args, signal) {
+            await connect(signal);
+            const owner = state;
+            if (owner === undefined || owner.tools === undefined)
+                throw new AnalysisProtocolError("JEB MCP client failed to connect");
+            const result = await owner.client.callTool({ name, arguments: args }, signal === undefined ? {} : { signal });
+            return decodeJebToolResult(result);
+        },
+        async close() {
+            closed = true;
+            if (closing !== undefined)
+                return closing;
+            const operation = (async () => {
+                const owner = state;
+                if (owner === undefined)
+                    return;
+                owner.tools = undefined;
+                owner.signal.abort();
+                if (owner.acquisition !== undefined)
+                    await owner.acquisition.catch(() => undefined);
+                if (state === owner)
+                    await dispose(owner);
+            })();
+            closing = operation;
+            try {
+                await operation;
+            }
+            finally {
+                if (closing === operation)
+                    closing = undefined;
+            }
+        },
+    };
+};

package/dist/jeb/JebMcpEndpoint.js

@@ -0,0 +1,40 @@
+import { AnalysisInputError } from "../domain/analysisErrorCore.js";
+import { err, ok } from "../domain/result.js";
+/** Default JEB MCP endpoint documented by the engine's headless client. */
+export const DEFAULT_JEB_MCP_ENDPOINT = "http://127.0.0.1:8425/mcp";
+/**
+ * Normalize the caller-selected JEB MCP endpoint.
+ *
+ * Only the scheme, host, and port select the engine; credentials, paths with
+ * segments beyond the MCP route, queries, and fragments are rejected rather
+ * than silently dropped.
+ */
+export const parseJebMcpEndpoint = (value) => {
+    const raw = value === undefined || value.length === 0 ? null : value;
+    let url;
+    try {
+        url = new URL(raw ?? DEFAULT_JEB_MCP_ENDPOINT);
+    }
+    catch {
+        return err(new AnalysisInputError("jeb_mcp_endpoint", {
+            cause: "Expected an absolute http(s) URL",
+        }));
+    }
+    if (url.protocol !== "http:" && url.protocol !== "https:")
+        return err(new AnalysisInputError("jeb_mcp_endpoint", {
+            cause: "Only http and https JEB MCP endpoints are supported",
+        }));
+    if (url.hostname !== "127.0.0.1" && url.hostname !== "[::1]")
+        return err(new AnalysisInputError("jeb_mcp_endpoint", {
+            cause: "JEB MCP endpoint must use a literal loopback host (127.0.0.1 or ::1)",
+        }));
+    if (url.username !== "" || url.password !== "")
+        return err(new AnalysisInputError("jeb_mcp_endpoint", {
+            cause: "Embedding credentials in the JEB MCP endpoint is not supported; configure authentication with the engine",
+        }));
+    if (url.search !== "" || url.hash !== "")
+        return err(new AnalysisInputError("jeb_mcp_endpoint", {
+            cause: "JEB MCP endpoint query strings and fragments are not supported",
+        }));
+    return ok(url);
+};

package/dist/jeb/JebProvider.js

@@ -0,0 +1,299 @@
+import { z } from "zod";
+import { createAnalysisExecution } from "../application/AnalysisProvider.js";
+import { jebResultSchemas } from "../domain/jeb/jebAnalysis.js";
+import { AnalysisCancelledError, AnalysisCapabilityUnavailableError, AnalysisProtocolError, AnalysisUnsupportedTargetError, } from "../domain/analysisErrorCore.js";
+import { AnalysisError } from "../domain/analysisErrorBase.js";
+import { err, ok } from "../domain/result.js";
+import { parseJebMcpEndpoint, DEFAULT_JEB_MCP_ENDPOINT, } from "./JebMcpEndpoint.js";
+import { createStreamableHttpJebMcpConnection, } from "./JebMcpConnection.js";
+export const JEB_PROVIDER_IDENTITY = {
+    id: "jeb",
+    name: "JEB",
+    version: null,
+};
+/** JEB's tool envelope: success with typed fields, or a message-only failure. */
+const failure = z
+    .object({
+    success: z.literal(false),
+    message: z.string().optional(),
+    error: z
+        .object({
+        code: z.string().optional(),
+        message: z.string().optional(),
+        recovery_tool: z.string().optional(),
+    })
+        .optional(),
+})
+    .passthrough();
+const clientInformation = z
+    .object({
+    success: z.literal(true),
+    version: z.string().optional(),
+    gui_client: z.boolean().optional(),
+    startup_ts: z.number().int().nonnegative().optional(),
+    message: z.string().nullish(),
+})
+    .passthrough();
+const unitEntry = z.object({ unit_path: z.string(), unit_type: z.string() });
+const openProject = z
+    .object({
+    success: z.literal(true),
+    name: z.string().nullish(),
+    creation_datetime: z.string().nullish(),
+    input_files: z
+        .array(z.object({
+        file_name: z.string(),
+        file_size: z.number().int().nonnegative(),
+        contents_sha256_hash: z.string(),
+    }))
+        .optional(),
+    units: z.array(unitEntry).optional(),
+})
+    .passthrough();
+const listUnits = z
+    .object({ success: z.literal(true), units: z.array(unitEntry) })
+    .passthrough();
+const decompiledItem = z
+    .object({ success: z.literal(true), text: z.string() })
+    .passthrough();
+const refusalReason = (payload, fallback) => {
+    const parsed = failure.safeParse(payload);
+    if (!parsed.success)
+        return fallback;
+    const envelope = parsed.data;
+    const reason = envelope.error?.message ?? envelope.message ?? envelope.error?.code;
+    if (reason !== undefined && reason.length > 0)
+        return reason;
+    return fallback;
+};
+/** Serve REA's JEB operations from a running engine client over MCP. */
+export class JebProvider {
+    #connection;
+    #endpoint;
+    #identity = JEB_PROVIDER_IDENTITY;
+    #guiClient = null;
+    constructor(options = {}) {
+        const environment = options.environment ?? {};
+        const endpoint = parseJebMcpEndpoint(environment.REA_JEB_MCP_URL);
+        if (!endpoint.ok)
+            throw endpoint.error;
+        this.#endpoint = endpoint.value;
+        this.#connection = (options.connectionFactory ??
+            ((url) => createStreamableHttpJebMcpConnection(url)))(this.#endpoint);
+    }
+    async inspectAvailability(signal) {
+        try {
+            await this.#refreshClientInformation(signal);
+            return {
+                status: "available",
+                code: null,
+                reason: null,
+                diagnostics: {
+                    endpoint: this.#endpoint.toString(),
+                    engine_version: this.#identity.version,
+                },
+            };
+        }
+        catch (cause) {
+            if (signal?.aborted === true)
+                throw cause;
+            return {
+                status: "unavailable",
+                code: "not_configured",
+                reason: cause instanceof Error
+                    ? cause.message
+                    : "The JEB MCP endpoint did not respond",
+                diagnostics: { endpoint: this.#endpoint.toString() },
+            };
+        }
+    }
+    async close() {
+        await this.#connection.close();
+    }
+    async execute(request, options) {
+        if (options?.signal?.aborted === true)
+            return err(new AnalysisCancelledError(request.operation));
+        try {
+            const execution = await this.#dispatch(request, options?.signal);
+            if (options?.signal?.aborted)
+                return err(new AnalysisCancelledError(request.operation));
+            if (execution.ok)
+                this.#identity = {
+                    ...this.#identity,
+                    version: execution.value.provider.version,
+                };
+            return execution;
+        }
+        catch (cause) {
+            if (options?.signal?.aborted)
+                return err(new AnalysisCancelledError(request.operation, { cause }));
+            return err(this.#providerFailure(request.operation, cause));
+        }
+    }
+    async #dispatch(request, signal) {
+        const cancelled = (operation) => {
+            if (signal?.aborted === true)
+                throw new AnalysisCancelledError(operation);
+        };
+        switch (request.operation) {
+            case "inspect_jeb_client": {
+                cancelled(request.operation);
+                return this.#inspectClient(signal);
+            }
+            case "open_jeb_project": {
+                cancelled(request.operation);
+                return this.#openProject(request, signal);
+            }
+            case "list_jeb_units": {
+                cancelled(request.operation);
+                return this.#listUnits(request, signal);
+            }
+            case "decompile_jeb_item": {
+                cancelled(request.operation);
+                return this.#decompileItem(request, signal);
+            }
+        }
+    }
+    async #engine(signal) {
+        await this.#requireClientInformation(signal);
+        return {
+            name: "jeb",
+            version: this.#identity.version,
+            endpoint: this.#endpoint.toString(),
+            gui_client: this.#guiClient,
+        };
+    }
+    async #requireClientInformation(signal) {
+        if (this.#identity.version !== null)
+            return;
+        await this.#refreshClientInformation(signal);
+    }
+    async #refreshClientInformation(signal) {
+        if (signal?.aborted === true)
+            throw new AnalysisCancelledError("inspect_jeb_client");
+        const payload = await this.#connection.call("get_client_information", {}, signal);
+        const information = clientInformation.parse(this.#requireSuccess(payload, "inspect_jeb_client"));
+        this.#identity = {
+            ...this.#identity,
+            version: information.version ?? null,
+        };
+        this.#guiClient = information.gui_client ?? null;
+    }
+    async #inspectClient(signal) {
+        const payload = await this.#connection.call("get_client_information", {}, signal);
+        const information = clientInformation.parse(this.#requireSuccess(payload, "inspect_jeb_client"));
+        this.#identity = {
+            ...this.#identity,
+            version: information.version ?? null,
+        };
+        this.#guiClient = information.gui_client ?? null;
+        const result = jebResultSchemas.inspect_jeb_client.parse({
+            engine: {
+                name: "jeb",
+                version: information.version ?? null,
+                endpoint: this.#endpoint.toString(),
+                gui_client: information.gui_client ?? null,
+            },
+            startup_ts: information.startup_ts ?? null,
+            message: information.message ?? null,
+        });
+        return ok(createAnalysisExecution(result, this.#identity, {
+            rawResult: payload,
+            limitations: information.version === undefined
+                ? ["The engine did not report its version."]
+                : [],
+        }));
+    }
+    async #openProject(request, signal) {
+        const payload = await this.#connection.call("open_project", {
+            file_path: request.input.path,
+        }, signal);
+        const opened = openProject.parse(this.#requireSuccess(payload, request.operation));
+        const engine = await this.#engine(signal);
+        const result = jebResultSchemas.open_jeb_project.parse({
+            engine,
+            project_name: opened.name ?? null,
+            creation_datetime: opened.creation_datetime ?? null,
+            input_files: opened.input_files ?? [],
+            units: opened.units ?? [],
+        });
+        return ok(createAnalysisExecution(result, this.#identity, {
+            rawResult: payload,
+            limitations: [
+                "JEB resolves and analyzes the artifact on the engine host; REA did not open the target itself.",
+            ],
+        }));
+    }
+    async #listUnits(request, signal) {
+        const { count, index, filter, parent_unit_path } = request.input;
+        const payload = await this.#connection.call("list_units", {
+            count,
+            index,
+            ...(filter === undefined ? {} : { filter }),
+            ...(parent_unit_path === undefined ? {} : { parent_unit_path }),
+        }, signal);
+        const listed = listUnits.parse(this.#requireSuccess(payload, request.operation));
+        const units = listed.units;
+        const engine = await this.#engine(signal);
+        const result = jebResultSchemas.list_jeb_units.parse({
+            engine,
+            filter: filter ?? null,
+            parent_unit_path: parent_unit_path ?? null,
+            index,
+            count,
+            units,
+            coverage: units.length < count ? "complete" : "partial",
+        });
+        return ok(createAnalysisExecution(result, this.#identity, {
+            rawResult: payload,
+            limitations: [
+                "The engine caps unit pages at 100; a full page means more units may exist.",
+            ],
+        }));
+    }
+    async #decompileItem(request, signal) {
+        const { item_address, item_kind, unit_path } = request.input;
+        const payload = await this.#connection.call("decompile_code_item", {
+            item_address,
+            item_kind,
+            ...(unit_path === undefined ? {} : { unit_path }),
+        }, signal);
+        const decompiled = decompiledItem.parse(this.#requireSuccess(payload, request.operation));
+        const engine = await this.#engine(signal);
+        const result = jebResultSchemas.decompile_jeb_item.parse({
+            engine,
+            unit_path: unit_path ?? null,
+            item_address,
+            item_kind,
+            text: decompiled.text,
+        });
+        return ok(createAnalysisExecution(result, this.#identity, {
+            rawResult: payload,
+            limitations: unit_path === undefined
+                ? [
+                    "The engine selected the project's first code unit implicitly; the effective unit identity is unknown.",
+                ]
+                : [],
+        }));
+    }
+    #requireSuccess(payload, operation) {
+        if (typeof payload !== "object" || payload === null)
+            throw new AnalysisProtocolError("JEB MCP returned a non-object envelope; no observation can be established");
+        const success = payload.success;
+        if (success === false)
+            throw new AnalysisUnsupportedTargetError(operation, this.#endpoint.toString(), refusalReason(payload, "The engine refused the request"));
+        if (success !== true)
+            throw new AnalysisProtocolError("JEB MCP omitted its success field; no observation can be established");
+        return payload;
+    }
+    #providerFailure(operation, cause) {
+        if (cause instanceof AnalysisError)
+            return cause;
+        if (cause instanceof z.ZodError)
+            return new AnalysisProtocolError("JEB omitted or malformed required observation fields", { cause });
+        return new AnalysisCapabilityUnavailableError("jeb", operation, cause instanceof Error ? cause.message : String(cause), {
+            cause: cause instanceof Error ? cause : undefined,
+            userMessage: `Start a JEB client serving MCP (default ${DEFAULT_JEB_MCP_ENDPOINT}) or set REA_JEB_MCP_URL to the running endpoint.`,
+        });
+    }
+}

package/dist/mcpDoctor.js

@@ -5,6 +5,7 @@ import { resolve } from "node:path";
 import { CATALOG_IDENTITY } from "./catalogIdentity.js";
 import { PROMPT_CONTRACTS } from "./contracts/promptContracts.js";
 import { TOOL_CONTRACTS } from "./contracts/toolContracts.js";
+import { err, ok } from "./domain/result.js";
 import { PRODUCT_IDENTITY } from "./identity.js";
 import { MCP_STARTUP_POLICY } from "./mcpStartupPolicy.js";
 const OUTPUT_FORMATS = ["toon", "json", "yaml", "md", "jsonl"];
@@ -85,16 +86,22 @@ export const runProductionMcpDoctor = async (options) => {
 };
 const inspectProductionMcpSession = async (client, deadline, signal) => {
     const request = requestOptions(deadline, signal);
-    const [tools, prompts, requestFlow] = await Promise.all([
+    const [tools, prompts] = await Promise.all([
         client.listTools(undefined, request),
         client.listPrompts(undefined, request),
-        client.callTool({ name: "binary_session", arguments: {} }, request),
     ]);
+    const sessionTool = tools.tools.find(({ name }) => name === "binary_session");
+    const requestFlow = await client
+        .callTool({ name: "binary_session", arguments: {} }, {
+        ...requestOptions(deadline, signal),
+        ...(sessionTool === undefined ? {} : { toolDefinition: sessionTool }),
+    })
+        .then(ok, (cause) => err({ kind: "request-flow", detail: errorMessage(cause) }));
     const inventory = {
         tools: compareInventory(TOOL_CONTRACTS.map(({ name }) => name), tools.tools.map(({ name }) => name)),
         prompts: compareInventory(PROMPT_CONTRACTS.map(({ name }) => name), prompts.prompts.map(({ name }) => name)),
     };
-    const observedIdentity = parseIdentityToolResult(requestFlow.structuredContent);
+    const observedIdentity = parseIdentityToolResult(requestFlow.ok ? requestFlow.value.structuredContent : undefined);
     const serverVersion = client.getServerVersion();
     const protocolVersion = client.getNegotiatedProtocolVersion();
     const checks = [
@@ -115,8 +122,10 @@ const inspectProductionMcpSession = async (client, deadline, signal) => {
         },
         {
             name: "request-flow",
-            ok: requestFlow.isError !== true,
-            detail: "binary_session target-free request",
+            ok: requestFlow.ok && requestFlow.value.isError !== true,
+            detail: requestFlow.ok
+                ? "binary_session target-free request"
+                : requestFlow.error.detail,
         },
     ];
     return {
@@ -136,7 +145,7 @@ const inspectProductionMcpSession = async (client, deadline, signal) => {
         },
         request_flow: {
             tool: "binary_session",
-            ok: requestFlow.isError !== true,
+            ok: requestFlow.ok && requestFlow.value.isError !== true,
         },
         checks,
     };

package/dist/native/AppleDispatchCoverage.js

@@ -1,9 +1,15 @@
 const describeFixups = (fixups) => {
-    if (fixups.kind === "chained")
-        return `chained fixups: ${fixups.formats.join(", ") || "no fixup segments"}`;
-    return fixups.kind === "dyld-info"
-        ? "LC_DYLD_INFO bind opcodes"
-        : "no fixup load commands";
+    const unread = fixups.unreadRebaseBytes > 0
+        ? `LC_DYLD_INFO rebase opcodes were not decoded (${fixups.unreadRebaseBytes} bytes)`
+        : undefined;
+    const kind = fixups.kind === "chained"
+        ? `chained fixups: ${fixups.formats.join(", ") || "no fixup segments"}`
+        : fixups.kind === "dyld-info"
+            ? "LC_DYLD_INFO bind opcodes"
+            : unread === undefined
+                ? "no fixup load commands"
+                : undefined;
+    return [unread, kind].filter((line) => line !== undefined).join("; ");
 };
 /** Append the per-facet coverage of one Apple dispatch metadata decode. */
 export const pushDispatchCoverage = (input) => {
@@ -42,15 +48,22 @@ export const pushDispatchCoverage = (input) => {
         examined: categoriesExamined,
         decoded: result.objc_categories.filter(({ decode }) => decode.status === "decoded").length,
     });
+    const fixupReason = [
+        describeFixups(fixups),
+        ...fixups.issues.map(({ code, location, message }) => `${code}${location === undefined ? "" : ` at ${location}`}: ${message}`),
+    ]
+        .filter((line) => line.length > 0)
+        .join("; ");
     result.coverage.push({
         facet: "pointer_fixups",
-        status: fixups.issues.length > 0 ? "partial" : "complete",
-        reason: [
-            describeFixups(fixups),
-            ...fixups.issues.map(({ code, location, message }) => `${code}${location === undefined ? "" : ` at ${location}`}: ${message}`),
-        ].join("; "),
-        examined: 0,
-        decoded: 0,
+        status: fixups.issues.length > 0 || fixups.unreadRebaseBytes > 0
+            ? "partial"
+            : fixups.examined === 0
+                ? "unsupported"
+                : "complete",
+        reason: fixupReason.length > 0 ? fixupReason : null,
+        examined: fixups.examined,
+        decoded: fixups.issues.length > 0 ? 0 : fixups.examined,
     });
     result.coverage.push({
         facet: "swift_generic_resilient_witnesses_overrides_async_coroutines",

package/dist/native/AppleDispatchMetadata.js

@@ -1,8 +1,8 @@
 import { createHash } from "node:crypto";
-import { open } from "node:fs/promises";
-import { constants } from "node:fs";
 import { objcSwiftMetadataSchema, nativeDispatchMetadataResultSchema, } from "../domain/native/objcSwiftMetadata.js";
-import { AnalysisCancelledError } from "../domain/analysisErrorCore.js";
+import { AnalysisCancelledError, AnalysisResourceConstraintError, } from "../domain/analysisErrorCore.js";
+import { openRegularFile } from "../filesystem/RegularFile.js";
+import { readBoundedFileBytes } from "../process/BoundedFileBytes.js";
 import { EvidenceIntegrityError } from "../domain/evidenceErrors.js";
 import { pushDispatchCoverage } from "./AppleDispatchCoverage.js";
 import { parsePointerFixups } from "./AppleMachoFixups.js";
@@ -140,14 +140,21 @@ export const decodeAppleDispatchMetadata = (bytes, maxRecords, provenance, archi
 export const inspectAppleDispatchMetadata = async (target, maxRecords, signal) => {
     if (target.kind !== "executable" || target.format !== "mach-o")
         throw new TypeError("Apple dispatch metadata requires a Mach-O target");
-    const handle = await open(target.path, constants.O_RDONLY | constants.O_NOFOLLOW);
+    const maximumBytes = 64 * 1024 * 1024;
+    const capacityError = () => new AnalysisResourceConstraintError("inspect_native_dispatch_metadata", "memory", "Apple static metadata input exceeds its 64 MiB snapshot budget", { input_bytes: maximumBytes });
+    const handle = await openRegularFile(target.path, {
+        symlinks: "reject",
+        signal,
+    });
     try {
         const before = await handle.stat();
-        if (!before.isFile() || before.size > 64 * 1024 * 1024)
-            throw new RangeError("Apple metadata target must be a regular file no larger than 64 MiB");
+        if (before.size > maximumBytes)
+            throw capacityError();
         if (signal?.aborted)
             throw new AnalysisCancelledError("inspect_native_dispatch_metadata");
-        const bytes = await handle.readFile({ signal });
+        const bytes = await readBoundedFileBytes(handle, maximumBytes, signal);
+        if (bytes === undefined)
+            throw capacityError();
         const digest = createHash("sha256").update(bytes).digest("hex");
         if (digest !== target.sha256)
             throw new EvidenceIntegrityError("Apple metadata target digest changed after session binding");