rea-agents 1.6.0 → 2.0.0

package/dist/domain/javascriptApplicationVersionKeys.js

@@ -0,0 +1,170 @@
+import { compareCodePoints } from "./javascriptApplicationGraph.js";
+const matchTiers = () => [
+    { basis: "exact-content-digest", confidence: "exact", key: contentDigestKey },
+    {
+        basis: "exact-module-source-digest",
+        confidence: "exact",
+        key: moduleSourceDigestKey,
+    },
+    { basis: "exact-node-identity", confidence: "exact", key: nodeIdentityKey },
+    { basis: "source-map-identity", confidence: "high", key: sourceMapKey },
+    {
+        basis: "structural-fingerprint",
+        confidence: "medium",
+        key: structuralFingerprintKey,
+    },
+    { basis: "semantic-key", confidence: "medium", key: semanticKey },
+];
+/** Apply ordered, unique-only matching tiers without fuzzy pairing. */
+export const matchJavaScriptApplicationVersions = (leftNodes, rightNodes) => {
+    const left = new Map(leftNodes.map((node) => [node.node_id, node]));
+    const right = new Map(rightNodes.map((node) => [node.node_id, node]));
+    const leftCandidates = new Map();
+    const rightCandidates = new Map();
+    const pairs = [];
+    for (const tier of matchTiers())
+        applyTier(left, right, pairs, leftCandidates, rightCandidates, tier);
+    const remainingLeft = sortedNodes(left.values());
+    const remainingRight = sortedNodes(right.values());
+    const leftIds = new Set(remainingLeft.map(({ node_id: id }) => id));
+    const rightIds = new Set(remainingRight.map(({ node_id: id }) => id));
+    return {
+        pairs: pairs.sort((a, b) => compareCodePoints(`${a.left.node_id}\0${a.right.node_id}`, `${b.left.node_id}\0${b.right.node_id}`)),
+        unmatchedLeft: remainingLeft,
+        unmatchedRight: remainingRight,
+        candidatesForLeft: filteredCandidates(leftCandidates, rightIds),
+        candidatesForRight: filteredCandidates(rightCandidates, leftIds),
+    };
+};
+const applyTier = (left, right, pairs, leftCandidates, rightCandidates, tier) => {
+    const leftByKey = nodesByKey(left.values(), tier.key);
+    const rightByKey = nodesByKey(right.values(), tier.key);
+    for (const key of [...leftByKey.keys()].sort(compareCodePoints)) {
+        const leftGroup = leftByKey.get(key) ?? [];
+        const rightGroup = rightByKey.get(key) ?? [];
+        if (rightGroup.length === 0)
+            continue;
+        recordCandidates(leftGroup, rightGroup, leftCandidates, rightCandidates);
+        if (leftGroup.length !== 1 || rightGroup.length !== 1)
+            continue;
+        const leftNode = leftGroup[0];
+        const rightNode = rightGroup[0];
+        if (leftNode === undefined || rightNode === undefined)
+            continue;
+        pairs.push({ left: leftNode, right: rightNode, ...tier });
+        left.delete(leftNode.node_id);
+        right.delete(rightNode.node_id);
+    }
+};
+const nodesByKey = (nodes, keyFor) => {
+    const output = new Map();
+    for (const node of nodes) {
+        const key = keyFor(node);
+        if (key === null)
+            continue;
+        output.set(key, [...(output.get(key) ?? []), node]);
+    }
+    return output;
+};
+const recordCandidates = (left, right, leftCandidates, rightCandidates) => {
+    for (const leftNode of left) {
+        const candidates = leftCandidates.get(leftNode.node_id) ?? new Set();
+        for (const rightNode of right)
+            candidates.add(rightNode.node_id);
+        leftCandidates.set(leftNode.node_id, candidates);
+    }
+    for (const rightNode of right) {
+        const candidates = rightCandidates.get(rightNode.node_id) ?? new Set();
+        for (const leftNode of left)
+            candidates.add(leftNode.node_id);
+        rightCandidates.set(rightNode.node_id, candidates);
+    }
+};
+const filteredCandidates = (candidates, retained) => new Map([...candidates.entries()].flatMap(([nodeId, values]) => {
+    const filtered = [...values]
+        .filter((value) => retained.has(value))
+        .sort(compareCodePoints);
+    return filtered.length === 0 ? [] : [[nodeId, filtered]];
+}));
+const nodeIdentityKey = (node) => `node\0${node.kind}\0${node.node_id}`;
+const contentDigestKey = (node) => node.identity.strategy === "content-digest"
+    ? `content\0${node.kind}\0${node.identity.sha256}`
+    : null;
+const moduleSourceDigestKey = (node) => {
+    if (node.kind !== "javascript-module")
+        return null;
+    const value = uniqueStringProperty(node, "source_sha256");
+    return value === null ? null : `module-source\0${node.kind}\0${value}`;
+};
+const sourceMapKey = (node) => node.kind === "source-module" &&
+    node.identity.strategy === "source-map-original"
+    ? `source-map\0${node.identity.original_source}`
+    : null;
+const structuralFingerprintKey = (node) => {
+    if (node.kind !== "javascript-module")
+        return null;
+    const digest = uniqueStringProperty(node, "structural_fingerprint_sha256");
+    const algorithm = uniqueStringProperty(node, "structural_fingerprint_algorithm");
+    const status = uniqueStringProperty(node, "structural_fingerprint_status");
+    return digest === null || algorithm === null || status !== "complete"
+        ? null
+        : `structural\0${node.kind}\0${algorithm}\0${digest}`;
+};
+const semanticKey = (node) => {
+    if ([
+        "javascript-module",
+        "javascript-chunk",
+        "runtime-script-instance",
+        "unknown",
+    ].includes(node.kind))
+        return null;
+    const properties = firstProperties(node);
+    const value = semanticValue(node, properties);
+    return value === null ? null : `semantic\0${node.kind}\0${value}`;
+};
+const semanticValue = (node, properties) => {
+    if (node.kind === "endpoint")
+        return joined(properties.endpoint_kind, properties.value);
+    if (node.kind === "storage")
+        return joined(properties.storage_kind, properties.name ?? properties.mechanism);
+    if (node.kind === "ipc-channel")
+        return properties.resolution === "dynamic"
+            ? null
+            : (stringValue(properties.channel) ?? firstLabel(node));
+    if (node.kind === "context-bridge-api")
+        return firstLabel(node) ?? stringValue(properties.api_name);
+    if (node.kind === "native-export")
+        return (joined(properties.specifier, stringList(properties.requested_members).join(",")) ?? firstLabel(node));
+    if ([
+        "electron-main",
+        "electron-preload",
+        "electron-renderer",
+        "electron-utility",
+    ].includes(node.kind))
+        return joined(properties.declared_path, properties.resolved_path);
+    if (node.kind === "package")
+        return stringValue(properties.name);
+    return canonicalPath(node) ?? stringValue(properties.path);
+};
+const canonicalPath = (node) => node.identity.strategy === "canonical-path" ? node.identity.path : null;
+const firstProperties = (node) => node.observations[0]?.properties ?? {};
+const firstLabel = (node) => node.observations.find(({ label }) => label !== null)?.label ?? null;
+const uniqueStringProperty = (node, name) => {
+    const values = [
+        ...new Set(node.observations
+            .map(({ properties }) => properties[name])
+            .filter((value) => typeof value === "string")),
+    ];
+    return values.length === 1 ? (values[0] ?? null) : null;
+};
+const joined = (...values) => {
+    const strings = values.map(stringValue);
+    return strings.some((value) => value === null) ? null : strings.join("\0");
+};
+const stringValue = (value) => typeof value === "string" && value !== "" ? value : null;
+const stringList = (value) => Array.isArray(value)
+    ? value
+        .filter((item) => typeof item === "string")
+        .sort(compareCodePoints)
+    : [];
+const sortedNodes = (nodes) => [...nodes].sort((left, right) => compareCodePoints(left.node_id, right.node_id));

