rea-agents 5.0.0 → 6.1.0

package/dist/domain/canonicalJsonDigestSteps.js

@@ -0,0 +1,133 @@
+import { createHash } from "node:crypto";
+/** Hash owned, validated JSON in bounded steps without a document-sized string. */
+export function* canonicalJsonDigestSteps(value) {
+    const hash = createHash("sha256");
+    const ancestors = new Set();
+    const stack = [{ kind: "value", value }];
+    let buffered = "";
+    let flushed = false;
+    const emit = (part) => {
+        buffered += part;
+        if (buffered.length >= 8192) {
+            hash.update(buffered);
+            buffered = "";
+            flushed = true;
+        }
+    };
+    try {
+        while (stack.length > 0) {
+            if (flushed) {
+                flushed = false;
+                yield;
+            }
+            const frame = stack.pop();
+            if (frame === undefined)
+                break;
+            if (frame.kind === "separator") {
+                emit(":");
+                continue;
+            }
+            if (frame.kind === "string") {
+                if (frame.index === frame.value.length) {
+                    emit('"');
+                    continue;
+                }
+                let end = Math.min(frame.index + 8192, frame.value.length);
+                const last = frame.value.charCodeAt(end - 1);
+                const next = frame.value.charCodeAt(end);
+                if (end < frame.value.length &&
+                    last >= 0xd800 &&
+                    last <= 0xdbff &&
+                    next >= 0xdc00 &&
+                    next <= 0xdfff)
+                    end -= 1;
+                emit(JSON.stringify(frame.value.slice(frame.index, end)).slice(1, -1));
+                frame.index = end;
+                stack.push(frame);
+                continue;
+            }
+            if (frame.kind === "array") {
+                if (frame.index === frame.length) {
+                    emit("]");
+                    ancestors.delete(frame.value);
+                    continue;
+                }
+                const item = frame.value[frame.index];
+                if (item === undefined)
+                    throw new TypeError("Canonical JSON digest requires dense JSON arrays");
+                if (frame.index++ > 0)
+                    emit(",");
+                stack.push(frame, { kind: "value", value: item });
+                continue;
+            }
+            if (frame.kind === "object") {
+                if (frame.index === frame.keys.length) {
+                    emit("}");
+                    ancestors.delete(frame.value);
+                    continue;
+                }
+                const key = frame.keys[frame.index++];
+                if (key === undefined)
+                    throw new TypeError("Canonical JSON object changed during hashing");
+                const item = frame.value[key];
+                if (item === undefined)
+                    continue;
+                if (frame.written++ > 0)
+                    emit(",");
+                if (key.length > 8192) {
+                    emit('"');
+                    stack.push(frame, { kind: "value", value: item }, { kind: "separator" }, { kind: "string", value: key, index: 0 });
+                    continue;
+                }
+                emit(JSON.stringify(key));
+                emit(":");
+                stack.push(frame, { kind: "value", value: item });
+                continue;
+            }
+            const item = frame.value;
+            if (typeof item === "string" && item.length > 8192) {
+                emit('"');
+                stack.push({ kind: "string", value: item, index: 0 });
+            }
+            else if (item === null || typeof item !== "object") {
+                if (typeof item === "number" && !Number.isFinite(item))
+                    throw new Error(Number.isNaN(item)
+                        ? "NaN is not allowed"
+                        : "Infinity is not allowed");
+                emit(JSON.stringify(item));
+            }
+            else {
+                if (ancestors.has(item))
+                    throw new Error("Circular reference detected");
+                ancestors.add(item);
+                if (Array.isArray(item)) {
+                    emit("[");
+                    stack.push({
+                        kind: "array",
+                        value: item,
+                        length: item.length,
+                        index: 0,
+                    });
+                }
+                else {
+                    emit("{");
+                    stack.push({
+                        kind: "object",
+                        value: item,
+                        keys: Object.keys(item).sort(),
+                        index: 0,
+                        written: 0,
+                    });
+                }
+            }
+        }
+        if (buffered !== "")
+            hash.update(buffered);
+        return hash.digest("hex");
+    }
+    finally {
+        stack.length = 0;
+        ancestors.clear();
+        buffered = "";
+    }
+}

