rea-agents 0.2.1 → 0.4.0

package/dist/domain/artifactGraph.js

@@ -0,0 +1,194 @@
+import { z } from "zod";
+const sha256Schema = z.string().regex(/^[a-f0-9]{64}$/u);
+const artifactIdSchema = z.string().regex(/^art_[a-f0-9]{64}$/u);
+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 boundedRelativePathSchema = z
+    .string()
+    .min(1)
+    .max(4_096)
+    .refine((path) => !path.startsWith("/") &&
+    !path.includes("\\") &&
+    path.split("/").every((part) => part !== "" && part !== ".."), "Expected a normalized relative POSIX path without traversal");
+/** Closed artifact categories used to traverse application containers. */
+const artifactKindSchema = z.enum([
+    "container",
+    "executable",
+    "dynamic-library",
+    "framework",
+    "native-addon",
+    "javascript",
+    "source-map",
+    "plist",
+    "entitlements",
+    "resource",
+    "universal-slice",
+    "package-metadata",
+    "unknown",
+]);
+/** Recognized storage or application formats; unknown bytes remain explicit. */
+const artifactFormatSchema = z.enum([
+    "dmg",
+    "zip",
+    "pkg",
+    "asar",
+    "javascript-bundle",
+    "source-map",
+    "mach-o-universal",
+    "mach-o",
+    "elf",
+    "pe",
+    "hopper",
+    "ipa",
+    "apk",
+    "plist",
+    "entitlements",
+    "directory",
+    "file",
+    "unknown",
+]);
+/** Exact bounded policy applied while discovering or extracting artifacts. */
+const artifactTraversalLimitsSchema = z.object({
+    max_entries: z.number().int().min(1).max(1_000_000),
+    max_total_bytes: z.number().int().min(1).max(Number.MAX_SAFE_INTEGER),
+    max_entry_bytes: z.number().int().min(1).max(Number.MAX_SAFE_INTEGER),
+    max_compression_ratio: z.number().min(1).max(100_000),
+    max_depth: z.number().int().min(0).max(100),
+    max_path_bytes: z.number().int().min(1).max(65_535),
+});
+/** File byte interval for an artifact derived without writing it to disk. */
+const artifactByteRangeSchema = z.object({
+    offset: z.number().int().min(0),
+    length: z.number().int().min(0),
+});
+/** Bounded external command provenance, including observable side effects. */
+const artifactCommandSchema = z.object({
+    tool: z.string().min(1),
+    arguments: z.array(z.string().max(4_096)).max(1_024),
+    tool_version: z.string().nullable(),
+    executable_sha256: sha256Schema.nullable(),
+    exit_code: z.number().int().nullable(),
+    effects: z.array(z.enum(["read", "write", "mount"])).max(3),
+});
+/** One content-addressed application artifact in deterministic manifest order. */
+const artifactNodeSchema = z.object({
+    artifact_id: artifactIdSchema,
+    kind: artifactKindSchema,
+    format: artifactFormatSchema,
+    sha256: sha256Schema,
+    size: z.number().int().min(0).max(Number.MAX_SAFE_INTEGER),
+    media_type: z.string().min(1).nullable(),
+    architecture: z.string().min(1).nullable(),
+    executable: z.boolean(),
+    content_state: z.enum(["materialized", "embedded", "virtual"]),
+    limitations: z.array(z.string()),
+});
+/** One path or virtual location where an artifact occurs in its parent. */
+const artifactOccurrenceSchema = z.object({
+    occurrence_id: occurrenceIdSchema,
+    artifact_id: artifactIdSchema.nullable(),
+    parent_occurrence_id: occurrenceIdSchema.nullable(),
+    logical_path: boundedRelativePathSchema,
+    entry_kind: z.enum(["file", "directory", "symlink", "slice"]),
+    declared_size: z
+        .number()
+        .int()
+        .min(0)
+        .max(Number.MAX_SAFE_INTEGER)
+        .nullable(),
+    compressed_size: z
+        .number()
+        .int()
+        .min(0)
+        .max(Number.MAX_SAFE_INTEGER)
+        .nullable(),
+    executable: z.boolean(),
+    encrypted: z.boolean(),
+    hash_status: z.enum(["verified", "not-hashed-limit", "unavailable"]),
+    source_location: artifactByteRangeSchema.nullable(),
+    limitations: z.array(z.string()),
+});
+/** Parent-child derivation relation between two content-addressed artifacts. */
+const artifactEdgeSchema = z.object({
+    edge_id: edgeIdSchema,
+    ordinal: z.number().int().min(0),
+    parent_artifact_id: artifactIdSchema,
+    child_artifact_id: artifactIdSchema,
+    relation: z.enum([
+        "contains",
+        "extracts",
+        "slice-of",
+        "embeds",
+        "loads",
+        "maps-source",
+        "derived-from",
+    ]),
+    occurrence_id: occurrenceIdSchema,
+    logical_path: boundedRelativePathSchema.nullable(),
+    producer: artifactCommandSchema.nullable(),
+});
+/** Stable cryptographic commitment and counts for a complete artifact graph. */
+const artifactGraphManifestSchema = z.object({
+    schema_version: z.literal(1),
+    manifest_id: manifestIdSchema,
+    root_artifact_id: artifactIdSchema,
+    root_sha256: sha256Schema,
+    root_format: artifactFormatSchema,
+    graph_sha256: sha256Schema,
+    node_count: z.number().int().min(1),
+    occurrence_count: z.number().int().min(1),
+    edge_count: z.number().int().min(0),
+});
+/** Independently bounded offset page used for deterministic graph traversal. */
+const artifactPageSchema = (item) => z.object({
+    items: z.array(item).max(500),
+    offset: z.number().int().min(0),
+    limit: z.number().int().min(1).max(500),
+    total: z.number().int().min(0),
+    next_offset: z.number().int().min(0).nullable(),
+});
+/** Inventory observation containing stable manifest identity and bounded pages. */
+export const artifactInventoryResultSchema = z.object({
+    manifest: artifactGraphManifestSchema,
+    nodes: artifactPageSchema(artifactNodeSchema),
+    occurrences: artifactPageSchema(artifactOccurrenceSchema),
+    edges: artifactPageSchema(artifactEdgeSchema),
+    limits: artifactTraversalLimitsSchema,
+    provenance: z.array(artifactCommandSchema).max(256),
+    limitations: z.array(z.string()),
+});
+/** One safely materialized artifact beneath caller-approved output root. */
+const extractedArtifactSchema = z.object({
+    artifact_id: artifactIdSchema,
+    relative_path: boundedRelativePathSchema,
+    sha256: sha256Schema,
+    bytes_written: z.number().int().min(0).max(Number.MAX_SAFE_INTEGER),
+    created: z.boolean(),
+});
+/** Path-independent commitment to one selected extraction operation. */
+const artifactExtractionManifestSchema = z.object({
+    schema_version: z.literal(1),
+    extraction_id: extractionIdSchema,
+    source_manifest_id: manifestIdSchema,
+    selected_occurrence_ids: z.array(occurrenceIdSchema).min(1).max(500),
+    files_sha256: sha256Schema,
+    output_root_alias: z.literal("$OUTPUT_ROOT"),
+});
+/** Safe extraction observation with containment and cleanup verification. */
+export const artifactExtractionResultSchema = z.object({
+    manifest: artifactGraphManifestSchema,
+    extraction_manifest: artifactExtractionManifestSchema,
+    output_root: z.string().min(1),
+    artifacts: artifactPageSchema(extractedArtifactSchema),
+    containment_verified: z.boolean(),
+    cleanup: z.object({
+        attempted: z.boolean(),
+        verified: z.boolean(),
+        residual_paths: z.array(boundedRelativePathSchema).max(500),
+    }),
+    limits: artifactTraversalLimitsSchema,
+    provenance: z.array(artifactCommandSchema).max(256),
+    limitations: z.array(z.string()),
+});

