rea-agents 2.2.0 → 2.3.0

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;
+};

package/dist/domain/javascriptSemanticQueryRelations.js

@@ -0,0 +1,15 @@
+const OWNERSHIP_RELATIONS = new Set([
+    "acquires",
+    "aggregates",
+    "awaits",
+    "chains",
+    "connects-stdio",
+    "creates-promise",
+    "detaches-task",
+    "owns",
+    "releases",
+    "returns-task",
+    "spawns",
+]);
+/** Whether one relation participates in bidirectional ownership traversal. */
+export const isJavaScriptSemanticOwnershipRelation = (relation) => OWNERSHIP_RELATIONS.has(relation);

package/dist/domain/javascriptSemanticQuerySchemas.js

@@ -0,0 +1,188 @@
+import { z } from "zod";
+import { JAVASCRIPT_SEMANTIC_NODE_KINDS, JAVASCRIPT_SEMANTIC_RELATIONS, javaScriptSemanticNodeSchema, javaScriptSemanticRelationSchema, javaScriptSemanticUnknownSchema, } from "./javascriptSemanticGraphSchemas.js";
+import { jsonValueSchema } from "./jsonValue.js";
+const digestSchema = z.string().regex(/^[a-f0-9]{64}$/u);
+const semanticNodeIdSchema = z.string().regex(/^jsrg_node_[a-f0-9]{64}$/u);
+const literalSeedSchema = z.strictObject({
+    kind: z.literal("literal"),
+    value: jsonValueSchema.refine((value) => value === null ||
+        typeof value === "string" ||
+        typeof value === "number" ||
+        typeof value === "boolean", "Literal seeds accept only JSON primitive values"),
+});
+/** Authenticated starting points accepted by semantic tracing. */
+export const javaScriptSemanticQuerySeedSchema = z.discriminatedUnion("kind", [
+    z.strictObject({
+        kind: z.literal("semantic-node"),
+        node_id: semanticNodeIdSchema,
+    }),
+    z.strictObject({
+        kind: z.literal("application-node"),
+        node_id: z.string().regex(/^jag_node_[a-f0-9]{64}$/u),
+    }),
+    literalSeedSchema,
+    z.strictObject({
+        kind: z.literal("function"),
+        fingerprint_sha256: digestSchema,
+    }),
+    z.strictObject({
+        kind: z.literal("property"),
+        name: z.string().min(1).max(4_096),
+    }),
+    z.strictObject({
+        kind: z.literal("endpoint"),
+        value: z.string().min(1).max(16_384),
+    }),
+    z.strictObject({
+        kind: z.literal("event"),
+        name: z.string().min(1).max(4_096),
+    }),
+    z.strictObject({
+        kind: z.literal("boundary-field"),
+        field: z.string().min(1).max(4_096),
+    }),
+]);
+/** Strict caller limits for deterministic bounded traversal. */
+export const javaScriptSemanticQueryLimitsSchema = z.strictObject({
+    max_seed_matches: z.number().int().min(1).max(1_000).default(25),
+    max_nodes: z.number().int().min(1).max(50_000).default(2_000),
+    max_edges: z.number().int().min(1).max(100_000).default(4_000),
+    max_depth: z.number().int().min(0).max(64).default(12),
+    max_functions: z.number().int().min(1).max(10_000).default(500),
+    max_modules: z.number().int().min(1).max(10_000).default(500),
+    max_unknowns: z.number().int().min(0).max(10_000).default(1_000),
+    page_size: z.number().int().min(1).max(1_000).default(200),
+});
+const sourceMapAuthoritySchema = z.strictObject({
+    authority: z.literal("none"),
+});
+/** Parsed pure-domain query over one authenticated companion graph. */
+export const javaScriptSemanticQueryInputSchema = z.strictObject({
+    seed: javaScriptSemanticQuerySeedSchema,
+    direction: z.enum([
+        "backward-provenance",
+        "forward-influence",
+        "callers",
+        "ownership",
+    ]),
+    allowed_relations: z
+        .array(z.enum(JAVASCRIPT_SEMANTIC_RELATIONS))
+        .min(1)
+        .max(JAVASCRIPT_SEMANTIC_RELATIONS.length)
+        .optional(),
+    include_ambiguous_dynamic_edges: z.boolean().default(false),
+    expected: z
+        .strictObject({
+        role: z.enum(["source", "sink"]),
+        classes: z.array(z.enum(JAVASCRIPT_SEMANTIC_NODE_KINDS)).min(1).max(24),
+    })
+        .nullable()
+        .default(null),
+    source_map_authority: sourceMapAuthoritySchema.default({ authority: "none" }),
+    limits: javaScriptSemanticQueryLimitsSchema.default({
+        max_seed_matches: 25,
+        max_nodes: 2_000,
+        max_edges: 4_000,
+        max_depth: 12,
+        max_functions: 500,
+        max_modules: 500,
+        max_unknowns: 1_000,
+        page_size: 200,
+    }),
+    cursor: z
+        .string()
+        .regex(/^jsrqc_[0-9]+_[a-f0-9]{64}$/u)
+        .nullable()
+        .default(null),
+});
+const queryFrontierSchema = z.strictObject({
+    node_id: semanticNodeIdSchema,
+    depth: z.number().int().min(0).max(65),
+    reason: z.enum([
+        "max-depth",
+        "max-edges",
+        "max-functions",
+        "max-modules",
+        "max-nodes",
+        "max-seed-matches",
+    ]),
+});
+/** Deterministic, pageable semantic trace result. */
+export const javaScriptSemanticQueryResultSchema = z.strictObject({
+    schema_version: z.literal(1),
+    query_id: z.string().regex(/^jsrq_[a-f0-9]{64}$/u),
+    source_graph_id: z.string().regex(/^jsrg_[a-f0-9]{64}$/u),
+    seed: javaScriptSemanticQuerySeedSchema,
+    direction: javaScriptSemanticQueryInputSchema.shape.direction,
+    status: z.enum([
+        "found",
+        "no-match",
+        "ambiguous",
+        "partial",
+        "truncated",
+        "unsupported",
+    ]),
+    seed_node_ids: z.array(semanticNodeIdSchema).max(1_000),
+    nodes: z.array(javaScriptSemanticNodeSchema).max(3_000),
+    relations: z.array(javaScriptSemanticRelationSchema).max(1_000),
+    unknowns: z.array(javaScriptSemanticUnknownSchema).max(100_000),
+    expected_match_node_ids: z.array(semanticNodeIdSchema).max(50_000),
+    summary: z.strictObject({
+        total_seed_matches: z.number().int().min(0),
+        retained_seed_matches: z.number().int().min(0),
+        traversed_nodes: z.number().int().min(0),
+        traversed_relations: z.number().int().min(0),
+        traversed_functions: z.number().int().min(0),
+        traversed_modules: z.number().int().min(0),
+        relevant_unknowns: z.number().int().min(0),
+        retained_unknowns: z.number().int().min(0).max(10_000),
+    }),
+    coverage: z.strictObject({
+        status: z.enum(["complete", "partial", "truncated", "unavailable"]),
+        frontier: z.array(queryFrontierSchema).max(100_000),
+    }),
+    page: z.strictObject({
+        offset: z.number().int().min(0),
+        size: z.number().int().min(0).max(1_000),
+        next_cursor: z
+            .string()
+            .regex(/^jsrqc_[0-9]+_[a-f0-9]{64}$/u)
+            .nullable(),
+    }),
+    applied_limits: javaScriptSemanticQueryLimitsSchema,
+    accepted_limit_ranges: z.strictObject({
+        max_seed_matches: z.strictObject({
+            minimum: z.literal(1),
+            maximum: z.literal(1_000),
+        }),
+        max_nodes: z.strictObject({
+            minimum: z.literal(1),
+            maximum: z.literal(50_000),
+        }),
+        max_edges: z.strictObject({
+            minimum: z.literal(1),
+            maximum: z.literal(100_000),
+        }),
+        max_depth: z.strictObject({
+            minimum: z.literal(0),
+            maximum: z.literal(64),
+        }),
+        max_functions: z.strictObject({
+            minimum: z.literal(1),
+            maximum: z.literal(10_000),
+        }),
+        max_modules: z.strictObject({
+            minimum: z.literal(1),
+            maximum: z.literal(10_000),
+        }),
+        max_unknowns: z.strictObject({
+            minimum: z.literal(0),
+            maximum: z.literal(10_000),
+        }),
+        page_size: z.strictObject({
+            minimum: z.literal(1),
+            maximum: z.literal(1_000),
+        }),
+    }),
+    limitations: z.array(z.string().min(1).max(4_096)).max(1_000),
+});