package/dist/domain/javascriptAstFingerprint.js

@@ -0,0 +1,143 @@
+import { createHash } from "node:crypto";
+import * as t from "@babel/types";
+/** Derive a rename-resistant, bounded syntax fingerprint without code execution. */
+export const fingerprintJavaScriptAst = (node, maximumTokens) => {
+    const tokens = [];
+    let truncated = false;
+    t.traverseFast(node, (current) => {
+        if (tokens.length >= maximumTokens) {
+            truncated = true;
+            return t.traverseFast.stop;
+        }
+        tokens.push(...semanticTokens(current));
+        if (tokens.length > maximumTokens) {
+            tokens.length = maximumTokens;
+            truncated = true;
+            return t.traverseFast.stop;
+        }
+        return undefined;
+    });
+    return {
+        sha256: createHash("sha256").update(JSON.stringify(tokens)).digest("hex"),
+        truncated,
+    };
+};
+/** Collect statically declared CommonJS/bundler export names from one factory. */
+export const collectJavaScriptExports = (node, maximumExports) => {
+    const exports = new Set();
+    let truncated = false;
+    t.traverseFast(node, (current) => {
+        if (exports.size >= maximumExports) {
+            truncated = true;
+            return t.traverseFast.stop;
+        }
+        if (t.isAssignmentExpression(current))
+            collectAssignmentExports(current.left, current.right, exports, maximumExports);
+        if (t.isCallExpression(current))
+            collectCallExports(current, exports, maximumExports);
+        return undefined;
+    });
+    return {
+        values: [...exports].sort(compareCodePoints),
+        truncated,
+    };
+};
+const semanticTokens = (node) => {
+    const tokens = [`node:${node.type}`];
+    if (t.isStringLiteral(node))
+        tokens.push(`string:${bounded(node.value)}`);
+    else if (t.isNumericLiteral(node))
+        tokens.push(`number:${String(node.value)}`);
+    else if (t.isBooleanLiteral(node))
+        tokens.push(`boolean:${String(node.value)}`);
+    else if (t.isRegExpLiteral(node))
+        tokens.push(`regexp:${bounded(node.pattern)}/${node.flags}`);
+    else if (t.isBinaryExpression(node) || t.isLogicalExpression(node))
+        tokens.push(`operator:${node.operator}`);
+    else if (t.isUnaryExpression(node) || t.isUpdateExpression(node))
+        tokens.push(`operator:${node.operator}`);
+    if (t.isMemberExpression(node) || t.isOptionalMemberExpression(node)) {
+        const property = propertyName(node.property);
+        if (property !== "")
+            tokens.push(`property:${bounded(property)}`);
+    }
+    if ((t.isObjectProperty(node) || t.isObjectMethod(node)) && !node.computed) {
+        const key = propertyName(node.key);
+        if (key !== "")
+            tokens.push(`key:${bounded(key)}`);
+    }
+    return tokens;
+};
+const collectAssignmentExports = (left, right, output, maximum) => {
+    const path = memberPath(left);
+    if (path === "exports" || path === "module.exports") {
+        if (t.isObjectExpression(right))
+            collectObjectKeys(right, output, maximum);
+        else
+            addExport(output, "default", maximum);
+        return;
+    }
+    if (path.startsWith("exports."))
+        addExport(output, path.slice("exports.".length), maximum);
+    if (path.startsWith("module.exports."))
+        addExport(output, path.slice("module.exports.".length), maximum);
+};
+const collectCallExports = (call, output, maximum) => {
+    const callee = memberPath(call.callee);
+    if (callee === "Object.defineProperty") {
+        const target = memberPath(call.arguments[0]);
+        const name = stringValue(call.arguments[1]);
+        if ((target === "exports" || target === "module.exports") && name)
+            addExport(output, name, maximum);
+    }
+    if (!callee.endsWith(".d"))
+        return;
+    const target = memberPath(call.arguments[0]);
+    const declarations = call.arguments[1];
+    if ((target === "exports" || target === "module.exports") &&
+        t.isObjectExpression(declarations))
+        collectObjectKeys(declarations, output, maximum);
+};
+const collectObjectKeys = (object, output, maximum) => {
+    for (const property of object.properties) {
+        if (output.size >= maximum)
+            return;
+        if (!t.isObjectProperty(property) && !t.isObjectMethod(property))
+            continue;
+        const name = propertyName(property.key);
+        if (name !== "")
+            addExport(output, name, maximum);
+    }
+};
+const addExport = (output, name, maximum) => {
+    if (output.size < maximum)
+        output.add(name.slice(0, 4_096));
+};
+const memberPath = (node, depth = 0) => {
+    if (depth >= 128)
+        return "[deep]";
+    if (node === undefined || node === null)
+        return "";
+    if (t.isIdentifier(node) || t.isPrivateName(node))
+        return t.isIdentifier(node) ? node.name : "";
+    if (t.isThisExpression(node))
+        return "this";
+    if (t.isMemberExpression(node) || t.isOptionalMemberExpression(node)) {
+        const object = t.isNode(node.object)
+            ? memberPath(node.object, depth + 1)
+            : "";
+        const property = propertyName(node.property);
+        return object === "" ? property : `${object}.${property}`;
+    }
+    return "";
+};
+const propertyName = (node) => {
+    if (t.isIdentifier(node))
+        return node.name;
+    if (t.isStringLiteral(node) || t.isNumericLiteral(node))
+        return String(node.value);
+    return "";
+};
+const stringValue = (node) => t.isStringLiteral(node) ? node.value : undefined;
+const bounded = (value) => value.slice(0, 1_024);
+const compareCodePoints = (left, right) => left < right ? -1 : left > right ? 1 : 0;

