rea-agents 6.0.0 → 6.2.0

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. */
@@ -77,9 +79,10 @@ const evidenceBaseSchema = z
     evidence_id: prefixedDigestSchema("ev"),
     subject: subjectSchema.nullable(),
     provider: providerSchema,
+    analysis_profile: analysisProfileSchema.nullable(),
     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"]),
@@ -90,13 +93,10 @@ const evidenceBaseSchema = z
     evidence_links: z.array(prefixedDigestSchema("ev")),
 })
     .strict();
-/** Object envelope used to specialize caller-visible Evidence result schemas. */
-export const evidenceEnvelopeSchema = evidenceBaseSchema.extend({
-    analysis_profile: analysisProfileSchema.optional(),
-});
-const validateAnalysisProfileProvider = (evidence, context) => {
+/** Require a reported analysis profile to identify the observation provider. */
+export const validateAnalysisProfileProvider = (evidence, context) => {
     const profile = evidence.analysis_profile;
-    if (profile !== undefined &&
+    if (profile !== null &&
         (profile.provider.id !== evidence.provider.id ||
             profile.provider.name !== evidence.provider.name ||
             profile.provider.version !== evidence.provider.version))
@@ -107,15 +107,15 @@ const validateAnalysisProfileProvider = (evidence, context) => {
         });
 };
 /** Strict, provider-neutral record for one successful public observation. */
-export const evidenceSchema = evidenceEnvelopeSchema.superRefine(validateAnalysisProfileProvider);
-const profiledEvidenceSchema = evidenceBaseSchema
-    .extend({ analysis_profile: analysisProfileSchema })
-    .superRefine(validateAnalysisProfileProvider);
-/** JSON-exact union used where Evidence participates in larger schemas. */
-export const evidenceRecordSchema = z.union([
-    profiledEvidenceSchema,
-    evidenceBaseSchema,
-]);
+export const evidenceSchema = evidenceBaseSchema.superRefine(validateAnalysisProfileProvider);
+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
@@ -125,9 +125,7 @@ const semanticProjection = (evidence) => ({
             architecture: evidence.subject.architecture,
         },
     provider: evidence.provider,
-    ...(!("analysis_profile" in evidence)
-        ? {}
-        : { analysis_profile: evidence.analysis_profile }),
+    analysis_profile: evidence.analysis_profile,
     predicate_type: evidence.predicate_type,
     operation: evidence.operation,
     parameters: evidence.parameters,
@@ -140,18 +138,54 @@ 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;
+    const evidence = evidenceSchema.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
         : {
@@ -174,9 +208,7 @@ export const createEvidence = (target, provider, observation) => {
             name: provider.name,
             version: provider.version,
         },
-        ...(observation.analysisProfile === undefined
-            ? {}
-            : { analysis_profile: observation.analysisProfile }),
+        analysis_profile: observation.analysisProfile ?? null,
         predicate_type: observation.predicateType ?? "rea.analysis",
         operation: observation.operation,
         parameters: observation.parameters,
@@ -197,13 +229,13 @@ export const createEvidence = (target, provider, observation) => {
         locations: [...(observation.locations ?? [])],
         evidence_links: [...(observation.evidenceLinks ?? [])],
     };
-    // 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 normalized = schema.parse({
+    const sharedResult = typeof observation.result === "object" &&
+        observation.result !== null &&
+        isImmutableJsonSnapshot(observation.result);
+    const selectedSchema = sharedResult
+        ? evidenceSchema.safeExtend({ normalized_result: immutableResultSchema })
+        : evidenceSchema;
+    const normalized = selectedSchema.parse({
         ...semantic,
         evidence_id: `ev_${"0".repeat(64)}`,
         subject,
@@ -211,8 +243,5 @@ export const createEvidence = (target, provider, observation) => {
     // 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,
-        evidence_id: computeEvidenceId(normalized),
-    };
+    return { normalized, sharedResult };
 };

package/dist/domain/evidenceBundle.js

@@ -1,23 +1,22 @@
 import { z } from "zod";
 import canonicalize from "canonicalize";
-import { evidenceEnvelopeSchema, evidenceRecordSchema, parseEvidence, providerSchema, } from "./evidence.js";
+import { evidenceSchema, immutableEvidence, parseEvidence, providerSchema, } from "./evidence.js";
 import { residualUnknownSchema, } from "./residualUnknown.js";
-const artifactManifestSchema = evidenceEnvelopeSchema.shape.subject
-    .unwrap()
-    .pick({
+import { freezeJsonSnapshot } from "./immutableJson.js";
+const artifactManifestSchema = evidenceSchema.shape.subject.unwrap().pick({
     digest: true,
     format: true,
     architecture: true,
 });
 const providerManifestSchema = providerSchema;
-const environmentManifestSchema = evidenceEnvelopeSchema.shape.environment.unwrap();
+const environmentManifestSchema = evidenceSchema.shape.environment.unwrap();
 const scenarioManifestSchema = z.object({
-    evidence_id: evidenceEnvelopeSchema.shape.evidence_id,
+    evidence_id: evidenceSchema.shape.evidence_id,
     operation: z.string().min(1),
     authority: z.literal("controlled-replay"),
 });
 const captureManifestSchema = z.object({
-    evidence_id: evidenceEnvelopeSchema.shape.evidence_id,
+    evidence_id: evidenceSchema.shape.evidence_id,
     predicate_type: z.string().min(1),
 });
 export const evidenceBundleSchema = z.object({
@@ -27,8 +26,21 @@ export const evidenceBundleSchema = z.object({
     scenarios: z.array(scenarioManifestSchema),
     captures: z.array(captureManifestSchema),
     unknowns: z.array(residualUnknownSchema),
-    records: z.array(evidenceRecordSchema),
+    records: z.array(evidenceSchema),
 });
+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 +132,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 = 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.`;
+};
+/** 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/evidenceCompletionLedger.js

@@ -1,9 +1,10 @@
 import { createHash } from "node:crypto";
 import canonicalize from "canonicalize";
 import { z } from "zod";
+import { IDENTIFIER_PATTERN } from "./stringPatterns.js";
 import { prefixedDigestSchema } from "./../domain/digests.js";
 const evidenceIdSchema = prefixedDigestSchema("ev");
-const claimIdSchema = z.string().regex(/^[A-Za-z][A-Za-z0-9._-]*$/u);
+const claimIdSchema = z.string().regex(IDENTIFIER_PATTERN);
 /** Terminal outcome recorded for one verifier claim. */
 export const evidenceCompletionStatusSchema = z.enum([
     "pass",

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/explicitSensitiveFailure.js

@@ -1,4 +1,4 @@
-import { AnalysisAccessDeniedError, AnalysisArtifactChangedError, AnalysisInputError, AnalysisOutputError, AnalysisCapabilityUnavailableError, } from "./analysisErrorCore.js";
+import { AnalysisAccessDeniedError, AnalysisArtifactChangedError, AnalysisInputError, AnalysisOutputError, AnalysisCapabilityUnavailableError, AnalysisResourceConstraintError, } from "./analysisErrorCore.js";
 import { redactExplicitText } from "./explicitSensitiveValues.js";
 import { ProviderAdapterError } from "./providerAdapterError.js";
 import { ProviderCleanupError } from "./providerCleanupError.js";
@@ -79,6 +79,22 @@ export const redactExplicitFailure = (error, values) => {
                 ? {}
                 : { userMessage: text(error.userMessage) }),
         });
+    if (error instanceof AnalysisResourceConstraintError)
+        return new AnalysisResourceConstraintError(error.operation, error.resource, text(error.reason), error.reportedLimits === null ? null : diagnostics(error.reportedLimits), {
+            cause: error,
+            ...(error.remediationAction === undefined
+                ? {}
+                : { remediationAction: text(error.remediationAction) }),
+            ...(error.capturedOutput === undefined
+                ? {}
+                : {
+                    capturedOutput: {
+                        stdout: text(error.capturedOutput.stdout),
+                        stderr: text(error.capturedOutput.stderr),
+                        truncated: error.capturedOutput.truncated,
+                    },
+                }),
+        });
     if (error instanceof ProviderCleanupError)
         return new ProviderCleanupError(error.providerId, error.cleanupResources.map(text), diagnostics(error.diagnostics ?? {}), { operation: error.operation, cause: error });
     if (error instanceof ProviderAdapterError)

package/dist/domain/firmware/firmwareAnalysis.js

@@ -1,13 +1,11 @@
 import { z } from "zod";
 import { digestSchema } from "../digests.js";
 import { jsonValueSchema } from "../jsonValue.js";
-import { isAbsoluteLocalPath } from "../localPath.js";
+import { isAbsoluteLocalPath, localPathStringSchema } from "../localPath.js";
 const bytes = z.number().int().min(0).max(Number.MAX_SAFE_INTEGER);
 const range = z.strictObject({ offset: bytes, length: bytes.positive() });
 const target = {
-    path: z
-        .string()
-        .min(1)
+    path: localPathStringSchema
         .refine(isAbsoluteLocalPath, {
         message: "path must be an absolute local filesystem path (for example /tmp/firmware.bin or C:\\firmware\\firmware.bin)",
     })
@@ -18,9 +16,10 @@ export const firmwareInputSchemas = {
     inspect_firmware_regions: z.strictObject(target),
     extract_firmware: z.strictObject({
         ...target,
-        output_directory: z
-            .string()
-            .min(1)
+        output_directory: localPathStringSchema
+            .refine(isAbsoluteLocalPath, {
+            message: "output_directory must be an absolute local filesystem path",
+        })
             .describe("Absolute, absent output directory; parent must exist"),
         range: range
             .optional()

package/dist/domain/functionComparison.js

@@ -4,15 +4,14 @@ import { functionMatch } from "./functionComparisonNormalization.js";
 import { functionComparisonResultSchema, } from "./functionComparisonSchemas.js";
 import { overallStatus, summarize } from "./functionComparisonResults.js";
 import { compareDimensions } from "./functionComparisonDimensions.js";
-export { functionComparisonInputSchema, functionComparisonResultSchema, } from "./functionComparisonSchemas.js";
 /** Compare two complete function Evidence records without fuzzy matching. */
 export const compareFunctions = (leftInput, rightInput) => {
     const left = parseFunctionEvidence(leftInput);
     const right = parseFunctionEvidence(rightInput);
-    const links = [left.evidence[0].evidence_id, right.evidence[0].evidence_id];
-    const providersDiffer = canonicalJson(left.provider, "Function comparison") !==
-        canonicalJson(right.provider, "Function comparison");
-    const dimensions = compareDimensions(left, right, links, providersDiffer);
+    const links = [left.evidence.evidence_id, right.evidence.evidence_id];
+    const providersDiffer = canonicalJson(left.evidence.provider, "Function comparison") !==
+        canonicalJson(right.evidence.provider, "Function comparison");
+    const dimensions = compareDimensions(left, right, { links, providersDiffer });
     const match = functionMatch(left, right);
     const changes = dimensions.filter(({ status }) => status !== "unchanged");
     return functionComparisonResultSchema.parse({