rea-agents 2.2.0 → 2.3.0

package/dist/application/JavaScriptSemanticGraphBuilder.js

@@ -0,0 +1,294 @@
+import { createJavaScriptSemanticGraph, } from "../domain/javascriptSemanticGraph.js";
+import { JAVASCRIPT_SEMANTIC_RELATION_FAMILIES, JAVASCRIPT_SEMANTIC_RELATION_FAMILY, } from "../domain/javascriptSemanticGraphSchemas.js";
+import { inferredSemanticEvidenceAt } from "./JavaScriptSemanticGraphEvidence.js";
+import { projectSemanticClosureCaptures, projectSemanticFrontiers, projectSemanticReturnValues, semanticRecoveryLimits, } from "./JavaScriptSemanticGraphFlowProjection.js";
+import { owningSemanticCallableNode, semanticFamilyStatus, semanticNodesWithinRange, semanticRangesEqual as rangesEqual, } from "./JavaScriptSemanticGraphProjection.js";
+import { addSemanticFallbackRoot as addFallbackRoot, addSemanticGraphNode as addNode, addSemanticGraphRelation as addRelation, constructSemanticGraphNode as semanticNode, createSemanticGraphProjectionState as emptyState, MAX_APPLICATION_NODE_IDS_PER_SEMANTIC_NODE, MAX_SEMANTIC_GRAPH_NODES, MAX_SEMANTIC_GRAPH_RELATIONS, MAX_SEMANTIC_GRAPH_UNKNOWNS, } from "./JavaScriptSemanticGraphConstruction.js";
+/** Project bounded per-file semantic IR into an artifact-bound companion graph. */
+export const buildJavaScriptSemanticGraph = ({ rootArtifactSha256, applicationGraph, analysis, }) => {
+    const state = emptyState(applicationGraph);
+    for (const analyzed of analysis.files) {
+        if (analyzed.semantic === null)
+            continue;
+        projectFile(analyzed.file, analyzed.semantic.ir, state);
+    }
+    if (state.roots.size === 0)
+        addFallbackRoot(rootArtifactSha256, state);
+    const semanticTruncated = analysis.files.some(({ semantic }) => semantic?.ir.coverage.status === "truncated");
+    const truncated = state.limitsReached.size > 0 || semanticTruncated;
+    const unknowns = [...state.unknowns.values()];
+    return createJavaScriptSemanticGraph({
+        schema: "JavaScriptSemanticRelationGraph",
+        schema_version: 1,
+        root_artifact_sha256: rootArtifactSha256,
+        application_graph_id: applicationGraph.graph_id,
+        root_node_ids: [...state.roots],
+        nodes: [...state.nodes.values()],
+        relations: [...state.relations.values()],
+        fingerprints: [],
+        unknowns,
+        coverage: {
+            status: truncated ? "partial" : "unknown",
+            truncated,
+            omitted_nodes: truncated ? null : 0,
+            omitted_relations: truncated ? null : 0,
+            limits: [
+                {
+                    name: "max_nodes",
+                    value: MAX_SEMANTIC_GRAPH_NODES,
+                    unit: "items",
+                },
+                {
+                    name: "max_relations",
+                    value: MAX_SEMANTIC_GRAPH_RELATIONS,
+                    unit: "items",
+                },
+                {
+                    name: "max_unknowns",
+                    value: MAX_SEMANTIC_GRAPH_UNKNOWNS,
+                    unit: "items",
+                },
+                {
+                    name: "max_application_node_ids_per_semantic_node",
+                    value: MAX_APPLICATION_NODE_IDS_PER_SEMANTIC_NODE,
+                    unit: "items",
+                },
+                ...semanticRecoveryLimits(analysis),
+            ],
+            families: JAVASCRIPT_SEMANTIC_RELATION_FAMILIES.map((family) => ({
+                family,
+                status: semanticFamilyStatus(family, analysis, truncated),
+                retained_relations: [...state.relations.values()].filter((relation) => JAVASCRIPT_SEMANTIC_RELATION_FAMILY[relation.relation] === family).length,
+                omitted_relations: truncated ? null : 0,
+                unknown_ids: unknowns
+                    .filter((unknown) => unknown.family === family)
+                    .map(({ unknown_id: identifier }) => identifier),
+            })),
+        },
+        limitations: [
+            "The semantic graph contains static syntax observations and conservative relationship candidates; it does not claim runtime execution.",
+            "Local data flow does not claim control-flow-sensitive reaching definitions or arbitrary dynamic property resolution.",
+            "Function fingerprints and promise, event, process, request, boundary, timer, configuration, and resource extraction are not available in this graph version's current extractor coverage.",
+            ...(truncated
+                ? [
+                    "Semantic graph projection reached one or more explicit hard limits.",
+                ]
+                : []),
+        ],
+    });
+};
+const projectFile = (file, ir, state) => {
+    const moduleNode = addNode(state, semanticNode(file, {
+        kind: "module",
+        roleKey: "module",
+        location: null,
+        label: file.path,
+        functionNodeId: null,
+    }, state));
+    if (moduleNode === null)
+        return;
+    state.roots.add(moduleNode.node_id);
+    const callableNodes = new Map(ir.callables.flatMap((callable) => {
+        const node = addNode(state, semanticNode(file, {
+            kind: "function",
+            roleKey: `callable:${callable.callableId}`,
+            location: callable.location,
+            label: callable.name,
+            functionNodeId: null,
+        }, state));
+        return node === null ? [] : [[callable.callableId, node]];
+    }));
+    const bindingNodes = new Map(ir.bindings.flatMap((binding) => {
+        const location = binding.definitions[0]?.location ?? null;
+        const kind = binding.kind === "parameter" ? "parameter" : "binding";
+        const owner = owningSemanticCallableNode(location, ir, callableNodes);
+        const node = addNode(state, semanticNode(file, {
+            kind,
+            roleKey: `binding:${binding.bindingId}`,
+            location,
+            label: binding.name,
+            functionNodeId: owner?.node_id ?? null,
+        }, state));
+        return node === null ? [] : [[binding.bindingId, node]];
+    }));
+    const returnSiteNodes = createReturnSiteNodes(file, ir, callableNodes, state);
+    const callSiteNodes = createCallSiteNodes(file, ir, callableNodes, state);
+    const context = {
+        file,
+        ir,
+        state,
+        moduleNode,
+        bindingNodes,
+        callableNodes,
+        callSiteNodes,
+        returnSiteNodes,
+        argumentNodes: new Map(),
+        referenceNodes: [],
+        callResolutions: new Map(ir.callSites.map((call) => [
+            call.callSiteId,
+            call.resolution === "exact" ? "resolved" : "candidate",
+        ])),
+    };
+    projectDefinitionsAndReferences(context);
+    projectCalls(context);
+    projectSemanticClosureCaptures(context);
+    projectSemanticFrontiers(context);
+};
+const createReturnSiteNodes = (file, ir, callables, state) => {
+    const result = new Map();
+    for (const callable of ir.callables) {
+        const owner = callables.get(callable.callableId);
+        if (owner === undefined)
+            continue;
+        for (const site of callable.returnSites) {
+            const identifier = site.returnSiteId;
+            const node = addNode(state, semanticNode(file, {
+                kind: "return-site",
+                roleKey: identifier,
+                location: site.location,
+                label: "return",
+                functionNodeId: owner.node_id,
+            }, state));
+            if (node !== null)
+                result.set(identifier, node);
+        }
+    }
+    return result;
+};
+const createCallSiteNodes = (file, ir, callables, state) => {
+    const result = new Map();
+    for (const call of ir.callSites) {
+        const owner = call.callerCallableId === null
+            ? null
+            : (callables.get(call.callerCallableId)?.node_id ?? null);
+        const node = addNode(state, semanticNode(file, {
+            kind: "call-site",
+            roleKey: `call:${call.callSiteId}`,
+            location: call.location,
+            label: call.kind,
+            functionNodeId: owner,
+        }, state));
+        if (node !== null)
+            result.set(call.callSiteId, node);
+    }
+    return result;
+};
+const projectDefinitionsAndReferences = (context) => {
+    for (const binding of context.ir.bindings) {
+        const bindingNode = context.bindingNodes.get(binding.bindingId);
+        if (bindingNode === undefined)
+            continue;
+        for (const [index, definition] of binding.definitions.entries()) {
+            const definitionNode = addNode(context.state, semanticNode(context.file, {
+                kind: "expression",
+                roleKey: `definition:${binding.bindingId}:${String(index)}`,
+                location: definition.location,
+                label: definition.kind,
+                functionNodeId: bindingNode.function_node_id,
+            }, context.state));
+            addRelation(context.state, {
+                source: definitionNode,
+                target: bindingNode,
+                relation: "defines",
+                resolution: "resolved",
+            });
+        }
+    }
+    for (const [index, reference] of context.ir.references.entries()) {
+        const expression = addNode(context.state, semanticNode(context.file, {
+            kind: "expression",
+            roleKey: `reference:${String(index)}:${reference.role}:${reference.name}`,
+            location: reference.location,
+            label: reference.name,
+            functionNodeId: owningSemanticCallableNode(reference.location, context.ir, context.callableNodes)?.node_id ?? null,
+        }, context.state));
+        const binding = reference.bindingId === null
+            ? undefined
+            : context.bindingNodes.get(reference.bindingId);
+        if (expression !== null)
+            context.referenceNodes.push(expression);
+        if (binding === undefined || expression === null)
+            continue;
+        if (reference.role === "read")
+            addRelation(context.state, {
+                source: binding,
+                target: expression,
+                relation: "reads",
+                resolution: "resolved",
+                evidence: inferredSemanticEvidenceAt(context.file, reference.location),
+            });
+        else
+            addRelation(context.state, {
+                source: expression,
+                target: binding,
+                relation: "writes",
+                resolution: "resolved",
+            });
+    }
+};
+const projectCalls = (context) => {
+    for (const call of context.ir.callSites) {
+        const callNode = context.callSiteNodes.get(call.callSiteId);
+        if (callNode === undefined)
+            continue;
+        for (const callableId of call.calleeCallableIds) {
+            const callable = context.callableNodes.get(callableId);
+            addRelation(context.state, {
+                source: callNode,
+                target: callable,
+                relation: "calls",
+                resolution: call.resolution === "exact" ? "resolved" : "candidate",
+            });
+        }
+        for (const argument of call.arguments) {
+            const argumentNode = createArgumentNode(context, callNode, call.callSiteId, argument);
+            if (argumentNode !== null)
+                context.argumentNodes.set(`${call.callSiteId}\u0000${String(argument.index)}`, argumentNode);
+            const references = semanticNodesWithinRange(context.referenceNodes, argument.location);
+            for (const reference of references)
+                addRelation(context.state, {
+                    source: reference,
+                    target: argumentNode,
+                    relation: "aliases",
+                    resolution: references.length === 1 &&
+                        rangesEqual(reference.identity.source_range, argument.location)
+                        ? "resolved"
+                        : "candidate",
+                });
+        }
+    }
+    for (const flow of context.ir.argumentFlows) {
+        const argument = context.argumentNodes.get(`${flow.callSiteId}\u0000${String(flow.argumentIndex)}`);
+        const parameter = context.bindingNodes.get(flow.parameterBindingId);
+        addRelation(context.state, {
+            source: argument,
+            target: parameter,
+            relation: "argument-to-parameter",
+            resolution: context.callResolutions.get(flow.callSiteId) ?? "candidate",
+        });
+    }
+    for (const flow of context.ir.callReturnFlows)
+        addRelation(context.state, {
+            source: context.returnSiteNodes.get(flow.returnSiteId),
+            target: context.callSiteNodes.get(flow.callSiteId),
+            relation: "returns-to-call",
+            resolution: context.callResolutions.get(flow.callSiteId) ?? "candidate",
+        });
+    for (const flow of context.ir.callResultFlows)
+        addRelation(context.state, {
+            source: context.callSiteNodes.get(flow.callSiteId),
+            target: context.bindingNodes.get(flow.bindingId),
+            relation: "aliases",
+            resolution: context.callResolutions.get(flow.callSiteId) ?? "candidate",
+        });
+    projectSemanticReturnValues(context);
+};
+const createArgumentNode = (context, callNode, callSiteId, argument) => addNode(context.state, semanticNode(context.file, {
+    kind: "expression",
+    roleKey: `argument:${callSiteId}:${String(argument.index)}`,
+    location: argument.location,
+    label: argument.spread
+        ? "spread argument"
+        : `argument ${String(argument.index)}`,
+    functionNodeId: callNode.function_node_id,
+}, context.state));

