rea-agents 6.0.0 → 6.1.0

package/dist/native/AppleSwiftDispatchFacets.js

@@ -1,3 +1,4 @@
+import { issue } from "./AppleDispatchDecodeFacts.js";
 const hex = (value) => `0x${value.toString(16)}`;
 const decoded = { status: "decoded", reason: null };
 /** Create a Swift ABI signed-relative pointer decoder that records relative_pointers. */
@@ -42,7 +43,9 @@ export const createSwiftRelativeReader = (input) => {
 export const decodeSwiftDispatchFacets = (input) => {
     const { sections, segments, readers: read, relative, budget, result } = input;
     const swiftFailures = [];
+    const issues = [];
     let swiftExamined = 0;
+    let decodedRecords = 0;
     for (const section of sections.filter(({ name }) => name === "__swift5_proto")) {
         if (section.size % 4 !== 0)
             throw new RangeError("Misaligned Swift conformance section");
@@ -77,6 +80,9 @@ export const decodeSwiftDispatchFacets = (input) => {
                 if (staticWitness && read.pointer(witness) !== descriptor)
                     witnessReason =
                         "Witness-table conformance header is unresolved or encoded";
+                const conformanceDecode = witnessReason === null
+                    ? { status: "decoded", reason: null }
+                    : { status: "partial", reason: witnessReason };
                 result.swift_conformances.push({
                     type_name: typeName,
                     protocol_name: protocolName,
@@ -85,16 +91,14 @@ export const decodeSwiftDispatchFacets = (input) => {
                         ? { address: null, file_offset: null }
                         : read.location(witness),
                     location: read.location(descriptor),
-                    decode: witnessReason === null
-                        ? decoded
-                        : {
-                            status: "partial",
-                            reason: witnessReason,
-                        },
+                    decode: conformanceDecode,
                     evidence: read.evidence(descriptor, "Swift protocol conformance descriptor and directly encoded type/protocol names"),
                 });
+                if (conformanceDecode.status === "decoded")
+                    decodedRecords++;
                 if (witnessReason !== null) {
                     swiftFailures.push(`${typeName}: ${witnessReason}`);
+                    issues.push(issue("swift_conformances_static_witness_slots", "conformance_decode_partial", witnessReason, hex(descriptor)));
                     continue;
                 }
                 const count = read.u32(protocol + 16n);
@@ -113,6 +117,12 @@ export const decodeSwiftDispatchFacets = (input) => {
                         segments.some((segment) => segment.executable &&
                             implementation >= segment.address &&
                             implementation < segment.address + segment.size);
+                    const slotDecode = executable
+                        ? { status: "decoded", reason: null }
+                        : {
+                            status: "partial",
+                            reason: "Witness slot is non-function, async, nil, external, authenticated or encoded; implementation target is unresolved",
+                        };
                     result.swift_dispatch_slots.push({
                         owner: `${typeName}: ${protocolName}`,
                         table_kind: "witness_table",
@@ -122,29 +132,25 @@ export const decodeSwiftDispatchFacets = (input) => {
                         implementation_address: executable ? hex(implementation) : null,
                         thunk_address: null,
                         location: read.location(entry),
-                        decode: executable
-                            ? decoded
-                            : {
-                                status: "partial",
-                                reason: "Witness slot is non-function, async, nil, external, authenticated or encoded; implementation target is unresolved",
-                            },
+                        decode: slotDecode,
                         evidence: read.evidence(entry, "Static Swift witness slot, indexed after the conformance-descriptor header"),
                     });
+                    if (slotDecode.status !== "decoded")
+                        issues.push(issue("swift_conformances_static_witness_slots", "witness_slot_unresolved", slotDecode.reason, hex(entry)));
                 }
             }
             catch (cause) {
-                swiftFailures.push(`${hex(field)}: ${cause instanceof Error ? cause.message : String(cause)}`);
+                const message = cause instanceof Error ? cause.message : String(cause);
+                swiftFailures.push(`${hex(field)}: ${message}`);
+                issues.push(issue("swift_conformances_static_witness_slots", "conformance_decode_failed", message, hex(field)));
             }
         }
     }
-    result.coverage.push({
+    return {
         facet: "swift_conformances_static_witness_slots",
-        status: swiftFailures.length > 0 || budget.truncated ? "partial" : "complete",
-        reason: [
-            ...swiftFailures,
-            ...(budget.truncated ? ["max_records_reached"] : []),
-        ].join("; ") || null,
         examined: swiftExamined,
-        decoded: result.swift_conformances.length,
-    });
+        decoded: decodedRecords,
+        exhaustive: !budget.truncated && issues.length === 0,
+        issues,
+    };
 };

package/dist/native/AppleSwiftVtables.js

@@ -1,11 +1,15 @@
+import { issue } from "./AppleDispatchDecodeFacts.js";
 /** Decode non-generic, non-resilient Swift class vtable descriptors without instantiating metadata. */
 export const decodeSwiftClassVtables = (input) => {
     const { readers: read, result } = input;
     const failures = [];
+    const issues = [];
     let examined = 0;
+    let decoded = 0;
     for (const field of input.entries) {
         if (!read.admit()) {
             failures.push("max_records_reached");
+            issues.push(issue("swift_class_vtable_descriptors", "record_budget_exhausted", "max_records_reached", `0x${field.toString(16)}`));
             break;
         }
         examined++;
@@ -32,11 +36,12 @@ export const decodeSwiftClassVtables = (input) => {
                 throw new RangeError("Swift vtable count or offset exceeds declared metadata bounds");
             const owner = read.string(read.relative(descriptor + 8n));
             for (let index = 0; index < count; index++) {
+                const entry = header + 8n + BigInt(index * 8);
                 if (!read.admit()) {
                     failures.push("max_records_reached");
+                    issues.push(issue("swift_class_vtable_descriptors", "record_budget_exhausted", "max_records_reached", `0x${entry.toString(16)}`));
                     break;
                 }
-                const entry = header + 8n + BigInt(index * 8);
                 const methodFlags = read.u32(entry);
                 // Async slots reference async descriptors; coroutine and future kinds need separate decoders.
                 const synchronous = (methodFlags & 0x40) === 0 && (methodFlags & 15) <= 3;
@@ -61,26 +66,27 @@ export const decodeSwiftClassVtables = (input) => {
                         },
                     evidence: read.evidence(entry, "Swift class vtable method descriptor; slot index is a metadata word offset, not a source method ordinal"),
                 });
+                if (resolved)
+                    decoded++;
+                else
+                    issues.push(issue("swift_class_vtable_descriptors", "vtable_implementation_unresolved", "Async, coroutine, external or unmapped vtable implementation is unresolved", `0x${entry.toString(16)}`));
             }
-            if ((specific & 0x4000) !== 0)
+            if ((specific & 0x4000) !== 0) {
                 failures.push(`${owner}: inherited override descriptors are unsupported`);
+                issues.push(issue("swift_class_vtable_descriptors", "inherited_override_descriptors_unsupported", "Inherited override descriptors are unsupported", `0x${descriptor.toString(16)}`));
+            }
         }
         catch (cause) {
-            failures.push(`0x${field.toString(16)}: ${cause instanceof Error ? cause.message : String(cause)}`);
+            const message = cause instanceof Error ? cause.message : String(cause);
+            failures.push(`0x${field.toString(16)}: ${message}`);
+            issues.push(issue("swift_class_vtable_descriptors", "vtable_decode_failed", message, `0x${field.toString(16)}`));
         }
     }
-    const slots = result.swift_dispatch_slots.filter((slot) => slot.table_kind === "class_vtable");
-    result.coverage.push({
+    return {
         facet: "swift_class_vtable_descriptors",
         examined,
-        decoded: slots.filter((slot) => slot.decode.status === "decoded").length,
-        status: failures.length > 0 ||
-            slots.some((slot) => slot.decode.status !== "decoded")
-            ? "partial"
-            : "complete",
-        reason: failures.join("; ") ||
-            (slots.some((slot) => slot.decode.status !== "decoded")
-                ? "vtable_implementations_unresolved"
-                : null),
-    });
+        decoded,
+        exhaustive: issues.length === 0,
+        issues,
+    };
 };

