rea-agents 4.1.0 → 6.0.0

package/dist/evm/EvmoleFailures.js

@@ -0,0 +1,126 @@
+import { ArtifactReaderFailure } from "../artifacts/ArtifactReader.js";
+import { AnalysisError, } from "../domain/analysisErrorBase.js";
+import { AnalysisAccessDeniedError, AnalysisArtifactChangedError, AnalysisCapabilityUnavailableError, AnalysisCancelledError, AnalysisInputError, AnalysisOutputError, AnalysisResourceConstraintError, AnalysisTimeoutError, } from "../domain/analysisErrorCore.js";
+import { ProviderAdapterError } from "../domain/providerAdapterError.js";
+import { ProviderCleanupError } from "../domain/providerCleanupError.js";
+import { OwnedCommandFailure } from "../process/OwnedCommand.js";
+import { EVMOLE_PROVIDER_IDENTITY, EVM_INTERFACE_LIMITS, EVM_FILE_SIZE_FAILURE_EXIT, } from "./EvmoleRelease.js";
+/** Keep carrier read, engine and owned lifecycle failures distinct. */
+export const evmInterfaceFailure = (cause, phase, path, workerLimits, limiter = "/usr/bin/prlimit", fileFailure) => {
+    if (cause instanceof AnalysisError)
+        return cause;
+    if (cause instanceof OwnedCommandFailure) {
+        const outputOptions = cause.snapshot === null
+            ? undefined
+            : { capturedOutput: capturedEvmOutput(cause.snapshot) };
+        if (cause.cleanupFailure !== null)
+            return new ProviderCleanupError(EVMOLE_PROVIDER_IDENTITY.id, cause.resources, {
+                reason: cause.cleanupFailure,
+                ...(cause.snapshot === null
+                    ? {}
+                    : { captured_output: { ...capturedEvmOutput(cause.snapshot) } }),
+                previous_error: {
+                    failure_kind: cause.reason,
+                    message: cause.message,
+                    exit_code: cause.snapshot?.exitCode ?? null,
+                    signal: cause.snapshot?.signal ?? null,
+                    stdout: cause.snapshot?.stdout.text ?? null,
+                    stderr: cause.snapshot?.stderr.text ?? null,
+                },
+            }, { operation: "inspect_evm_interface", cause });
+        if (cause.reason === "cancelled")
+            return new AnalysisCancelledError("inspect_evm_interface", outputOptions);
+        if (cause.reason === "timeout")
+            return new AnalysisTimeoutError("inspect_evm_interface", EVM_INTERFACE_LIMITS.timeoutMs, outputOptions);
+        if (cause.reason === "output-limit")
+            return new AnalysisOutputError("inspect_evm_interface", cause.message, outputOptions);
+        if (cause.reason === "process" &&
+            (cause.snapshot?.signal === "SIGXCPU" ||
+                cause.snapshot?.signal === "SIGXFSZ" ||
+                (fileFailure?.verified === true &&
+                    cause.snapshot?.exitCode === EVM_FILE_SIZE_FAILURE_EXIT &&
+                    cause.snapshot.signal === null)))
+            return new AnalysisResourceConstraintError("inspect_evm_interface", cause.snapshot.signal === "SIGXCPU" ? "cpu" : "file-size", (cause.snapshot.signal === null
+                ? "Owned EVM worker reported EFBIG while writing its reply; the exact write failure cause is unknown."
+                : `Owned EVM command terminated with ${cause.snapshot.signal}; the exact signal cause is unknown.`) +
+                " Effective worker limits are unknown. Configured soft limits are retained separately.", workerLimits === undefined
+                ? null
+                : {
+                    configured_soft_limits: {
+                        address_space_bytes: workerLimits.addressSpaceBytes,
+                        cpu_seconds: workerLimits.cpuSeconds,
+                        file_size_bytes: workerLimits.fileSizeBytes,
+                    },
+                    effective_soft_limits: null,
+                }, outputOptions);
+    }
+    if (cause instanceof Error &&
+        "code" in cause &&
+        "syscall" in cause &&
+        typeof cause.syscall === "string" &&
+        cause.syscall.startsWith("spawn ")) {
+        const reason = `Configured util-linux prlimit could not launch (${String(cause.code)}): ${limiter}. Check its executable/interpreter and host execute access.`;
+        return new AnalysisCapabilityUnavailableError(EVMOLE_PROVIDER_IDENTITY.id, "inspect_evm_interface", reason, { cause, userMessage: reason });
+    }
+    if (cause instanceof ArtifactReaderFailure) {
+        if (cause.reason === "cancelled")
+            return new AnalysisCancelledError("inspect_evm_interface");
+        if (cause.reason === "integrity")
+            return new AnalysisArtifactChangedError("inspect_evm_interface", path, cause.message, { cause });
+        if (phase === "artifact-read" &&
+            ["limit", "path", "format"].includes(cause.reason))
+            return new AnalysisInputError("inspect_evm_interface", { cause }, [
+                {
+                    path: ["path"],
+                    reason: cause.reason === "limit" ? "out_of_range" : "invalid_format",
+                    message: cause.message,
+                },
+            ]);
+    }
+    if (phase === "artifact-read" && cause instanceof Error && "code" in cause) {
+        if (cause.code === "EACCES" || cause.code === "EPERM")
+            return new AnalysisAccessDeniedError("inspect_evm_interface", path, cause.code, { cause });
+        if (cause.code === "ENOENT" || cause.code === "ENOTDIR")
+            return new AnalysisInputError("inspect_evm_interface", { cause }, [
+                {
+                    path: ["path"],
+                    reason: "invalid_value",
+                    message: `Selected bytecode carrier could not be read (${String(cause.code)}): ${path}.`,
+                },
+            ]);
+    }
+    return new ProviderAdapterError(EVMOLE_PROVIDER_IDENTITY.id, "inspect_evm_interface", {
+        cause,
+        diagnostics: {
+            phase,
+            path,
+            ...(workerLimits === undefined
+                ? {}
+                : { configured_resource_limits: { ...workerLimits } }),
+            reason: cause instanceof Error ? cause.message : String(cause),
+            ...(fileFailure === undefined
+                ? {}
+                : { file_size_failure_marker: { ...fileFailure } }),
+            ...(cause instanceof OwnedCommandFailure
+                ? {
+                    failure_kind: cause.reason,
+                    exit_code: cause.snapshot?.exitCode ?? null,
+                    signal: cause.snapshot?.signal ?? null,
+                    stdout: cause.snapshot?.stdout.text ?? null,
+                    stderr: cause.snapshot?.stderr.text ?? null,
+                    ...(cause.snapshot === null
+                        ? {}
+                        : {
+                            captured_output: { ...capturedEvmOutput(cause.snapshot) },
+                        }),
+                }
+                : {}),
+        },
+    });
+};
+/** Preserve retained worker diagnostics with their observed truncation status. */
+export const capturedEvmOutput = (snapshot) => ({
+    stdout: snapshot.stdout.text,
+    stderr: snapshot.stderr.text,
+    truncated: snapshot.diagnosticTruncated === true,
+});