package/dist/application/JavaScriptSemanticGraphConstruction.js

@@ -0,0 +1,144 @@
+import { createJavaScriptSemanticGraphNode, createJavaScriptSemanticGraphRelation, } from "../domain/javascriptSemanticGraph.js";
+import { inferredSemanticEvidence, observedSemanticEvidence, unavailableSemanticRootEvidence, } from "./JavaScriptSemanticGraphEvidence.js";
+/** Hard semantic graph node bound enforced during artifact projection. */
+export const MAX_SEMANTIC_GRAPH_NODES = 100_000;
+/** Hard semantic graph relation bound enforced during artifact projection. */
+export const MAX_SEMANTIC_GRAPH_RELATIONS = 200_000;
+/** Hard unresolved-frontier bound enforced across all analyzed files. */
+export const MAX_SEMANTIC_GRAPH_UNKNOWNS = 100_000;
+/** Maximum structural nodes linked to one exact semantic location. */
+export const MAX_APPLICATION_NODE_IDS_PER_SEMANTIC_NODE = 64;
+/** Create empty projection state with structural application-node mappings. */
+export const createSemanticGraphProjectionState = (applicationGraph) => {
+    const index = indexApplicationNodes(applicationGraph.nodes);
+    return {
+        nodes: new Map(),
+        relations: new Map(),
+        unknowns: new Map(),
+        roots: new Set(),
+        limitsReached: new Set(index.truncated ? ["max_application_node_ids_per_semantic_node"] : []),
+        applicationNodeIdsByLocation: index.identifiers,
+    };
+};
+/** Construct one canonical semantic node backed by an exact artifact file. */
+export const constructSemanticGraphNode = (file, input, state) => createJavaScriptSemanticGraphNode({
+    kind: input.kind,
+    identity: {
+        artifact_sha256: file.sha256,
+        module_path: file.path,
+        source_range: input.location,
+        role_key: input.roleKey,
+    },
+    function_node_id: input.functionNodeId,
+    application_node_ids: matchingApplicationNodeIds(file, input, state),
+    label: input.label,
+    properties: {},
+    evidence: observedSemanticEvidence(file, input.location),
+});
+/** Retain one canonical node unless the hard graph bound was reached. */
+export const addSemanticGraphNode = (state, node) => {
+    const existing = state.nodes.get(node.node_id);
+    if (existing !== undefined)
+        return existing;
+    if (state.nodes.size >= MAX_SEMANTIC_GRAPH_NODES) {
+        state.limitsReached.add("max_nodes");
+        return null;
+    }
+    state.nodes.set(node.node_id, node);
+    return node;
+};
+/** Retain one non-self semantic relationship unless its hard bound was reached. */
+export const addSemanticGraphRelation = (state, input) => {
+    if (input.source === undefined ||
+        input.source === null ||
+        input.target === undefined ||
+        input.target === null ||
+        input.source.node_id === input.target.node_id)
+        return;
+    const value = createJavaScriptSemanticGraphRelation({
+        source_node_id: input.source.node_id,
+        target_node_id: input.target.node_id,
+        relation: input.relation,
+        resolution: input.resolution ?? "candidate",
+        properties: {},
+        evidence: input.evidence ?? inferredSemanticEvidence(input.source),
+    });
+    if (state.relations.has(value.relation_id))
+        return;
+    if (state.relations.size >= MAX_SEMANTIC_GRAPH_RELATIONS) {
+        state.limitsReached.add("max_relations");
+        return;
+    }
+    state.relations.set(value.relation_id, value);
+};
+/** Retain one unresolved frontier unless the global graph bound was reached. */
+export const addSemanticGraphUnknown = (state, unknown) => {
+    if (state.unknowns.has(unknown.unknown_id))
+        return;
+    if (state.unknowns.size >= MAX_SEMANTIC_GRAPH_UNKNOWNS) {
+        state.limitsReached.add("max_unknowns");
+        return;
+    }
+    state.unknowns.set(unknown.unknown_id, unknown);
+};
+/** Add a truthful root when no source file could produce semantic IR. */
+export const addSemanticFallbackRoot = (rootArtifactSha256, state) => {
+    const node = addSemanticGraphNode(state, createJavaScriptSemanticGraphNode({
+        kind: "module",
+        identity: {
+            artifact_sha256: rootArtifactSha256,
+            module_path: "unknown-semantic-root",
+            source_range: null,
+            role_key: "artifact-root",
+        },
+        function_node_id: null,
+        application_node_ids: [],
+        label: "unavailable semantic root",
+        properties: {},
+        evidence: unavailableSemanticRootEvidence(rootArtifactSha256),
+    }));
+    if (node !== null)
+        state.roots.add(node.node_id);
+};
+const indexApplicationNodes = (nodes) => {
+    const identifiers = new Map();
+    for (const node of nodes) {
+        for (const observation of node.observations) {
+            const { artifact, location } = observation.evidence;
+            if (!artifact.available || !location.available)
+                continue;
+            if (location.value.kind === "artifact-path") {
+                addApplicationNodeIdentifier(identifiers, applicationLocationKey(artifact.sha256, location.value.path, null), node.node_id);
+            }
+            if (location.value.kind === "source-range") {
+                addApplicationNodeIdentifier(identifiers, applicationLocationKey(artifact.sha256, location.value.source, {
+                    start: location.value.start,
+                    end: location.value.end,
+                }), node.node_id);
+            }
+        }
+    }
+    let truncated = false;
+    const indexed = new Map([...identifiers].map(([key, values]) => {
+        const sorted = [...values].sort();
+        if (sorted.length > MAX_APPLICATION_NODE_IDS_PER_SEMANTIC_NODE)
+            truncated = true;
+        return [key, sorted.slice(0, MAX_APPLICATION_NODE_IDS_PER_SEMANTIC_NODE)];
+    }));
+    return { identifiers: indexed, truncated };
+};
+const matchingApplicationNodeIds = (file, input, state) => [
+    ...(state.applicationNodeIdsByLocation.get(applicationLocationKey(file.sha256, file.path, input.location)) ?? []),
+];
+const addApplicationNodeIdentifier = (identifiers, key, nodeId) => {
+    const values = identifiers.get(key) ?? new Set();
+    values.add(nodeId);
+    identifiers.set(key, values);
+};
+const applicationLocationKey = (artifactSha256, path, range) => [
+    artifactSha256,
+    path,
+    range === null
+        ? "artifact-path"
+        : `${range.start.line}:${range.start.column}-${range.end.line}:${range.end.column}`,
+].join("\u0000");

