rea-agents 6.3.0 → 6.5.0

package/dist/domain/evidence.js

@@ -1,61 +1,82 @@
+import { basename } from "node:path";
 import { z } from "zod";
 import { digestCanonicalValue } from "./canonicalDigest.js";
 import { canonicalJsonDigestSteps } from "./canonicalJsonDigestSteps.js";
+import { nulFreeStringSchema } from "./localPath.js";
 import { analysisProfileSchema, } from "./analysisProfile.js";
+import { BINARY_ARCHITECTURES, } from "./binaryTargetTypes.js";
 import { jsonObjectSchema, jsonValueSchema, jsonValueValidationIssue, jsonValueValidationSteps, } from "./jsonValue.js";
 import { freezeJsonSnapshot, isImmutableJsonSnapshot, } from "./immutableJson.js";
 import { digestSchema } from "./../domain/digests.js";
 import { prefixedDigestSchema } from "./../domain/digests.js";
+import { relationshipCoverageSchema, } from "./relationshipCoverage.js";
 /** Provider identity schema shared by evidence-bearing persistence formats. */
-export const providerSchema = z.object({
+export const providerSchema = z.strictObject({
     id: z.string().min(1),
     name: z.string().min(1),
     version: z.string().nullable(),
 });
-const subjectSchema = z.object({
+const subjectFormatSchema = z.enum([
+    "hopper",
+    "analysis-database",
+    "mach-o",
+    "elf",
+    "pe",
+    "dos-mz",
+    "dos-com",
+    "raw-binary",
+    "zip",
+    "ipa",
+    "apk",
+    "msix",
+    "appx",
+    "hap",
+    "hsp",
+    "app-pack",
+    "asar",
+    "dmg",
+    "pkg",
+    "plist",
+    "javascript",
+    "source-map",
+    "directory",
+    "file",
+    "unknown",
+    "mach-o-universal",
+    "javascript-bundle",
+    "entitlements",
+]);
+const subjectBaseSchema = z.strictObject({
     name: z.string().min(1),
-    digest: z.object({ sha256: digestSchema }),
-    format: z.enum([
-        "hopper",
-        "analysis-database",
-        "mach-o",
-        "elf",
-        "pe",
-        "dos-mz",
-        "dos-com",
-        "zip",
-        "ipa",
-        "apk",
-        "msix",
-        "appx",
-        "asar",
-        "dmg",
-        "pkg",
-        "plist",
-        "javascript",
-        "source-map",
-        "directory",
-        "file",
-        "unknown",
-        "mach-o-universal",
-        "javascript-bundle",
-        "entitlements",
-    ]),
-    architecture: z.enum(["x86", "x86_64", "arm", "arm64"]).nullable(),
-    local_path: z.string(),
+    digest: z.strictObject({ sha256: digestSchema }),
+    local_path: nulFreeStringSchema,
 });
+// The format owns the architecture claim, including nested Evidence subjects.
+const subjectSchema = z.discriminatedUnion("format", [
+    subjectBaseSchema.extend({
+        format: subjectFormatSchema.exclude(["raw-binary"]),
+        architecture: z.enum(BINARY_ARCHITECTURES).exclude(["6502"]).nullable(),
+    }),
+    subjectBaseSchema.extend({
+        format: z.literal("raw-binary"),
+        architecture: z.enum(BINARY_ARCHITECTURES).nullable(),
+    }),
+]);
 /** Source location attached to an evidence observation. */
 /** Source-location schema shared by evidence-bearing persistence formats. */
 export const evidenceLocationSchema = z.discriminatedUnion("kind", [
-    z.object({ kind: z.literal("address"), address: z.string().min(1) }),
-    z.object({
+    z.strictObject({ kind: z.literal("address"), address: z.string().min(1) }),
+    z.strictObject({
         kind: z.literal("address-range"),
         start: z.string().min(1),
         end: z.string().min(1),
     }),
-    z.object({ kind: z.literal("artifact-path"), path: z.string().min(1) }),
-    z.object({ kind: z.literal("file-offset"), offset: z.number().int().min(0) }),
-    z.object({
+    z.strictObject({ kind: z.literal("artifact-path"), path: z.string().min(1) }),
+    z.strictObject({
+        kind: z.literal("file-offset"),
+        offset: z.number().int().min(0),
+    }),
+    z.strictObject({
         kind: z.literal("file-offset-range"),
         start: z.number().int().min(0),
         end: z.number().int().min(0),
@@ -68,7 +89,7 @@ const evidenceAuthoritySchema = z.enum([
     "external-service",
     "analyst-inference",
 ]);
-const executionEnvironmentSchema = z.object({
+const executionEnvironmentSchema = z.strictObject({
     id: z.string().min(1),
     platform: z.string().min(1),
     architecture: z.string().min(1),
@@ -89,6 +110,7 @@ const evidenceBaseSchema = z
     authority: evidenceAuthoritySchema,
     environment: executionEnvironmentSchema.nullable(),
     limitations: z.array(z.string()),
+    relationship_coverage: relationshipCoverageSchema.nullable().default(null),
     locations: z.array(evidenceLocationSchema),
     evidence_links: z.array(prefixedDigestSchema("ev")),
 })
@@ -125,6 +147,12 @@ const immutableResultSchema = z
     if (issue !== undefined)
         context.addIssue({ code: "custom", message: issue });
 });
+/** Rebind a matching immutable artifact subject to the caller's selected path. */
+export const rebindEvidenceSubjectTargetPath = (subject, target) => subject.sha256 === target.sha256 &&
+    subject.format === target.format &&
+    (subject.architecture ?? null) === (target.architecture ?? null)
+    ? { ...subject, path: target.path }
+    : subject;
 const semanticProjection = (evidence) => ({
     subject: evidence.subject === null
         ? null
@@ -144,6 +172,9 @@ const semanticProjection = (evidence) => ({
     authority: evidence.authority,
     environment: evidence.environment,
     limitations: evidence.limitations,
+    ...(evidence.relationship_coverage === null
+        ? {}
+        : { relationship_coverage: evidence.relationship_coverage }),
     locations: evidence.locations,
     evidence_links: evidence.evidence_links,
 });
@@ -160,6 +191,38 @@ export const parseEvidence = (input) => {
 };
 /** Authenticate and seal a ledger-owned snapshot; external mutable values are copied first. */
 export const immutableEvidence = (input) => rememberImmutableEvidence(parseEvidence(input));
+/** Rebind display path metadata when an authenticated record names this target. */
+export const rebindEvidenceToTargetPath = (evidence, target) => {
+    const subject = evidence.subject;
+    if (subject === null)
+        return evidence;
+    const rebound = rebindEvidenceSubjectTargetPath({
+        path: subject.local_path,
+        sha256: subject.digest.sha256,
+        format: subject.format,
+        ...(subject.architecture === null
+            ? {}
+            : { architecture: subject.architecture }),
+    }, target);
+    if (rebound.path === subject.local_path)
+        return evidence;
+    const reboundSubject = subjectSchema.parse({
+        ...subject,
+        name: basename(target.path) || "artifact",
+        local_path: target.path,
+    });
+    const reboundEvidence = { ...evidence, subject: reboundSubject };
+    if (!isImmutableEvidence(evidence))
+        return immutableEvidence(reboundEvidence);
+    // The original authenticated Evidence owns immutable payloads. Only the
+    // small display subject and envelope are new, so preserve those payloads
+    // without reparsing a potentially large analysis result.
+    Object.freeze(reboundSubject.digest);
+    Object.freeze(reboundSubject);
+    Object.freeze(reboundEvidence);
+    immutableEvidenceSnapshots.set(reboundEvidence, reboundEvidence);
+    return reboundEvidence;
+};
 /** Recognize authenticated Evidence whose complete reachable JSON data is immutable. */
 export const isImmutableEvidence = (evidence) => immutableEvidenceSnapshots.has(evidence);
 const rememberImmutableEvidence = (evidence) => {
@@ -194,7 +257,7 @@ const normalizeEvidenceObservation = (target, provider, observation) => {
     const subject = target === undefined
         ? null
         : {
-            name: target.path.split("/").at(-1) || "artifact",
+            name: basename(target.path) || "artifact",
             digest: { sha256: target.sha256 },
             format: target.format,
             architecture: target.architecture ?? null,
@@ -231,6 +294,9 @@ const normalizeEvidenceObservation = (target, provider, observation) => {
                 : []),
             ...(observation.limitations ?? []),
         ],
+        ...(observation.relationshipCoverage === undefined
+            ? { relationship_coverage: null }
+            : { relationship_coverage: observation.relationshipCoverage }),
         locations: [...(observation.locations ?? [])],
         evidence_links: [...(observation.evidenceLinks ?? [])],
     };

package/dist/domain/evidenceBundle.js

@@ -4,23 +4,28 @@ import { compareUnicodeCodePoints } from "./unicodeCodePointOrder.js";
 import { evidenceSchema, immutableEvidence, parseEvidence, providerSchema, } from "./evidence.js";
 import { residualUnknownSchema, } from "./residualUnknown.js";
 import { freezeJsonSnapshot } from "./immutableJson.js";
-const artifactManifestSchema = evidenceSchema.shape.subject.unwrap().pick({
+const [detectedSubjectSchema, rawSubjectSchema] = evidenceSchema.shape.subject.unwrap().options;
+const manifestFields = {
     digest: true,
     format: true,
     architecture: true,
-});
+};
+const artifactManifestSchema = z.discriminatedUnion("format", [
+    detectedSubjectSchema.pick(manifestFields),
+    rawSubjectSchema.pick(manifestFields),
+]);
 const providerManifestSchema = providerSchema;
 const environmentManifestSchema = evidenceSchema.shape.environment.unwrap();
-const scenarioManifestSchema = z.object({
+const scenarioManifestSchema = z.strictObject({
     evidence_id: evidenceSchema.shape.evidence_id,
     operation: z.string().min(1),
     authority: z.literal("controlled-replay"),
 });
-const captureManifestSchema = z.object({
+const captureManifestSchema = z.strictObject({
     evidence_id: evidenceSchema.shape.evidence_id,
     predicate_type: z.string().min(1),
 });
-export const evidenceBundleSchema = z.object({
+export const evidenceBundleSchema = z.strictObject({
     artifacts: z.array(artifactManifestSchema),
     providers: z.array(providerManifestSchema),
     environments: z.array(environmentManifestSchema),
@@ -30,6 +35,13 @@ export const evidenceBundleSchema = z.object({
     records: z.array(evidenceSchema),
 });
 const immutableBundles = new WeakMap();
+/** Caller input has valid shape but is not in authenticated canonical form. */
+export class NonCanonicalEvidenceBundleError extends TypeError {
+    constructor() {
+        super("Evidence bundle manifests are not canonical");
+        this.name = "NonCanonicalEvidenceBundleError";
+    }
+}
 /** Build and authenticate a sealed bundle while reusing immutable Evidence records. */
 export const createImmutableEvidenceBundle = (records, unknowns = []) => {
     const checkedRecords = records.map(immutableEvidence);
@@ -49,11 +61,11 @@ export const createEvidenceBundle = (records, unknowns = []) => {
         artifacts: uniqueSorted(sortedRecords.flatMap(({ subject }) => subject === null
             ? []
             : [
-                {
+                artifactManifestSchema.parse({
                     digest: subject.digest,
                     format: subject.format,
                     architecture: subject.architecture,
-                },
+                }),
             ])),
         providers: uniqueSorted(sortedRecords.map(({ provider }) => provider)),
         environments: uniqueSorted(sortedRecords.flatMap(({ environment }) => environment === null ? [] : [environment])),
@@ -138,17 +150,22 @@ const referencedEvidenceIds = (unknown) => [
     ...unknown.mutation_evidence_ids,
     ...(unknown.resolution?.evidence_ids ?? []),
 ];
-/**
- * Name the bundle constraint that failed and how to recover. A single
- * Evidence record, such as one command result, is not a bundle.
- */
 export const describeEvidenceBundleFailure = (input, cause) => {
-    const record = evidenceSchema.safeParse(input);
-    if (record.success)
-        return `Expected an Evidence bundle with records and manifest arrays, but this JSON is one Evidence record (${record.data.evidence_id}). Export a session bundle with the MCP export_evidence_bundle tool and supply that file.`;
-    return cause instanceof z.ZodError
-        ? `Evidence bundle does not match the bundle schema ${describeValidationFailure(cause)}. Supply an unmodified bundle written by export_evidence_bundle or rea evidence-export.`
-        : `Evidence bundle validation failed: ${describeValidationFailure(cause)}. Recreate or re-export the bundle, then try again.`;
+    try {
+        const record = parseEvidence(input);
+        return {
+            kind: "single-record",
+            message: `Expected an Evidence bundle with records and manifest arrays, but this JSON is one Evidence record (${record.evidence_id}). Export a session bundle with the MCP export_evidence_bundle tool and supply that file.`,
+        };
+    }
+    catch {
+        return {
+            kind: "invalid-bundle",
+            message: cause instanceof z.ZodError
+                ? `Evidence bundle does not match the bundle schema ${describeValidationFailure(cause)}. Supply an unmodified bundle written by export_evidence_bundle or rea evidence-export.`
+                : `Evidence bundle validation failed: ${describeValidationFailure(cause)}. Recreate or re-export the bundle, then try again.`,
+        };
+    }
 };
 /** Locate the first schema issue, or keep a thrown constraint message. */
 export const describeValidationFailure = (cause) => {
@@ -162,19 +179,36 @@ export const describeValidationFailure = (cause) => {
 };
 /** Parse records, verify semantic IDs, and reject inconsistent manifests. */
 export const parseEvidenceBundle = (input) => {
+    return parseBundle(input, false);
+};
+/** Authenticate and seal file-owned payloads once for downstream zero-copy reuse. */
+export const parseImmutableEvidenceBundle = (input) => {
+    return parseBundle(input, true);
+};
+const parseBundle = (input, seal) => {
     if (typeof input === "object" && input !== null) {
         const owned = immutableBundles.get(input);
         if (owned !== undefined)
             return owned;
     }
-    const parsed = evidenceBundleSchema.parse(input);
+    return authenticateBundle(evidenceBundleSchema.parse(input), seal);
+};
+/** Authenticate evidence and bundle invariants after the bundle shape is parsed. */
+export const authenticateParsedEvidenceBundle = (parsed) => authenticateBundle(parsed, false);
+const authenticateBundle = (parsed, seal) => {
     const recordIds = parsed.records.map(({ evidence_id: id }) => id);
     if (new Set(recordIds).size !== recordIds.length)
         throw new TypeError("Evidence bundle contains duplicate record IDs");
     validateUnknownGraph(parsed.unknowns, parsed.records);
     const canonical = createEvidenceBundle(parsed.records.map((record, index) => {
         try {
-            return parseEvidence(record);
+            if (!seal)
+                return parseEvidence(record);
+            // Schema parsing gave this boundary exclusive ownership. Register only
+            // validated payloads before authenticating the complete record envelope.
+            record.normalized_result = freezeJsonSnapshot(record.normalized_result);
+            record.raw_result = freezeJsonSnapshot(record.raw_result);
+            return immutableEvidence(record);
         }
         catch (cause) {
             if (cause instanceof z.ZodError)
@@ -186,7 +220,11 @@ export const parseEvidenceBundle = (input) => {
         }
     }), parsed.unknowns);
     if (JSON.stringify(parsed) !== JSON.stringify(canonical))
-        throw new TypeError("Evidence bundle manifests are not canonical");
+        throw new NonCanonicalEvidenceBundleError();
+    if (seal) {
+        freezeJsonSnapshot(canonical);
+        immutableBundles.set(canonical, canonical);
+    }
     return canonical;
 };
 const validateUnknownGraph = (unknowns, records) => {

package/dist/domain/evidenceErrors.js

@@ -30,12 +30,17 @@ export class EvidenceFileError extends AnalysisError {
     operation;
     reason;
     _tag = "EvidenceFileError";
+    userMessage;
     /** Caller-selected path that failed, resolved against the working directory. */
     path;
+    /** Present only when a write committed before cleanup failed. */
+    published;
     constructor(operation, reason, options) {
         super(`Evidence bundle ${operation} failed: ${reason}`, options);
         this.operation = operation;
         this.reason = reason;
         this.path = options?.path;
+        this.published = options?.published;
+        this.userMessage = options?.userMessage;
     }
 }

package/dist/domain/evidenceRecordSummary.js

@@ -0,0 +1,144 @@
+import { z } from "zod";
+import { digestSchema, prefixedDigestSchema } from "./digests.js";
+import { evidenceSchema } from "./evidence.js";
+/** Exact retained-record selectors; selection never resolves a provider address. */
+export const evidenceRecordFiltersSchema = z.strictObject({
+    evidence_id: prefixedDigestSchema("ev").optional(),
+    operation: z.string().min(1).optional(),
+    target_sha256: digestSchema.optional(),
+    analysis_profile_digest: digestSchema.optional(),
+    procedure_address: z.string().min(1).optional(),
+});
+const countSchema = z.number().int().nonnegative();
+const nativeMetadataSchema = z.object({
+    procedure: z.object({ address: z.string(), name: z.string().nullish() }),
+    native_value_flow: z.unknown().optional(),
+});
+const valueFlowMetadataSchema = z.union([
+    z.object({
+        available: z.literal(true),
+        truncated: z.boolean(),
+        omitted_operations_lower_bound: countSchema.optional(),
+        known_omitted_inputs: countSchema.optional(),
+        known_omitted_edges: countSchema.optional(),
+    }),
+    z.object({ available: z.literal(false), reason: z.string() }),
+]);
+const nativeSummarySchema = z.discriminatedUnion("available", [
+    z.strictObject({
+        available: z.literal(true),
+        procedure_address: z.string(),
+        procedure_name: z.string().nullable(),
+        value_flow: z.discriminatedUnion("status", [
+            z.strictObject({
+                status: z.literal("observed"),
+                truncated: z.boolean(),
+                omitted_operations_lower_bound: countSchema.nullable(),
+                known_omitted_inputs: countSchema.nullable(),
+                known_omitted_edges: countSchema.nullable(),
+            }),
+            z.strictObject({ status: z.literal("unavailable"), reason: z.string() }),
+            z.strictObject({ status: z.literal("not-recorded") }),
+            z.strictObject({ status: z.literal("unknown"), reason: z.string() }),
+        ]),
+    }),
+    z.strictObject({
+        available: z.literal(false),
+        reason: z.enum(["different-operation", "not-recorded-or-incompatible"]),
+    }),
+]);
+/** Metadata for complete retained records, independent of analysis completeness. */
+export const evidenceBundleSummarySchema = z.strictObject({
+    kind: z.literal("evidence-bundle-summary"),
+    filters: z.record(z.string(), z.string()),
+    total_retained_records: countSchema,
+    matching_records: countSchema,
+    unknown_revisions: countSchema,
+    records: z.array(z.strictObject({
+        evidence_id: evidenceSchema.shape.evidence_id,
+        subject: evidenceSchema.shape.subject,
+        provider: evidenceSchema.shape.provider,
+        operation: evidenceSchema.shape.operation,
+        confidence: evidenceSchema.shape.confidence,
+        authority: evidenceSchema.shape.authority,
+        analysis_profile_digest: digestSchema.nullable(),
+        retention: z.literal("complete-record"),
+        limitation_count: countSchema,
+        native_dossier: nativeSummarySchema,
+    })),
+});
+const nativeSummary = (evidence) => {
+    if (evidence.operation !== "analyze_function")
+        return { available: false, reason: "different-operation" };
+    // Read only producer metadata. Parsing the full dossier would allocate every
+    // large collection merely to discover its already authenticated parent ID.
+    const parsed = nativeMetadataSchema.safeParse(evidence.normalized_result);
+    if (!parsed.success)
+        return { available: false, reason: "not-recorded-or-incompatible" };
+    const flow = valueFlowMetadataSchema.safeParse(parsed.data.native_value_flow);
+    return {
+        available: true,
+        procedure_address: parsed.data.procedure.address,
+        procedure_name: parsed.data.procedure.name ?? null,
+        value_flow: parsed.data.native_value_flow == null
+            ? { status: "not-recorded" }
+            : !flow.success
+                ? {
+                    status: "unknown",
+                    reason: "Value-flow metadata has an incompatible representation.",
+                }
+                : flow.data.available
+                    ? {
+                        status: "observed",
+                        truncated: flow.data.truncated,
+                        omitted_operations_lower_bound: flow.data.omitted_operations_lower_bound ?? null,
+                        known_omitted_inputs: flow.data.known_omitted_inputs ?? null,
+                        known_omitted_edges: flow.data.known_omitted_edges ?? null,
+                    }
+                    : { status: "unavailable", reason: flow.data.reason },
+    };
+};
+/** Discover retained Evidence without reading or copying its complete payloads. */
+export const summarizeEvidenceBundle = (bundle, filters = {}) => {
+    const selectedFilters = {};
+    for (const [field, value] of Object.entries(filters))
+        if (value !== undefined)
+            selectedFilters[field] = value;
+    const records = [];
+    for (const evidence of bundle.records) {
+        if ((filters.evidence_id !== undefined &&
+            filters.evidence_id !== evidence.evidence_id) ||
+            (filters.operation !== undefined &&
+                filters.operation !== evidence.operation) ||
+            (filters.target_sha256 !== undefined &&
+                filters.target_sha256 !== evidence.subject?.digest.sha256) ||
+            (filters.analysis_profile_digest !== undefined &&
+                filters.analysis_profile_digest !== evidence.analysis_profile?.digest))
+            continue;
+        const native = nativeSummary(evidence);
+        if (filters.procedure_address !== undefined &&
+            (!native.available ||
+                filters.procedure_address !== native.procedure_address))
+            continue;
+        records.push({
+            evidence_id: evidence.evidence_id,
+            subject: evidence.subject,
+            provider: evidence.provider,
+            operation: evidence.operation,
+            confidence: evidence.confidence,
+            authority: evidence.authority,
+            analysis_profile_digest: evidence.analysis_profile?.digest ?? null,
+            retention: "complete-record",
+            limitation_count: evidence.limitations.length,
+            native_dossier: native,
+        });
+    }
+    return {
+        kind: "evidence-bundle-summary",
+        filters: selectedFilters,
+        total_retained_records: bundle.records.length,
+        matching_records: records.length,
+        unknown_revisions: bundle.unknowns.length,
+        records,
+    };
+};

package/dist/domain/evm/evmInterface.js

@@ -1,12 +1,11 @@
 import { z } from "zod";
+import { localPathStringSchema } from "../localPath.js";
+import { solidityMetadataSchema } from "./solidityMetadata.js";
 const byteOffset = z.number().int().nonnegative();
 const sha256 = z.string().regex(/^[a-f0-9]{64}$/);
 /** Select the carrier representation explicitly; no RPC or deployed-contract lookup is implied. */
 export const inspectEvmInterfaceInputSchema = z.strictObject({
-    path: z
-        .string()
-        .min(1)
-        .describe("Absolute path to caller-selected local bytecode carrier"),
+    path: localPathStringSchema.describe("Absolute path to caller-selected local bytecode carrier"),
     encoding: z
         .enum(["raw", "hex"])
         .describe("Raw bytes or UTF-8 hex with optional 0x prefix and outer ASCII whitespace"),
@@ -28,6 +27,7 @@ export const evmInterfaceSchema = z
         kind: z.literal("unknown"),
         deployment_authenticity: z.literal("unknown"),
         hardfork: z.literal("unknown"),
+        metadata: solidityMetadataSchema.nullable().default(null),
     }),
     evidence_kind: z.literal("inferred"),
     functions: z.array(z.strictObject({
@@ -53,6 +53,20 @@ export const evmInterfaceSchema = z
             path: ["bytecode"],
             message: "Selected byte count does not match the bytecode hex representation.",
         });
+    const metadata = value.bytecode.metadata;
+    if (metadata !== null &&
+        metadata.status !== "unavailable" &&
+        (metadata.bytecode_offset === null ||
+            metadata.cbor_bytes === null ||
+            metadata.bytecode_offset + metadata.cbor_bytes + 2 !==
+                value.bytecode.bytes ||
+            metadata.cbor_bytes !==
+                Number.parseInt(value.bytecode.hex.slice(-4), 16)))
+        context.addIssue({
+            code: "custom",
+            path: ["bytecode", "metadata"],
+            message: "Metadata range must match the terminal length suffix in selected bytecode.",
+        });
     for (const [index, fn] of value.functions.entries())
         if (fn.bytecode_offset >= value.bytecode.bytes)
             context.addIssue({

package/dist/domain/evm/solidityMetadata.js

@@ -0,0 +1,70 @@
+import { z } from "zod";
+/** Scalar view of CBOR; uninterpreted containers remain in original bytecode. */
+export const solidityMetadataScalarSchema = z.discriminatedUnion("kind", [
+    z.strictObject({ kind: z.literal("text"), value: z.string().max(65535) }),
+    z.strictObject({
+        kind: z.literal("integer"),
+        value: z
+            .string()
+            .max(21)
+            .regex(/^-?(?:0|[1-9][0-9]*)$/),
+    }),
+    z.strictObject({
+        kind: z.literal("bytes"),
+        value: z
+            .string()
+            .max(131070)
+            .regex(/^(?:[a-f0-9]{2})*$/),
+    }),
+    z.strictObject({ kind: z.literal("boolean"), value: z.boolean() }),
+    z.strictObject({ kind: z.literal("null") }),
+    z.strictObject({
+        kind: z.literal("uninterpreted"),
+        container: z.enum(["array", "map"]),
+    }),
+]);
+/** A trailer candidate, not authentication of Solidity origin or deployment. */
+export const solidityMetadataSchema = z
+    .strictObject({
+    profile: z.literal("terminal-cbor-scalars-v1"),
+    status: z.enum(["unavailable", "decoded", "partial", "not-decoded"]),
+    bytecode_offset: z.number().int().nonnegative().nullable(),
+    cbor_bytes: z.number().int().positive().max(65535).nullable(),
+    entries: z
+        .array(z.strictObject({
+        key: solidityMetadataScalarSchema,
+        value: solidityMetadataScalarSchema,
+    }))
+        .max(32767),
+    compiler_version: z
+        .strictObject({
+        representation: z.enum(["release-bytes", "prerelease-text"]),
+        value: z.string().min(1).max(65535),
+    })
+        .nullable(),
+    diagnostic: z.string().max(512).nullable(),
+})
+    .superRefine((value, context) => {
+    const unavailable = value.status === "unavailable";
+    if (unavailable
+        ? value.bytecode_offset !== null || value.cbor_bytes !== null
+        : value.bytecode_offset === null || value.cbor_bytes === null)
+        context.addIssue({
+            code: "custom",
+            message: "Only unavailable metadata omits the candidate range.",
+        });
+    const unexamined = unavailable || value.status === "not-decoded";
+    if (unexamined &&
+        (value.entries.length !== 0 || value.compiler_version !== null))
+        context.addIssue({
+            code: "custom",
+            message: "Unavailable interpretation cannot report decoded entries or compiler identity.",
+        });
+    const uninterpreted = value.entries.some(({ key, value: entryValue }) => key.kind === "uninterpreted" || entryValue.kind === "uninterpreted");
+    if ((value.status === "decoded" && uninterpreted) ||
+        (value.status === "partial" && !uninterpreted))
+        context.addIssue({
+            code: "custom",
+            message: "Scalar coverage must preserve uninterpreted containers.",
+        });
+});