rea-agents 5.0.0 → 6.0.0

package/dist/dotnet/ManagedMetadataInventory.js

@@ -27,7 +27,31 @@ const uniqueIssues = (issues) => [
     ...new Map(issues.map((issue) => [JSON.stringify(issue), issue])).values(),
 ];
 const heapExtent = (layout) => Math.max(layout.strings.size, layout.blob.size);
-const readReferences = (bytes, layout, issues) => readRows(layout.table(35), (row) => safeRead(() => readAssemblyReference(bytes, layout, row, heapExtent(layout)), issues));
+const validateIdentityTableCounts = (layout, issues) => {
+    const moduleRows = layout.table(0)?.rowCount ?? 0;
+    if (moduleRows !== 1)
+        issues.push({
+            code: "invalid-row",
+            scope: "metadata.Module",
+            offset: layout.table(0)?.offset ?? null,
+            detail: `Module table must contain exactly one row; found ${String(moduleRows)}`,
+        });
+    const assemblyRows = layout.table(32)?.rowCount ?? 0;
+    if (assemblyRows > 1)
+        issues.push({
+            code: "invalid-row",
+            scope: "metadata.Assembly",
+            offset: layout.table(32)?.offset ?? null,
+            detail: `Assembly table can contain at most one row; found ${String(assemblyRows)}`,
+        });
+};
+const readReferences = (bytes, layout, issues) => {
+    const references = readRows(layout.table(35), (row) => safeRead(() => readAssemblyReference(bytes, layout, row, heapExtent(layout)), issues));
+    return {
+        references,
+        referenceNames: [...new Set(references.map(({ name }) => name))].sort(),
+    };
+};
 const readResources = ({ bytes, layout, resourceDirectory, issues, }) => readRows(layout.table(40), (row) => safeRead(() => readResource({
     bytes,
     layout,
@@ -35,53 +59,39 @@ const readResources = ({ bytes, layout, resourceDirectory, issues, }) => readRow
     directory: resourceDirectory,
     issues,
 }), issues));
