rea-agents 2.1.0 → 2.3.0

package/dist/domain/javascriptSemanticGraphSerialization.js

@@ -0,0 +1,23 @@
+import canonicalize from "canonicalize";
+import { z } from "zod";
+import { javaScriptSemanticGraphSchema, } from "./javascriptSemanticGraph.js";
+const canonicalJson = (value) => {
+    const encoded = canonicalize(value);
+    if (encoded === undefined)
+        throw new TypeError("JavaScript semantic graph could not canonicalize data");
+    return encoded;
+};
+/** Parse a stored semantic graph and reject unsupported versions or stale IDs. */
+export const parseJavaScriptSemanticGraph = (input) => {
+    const envelope = z
+        .object({ schema: z.string(), schema_version: z.number() })
+        .passthrough()
+        .safeParse(input);
+    if (envelope.success &&
+        envelope.data.schema === "JavaScriptSemanticRelationGraph" &&
+        envelope.data.schema_version !== 1)
+        throw new TypeError(`Unsupported JavaScript Semantic Relation Graph schema version: ${String(envelope.data.schema_version)}`);
+    return javaScriptSemanticGraphSchema.parse(input);
+};
+/** Serialize a verified semantic graph as canonical JSON. */
+export const serializeJavaScriptSemanticGraph = (input) => canonicalJson(parseJavaScriptSemanticGraph(input));

package/dist/domain/javascriptSemanticIr.js

