rea-agents 6.0.0 → 6.2.0

package/dist/application/EnhancedLiteralTracing.js

@@ -28,32 +28,29 @@ export const traceLiteralFeature = async (call, input, signal) => {
 };
 const literalMatches = async (call, input, sources, signal) => {
     const matches = [];
-    const needles = [...new Set(input.query.trim().split(/\s+/u))];
     const matched = new Set();
-    for (const needle of needles) {
-        for (const [tool, type] of sources) {
-            const result = await call(tool, {
-                pattern: needle,
-                mode: "literal",
-                case_sensitive: input.case_sensitive,
-            }, signal);
-            if (!result.ok)
-                return result;
-            const items = z
-                .array(z.object({ address: z.string(), value: z.string() }))
-                .safeParse(result.value);
-            if (!items.success)
-                return err(new AnalysisOutputError(tool, "provider returned an invalid search result"));
-            addPageMatches({
-                items: items.data.map(({ address, value: name }) => ({
-                    address,
-                    name,
-                })),
-                type,
-                matches,
-                matched,
-            });
-        }
+    for (const [tool, type] of sources) {
+        const result = await call(tool, {
+            pattern: input.query,
+            mode: "literal",
+            case_sensitive: input.case_sensitive,
+        }, signal);
+        if (!result.ok)
+            return result;
+        const items = z
+            .array(z.object({ address: z.string(), value: z.string() }))
+            .safeParse(result.value);
+        if (!items.success)
+            return err(new AnalysisOutputError(tool, "provider returned an invalid search result"));
+        addPageMatches({
+            items: items.data.map(({ address, value: name }) => ({
+                address,
+                name,
+            })),
+            type,
+            matches,
+            matched,
+        });
     }
     return ok({ matches });
 };

package/dist/application/EnhancedTools.js

@@ -1,9 +1,9 @@
 import { z } from "zod";
 import { enhancedInputSchemas } from "../contracts/enhancedInputs.js";
-import { AnalysisCancelledError, AnalysisOutputError, } from "../domain/analysisErrorCore.js";
+import { AnalysisCancelledError, AnalysisCapabilityUnavailableError, AnalysisOutputError, } from "../domain/analysisErrorCore.js";
 import { projectAnalysisError } from "../domain/analysisErrorProjection.js";
 import {} from "../domain/analysisErrorBase.js";
-import { addressDistance, functionDossierSchema, parseDocuments, parseFunctionDossier, parseListCount, parseRelatedAddresses, parseSegments, } from "../domain/hopperValues.js";
+import { addressDistance, functionDossierSchema, parseFunctionDossier, parseListCount, parseRelatedAddresses, parseSegments, } from "../domain/hopperValues.js";
 import { err, ok } from "../domain/result.js";
 import { categorizeSwiftTypes, discoverObjcClasses, discoverObjcProtocols, } from "../domain/symbolAnalysis.js";
 import { inspectNativeDispatch } from "./native/NativeDispatchMetadataInspection.js";
@@ -11,7 +11,9 @@ import { traceNativeValues } from "./native/NativeValueTrace.js";
 import { traceNativeUiAction } from "./native/NativeUiActionTrace.js";
 import { jsonValueSchema } from "../domain/jsonValue.js";
 import { invalidEnhancedInput, } from "./EnhancedToolTypes.js";
+import { resolveAnalysisDocument } from "./AnalysisDocument.js";
 import { traceCallPath } from "./CallPathTracing.js";
+import { resolveProcedureAddress } from "./ProcedureAddressResolution.js";
 import { traceLiteralFeature } from "./EnhancedLiteralTracing.js";
 import { projectNativeApiInspection } from "./native/NativeApiInspection.js";
 /**
@@ -177,20 +179,34 @@ export class EnhancedTools {
     }
     async #batchDecompile(addresses, signal) {
         const items = await Promise.all(addresses.map(async (address) => {
-            const result = await this.#call("procedure_pseudo_code", { procedure: address }, signal);
+            const resolved = await resolveProcedureAddress(this.#call.bind(this), address, signal);
+            const procedure = resolved.ok
+                ? await this.#batchProcedureIdentity(resolved.value, signal)
+                : {
+                    status: "unknown",
+                    error: projectAnalysisError(resolved.error),
+                };
+            const result = await this.#call("procedure_pseudo_code", { procedure: resolved.ok ? resolved.value : address }, signal);
             if (!result.ok)
                 return {
                     address,
+                    procedure,
                     status: "error",
                     error: projectAnalysisError(result.error),
                 };
             if (typeof result.value !== "string" || result.value.length === 0)
                 return {
                     address,
+                    procedure,
                     status: "error",
                     error: projectAnalysisError(new AnalysisOutputError("procedure_pseudo_code", "provider returned empty pseudocode")),
                 };
-            return { address, status: "ok", pseudocode: result.value };
+            return {
+                address,
+                procedure,
+                status: "ok",
+                pseudocode: result.value,
+            };
         }));
         const succeeded = items.filter(({ status }) => status === "ok").length;
         return ok({
@@ -200,12 +216,32 @@ export class EnhancedTools {
             failed: items.length - succeeded,
         });
     }
+    async #batchProcedureIdentity(address, signal) {
+        const observed = await this.#call("address_name", { address }, signal);
+        const named = observed.ok &&
+            (typeof observed.value === "string" || observed.value === null);
+        return {
+            status: "resolved",
+            address,
+            name: named ? observed.value : null,
+            ...(named
+                ? {}
+                : {
+                    name_error: projectAnalysisError(observed.ok
+                        ? new AnalysisOutputError("address_name", "provider returned an invalid entry label")
+                        : observed.error),
+                }),
+        };
+    }
     async #callGraph(input, signal) {
         const relation = input.direction === "forward" ? "callees" : "callers";
         const tool = input.direction === "forward" ? "procedure_callees" : "procedure_callers";
-        const discovered = new Set([input.address]);
+        const resolved = await resolveProcedureAddress(this.#call.bind(this), input.address, signal);
+        if (!resolved.ok)
+            return resolved;
+        const discovered = new Set([resolved.value]);
         const queue = [
-            { address: input.address, depth: 0 },
+            { address: resolved.value, depth: 0 },
         ];
         let queueIndex = 0;
         const graph = {};
@@ -249,9 +285,23 @@ export class EnhancedTools {
     }
     async #analyzeSwiftTypes(input, signal) {
         const procedures = await this.#allAddressed("list_procedures", signal);
-        return procedures.ok
-            ? ok(categorizeSwiftTypes(procedures.value, input))
-            : procedures;
+        if (!procedures.ok)
+            return procedures;
+        const symbols = await this.#allAddressed("list_names", signal);
+        if (!symbols.ok &&
+            !(symbols.error instanceof AnalysisCapabilityUnavailableError))
+            return symbols;
+        const result = categorizeSwiftTypes(procedures.value, input, symbols.ok ? symbols.value : []);
+        return ok(symbols.ok
+            ? result
+            : {
+                ...result,
+                symbol_inventory_error: projectAnalysisError(symbols.error),
+                limitations: [
+                    ...result.limitations,
+                    "The provider's symbol inventory is unavailable; demangled procedures could not be joined to their Swift aliases.",
+                ],
+            });
     }
     async #findXrefs(name, signal) {
         const names = await this.#allAddressed("list_names", signal);
@@ -274,16 +324,16 @@ export class EnhancedTools {
         });
     }
     async #binaryOverview(signal) {
-        const [segmentsResult, documentsResult, proceduresResult, stringsResult] = await Promise.all([
+        const document = await resolveAnalysisDocument(this.analysis, undefined, signal);
+        if (!document.ok)
+            return document;
+        const [segmentsResult, proceduresResult, stringsResult] = await Promise.all([
             this.#call("list_segments", {}, signal),
-            this.#call("list_documents", {}, signal),
             this.#call("list_procedures", {}, signal),
             this.#call("list_strings", {}, signal),
         ]);
         if (!segmentsResult.ok)
             return segmentsResult;
-        if (!documentsResult.ok)
-            return documentsResult;
         if (!proceduresResult.ok)
             return proceduresResult;
         if (!stringsResult.ok)
@@ -291,9 +341,6 @@ export class EnhancedTools {
         const segments = parseSegments(segmentsResult.value);
         if (!segments.ok)
             return segments;
-        const documents = parseDocuments(documentsResult.value);
-        if (!documents.ok)
-            return documents;
         const procedureCount = parseListCount(proceduresResult.value, "procedures");
         if (!procedureCount.ok)
             return procedureCount;
@@ -301,7 +348,7 @@ export class EnhancedTools {
         if (!stringCount.ok)
             return stringCount;
         return ok({
-            document: documents.value[0] ?? "unknown",
+            document: document.value,
             segments: segments.value.map(({ name, start, end }) => ({
                 name,
                 start,

package/dist/application/EvidenceBundleFiles.js

@@ -1,37 +1,54 @@
-import { parseEvidenceBundle, serializeEvidenceBundle, } from "../domain/evidenceBundle.js";
+import { describeEvidenceBundleFailure, describeValidationFailure, parseEvidenceBundle, } from "../domain/evidenceBundle.js";
 import { EvidenceFileError, EvidenceIntegrityError, } from "../domain/evidenceErrors.js";
 import { err, ok } from "../domain/result.js";
-import { parseProcessCapture } from "../domain/process/processCapture.js";
-import { readJsonFile, writeTextFile } from "./JsonFiles.js";
+import { AnalysisCancelledError } from "../domain/analysisErrorCore.js";
+import { parseProcessCapture } from "../domain/process/processCaptureParsing.js";
+import { bufferedJsonParts, canonicalJsonParts, } from "../domain/jsonSerialization.js";
+import { readJsonFile, writeTextParts } from "./JsonFiles.js";
 /** Read and validate an evidence bundle at the caller-supplied path. */
 export const readEvidenceBundle = async (path) => {
     const loaded = await readJsonFile(path);
     if (!loaded.ok)
         return loaded;
+    let bundle;
     try {
-        const bundle = parseEvidenceBundle(loaded.value);
-        for (const record of bundle.records) {
-            if (record.predicate_type === "rea.process-capture")
-                parseProcessCapture(record.normalized_result);
-        }
-        return ok(bundle);
+        bundle = parseEvidenceBundle(loaded.value);
     }
     catch (cause) {
         return err(new EvidenceIntegrityError("Evidence bundle validation failed", {
             cause,
+            userMessage: describeEvidenceBundleFailure(loaded.value, cause),
         }));
     }
+    for (const record of bundle.records) {
+        if (record.predicate_type !== "rea.process-capture")
+            continue;
+        try {
+            parseProcessCapture(record.normalized_result);
+        }
+        catch (cause) {
+            return err(new EvidenceIntegrityError("Evidence bundle validation failed", {
+                cause,
+                userMessage: `Process capture record ${record.evidence_id} has an invalid normalized_result (${describeValidationFailure(cause)}). Recreate or re-export the bundle, then try again.`,
+            }));
+        }
+    }
+    return ok(bundle);
 };
 /** Atomically write deterministic evidence JSON at the caller-supplied path. */
-export const writeEvidenceBundle = async (bundle, path, overwrite) => {
-    let encoded;
+export const writeEvidenceBundle = async (bundle, path, overwrite, signal) => {
+    if (signal?.aborted === true)
+        return err(new AnalysisCancelledError("export_evidence_bundle"));
+    let checked;
     try {
-        encoded = serializeEvidenceBundle(bundle);
+        checked = parseEvidenceBundle(bundle);
     }
     catch (cause) {
         return err(new EvidenceIntegrityError("Evidence bundle validation failed", {
             cause,
         }));
     }
-    return writeTextFile(encoded, path, overwrite);
+    return writeTextParts(bufferedJsonParts(canonicalJsonParts(checked)), path, overwrite, signal === undefined
+        ? undefined
+        : { signal, operation: "export_evidence_bundle" });
 };

package/dist/application/FunctionAnalysisEvidence.js

@@ -1,15 +1,14 @@
 import { toolContract } from "../contracts/toolContracts.js";
-import { AnalysisInputError } from "../domain/analysisErrorCore.js";
 import { createEvidence } from "../domain/evidence.js";
 import { parseFunctionDossier } from "../domain/hopperValues.js";
 import { jsonObjectSchema } from "../domain/jsonValue.js";
 import { err, ok } from "../domain/result.js";
-import { projectInputIssues } from "../domain/inputIssueProjection.js";
+import { analysisInputErrorFromIssues } from "../domain/inputIssueProjection.js";
 /** Preserve the provider's observations when presenting a validated function dossier. */
 export const executeFunctionAnalysisEvidence = async (analysis, parameters, target, options) => {
     const input = toolContract("analyze_function").inputSchema.safeParse(parameters);
     if (!input.success)
-        return err(new AnalysisInputError("analyze_function", { cause: input.error }, projectInputIssues(input.error.issues, parameters)));
+        return err(analysisInputErrorFromIssues("analyze_function", input.error.issues, parameters, { cause: input.error }));
     const arguments_ = jsonObjectSchema.parse(input.data);
     const execution = await analysis.execute("analyze_function", arguments_, options);
     if (!execution.ok)

package/dist/application/InventoryProjectionEvidence.js

@@ -1,14 +1,15 @@
 import { z } from "zod";
-import { AnalysisInputError, AnalysisProtocolError, } from "../domain/analysisErrorCore.js";
+import { AnalysisProtocolError } from "../domain/analysisErrorCore.js";
 import {} from "../domain/analysisErrorBase.js";
 import { createEvidence, } from "../domain/evidence.js";
 import { jsonValueSchema } from "../domain/jsonValue.js";
 import { err, ok } from "../domain/result.js";
+import { requestInputError, workflowInputError } from "./workflowInputError.js";
 /** Parse one inventory projection and wrap its deterministic result in Evidence. */
 export const projectInventoryEvidence = (options) => {
     const parsed = options.schema.safeParse(options.rawInput);
     if (!parsed.success)
-        return err(new AnalysisInputError(options.operation, { cause: parsed.error }));
+        return err(requestInputError(options.operation, parsed.error, options.rawInput));
     try {
         const result = options.project(parsed.data);
         const first = parsed.data.inventory_evidence[0];
@@ -38,7 +39,7 @@ export const projectInventoryEvidence = (options) => {
     }
     catch (cause) {
         return err(cause instanceof TypeError || cause instanceof z.ZodError
-            ? new AnalysisInputError(options.operation, { cause })
+            ? workflowInputError(options.operation, cause)
             : new AnalysisProtocolError(options.protocolError, { cause }));
     }
 };

package/dist/application/InvestigationProviders.js

@@ -5,9 +5,12 @@ export const REA_WORKFLOW_PROVIDER = {
     name: "REA composed investigation workflow",
     version: "1",
 };
-/** Commit a workflow result to the exact upstream deep-analysis profile. */
-export const workflowAnalysisProfile = (upstream) => createAnalysisProfile(REA_WORKFLOW_PROVIDER, {
+/** Commit a workflow result to its upstream profile and applicable semantic revision. */
+export const workflowAnalysisProfile = (upstream, operation) => createAnalysisProfile(REA_WORKFLOW_PROVIDER, {
     upstream_analysis_profile: upstream,
+    ...(operation === "binary_overview" || operation === "batch_decompile"
+        ? { workflow_revision: 2 }
+        : {}),
 });
 /** Provider identity for deterministic artifact inventories. */
 export const ARTIFACT_GRAPH_PROVIDER = {
@@ -57,6 +60,12 @@ export const JAVASCRIPT_RUNTIME_RECONCILIATION_PROVIDER = {
     name: "REA JavaScript runtime reconciliation",
     version: "1",
 };
+/** Provider identity for selected views of retained analysis Evidence. */
+export const ANALYSIS_VIEW_PROVIDER = {
+    id: "rea-analysis-view",
+    name: "REA analysis view projection",
+    version: "1",
+};
 /** Provider identity for graph-native feature tracing and version comparison. */
 export const JAVASCRIPT_APPLICATION_WORKFLOW_PROVIDER = {
     id: "rea-javascript-application-workflows",

package/dist/application/JsonFiles.js

@@ -1,34 +1,42 @@
-import { link, lstat, mkdtemp, readFile, realpath, rm } from "node:fs/promises";
+import { link, lstat, mkdtemp, open, readFile, realpath, rename, rm, } from "node:fs/promises";
 import { basename, dirname, resolve } from "node:path";
-import writeFileAtomic from "write-file-atomic";
 import { EvidenceFileError } from "../domain/evidenceErrors.js";
+import { AnalysisCancelledError } from "../domain/analysisErrorCore.js";
 import { err, ok } from "../domain/result.js";
 /** Read JSON data from a regular file at the caller-supplied path. */
 export const readJsonFile = async (path) => {
+    const requestedPath = resolve(path);
     try {
-        const canonicalPath = await realpath(resolve(path));
+        const canonicalPath = await realpath(requestedPath);
         const stats = await lstat(canonicalPath);
         if (!stats.isFile())
-            return err(new EvidenceFileError("read", "not-file"));
+            return err(new EvidenceFileError("read", "not-file", { path: requestedPath }));
         const encoded = await readFile(canonicalPath);
         let decoded;
         try {
             decoded = JSON.parse(new TextDecoder("utf-8", { fatal: true, ignoreBOM: true }).decode(encoded));
         }
         catch (cause) {
-            return err(new EvidenceFileError("read", "invalid-json", { cause }));
+            return err(new EvidenceFileError("read", "invalid-json", {
+                cause,
+                path: requestedPath,
+            }));
         }
         return ok(decoded);
     }
     catch (cause) {
-        return err(new EvidenceFileError("read", "io", { cause }));
+        return err(new EvidenceFileError("read", missingOrIo(cause), {
+            cause,
+            path: requestedPath,
+        }));
     }
 };
 /** Atomically write text to the caller-supplied path. */
-export const writeTextFile = async (encoded, path, overwrite) => {
-    const bytes = Buffer.byteLength(encoded, "utf8");
+export const writeTextFile = async (encoded, path, overwrite) => writeTextParts([encoded], path, overwrite);
+export async function writeTextParts(parts, path, overwrite, cancellation) {
+    const requestedPath = resolve(path);
     try {
-        const requestedPath = resolve(path);
+        assertWriteActive(cancellation);
         const canonicalParent = await realpath(dirname(requestedPath));
         const destination = resolve(canonicalParent, basename(requestedPath));
         const existing = await lstat(destination).catch((cause) => {
@@ -38,42 +46,89 @@ export const writeTextFile = async (encoded, path, overwrite) => {
         });
         if (existing !== undefined) {
             if (!overwrite)
-                return err(new EvidenceFileError("write", "exists"));
+                return err(new EvidenceFileError("write", "exists", { path: requestedPath }));
             if (!existing.isFile() || existing.isSymbolicLink())
-                return err(new EvidenceFileError("write", "not-file"));
+                return err(new EvidenceFileError("write", "not-file", { path: requestedPath }));
         }
-        if (overwrite)
-            await writeFileAtomic(destination, encoded, {
-                encoding: "utf8",
-                mode: 0o600,
-                fsync: true,
-            });
-        else
-            await publishNewFile(destination, encoded);
+        assertWriteActive(cancellation);
+        const bytes = await publishFile(destination, parts, overwrite, cancellation);
         return ok({ path: requestedPath, bytes });
     }
     catch (cause) {
+        if (cancellation?.signal.aborted === true &&
+            cause instanceof AnalysisCancelledError &&
+            cause.operation === cancellation.operation)
+            return err(cause);
         if (!overwrite && fileErrorCode(cause) === "EEXIST")
-            return err(new EvidenceFileError("write", "exists", { cause }));
-        return err(new EvidenceFileError("write", "io", { cause }));
+            return err(new EvidenceFileError("write", "exists", {
+                cause,
+                path: requestedPath,
+            }));
+        return err(new EvidenceFileError("write", missingOrIo(cause), {
+            cause,
+            path: requestedPath,
+        }));
     }
+}
+/** A missing path or parent is a selection error, not a permission failure. */
+const missingOrIo = (cause) => {
+    const code = fileErrorCode(cause);
+    return code === "ENOENT" || code === "ENOTDIR" ? "missing" : "io";
 };
-const publishNewFile = async (destination, encoded) => {
+const publishFile = async (destination, parts, overwrite, cancellation) => {
     const stagingDirectory = await mkdtemp(resolve(dirname(destination), ".rea-write-"));
     try {
         const staged = resolve(stagingDirectory, "content");
-        await writeFileAtomic(staged, encoded, {
-            encoding: "utf8",
-            mode: 0o600,
-            fsync: true,
-        });
+        const file = await open(staged, "wx", 0o600);
+        let bytes = 0;
+        try {
+            bytes = await writeStagedParts(file, parts, cancellation);
+            assertWriteActive(cancellation);
+            await file.sync();
+        }
+        finally {
+            await file.close();
+        }
+        // Once submitted, the atomic publication can win a later cancellation race.
+        assertWriteActive(cancellation);
+        if (overwrite)
+            await rename(staged, destination);
         // A hard link publishes complete bytes atomically and cannot replace an existing name.
-        await link(staged, destination);
+        else
+            await link(staged, destination);
+        return bytes;
     }
     finally {
         await rm(stagingDirectory, { recursive: true, force: true });
     }
 };
+const writeStagedParts = async (file, parts, cancellation) => {
+    assertWriteActive(cancellation);
+    const iterator = parts[Symbol.iterator]();
+    let exhausted = false;
+    let bytes = 0;
+    try {
+        for (;;) {
+            assertWriteActive(cancellation);
+            const part = iterator.next();
+            if (part.done)
+                exhausted = true;
+            assertWriteActive(cancellation);
+            if (part.done)
+                return bytes;
+            await file.writeFile(part.value, { encoding: "utf8" });
+            bytes += Buffer.byteLength(part.value, "utf8");
+        }
+    }
+    finally {
+        if (!exhausted)
+            iterator.return?.();
+    }
+};
+const assertWriteActive = (cancellation) => {
+    if (cancellation?.signal.aborted === true)
+        throw new AnalysisCancelledError(cancellation.operation);
+};
 const fileErrorCode = (cause) => typeof cause === "object" && cause !== null && "code" in cause
     ? cause.code
     : undefined;

package/dist/application/LinuxHopper.js

@@ -84,7 +84,7 @@ export const readLinuxDistribution = async () => {
     }
 };
 /** Download, verify, install, and read back the official Hopper Linux package. */
-export const installLinuxHopper = async (host = systemLinuxHopperInstallHost(), options = {}) => {
+export const installLinuxHopper = async (host = systemLinuxHopperInstallHost(process.env), options = {}) => {
     if (options.signal?.aborted === true)
         return { status: "failed", reason: "cancelled" };
     const distribution = await host.distribution();
@@ -124,7 +124,8 @@ export const installLinuxHopper = async (host = systemLinuxHopperInstallHost(),
 };
 /** Canonical launcher path for a legacy user-local Linux Hopper installation. */
 export const linuxHopperLauncherPath = (home) => join(home, ".local/share/rea/hopper/bin/Hopper");
-const systemLinuxHopperInstallHost = () => ({
+/** Compose package-manager and linker checks from the selected caller environment. */
+export const systemLinuxHopperInstallHost = (environment) => ({
     distribution: readLinuxDistribution,
     async download(url, options) {
         const response = await fetch(url, {
@@ -138,11 +139,11 @@ const systemLinuxHopperInstallHost = () => ({
     },
     createTemporaryDirectory: () => mkdtemp(join(tmpdir(), "rea-hopper-")),
     writeArchive: (path, bytes) => writeFile(path, bytes, { mode: 0o600 }),
-    installPackage: installSystemPackage,
+    installPackage: (family, archive) => installSystemPackage(family, archive, environment),
     async launcherStatus(path) {
         try {
             await access(path);
-            const linked = await execFileOutput("ldd", [path]);
+            const linked = await execFileOutput("ldd", [path], { env: environment });
             if (!linuxSharedLibrariesAvailable(`${linked.stdout}\n${linked.stderr}`))
                 return "runtime_dependencies";
             return (await linuxHopperBinarySupported(path))
@@ -175,10 +176,12 @@ export const linuxHopperBinarySupported = async (path) => {
 export const linuxHopperLauncherDigestSupported = (digest) => SUPPORTED_HOPPER_SHA256.has(digest);
 /** Interpret ldd output conservatively so a present but broken launcher is unhealthy. */
 export const linuxSharedLibrariesAvailable = (output) => !/(?:=>\s+not found|error while loading shared libraries)/iu.test(output);
-const installSystemPackage = async (family, archive) => {
+const installSystemPackage = async (family, archive, environment) => {
     try {
         for (const command of linuxPackageManagerCommands(family, archive, process.getuid?.() === 0))
-            await execFileAsync(command.executable, command.args);
+            await execFileAsync(command.executable, command.args, {
+                env: environment,
+            });
         return true;
     }
     catch (cause) {