package/dist/evm/EvmoleInterfaceAdapter.js

@@ -0,0 +1,53 @@
+import { z } from "zod";
+const offset = z.number().int().nonnegative();
+const reportedMetadata = z.strictObject({
+    bytecodeOffset: offset,
+    cborLength: offset,
+    entries: z.array(z.strictObject({
+        key: z.string(),
+        value: z.discriminatedUnion("type", [
+            z.strictObject({ type: z.literal("string"), value: z.string() }),
+            z.strictObject({ type: z.literal("integer"), value: z.number() }),
+            z.strictObject({ type: z.literal("bytes"), value: z.string() }),
+            z.strictObject({ type: z.literal("bool"), value: z.boolean() }),
+            z.strictObject({ type: z.literal("undecoded"), value: z.string() }),
+        ]),
+    })),
+});
+/** Parse the exact producer representation before assigning portable field names. */
+export const evmoleInterfaceReplySchema = z.strictObject({
+    // The unchanged JS binding exposes disabled facets as own undefined keys.
+    // Their JSON transport representation is absence; actual facet values are
+    // outside this interface-only profile and must still fail validation.
+    storage: z.undefined().optional(),
+    transientStorage: z.undefined().optional(),
+    disassembled: z.undefined().optional(),
+    basicBlocks: z.undefined().optional(),
+    controlFlowGraph: z.undefined().optional(),
+    // Upstream also extracts metadata when selectors are requested, regardless
+    // of its metadata flag. Retain its reported values without precision claims.
+    metadata: reportedMetadata.optional(),
+    functions: z
+        .array(z.strictObject({
+        selector: z.string().regex(/^[a-f0-9]{8}$/),
+        bytecodeOffset: offset,
+        dispatch: z.enum(["abi", "fallback"]),
+        arguments: z.string().optional(),
+        stateMutability: z.string().optional(),
+    }))
+        .optional(),
+});
+/** Preserve inference strings and unknown absence; selectors use the conventional 0x display prefix. */
+export const projectEvmoleInterface = (raw) => {
+    const producer = evmoleInterfaceReplySchema.parse(raw);
+    return {
+        raw: producer,
+        functions: (producer.functions ?? []).map((fn) => ({
+            selector: `0x${fn.selector}`,
+            bytecode_offset: fn.bytecodeOffset,
+            dispatch: fn.dispatch,
+            inferred_arguments: fn.arguments ?? null,
+            inferred_state_mutability: fn.stateMutability ?? null,
+        })),
+    };
+};