@@ -5,6 +5,13 @@ export const DEFAULT_JAVASCRIPT_SEMANTIC_LIMITS = {
     maxCallables: 20_000,
     maxReferences: 100_000,
     maxModuleLinks: 20_000,
+    maxReturnSites: 20_000,
+    maxCallSites: 20_000,
+    maxCallArguments: 100_000,
+    maxArgumentFlows: 100_000,
+    maxCallReturnFlows: 100_000,
+    maxClosureCaptures: 100_000,
+    maxFrontiers: 20_000,
     maxValueDepth: 16,
     maxUnionValues: 32,
     maxObjectProperties: 256,
@@ -16,12 +23,18 @@ export const semanticBinding = (ir, bindingId) => ir.bindings.find(({ bindingId:
 /** Fail-closed result when Babel cannot produce an inert syntax tree. */
 export const failedJavaScriptSemanticIr = () => ({
     schema: "JavaScriptSemanticIR",
-    schemaVersion: 1,
+    schemaVersion: 3,
     scopes: [],
     bindings: [],
     callables: [],
     references: [],
     moduleLinks: [],
+    callSites: [],
+    argumentFlows: [],
+    callReturnFlows: [],
+    callResultFlows: [],
+    closureCaptures: [],
+    frontiers: [],
     coverage: { status: "failed", omittedCount: null, limitsReached: [] },
     limitations: [
         "JavaScript parsing failed; no semantic absence claim is available.",

package/dist/domain/javascriptSemanticPrimitives.js

@@ -0,0 +1,36 @@
+import * as t from "@babel/types";
+import { reachSemanticValueLimit, semanticPrimitiveKey, } from "./javascriptSemanticProvenance.js";
+import { compareCodePoints } from "./javascriptStaticAnalysisHelpers.js";
+/** Normalize one bounded collection of possible primitive values. */
+export const semanticPrimitiveSet = (values, state) => {
+    const unique = [
+        ...new Map(values.map((value) => [semanticPrimitiveKey(value), value])).values(),
+    ].sort((left, right) => compareCodePoints(semanticPrimitiveKey(left), semanticPrimitiveKey(right)));
+    if (unique.length > state.limits.maxUnionValues) {
+        reachSemanticValueLimit(state, "maxUnionValues");
+        return {
+            status: "limit-reached",
+            reason: "maxUnionValues reached.",
+        };
+    }
+    const only = unique[0];
+    return unique.length === 1 && only !== undefined
+        ? { status: "literal", value: only }
+        : { status: "union", values: unique };
+};
+/** Read the primitive candidates retained in one lattice value. */
+export const semanticPrimitiveCandidates = (value) => value.status === "literal"
+    ? [value.value]
+    : value.status === "union"
+        ? value.values
+        : null;
+/** Parse one Babel primitive literal without evaluating code. */
+export const semanticPrimitiveValue = (node) => {
+    if (t.isStringLiteral(node) || t.isNumericLiteral(node))
+        return { found: true, value: node.value };
+    if (t.isBooleanLiteral(node))
+        return { found: true, value: node.value };
+    if (t.isNullLiteral(node))
+        return { found: true, value: null };
+    return { found: false };
+};

package/dist/domain/javascriptSemanticProjection.js

@@ -13,8 +13,9 @@ export const collectSemanticCallable = (input) => {
         reachSemanticLimit(state, "maxCallables");
         return;
     }
+    const callableId = semanticCallableIdForNode(node) ?? "callable:unknown:-1:-1";
     state.callables.push({
-        callableId: `callable:${kind}:${String(node.start ?? -1)}:${String(node.end ?? -1)}`,
+        callableId,
         kind,
         name: callableName(node, parent),
         containerScopeId: containerScope.scopeId,
@@ -22,7 +23,15 @@ export const collectSemanticCallable = (input) => {
             ? null
             : bodyScope.scopeId,
         location: range(node),
+        returnSites: [],
+        returnCoverage: {
+            status: "partial",
+            retainedCount: 0,
+            omittedCount: null,
+            limitsReached: [],
+        },
     });
+    state.callableNodesById.set(callableId, node);
 };
 /** Collect one static import/export relationship for later composition. */
 export const collectSemanticModuleLink = (node, state) => {
@@ -46,6 +55,7 @@ export const collectSemanticModuleLink = (node, state) => {
             importedName: null,
             localName: defaultDeclarationName(node.declaration),
             exportedName: "default",
+            callableId: semanticCallableIdForNode(node.declaration),
             location: range(node),
         });
     else if (t.isVariableDeclarator(node))
@@ -61,7 +71,7 @@ export const collectSemanticReferences = (program, state) => {
         enter: (node, parent) => {
             if (!t.isIdentifier(node) || parent === null)
                 return;
-            const role = referenceRole(node, parent);
+            const role = semanticReferenceRole(node, parent);
             if (role === null)
                 return;
             const key = `${String(node.start)}:${role}:${node.name}`;
@@ -205,6 +215,7 @@ const collectNamedExports = (node, state) => {
                 importedName: null,
                 localName,
                 exportedName: localName,
+                callableId: declarationCallableId(node.declaration, localName),
                 location: range(node.declaration),
             });
     for (const specifier of node.specifiers)
@@ -265,6 +276,7 @@ const collectCommonJsExport = (node, state) => {
         importedName: origin?.importedPath.at(-1) ?? null,
         localName: t.isIdentifier(node.right) ? node.right.name : null,
         exportedName,
+        callableId: semanticCallableIdForNode(node.right),
         location: range(node),
     });
 };
@@ -273,9 +285,29 @@ const addModuleLink = (state, link) => {
         reachSemanticLimit(state, "maxModuleLinks");
         return;
     }
-    state.moduleLinks.push(link);
+    state.moduleLinks.push({ ...link, callableId: link.callableId ?? null });
+};
+/** Deterministic callable identity shared by collection and return recovery. */
+export const semanticCallableIdForNode = (node) => {
+    const kind = callableKind(node);
+    return kind === undefined
+        ? null
+        : `callable:${kind}:${String(node.start ?? -1)}:${String(node.end ?? -1)}`;
+};
+const declarationCallableId = (declaration, localName) => {
+    if ((t.isFunctionDeclaration(declaration) ||
+        t.isClassDeclaration(declaration)) &&
+        declaration.id?.name === localName)
+        return semanticCallableIdForNode(declaration);
+    if (!t.isVariableDeclaration(declaration))
+        return null;
+    const declarator = declaration.declarations.find(({ id }) => t.isIdentifier(id, { name: localName }));
+    return declarator?.init === null || declarator?.init === undefined
+        ? null
+        : semanticCallableIdForNode(declarator.init);
 };
-const referenceRole = (node, parent) => {
+/** Classify one identifier occurrence consistently with semantic references. */
+export const semanticReferenceRole = (node, parent) => {
     if (isDeclarationIdentifier(node, parent) || isNonReferenceKey(node, parent))
         return null;
     if ((t.isAssignmentExpression(parent) && parent.left === node) ||

package/dist/domain/javascriptSemanticProvenance.js

@@ -0,0 +1,29 @@
+import { compareCodePoints } from "./javascriptStaticAnalysisHelpers.js";
+/** Construct one immutable semantic provenance value. */
+export const semanticProvenance = (status, origins, reason) => ({ status, origins, reason });
+/** Normalize bounded exact module origins into one provenance classification. */
+export const semanticOriginsProvenance = (origins, state) => {
+    const unique = uniqueSemanticOrigins(origins);
+    if (unique.length > state.limits.maxUnionValues)
+        return semanticLimitProvenance(state, "maxUnionValues");
+    return unique.length === 1
+        ? semanticProvenance("module", unique, null)
+        : semanticProvenance("ambiguous", unique, "Multiple module origins.");
+};
+/** Deduplicate and canonically order module origins. */
+export const uniqueSemanticOrigins = (origins) => [
+    ...new Map(origins.map((origin) => [semanticOriginKey(origin), origin])).values(),
+].sort((left, right) => compareCodePoints(semanticOriginKey(left), semanticOriginKey(right)));
+/** Mark and return an explicit provenance-limit value. */
+export const semanticLimitProvenance = (state, limit) => {
+    reachSemanticValueLimit(state, limit);
+    return semanticProvenance("limit-reached", [], `${limit} reached.`);
+};
+/** Record one value-lattice limit against the shared semantic analysis state. */
+export const reachSemanticValueLimit = (state, limit) => {
+    state.limitsReached.add(limit);
+    state.omittedCount += 1;
+};
+const semanticOriginKey = (origin) => `${origin.specifier}\0${origin.importedPath.join("\0")}`;
+/** Canonically distinguish primitive values across type boundaries. */
+export const semanticPrimitiveKey = (value) => `${value === null ? "null" : typeof value}:${JSON.stringify(value)}`;

package/dist/domain/javascriptSemanticQuery.js

@@ -0,0 +1,294 @@
+import { compareCodePoints } from "./javascriptApplicationGraph.js";
+import { isJavaScriptSemanticOwnershipRelation as ownershipRelation } from "./javascriptSemanticQueryRelations.js";
+import { javaScriptSemanticQueryInputSchema, javaScriptSemanticQueryResultSchema, } from "./javascriptSemanticQuerySchemas.js";
+import { assessJavaScriptSemanticQuery, } from "./javascriptSemanticQueryAssessment.js";
+import { canonicalJavaScriptSemanticQueryJson as canonicalJson, createJavaScriptSemanticQueryCursor as createCursor, JavaScriptSemanticQueryCursorError, javaScriptSemanticQueryIdentifier as queryIdentifier, parseJavaScriptSemanticQueryCursor as parseCursor, resolveJavaScriptSemanticQuerySeeds as resolveSeeds, } from "./javascriptSemanticQueryIdentity.js";
+/** Run one deterministic bounded traversal over a verified semantic graph. */
+export const queryJavaScriptSemanticGraph = (graph, rawInput) => {
+    const input = javaScriptSemanticQueryInputSchema.parse(rawInput);
+    const queryId = queryIdentifier(graph, input);
+    const offset = parseCursor(input.cursor, queryId);
+    const seeds = resolveSeeds(graph, input);
+    const admission = admitSeeds(graph, seeds, input);
+    const retainedSeeds = admission.nodeIds;
+    const adjacency = buildAdjacency(graph.relations, input);
+    const traversal = traverse(graph, retainedSeeds, adjacency, input);
+    const frontier = uniqueFrontier([
+        ...traversal.frontier,
+        ...admission.frontier,
+    ]);
+    const page = createQueryPage({
+        graph,
+        traversal,
+        query: input,
+        queryId,
+        offset,
+        retainedSeeds,
+    });
+    const allRelevantUnknowns = relevantUnknownFrontiers(graph, traversal.nodeIds, input);
+    const relevantUnknowns = allRelevantUnknowns.slice(0, input.limits.max_unknowns);
+    const candidateRelations = relevantCandidateRelationCount(graph, traversal.nodeIds, input);
+    const expectedMatches = expectedMatchesFor(page.retainedNodes, page.retainedRelations, input);
+    const assessment = assessJavaScriptSemanticQuery({
+        graph,
+        totalSeeds: seeds.length,
+        retainedSeeds: retainedSeeds.length,
+        expectedMatches: expectedMatches.length,
+        hasExpectation: input.expected !== null,
+        frontier,
+        unknowns: relevantUnknowns,
+        candidateRelations,
+        unknownsTruncated: allRelevantUnknowns.length > relevantUnknowns.length,
+    });
+    return javaScriptSemanticQueryResultSchema.parse({
+        schema_version: 1,
+        query_id: queryId,
+        source_graph_id: graph.graph_id,
+        seed: input.seed,
+        direction: input.direction,
+        status: assessment.status,
+        seed_node_ids: retainedSeeds,
+        nodes: page.pageNodes,
+        relations: page.pageRelations,
+        unknowns: relevantUnknowns,
+        expected_match_node_ids: expectedMatches.map(({ node_id }) => node_id),
+        summary: {
+            total_seed_matches: seeds.length,
+            retained_seed_matches: retainedSeeds.length,
+            traversed_nodes: traversal.nodeIds.size,
+            traversed_relations: traversal.relationIds.size,
+            traversed_functions: traversal.functionIds.size,
+            traversed_modules: traversal.modules.size,
+            relevant_unknowns: allRelevantUnknowns.length,
+            retained_unknowns: relevantUnknowns.length,
+        },
+        coverage: assessment.coverage,
+        page: {
+            offset,
+            size: page.pageRelations.length,
+            next_cursor: page.nextCursor,
+        },
+        applied_limits: input.limits,
+        accepted_limit_ranges: assessment.acceptedLimitRanges,
+        limitations: assessment.limitations,
+    });
+};
+const createQueryPage = ({ graph, traversal, query, queryId, offset, retainedSeeds, }) => {
+    const retainedNodes = graph.nodes.filter(({ node_id }) => traversal.nodeIds.has(node_id));
+    const retainedRelations = graph.relations.filter(({ relation_id }) => traversal.relationIds.has(relation_id));
+    if (offset > retainedRelations.length)
+        throw new JavaScriptSemanticQueryCursorError("Semantic query cursor is beyond the retained result");
+    const pageRelations = retainedRelations.slice(offset, offset + query.limits.page_size);
+    const pageNodeIds = new Set([
+        ...retainedSeeds,
+        ...pageRelations.flatMap(({ source_node_id, target_node_id }) => [
+            source_node_id,
+            target_node_id,
+        ]),
+    ]);
+    const pageNodes = graph.nodes.filter(({ node_id }) => pageNodeIds.has(node_id));
+    const nextOffset = offset + pageRelations.length;
+    return {
+        retainedNodes,
+        retainedRelations,
+        pageRelations,
+        pageNodes,
+        nextCursor: nextOffset < retainedRelations.length
+            ? createCursor(queryId, nextOffset)
+            : null,
+    };
+};
+const admitSeeds = (graph, seeds, input) => {
+    const nodes = new Map(graph.nodes.map((node) => [node.node_id, node]));
+    const retained = [];
+    const functions = new Set();
+    const modules = new Set();
+    const frontier = [];
+    for (const nodeId of seeds) {
+        const node = nodes.get(nodeId);
+        if (node === undefined)
+            continue;
+        const reason = seedBlockedReason(node, {
+            retained,
+            functions,
+            modules,
+            input,
+        });
+        if (reason !== null) {
+            frontier.push({ node_id: nodeId, depth: 0, reason });
+            continue;
+        }
+        retained.push(nodeId);
+        retainOwners(node, functions, modules);
+    }
+    return { nodeIds: retained, frontier: uniqueFrontier(frontier) };
+};
+const seedBlockedReason = (node, bounds) => {
+    if (bounds.retained.length >= bounds.input.limits.max_seed_matches)
+        return "max-seed-matches";
+    if (bounds.retained.length >= bounds.input.limits.max_nodes)
+        return "max-nodes";
+    const functionId = functionOwner(node);
+    if (functionId !== null &&
+        !bounds.functions.has(functionId) &&
+        bounds.functions.size >= bounds.input.limits.max_functions)
+        return "max-functions";
+    if (!bounds.modules.has(node.identity.module_path) &&
+        bounds.modules.size >= bounds.input.limits.max_modules)
+        return "max-modules";
+    return null;
+};
+const buildAdjacency = (relations, input) => {
+    const adjacency = new Map();
+    const allowed = input.allowed_relations === undefined
+        ? null
+        : new Set(input.allowed_relations);
+    for (const relation of relations) {
+        if (allowed !== null && !allowed.has(relation.relation))
+            continue;
+        if (relation.resolution === "candidate" &&
+            !input.include_ambiguous_dynamic_edges)
+            continue;
+        addDirectedEntries(adjacency, relation, input.direction);
+    }
+    for (const entries of adjacency.values())
+        entries.sort((left, right) => compareCodePoints(`${left.relation.relation_id}\0${left.nextNodeId}`, `${right.relation.relation_id}\0${right.nextNodeId}`));
+    return adjacency;
+};
+const addDirectedEntries = (adjacency, relation, direction) => {
+    if (direction === "callers") {
+        if (relation.relation === "calls")
+            addEntry(adjacency, relation.target_node_id, relation.source_node_id, relation);
+        return;
+    }
+    if (direction === "ownership") {
+        if (!ownershipRelation(relation.relation))
+            return;
+        addEntry(adjacency, relation.source_node_id, relation.target_node_id, relation);
+        addEntry(adjacency, relation.target_node_id, relation.source_node_id, relation);
+        return;
+    }
+    if (direction === "backward-provenance")
+        addEntry(adjacency, relation.target_node_id, relation.source_node_id, relation);
+    else
+        addEntry(adjacency, relation.source_node_id, relation.target_node_id, relation);
+};
+const addEntry = (adjacency, from, nextNodeId, relation) => {
+    const entries = adjacency.get(from) ?? [];
+    entries.push({ relation, nextNodeId });
+    adjacency.set(from, entries);
+};
+const traverse = (graph, seeds, adjacency, input) => {
+    const nodes = new Map(graph.nodes.map((node) => [node.node_id, node]));
+    const nodeIds = new Set(seeds);
+    const relationIds = new Set();
+    const functionIds = new Set();
+    const modules = new Set();
+    const frontier = [];
+    for (const nodeId of nodeIds)
+        retainOwners(nodes.get(nodeId), functionIds, modules);
+    const depths = new Map([...nodeIds].map((nodeId) => [nodeId, 0]));
+    const queue = [...nodeIds];
+    const bounds = {
+        nodes,
+        nodeIds,
+        relationIds,
+        functionIds,
+        modules,
+        input,
+    };
+    for (let offset = 0; offset < queue.length; offset += 1) {
+        const current = queue[offset];
+        if (current === undefined)
+            continue;
+        const depth = depths.get(current) ?? 0;
+        for (const entry of adjacency.get(current) ?? []) {
+            const reason = blockedReason(entry, depth, bounds);
+            if (reason !== null) {
+                frontier.push({ node_id: current, depth, reason });
+                continue;
+            }
+            relationIds.add(entry.relation.relation_id);
+            if (nodeIds.has(entry.nextNodeId))
+                continue;
+            const node = nodes.get(entry.nextNodeId);
+            if (node === undefined)
+                continue;
+            nodeIds.add(entry.nextNodeId);
+            retainOwners(node, functionIds, modules);
+            depths.set(entry.nextNodeId, depth + 1);
+            queue.push(entry.nextNodeId);
+        }
+    }
+    return {
+        nodeIds,
+        relationIds,
+        functionIds,
+        modules,
+        frontier: uniqueFrontier(frontier),
+    };
+};
+const blockedReason = (entry, depth, bounds) => {
+    if (depth >= bounds.input.limits.max_depth)
+        return "max-depth";
+    if (!bounds.relationIds.has(entry.relation.relation_id) &&
+        bounds.relationIds.size >= bounds.input.limits.max_edges)
+        return "max-edges";
+    if (bounds.nodeIds.has(entry.nextNodeId))
+        return null;
+    if (bounds.nodeIds.size >= bounds.input.limits.max_nodes)
+        return "max-nodes";
+    const node = bounds.nodes.get(entry.nextNodeId);
+    if (node === undefined)
+        return null;
+    const functionId = functionOwner(node);
+    if (functionId !== null &&
+        !bounds.functionIds.has(functionId) &&
+        bounds.functionIds.size >= bounds.input.limits.max_functions)
+        return "max-functions";
+    if (!bounds.modules.has(node.identity.module_path) &&
+        bounds.modules.size >= bounds.input.limits.max_modules)
+        return "max-modules";
+    return null;
+};
+const retainOwners = (node, functions, modules) => {
+    if (node === undefined)
+        return;
+    const functionId = functionOwner(node);
+    if (functionId !== null)
+        functions.add(functionId);
+    modules.add(node.identity.module_path);
+};
+const functionOwner = (node) => node.kind === "function" ? node.node_id : node.function_node_id;
+const uniqueFrontier = (frontier) => [
+    ...new Map(frontier.map((item) => [
+        `${item.node_id}\0${String(item.depth)}\0${item.reason}`,
+        item,
+    ])).values(),
+].sort((left, right) => compareCodePoints(canonicalJson(left), canonicalJson(right)));
+const relevantUnknownFrontiers = (graph, nodeIds, input) => {
+    const allowed = input.allowed_relations === undefined
+        ? null
+        : new Set(input.allowed_relations);
+    return graph.unknowns.filter((unknown) => (unknown.node_id === null || nodeIds.has(unknown.node_id)) &&
+        (allowed === null ||
+            unknown.relation_kinds.some((relation) => allowed.has(relation))));
+};
+const relevantCandidateRelationCount = (graph, nodeIds, input) => {
+    const allowed = input.allowed_relations === undefined
+        ? null
+        : new Set(input.allowed_relations);
+    return graph.relations.filter((relation) => relation.resolution === "candidate" &&
+        (allowed === null || allowed.has(relation.relation)) &&
+        (nodeIds.has(relation.source_node_id) ||
+            nodeIds.has(relation.target_node_id))).length;
+};
+const expectedMatchesFor = (nodes, relations, input) => {
+    if (input.expected === null)
+        return [];
+    const classes = new Set(input.expected.classes);
+    const connected = new Set(relations.map((relation) => input.expected?.role === "source"
+        ? relation.target_node_id
+        : relation.source_node_id));
+    return nodes.filter(({ kind, node_id }) => classes.has(kind) && !connected.has(node_id));
+};

package/dist/domain/javascriptSemanticQueryAssessment.js

@@ -0,0 +1,74 @@
+import { compareCodePoints } from "./javascriptApplicationGraph.js";
+/** Classify a bounded semantic traversal without promoting unknowns to absence. */
+export const assessJavaScriptSemanticQuery = (input) => ({
+    status: queryStatus(input),
+    coverage: queryCoverage(input),
+    limitations: queryLimitations(input),
+    acceptedLimitRanges: {
+        max_seed_matches: { minimum: 1, maximum: 1_000 },
+        max_nodes: { minimum: 1, maximum: 50_000 },
+        max_edges: { minimum: 1, maximum: 100_000 },
+        max_depth: { minimum: 0, maximum: 64 },
+        max_functions: { minimum: 1, maximum: 10_000 },
+        max_modules: { minimum: 1, maximum: 10_000 },
+        max_unknowns: { minimum: 0, maximum: 10_000 },
+        page_size: { minimum: 1, maximum: 1_000 },
+    },
+});
+const queryCoverage = (input) => ({
+    status: input.graph.coverage.status === "unavailable"
+        ? "unavailable"
+        : input.frontier.length > 0 || input.unknownsTruncated
+            ? "truncated"
+            : input.unknowns.length > 0 ||
+                input.candidateRelations > 0 ||
+                input.graph.coverage.status !== "complete"
+                ? "partial"
+                : "complete",
+    frontier: [...input.frontier],
+});
+const queryStatus = (input) => {
+    if (input.graph.coverage.status === "unavailable")
+        return "unsupported";
+    if (input.frontier.length > 0 || input.unknownsTruncated)
+        return "truncated";
+    if (input.candidateRelations > 0)
+        return "ambiguous";
+    if (input.totalSeeds === 0 ||
+        (input.hasExpectation && input.expectedMatches === 0))
+        return input.unknowns.length > 0 ||
+            input.graph.coverage.status !== "complete"
+            ? "partial"
+            : "no-match";
+    return input.totalSeeds > 1 ? "ambiguous" : "found";
+};
+const queryLimitations = (input) => uniqueSorted([
+    "Semantic graph reachability is a static inference and does not prove runtime execution.",
+    ...input.graph.limitations,
+    ...(input.totalSeeds === input.retainedSeeds
+        ? []
+        : [
+            "Seed matches exceeded caller bounds; omitted starts remain unexplored.",
+        ]),
+    ...(input.frontier.length === 0
+        ? []
+        : [
+            "Traversal stopped at explicit caller limits; frontier facts remain unknown.",
+        ]),
+    ...(input.unknowns.length === 0
+        ? []
+        : [
+            "Relevant dynamic, unsupported, incomplete, or ambiguous semantics remain unknown.",
+        ]),
+    ...(input.unknownsTruncated
+        ? [
+            "Relevant unknown frontiers exceeded the caller limit; omitted unknowns remain unresolved.",
+        ]
+        : []),
+    ...(input.candidateRelations === 0
+        ? []
+        : [
+            "Candidate relations remain ambiguous and do not establish a resolved semantic path.",
+        ]),
+]);
+const uniqueSorted = (values) => [...new Set(values)].sort(compareCodePoints);

package/dist/domain/javascriptSemanticQueryIdentity.js

@@ -0,0 +1,86 @@
+import { createHash } from "node:crypto";
+import canonicalize from "canonicalize";
+import { compareCodePoints } from "./javascriptApplicationGraph.js";
+/** Caller cursor that cannot identify a page of the current semantic query. */
+export class JavaScriptSemanticQueryCursorError extends TypeError {
+}
+/** Canonical JSON used by semantic query commitments and ordering. */
+export const canonicalJavaScriptSemanticQueryJson = (value) => {
+    const encoded = canonicalize(value);
+    if (encoded === undefined)
+        throw new TypeError("JavaScript semantic query could not canonicalize data");
+    return encoded;
+};
+const digest = (value) => createHash("sha256")
+    .update(canonicalJavaScriptSemanticQueryJson(value))
+    .digest("hex");
+const uniqueSorted = (values) => [...new Set(values)].sort(compareCodePoints);
+/** Derive the stable identity for one graph-bound query without its cursor. */
+export const javaScriptSemanticQueryIdentifier = (graph, input) => {
+    const { cursor: _cursor, ...semantic } = input;
+    return `jsrq_${digest({
+        source_graph_id: graph.graph_id,
+        ...semantic,
+        allowed_relations: semantic.allowed_relations === undefined
+            ? undefined
+            : uniqueSorted(semantic.allowed_relations),
+        expected: semantic.expected === null
+            ? null
+            : {
+                ...semantic.expected,
+                classes: uniqueSorted(semantic.expected.classes),
+            },
+    })}`;
+};
+/** Commit one deterministic relation-page offset to a query identity. */
+export const createJavaScriptSemanticQueryCursor = (queryId, offset) => `jsrqc_${String(offset)}_${digest({ query_id: queryId, offset })}`;
+/** Parse a query-bound cursor and reject stale, malformed, or foreign values. */
+export const parseJavaScriptSemanticQueryCursor = (cursor, queryId) => {
+    if (cursor === null)
+        return 0;
+    const match = /^jsrqc_([0-9]+)_([a-f0-9]{64})$/u.exec(cursor);
+    const offsetText = match?.[1];
+    const commitment = match?.[2];
+    if (offsetText === undefined || commitment === undefined)
+        throw new JavaScriptSemanticQueryCursorError("Semantic query cursor is malformed");
+    const offset = Number(offsetText);
+    if (!Number.isSafeInteger(offset) ||
+        offset < 0 ||
+        commitment !== digest({ query_id: queryId, offset }))
+        throw new JavaScriptSemanticQueryCursorError("Semantic query cursor does not match this query");
+    return offset;
+};
+/** Resolve deterministic seed candidates without applying traversal limits. */
+export const resolveJavaScriptSemanticQuerySeeds = (graph, input) => {
+    const fingerprintFunctions = new Set(input.seed.kind === "function"
+        ? graph.fingerprints
+            .filter(({ fingerprint_sha256 }) => input.seed.kind === "function" &&
+            fingerprint_sha256 === input.seed.fingerprint_sha256)
+            .map(({ function_node_id }) => function_node_id)
+        : []);
+    return graph.nodes
+        .filter((node) => seedMatches(node, input, fingerprintFunctions))
+        .map(({ node_id }) => node_id)
+        .sort(compareCodePoints);
+};
+const seedMatches = (node, input, fingerprintFunctions) => {
+    const seed = input.seed;
+    if (seed.kind === "semantic-node")
+        return node.node_id === seed.node_id;
+    if (seed.kind === "application-node")
+        return node.application_node_ids.includes(seed.node_id);
+    if (seed.kind === "function")
+        return fingerprintFunctions.has(node.node_id);
+    if (seed.kind === "literal")
+        return (node.kind === "literal" &&
+            canonicalJavaScriptSemanticQueryJson(node.properties.value) ===
+                canonicalJavaScriptSemanticQueryJson(seed.value));
+    if (seed.kind === "property")
+        return node.kind === "property-slot" && node.properties.name === seed.name;
+    if (seed.kind === "endpoint")
+        return node.kind === "request" && node.properties.endpoint === seed.value;
+    if (seed.kind === "event")
+        return (["event", "listener"].includes(node.kind) &&
+            node.properties.event_name === seed.name);
+    return node.kind === "boundary" && node.properties.field === seed.field;
+};