package/dist/domain/artifactInventoryEvidence.js

@@ -0,0 +1,150 @@
+import { createHash } from "node:crypto";
+import canonicalize from "canonicalize";
+import { artifactInventoryResultSchema, } from "./artifactGraph.js";
+import { parseEvidence } from "./evidence.js";
+/** Parse, merge, and verify a bounded set of inventory Evidence pages. */
+export const parseArtifactInventoryEvidence = (input) => assembleInventorySet((Array.isArray(input) ? input : [input]).map((value) => {
+    const evidence = parseEvidence(value);
+    if (evidence.operation !== "inventory_artifact")
+        throw new TypeError("Artifact comparison requires inventory_artifact Evidence");
+    const inventory = artifactInventoryResultSchema.parse(evidence.normalized_result);
+    if (evidence.subject === null ||
+        evidence.subject.digest.sha256 !== inventory.manifest.root_sha256 ||
+        evidence.subject.format !== inventory.manifest.root_format)
+        throw new TypeError("Artifact inventory Evidence subject does not match its root digest");
+    validateInventoryPage(inventory);
+    return { evidence, inventory };
+}));
+const validateInventoryPage = (inventory) => {
+    assertUnique(inventory.nodes.items.map(({ artifact_id: id }) => id), "node ID");
+    assertUnique(inventory.occurrences.items.map(({ occurrence_id: id }) => id), "occurrence ID");
+    assertUnique(inventory.occurrences.items.map(({ logical_path: path }) => path), "logical path");
+    assertUnique(inventory.edges.items.map(({ edge_id: id }) => id), "edge ID");
+    for (const node of inventory.nodes.items)
+        if (node.artifact_id !==
+            `art_${digestCanonical({ schema_version: 1, sha256: node.sha256 })}`)
+            throw new TypeError("Artifact node ID is not content-addressed");
+};
+const assembleInventorySet = (pages) => {
+    if (pages.length === 0 || pages.length > 100)
+        throw new TypeError("Artifact comparison requires 1 to 100 Evidence pages");
+    const first = pages[0];
+    if (first === undefined)
+        throw new TypeError("Artifact comparison requires Evidence pages");
+    const manifestJson = canonicalJson(first.inventory.manifest);
+    const nodes = new Map();
+    const occurrences = new Map();
+    const paths = new Map();
+    const edges = new Map();
+    for (const page of pages) {
+        if (canonicalJson(page.inventory.manifest) !== manifestJson)
+            throw new TypeError("Artifact inventory pages do not share one manifest");
+        for (const node of page.inventory.nodes.items)
+            mergeExact(nodes, node.artifact_id, node, "node");
+        for (const occurrence of page.inventory.occurrences.items) {
+            mergeExact(occurrences, occurrence.occurrence_id, occurrence, "occurrence");
+            mergeExact(paths, occurrence.logical_path, occurrence, "logical path");
+        }
+        for (const edge of page.inventory.edges.items)
+            mergeExact(edges, edge.edge_id, edge, "edge");
+    }
+    const inventory = orderedInventory(first.inventory, pages, {
+        nodes,
+        occurrences,
+        edges,
+    });
+    if (inventory.complete)
+        validateCompleteInventory(inventory);
+    return { evidence: pages.map(({ evidence }) => evidence), inventory };
+};
+const orderedInventory = (first, pages, values) => {
+    const nodes = [...values.nodes.values()].sort((left, right) => left.artifact_id.localeCompare(right.artifact_id));
+    const occurrences = [...values.occurrences.values()].sort((left, right) => left.logical_path.localeCompare(right.logical_path, "en"));
+    const edges = [...values.edges.values()].sort((left, right) => left.edge_id.localeCompare(right.edge_id));
+    return {
+        manifest: first.manifest,
+        nodes,
+        occurrences,
+        edges,
+        limitations: [
+            ...new Set(pages.flatMap(({ inventory }) => inventory.limitations)),
+        ].sort((left, right) => left.localeCompare(right)),
+        complete: nodes.length === first.manifest.node_count &&
+            occurrences.length === first.manifest.occurrence_count &&
+            edges.length === first.manifest.edge_count,
+    };
+};
+const validateCompleteInventory = (inventory) => {
+    const nodeIds = new Set(inventory.nodes.map(({ artifact_id: id }) => id));
+    const occurrenceIds = new Set(inventory.occurrences.map(({ occurrence_id: id }) => id));
+    const rootNode = inventory.nodes.find(({ artifact_id: id }) => id === inventory.manifest.root_artifact_id);
+    if (rootNode?.sha256 !== inventory.manifest.root_sha256)
+        throw new TypeError("Artifact root node does not match its manifest digest");
+    for (const occurrence of inventory.occurrences)
+        validateOccurrence(occurrence, inventory, nodeIds, occurrenceIds);
+    for (const edge of inventory.edges)
+        validateEdge(edge, nodeIds, occurrenceIds);
+    const graphSha256 = digestCanonical({
+        nodes: inventory.nodes,
+        occurrences: inventory.occurrences,
+        edges: inventory.edges,
+    });
+    if (graphSha256 !== inventory.manifest.graph_sha256)
+        throw new TypeError("Artifact graph commitment does not match its members");
+    const manifestId = `agm_${digestCanonical({
+        schema_version: 1,
+        root_artifact_id: inventory.manifest.root_artifact_id,
+        graph_sha256: graphSha256,
+    })}`;
+    if (manifestId !== inventory.manifest.manifest_id)
+        throw new TypeError("Artifact manifest ID does not match its commitment");
+};
+const validateOccurrence = (occurrence, inventory, nodeIds, occurrenceIds) => {
+    if (occurrence.artifact_id !== null && !nodeIds.has(occurrence.artifact_id))
+        throw new TypeError("Artifact occurrence references a missing node");
+    if (occurrence.parent_occurrence_id !== null &&
+        !occurrenceIds.has(occurrence.parent_occurrence_id))
+        throw new TypeError("Artifact occurrence references a missing parent");
+    const expectedId = occurrence.logical_path === "."
+        ? `occ_${digestCanonical({ root: inventory.manifest.root_artifact_id })}`
+        : `occ_${digestCanonical({
+            root_artifact_id: inventory.manifest.root_artifact_id,
+            logical_path: occurrence.logical_path,
+            entry_kind: occurrence.entry_kind,
+        })}`;
+    if (occurrence.occurrence_id !== expectedId)
+        throw new TypeError("Artifact occurrence ID does not match its identity");
+};
+const validateEdge = (edge, nodeIds, occurrenceIds) => {
+    if (!nodeIds.has(edge.parent_artifact_id) ||
+        !nodeIds.has(edge.child_artifact_id) ||
+        !occurrenceIds.has(edge.occurrence_id))
+        throw new TypeError("Artifact edge references a missing graph member");
+    const semantic = {
+        parent_artifact_id: edge.parent_artifact_id,
+        child_artifact_id: edge.child_artifact_id,
+        relation: edge.relation,
+        occurrence_id: edge.occurrence_id,
+        logical_path: edge.logical_path,
+    };
+    if (edge.edge_id !== `edge_${digestCanonical(semantic)}`)
+        throw new TypeError("Artifact edge ID does not match its identity");
+};
+const mergeExact = (output, key, value, label) => {
+    const previous = output.get(key);
+    if (previous !== undefined &&
+        canonicalJson(previous) !== canonicalJson(value))
+        throw new TypeError(`Artifact inventory has conflicting ${label} pages`);
+    output.set(key, value);
+};
+const assertUnique = (values, label) => {
+    if (new Set(values).size !== values.length)
+        throw new TypeError(`Artifact inventory contains a duplicate ${label}`);
+};
+const digestCanonical = (value) => createHash("sha256").update(canonicalJson(value)).digest("hex");
+const canonicalJson = (value) => {
+    const encoded = canonicalize(value);
+    if (encoded === undefined)
+        throw new TypeError("Artifact inventory could not canonicalize graph data");
+    return encoded;
+};

