rea-agents 6.4.0 → 6.7.0

package/dist/evm/EvmoleFailures.js

@@ -7,6 +7,8 @@ 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) => {
+    const cleanup = cause instanceof ArtifactReaderFailure ? cause.cleanup : undefined;
+    const cleanupOptions = cleanup === undefined ? {} : { cleanup };
     if (cause instanceof AnalysisError)
         return cause;
     if (cause instanceof OwnedCommandFailure) {
@@ -27,9 +29,13 @@ export const evmInterfaceFailure = (cause, phase, path, workerLimits, limiter =
                 },
             }, { operation: "inspect_evm_interface", cause });
         if (cause.reason === "cancelled")
-            return new AnalysisCancelledError("inspect_evm_interface", outputOptions);
+            return new AnalysisCancelledError("inspect_evm_interface", {
+                cause: cause.cancellation?.reason,
+                ...outputOptions,
+                ...cleanupOptions,
+            });
         if (cause.reason === "timeout")
-            return new AnalysisTimeoutError("inspect_evm_interface", EVM_INTERFACE_LIMITS.timeoutMs, outputOptions);
+            return new AnalysisTimeoutError("inspect_evm_interface", EVM_INTERFACE_LIMITS.timeoutMs, { ...outputOptions, ...cleanupOptions });
         if (cause.reason === "output-limit")
             return new AnalysisOutputError("inspect_evm_interface", cause.message, outputOptions);
         if (cause.reason === "process" &&
@@ -62,12 +68,15 @@ export const evmInterfaceFailure = (cause, phase, path, workerLimits, limiter =
     }
     if (cause instanceof ArtifactReaderFailure) {
         if (cause.reason === "cancelled")
-            return new AnalysisCancelledError("inspect_evm_interface");
+            return new AnalysisCancelledError("inspect_evm_interface", {
+                cause,
+                ...cleanupOptions,
+            });
         if (cause.reason === "integrity")
-            return new AnalysisArtifactChangedError("inspect_evm_interface", path, cause.message, { cause });
+            return new AnalysisArtifactChangedError("inspect_evm_interface", path, cause.message, { cause, ...cleanupOptions });
         if (phase === "artifact-read" &&
             ["limit", "path", "format"].includes(cause.reason))
-            return new AnalysisInputError("inspect_evm_interface", { cause }, [
+            return new AnalysisInputError("inspect_evm_interface", { cause, ...cleanupOptions }, [
                 {
                     path: ["path"],
                     reason: cause.reason === "limit" ? "out_of_range" : "invalid_format",
@@ -77,9 +86,9 @@ export const evmInterfaceFailure = (cause, phase, path, workerLimits, limiter =
     }
     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 });
+            return new AnalysisAccessDeniedError("inspect_evm_interface", path, cause.code, { cause, ...cleanupOptions });
         if (cause.code === "ENOENT" || cause.code === "ENOTDIR")
-            return new AnalysisInputError("inspect_evm_interface", { cause }, [
+            return new AnalysisInputError("inspect_evm_interface", { cause, ...cleanupOptions }, [
                 {
                     path: ["path"],
                     reason: "invalid_value",
@@ -89,6 +98,10 @@ export const evmInterfaceFailure = (cause, phase, path, workerLimits, limiter =
     }
     return new ProviderAdapterError(EVMOLE_PROVIDER_IDENTITY.id, "inspect_evm_interface", {
         cause,
+        ...cleanupOptions,
+        ...(cause instanceof OwnedCommandFailure && cause.snapshot !== null
+            ? { capturedOutput: capturedEvmOutput(cause.snapshot) }
+            : {}),
         diagnostics: {
             phase,
             path,
@@ -104,13 +117,6 @@ export const evmInterfaceFailure = (cause, phase, path, workerLimits, limiter =
                     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) },
-                        }),
                 }
                 : {}),
         },

package/dist/evm/EvmoleInterfaceAdapter.js

@@ -7,7 +7,11 @@ const reportedMetadata = 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("integer"),
+                // Reported integers can exceed the safe range; fractions still violate the tag.
+                value: z.number().refine(Number.isInteger, "Expected an integer"),
+            }),
             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() }),

package/dist/evm/EvmoleInterfaceProvider.js

@@ -6,10 +6,14 @@ 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 { ArtifactResourceScope } from "../artifacts/ArtifactResourceScope.js";
+import { ArtifactReaderFailure } from "../artifacts/ArtifactReader.js";
+import { OwnedCommandFailure, ownedCommandResources, } from "../process/OwnedCommand.js";
 import { AnalysisCancelledError, AnalysisCapabilityUnavailableError, AnalysisUnsupportedTargetError, AnalysisInputError, AnalysisOutputError, } from "../domain/analysisErrorCore.js";
 import { projectAnalysisError } from "../domain/analysisErrorProjection.js";
+import { evmInterfaceEvidence } from "../application/evm/EvmInterfaceEvidence.js";
 import { evmInterfaceSchema } from "../domain/evm/evmInterface.js";
+import { solidityMetadataSchema } from "../domain/evm/solidityMetadata.js";
 import { ProviderAdapterError } from "../domain/providerAdapterError.js";
 import { ProviderCleanupError } from "../domain/providerCleanupError.js";
 import { err, ok } from "../domain/result.js";
@@ -30,6 +34,7 @@ const replySchema = z.discriminatedUnion("ok", [
             sha256: z.string().regex(/^[a-f0-9]{64}$/),
             bytes: z.number().int().nonnegative(),
             hex: z.string().regex(/^(?:[a-f0-9]{2})*$/),
+            metadata: solidityMetadataSchema.optional(),
         }),
         raw: evmoleInterfaceReplySchema,
     }),
@@ -39,11 +44,41 @@ const replySchema = z.discriminatedUnion("ok", [
         message: z.string(),
     }),
 ]);