package/dist/application/JavaScriptSemanticGraphEvidence.js

@@ -0,0 +1,86 @@
+const INFERENCE_LIMITATION = "This relationship is a bounded static candidate; it does not prove runtime execution or causal flow.";
+/** Exact artifact-backed syntax evidence for one semantic graph node. */
+export const observedSemanticEvidence = (file, location) => ({
+    authority: "ast-static-analysis",
+    state: "observed",
+    confidence: "exact",
+    artifact: {
+        available: true,
+        artifact_id: `art_${file.sha256}`,
+        sha256: file.sha256,
+    },
+    location: location === null
+        ? { available: true, value: { kind: "artifact-path", path: file.path } }
+        : {
+            available: true,
+            value: { kind: "source-range", source: file.path, ...location },
+        },
+    extractor: {
+        name: "rea-javascript-semantic-analysis",
+        version: "1",
+        operation: "analyze_javascript_application",
+        executable_sha256: null,
+    },
+    coverage: {
+        status: "complete",
+        truncated: false,
+        omitted_count: 0,
+        limits: [],
+    },
+    limitations: [],
+    evidence_ids: [],
+});
+/** Conservative static relationship evidence derived from one syntax node. */
+export const inferredSemanticEvidence = (source) => ({
+    ...source.evidence,
+    authority: "static-relationship-inference",
+    state: "inferred",
+    confidence: "high",
+    limitations: [INFERENCE_LIMITATION],
+});
+/** Static relationship evidence anchored at the syntax that proves the link. */
+export const inferredSemanticEvidenceAt = (file, location) => ({
+    ...observedSemanticEvidence(file, location),
+    authority: "static-relationship-inference",
+    state: "inferred",
+    confidence: "high",
+    limitations: [INFERENCE_LIMITATION],
+});
+/** Explicit absence of semantic syntax for an artifact-level fallback root. */
+export const unavailableSemanticRootEvidence = (rootArtifactSha256) => ({
+    authority: "unknown",
+    state: "unavailable",
+    confidence: "unknown",
+    artifact: {
+        available: true,
+        artifact_id: `art_${rootArtifactSha256}`,
+        sha256: rootArtifactSha256,
+    },
+    location: {
+        available: false,
+        reason: "not-observed",
+        detail: "No admitted JavaScript source produced semantic IR.",
+    },
+    extractor: {
+        name: "rea-javascript-semantic-analysis",
+        version: "1",
+        operation: "analyze_javascript_application",
+        executable_sha256: null,
+    },
+    coverage: {
+        status: "unavailable",
+        truncated: false,
+        omitted_count: null,
+        limits: [],
+    },
+    limitations: ["This synthetic graph root does not claim a source location."],
+    evidence_ids: [],
+});
+/** Explicit unknown evidence at one unresolved dynamic syntax location. */
+export const unknownSemanticEvidence = (file, location) => ({
+    ...observedSemanticEvidence(file, location),
+    authority: "unknown",
+    state: "unknown",
+    confidence: "unknown",
+    limitations: ["Dynamic syntax prevents an exact static relationship."],
+});