-const readAttributes = (bytes, layout, issues) => readRows(layout.table(12), (row) => safeRead(() => readCustomAttribute(bytes, layout, row, heapExtent(layout)), issues));
-const collectReferenceNames = (bytes, layout, issues) => {
-    const names = [];
-    const referenceTable = layout.table(35);
-    for (let row = 1; row <= (referenceTable?.rowCount ?? 0); row += 1) {
-        const reference = safeRead(() => readAssemblyReference(bytes, layout, row, heapExtent(layout)), issues);
-        if (reference !== undefined)
-            names.push(reference.name);
-    }
-    return names;
-};
-const collectTargetFrameworks = (bytes, layout, issues) => {
-    const targetFrameworks = [];
-    const attributeTable = layout.table(12);
-    for (let row = 1; row <= (attributeTable?.rowCount ?? 0); row += 1) {
-        const attribute = safeRead(() => readCustomAttribute(bytes, layout, row, heapExtent(layout)), issues);
-        if (attribute?.parent_token === metadataToken(32, 1) &&
+const readAttributes = (bytes, layout, issues) => {
+    const attributes = readRows(layout.table(12), (row) => safeRead(() => readCustomAttribute(bytes, layout, row, heapExtent(layout)), issues));
+    const targetFrameworks = new Set();
+    for (const attribute of attributes) {
+        if (attribute.parent_token === metadataToken(32, 1) &&
             attribute.type_name ===
                 "System.Runtime.Versioning.TargetFrameworkAttribute" &&
-            attribute.decoded_fixed_string !== null &&
-            !targetFrameworks.includes(attribute.decoded_fixed_string))
-            targetFrameworks.push(attribute.decoded_fixed_string);
+            attribute.decoded_fixed_string !== null)
+            targetFrameworks.add(attribute.decoded_fixed_string);
     }
-    return targetFrameworks;
+    return { attributes, targetFrameworks: [...targetFrameworks].sort() };
 };
 /** Inventory identity tables without CLR reflection or execution. */
 export const readManagedMetadataInventory = (bytes, layout, resourceDirectory) => {
     const issues = [];
+    validateIdentityTableCounts(layout, issues);
     const module = safeRead(() => readModule(bytes, layout, heapExtent(layout)), issues) ??
         null;
     const assembly = safeRead(() => readAssembly(bytes, layout, heapExtent(layout)), issues) ??
         null;
-    const references = readReferences(bytes, layout, issues);
+    const { references, referenceNames } = readReferences(bytes, layout, issues);
     const resources = readResources({
         bytes,
         layout,
         resourceDirectory,
         issues,
     });
-    const attributes = readAttributes(bytes, layout, issues);
-    const referenceNames = collectReferenceNames(bytes, layout, issues);
-    const targetFrameworks = collectTargetFrameworks(bytes, layout, issues);
+    const { attributes, targetFrameworks } = readAttributes(bytes, layout, issues);
     return {
         module,
         assembly,
-        targetFrameworks: [...targetFrameworks].sort(),
-        referenceNames: [...new Set(referenceNames)].sort(),
+        targetFrameworks,
+        referenceNames,
         references,
         resources,
         attributes,

package/dist/dotnet/ManagedMetadataInventoryRows.js

@@ -1,5 +1,5 @@
 import { metadataRowOffset, } from "./ManagedMetadataLayout.js";
-import { metadataRowCursor, metadataCodedToken, metadataToken, readMetadataBlob, readMetadataGuid, readMetadataString, sha256Bytes, strongNameToken, } from "./ManagedMetadataHeaps.js";
+import { metadataRowCursor, metadataCodedToken, metadataCodedTokenInvalidReason, metadataToken, readMetadataBlob, readMetadataGuid, readMetadataString, sha256Bytes, strongNameToken, } from "./ManagedMetadataHeaps.js";
 import { managedFailure } from "./ManagedReaderFailure.js";
 const publicKeyIdentity = (bytes, kind) => ({
     kind: bytes.length === 0 ? "none" : kind,
@@ -212,23 +212,28 @@ const decodeFixedString = (blob) => {
 export const readCustomAttribute = (bytes, layout, row, heapExtent) => {
     const cursor = metadataRowCursor(bytes, layout, 12, row);
     const parentRaw = cursor.readIndex(layout.codedIndexSize("HasCustomAttribute"));
+    const typeOffset = cursor.offset;
     const typeRaw = cursor.readIndex(layout.codedIndexSize("CustomAttributeType"));
     const value = readMetadataBlob(bytes, layout, cursor.readIndex(layout.blobIndexSize), heapExtent);
     const parent = metadataCodedToken(parentRaw, 5, [
         6, 4, 1, 2, 8, 9, 10, 0, 14, 23, 20, 17, 26, 27, 32, 35, 38, 39, 40, 42,
         44, 43,
-    ]);
+    ], layout.rowCounts);
+    const parentReason = metadataCodedTokenInvalidReason(parentRaw, 5, [
+        6, 4, 1, 2, 8, 9, 10, 0, 14, 23, 20, 17, 26, 27, 32, 35, 38, 39, 40, 42,
+        44, 43,
+    ], layout.rowCounts);
     if (parent === null)
-        throw managedFailure("invalid-row", "metadata.CustomAttribute", "CustomAttribute parent coded index is invalid", cursor.start);
+        throw managedFailure("invalid-row", `metadata.CustomAttribute:${metadataToken(12, row)}`, `CustomAttribute parent coded index 0x${parentRaw.toString(16)} is invalid${parentReason === null ? " because the required parent is null" : `: ${parentReason}`}`, cursor.start);
+    const typeReason = metadataCodedTokenInvalidReason(typeRaw, 3, [undefined, undefined, 6, 10], layout.rowCounts);
+    if (typeReason !== null || typeRaw === 0)
+        throw managedFailure("invalid-row", `metadata.CustomAttribute:${metadataToken(12, row)}`, typeReason === null
+            ? "CustomAttribute constructor coded index 0x0 is null, but Type must reference a MethodDef or MemberRef row"
+            : `CustomAttribute constructor coded index 0x${typeRaw.toString(16)} is invalid: ${typeReason}`, typeOffset);
     const typeName = attributeTypeName(bytes, layout, typeRaw, heapExtent);
     return {
         parent_token: parent,
-        constructor_token: metadataCodedToken(typeRaw, 3, [
-            undefined,
-            undefined,
-            6,
-            10,
-        ]),
+        constructor_token: metadataCodedToken(typeRaw, 3, [undefined, undefined, 6, 10], layout.rowCounts),
         type_name: typeName,
         value_length: value.length,
         value_sha256: sha256Bytes(value),
@@ -244,8 +249,17 @@ export const readResource = ({ bytes, layout, row, directory, issues, }) => {
     const declaredOffset = cursor.readUInt32();
     const flags = cursor.readUInt32();
     const name = readMetadataString(bytes, layout, cursor.readIndex(layout.stringIndexSize), Math.max(layout.strings.size, layout.blob.size));
+    const implementationOffset = cursor.offset;
     const implementationRaw = cursor.readIndex(layout.codedIndexSize("Implementation"));
-    const implementationToken = metadataCodedToken(implementationRaw, 2, [38, 35, 39]);
+    const implementationToken = metadataCodedToken(implementationRaw, 2, [38, 35, 39], layout.rowCounts);
+    const implementationReason = metadataCodedTokenInvalidReason(implementationRaw, 2, [38, 35, 39], layout.rowCounts);
+    if (implementationReason !== null)
+        issues.push({
+            code: "invalid-row",
+            scope: `metadata.ManifestResource:${metadataToken(40, row)}`,
+            offset: implementationOffset,
+            detail: `ManifestResource implementation coded index 0x${implementationRaw.toString(16)} is invalid: ${implementationReason}`,
+        });
     let dataLength = null;
     let dataSha256 = null;
     if (implementationRaw === 0) {

package/dist/dotnet/ManagedMethodBodyReader.js

@@ -1,4 +1,5 @@
 import { decodeInstructions, parseExceptionRegions, } from "./ManagedMemberInstructionDecoder.js";
+import { validateExceptionRegionRanges } from "./ManagedExceptionRegionValidation.js";
 import { sha256Bytes } from "./ManagedMetadataHeaps.js";
 const bodyStatus = (decodedIssue, truncatedInstructions, exceptionRegions) => {
     if (decodedIssue !== null || exceptionRegions?.status === "malformed")
@@ -38,6 +39,7 @@ const readMethodBodyHeader = (bytes, offset) => {
         localSig: bytes.readUInt32LE(offset + 8),
     };
 };
+const readExceptionRegions = (bytes, sectionOffset, methodEnd, ilSize, instructionOffsets) => validateExceptionRegionRanges(parseExceptionRegions(bytes, sectionOffset, methodEnd), ilSize, instructionOffsets);
 /** Decode admitted managed CIL, retaining unavailable implementation metadata as partial. */
 export const methodBody = (bytes, pe, rva, implementation = {
     implFlags: 0,
@@ -50,7 +52,11 @@ export const methodBody = (bytes, pe, rva, implementation = {
         return emptyMethodBody(rva, "partial", "CIL decoding is unavailable for native, runtime, unmanaged, or P/Invoke implementations");
     try {
         const offset = pe.rvaToOffset(rva, 1, "method.body");
+        const methodExtent = pe.rvaAvailableBytes(rva, "method.body");
         const header = readMethodBodyHeader(bytes, offset);
+        if (header.size > methodExtent ||
+            header.ilSize > methodExtent - header.size)
+            throw new RangeError("Method body leaves file-backed PE section data");
         const ilOffset = offset + header.size;
         if (ilOffset > bytes.length - header.ilSize)
             throw new RangeError("Method IL bytes leave artifact");
@@ -76,7 +82,7 @@ export const methodBody = (bytes, pe, rva, implementation = {
         const methodEnd = ilOffset + header.ilSize;
         const sectionOffset = (methodEnd + 3) & ~3;
         const exceptionRegions = header.format === "fat" && (header.flags & 8) !== 0
-            ? parseExceptionRegions(bytes, sectionOffset, bytes.length)
+            ? readExceptionRegions(bytes, sectionOffset, offset + methodExtent, header.ilSize, decoded.instructionStarts)
             : null;
         const status = bodyStatus(decoded.issue, decoded.truncated, exceptionRegions);
         return {

package/dist/dotnet/ManagedNativeBoundaryHelpers.js

@@ -1,6 +1,6 @@
 import { managedNativeBoundaryInspectionSchema, } from "../domain/managed/managedArtifact.js";
 import {} from "./ManagedMetadataLayout.js";
-import { metadataRowCursor, metadataCodedToken, metadataToken, readMetadataString, } from "./ManagedMetadataHeaps.js";
+import { metadataRowCursor, metadataCodedToken, metadataCodedTokenInvalidReason, metadataToken, readMetadataString, } from "./ManagedMetadataHeaps.js";
 import { managedTableRowCounts } from "./ManagedMetadataInventory.js";
 const flagsHex = (value) => `0x${value.toString(16).padStart(4, "0")}`;
 export const parseModuleRefs = (bytes, layout, heapExtent) => {
@@ -61,14 +61,26 @@ export const parseMethods = (bytes, layout, heapExtent) => {
     }
     return methods;
 };
-export const parseImplMaps = ({ bytes, layout, heapExtent, modules, members, }) => {
+export const parseImplMaps = ({ bytes, layout, heapExtent, modules, members, issues, }) => {
     const moduleNames = new Map(modules.map((module) => [module.token, module]));
     const imports = [];
     const table = layout.table(28);
     for (let row = 1; row <= (table?.rowCount ?? 0); row += 1) {
         const cursor = metadataRowCursor(bytes, layout, 28, row);
         const mappingFlags = cursor.readUInt16();
-        const memberToken = metadataCodedToken(cursor.readIndex(layout.codedIndexSize("MemberForwarded")), 1, [4, 6]);
+        const memberForwardedOffset = cursor.offset;
+        const memberForwardedRaw = cursor.readIndex(layout.codedIndexSize("MemberForwarded"));
+        const memberForwardedReason = metadataCodedTokenInvalidReason(memberForwardedRaw, 1, [4, 6], layout.rowCounts);
+        if (memberForwardedReason !== null || memberForwardedRaw === 0)
+            issues.push({
+                code: "invalid-row",
+                scope: `metadata.ImplMap:${metadataToken(28, row)}`,
+                offset: memberForwardedOffset,
+                detail: memberForwardedReason === null
+                    ? "ImplMap MemberForwarded coded index 0x0 is null, but the column must reference a Field or MethodDef row"
+                    : `ImplMap MemberForwarded coded index 0x${memberForwardedRaw.toString(16)} is invalid: ${memberForwardedReason}`,
+            });
+        const memberToken = metadataCodedToken(memberForwardedRaw, 1, [4, 6], layout.rowCounts);
         const importName = readMetadataString(bytes, layout, cursor.readIndex(layout.stringIndexSize), heapExtent);
         const importScopeRow = cursor.readIndex(layout.tableIndexSize(26));
         const importScopeToken = importScopeRow === 0 ? null : metadataToken(26, importScopeRow);

package/dist/dotnet/ManagedNativeBoundaryInspector.js

@@ -89,6 +89,7 @@ export const inspectManagedNativeBoundariesBytes = (bytes, target) => {
         });
     }
     const heapExtent = Math.max(layout.strings.size, layout.blob.size);
+    const issues = [...inventory.issues];
     const moduleRefs = parseModuleRefs(bytes, layout, heapExtent);
     const members = new Map([
         ...parseFields(bytes, layout, heapExtent),
@@ -100,6 +101,7 @@ export const inspectManagedNativeBoundariesBytes = (bytes, target) => {
         heapExtent,
         modules: moduleRefs,
         members,
+        issues,
     });
     const pinvokeTokens = new Set(imports
         .map(({ member_token }) => member_token)
@@ -115,6 +117,6 @@ export const inspectManagedNativeBoundariesBytes = (bytes, target) => {
         imports,
         implementations,
         native: cliNative(pe),
-        issues: [],
+        issues,
     });
 };

package/dist/dotnet/ManagedPeReader.js

@@ -186,5 +186,16 @@ export const readManagedPeLayout = (bytes) => {
         cliDirectoryPresent,
         cliIssue,
         rvaToOffset: (rva, size, scope) => mapRva({ bytes, sections, rva, size, scope }),
+        rvaAvailableBytes: (rva, scope) => {
+            mapRva({ bytes, sections, rva, size: 1, scope });
+            for (const section of sections) {
+                if (rva < section.virtualAddress)
+                    continue;
+                const within = rva - section.virtualAddress;
+                if (within < section.rawSize)
+                    return Math.min(section.rawSize - within, bytes.length - section.rawOffset - within);
+            }
+            throw managedFailure("invalid-directory", scope, `${scope} RVA is not covered by file-backed PE section data`);
+        },
     };
 };

package/dist/evm/EvmBytecodeCarrier.js

@@ -0,0 +1,21 @@
+/** Expected carrier encoding failure, independent of the analysis engine. */
+export class EvmCarrierFailure extends Error {
+}
+/** Decode only the explicitly selected representation; source carrier bytes are retained separately. */
+export const decodeEvmBytecodeCarrier = (bytes, encoding) => {
+    if (encoding === "raw")
+        return Uint8Array.from(bytes);
+    let text;
+    try {
+        text = new TextDecoder("utf-8", { fatal: true, ignoreBOM: true }).decode(bytes);
+    }
+    catch (cause) {
+        throw new EvmCarrierFailure("Hex carrier must be valid UTF-8.", { cause });
+    }
+    const code = text
+        .replace(/^[\x09-\x0d\x20]+|[\x09-\x0d\x20]+$/g, "")
+        .replace(/^0x/i, "");
+    if (!/^(?:[a-fA-F0-9]{2})*$/.test(code))
+        throw new EvmCarrierFailure("Hex carrier requires complete hexadecimal byte pairs, an optional 0x prefix and outer ASCII whitespace; interior separators are invalid.");
+    return Uint8Array.from(Buffer.from(code, "hex"));
+};

package/dist/evm/EvmWorkerLimits.js

@@ -0,0 +1,40 @@
+import { err, ok } from "../domain/result.js";
+import { EVM_INTERFACE_LIMITS } from "./EvmoleRelease.js";
+/** Read only the three selected Linux limits, retaining tighter soft/hard boundaries. */
+export const selectEvmWorkerLimits = (raw) => {
+    if (typeof raw !== "string" || Buffer.byteLength(raw) > 64 * 1024)
+        return err("Linux resource limits must be text within the 64 KiB parsing budget.");
+    const selected = [];
+    for (const [name, units, maximum] of [
+        ["Max address space", "bytes", EVM_INTERFACE_LIMITS.addressSpaceBytes],
+        ["Max cpu time", "seconds", 30],
+        ["Max file size", "bytes", EVM_INTERFACE_LIMITS.outputBytes],
+    ]) {
+        const entries = raw
+            .split("\n")
+            .filter((line) => line.startsWith(name + " "));
+        if (entries.length !== 1)
+            return err(`Linux resource limits must report exactly one ${name} row.`);
+        const match = new RegExp(`^${name}\\s+(unlimited|[0-9]+)\\s+(unlimited|[0-9]+)\\s+${units}\\s*$`).exec(entries[0] ?? "");
+        if (match === null)
+            return err(`Malformed inherited Linux resource limit: ${name}.`);
+        let effective = BigInt(maximum);
+        const soft = match[1];
+        const hard = match[2];
+        if (soft === undefined || hard === undefined)
+            return err(`Missing ${name} values.`);
+        if (hard !== "unlimited" &&
+            (soft === "unlimited" || BigInt(soft) > BigInt(hard)))
+            return err(`Inherited ${name} soft limit exceeds its hard limit.`);
+        for (const value of [soft, hard])
+            if (value !== "unlimited" && BigInt(value) < effective)
+                effective = BigInt(value);
+        selected.push(Number(effective));
+    }
+    const [addressSpaceBytes, cpuSeconds, fileSizeBytes] = selected;
+    if (addressSpaceBytes === undefined ||
+        cpuSeconds === undefined ||
+        fileSizeBytes === undefined)
+        return err("Required Linux resource limits were not selected.");
+    return ok({ addressSpaceBytes, cpuSeconds, fileSizeBytes });
+};

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,
+        })),
+    };
+};