package/dist/domain/javascriptFeatureSeed.js

@@ -0,0 +1,140 @@
+import { compareCodePoints } from "./javascriptApplicationGraph.js";
+/** Locate every graph node matching a typed literal seed without regex execution. */
+export const findApplicationFeatureSeeds = (nodes, seed) => nodes
+    .flatMap((node) => seedMatch(node, seed))
+    .sort((left, right) => compareCodePoints(`${left.node_id}\0${left.basis}\0${left.field}`, `${right.node_id}\0${right.basis}\0${right.field}`));
+const seedMatch = (node, seed) => {
+    if (seed.kind === "node-id")
+        return node.node_id === seed.value
+            ? [
+                {
+                    node_id: node.node_id,
+                    kind: node.kind,
+                    basis: "node-id",
+                    field: "node_id",
+                },
+            ]
+            : [];
+    if (!kindMatches(node, seed.kind))
+        return [];
+    const mode = seed.match ?? (seed.kind === "string" ? "contains" : "exact");
+    const query = normalized(seed.value, seed.case_sensitive);
+    const match = candidateFields(node, seed.kind).find((candidate) => {
+        const value = normalized(candidate.value, seed.case_sensitive);
+        return mode === "exact" ? value === query : value.includes(query);
+    });
+    return match === undefined
+        ? []
+        : [
+            {
+                node_id: node.node_id,
+                kind: node.kind,
+                basis: match.basis,
+                field: match.field,
+            },
+        ];
+};
+const kindMatches = (node, kind) => {
+    if (kind === "string")
+        return true;
+    if (kind === "route")
+        return (node.kind === "endpoint" &&
+            node.observations.some(({ properties }) => properties.endpoint_kind === "route"));
+    if (kind === "api")
+        return node.kind === "context-bridge-api";
+    if (kind === "channel")
+        return node.kind === "ipc-channel";
+    if (kind === "module")
+        return ["javascript-asset", "javascript-module", "source-module"].includes(node.kind);
+    return node.kind === "native-export";
+};
+const candidateFields = (node, seedKind) => {
+    const fields = [
+        ...identityFields(node),
+        ...node.observations.flatMap((observation, index) => [
+            ...(observation.label === null
+                ? []
+                : [
+                    {
+                        basis: "label",
+                        field: `observations[${String(index)}].label`,
+                        value: observation.label,
+                    },
+                ]),
+            ...propertyFields(observation.properties, `observations[${String(index)}].properties`),
+        ]),
+    ];
+    if (seedKind === "string")
+        return fields;
+    const names = relevantFields[seedKind];
+    return fields.filter(({ field }) => names.some((name) => field === "identity" || field.endsWith(name)));
+};
+const relevantFields = {
+    route: [".label", ".value", ".path"],
+    api: [".label", ".api_name", ".key", ".methods", ".members"],
+    channel: [".label", ".channel", ".key"],
+    module: [
+        ".label",
+        ".module_key",
+        ".path",
+        ".source",
+        ".original_source",
+        ".exports",
+    ],
+    "native-export": [".label", ".key", ".requested_members", ".members"],
+};
+const identityFields = (node) => {
+    const identity = node.identity;
+    if (identity.strategy === "content-digest")
+        return [{ basis: "identity", field: "identity", value: identity.sha256 }];
+    if (identity.strategy === "source-map-original")
+        return [
+            {
+                basis: "identity",
+                field: "identity.original_source",
+                value: identity.original_source,
+            },
+        ];
+    if (identity.strategy === "canonical-path")
+        return [
+            { basis: "identity", field: "identity.path", value: identity.path },
+        ];
+    if (identity.strategy === "artifact-local-key")
+        return [{ basis: "identity", field: "identity.key", value: identity.key }];
+    if (identity.strategy === "runtime-instance")
+        return [
+            {
+                basis: "identity",
+                field: "identity.runtime_key",
+                value: identity.runtime_key,
+            },
+        ];
+    return [];
+};
+const propertyFields = (value, prefix) => {
+    const output = [];
+    const visit = (current, path, depth) => {
+        if (output.length >= 512 || depth > 6)
+            return;
+        if (typeof current === "string") {
+            output.push({ basis: "property", field: path, value: current });
+            return;
+        }
+        if (Array.isArray(current)) {
+            for (const [index, item] of current.entries())
+                visit(item, `${path}[${String(index)}]`, depth + 1);
+            return;
+        }
+        if (current !== null && typeof current === "object")
+            for (const key of Object.keys(current).sort(compareCodePoints))
+                visit(current[key] ?? null, `${path}.${key}`, depth + 1);
+    };
+    visit(value, prefix, 0);
+    return output;
+};
+const normalized = (value, caseSensitive) => {
+    const normalizedValue = value.normalize("NFKC");
+    return caseSensitive
+        ? normalizedValue
+        : normalizedValue.toLocaleLowerCase("en-US");
+};

