rea-agents 1.2.0 → 1.4.0

package/dist/domain/analysisSnapshot.js

@@ -0,0 +1,149 @@
+import { createHash } from "node:crypto";
+import canonicalize from "canonicalize";
+import { z } from "zod";
+import { evidenceBundleForTarget, evidenceBundleSchema, parseEvidenceBundle, } from "./evidenceBundle.js";
+import { evidenceLocationSchema, providerSchema, } from "./evidence.js";
+import { jsonObjectSchema, jsonValueSchema, } from "./jsonValue.js";
+const digestSchema = z.string().regex(/^[a-f0-9]{64}$/u);
+const architectureSchema = z.enum(["x86", "x86_64", "arm", "arm64"]);
+const formatSchema = z.enum([
+    "hopper",
+    "mach-o",
+    "elf",
+    "pe",
+    "zip",
+    "ipa",
+    "apk",
+    "asar",
+    "dmg",
+    "pkg",
+    "plist",
+    "javascript",
+    "source-map",
+]);
+const subjectSchema = z.object({
+    path: z.string().min(1),
+    sha256: digestSchema,
+    format: z.enum([
+        ...formatSchema.options,
+        "directory",
+        "file",
+        "unknown",
+        "mach-o-universal",
+        "javascript-bundle",
+        "entitlements",
+    ]),
+    architecture: architectureSchema.nullable(),
+});
+const targetSchema = z.object({
+    sha256: digestSchema,
+    format: formatSchema,
+    architecture: architectureSchema.nullable(),
+    loader_args: z.array(z.string()),
+});
+const entrySchema = z.object({
+    query_id: z.string().regex(/^query_[a-f0-9]{64}$/u),
+    operation: z.string().min(1),
+    parameters: jsonObjectSchema,
+    execution: z.object({
+        result: jsonValueSchema,
+        raw_result: jsonValueSchema.nullable(),
+        provider: providerSchema,
+        limitations: z.array(z.string()),
+        locations: z.array(evidenceLocationSchema),
+        subject: subjectSchema.nullable(),
+    }),
+});
+/** Provider-neutral, deterministic cache of successful immutable analysis calls. */
+const analysisSnapshotSchema = z.object({
+    snapshot_version: z.literal(1),
+    target: targetSchema,
+    entries: z.array(entrySchema).max(10_000),
+    evidence_bundle: evidenceBundleSchema,
+});
+const canonicalJson = (value) => {
+    const json = jsonValueSchema.parse(value);
+    const encoded = canonicalize(json);
+    if (encoded === undefined)
+        throw new TypeError("RFC 8785 canonicalization rejected snapshot data");
+    return encoded;
+};
+/** Project a binary into the path-free identity used for cache invalidation. */
+export const snapshotTarget = (target) => ({
+    sha256: target.sha256,
+    format: target.format,
+    architecture: target.architecture ?? null,
+    loader_args: [...target.loaderArgs],
+});
+/** Compare an open binary with the immutable identity in a snapshot. */
+export const snapshotMatchesTarget = (snapshot, target) => snapshot.sha256 === target.sha256 &&
+    snapshot.format === target.format &&
+    snapshot.architecture === (target.architecture ?? null) &&
+    JSON.stringify(snapshot.loader_args) === JSON.stringify(target.loaderArgs);
+/** Find exact persisted CLI evidence without starting an analysis provider. */
+export const snapshotEvidenceForQuery = (snapshot, query) => {
+    const { target, operation, parameters, provider } = query;
+    if (!snapshotMatchesTarget(snapshot.target, target))
+        return undefined;
+    const encodedParameters = canonicalJson(parameters);
+    return snapshot.evidence_bundle.records.find((record) => record.subject?.digest.sha256 === target.sha256 &&
+        record.operation === operation &&
+        record.provider.id === provider.id &&
+        record.provider.name === provider.name &&
+        record.provider.version === provider.version &&
+        canonicalJson(record.parameters) === encodedParameters);
+};
+/** Compute the stable lookup key for one provider-specific analysis query. */
+export const analysisQueryId = (target, operation, parameters, provider) => `query_${createHash("sha256")
+    .update(canonicalJson({
+    target,
+    operation,
+    parameters,
+    provider: {
+        id: provider.id,
+        name: provider.name,
+        version: provider.version,
+    },
+}))
+    .digest("hex")}`;
+/** Create one serializable snapshot entry from a successful provider call. */
+export const createAnalysisSnapshotEntry = (target, operation, parameters, execution) => ({
+    query_id: analysisQueryId(target, operation, parameters, execution.provider),
+    operation,
+    parameters: jsonObjectSchema.parse(parameters),
+    execution: {
+        result: execution.result,
+        raw_result: execution.rawResult,
+        provider: execution.provider,
+        limitations: [...execution.limitations],
+        locations: [...execution.locations],
+        subject: execution.subject === null
+            ? null
+            : {
+                ...execution.subject,
+                architecture: execution.subject.architecture ?? null,
+            },
+    },
+});
+/** Parse a snapshot and reject altered query IDs or non-canonical entry order. */
+export const parseAnalysisSnapshot = (input) => {
+    const parsed = analysisSnapshotSchema.parse(input);
+    parseEvidenceBundle(parsed.evidence_bundle);
+    if (JSON.stringify(evidenceBundleForTarget(parsed.evidence_bundle, parsed.target.sha256)) !== JSON.stringify(parsed.evidence_bundle))
+        throw new TypeError("Analysis snapshot evidence contains records for another target");
+    const ids = new Set();
+    for (const entry of parsed.entries) {
+        const expected = analysisQueryId(parsed.target, entry.operation, entry.parameters, entry.execution.provider);
+        if (entry.query_id !== expected)
+            throw new TypeError("Analysis snapshot query identifier does not match");
+        if (ids.has(entry.query_id))
+            throw new TypeError("Analysis snapshot contains duplicate queries");
+        ids.add(entry.query_id);
+    }
+    const sorted = [...parsed.entries].sort((left, right) => left.query_id.localeCompare(right.query_id));
+    if (JSON.stringify(parsed.entries) !== JSON.stringify(sorted))
+        throw new TypeError("Analysis snapshot entries are not canonical");
+    return parsed;
+};
+/** Serialize a validated snapshot with byte-stable canonical entry ordering. */
+export const serializeAnalysisSnapshot = (snapshot) => `${canonicalJson(parseAnalysisSnapshot(snapshot))}\n`;