package/dist/domain/canonicalOrdering.js

@@ -1,11 +1,15 @@
+import { compareUnicodeCodePoints } from "./unicodeCodePointOrder.js";
 /**
  * Canonical code-point ordering shared across domain and application layers.
  *
- * Compares strings by Unicode code point (`<`/`>`) so graph ordering,
- * fingerprints, and deterministic tie-breaks stay stable regardless of
- * locale. Prefer this over `String.prototype.localeCompare`, which is
- * locale-dependent.
+ * Compares strings by Unicode code point so graph ordering, fingerprints, and
+ * deterministic tie-breaks stay stable regardless of locale. Prefer this over
+ * `String.prototype.localeCompare`, which is locale-dependent.
+ *
+ * Ordering by code point differs from ordering by UTF-16 code unit for astral
+ * code points (above U+FFFF), whose lead surrogate is numerically below the
+ * BMP tail U+E000-U+FFFF.
  */
-export const compareCodePoints = (left, right) => left < right ? -1 : left > right ? 1 : 0;
+export const compareCodePoints = (left, right) => compareUnicodeCodePoints(left, right);
 /** Deduplicate and sort strings with canonical code-point ordering. */
 export const uniqueSorted = (values) => [...new Set(values)].sort(compareCodePoints);

package/dist/domain/changedBehavior.js

@@ -1,15 +1,16 @@
 import { z } from "zod";
 import { artifactComparisonResultSchema } from "./artifactComparison.js";
 import { uniqueSorted } from "./canonicalOrdering.js";
+import { comparisonSourceEvidenceIds } from "./comparisonSourceEvidence.js";
 import { evidenceSchema, parseEvidence } from "./evidence.js";
 import { functionComparisonResultSchema } from "./functionComparison.js";
-import { PROCESS_PROVIDER, isProcessEvidenceProvider, } from "./processEvidenceProvider.js";
-import { comparisonStatusSchema, deriveProcessComparisonStatus, PROCESS_COMPARISON_DIMENSIONS, processCaptureComparisonSchema, } from "./processCapture.js";
+import { PROCESS_PROVIDER, isProcessEvidenceProvider, } from "./process/processEvidenceProvider.js";
+import { comparisonStatusSchema, deriveProcessComparisonStatus, PROCESS_COMPARISON_DIMENSIONS, processCaptureComparisonSchema, } from "./process/processCapture.js";
 import { prefixedDigestSchema } from "./../domain/digests.js";
 const evidenceIdSchema = prefixedDigestSchema("ev");
 /** Input for aggregating existing comparison Evidence. */
