rea-agents 0.3.0 → 0.5.0

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"));

package/dist/domain/callPath.js

@@ -0,0 +1,346 @@
+import { DirectedGraph } from "graphology";
+import { bidirectional } from "graphology-shortest-path/unweighted.js";
+import { z } from "zod";
+import { evidenceSchema } from "./evidence.js";
+import { parseFunctionEvidence, } from "./functionDossierEvidence.js";
+const addressSchema = z.string().regex(/^0x(?:0|[1-9a-f][0-9a-f]*)$/u);
+const inputAddressSchema = z
+    .string()
+    .regex(/^0[xX][0-9a-fA-F]+$/u)
+    .transform((address) => `0x${BigInt(address).toString(16)}`);
+const evidenceIdSchema = z.string().regex(/^ev_[a-f0-9]{64}$/u);
+const evidenceGroupSchema = z.union([
+    evidenceSchema,
+    z.array(evidenceSchema).min(1).max(100),
+]);
+const MAX_EVIDENCE_PAGES = 2_000;
+const MAX_GRAPH_EDGES = 10_000;
+const MAX_PATH_EXPANSIONS = 100_000;
+/** Strict, bounded input for explicit call-path reconstruction. */
+export const callPathInputSchema = z
+    .object({
+    functions: z.array(evidenceGroupSchema).min(1).max(500),
+    start: z.object({ address: inputAddressSchema }).strict(),
+    goal: z.object({ address: inputAddressSchema }).strict(),
+    max_depth: z.number().int().min(0).max(32).default(8),
+    max_paths: z.number().int().min(1).max(100).default(10),
+    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(({ functions }, context) => {
+    const pages = functions.reduce((total, group) => total + (Array.isArray(group) ? group.length : 1), 0);
+    if (pages > MAX_EVIDENCE_PAGES)
+        context.addIssue({
+            code: "custom",
+            message: `Call-path Evidence exceeds ${MAX_EVIDENCE_PAGES} pages`,
+            path: ["functions"],
+        });
+});
+const citedNodeSchema = z.object({
+    address: addressSchema,
+    name: z.string().nullable(),
+    evidence_links: z.array(evidenceIdSchema).min(1).max(100),
+});
+const citedEdgeSchema = z.object({
+    source: addressSchema,
+    target: addressSchema,
+    evidence_links: z.array(evidenceIdSchema).min(1).max(100),
+});
+const pathSchema = z.object({
+    hops: z.number().int().min(0),
+    nodes: z.array(citedNodeSchema).min(1).max(33),
+    edges: z.array(citedEdgeSchema).max(32),
+    evidence_links: z.array(evidenceIdSchema).min(1).max(3_300),
+});
+/** Evidence-cited, bounded directed call-path result. */
+export const callPathResultSchema = z.object({
+    status: z.enum(["found", "not_found", "unknown", "truncated"]),
+    start: addressSchema,
+    goal: addressSchema,
+    shortest_hops: z.number().int().min(0).nullable(),
+    search_scope: z.object({
+        max_depth: z.number().int().min(0).max(32),
+        max_paths: z.number().int().min(1).max(100),
+        exhaustive: z.boolean(),
+    }),
+    explored: z.object({
+        nodes: z.number().int().min(0),
+        edges: z.number().int().min(0),
+        depth_reached: z.number().int().min(0),
+    }),
+    paths: z.object({
+        items: z.array(pathSchema).max(100),
+        offset: z.number().int().min(0),
+        limit: z.number().int().min(1).max(100),
+        total: z.number().int().min(0).nullable(),
+        returned: z.number().int().min(0).max(100),
+        truncated: z.boolean(),
+        lower_bound: z.number().int().min(0),
+        next_offset: z.number().int().min(0).nullable(),
+    }),
+    evidence_links: z.array(evidenceIdSchema).min(1).max(50_000),
+    limitations: z.array(z.string()),
+});
+/** Reconstruct bounded direct-callee paths from explicit analyze_function Evidence. */
+export const buildCallPath = (input) => {
+    const parsed = callPathInputSchema.parse(input);
+    const snapshots = parseSnapshots(parsed.functions);
+    assertCompatible(snapshots);
+    if (!snapshots.has(parsed.start.address))
+        throw new TypeError(`No analyze_function Evidence was supplied for start ${parsed.start.address}`);
+    const graph = createGraph(snapshots);
+    const search = inspectSearch({
+        graph,
+        snapshots,
+        start: parsed.start.address,
+        goal: parsed.goal.address,
+        maxDepth: parsed.max_depth,
+    });
+    const shortest = graph.hasNode(parsed.start.address) && graph.hasNode(parsed.goal.address)
+        ? bidirectional(graph, parsed.start.address, parsed.goal.address)
+        : null;
+    const enumeration = shortest === null || shortest.length - 1 > parsed.max_depth
+        ? { paths: [], budgetExhausted: false }
+        : enumeratePaths({
+            graph,
+            start: parsed.start.address,
+            goal: parsed.goal.address,
+            shortestDepth: shortest.length - 1,
+            maxDepth: parsed.max_depth,
+            limit: parsed.max_paths + 1,
+        });
+    const hasKnownExtraPath = enumeration.paths.length > parsed.max_paths;
+    const capped = hasKnownExtraPath || enumeration.budgetExhausted;
+    const retained = enumeration.paths.slice(0, parsed.max_paths);
+    const paths = retained.map((path) => citePath(path, snapshots));
+    const total = paths.length;
+    const items = paths.slice(parsed.offset, parsed.offset + parsed.limit);
+    const found = paths.length > 0;
+    const exhaustive = search.exhaustive && !capped;
+    const status = callPathStatus({ capped, found, exhaustive });
+    const limitations = [...search.limitations];
+    if (capped)
+        limitations.push(enumeration.budgetExhausted
+            ? `Path enumeration stopped at ${MAX_PATH_EXPANSIONS} expansions`
+            : `Path enumeration stopped at max_paths=${parsed.max_paths}`);
+    if (!found && shortest !== null && shortest.length - 1 > parsed.max_depth)
+        limitations.push(`The shortest observed path exceeds max_depth=${parsed.max_depth}`);
+    return callPathResultSchema.parse({
+        status,
+        start: parsed.start.address,
+        goal: parsed.goal.address,
+        shortest_hops: found ? (paths[0]?.hops ?? null) : null,
+        search_scope: {
+            max_depth: parsed.max_depth,
+            max_paths: parsed.max_paths,
+            exhaustive,
+        },
+        explored: {
+            nodes: search.reached.size,
+            edges: [...search.reached.keys()].reduce((count, node) => count + (graph.hasNode(node) ? graph.outDegree(node) : 0), 0),
+            depth_reached: Math.max(0, ...search.reached.values()),
+        },
+        paths: {
+            items,
+            offset: parsed.offset,
+            limit: parsed.limit,
+            total: capped ? null : total,
+            returned: items.length,
+            truncated: capped,
+            lower_bound: total + (hasKnownExtraPath ? 1 : 0),
+            next_offset: parsed.offset + items.length < total
+                ? parsed.offset + items.length
+                : null,
+        },
+        evidence_links: uniqueEvidence(snapshots.values()),
+        limitations: [...new Set(limitations)].sort((left, right) => left.localeCompare(right)),
+    });
+};
+const callPathStatus = ({ capped, found, exhaustive, }) => {
+    if (capped)
+        return "truncated";
+    if (found)
+        return "found";
+    return exhaustive ? "not_found" : "unknown";
+};
+const parseSnapshots = (groups) => {
+    const snapshots = new Map();
+    for (const group of groups) {
+        const snapshot = parseFunctionEvidence(group);
+        const address = normalizeAddress(snapshot.procedure.address);
+        for (const callee of snapshot.collections.callees.items)
+            normalizeAddress(callee.address);
+        if (snapshots.has(address))
+            throw new TypeError(`Duplicate function Evidence for ${address}`);
+        snapshots.set(address, snapshot);
+    }
+    return snapshots;
+};
+const assertCompatible = (snapshots) => {
+    const first = snapshots.values().next().value;
+    if (first === undefined)
+        return;
+    for (const snapshot of snapshots.values()) {
+        if (snapshot.subject.digest.sha256 !== first.subject.digest.sha256 ||
+            snapshot.subject.format !== first.subject.format ||
+            snapshot.subject.architecture !== first.subject.architecture)
+            throw new TypeError("Call-path Evidence mixes artifact subjects");
+        if (snapshot.provider.id !== first.provider.id ||
+            snapshot.provider.name !== first.provider.name ||
+            snapshot.provider.version !== first.provider.version)
+            throw new TypeError("Call-path Evidence mixes providers");
+    }
+};
+const createGraph = (snapshots) => {
+    const graph = new DirectedGraph({ allowSelfLoops: true, multi: false });
+    for (const [address, snapshot] of snapshots) {
+        graph.mergeNode(address);
+        for (const callee of snapshot.collections.callees.items) {
+            const calleeAddress = normalizeAddress(callee.address);
+            graph.mergeNode(calleeAddress);
+            graph.mergeDirectedEdge(address, calleeAddress);
+            if (graph.size > MAX_GRAPH_EDGES)
+                throw new TypeError(`Call graph exceeds ${MAX_GRAPH_EDGES} directed edges`);
+        }
+    }
+    return graph;
+};
+const inspectSearch = ({ graph, snapshots, start, goal, maxDepth, }) => {
+    if (!graph.hasNode(start))
+        return {
+            graph,
+            snapshots,
+            reached: new Map(),
+            exhaustive: false,
+            limitations: [
+                `No analyze_function Evidence was supplied for start ${start}`,
+            ],
+        };
+    const reached = new Map([[start, 0]]);
+    const queue = [start];
+    const limitations = [];
+    for (let index = 0; index < queue.length; index += 1) {
+        const node = queue[index];
+        if (node === undefined)
+            continue;
+        const depth = reached.get(node) ?? 0;
+        if (node === goal)
+            continue;
+        const snapshot = snapshots.get(node);
+        if (snapshot === undefined) {
+            limitations.push(`No analyze_function Evidence covers reachable function ${node}`);
+            continue;
+        }
+        if (!snapshot.collections.callees.complete)
+            limitations.push(`Callee coverage is incomplete for reachable function ${node}`);
+        const neighbors = graph
+            .outNeighbors(node)
+            .sort((left, right) => left.localeCompare(right));
+        if (depth === maxDepth) {
+            if (neighbors.length > 0)
+                limitations.push(`Search reached max_depth=${maxDepth} at ${node}`);
+            continue;
+        }
+        for (const neighbor of neighbors)
+            if (!reached.has(neighbor)) {
+                reached.set(neighbor, depth + 1);
+                queue.push(neighbor);
+            }
+    }
+    return {
+        graph,
+        snapshots,
+        reached,
+        exhaustive: limitations.length === 0,
+        limitations,
+    };
+};
+const enumeratePaths = ({ graph, start, goal, shortestDepth, maxDepth, limit, }) => {
+    const output = [];
+    const state = {
+        graph,
+        goal,
+        path: [start],
+        visited: new Set([start]),
+        output,
+        limit,
+        expansions: 0,
+        budgetExhausted: false,
+    };
+    for (let depth = shortestDepth; depth <= maxDepth && output.length < limit; depth += 1)
+        enumerateAtDepth(state, depth);
+    return { paths: output, budgetExhausted: state.budgetExhausted };
+};
+const enumerateAtDepth = (state, remaining) => {
+    const { graph, goal, path, visited, output, limit } = state;
+    state.expansions += 1;
+    if (state.expansions > MAX_PATH_EXPANSIONS) {
+        state.budgetExhausted = true;
+        return;
+    }
+    const current = path.at(-1);
+    if (current === undefined || output.length >= limit)
+        return;
+    if (remaining === 0) {
+        if (current === goal)
+            output.push([...path]);
+        return;
+    }
+    if (current === goal)
+        return;
+    for (const neighbor of graph
+        .outNeighbors(current)
+        .sort((left, right) => left.localeCompare(right))) {
+        if (visited.has(neighbor))
+            continue;
+        visited.add(neighbor);
+        path.push(neighbor);
+        enumerateAtDepth(state, remaining - 1);
+        path.pop();
+        visited.delete(neighbor);
+        if (output.length >= limit || state.budgetExhausted)
+            return;
+    }
+};
+const citePath = (addresses, snapshots) => {
+    const edges = addresses.slice(0, -1).map((source, index) => {
+        const target = addresses[index + 1];
+        if (target === undefined)
+            throw new TypeError("Call path has an invalid edge");
+        return {
+            source,
+            target,
+            evidence_links: snapshotLinks(snapshots.get(source)),
+        };
+    });
+    const nodes = addresses.map((address, index) => {
+        const snapshot = snapshots.get(address);
+        const supporting = snapshot ??
+            (index > 0 ? snapshots.get(addresses[index - 1] ?? "") : undefined);
+        return {
+            address,
+            name: snapshot?.procedure.name ?? null,
+            evidence_links: snapshotLinks(supporting),
+        };
+    });
+    return {
+        hops: edges.length,
+        nodes,
+        edges,
+        evidence_links: [
+            ...new Set(edges
+                .flatMap(({ evidence_links: links }) => links)
+                .concat(nodes.flatMap(({ evidence_links: links }) => links))),
+        ],
+    };
+};
+const snapshotLinks = (snapshot) => {
+    if (snapshot === undefined)
+        throw new TypeError("Every call-path claim requires supporting Evidence");
+    return snapshot.evidence.map(({ evidence_id }) => evidence_id);
+};
+const uniqueEvidence = (snapshots) => [
+    ...new Set([...snapshots].flatMap((snapshot) => snapshotLinks(snapshot))),
+].sort((left, right) => left.localeCompare(right));
+const normalizeAddress = (input) => inputAddressSchema.parse(input);