package/dist/application/JavaScriptSemanticGraphFlowProjection.js

@@ -0,0 +1,72 @@
+import { createJavaScriptSemanticGraphUnknown } from "../domain/javascriptSemanticGraph.js";
+import { addSemanticGraphRelation, addSemanticGraphUnknown, } from "./JavaScriptSemanticGraphConstruction.js";
+import { inferredSemanticEvidenceAt, unknownSemanticEvidence, } from "./JavaScriptSemanticGraphEvidence.js";
+import { semanticNodesWithinRange } from "./JavaScriptSemanticGraphProjection.js";
+/** Link direct return expressions to their retained semantic references. */
+export const projectSemanticReturnValues = (context) => {
+    for (const callable of context.ir.callables)
+        for (const site of callable.returnSites) {
+            const returnNode = context.returnSiteNodes.get(site.returnSiteId);
+            const references = semanticNodesWithinRange(context.referenceNodes, site.location);
+            for (const reference of references)
+                addSemanticGraphRelation(context.state, {
+                    source: reference,
+                    target: returnNode,
+                    relation: "aliases",
+                    resolution: site.identityReferenceLocation !== null &&
+                        rangesEqual(reference.identity.source_range, site.identityReferenceLocation)
+                        ? "resolved"
+                        : "candidate",
+                });
+        }
+};
+const rangesEqual = (left, right) => left !== null &&
+    right !== null &&
+    left.start.line === right.start.line &&
+    left.start.column === right.start.column &&
+    left.end.line === right.end.line &&
+    left.end.column === right.end.column;
+/** Link each captured binding to the callable at the exact reference site. */
+export const projectSemanticClosureCaptures = (context) => {
+    for (const capture of context.ir.closureCaptures)
+        addSemanticGraphRelation(context.state, {
+            source: context.bindingNodes.get(capture.bindingId),
+            target: context.callableNodes.get(capture.callableId),
+            relation: "captures",
+            resolution: "resolved",
+            evidence: inferredSemanticEvidenceAt(context.file, capture.referenceLocation),
+        });
+};
+/** Retain bounded unresolved dynamic-call and dynamic-property frontiers. */
+export const projectSemanticFrontiers = (context) => {
+    for (const frontier of context.ir.frontiers) {
+        const unknown = createJavaScriptSemanticGraphUnknown({
+            node_id: frontier.callableId === null
+                ? context.moduleNode.node_id
+                : (context.callableNodes.get(frontier.callableId)?.node_id ??
+                    context.moduleNode.node_id),
+            family: frontier.kind === "dynamic-call" ? "call-flow" : "object-flow",
+            relation_kinds: frontier.kind === "dynamic-call"
+                ? ["calls"]
+                : ["reads-property", "writes-property"],
+            reason: frontier.kind,
+            detail: frontier.reason,
+            candidate_node_ids: [],
+            evidence: unknownSemanticEvidence(context.file, frontier.location),
+        });
+        addSemanticGraphUnknown(context.state, unknown);
+    }
+};
+/** Publish exact semantic analyzer limits reached by any admitted source file. */
+export const semanticRecoveryLimits = (analysis) => {
+    const limits = new Map();
+    for (const { semantic } of analysis.files) {
+        if (semantic === null)
+            continue;
+        for (const name of semantic.ir.coverage.limitsReached)
+            limits.set(`semantic.${name}`, semantic.limits[name]);
+    }
+    return [...limits]
+        .sort(([left], [right]) => left.localeCompare(right))
+        .map(([name, value]) => ({ name, value, unit: "items" }));
+};