package/dist/domain/artifactComparison.js

@@ -11,8 +11,15 @@ const comparisonStatusSchema = z.enum([
     "changed",
     "truncated",
     "unknown",
+    "contradiction",
+]);
+const changeKindSchema = z.enum([
+    "added",
+    "removed",
+    "changed",
+    "unknown",
+    "contradiction",
 ]);
-const changeKindSchema = z.enum(["added", "removed", "changed", "unknown"]);
 const comparisonDimensionSchema = z.enum([
     "content",
     "kind",
@@ -22,6 +29,7 @@ const comparisonDimensionSchema = z.enum([
     "relations",
     "metadata",
     "availability",
+    "integrity",
 ]);
 /** Strict Evidence-backed input for deterministic artifact comparison. */
 export const artifactComparisonInputSchema = z.object({
@@ -68,6 +76,7 @@ export const artifactComparisonResultSchema = z.object({
         removed: z.number().int().min(0),
         changed: z.number().int().min(0),
         unknown: z.number().int().min(0),
+        contradiction: z.number().int().min(0).default(0),
     }),
     changes: z.object({
         items: z.array(artifactChangeSchema).max(500),
@@ -84,8 +93,8 @@ export const compareArtifacts = (leftEvidence, rightEvidence, offset, limit) =>
     const right = parseArtifactInventoryEvidence(rightEvidence);
     const leftComplete = left.inventory.complete;
     const rightComplete = right.inventory.complete;
-    const leftCovered = leftComplete && left.inventory.limitations.length === 0;
-    const rightCovered = rightComplete && right.inventory.limitations.length === 0;
+    const leftCovered = leftComplete && !hasCoverageLimitation(left.inventory.limitations);
+    const rightCovered = rightComplete && !hasCoverageLimitation(right.inventory.limitations);
     const limitations = [
         ...left.inventory.limitations.map((item) => `Left: ${item}`),
         ...right.inventory.limitations.map((item) => `Right: ${item}`),
@@ -101,13 +110,15 @@ export const compareArtifacts = (leftEvidence, rightEvidence, offset, limit) =>
     return artifactComparisonResultSchema.parse({
         status: !leftComplete || !rightComplete
             ? "truncated"
-            : !leftCovered || !rightCovered
-                ? "unknown"
-                : changes.some(({ classification }) => classification === "unknown")
+            : changes.some(({ classification }) => classification === "contradiction")
+                ? "contradiction"
+                : !leftCovered || !rightCovered
                     ? "unknown"
-                    : changes.length === 0
-                        ? "unchanged"
-                        : "changed",
+                    : changes.some(({ classification }) => classification === "unknown")
+                        ? "unknown"
+                        : changes.length === 0
+                            ? "unchanged"
+                            : "changed",
         left_manifest_id: left.inventory.manifest.manifest_id,
         right_manifest_id: right.inventory.manifest.manifest_id,
         summary,
@@ -172,6 +183,13 @@ const classifyPath = (input) => {
             classification: input.complete ? "removed" : "unknown",
             dimensions: [input.complete ? "content" : "availability"],
         };
+    if (input.leftOccurrence.hash_status === "mismatched" ||
+        input.rightOccurrence.hash_status === "mismatched")
+        return {
+            ...base,
+            classification: "contradiction",
+            dimensions: ["integrity"],
+        };
     if (input.leftOccurrence.hash_status !== "verified" ||
         input.rightOccurrence.hash_status !== "verified" ||
         input.leftNode === undefined ||
@@ -253,13 +271,20 @@ const relationsByPath = (inventory) => {
     return output;
 };
 const summarize = (left, right, changes, covered) => {
-    const counts = { added: 0, removed: 0, changed: 0, unknown: 0 };
+    const counts = {
+        added: 0,
+        removed: 0,
+        changed: 0,
+        unknown: 0,
+        contradiction: 0,
+    };
     for (const change of changes)
         counts[change.classification] += 1;
     return {
         unchanged: covered
             ? Math.max(0, Math.min(left.occurrences.length, right.occurrences.length) -
                 counts.changed -
+                counts.contradiction -
                 counts.unknown)
             : 0,
         ...counts,
@@ -268,6 +293,8 @@ const summarize = (left, right, changes, covered) => {
             : Math.max(counts.unknown, Math.max(left.manifest.occurrence_count, right.manifest.occurrence_count) -
                 counts.added -
                 counts.removed -
-                counts.changed),
+                counts.changed -
+                counts.contradiction),
     };
 };
+const hasCoverageLimitation = (limitations) => limitations.some((limitation) => !/integrity contradiction\(s\) were recorded/u.test(limitation));

package/dist/domain/artifactGraph.js

@@ -5,6 +5,7 @@ const occurrenceIdSchema = z.string().regex(/^occ_[a-f0-9]{64}$/u);
 const edgeIdSchema = z.string().regex(/^edge_[a-f0-9]{64}$/u);
 const manifestIdSchema = z.string().regex(/^agm_[a-f0-9]{64}$/u);
 const extractionIdSchema = z.string().regex(/^aex_[a-f0-9]{64}$/u);
+const contradictionIdSchema = z.string().regex(/^ic_[a-f0-9]{64}$/u);
 const boundedRelativePathSchema = z
     .string()
     .min(1)
@@ -106,10 +107,29 @@ const artifactOccurrenceSchema = z.object({
         .nullable(),
     executable: z.boolean(),
     encrypted: z.boolean(),
-    hash_status: z.enum(["verified", "not-hashed-limit", "unavailable"]),
+    hash_status: z.enum([
+        "verified",
+        "mismatched",
+        "not-hashed-limit",
+        "unavailable",
+    ]),
     source_location: artifactByteRangeSchema.nullable(),
     limitations: z.array(z.string()),
 });
+/** Observed bytes that contradict a container's declared integrity identity. */
+const integrityContradictionSchema = z.object({
+    contradiction_id: contradictionIdSchema,
+    occurrence_id: occurrenceIdSchema,
+    parent_artifact_id: artifactIdSchema,
+    logical_path: boundedRelativePathSchema,
+    declared_sha256: sha256Schema,
+    observed_sha256: sha256Schema,
+    entry_kind: z.enum(["file", "slice"]),
+    unpacked: z.boolean(),
+    trust: z.literal("observed-untrusted"),
+    provenance: z.literal("container-integrity-metadata-versus-observed-bytes"),
+    limitations: z.array(z.string()).min(1),
+});
 /** Parent-child derivation relation between two content-addressed artifacts. */
 const artifactEdgeSchema = z.object({
     edge_id: edgeIdSchema,
@@ -157,6 +177,10 @@ export const artifactInventoryResultSchema = z.object({
     edges: artifactPageSchema(artifactEdgeSchema),
     limits: artifactTraversalLimitsSchema,
     provenance: z.array(artifactCommandSchema).max(256),
+    integrity_contradictions: z
+        .array(integrityContradictionSchema)
+        .max(100)
+        .default([]),
     limitations: z.array(z.string()),
 });
 /** One safely materialized artifact beneath caller-approved output root. */

package/dist/domain/artifactInventoryEvidence.js

@@ -39,6 +39,9 @@ const assembleInventorySet = (pages) => {
     for (const page of pages) {
         if (canonicalJson(page.inventory.manifest) !== manifestJson)
             throw new TypeError("Artifact inventory pages do not share one manifest");
+        if (canonicalJson(page.inventory.integrity_contradictions) !==
+            canonicalJson(first.inventory.integrity_contradictions))
+            throw new TypeError("Artifact inventory pages do not share integrity contradictions");
         for (const node of page.inventory.nodes.items)
             mergeExact(nodes, node.artifact_id, node, "node");
         for (const occurrence of page.inventory.occurrences.items) {
@@ -66,6 +69,7 @@ const orderedInventory = (first, pages, values) => {
         nodes,
         occurrences,
         edges,
+        integrityContradictions: first.integrity_contradictions,
         limitations: [
             ...new Set(pages.flatMap(({ inventory }) => inventory.limitations)),
         ].sort((left, right) => left.localeCompare(right)),
@@ -84,10 +88,24 @@ const validateCompleteInventory = (inventory) => {
         validateOccurrence(occurrence, inventory, nodeIds, occurrenceIds);
     for (const edge of inventory.edges)
         validateEdge(edge, nodeIds, occurrenceIds);
+    for (const contradiction of inventory.integrityContradictions) {
+        if (!nodeIds.has(contradiction.parent_artifact_id) ||
+            !occurrenceIds.has(contradiction.occurrence_id))
+            throw new TypeError("Integrity contradiction references a missing graph member");
+        const expectedId = `ic_${digestCanonical({
+            root_artifact_id: inventory.manifest.root_artifact_id,
+            logical_path: contradiction.logical_path,
+            declared_sha256: contradiction.declared_sha256,
+            observed_sha256: contradiction.observed_sha256,
+        })}`;
+        if (contradiction.contradiction_id !== expectedId)
+            throw new TypeError("Integrity contradiction ID does not match its identity");
+    }
     const graphSha256 = digestCanonical({
         nodes: inventory.nodes,
         occurrences: inventory.occurrences,
         edges: inventory.edges,
+        integrity_contradictions: inventory.integrityContradictions,
     });
     if (graphSha256 !== inventory.manifest.graph_sha256)
         throw new TypeError("Artifact graph commitment does not match its members");

package/dist/domain/changedBehavior.js

@@ -3,13 +3,24 @@ import { artifactComparisonResultSchema } from "./artifactComparison.js";
 import { evidenceSchema, parseEvidence } from "./evidence.js";
 import { functionComparisonResultSchema } from "./functionComparison.js";
 import { comparisonStatusSchema, processCaptureComparisonSchema, } from "./processCapture.js";
+import { crossVersionInvestigationInputSchema, investigationRunSummarySchema, } from "./investigationWorkspace.js";
 const evidenceIdSchema = z.string().regex(/^ev_[a-f0-9]{64}$/u);
 /** Strict bounded input for aggregating existing comparison Evidence. */
-export const changedBehaviorInputSchema = z.object({
-    comparisons: z.array(evidenceSchema).min(1).max(100),
+export const changedBehaviorInputSchema = z
+    .object({
+    comparisons: z.array(evidenceSchema).max(100).default([]),
+    investigation_run: crossVersionInvestigationInputSchema.optional(),
     offset: z.number().int().min(0).default(0),
     limit: z.number().int().min(1).max(100).default(100),
     unknown_registry_approved: z.literal(true).optional(),
+})
+    .superRefine((input, context) => {
+    if (input.comparisons.length > 0 ===
+        (input.investigation_run !== undefined))
+        context.addIssue({
+            code: "custom",
+            message: "Supply either existing comparisons or one investigation_run, but not both",
+        });
 });
 const findingSchema = z.object({
     scope: z.enum(["runtime", "protocol", "resource", "static_candidate"]),
@@ -48,6 +59,7 @@ export const changedBehaviorResultSchema = z.object({
     }),
     evidence_links: z.array(evidenceIdSchema).min(3).max(20_100),
     limitations: z.array(z.string()),
+    investigation_run: investigationRunSummarySchema.optional(),
 });
 const EXPECTED_PROVIDERS = {
     compare_process_captures: {
@@ -113,6 +125,7 @@ export const findChangedBehavior = (comparisonsInput, offset, limit) => {
             ...(runtimeStatuses.length === 0
                 ? ["No process comparison Evidence was supplied."]
                 : []),
+            ...evidence.flatMap(artifactPaginationLimitations),
         ]),
     });
 };
@@ -169,10 +182,8 @@ const parseResult = (evidence) => {
         return;
     }
     const result = artifactComparisonResultSchema.parse(evidence.normalized_result);
-    if (result.changes.offset !== 0 ||
-        result.changes.next_offset !== null ||
-        result.changes.items.length !== result.changes.total)
-        throw new TypeError("Changed-behavior analysis requires complete artifact comparison pagination");
+    if (result.changes.offset !== 0)
+        throw new TypeError("Changed-behavior analysis requires artifact comparison pagination from offset zero");
     assertNestedLinks(evidence, result.changes.items.flatMap(({ evidence_links: links }) => links));
 };
 const assertNestedLinks = (evidence, nestedLinks) => {
@@ -236,13 +247,17 @@ const artifactFindings = (evidence) => {
         dimension: `artifact:${change.logical_path}`,
         scope: "static_candidate",
         status: change.classification,
-        classification: change.classification === "unknown"
-            ? "unresolved_branch"
-            : "derived_relationship",
+        classification: change.classification === "contradiction"
+            ? "contradiction"
+            : change.classification === "unknown"
+                ? "unresolved_branch"
+                : "derived_relationship",
         limitations: result.limitations,
         links: change.evidence_links,
     }));
-    return (result.status === "unknown" || result.status === "truncated") &&
+    return (result.status === "unknown" ||
+        result.status === "truncated" ||
+        result.changes.next_offset !== null) &&
         !changes.some(({ classification }) => classification === "unresolved_branch")
         ? [
             ...changes,
@@ -257,6 +272,16 @@ const artifactFindings = (evidence) => {
         ]
         : changes;
 };
+const artifactPaginationLimitations = (evidence) => {
+    if (evidence.operation !== "compare_artifacts")
+        return [];
+    const result = artifactComparisonResultSchema.parse(evidence.normalized_result);
+    return result.changes.next_offset === null
+        ? []
+        : [
+            `Artifact comparison reports ${String(result.changes.items.length)} of ${String(result.changes.total)} changes.`,
+        ];
+};
 const makeFinding = (input) => findingSchema.parse({
     scope: input.scope,
     dimension: input.dimension,