package/dist/domain/javascriptFeatureTrace.js

@@ -0,0 +1,232 @@
+import { createHash } from "node:crypto";
+import canonicalize from "canonicalize";
+import { compareCodePoints, createJavaScriptApplicationGraph, } from "./javascriptApplicationGraph.js";
+import { applicationFeatureTraceResultSchema, } from "./javascriptFeatureTraceSchemas.js";
+import { findApplicationFeatureSeeds, } from "./javascriptFeatureSeed.js";
+import { traverseApplicationFeature, } from "./javascriptFeatureTraversal.js";
+import { buildJavaScriptNativeHandoffs } from "./javascriptNativeHandoff.js";
+/** Trace a literal feature through a bounded, authority-preserving JAG. */
+export const traceApplicationFeature = (input) => {
+    const allSeedMatches = findApplicationFeatureSeeds(input.graph.nodes, input.seed);
+    const seedMatches = allSeedMatches.slice(0, input.limits.max_seed_matches);
+    if (seedMatches.length === 0)
+        return noMatchResult(input);
+    const traversal = traverseApplicationFeature(input.graph, seedMatches.map(({ node_id: id }) => id), input.direction, input.limits);
+    const graph = traceGraph(input, seedMatches, traversal, allSeedMatches.length);
+    const allPaths = terminalPaths(traversal, seedMatches);
+    const paths = allPaths.slice(0, input.limits.max_paths);
+    const nativeHandoffs = buildJavaScriptNativeHandoffs(traversal.nodes, traversal.edges, input.nativeEvidence);
+    const evidenceLinks = uniqueSorted([
+        input.sourceEvidenceId,
+        ...nativeHandoffs.flatMap(({ evidence_ids: ids }) => ids),
+    ]);
+    const omissions = traceOmissions(input, traversal, allSeedMatches.length, allPaths.length);
+    const semantic = {
+        schema_version: 1,
+        source_evidence_id: input.sourceEvidenceId,
+        source_graph_id: input.graph.graph_id,
+        seed: input.seed,
+        direction: input.direction,
+        seed_matches: seedMatches,
+        graph,
+        paths,
+        native_handoffs: nativeHandoffs,
+        summary: {
+            matched_seeds: seedMatches.length,
+            traced_nodes: traversal.nodes.length,
+            traced_edges: traversal.edges.length,
+            terminal_paths: paths.length,
+            native_handoffs: nativeHandoffs.length,
+            ...factSummary(traversal.nodes, traversal.edges),
+        },
+        coverage: {
+            status: traceCoverageStatus(input.graph, omissions),
+            source_graph_status: input.graph.coverage.status,
+            scanned_nodes: input.graph.nodes.length,
+            total_seed_matches: allSeedMatches.length,
+            ...omissions,
+            frontier_node_ids: traversal.frontierNodeIds,
+        },
+        evidence_links: evidenceLinks,
+        limitations: traceLimitations(input.graph, omissions),
+    };
+    return applicationFeatureTraceResultSchema.parse({
+        ...semantic,
+        trace_id: `jatr_${digestCanonical(semantic)}`,
+    });
+};
+const noMatchResult = (input) => {
+    const semantic = {
+        schema_version: 1,
+        source_evidence_id: input.sourceEvidenceId,
+        source_graph_id: input.graph.graph_id,
+        seed: input.seed,
+        direction: input.direction,
+        seed_matches: [],
+        graph: null,
+        paths: [],
+        native_handoffs: [],
+        summary: {
+            matched_seeds: 0,
+            traced_nodes: 0,
+            traced_edges: 0,
+            terminal_paths: 0,
+            native_handoffs: 0,
+            observed_facts: 0,
+            inferred_facts: 0,
+            unknown_facts: 0,
+            unavailable_facts: 0,
+        },
+        coverage: {
+            status: "no-match",
+            source_graph_status: input.graph.coverage.status,
+            scanned_nodes: input.graph.nodes.length,
+            total_seed_matches: 0,
+            omitted_seed_matches: 0,
+            omitted_nodes: 0,
+            omitted_edges: 0,
+            omitted_paths: 0,
+            frontier_node_ids: [],
+        },
+        evidence_links: [input.sourceEvidenceId],
+        limitations: uniqueSorted([
+            "No graph entity matched the literal seed; this is not evidence that the feature is absent.",
+            ...sourceCoverageLimitations(input.graph),
+        ]),
+    };
+    return applicationFeatureTraceResultSchema.parse({
+        ...semantic,
+        trace_id: `jatr_${digestCanonical(semantic)}`,
+    });
+};
+const traceGraph = (input, seedMatches, traversal, totalSeedMatches) => {
+    const omitted = traversal.omittedNodeCount +
+        traversal.omittedEdgeCount +
+        (totalSeedMatches - seedMatches.length);
+    return createJavaScriptApplicationGraph({
+        schema: "JavaScriptApplicationGraph",
+        schema_version: 1,
+        root_node_ids: uniqueSorted(seedMatches.map(({ node_id: id }) => id)),
+        nodes: traversal.nodes,
+        edges: traversal.edges,
+        coverage: traceGraphCoverage(input.graph, input.limits, omitted),
+        limitations: uniqueSorted([
+            ...input.graph.limitations,
+            "Trace edges retain their source authority; graph connectivity does not prove runtime execution or reachability.",
+            ...(omitted === 0
+                ? []
+                : ["Trace output stopped at explicit caller bounds."]),
+        ]),
+    });
+};
+const traceGraphCoverage = (source, limits, omitted) => {
+    if (omitted > 0)
+        return {
+            status: "partial",
+            truncated: true,
+            omitted_count: omitted,
+            limits: [
+                {
+                    name: "max-seed-matches",
+                    value: limits.max_seed_matches,
+                    unit: "items",
+                },
+                { name: "max-depth", value: limits.max_depth, unit: "depth" },
+                { name: "max-nodes", value: limits.max_nodes, unit: "items" },
+                { name: "max-edges", value: limits.max_edges, unit: "items" },
+            ],
+        };
+    return source.coverage.status === "complete"
+        ? { status: "complete", truncated: false, omitted_count: 0, limits: [] }
+        : {
+            status: source.coverage.status,
+            truncated: source.coverage.truncated,
+            omitted_count: source.coverage.omitted_count,
+            limits: source.coverage.limits,
+        };
+};
+const terminalPaths = (traversal, seeds) => {
+    const seedIds = new Set(seeds.map(({ node_id: id }) => id));
+    const edgeById = new Map(traversal.edges.map((edge) => [edge.edge_id, edge]));
+    return traversal.nodes
+        .filter((node) => isTerminal(node) &&
+        (!seedIds.has(node.node_id) || traversal.nodes.length === 1))
+        .map((node) => pathTo(node, traversal.predecessors, edgeById))
+        .filter((path) => path !== null)
+        .sort((left, right) => compareCodePoints(left.path_id, right.path_id));
+};
+const pathTo = (node, predecessors, edgeById) => {
+    const nodeIds = [node.node_id];
+    const edgeIds = [];
+    let current = node.node_id;
+    while (predecessors.has(current)) {
+        const predecessor = predecessors.get(current);
+        if (predecessor === undefined)
+            break;
+        nodeIds.push(predecessor.previousNodeId);
+        edgeIds.push(predecessor.edgeId);
+        current = predecessor.previousNodeId;
+    }
+    nodeIds.reverse();
+    edgeIds.reverse();
+    const edges = edgeIds
+        .map((edgeId) => edgeById.get(edgeId))
+        .filter((edge) => edge !== undefined);
+    if (edges.length !== edgeIds.length)
+        return null;
+    const semantic = {
+        start_node_id: nodeIds[0] ?? node.node_id,
+        end_node_id: node.node_id,
+        end_kind: node.kind,
+        node_ids: nodeIds,
+        edge_ids: edgeIds,
+        authorities: uniqueSorted(edges.map(({ evidence }) => evidence.authority)),
+        contains_inference: edges.some(({ evidence }) => evidence.state === "inferred"),
+    };
+    return { ...semantic, path_id: `jatp_${digestCanonical(semantic)}` };
+};
+const isTerminal = (node) => ["endpoint", "storage", "native-addon", "native-export", "unknown"].includes(node.kind);
+const factSummary = (nodes, edges) => {
+    const states = [
+        ...nodes.flatMap(({ observations }) => observations.map(({ evidence }) => evidence.state)),
+        ...edges.map(({ evidence }) => evidence.state),
+    ];
+    return {
+        observed_facts: states.filter((state) => state === "observed").length,
+        inferred_facts: states.filter((state) => state === "inferred").length,
+        unknown_facts: states.filter((state) => state === "unknown").length,
+        unavailable_facts: states.filter((state) => state === "unavailable").length,
+    };
+};
+const traceOmissions = (input, traversal, seedMatches, paths) => ({
+    omitted_seed_matches: Math.max(0, seedMatches - input.limits.max_seed_matches),
+    omitted_nodes: traversal.omittedNodeCount,
+    omitted_edges: traversal.omittedEdgeCount,
+    omitted_paths: Math.max(0, paths - input.limits.max_paths),
+});
+const traceCoverageStatus = (graph, omissions) => Object.values(omissions).some((value) => value > 0)
+    ? "truncated"
+    : graph.coverage.status === "complete"
+        ? "complete-within-source"
+        : "partial";
+const traceLimitations = (graph, omissions) => uniqueSorted([
+    "A trace reports graph relationships, not proof that code executed or that a feature is reachable in every state.",
+    "Static, native, passive-runtime, inferred, and unknown facts retain their original authority in the returned graph.",
+    "Native handoffs never open a binary or invoke a provider automatically; snapshot reuse remains provider/profile/target exact.",
+    ...sourceCoverageLimitations(graph),
+    ...(Object.values(omissions).some((value) => value > 0)
+        ? ["Trace results were truncated at explicit caller limits."]
+        : []),
+]);
+const sourceCoverageLimitations = (graph) => graph.coverage.status === "complete"
+    ? []
+    : [
+        "The source application graph is incomplete; unmatched seeds and frontiers remain unknown.",
+    ];
+const digestCanonical = (value) => {
+    const encoded = canonicalize(value);
+    if (encoded === undefined)
+        throw new TypeError("Feature trace could not canonicalize data");
+    return createHash("sha256").update(encoded).digest("hex");
+};
+const uniqueSorted = (values) => [...new Set(values)].sort(compareCodePoints);