+const compactErrorProjection = (error) => {
+    const projection = projectAnalysisError(error);
+    if (error.capturedOutput === undefined)
+        return projection;
+    // The cleanup result owns this exact captured stream. Other diagnostics and
+    // partial Evidence retain their original fields, including stdout/stderr.
+    const details = { ...projection.details };
+    delete details.captured_output;
+    return { ...projection, details };
+};
+const evmCleanupFailure = (input, result, resources, reason, output, cause) => {
+    const partialObservation = result.ok
+        ? evmInterfaceEvidence(input, result.value)
+        : result.error.partialObservation;
+    const capturedOutput = result.ok
+        ? output
+        : (result.error.capturedOutput ?? output);
+    return new ProviderCleanupError(EVMOLE_PROVIDER_IDENTITY.id, resources, {
+        reason,
+        previous_error: result.ok ? null : compactErrorProjection(result.error),
+        ...(capturedOutput === undefined
+            ? {}
+            : { captured_output: { ...capturedOutput } }),
+    }, {
+        operation: OPERATION,
+        ...(cause === undefined ? {} : { cause }),
+        ...(partialObservation === undefined ? {} : { partialObservation }),
+    });
+};
 /** Run unchanged EVMole/WASM in an owned worker; no target, chain or network execution. */
 export class EvmoleInterfaceProvider {
     environment;
     launcher;
     createRuntime;
+    #resources = new ArtifactResourceScope();
     #tail = Promise.resolve();
     #closing = false;
     #closePromise;
@@ -57,7 +92,16 @@ export class EvmoleInterfaceProvider {
     inspect(input, options) {
         if (this.#closing)
             return Promise.resolve(err(this.#closedError()));
-        const operation = this.#tail.then(() => this.#closing ? err(this.#closedError()) : this.#inspect(input, options));
+        const operation = this.#tail.then(async () => {
+            if (this.#closing)
+                return err(this.#closedError());
+            try {
+                return await this.#resources.run(() => this.#inspect(input, options));
+            }
+            catch (cause) {
+                return err(evmInterfaceFailure(cause, "artifact-read", input.path));
+            }
+        });
         this.#tail = operation.then(() => undefined, () => undefined);
         return operation;
     }
@@ -67,6 +111,7 @@ export class EvmoleInterfaceProvider {
             return err(pending);
         let root;
         let processOwner;
+        let processCleanup;
         let retainedOutput;
         let phase = "configuration";
         let workerLimits;
@@ -74,7 +119,9 @@ export class EvmoleInterfaceProvider {
         let result;
         try {
             if (options?.signal?.aborted)
-                throw new AnalysisCancelledError(OPERATION);
+                throw new AnalysisCancelledError(OPERATION, {
+                    cause: options.signal.reason,
+                });
             if (process.platform !== "linux" || process.arch !== "x64")
                 throw new AnalysisCapabilityUnavailableError(EVMOLE_PROVIDER_IDENTITY.id, OPERATION, HOST_REQUIREMENT, { userMessage: HOST_REQUIREMENT });
             try {
@@ -101,7 +148,7 @@ export class EvmoleInterfaceProvider {
                 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);
+            const carrier = await readStableArtifact(input.path, EVM_INTERFACE_LIMITS.inputBytes, options?.signal, undefined, this.#resources);
             phase = "worker";
             root = await this.createRuntime();
             const snapshotPath = join(root.path, "carrier.snapshot");
@@ -144,18 +191,36 @@ export class EvmoleInterfaceProvider {
             }, {
                 ...(options?.signal === undefined ? {} : { signal: options.signal }),
                 ...(this.launcher === undefined ? {} : { launcher: this.launcher }),
+                retainCleanup: (owner, cleanup) => {
+                    processOwner = owner;
+                    processCleanup = {
+                        reason: cleanup.reason,
+                        resources: owner.launch.ownership === undefined
+                            ? ["owned-worker"]
+                            : ownedCommandResources(owner.launch.ownership, root?.path),
+                    };
+                },
             });
             const capturedOutput = capturedEvmOutput(execution);
             retainedOutput = capturedOutput;
             let reply;
             try {
-                const file = await readStableArtifact(replyPath, EVM_INTERFACE_LIMITS.outputBytes, options?.signal);
+                const file = await readStableArtifact(replyPath, EVM_INTERFACE_LIMITS.outputBytes, options?.signal, undefined, this.#resources);
                 reply = replySchema.parse(JSON.parse(file.bytes.toString("utf8")));
             }
             catch (cause) {
+                const cleanup = cause instanceof ArtifactReaderFailure ? cause.cleanup : undefined;
                 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 });
+                    throw new AnalysisCancelledError(OPERATION, {
+                        cause: options.signal.reason,
+                        capturedOutput,
+                        ...(cleanup === undefined ? {} : { cleanup }),
+                    });
+                throw new AnalysisOutputError(OPERATION, `Owned interface worker reply failed for ${input.path}: ${cause instanceof Error ? cause.message : String(cause)}`, {
+                    cause,
+                    capturedOutput,
+                    ...(cleanup === undefined ? {} : { cleanup }),
+                });
             }
             if (!reply.ok) {
                 if (reply.reason === "unsupported")
@@ -198,6 +263,7 @@ export class EvmoleInterfaceProvider {
                 "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.",
+                "Terminal CBOR metadata is an independently decoded candidate, not proof of Solidity origin, source identity or deployment. Nested or unsupported values retain explicit unavailable interpretation and original byte ranges.",
                 "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({
@@ -236,20 +302,25 @@ export class EvmoleInterfaceProvider {
             }));
         }
         catch (cause) {
-            if (cause instanceof OwnedCommandFailure)
+            if (cause instanceof OwnedCommandFailure &&
+                cause.cleanupOwner !== undefined)
                 processOwner = cause.cleanupOwner;
             let fileFailure;
+            let markerCleanupFailure;
             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);
+                    const marker = await readStableArtifact(join(root.path, "resource.failure"), 1, undefined, undefined, this.#resources);
                     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) {
+                    if (markerFailure instanceof ArtifactReaderFailure &&
+                        markerFailure.cleanup !== undefined)
+                        markerCleanupFailure = ArtifactReaderFailure.withCleanup(cause, markerFailure.cleanup);
                     fileFailure = {
                         verified: false,
                         failure: markerFailure instanceof Error
@@ -258,18 +329,36 @@ export class EvmoleInterfaceProvider {
                     };
                 }
             }
-            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));
+            result = err(markerCleanupFailure !== undefined
+                ? evmInterfaceFailure(markerCleanupFailure, "artifact-read", input.path, workerLimits, limiter, fileFailure)
+                : options?.signal?.aborted &&
+                    (cause === options.signal.reason ||
+                        (cause instanceof Error && cause.name === "AbortError"))
+                    ? new AnalysisCancelledError(OPERATION, {
+                        cause,
+                        ...(retainedOutput === undefined
+                            ? {}
+                            : { capturedOutput: retainedOutput }),
+                        ...(cause instanceof ArtifactReaderFailure &&
+                            cause.cleanup !== undefined
+                            ? { cleanup: cause.cleanup }
+                            : {}),
+                    })
+                    : evmInterfaceFailure(cause, phase, input.path, workerLimits, limiter, fileFailure));
         }
         if (processOwner !== undefined) {
-            this.#pendingCleanup = { root, process: processOwner };
-            // The command failure already owns this cleanup diagnostic and its resources.
-            return result;
+            this.#pendingCleanup = {
+                root,
+                process: processOwner,
+            };
+            if (processCleanup === undefined)
+                return result;
+            return err(evmCleanupFailure(input, result, [
+                ...new Set([
+                    ...(root === undefined ? [] : [root.path]),
+                    ...processCleanup.resources,
+                ]),
+            ], processCleanup.reason, retainedOutput, processOwner));
         }
         if (root !== undefined) {
             try {
@@ -279,30 +368,43 @@ export class EvmoleInterfaceProvider {
                 const retainedRoot = root;
                 this.#pendingCleanup = { root: retainedRoot, process: undefined };
                 root = undefined;
-                return err(new ProviderCleanupError(EVMOLE_PROVIDER_IDENTITY.id, [retainedRoot.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 err(evmCleanupFailure(input, result, [retainedRoot.path], cause instanceof Error ? cause.message : String(cause), retainedOutput, cause));
             }
         }
         return result.ok && options?.signal?.aborted
-            ? err(new AnalysisCancelledError(OPERATION, retainedOutput === undefined
-                ? undefined
-                : { capturedOutput: retainedOutput }))
+            ? err(new AnalysisCancelledError(OPERATION, {
+                cause: options.signal.reason,
+                partialObservation: evmInterfaceEvidence(input, result.value),
+                ...(retainedOutput === undefined
+                    ? {}
+                    : { capturedOutput: retainedOutput }),
+            }))
             : result;
     }
     async close() {
         this.#closing = true;
         this.#closePromise ??= this.#tail
             .then(async () => {
-            const failure = await this.#retire();
-            if (failure !== undefined)
-                throw failure;
+            const outcomes = await Promise.allSettled([
+                this.#retire(),
+                this.#resources.close(),
+            ]);
+            const failures = outcomes.flatMap((outcome) => outcome.status === "rejected"
+                ? [outcome.reason]
+                : outcome.value === undefined
+                    ? []
+                    : [outcome.value]);
+            if (failures.length > 0) {
+                const resources = failures.flatMap((failure) => failure instanceof ProviderCleanupError
+                    ? failure.cleanupResources
+                    : failure instanceof ArtifactReaderFailure &&
+                        failure.cleanup !== undefined
+                        ? failure.cleanup.resources
+                        : ["artifact-resources"]);
+                throw new ProviderCleanupError(EVMOLE_PROVIDER_IDENTITY.id, [...new Set(resources)], {
+                    failures: failures.map((failure) => failure instanceof Error ? failure.message : String(failure)),
+                }, { operation: OPERATION, cause: new AggregateError(failures) });
+            }
         })
             .catch((cause) => {
             this.#closePromise = undefined;
@@ -320,7 +422,12 @@ export class EvmoleInterfaceProvider {
         if (pending.process !== undefined) {
             const stopped = await pending.process.stop();
             if (stopped.status === "incomplete")
-                return new ProviderCleanupError(EVMOLE_PROVIDER_IDENTITY.id, [pending.process.launch.ownership?.runId ?? "owned-worker"], { reason: stopped.reason }, { operation: OPERATION });
+                return new ProviderCleanupError(EVMOLE_PROVIDER_IDENTITY.id, [
+                    ...(pending.root === undefined ? [] : [pending.root.path]),
+                    ...(pending.process.launch.ownership === undefined
+                        ? ["owned-worker"]
+                        : ownedCommandResources(pending.process.launch.ownership)),
+                ], { reason: stopped.reason }, { operation: OPERATION });
             pending.process = undefined;
         }
         if (pending.root !== undefined) {

package/dist/evm/EvmoleInterfaceWorker.js

@@ -3,6 +3,7 @@ import { readFile, writeFile } from "node:fs/promises";
 import { z } from "zod";
 import { decodeEvmBytecodeCarrier, EvmCarrierFailure, } from "./EvmBytecodeCarrier.js";
 import { projectEvmoleInterface } from "./EvmoleInterfaceAdapter.js";
+import { inspectSolidityMetadata } from "./SolidityMetadata.js";
 import { EVM_INTERFACE_LIMITS, EVM_FILE_SIZE_FAILURE_EXIT, } from "./EvmoleRelease.js";
 const requestSchema = z.strictObject({
     snapshot_path: z.string(),
@@ -42,6 +43,7 @@ const main = async () => {
                 sha256: createHash("sha256").update(bytes).digest("hex"),
                 bytes: bytes.length,
                 hex: Buffer.from(bytes).toString("hex"),
+                metadata: inspectSolidityMetadata(bytes),
             },
             raw: inferred.raw,
         };

package/dist/evm/SolidityMetadata.js

@@ -0,0 +1,139 @@
+import { decode, Tokenizer, Type } from "cborg";
+const PROFILE = "terminal-cbor-scalars-v1";
+const MAX_DEPTH = 64;
+const utf8 = new TextDecoder("utf-8", { fatal: true, ignoreBOM: true });
+const decodeOptions = {
+    useMaps: true,
+    allowBigInt: true,
+    allowIndefinite: false,
+    allowUndefined: false,
+    allowInfinity: false,
+    allowNaN: false,
+    rejectDuplicateMapKeys: true,
+    retainStringBytes: true,
+};
+/** Bound recursive decoder entry before collection interpretation/allocation. */
+class BoundedMetadataTokenizer extends Tokenizer {
+    remaining = [];
+    constructor(bytes) {
+        super(bytes, decodeOptions);
+    }
+    next() {
+        while (this.remaining.at(-1) === 0)
+            this.remaining.pop();
+        const token = super.next();
+        if (Type.equals(token.type, Type.tag) ||
+            Type.equals(token.type, Type.float))
+            throw new Error("CBOR tags and floating-point values are outside this metadata profile.");
+        if (Type.equals(token.type, Type.string)) {
+            if (token.byteValue !== undefined)
+                token.value = utf8.decode(token.byteValue);
+            // cborg answers the shortest-form empty text (0x60) with a shared token that has no
+            // bytes; it can only mean "", which is already its value.
+            else if (token.value !== "" || token.encodedLength !== 1)
+                throw new Error("CBOR text bytes were unavailable for strict UTF-8 validation.");
+        }
+        const parent = this.remaining.length - 1;
+        if (parent >= 0)
+            this.remaining[parent]--;
+        if (Type.equals(token.type, Type.map) ||
+            Type.equals(token.type, Type.array)) {
+            const count = token.value;
+            const children = typeof count === "number"
+                ? count * (Type.equals(token.type, Type.map) ? 2 : 1)
+                : NaN;
+            if (!Number.isSafeInteger(children) ||
+                children < 0 ||
+                children > this.data.length)
+                throw new Error("Declared CBOR collection exceeds the encoded item-byte bound.");
+            if (this.remaining.length >= MAX_DEPTH)
+                throw new Error("CBOR nesting exceeds the 64-level metadata profile.");
+            this.remaining.push(children);
+        }
+        return token;
+    }
+}
+const scalar = (value) => {
+    if (typeof value === "string")
+        return { kind: "text", value };
+    if (typeof value === "bigint")
+        return { kind: "integer", value: value.toString() };
+    if (typeof value === "number" && Number.isSafeInteger(value))
+        return { kind: "integer", value: String(value) };
+    if (typeof value === "boolean")
+        return { kind: "boolean", value };
+    if (value === null)
+        return { kind: "null" };
+    if (value instanceof Uint8Array)
+        return { kind: "bytes", value: Buffer.from(value).toString("hex") };
+    if (value instanceof Map)
+        return { kind: "uninterpreted", container: "map" };
+    if (Array.isArray(value))
+        return { kind: "uninterpreted", container: "array" };
+    throw new Error("CBOR decoder returned a value outside the admitted profile.");
+};
+/** Parse only a plausible terminal root-map candidate; never establish absence. */
+export const inspectSolidityMetadata = (bytes) => {
+    const empty = {
+        profile: PROFILE,
+        status: "unavailable",
+        bytecode_offset: null,
+        cbor_bytes: null,
+        entries: [],
+        compiler_version: null,
+        diagnostic: "No plausible terminal CBOR map was identified; Solidity origin and metadata absence remain unknown.",
+    };
+    if (bytes.length < 3)
+        return empty;
+    const length = bytes[bytes.length - 2] * 256 + bytes[bytes.length - 1];
+    const offset = bytes.length - 2 - length;
+    if (length === 0 || offset < 0 || bytes[offset] >> 5 !== 5)
+        return empty;
+    const selected = bytes.subarray(offset, bytes.length - 2);
+    const result = {
+        ...empty,
+        status: "not-decoded",
+        bytecode_offset: offset,
+        cbor_bytes: length,
+    };
+    try {
+        const raw = decode(selected, {
+            ...decodeOptions,
+            tokenizer: new BoundedMetadataTokenizer(selected),
+        });
+        if (!(raw instanceof Map))
+            throw new Error("Terminal CBOR candidate did not decode to a root map.");
+        for (const [key, value] of raw)
+            result.entries.push({ key: scalar(key), value: scalar(value) });
+        result.status = result.entries.some(({ key, value }) => key.kind === "uninterpreted" || value.kind === "uninterpreted")
+            ? "partial"
+            : "decoded";
+        result.diagnostic =
+            result.status === "partial"
+                ? "Nested containers are uninterpreted; their exact bytes remain at the recorded range in original bytecode."
+                : null;
+        const version = raw.get("solc");
+        if (version instanceof Uint8Array && version.length === 3)
+            result.compiler_version = {
+                representation: "release-bytes",
+                value: [...version].join("."),
+            };
+        else if (typeof version === "string" && version.length > 0)
+            result.compiler_version = {
+                representation: "prerelease-text",
+                value: version,
+            };
+        return result;
+    }
+    catch (cause) {
+        return {
+            ...result,
+            status: "not-decoded",
+            entries: [],
+            compiler_version: null,
+            diagnostic: (cause instanceof Error
+                ? cause.message
+                : String(cause)).slice(0, 512),
+        };
+    }
+};