package/dist/application/JavaScriptSemanticGraphProjection.js

@@ -0,0 +1,33 @@
+import { compareCodePoints } from "../domain/javascriptApplicationGraph.js";
+import { JAVASCRIPT_SEMANTIC_RELATION_FAMILIES } from "../domain/javascriptSemanticGraphSchemas.js";
+/** Find the innermost callable that contains one exact source range. */
+export const owningSemanticCallableNode = (location, ir, nodes) => {
+    if (location === null)
+        return undefined;
+    return ir.callables
+        .filter((callable) => contains(callable.location, location))
+        .sort((left, right) => compareCodePoints(positionKey(right.location), positionKey(left.location)))
+        .map(({ callableId }) => nodes.get(callableId))
+        .find((node) => node !== undefined);
+};
+/** Find retained semantic nodes whose exact ranges are within one expression. */
+export const semanticNodesWithinRange = (nodes, range) => nodes.filter((node) => node.identity.source_range !== null &&
+    contains(range, node.identity.source_range));
+/** Report extractor support without treating missing families as absence. */
+export const semanticFamilyStatus = (family, analysis, truncated) => {
+    if (!["call-flow", "closure", "data-flow", "object-flow"].includes(family))
+        return "unsupported";
+    if (truncated)
+        return "unknown";
+    return analysis.truncated_scopes === 0 ? "partial" : "unknown";
+};
+/** Compare two exact semantic source ranges. */
+export const semanticRangesEqual = (left, right) => left !== null &&
+    left.start.line === right.start.line &&
+    left.start.column === right.start.column &&
+    left.end.line === right.end.line &&
+    left.end.column === right.end.column;
+const contains = (outer, inner) => pointCompare(outer.start, inner.start) <= 0 &&
+    pointCompare(outer.end, inner.end) >= 0;
+const pointCompare = (left, right) => left.line - right.line || left.column - right.column;
+const positionKey = (range) => `${String(range.start.line).padStart(12, "0")}:${String(range.start.column).padStart(12, "0")}`;