package/dist/evm/EvmoleInterfaceProvider.js

@@ -0,0 +1,273 @@
+import { createHash, randomUUID } from "node:crypto";
+import { access, readFile, stat, writeFile } from "node:fs/promises";
+import { constants } from "node:fs";
+import { isAbsolute, join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { z } from "zod";
+import { createAnalysisExecution, } from "../application/AnalysisProvider.js";
+import { readStableArtifact } from "../artifacts/readStableArtifact.js";
+import { OwnedCommandFailure } from "../process/OwnedCommand.js";
+import { AnalysisCancelledError, AnalysisCapabilityUnavailableError, AnalysisUnsupportedTargetError, AnalysisInputError, AnalysisOutputError, } from "../domain/analysisErrorCore.js";
+import { projectAnalysisError } from "../domain/analysisErrorProjection.js";
+import { evmInterfaceSchema } from "../domain/evm/evmInterface.js";
+import { ProviderAdapterError } from "../domain/providerAdapterError.js";
+import { ProviderCleanupError } from "../domain/providerCleanupError.js";
+import { err, ok } from "../domain/result.js";
+import { runOwnedCommand } from "../process/OwnedCommand.js";
+import { PrivateRuntimeRoot } from "../process/PrivateRuntimeRoot.js";
+import { evmInterfaceFailure, capturedEvmOutput, } from "./EvmoleFailures.js";
+import { evmoleInterfaceReplySchema, projectEvmoleInterface, } from "./EvmoleInterfaceAdapter.js";
+import { EVMOLE_PROVIDER_IDENTITY, EVM_INTERFACE_LIMITS, EVM_FILE_SIZE_FAILURE_EXIT, } from "./EvmoleRelease.js";
+import { decodeEvmBytecodeCarrier } from "./EvmBytecodeCarrier.js";
+import { selectEvmWorkerLimits, } from "./EvmWorkerLimits.js";
+const OPERATION = "inspect_evm_interface";
+const replySchema = z.discriminatedUnion("ok", [
+    z.strictObject({
+        ok: z.literal(true),
+        version: z.literal("0.9.3"),
+        bytecode: z.strictObject({
+            sha256: z.string().regex(/^[a-f0-9]{64}$/),
+            bytes: z.number().int().nonnegative(),
+            hex: z.string().regex(/^(?:[a-f0-9]{2})*$/),
+        }),
+        raw: evmoleInterfaceReplySchema,
+    }),
+    z.strictObject({
+        ok: z.literal(false),
+        reason: z.enum(["format", "decoder", "output-limit", "unsupported"]),
+        message: z.string(),
+    }),
+]);
+/** Run unchanged EVMole/WASM in an owned worker; no target, chain or network execution. */
+export class EvmoleInterfaceProvider {
+    environment;
+    launcher;
+    createRuntime;
+    constructor(environment = process.env, launcher, createRuntime = () => PrivateRuntimeRoot.create({ prefix: "rea-evm-interface-" })) {
+        this.environment = environment;
+        this.launcher = launcher;
+        this.createRuntime = createRuntime;
+    }
+    /** Bind recovered interface candidates to both original carrier and decoded byte identity. */
+    async inspect(input, options) {
+        let root;
+        let retainedOutput;
+        let phase = "configuration";
+        let workerLimits;
+        const limiter = this.environment.REA_EVM_PRLIMIT_COMMAND ?? "/usr/bin/prlimit";
+        let result;
+        try {
+            if (options?.signal?.aborted)
+                throw new AnalysisCancelledError(OPERATION);
+            if (process.platform !== "linux" || process.arch !== "x64")
+                throw new AnalysisCapabilityUnavailableError(EVMOLE_PROVIDER_IDENTITY.id, OPERATION, "Initial real-verified offline EVM interface profile supports Linux x64 only.");
+            try {
+                if (!isAbsolute(limiter))
+                    throw new Error("REA_EVM_PRLIMIT_COMMAND must be an absolute executable path.");
+                await access(limiter, constants.X_OK);
+                if (!(await stat(limiter)).isFile())
+                    throw new Error("Configured prlimit must be a regular executable file, not a directory.");
+            }
+            catch (cause) {
+                const reason = `Offline EVM interface inspection requires caller-supplied util-linux prlimit: ${limiter}; ${cause instanceof Error ? cause.message : String(cause)}`;
+                throw new AnalysisCapabilityUnavailableError(EVMOLE_PROVIDER_IDENTITY.id, OPERATION, reason, { cause, userMessage: reason });
+            }
+            let inheritedLimits;
+            try {
+                inheritedLimits = await readFile("/proc/self/limits", "utf8");
+            }
+            catch (cause) {
+                const reason = `Could not read inherited Linux resource limits at /proc/self/limits: ${cause instanceof Error ? cause.message : String(cause)}`;
+                throw new AnalysisCapabilityUnavailableError(EVMOLE_PROVIDER_IDENTITY.id, OPERATION, reason, { cause, userMessage: reason });
+            }
+            const limits = selectEvmWorkerLimits(inheritedLimits);
+            if (!limits.ok)
+                throw new AnalysisCapabilityUnavailableError(EVMOLE_PROVIDER_IDENTITY.id, OPERATION, limits.error, { userMessage: limits.error });
+            workerLimits = limits.value;
+            phase = "artifact-read";
+            const carrier = await readStableArtifact(input.path, EVM_INTERFACE_LIMITS.inputBytes, options?.signal);
+            phase = "worker";
+            root = await this.createRuntime();
+            const snapshotPath = join(root.path, "carrier.snapshot");
+            const requestPath = join(root.path, "request.json");
+            const replyPath = join(root.path, "reply.json");
+            await writeFile(snapshotPath, carrier.bytes, {
+                flag: "wx",
+                mode: 0o600,
+                ...(options?.signal === undefined ? {} : { signal: options.signal }),
+            });
+            await writeFile(requestPath, JSON.stringify({
+                snapshot_path: snapshotPath,
+                reply_path: replyPath,
+                failure_marker_path: join(root.path, "resource.failure"),
+                encoding: input.encoding,
+            }), { flag: "wx", mode: 0o600 });
+            const { NODE_OPTIONS: _ambientNodeOptions, ...environment } = this.environment;
+            const execution = await runOwnedCommand({
+                command: limiter,
+                arguments: [
+                    `--as=${String(workerLimits.addressSpaceBytes)}:`,
+                    `--fsize=${String(workerLimits.fileSizeBytes)}:`,
+                    "--core=0:",
+                    `--cpu=${String(workerLimits.cpuSeconds)}:`,
+                    "--",
+                    process.execPath,
+                    "--max-old-space-size=256",
+                    "--v8-pool-size=1",
+                    "--disable-wasm-trap-handler",
+                    fileURLToPath(new URL("./EvmoleInterfaceWorker.js", import.meta.url)),
+                    requestPath,
+                ],
+                cwd: root.path,
+                expectedCommand: null,
+                runId: `rea-evm-interface-${randomUUID()}`,
+                hostEnvironment: environment,
+            }, {
+                timeoutMs: EVM_INTERFACE_LIMITS.timeoutMs,
+                diagnosticBytes: EVM_INTERFACE_LIMITS.diagnosticBytes,
+            }, {
+                ...(options?.signal === undefined ? {} : { signal: options.signal }),
+                ...(this.launcher === undefined ? {} : { launcher: this.launcher }),
+            });
+            const capturedOutput = capturedEvmOutput(execution);
+            retainedOutput = capturedOutput;
+            let reply;
+            try {
+                const file = await readStableArtifact(replyPath, EVM_INTERFACE_LIMITS.outputBytes, options?.signal);
+                reply = replySchema.parse(JSON.parse(file.bytes.toString("utf8")));
+            }
+            catch (cause) {
+                if (options?.signal?.aborted)
+                    throw new AnalysisCancelledError(OPERATION, { capturedOutput });
+                throw new AnalysisOutputError(OPERATION, `Owned interface worker reply failed for ${input.path}: ${cause instanceof Error ? cause.message : String(cause)}`, { cause, capturedOutput });
+            }
+            if (!reply.ok) {
+                if (reply.reason === "unsupported")
+                    throw new AnalysisUnsupportedTargetError(OPERATION, input.path, reply.message, { capturedOutput });
+                if (reply.reason === "format")
+                    throw new AnalysisInputError(OPERATION, { capturedOutput }, [
+                        {
+                            path: ["path"],
+                            reason: "invalid_format",
+                            message: reply.message,
+                        },
+                    ]);
+                if (reply.reason === "output-limit")
+                    throw new AnalysisOutputError(OPERATION, reply.message, {
+                        capturedOutput,
+                    });
+                throw new ProviderAdapterError(EVMOLE_PROVIDER_IDENTITY.id, OPERATION, {
+                    diagnostics: {
+                        phase,
+                        failure_kind: reply.reason,
+                        reason: reply.message,
+                        stdout: execution.stdout.text,
+                        stderr: execution.stderr.text,
+                        captured_output: { ...capturedOutput },
+                    },
+                });
+            }
+            const selectedBytes = decodeEvmBytecodeCarrier(carrier.bytes, input.encoding);
+            const selectedHex = Buffer.from(selectedBytes).toString("hex");
+            const decodedHash = createHash("sha256")
+                .update(selectedBytes)
+                .digest("hex");
+            if (decodedHash !== reply.bytecode.sha256 ||
+                selectedHex !== reply.bytecode.hex ||
+                selectedBytes.length !== reply.bytecode.bytes)
+                throw new AnalysisOutputError(OPERATION, "Decoded bytecode representation does not match the selected carrier, encoding or reported SHA-256.", { capturedOutput });
+            const limitations = [
+                `Configured worker resource soft limits: address_space_bytes=${String(workerLimits.addressSpaceBytes)}, cpu_seconds=${String(workerLimits.cpuSeconds)}, file_size_bytes=${String(workerLimits.fileSizeBytes)}. Selected from inherited tighter limits; original hard limits are retained. Effective worker limits are not independently probed.`,
+                "Upstream may also report terminal metadata while recovering selectors. Its reported values are retained in raw_result, but integer precision and non-text-key coverage are unknown in the JS binding; complete original bytecode remains available.",
+                "Recovered selectors, argument strings and mutability are upstream inferences, not verified ABI signatures or names. Empty results do not prove the absence of callable dispatch.",
+                "Bytecode kind, hardfork and deployed-contract authenticity are unknown. This inspection performs no target runtime execution, chain/RPC lookup or network request.",
+                "Original carrier and decoded bytecode SHA-256 are distinct identities; SHA-256 is not the Ethereum Keccak code hash.",
+                "The owned worker has a 256 MiB JavaScript heap, 3 GiB virtual address-space limit and 30-second deadline. Virtual address space is distinct from resident memory; limits fail without partial success.",
+            ];
+            const validated = evmInterfaceSchema.safeParse({
+                artifact: {
+                    path: input.path,
+                    sha256: carrier.sha256,
+                    bytes: carrier.bytes.length,
+                    encoding: input.encoding,
+                },
+                bytecode: {
+                    ...reply.bytecode,
+                    digest_algorithm: "sha256",
+                    kind: "unknown",
+                    deployment_authenticity: "unknown",
+                    hardfork: "unknown",
+                },
+                evidence_kind: "inferred",
+                functions: projectEvmoleInterface(reply.raw).functions,
+                discovery_completeness: "unknown",
+                runtime_execution: "not-performed",
+                diagnostics: {
+                    stdout: execution.stdout.text,
+                    stderr: execution.stderr.text,
+                    truncated: capturedOutput.truncated,
+                },
+                limitations,
+            });
+            if (!validated.success)
+                throw new AnalysisOutputError(OPERATION, `Interface worker returned invalid bytecode-relative evidence: ${validated.error.issues[0]?.message ?? "schema mismatch"}`, { capturedOutput });
+            const report = validated.data;
+            result = ok(createAnalysisExecution(report, EVMOLE_PROVIDER_IDENTITY, {
+                rawResult: reply.raw,
+                subject: { path: input.path, format: "file", sha256: carrier.sha256 },
+                locations: [{ kind: "artifact-path", path: input.path }],
+                limitations,
+            }));
+        }
+        catch (cause) {
+            let fileFailure;
+            if (cause instanceof OwnedCommandFailure &&
+                cause.snapshot?.exitCode === EVM_FILE_SIZE_FAILURE_EXIT &&
+                cause.snapshot.signal === null &&
+                root !== undefined) {
+                try {
+                    const marker = await readStableArtifact(join(root.path, "resource.failure"), 1);
+                    if (!marker.bytes.equals(Buffer.from("F")))
+                        throw new Error("Private worker failure marker does not match the observed exit status.");
+                    fileFailure = { verified: true, failure: null };
+                }
+                catch (markerFailure) {
+                    fileFailure = {
+                        verified: false,
+                        failure: markerFailure instanceof Error
+                            ? markerFailure.message
+                            : String(markerFailure),
+                    };
+                }
+            }
+            result = err(options?.signal?.aborted &&
+                (cause === options.signal.reason ||
+                    (cause instanceof Error && cause.name === "AbortError"))
+                ? new AnalysisCancelledError(OPERATION, retainedOutput === undefined
+                    ? undefined
+                    : { capturedOutput: retainedOutput })
+                : evmInterfaceFailure(cause, phase, input.path, workerLimits, limiter, fileFailure));
+        }
+        if (root !== undefined) {
+            try {
+                await root.close();
+            }
+            catch (cause) {
+                return err(new ProviderCleanupError(EVMOLE_PROVIDER_IDENTITY.id, [root.path], {
+                    reason: cause instanceof Error ? cause.message : String(cause),
+                    previous_error: result.ok
+                        ? null
+                        : projectAnalysisError(result.error),
+                    ...(retainedOutput === undefined
+                        ? {}
+                        : { captured_output: { ...retainedOutput } }),
+                }, { operation: OPERATION }));
+            }
+        }
+        return result.ok && options?.signal?.aborted
+            ? err(new AnalysisCancelledError(OPERATION, retainedOutput === undefined
+                ? undefined
+                : { capturedOutput: retainedOutput }))
+            : result;
+    }
+}

package/dist/evm/EvmoleInterfaceWorker.js

@@ -0,0 +1,87 @@
+import { createHash } from "node:crypto";
+import { readFile, writeFile } from "node:fs/promises";
+import { z } from "zod";
+import { decodeEvmBytecodeCarrier, EvmCarrierFailure, } from "./EvmBytecodeCarrier.js";
+import { projectEvmoleInterface } from "./EvmoleInterfaceAdapter.js";
+import { EVM_INTERFACE_LIMITS, EVM_FILE_SIZE_FAILURE_EXIT, } from "./EvmoleRelease.js";
+const requestSchema = z.strictObject({
+    snapshot_path: z.string(),
+    reply_path: z.string(),
+    failure_marker_path: z.string(),
+    encoding: z.enum(["raw", "hex"]),
+});
+class UnsupportedContainer extends Error {
+}
+const main = async () => {
+    const requestPath = process.argv[2];
+    if (requestPath === undefined)
+        throw new Error("Owned worker request path missing.");
+    const request = requestSchema.parse(JSON.parse(await readFile(requestPath, "utf8")));
+    let reply;
+    try {
+        const bytes = decodeEvmBytecodeCarrier(await readFile(request.snapshot_path), request.encoding);
+        if (bytes[0] === 0xef && bytes[1] === 0x00)
+            throw new UnsupportedContainer("Container marker EF00 is outside the verified flat-bytecode interface profile.");
+        const modulePath = import.meta.resolve("evmole/no_tla");
+        const metadata = z
+            .object({ version: z.literal("0.9.3") })
+            .parse(JSON.parse(await readFile(new URL("../package.json", modulePath), "utf8")));
+        const engine = await import("evmole/no_tla");
+        engine.initSync({
+            module: await readFile(new URL(import.meta.resolve("evmole/evmole_bg.wasm"))),
+        });
+        const inferred = projectEvmoleInterface(engine.contractInfo(Buffer.from(bytes).toString("hex"), {
+            selectors: true,
+            arguments: true,
+            stateMutability: true,
+        }));
+        reply = {
+            ok: true,
+            version: metadata.version,
+            bytecode: {
+                sha256: createHash("sha256").update(bytes).digest("hex"),
+                bytes: bytes.length,
+                hex: Buffer.from(bytes).toString("hex"),
+            },
+            raw: inferred.raw,
+        };
+    }
+    catch (cause) {
+        reply = {
+            ok: false,
+            reason: cause instanceof EvmCarrierFailure
+                ? "format"
+                : cause instanceof UnsupportedContainer
+                    ? "unsupported"
+                    : "decoder",
+            message: cause instanceof Error ? cause.message : String(cause),
+        };
+    }
+    let encoded = JSON.stringify(reply);
+    if (Buffer.byteLength(encoded) > EVM_INTERFACE_LIMITS.outputBytes)
+        encoded = JSON.stringify({
+            ok: false,
+            reason: "output-limit",
+            message: "Complete interface evidence exceeds the 16 MiB reply budget.",
+        });
+    try {
+        await writeFile(request.reply_path, encoded, { flag: "wx", mode: 0o600 });
+    }
+    catch (cause) {
+        if (cause instanceof Error && "code" in cause && cause.code === "EFBIG") {
+            try {
+                await writeFile(request.failure_marker_path, "F", {
+                    flag: "wx",
+                    mode: 0o600,
+                });
+            }
+            catch (markerFailure) {
+                process.stderr.write(`File-size failure marker unavailable: ${markerFailure instanceof Error ? markerFailure.message : String(markerFailure)}\n`);
+            }
+            process.exitCode = EVM_FILE_SIZE_FAILURE_EXIT;
+        }
+        else
+            throw cause;
+    }
+};
+await main();

package/dist/evm/EvmoleRelease.js

@@ -0,0 +1,16 @@
+/** Unchanged locked npm/WASM profile; provenance is independent of chain deployment authenticity. */
+export const EVMOLE_PROVIDER_IDENTITY = {
+    id: "evmole-interface",
+    name: "REA EVM interface adapter",
+    version: "evmole@0.9.3",
+};
+/** Worker-reserved status for an observed EFBIG write without a complete reply. */
+export const EVM_FILE_SIZE_FAILURE_EXIT = 76;
+/** Complete offline inspection budgets; worker JavaScript heap is bounded separately. */
+export const EVM_INTERFACE_LIMITS = {
+    inputBytes: 4 * 1024 * 1024,
+    outputBytes: 16 * 1024 * 1024,
+    timeoutMs: 30_000,
+    diagnosticBytes: 1024 * 1024,
+    addressSpaceBytes: 3 * 1024 * 1024 * 1024,
+};

package/dist/firmware/FirmwareCommand.js

@@ -63,6 +63,7 @@ export const runFirmwareCommand = async (context) => {
         runId,
         cwd: context.cwd,
         hostEnvironment: context.environment,
+        signal,
         env: {
             TMPDIR: context.cwd,
             OMP_NUM_THREADS: "1",

package/dist/firmware/FirmwareProvider.js

@@ -1,7 +1,7 @@
 import { join, isAbsolute } from "node:path";
 import { z } from "zod";
 import { createAnalysisExecution, } from "../application/AnalysisProvider.js";
-import { firmwareResultSchemas, } from "../domain/firmwareAnalysis.js";
+import { firmwareResultSchemas, } from "../domain/firmware/firmwareAnalysis.js";
 import { AnalysisError } from "../domain/analysisErrorBase.js";
 import { AnalysisCancelledError, AnalysisCapabilityUnavailableError, AnalysisInputError, AnalysisOutputError, AnalysisTimeoutError, } from "../domain/analysisErrorCore.js";
 import { ProviderAdapterError } from "../domain/providerAdapterError.js";
@@ -9,7 +9,8 @@ import { ProviderCleanupError } from "../domain/providerCleanupError.js";
 import { err, ok } from "../domain/result.js";
 import { PrivateRuntimeRoot } from "../process/PrivateRuntimeRoot.js";
 import { publishFirmwareExtraction } from "./FirmwarePublication.js";
-import { FIRMWARE_LIMITS, FIRMWARE_RELEASES, BINWALK_PROVIDER_IDENTITY, UNBLOB_PROVIDER_IDENTITY, } from "./FirmwareRelease.js";
+import { FIRMWARE_LIMITS, BINWALK_PROVIDER_IDENTITY, UNBLOB_PROVIDER_IDENTITY, } from "./FirmwareRelease.js";
+import { admitFirmwareVersion } from "./FirmwareVersion.js";
 import { resolveFirmwareCommand, runFirmwareCommand, readFirmwareCommandReport, } from "./FirmwareCommand.js";
 import { inventoryFirmwareOutput, snapshotFirmware } from "./FirmwareFiles.js";
 import { normalizeBinwalkReport, normalizeUnblobReport, } from "./FirmwareReports.js";
@@ -94,15 +95,14 @@ export class FirmwareProvider {
             });
             const versionRun = await run(["--version"]);
             const version = versionRun.stdout.text.trim();
-            const expected = FIRMWARE_RELEASES[engineName].version;
-            if (versionRun.stdout.bytes > 1024 ||
-                (engineName === "binwalk"
-                    ? version !== `binwalk ${expected}`
-                    : version !== expected))
-                throw new AnalysisCapabilityUnavailableError(engineName, request.operation, `Unsupported tool version ${version}; this adapter is verified against ${expected}`);
+            if (versionRun.stdout.bytes > 1024)
+                throw new AnalysisCapabilityUnavailableError(engineName, request.operation, `Tool version banner is ${String(versionRun.stdout.bytes)} bytes; expected a short ${engineName} version line.`);
+            const admitted = admitFirmwareVersion(engineName, version);
+            if (admitted.status === "unsupported" || admitted.status === "unresolved")
+                throw new AnalysisCapabilityUnavailableError(engineName, request.operation, admitted.message);
             const engine = {
                 name: engineName,
-                version: expected,
+                version: admitted.version,
                 executable_path: command.command,
                 executable_sha256: command.sha256,
                 source_revision: null,
@@ -189,12 +189,18 @@ export class FirmwareProvider {
                 });
                 raw = { report, execution: processRun, version_execution: versionRun };
             }
-            outcome = ok(createAnalysisExecution(result, engineName === "binwalk"
+            const catalog = engineName === "binwalk"
                 ? BINWALK_PROVIDER_IDENTITY
-                : UNBLOB_PROVIDER_IDENTITY, {
+                : UNBLOB_PROVIDER_IDENTITY;
+            outcome = ok(createAnalysisExecution(result, { ...catalog, version: admitted.version }, {
                 subject: target.subject,
                 rawResult: raw,
-                limitations,
+                limitations: [
+                    ...limitations,
+                    ...(admitted.status === "compatible"
+                        ? [admitted.limitation]
+                        : []),
+                ],
                 locations: [
                     {
                         kind: "file-offset-range",

package/dist/firmware/FirmwarePublication.js

@@ -3,7 +3,7 @@ import { join } from "node:path";
 import { SafeOutputTree } from "../artifacts/SafeOutputTree.js";
 import { AnalysisOutputError } from "../domain/analysisErrorCore.js";
 import { ProviderCleanupError } from "../domain/providerCleanupError.js";
-import { firmwareResultSchemas } from "../domain/firmwareAnalysis.js";
+import { firmwareResultSchemas } from "../domain/firmware/firmwareAnalysis.js";
 import { hashFirmwareFile } from "./FirmwareFiles.js";
 /** Publish verified regular files, preserving links as metadata and rolling back failed writes. */
 export const publishFirmwareExtraction = async (context) => {

package/dist/firmware/FirmwareRelease.js

@@ -11,7 +11,7 @@ export const FIRMWARE_RELEASES = {
         repository: "https://github.com/onekey-sec/unblob",
     },
 };
-/** Catalog identities; Evidence uses the version observed from the executed tool. */
+/** Catalog identity for the verified Binwalk release. Evidence replaces version with the observed banner. */
 export const BINWALK_PROVIDER_IDENTITY = {
     id: "binwalk",
     name: "Binwalk",