-export const changedBehaviorInputSchema = z.object({
-    comparisons: z.array(evidenceSchema).default([]),
+export const changedBehaviorInputSchema = z.strictObject({
+    comparisons: z.array(evidenceSchema).min(1),
 });
 const findingSchema = z.object({
     scope: z.enum(["runtime", "protocol", "resource", "static_candidate"]),
@@ -22,7 +23,7 @@ const findingSchema = z.object({
     ]),
     status: comparisonStatusSchema,
     source_comparison_id: evidenceIdSchema,
-    evidence_links: z.array(evidenceIdSchema).min(3),
+    evidence_links: z.array(evidenceIdSchema).min(2),
     limitations: z.array(z.string()),
 });
 /** Truthful aggregate: runtime observations remain separate from static candidates. */
@@ -43,7 +44,7 @@ export const changedBehaviorResultSchema = z
     findings: z.object({
         items: z.array(findingSchema),
     }),
-    evidence_links: z.array(evidenceIdSchema).min(3),
+    evidence_links: z.array(evidenceIdSchema).min(2),
     limitations: z.array(z.string()),
 })
     .superRefine((result, context) => {
@@ -141,9 +142,8 @@ const parseComparisonEvidence = (input) => {
         evidence.authority !== "analyst-inference" ||
         evidence.subject !== null)
         throw new TypeError("Comparison Evidence operation, predicate, and provider disagree");
-    if (evidence.evidence_links.length < 2)
-        throw new TypeError("Comparison Evidence must cite both source observations");
-    assertUnique(evidence.evidence_links, "source Evidence links");
+    if (!comparisonSourceEvidenceIds(evidence).every((id) => evidence.evidence_links.includes(id)))
+        throw new TypeError("Comparison Evidence must cite both selected source observations");
     parseResult(evidence);
     return evidence;
 };

package/dist/domain/comparisonSourceEvidence.js

@@ -0,0 +1,40 @@
+import { z } from "zod";
+import { uniqueSorted } from "./canonicalOrdering.js";
+import { prefixedDigestSchema } from "./digests.js";
+const evidenceIdSchema = prefixedDigestSchema("ev");
+const sideParametersSchema = z.object({
+    left_evidence_id: evidenceIdSchema.optional(),
+    right_evidence_id: evidenceIdSchema.optional(),
+    left_evidence_ids: z.array(evidenceIdSchema).min(1).optional(),
+    right_evidence_ids: z.array(evidenceIdSchema).min(1).optional(),
+});
+/** Resolve each selected side and validate aliases and duplicates within that role. */
+export const comparisonSourceEvidenceSides = (evidence) => {
+    const parameters = sideParametersSchema.parse(evidence.parameters);
+    if ((parameters.left_evidence_id === undefined) !==
+        (parameters.right_evidence_id === undefined) ||
+        (parameters.left_evidence_ids === undefined) !==
+            (parameters.right_evidence_ids === undefined))
+        throw new TypeError("Comparison Evidence source representation omitted one side");
+    const side = (single, multiple) => {
+        if (single !== undefined &&
+            multiple !== undefined &&
+            (multiple.length !== 1 || multiple[0] !== single))
+            throw new TypeError("Comparison Evidence source representations disagree");
+        const selected = single === undefined ? (multiple ?? []) : [single];
+        if (selected.length === 0)
+            throw new TypeError("Comparison Evidence omitted its source parameters");
+        if (new Set(selected).size !== selected.length)
+            throw new TypeError("Comparison Evidence repeats a source within one side");
+        return selected;
+    };
+    return {
+        left: side(parameters.left_evidence_id, parameters.left_evidence_ids),
+        right: side(parameters.right_evidence_id, parameters.right_evidence_ids),
+    };
+};
+/** Resolve the source closure without counting observations shared by both roles twice. */
+export const comparisonSourceEvidenceIds = (evidence) => {
+    const sides = comparisonSourceEvidenceSides(evidence);
+    return uniqueSorted([...sides.left, ...sides.right]);
+};

package/dist/domain/comparisonStatus.js

@@ -1,39 +1,11 @@
 import { z } from "zod";
 /**
  * Canonical top-level comparison outcome shared by every comparison
- * pipeline. Pipeline-native detail enums (bundle classifications,
- * source-to-bundle split/merge kinds, scenario alignment states, function
- * truncation) keep their wire schemas; the mappers below project each of
- * them onto this triple without changing any pipeline result.
+ * pipeline. Pipeline-native detail enums keep their wire schemas, while
+ * shared result contracts use this canonical triple.
  */
 export const comparisonStatusSchema = z.enum([
     "unchanged",
     "changed",
     "unknown",
 ]);
-/** Canonical comparison conclusion shared by every comparison pipeline. */
-export const comparisonConclusionSchema = z.enum([
-    "observed_change",
-    "derived_relationship",
-    "contradiction",
-    "unresolved_branch",
-]);
-/** Project a bundle change classification onto the canonical triple. */
-export const bundleClassificationToCanonical = (classification) => (classification === "unknown" ? "unknown" : "changed");
-/** Project a source-to-bundle item status onto the canonical triple. */
-export const sourceToBundleStatusToCanonical = (status) => status === "unchanged"
-    ? "unchanged"
-    : status === "unknown"
-        ? "unknown"
-        : "changed";
-/**
- * Project a function dimension status onto the canonical triple. A
- * truncated dimension cannot support an unchanged/changed claim.
- */
-export const functionStatusToCanonical = (status) => status === "unchanged"
-    ? "unchanged"
-    : status === "changed"
-        ? "changed"
-        : "unknown";
-/** Project a browser-scenario artifact status onto the canonical triple. */
-export const scenarioArtifactStatusToCanonical = (status) => status;

package/dist/domain/configurationErrors.js

@@ -1,4 +1,4 @@
-import { AnalysisError } from "./analysisErrorBase.js";
+import { AnalysisError, } from "./analysisErrorBase.js";
 /** Runtime configuration could not be parsed safely. */
 export class ConfigurationError extends AnalysisError {
     _tag = "ConfigurationError";

package/dist/domain/conformanceTrustGate.js

@@ -38,18 +38,6 @@ const VOLATILE_DIMENSIONS = new Set([
     "created_at",
     "updated_at",
 ]);
-/** Dimension that carries semantic content. */
-const SEMANTIC_DIMENSIONS = new Set([
-    "exit_code",
-    "stdout",
-    "stderr",
-    "filesystem",
-    "process",
-    "process_tree",
-    "shim_events",
-    "protocol_events",
-    "event_journal",
-]);
 const isRecord = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
 const uniqueStrings = (values) => [
     ...new Set(values.filter((value) => value.length > 0)),
@@ -172,10 +160,6 @@ const comparisonIncompleteStatus = (expected, actual, options) => {
 export function isVolatileDimension(name) {
     return VOLATILE_DIMENSIONS.has(name);
 }
-/** Check if a dimension name carries semantic content. */
-export function isSemanticDimension(name) {
-    return SEMANTIC_DIMENSIONS.has(name);
-}
 /**
  * Compare two values for a dimension, classifying semantic diffs
  * from timing/normalization noise.

package/dist/domain/evidence.js

@@ -1,7 +1,9 @@
 import { z } from "zod";
 import { digestCanonicalValue } from "./canonicalDigest.js";
+import { canonicalJsonDigestSteps } from "./canonicalJsonDigestSteps.js";
 import { analysisProfileSchema, } from "./analysisProfile.js";
-import { jsonValueSchema } from "./jsonValue.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";
 /** Provider identity schema shared by evidence-bearing persistence formats. */
@@ -79,7 +81,7 @@ const evidenceBaseSchema = z
     provider: providerSchema,
     predicate_type: z.string().min(1),
     operation: z.string().min(1),
-    parameters: z.record(z.string(), jsonValueSchema),
+    parameters: jsonObjectSchema,
     raw_result: jsonValueSchema.nullable(),
     normalized_result: jsonValueSchema,
     confidence: z.enum(["observed", "derived", "inferred"]),
@@ -116,6 +118,14 @@ export const evidenceRecordSchema = z.union([
     profiledEvidenceSchema,
     evidenceBaseSchema,
 ]);
+const immutableEvidenceSnapshots = new WeakMap();
+const immutableResultSchema = z
+    .custom(isImmutableJsonSnapshot)
+    .superRefine((value, context) => {
+    const issue = jsonValueValidationIssue(value);
+    if (issue !== undefined)
+        context.addIssue({ code: "custom", message: issue });
+});
 const semanticProjection = (evidence) => ({
     subject: evidence.subject === null
         ? null
@@ -140,22 +150,64 @@ const semanticProjection = (evidence) => ({
     locations: evidence.locations,
     evidence_links: evidence.evidence_links,
 });
-/** Recompute the semantic identifier, excluding paths and raw payload bytes. */
+/** Hash semantic content, including raw results and excluding display-subject fields. */
 const computeEvidenceId = (evidence) => `ev_${digestCanonicalValue(semanticProjection(evidence), "Evidence")}`;
 /** Parse evidence and reject a syntactically valid but tampered semantic ID. */
 export const parseEvidence = (input) => {
-    const evidence = evidenceRecordSchema.parse(input);
+    const immutable = typeof input === "object" && input !== null
+        ? immutableEvidenceSnapshots.get(input)
+        : undefined;
+    if (immutable !== undefined)
+        return immutable;
+    // Select the producer's envelope before traversing its payload. A legacy
+    // record cannot satisfy the required-profile branch, whose failed parse
+    // would otherwise clone the entire normalized result before trying legacy.
+    const schema = typeof input === "object" && input !== null && "analysis_profile" in input
+        ? profiledEvidenceSchema
+        : evidenceBaseSchema;
+    const evidence = schema.parse(input);
     const { evidence_id: evidenceId, ...withoutId } = evidence;
     if (computeEvidenceId(withoutId) !== evidenceId)
         throw new TypeError("Evidence semantic identifier does not match its record");
     return evidence;
 };
+/** Authenticate and seal a ledger-owned snapshot; external mutable values are copied first. */
+export const immutableEvidence = (input) => rememberImmutableEvidence(parseEvidence(input));
+/** Recognize authenticated Evidence whose complete reachable JSON data is immutable. */
+export const isImmutableEvidence = (evidence) => immutableEvidenceSnapshots.has(evidence);
+const rememberImmutableEvidence = (evidence) => {
+    freezeJsonSnapshot(evidence);
+    immutableEvidenceSnapshots.set(evidence, evidence);
+    return evidence;
+};
 /** Build deterministic Evidence from an immutable artifact subject. */
 export const createEvidence = (target, provider, observation) => {
+    const { normalized, sharedResult } = normalizeEvidenceObservation(target, provider, observation);
+    const evidence = {
+        ...normalized,
+        evidence_id: computeEvidenceId(normalized),
+    };
+    return sharedResult ? rememberImmutableEvidence(evidence) : evidence;
+};
+/** Create Evidence from owned immutable JSON while exposing cooperative computation steps. */
+export function* createImmutableEvidenceSteps(target, provider, observation) {
+    if (!isImmutableJsonSnapshot(observation.result))
+        throw new TypeError("Cooperative Evidence requires an authenticated immutable result");
+    // The envelope parser below retains its usual diagnostics, using the completed
+    // immutable validation rather than traversing the payload synchronously again.
+    yield* jsonValueValidationSteps(observation.result);
+    const { normalized } = normalizeEvidenceObservation(target, provider, observation);
+    const digest = yield* canonicalJsonDigestSteps(semanticProjection(normalized));
+    return rememberImmutableEvidence({
+        ...normalized,
+        evidence_id: `ev_${digest}`,
+    });
+}
+const normalizeEvidenceObservation = (target, provider, observation) => {
     const subject = target === undefined
         ? null
         : {
-            name: target.path.split("/").at(-1) ?? target.path,
+            name: target.path.split("/").at(-1) || "artifact",
             digest: { sha256: target.sha256 },
             format: target.format,
             architecture: target.architecture ?? null,
@@ -187,20 +239,35 @@ export const createEvidence = (target, provider, observation) => {
         environment: observation.environment ?? null,
         limitations: [
             ...(target === undefined
-                ? ["Artifact identity is unavailable for this observation."]
+                ? [
+                    observation.subjectUnavailableReason ??
+                        "Artifact identity is unavailable for this observation.",
+                ]
                 : []),
             ...(observation.limitations ?? []),
         ],
         locations: [...(observation.locations ?? [])],
         evidence_links: [...(observation.evidenceLinks ?? [])],
     };
-    const normalized = evidenceRecordSchema.parse({
+    // Select the known envelope before parsing. A union otherwise traverses and
+    // clones a legacy result for the profiled branch before rejecting its absent
+    // profile and trying the legacy branch.
+    const schema = observation.analysisProfile === undefined
+        ? evidenceBaseSchema
+        : profiledEvidenceSchema;
+    const sharedResult = typeof observation.result === "object" &&
+        observation.result !== null &&
+        isImmutableJsonSnapshot(observation.result);
+    const selectedSchema = sharedResult
+        ? schema.safeExtend({ normalized_result: immutableResultSchema })
+        : schema;
+    const normalized = selectedSchema.parse({
         ...semantic,
         evidence_id: `ev_${"0".repeat(64)}`,
         subject,
     });
-    return parseEvidence({
-        ...normalized,
-        evidence_id: computeEvidenceId(normalized),
-    });
+    // The envelope has already been parsed into an independent snapshot. Only
+    // its derived identifier changes here; parsing again clones the full payload
+    // and recomputes the same digest while the previous snapshot is still live.
+    return { normalized, sharedResult };
 };

package/dist/domain/evidenceBundle.js

@@ -1,7 +1,8 @@
 import { z } from "zod";
 import canonicalize from "canonicalize";
-import { evidenceEnvelopeSchema, evidenceRecordSchema, parseEvidence, providerSchema, } from "./evidence.js";
+import { evidenceEnvelopeSchema, evidenceRecordSchema, immutableEvidence, parseEvidence, providerSchema, } from "./evidence.js";
 import { residualUnknownSchema, } from "./residualUnknown.js";
+import { freezeJsonSnapshot } from "./immutableJson.js";
 const artifactManifestSchema = evidenceEnvelopeSchema.shape.subject
     .unwrap()
     .pick({
@@ -29,6 +30,19 @@ export const evidenceBundleSchema = z.object({
     unknowns: z.array(residualUnknownSchema),
     records: z.array(evidenceRecordSchema),
 });
+const immutableBundles = new WeakMap();
+/** Build and authenticate a sealed bundle while reusing immutable Evidence records. */
+export const createImmutableEvidenceBundle = (records, unknowns = []) => {
+    const checkedRecords = records.map(immutableEvidence);
+    if (new Set(checkedRecords.map(({ evidence_id }) => evidence_id)).size !==
+        checkedRecords.length)
+        throw new TypeError("Evidence bundle contains duplicate record IDs");
+    const checkedUnknowns = unknowns.map((unknown) => residualUnknownSchema.parse(unknown));
+    validateUnknownGraph(checkedUnknowns, checkedRecords);
+    const bundle = freezeJsonSnapshot(createEvidenceBundle(checkedRecords, checkedUnknowns));
+    immutableBundles.set(bundle, bundle);
+    return bundle;
+};
 /** Project records into a deterministic bundle whose order has no semantics. */
 export const createEvidenceBundle = (records, unknowns = []) => {
     const sortedRecords = [...records].sort((left, right) => left.evidence_id.localeCompare(right.evidence_id));
@@ -120,8 +134,35 @@ 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 = evidenceRecordSchema.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.`;
+};
+/** Locate the first schema issue, or keep a thrown constraint message. */
+export const describeValidationFailure = (cause) => {
+    if (!(cause instanceof z.ZodError))
+        return cause instanceof Error ? cause.message : String(cause);
+    const [first, ...rest] = cause.issues;
+    const location = first === undefined || first.path.length === 0
+        ? "the document root"
+        : first.path.map(String).join(".");
+    return `at ${location}: ${first?.message ?? "invalid value"}${rest.length === 0 ? "" : ` (${String(rest.length)} more issues)`}`;
+};
 /** Parse records, verify semantic IDs, and reject inconsistent manifests. */
 export const parseEvidenceBundle = (input) => {
+    if (typeof input === "object" && input !== null) {
+        const owned = immutableBundles.get(input);
+        if (owned !== undefined)
+            return owned;
+    }
     const parsed = evidenceBundleSchema.parse(input);
     const recordIds = parsed.records.map(({ evidence_id: id }) => id);
     if (new Set(recordIds).size !== recordIds.length)

package/dist/domain/evidenceErrors.js

@@ -1,7 +1,15 @@
-import { AnalysisError } from "./analysisErrorBase.js";
+import { AnalysisError, } from "./analysisErrorBase.js";
 /** Evidence identity, schema, or bundle manifests failed integrity checks. */
 export class EvidenceIntegrityError extends AnalysisError {
     _tag = "EvidenceIntegrityError";
+    userMessage;
+    constructor(message, options) {
+        super(message, options);
+        this.userMessage = options?.userMessage;
+    }
+}
+/** A valid snapshot belongs to a different target, provider, or analysis profile. */
+export class AnalysisSnapshotMismatchError extends EvidenceIntegrityError {
 }
 /** A session Evidence reference is missing or has the wrong semantic identity. */
 export class EvidenceReferenceError extends EvidenceIntegrityError {
@@ -22,9 +30,12 @@ export class EvidenceFileError extends AnalysisError {
     operation;
     reason;
     _tag = "EvidenceFileError";
+    /** Caller-selected path that failed, resolved against the working directory. */
+    path;
     constructor(operation, reason, options) {
         super(`Evidence bundle ${operation} failed: ${reason}`, options);
         this.operation = operation;
         this.reason = reason;
+        this.path = options?.path;
     }
 }

package/dist/domain/evm/evmInterface.js

@@ -0,0 +1,63 @@
+import { z } from "zod";
+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"),
+    encoding: z
+        .enum(["raw", "hex"])
+        .describe("Raw bytes or UTF-8 hex with optional 0x prefix and outer ASCII whitespace"),
+});
+/** Recovered interface candidates are inferences, independently of observed byte identity. */
+export const evmInterfaceSchema = z
+    .strictObject({
+    artifact: z.strictObject({
+        path: z.string().min(1),
+        sha256,
+        bytes: byteOffset,
+        encoding: z.enum(["raw", "hex"]),
+    }),
+    bytecode: z.strictObject({
+        sha256,
+        bytes: byteOffset,
+        hex: z.string().regex(/^(?:[0-9a-f]{2})*$/),
+        digest_algorithm: z.literal("sha256"),
+        kind: z.literal("unknown"),
+        deployment_authenticity: z.literal("unknown"),
+        hardfork: z.literal("unknown"),
+    }),
+    evidence_kind: z.literal("inferred"),
+    functions: z.array(z.strictObject({
+        selector: z.string().regex(/^0x[0-9a-f]{8}$/),
+        bytecode_offset: byteOffset,
+        dispatch: z.enum(["abi", "fallback"]),
+        inferred_arguments: z.string().nullable(),
+        inferred_state_mutability: z.string().nullable(),
+    })),
+    discovery_completeness: z.literal("unknown"),
+    runtime_execution: z.literal("not-performed"),
+    diagnostics: z.strictObject({
+        stdout: z.string(),
+        stderr: z.string(),
+        truncated: z.boolean(),
+    }),
+    limitations: z.array(z.string()),
+})
+    .superRefine((value, context) => {
+    if (value.bytecode.hex.length !== value.bytecode.bytes * 2)
+        context.addIssue({
+            code: "custom",
+            path: ["bytecode"],
+            message: "Selected byte count does not match the bytecode hex representation.",
+        });
+    for (const [index, fn] of value.functions.entries())
+        if (fn.bytecode_offset >= value.bytecode.bytes)
+            context.addIssue({
+                code: "custom",
+                path: ["functions", index, "bytecode_offset"],
+                message: "Inferred body offset lies outside the selected bytecode.",
+            });
+});