package/dist/native/CommandRunner.js

@@ -1,30 +1,40 @@
 import { createHash, randomUUID } from "node:crypto";
 import { createReadStream } from "node:fs";
 import { realpath } from "node:fs/promises";
-import { spawn } from "node:child_process";
 import { err, ok } from "../domain/result.js";
+import { OwnedCommandFailure, runOwnedCommand, } from "../process/OwnedCommand.js";
+/** Maximum wall-clock duration for one native command. */
+export const NATIVE_COMMAND_TIMEOUT_MS = 60_000;
+/** Retain complete command output up to a bounded aggregate size. */
+export const NATIVE_COMMAND_OUTPUT_BUDGET_BYTES = 64 * 1024 * 1024;
+/** Native command failure with retained partial output and cleanup status. */
 export class NativeCommandFailure extends Error {
     tool;
     reason;
     exitCode;
-    constructor(tool, reason, exitCode = null, options) {
+    capture;
+    cleanupFailure;
+    cleanupResources;
+    constructor(tool, reason, exitCode = null, options, capture = null, cleanupFailure = null, cleanupResources = []) {
         super(`Native command ${tool} failed: ${reason}`, options);
         this.tool = tool;
         this.reason = reason;
         this.exitCode = exitCode;
+        this.capture = capture;
+        this.cleanupFailure = cleanupFailure;
+        this.cleanupResources = cleanupResources;
     }
 }
 /** Run allowlisted Xcode tools directly without a shell. */
 export class XcrunCommandRunner {
     resolveTool;
-    #resolved = new Map();
     constructor(resolveTool = (tool, signal) => resolveXcrunTool(tool, signal)) {
         this.resolveTool = resolveTool;
     }
     run(tool, arguments_, options) {
         if (!ALLOWED_TOOLS.has(tool))
             return Promise.resolve(err(new NativeCommandFailure(tool, "unavailable")));
-        return this.#resolve(tool, options.signal).then(async (resolved) => {
+        return this.resolveTool(tool, options.signal).then(async (resolved) => {
             if (!resolved.ok)
                 return resolved;
             const captured = await captureProcess(resolved.value.path, arguments_, tool, options);
@@ -35,21 +45,12 @@ export class XcrunCommandRunner {
                     executable: resolved.value.path,
                     executableSha256: resolved.value.sha256,
                     toolVersion: null,
-                    versionReason: "Tool exposes no uniform stable version flag; executable digest identifies it.",
+                    versionReason: "Tool exposes no uniform stable version flag; executable SHA-256 is a prelaunch file sample and does not prove atomic OS image binding.",
                     arguments: [...arguments_],
                 })
                 : captured;
         });
     }
-    async #resolve(tool, signal) {
-        const existing = this.#resolved.get(tool);
-        if (existing !== undefined)
-            return ok(existing);
-        const resolved = await this.resolveTool(tool, signal);
-        if (resolved.ok)
-            this.#resolved.set(tool, resolved.value);
-        return resolved;
-    }
 }
 const ALLOWED_TOOLS = new Set([
     "codesign",
@@ -64,93 +65,89 @@ const ALLOWED_TOOLS = new Set([
     "swift-demangle",
     "vtool",
 ]);
-/** Locate an Xcode tool through `xcrun --find` and pin its executable digest. */
+/** Locate an Xcode tool through `xcrun --find` and sample its executable digest. */
 export const resolveXcrunTool = async (tool, signal) => {
     const found = await captureProcess("/usr/bin/xcrun", ["--find", tool], "xcrun", signal === undefined ? {} : { signal });
     if (!found.ok) {
-        if (found.error.reason === "cancelled")
-            return err(new NativeCommandFailure(tool, "cancelled"));
-        return err(new NativeCommandFailure(tool, "unavailable"));
+        return err(new NativeCommandFailure(tool, found.error.reason === "nonzero-exit" ||
+            found.error.reason === "unavailable"
+            ? "unavailable"
+            : found.error.reason, found.error.exitCode, { cause: found.error }, found.error.capture, found.error.cleanupFailure, found.error.cleanupResources));
     }
     if (found.value.exitCode !== 0)
-        return err(new NativeCommandFailure(tool, "unavailable"));
+        return err(new NativeCommandFailure(tool, "unavailable", found.value.exitCode, undefined, failureCapture(found.value, false)));
     const candidate = found.value.stdout.trim();
     if (!candidate.startsWith("/"))
-        return err(new NativeCommandFailure(tool, "unavailable"));
+        return err(new NativeCommandFailure(tool, "unavailable", found.value.exitCode, undefined, failureCapture(found.value, false)));
     try {
         const path = await realpath(candidate);
-        return ok({ path, sha256: await hashFile(path) });
+        return ok({ path, sha256: await hashFile(path, signal) });
     }
     catch (cause) {
-        return err(new NativeCommandFailure(tool, "io", null, { cause }));
+        const capture = failureCapture(found.value, false);
+        if (signal?.aborted === true)
+            return err(new NativeCommandFailure(tool, "cancelled", capture.exitCode, { cause }, capture));
+        return err(new NativeCommandFailure(tool, "io", capture.exitCode, { cause }, capture));
     }
 };
-const captureProcess = (executable, arguments_, tool, options) => new Promise((resolve) => {
-    if (options.signal?.aborted === true) {
-        resolve(err(new NativeCommandFailure(tool, "cancelled")));
-        return;
+const failureCapture = (capture, truncated) => ({
+    stdout: capture.stdout,
+    stderr: capture.stderr,
+    stdoutBytes: capture.stdoutBytes,
+    stderrBytes: capture.stderrBytes,
+    exitCode: capture.exitCode,
+    signal: capture.signal,
+    truncated,
+});
+const captureProcess = async (executable, arguments_, tool, options) => {
+    const runId = `rea-native-command-${randomUUID()}`;
+    try {
+        const snapshot = await runOwnedCommand({
+            command: executable,
+            arguments: [...arguments_],
+            runId,
+            env: {
+                PATH: "/usr/bin:/bin:/usr/sbin:/sbin",
+                LC_ALL: "C",
+                LANG: "C",
+            },
+            hostEnvironment: {},
+            ...(options.signal === undefined ? {} : { signal: options.signal }),
+        }, {
+            timeoutMs: NATIVE_COMMAND_TIMEOUT_MS,
+            diagnosticBytes: NATIVE_COMMAND_OUTPUT_BUDGET_BYTES,
+            acceptNonZeroExit: options.acceptNonZero === true,
+        });
+        return ok(processCaptureFromSnapshot(snapshot));
     }
-    const runToken = randomUUID();
-    const child = spawn(executable, [...arguments_], {
-        shell: false,
-        stdio: ["ignore", "pipe", "pipe"],
-        env: {
-            PATH: "/usr/bin:/bin:/usr/sbin:/sbin",
-            LC_ALL: "C",
-            LANG: "C",
-            REA_NATIVE_RUN_TOKEN: runToken,
-        },
-    });
-    const stdout = [];
-    const stderr = [];
-    let stdoutBytes = 0;
-    let stderrBytes = 0;
-    let settled = false;
-    let reason;
-    const finish = (result) => {
-        if (settled)
-            return;
-        settled = true;
-        options.signal?.removeEventListener("abort", onAbort);
-        resolve(result);
-    };
-    const stop = (failure) => {
-        reason ??= failure;
-        child.kill("SIGKILL");
-    };
-    const onAbort = () => stop("cancelled");
-    options.signal?.addEventListener("abort", onAbort, { once: true });
-    child.stdout.on("data", (chunk) => {
-        stdoutBytes += chunk.length;
-        stdout.push(chunk);
-    });
-    child.stderr.on("data", (chunk) => {
-        stderrBytes += chunk.length;
-        stderr.push(chunk);
-    });
-    child.once("error", (cause) => finish(err(new NativeCommandFailure(tool, "io", null, { cause }))));
-    child.once("close", (code, signal) => {
-        if (reason !== undefined) {
-            finish(err(new NativeCommandFailure(tool, reason, code)));
-            return;
-        }
-        if (signal !== null || (code !== 0 && options.acceptNonZero !== true)) {
-            finish(err(new NativeCommandFailure(tool, "nonzero-exit", code)));
-            return;
+    catch (cause) {
+        if (cause instanceof OwnedCommandFailure) {
+            const capture = cause.snapshot === null
+                ? null
+                : failureCapture(processCaptureFromSnapshot(cause.snapshot), cause.snapshot.diagnosticTruncated === true);
+            return err(new NativeCommandFailure(tool, cause.reason === "process"
+                ? processFailureReason(capture)
+                : cause.reason, capture?.exitCode ?? null, { cause }, capture, cause.cleanupFailure, cause.resources));
         }
-        finish(ok({
-            stdout: Buffer.concat(stdout).toString("utf8"),
-            stderr: Buffer.concat(stderr).toString("utf8"),
-            stdoutBytes,
-            stderrBytes,
-            exitCode: code,
-            signal,
-        }));
-    });
+        return err(new NativeCommandFailure(tool, "io", null, { cause }));
+    }
+};
+const processFailureReason = (capture) => capture !== null &&
+    (capture.signal !== null ||
+        (capture.exitCode !== null && capture.exitCode !== 0))
+    ? "nonzero-exit"
+    : "io";
+const processCaptureFromSnapshot = (snapshot) => ({
+    stdout: snapshot.stdout.text,
+    stderr: snapshot.stderr.text,
+    stdoutBytes: snapshot.stdout.bytes,
+    stderrBytes: snapshot.stderr.bytes,
+    exitCode: snapshot.exitCode ?? null,
+    signal: snapshot.signal ?? null,
 });
-const hashFile = (path) => new Promise((resolve, reject) => {
+const hashFile = (path, signal) => new Promise((resolve, reject) => {
     const hash = createHash("sha256");
-    const stream = createReadStream(path);
+    const stream = createReadStream(path, signal === undefined ? undefined : { signal });
     stream.on("data", (chunk) => hash.update(chunk));
     stream.once("error", reject);
     stream.once("end", () => resolve(hash.digest("hex")));