package/dist/application/JavaScriptSemanticTraceService.js

@@ -0,0 +1,45 @@
+import { z } from "zod";
+import { AnalysisInputError, AnalysisProtocolError, } from "../domain/errors.js";
+import { jsonValueSchema } from "../domain/jsonValue.js";
+import { queryJavaScriptSemanticGraph } from "../domain/javascriptSemanticQuery.js";
+import { JavaScriptSemanticQueryCursorError } from "../domain/javascriptSemanticQueryIdentity.js";
+import { javaScriptSemanticTraceResultSchema, traceJavaScriptSemanticsInputSchema, } from "../domain/javascriptSemanticTraceSchemas.js";
+import { err, ok } from "../domain/result.js";
+import { parseApplicationGraphEvidence } from "./JavaScriptApplicationEvidenceGraph.js";
+import { createJavaScriptSemanticTraceEvidence } from "./JavaScriptApplicationWorkflowEvidence.js";
+const OPERATION = "trace_javascript_semantics";
+/** Trace semantic relations from input already parsed by a trusted adapter. */
+export const traceJavaScriptSemanticsEvidenceValidated = (input) => {
+    try {
+        const source = parseApplicationGraphEvidence(input.application);
+        if (source.semanticGraph === null)
+            return err(new AnalysisInputError(OPERATION, undefined, [
+                {
+                    path: ["application"],
+                    reason: "invalid_value",
+                    expected: "analyze_javascript_application v2 Evidence; reanalyze the artifact with the current REA version",
+                },
+            ]));
+        const query = queryJavaScriptSemanticGraph(source.semanticGraph, input.query);
+        const result = javaScriptSemanticTraceResultSchema.parse({
+            ...query,
+            source_evidence_id: source.evidence.evidence_id,
+            evidence_links: [source.evidence.evidence_id],
+        });
+        return ok(createJavaScriptSemanticTraceEvidence({
+            application_evidence_id: source.evidence.evidence_id,
+            query: jsonValueSchema.parse(input.query),
+        }, result));
+    }
+    catch (cause) {
+        if (cause instanceof JavaScriptSemanticQueryCursorError)
+            return err(new AnalysisInputError(OPERATION, undefined, [
+                {
+                    path: ["query", "cursor"],
+                    reason: "invalid_value",
+                    expected: "a cursor returned by the same graph, query, and limits",
+                },
+            ]));
+        return err(new AnalysisProtocolError("JavaScript semantic trace failed", { cause }));
+    }
+};