package/dist/domain/binaryTarget.js

@@ -28,6 +28,7 @@ export const parseBinaryTarget = async (input, cwd = process.cwd(), hostArchitec
             (targetKind === undefined && path.toLowerCase().endsWith(".hop")))
             return ok({
                 path,
+                sourcePath: canonical,
                 sha256: await sha256File(path),
                 kind: "database",
                 format: "hopper",
@@ -36,6 +37,16 @@ export const parseBinaryTarget = async (input, cwd = process.cwd(), hostArchitec
         const handle = await open(path, "r");
         let detected;
         try {
+            const artifactFormat = await detectArtifactFormat(path, handle);
+            if (artifactFormat !== undefined)
+                return ok({
+                    path,
+                    sourcePath: canonical,
+                    sha256: await sha256File(path),
+                    kind: isArchiveFormat(artifactFormat) ? "archive" : "artifact",
+                    format: artifactFormat,
+                    loaderArgs: [],
+                });
             detected = await readExecutableMetadata(handle, hostArchitecture);
         }
         finally {
@@ -45,6 +56,7 @@ export const parseBinaryTarget = async (input, cwd = process.cwd(), hostArchitec
             return err(new BinaryTargetError(path, detected.error));
         return ok({
             path,
+            sourcePath: canonical,
             sha256: await sha256File(path),
             kind: "executable",
             ...detected.value,
@@ -54,6 +66,49 @@ export const parseBinaryTarget = async (input, cwd = process.cwd(), hostArchitec
         return err(new BinaryTargetError(candidate, "path is not readable", { cause }));
     }
 };
+const detectArtifactFormat = async (path, handle) => {
+    const lower = path.toLowerCase();
+    const magic = Buffer.alloc(8);
+    const observed = await handle.read(magic, 0, magic.length, 0);
+    if (observed.bytesRead >= 4 &&
+        magic[0] === 0x50 &&
+        magic[1] === 0x4b &&
+        [0x03, 0x05, 0x07].includes(magic[2] ?? -1) &&
+        [0x04, 0x06, 0x08].includes(magic[3] ?? -1)) {
+        return lower.endsWith(".ipa")
+            ? "ipa"
+            : lower.endsWith(".apk")
+                ? "apk"
+                : "zip";
+    }
+    const named = namedArtifactFormat(lower);
+    if (named !== undefined)
+        return named;
+    if (lower.endsWith(".pkg") &&
+        observed.bytesRead >= 4 &&
+        magic.subarray(0, 4).toString("ascii") === "xar!")
+        return "pkg";
+    if (lower.endsWith(".dmg")) {
+        const size = (await handle.stat()).size;
+        if (size >= 512) {
+            const trailer = Buffer.alloc(4);
+            const read = await handle.read(trailer, 0, trailer.length, size - 512);
+            if (read.bytesRead === 4 && trailer.toString("ascii") === "koly")
+                return "dmg";
+        }
+    }
+    return undefined;
+};
+const namedArtifactFormat = (lowerPath) => {
+    if (lowerPath.endsWith(".asar"))
+        return "asar";
+    if (lowerPath.endsWith(".plist"))
+        return "plist";
+    if (lowerPath.endsWith(".map"))
+        return "source-map";
+    return /\.(?:m?js|cjs)$/u.test(lowerPath) ? "javascript" : undefined;
+};
+const isArchiveFormat = (format) => ["zip", "ipa", "apk", "asar", "dmg", "pkg"].includes(format);
 const sha256File = async (path) => {
     const hash = createHash("sha256");
     for await (const chunk of createReadStream(path))

package/dist/domain/bundleComparison.js

@@ -0,0 +1,266 @@
+import { createHash } from "node:crypto";
+import { z } from "zod";
+import { evidenceBundleSchema, parseEvidenceBundle, serializeEvidenceBundle, } from "./evidenceBundle.js";
+const evidenceIdSchema = z.string().regex(/^ev_[a-f0-9]{64}$/u);
+const digestSchema = z.string().regex(/^[a-f0-9]{64}$/u);
+const classificationSchema = z.enum([
+    "added",
+    "removed",
+    "changed",
+    "unknown",
+    "history_advanced",
+    "history_diverged",
+]);
+/** Strict bounded input for canonical Evidence bundle comparison. */
+export const bundleComparisonInputSchema = z.object({
+    left: evidenceBundleSchema,
+    right: evidenceBundleSchema,
+    record_pairs: z
+        .array(z.object({
+        left_evidence_id: evidenceIdSchema,
+        right_evidence_id: evidenceIdSchema,
+    }))
+        .max(500)
+        .default([]),
+    offset: z.number().int().min(0).default(0),
+    limit: z.number().int().min(1).max(500).default(100),
+});
+const bundleChangeSchema = z.object({
+    entity: z.enum(["evidence", "residual_unknown"]),
+    key: z.string().min(1),
+    classification: classificationSchema,
+    conclusion_kind: z.enum([
+        "observed_change",
+        "contradiction",
+        "unresolved_branch",
+    ]),
+    left_evidence_ids: z.array(evidenceIdSchema),
+    right_evidence_ids: z.array(evidenceIdSchema),
+    left_digest: digestSchema.nullable(),
+    right_digest: digestSchema.nullable(),
+    limitations: z.array(z.string()),
+});
+/** Deterministic classified delta between two canonical Evidence bundles. */
+export const bundleComparisonResultSchema = z.object({
+    status: z.enum(["unchanged", "changed", "unknown"]),
+    left_bundle_sha256: digestSchema,
+    right_bundle_sha256: digestSchema,
+    summary: z.object({
+        records_unchanged: z.number().int().min(0),
+        records_added: z.number().int().min(0),
+        records_removed: z.number().int().min(0),
+        records_changed: z.number().int().min(0),
+        unknowns_unchanged: z.number().int().min(0),
+        unknowns_added: z.number().int().min(0),
+        unknowns_removed: z.number().int().min(0),
+        unknowns_advanced: z.number().int().min(0),
+        unknowns_diverged: z.number().int().min(0),
+        unresolved: z.number().int().min(0),
+    }),
+    changes: z.object({
+        items: z.array(bundleChangeSchema).max(500),
+        offset: z.number().int().min(0),
+        limit: z.number().int().min(1).max(500),
+        total: z.number().int().min(0),
+        next_offset: z.number().int().min(0).nullable(),
+    }),
+    limitations: z.array(z.string()),
+});
+const MAX_ENTITIES = 100_000;
+/** Compare canonical bundle membership and only explicitly paired observations. */
+export const compareBundles = (...[leftInput, rightInput, recordPairs, offset, limit]) => {
+    const left = parseEvidenceBundle(leftInput);
+    const right = parseEvidenceBundle(rightInput);
+    enforceBounds(left, right);
+    const leftDigest = bundleDigest(left);
+    const rightDigest = bundleDigest(right);
+    const recordResult = compareRecords(left, right, recordPairs);
+    const unknownResult = compareUnknowns(left, right);
+    const changes = [...recordResult.changes, ...unknownResult.changes].sort(compareChanges);
+    const page = changes.slice(offset, offset + limit);
+    const unresolved = changes.filter(({ conclusion_kind: kind }) => kind !== "observed_change").length;
+    return bundleComparisonResultSchema.parse({
+        status: leftDigest === rightDigest && changes.length === 0
+            ? "unchanged"
+            : unresolved > 0
+                ? "unknown"
+                : "changed",
+        left_bundle_sha256: leftDigest,
+        right_bundle_sha256: rightDigest,
+        summary: {
+            ...recordResult.summary,
+            ...unknownResult.summary,
+            unresolved,
+        },
+        changes: {
+            items: page,
+            offset,
+            limit,
+            total: changes.length,
+            next_offset: offset + page.length < changes.length ? offset + page.length : null,
+        },
+        limitations: changes.some(({ limitations }) => limitations.length > 0)
+            ? [
+                "One-sided membership proves only bundle inclusion or omission, not behavioral absence.",
+            ]
+            : [],
+    });
+};
+const compareRecords = (left, right, pairs) => {
+    const leftIds = new Set(left.records.map(({ evidence_id: id }) => id));
+    const rightIds = new Set(right.records.map(({ evidence_id: id }) => id));
+    const pairedLeft = new Set();
+    const pairedRight = new Set();
+    const changes = [];
+    let changed = 0;
+    for (const pair of pairs) {
+        if (!leftIds.has(pair.left_evidence_id))
+            throw new TypeError(`Explicit pair references missing left evidence ${pair.left_evidence_id}`);
+        if (!rightIds.has(pair.right_evidence_id))
+            throw new TypeError(`Explicit pair references missing right evidence ${pair.right_evidence_id}`);
+        if (pairedLeft.has(pair.left_evidence_id) ||
+            pairedRight.has(pair.right_evidence_id))
+            throw new TypeError("Explicit evidence pairs must be one-to-one");
+        pairedLeft.add(pair.left_evidence_id);
+        pairedRight.add(pair.right_evidence_id);
+        if (pair.left_evidence_id === pair.right_evidence_id)
+            continue;
+        changed += 1;
+        changes.push({
+            entity: "evidence",
+            key: `pair:${pair.left_evidence_id}:${pair.right_evidence_id}`,
+            classification: "changed",
+            conclusion_kind: "observed_change",
+            left_evidence_ids: [pair.left_evidence_id],
+            right_evidence_ids: [pair.right_evidence_id],
+            left_digest: pair.left_evidence_id.slice(3),
+            right_digest: pair.right_evidence_id.slice(3),
+            limitations: [],
+        });
+    }
+    const common = [...leftIds].filter((id) => rightIds.has(id) && !pairedLeft.has(id) && !pairedRight.has(id));
+    const removed = [...leftIds].filter((id) => !rightIds.has(id) && !pairedLeft.has(id));
+    const added = [...rightIds].filter((id) => !leftIds.has(id) && !pairedRight.has(id));
+    for (const [classification, ids, side] of [
+        ["removed", removed, "left"],
+        ["added", added, "right"],
+    ])
+        for (const id of ids)
+            changes.push({
+                entity: "evidence",
+                key: id,
+                classification,
+                conclusion_kind: "observed_change",
+                left_evidence_ids: side === "left" ? [id] : [],
+                right_evidence_ids: side === "right" ? [id] : [],
+                left_digest: side === "left" ? id.slice(3) : null,
+                right_digest: side === "right" ? id.slice(3) : null,
+                limitations: [
+                    "One-sided membership does not establish behavioral absence.",
+                ],
+            });
+    return {
+        changes,
+        summary: {
+            records_unchanged: common.length + pairs.length - changed,
+            records_added: added.length,
+            records_removed: removed.length,
+            records_changed: changed,
+        },
+    };
+};
+const compareUnknowns = (left, right) => {
+    const leftHistories = histories(left.unknowns);
+    const rightHistories = histories(right.unknowns);
+    const ids = [...new Set([...leftHistories.keys(), ...rightHistories.keys()])];
+    const changes = [];
+    const summary = {
+        unknowns_unchanged: 0,
+        unknowns_added: 0,
+        unknowns_removed: 0,
+        unknowns_advanced: 0,
+        unknowns_diverged: 0,
+    };
+    for (const id of ids) {
+        const leftHistory = leftHistories.get(id);
+        const rightHistory = rightHistories.get(id);
+        if (leftHistory === undefined || rightHistory === undefined) {
+            const added = leftHistory === undefined;
+            summary[added ? "unknowns_added" : "unknowns_removed"] += 1;
+            changes.push(unknownChange(id, added ? "added" : "removed", leftHistory, rightHistory));
+            continue;
+        }
+        const leftDigests = leftHistory.map(({ revision_digest: digest }) => digest);
+        const rightDigests = rightHistory.map(({ revision_digest: digest }) => digest);
+        if (same(leftDigests, rightDigests)) {
+            summary.unknowns_unchanged += 1;
+            continue;
+        }
+        const advanced = isPrefix(leftDigests, rightDigests) ||
+            isPrefix(rightDigests, leftDigests);
+        summary[advanced ? "unknowns_advanced" : "unknowns_diverged"] += 1;
+        changes.push(unknownChange(id, advanced ? "history_advanced" : "history_diverged", leftHistory, rightHistory));
+    }
+    return { changes, summary };
+};
+const unknownChange = (id, classification, left, right) => ({
+    entity: "residual_unknown",
+    key: id,
+    classification,
+    conclusion_kind: classification === "history_diverged"
+        ? "contradiction"
+        : classification === "history_advanced"
+            ? "observed_change"
+            : "unresolved_branch",
+    left_evidence_ids: historyEvidenceIds(left ?? []),
+    right_evidence_ids: historyEvidenceIds(right ?? []),
+    left_digest: left?.at(-1)?.revision_digest ?? null,
+    right_digest: right?.at(-1)?.revision_digest ?? null,
+    limitations: left === undefined || right === undefined
+        ? ["A missing unknown history does not establish resolution."]
+        : [],
+});
+const histories = (unknowns) => {
+    const output = new Map();
+    for (const unknown of unknowns) {
+        const history = output.get(unknown.unknown_id) ?? [];
+        history.push(unknown);
+        output.set(unknown.unknown_id, history);
+    }
+    return output;
+};
+const historyEvidenceIds = (history) => [
+    ...new Set(history.flatMap((item) => [
+        ...item.supporting_evidence_ids,
+        ...item.contradicting_evidence_ids,
+        ...item.mutation_evidence_ids,
+        ...(item.resolution?.evidence_ids ?? []),
+    ])),
+].sort(ascii);
+const enforceBounds = (left, right) => {
+    const total = left.records.length +
+        right.records.length +
+        left.unknowns.length +
+        right.unknowns.length;
+    if (total > MAX_ENTITIES)
+        throw new TypeError(`Bundle comparison exceeds ${MAX_ENTITIES} entities`);
+};
+const bundleDigest = (bundle) => createHash("sha256").update(serializeEvidenceBundle(bundle)).digest("hex");
+const same = (left, right) => left.length === right.length &&
+    left.every((value, index) => value === right[index]);
+const isPrefix = (shorter, longer) => shorter.length < longer.length &&
+    shorter.every((value, index) => value === longer[index]);
+const ascii = (left, right) => left < right ? -1 : left > right ? 1 : 0;
+const compareChanges = (left, right) => ascii([
+    left.entity,
+    left.key,
+    left.classification,
+    left.left_digest ?? "",
+    left.right_digest ?? "",
+].join("\u0000"), [
+    right.entity,
+    right.key,
+    right.classification,
+    right.left_digest ?? "",
+    right.right_digest ?? "",
+].join("\u0000"));