Skip to content

armgit / rea

Public Imported from GitHub
0

Reverse engineer anything with agents, from app behavior down to native binaries.

feat(javascript): add bounded semantic relation graph

morlutob3939ea9ffc7
diff --git a/src/domain/javascriptSemanticGraph.ts b/src/domain/javascriptSemanticGraph.ts
new file mode 100644
index 000000000..257e3adf3
--- /dev/null
+++ b/src/domain/javascriptSemanticGraph.ts
@@ -0,0 +1,546 @@
+import { createHash } from "node:crypto";
+
+import canonicalize from "canonicalize";
+import { z } from "zod";
+
+import { compareCodePoints } from "./javascriptApplicationGraph.js";
+import type { ApplicationGraphEvidence } from "./javascriptApplicationEvidenceSchemas.js";
+import {
+ JAVASCRIPT_SEMANTIC_RELATION_FAMILIES,
+ JAVASCRIPT_SEMANTIC_RELATION_FAMILY,
+ javaScriptSemanticFingerprintInputSchema,
+ javaScriptSemanticFingerprintSchema,
+ javaScriptSemanticGraphInputSchema,
+ javaScriptSemanticGraphRecordSchema,
+ javaScriptSemanticNodeInputSchema,
+ javaScriptSemanticNodeSchema,
+ javaScriptSemanticRelationInputSchema,
+ javaScriptSemanticRelationSchema,
+ javaScriptSemanticUnknownInputSchema,
+ javaScriptSemanticUnknownSchema,
+ type JavaScriptSemanticGraphInput,
+ type JavaScriptSemanticGraphNode,
+ type JavaScriptSemanticGraphRelation,
+} from "./javascriptSemanticGraphSchemas.js";
+
+const canonicalJson = (value: unknown): string => {
+ const encoded = canonicalize(value);
+ if (encoded === undefined)
+ throw new TypeError(
+ "JavaScript semantic graph could not canonicalize data",
+ );
+ return encoded;
+};
+
+const digestCanonical = (value: unknown): string =>
+ createHash("sha256").update(canonicalJson(value)).digest("hex");
+
+const uniqueSorted = <Value extends string>(
+ values: readonly Value[],
+): Value[] => [...new Set(values)].sort(compareCodePoints);
+
+const normalizeEvidence = (
+ evidence: ApplicationGraphEvidence,
+): ApplicationGraphEvidence => ({
+ ...evidence,
+ coverage: {
+ ...evidence.coverage,
+ limits: [...evidence.coverage.limits].sort((left, right) =>
+ compareCodePoints(canonicalJson(left), canonicalJson(right)),
+ ),
+ },
+ limitations: uniqueSorted(evidence.limitations),
+ evidence_ids: uniqueSorted(evidence.evidence_ids),
+});
+
+const nodeIdentity = (
+ node: Pick<JavaScriptSemanticGraphNode, "kind" | "identity">,
+) => ({ kind: node.kind, identity: node.identity });
+
+const nodeId = (
+ node: Pick<JavaScriptSemanticGraphNode, "kind" | "identity">,
+): string => `jsrg_node_${digestCanonical(nodeIdentity(node))}`;
+
+/** Normalize one semantic entity and derive its artifact-version identifier. */
+export const createJavaScriptSemanticGraphNode = (
+ input: unknown,
+): JavaScriptSemanticGraphNode => {
+ const parsed = javaScriptSemanticNodeInputSchema.parse(input);
+ const semantic = {
+ ...parsed,
+ application_node_ids: uniqueSorted(parsed.application_node_ids),
+ evidence: normalizeEvidence(parsed.evidence),
+ identifier_strategy: {
+ strategy: "semantic-content-sha256" as const,
+ stability: "artifact-version" as const,
+ },
+ };
+ return javaScriptSemanticNodeSchema.parse({
+ ...semantic,
+ node_id: nodeId(semantic),
+ });
+};
+
+/** Normalize one semantic relationship and derive its exact identifier. */
+export const createJavaScriptSemanticGraphRelation = (
+ input: unknown,
+): JavaScriptSemanticGraphRelation => {
+ const parsed = javaScriptSemanticRelationInputSchema.parse(input);
+ const semantic = {
+ ...parsed,
+ evidence: normalizeEvidence(parsed.evidence),
+ identifier_strategy: {
+ strategy: "semantic-content-sha256" as const,
+ stability: "relationship-exact" as const,
+ },
+ };
+ return javaScriptSemanticRelationSchema.parse({
+ ...semantic,
+ relation_id: `jsrg_relation_${digestCanonical(semantic)}`,
+ });
+};
+
+/** Normalize one unresolved semantic frontier and derive its identifier. */
+export const createJavaScriptSemanticGraphUnknown = (input: unknown) => {
+ const parsed = javaScriptSemanticUnknownInputSchema.parse(input);
+ const semantic = {
+ ...parsed,
+ relation_kinds: uniqueSorted(parsed.relation_kinds),
+ candidate_node_ids: uniqueSorted(parsed.candidate_node_ids),
+ evidence: normalizeEvidence(parsed.evidence),
+ };
+ return javaScriptSemanticUnknownSchema.parse({
+ ...semantic,
+ unknown_id: `jsrg_unknown_${digestCanonical(semantic)}`,
+ });
+};
+
+/** Normalize one function fingerprint and derive its component commitment. */
+export const createJavaScriptSemanticFingerprint = (input: unknown) => {
+ const parsed = javaScriptSemanticFingerprintInputSchema.parse(input);
+ const semantic = {
+ ...parsed,
+ components: {
+ ...parsed.components,
+ effects: uniqueSorted(parsed.components.effects),
+ },
+ limitations: uniqueSorted(parsed.limitations),
+ evidence: normalizeEvidence(parsed.evidence),
+ };
+ const fingerprintSha256 = digestCanonical(semantic.components);
+ return javaScriptSemanticFingerprintSchema.parse({
+ ...semantic,
+ fingerprint_sha256: fingerprintSha256,
+ fingerprint_id: `jsrg_fingerprint_${digestCanonical({
+ function_node_id: semantic.function_node_id,
+ algorithm: semantic.algorithm,
+ fingerprint_sha256: fingerprintSha256,
+ })}`,
+ });
+};
+
+type GraphRecord = z.infer<typeof javaScriptSemanticGraphRecordSchema>;
+
+const sortedUniqueIssue = (
+ values: readonly string[],
+ path: PropertyKey[],
+ label: string,
+ context: z.RefinementCtx,
+): void => {
+ for (let index = 1; index < values.length; index += 1) {
+ if (compareCodePoints(values[index - 1] ?? "", values[index] ?? "") < 0)
+ continue;
+ context.addIssue({
+ code: "custom",
+ path: [...path, index],
+ message: `${label} must be sorted and unique`,
+ });
+ return;
+ }
+};
+
+const checkCoverage = (graph: GraphRecord, context: z.RefinementCtx): void => {
+ const families = graph.coverage.families.map(({ family }) => family);
+ if (
+ canonicalJson(families) !==
+ canonicalJson(JAVASCRIPT_SEMANTIC_RELATION_FAMILIES)
+ )
+ context.addIssue({
+ code: "custom",
+ path: ["coverage", "families"],
+ message:
+ "Coverage must name every semantic relation family once in canonical order",
+ });
+ if (
+ graph.coverage.status === "complete" &&
+ (graph.coverage.truncated ||
+ graph.coverage.omitted_nodes !== 0 ||
+ graph.coverage.omitted_relations !== 0 ||
+ graph.coverage.families.some(({ status }) => status !== "complete"))
+ )
+ context.addIssue({
+ code: "custom",
+ path: ["coverage"],
+ message: "Complete graph coverage cannot omit or truncate semantic facts",
+ });
+ if (graph.coverage.truncated && graph.coverage.limits.length === 0)
+ context.addIssue({
+ code: "custom",
+ path: ["coverage", "limits"],
+ message: "Truncated graph coverage must identify an effective limit",
+ });
+ const relationsByFamily = new Map(
+ JAVASCRIPT_SEMANTIC_RELATION_FAMILIES.map((family) => [family, 0]),
+ );
+ for (const relation of graph.relations) {
+ const family = JAVASCRIPT_SEMANTIC_RELATION_FAMILY[relation.relation];
+ relationsByFamily.set(family, (relationsByFamily.get(family) ?? 0) + 1);
+ }
+ const unknownsById = new Map(
+ graph.unknowns.map((unknown) => [unknown.unknown_id, unknown]),
+ );
+ for (const [index, family] of graph.coverage.families.entries()) {
+ if (family.retained_relations !== relationsByFamily.get(family.family))
+ context.addIssue({
+ code: "custom",
+ path: ["coverage", "families", index, "retained_relations"],
+ message: "Family retained relation count does not match graph content",
+ });
+ if (
+ family.unknown_ids.some(
+ (identifier) => unknownsById.get(identifier)?.family !== family.family,
+ )
+ )
+ context.addIssue({
+ code: "custom",
+ path: ["coverage", "families", index, "unknown_ids"],
+ message: "Family coverage references an unknown from another family",
+ });
+ if (
+ family.status === "complete" &&
+ (family.omitted_relations !== 0 || family.unknown_ids.length > 0)
+ )
+ context.addIssue({
+ code: "custom",
+ path: ["coverage", "families", index],
+ message: "Complete family coverage cannot omit or retain unknown facts",
+ });
+ }
+};
+
+const checkCanonicalOrder = (
+ graph: GraphRecord,
+ context: z.RefinementCtx,
+): void => {
+ sortedUniqueIssue(
+ graph.root_node_ids,
+ ["root_node_ids"],
+ "Root nodes",
+ context,
+ );
+ sortedUniqueIssue(
+ graph.nodes.map(({ node_id }) => node_id),
+ ["nodes"],
+ "Nodes",
+ context,
+ );
+ sortedUniqueIssue(
+ graph.relations.map(({ relation_id }) => relation_id),
+ ["relations"],
+ "Relations",
+ context,
+ );
+ sortedUniqueIssue(
+ graph.fingerprints.map(({ fingerprint_id }) => fingerprint_id),
+ ["fingerprints"],
+ "Fingerprints",
+ context,
+ );
+ sortedUniqueIssue(
+ graph.unknowns.map(({ unknown_id }) => unknown_id),
+ ["unknowns"],
+ "Unknown frontiers",
+ context,
+ );
+ sortedUniqueIssue(graph.limitations, ["limitations"], "Limitations", context);
+};
+
+const checkNodes = (
+ graph: GraphRecord,
+ nodes: ReadonlyMap<string, JavaScriptSemanticGraphNode>,
+ context: z.RefinementCtx,
+): void => {
+ for (const [index, node] of graph.nodes.entries()) {
+ if (node.node_id !== nodeId(node))
+ context.addIssue({
+ code: "custom",
+ path: ["nodes", index, "node_id"],
+ message: "Node identifier is stale",
+ });
+ if (
+ node.function_node_id !== null &&
+ nodes.get(node.function_node_id)?.kind !== "function"
+ )
+ context.addIssue({
+ code: "custom",
+ path: ["nodes", index, "function_node_id"],
+ message: "Function owner must name a function node",
+ });
+ }
+};
+
+const checkRoots = (
+ graph: GraphRecord,
+ nodes: ReadonlyMap<string, JavaScriptSemanticGraphNode>,
+ context: z.RefinementCtx,
+): void => {
+ for (const root of graph.root_node_ids)
+ if (!nodes.has(root))
+ context.addIssue({
+ code: "custom",
+ path: ["root_node_ids"],
+ message: "Root identifier must name a semantic node",
+ });
+};
+
+const checkRelations = (
+ graph: GraphRecord,
+ nodes: ReadonlyMap<string, JavaScriptSemanticGraphNode>,
+ context: z.RefinementCtx,
+): void => {
+ for (const [index, relation] of graph.relations.entries()) {
+ const { relation_id: identifier, ...semantic } = relation;
+ if (identifier !== "jsrg_relation_" + digestCanonical(semantic))
+ context.addIssue({
+ code: "custom",
+ path: ["relations", index, "relation_id"],
+ message: "Relation identifier is stale",
+ });
+ if (
+ !nodes.has(relation.source_node_id) ||
+ !nodes.has(relation.target_node_id)
+ )
+ context.addIssue({
+ code: "custom",
+ path: ["relations", index],
+ message: "Relation endpoints must name semantic nodes",
+ });
+ if (relation.source_node_id === relation.target_node_id)
+ context.addIssue({
+ code: "custom",
+ path: ["relations", index],
+ message: "Semantic relations cannot be self-referential",
+ });
+ if (
+ relation.resolution === "candidate" &&
+ relation.evidence.state === "observed"
+ )
+ context.addIssue({
+ code: "custom",
+ path: ["relations", index, "evidence", "state"],
+ message: "Candidate relations cannot claim observed resolution",
+ });
+ }
+};
+
+const checkUnknowns = (
+ graph: GraphRecord,
+ nodes: ReadonlyMap<string, JavaScriptSemanticGraphNode>,
+ context: z.RefinementCtx,
+): void => {
+ for (const [index, unknown] of graph.unknowns.entries()) {
+ const { unknown_id: identifier, ...semantic } = unknown;
+ if (identifier !== "jsrg_unknown_" + digestCanonical(semantic))
+ context.addIssue({
+ code: "custom",
+ path: ["unknowns", index, "unknown_id"],
+ message: "Unknown frontier identifier is stale",
+ });
+ if (unknown.node_id !== null && !nodes.has(unknown.node_id))
+ context.addIssue({
+ code: "custom",
+ path: ["unknowns", index, "node_id"],
+ message: "Unknown frontier node is absent",
+ });
+ if (
+ unknown.relation_kinds.some(
+ (kind) => JAVASCRIPT_SEMANTIC_RELATION_FAMILY[kind] !== unknown.family,
+ )
+ )
+ context.addIssue({
+ code: "custom",
+ path: ["unknowns", index, "relation_kinds"],
+ message: "Unknown relation kinds must belong to their declared family",
+ });
+ if (!["unknown", "unavailable"].includes(unknown.evidence.state))
+ context.addIssue({
+ code: "custom",
+ path: ["unknowns", index, "evidence", "state"],
+ message: "Unknown frontiers require unknown or unavailable evidence",
+ });
+ }
+};
+
+const checkUnknownReferences = (
+ graph: GraphRecord,
+ context: z.RefinementCtx,
+): void => {
+ const unknownIds = new Set(
+ graph.unknowns.map(({ unknown_id }) => unknown_id),
+ );
+ for (const [index, family] of graph.coverage.families.entries())
+ if (family.unknown_ids.some((identifier) => !unknownIds.has(identifier)))
+ context.addIssue({
+ code: "custom",
+ path: ["coverage", "families", index, "unknown_ids"],
+ message: "Family coverage references an absent unknown frontier",
+ });
+};
+
+const checkFingerprints = (
+ graph: GraphRecord,
+ nodes: ReadonlyMap<string, JavaScriptSemanticGraphNode>,
+ context: z.RefinementCtx,
+): void => {
+ for (const [index, fingerprint] of graph.fingerprints.entries()) {
+ if (nodes.get(fingerprint.function_node_id)?.kind !== "function")
+ context.addIssue({
+ code: "custom",
+ path: ["fingerprints", index, "function_node_id"],
+ message: "Fingerprint must name a function node",
+ });
+ if (
+ fingerprint.fingerprint_sha256 !== digestCanonical(fingerprint.components)
+ )
+ context.addIssue({
+ code: "custom",
+ path: ["fingerprints", index, "fingerprint_sha256"],
+ message: "Fingerprint component commitment is stale",
+ });
+ const expectedIdentifier =
+ "jsrg_fingerprint_" +
+ digestCanonical({
+ function_node_id: fingerprint.function_node_id,
+ algorithm: fingerprint.algorithm,
+ fingerprint_sha256: fingerprint.fingerprint_sha256,
+ });
+ if (fingerprint.fingerprint_id !== expectedIdentifier)
+ context.addIssue({
+ code: "custom",
+ path: ["fingerprints", index, "fingerprint_id"],
+ message: "Fingerprint identifier is stale",
+ });
+ if (
+ fingerprint.status !== "complete" &&
+ fingerprint.limitations.length === 0
+ )
+ context.addIssue({
+ code: "custom",
+ path: ["fingerprints", index, "limitations"],
+ message: "Incomplete fingerprints require a limitation",
+ });
+ }
+};
+
+const checkGraph = (graph: GraphRecord, context: z.RefinementCtx): void => {
+ checkCanonicalOrder(graph, context);
+ const nodes = new Map(graph.nodes.map((node) => [node.node_id, node]));
+ checkNodes(graph, nodes, context);
+ checkRoots(graph, nodes, context);
+ checkRelations(graph, nodes, context);
+ checkUnknowns(graph, nodes, context);
+ checkUnknownReferences(graph, context);
+ checkFingerprints(graph, nodes, context);
+ checkCoverage(graph, context);
+ if (graph.coverage.status !== "complete" && graph.limitations.length === 0)
+ context.addIssue({
+ code: "custom",
+ path: ["limitations"],
+ message: "Non-complete graph coverage requires a limitation",
+ });
+ const { graph_id: identifier, ...semantic } = graph;
+ if (identifier !== "jsrg_" + digestCanonical(semantic))
+ context.addIssue({
+ code: "custom",
+ path: ["graph_id"],
+ message: "Graph identifier is stale",
+ });
+};
+
+/** Strict semantic graph schema with verified canonical commitments. */
+export const javaScriptSemanticGraphSchema =
+ javaScriptSemanticGraphRecordSchema.superRefine(checkGraph);
+
+/** Fully validated JavaScript Semantic Relation Graph v1. */
+export type JavaScriptSemanticGraph = z.infer<
+ typeof javaScriptSemanticGraphSchema
+>;
+
+/** Normalize a complete companion graph and derive its graph ID. */
+export const createJavaScriptSemanticGraph = (
+ input: unknown,
+): JavaScriptSemanticGraph => {
+ const parsed = javaScriptSemanticGraphInputSchema.parse(input);
+ const semantic: JavaScriptSemanticGraphInput = {
+ ...parsed,
+ root_node_ids: uniqueSorted(parsed.root_node_ids),
+ nodes: [...parsed.nodes].sort((left, right) =>
+ compareCodePoints(left.node_id, right.node_id),
+ ),
+ relations: [...parsed.relations].sort((left, right) =>
+ compareCodePoints(left.relation_id, right.relation_id),
+ ),
+ fingerprints: [...parsed.fingerprints].sort((left, right) =>
+ compareCodePoints(left.fingerprint_id, right.fingerprint_id),
+ ),
+ unknowns: [...parsed.unknowns].sort((left, right) =>
+ compareCodePoints(left.unknown_id, right.unknown_id),
+ ),
+ coverage: {
+ ...parsed.coverage,
+ limits: [...parsed.coverage.limits].sort((left, right) =>
+ compareCodePoints(canonicalJson(left), canonicalJson(right)),
+ ),
+ families: [...parsed.coverage.families]
+ .map((family) => ({
+ ...family,
+ unknown_ids: uniqueSorted(family.unknown_ids),
+ }))
+ .sort((left, right) => compareCodePoints(left.family, right.family)),
+ },
+ limitations: uniqueSorted(parsed.limitations),
+ };
+ return javaScriptSemanticGraphSchema.parse({
+ ...semantic,
+ graph_id: `jsrg_${digestCanonical(semantic)}`,
+ });
+};
+
+/** Parse a stored semantic graph and reject unsupported versions or stale IDs. */
+export const parseJavaScriptSemanticGraph = (
+ input: unknown,
+): JavaScriptSemanticGraph => {
+ 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: unknown): string =>
+ canonicalJson(parseJavaScriptSemanticGraph(input));
+
+/** Compute the canonical SHA-256 commitment of a verified semantic graph. */
+export const computeJavaScriptSemanticGraphSha256 = (input: unknown): string =>
+ digestCanonical(parseJavaScriptSemanticGraph(input));
+
+export type { JavaScriptSemanticGraphNode, JavaScriptSemanticGraphRelation };
diff --git a/src/domain/javascriptSemanticGraphSchemas.ts b/src/domain/javascriptSemanticGraphSchemas.ts
new file mode 100644
index 000000000..ad7246147
--- /dev/null
+++ b/src/domain/javascriptSemanticGraphSchemas.ts
@@ -0,0 +1,393 @@
+import { z } from "zod";
+
+import { applicationGraphEvidenceSchema } from "./javascriptApplicationEvidenceSchemas.js";
+import { isJsonWithinLimits } from "./jsonLimits.js";
+import { jsonValueSchema } from "./jsonValue.js";
+
+const digestSchema = z.string().regex(/^[a-f0-9]{64}$/u);
+const boundedTextSchema = z.string().min(1).max(4_096);
+const semanticNodeIdSchema = z.string().regex(/^jsrg_node_[a-f0-9]{64}$/u);
+const semanticRelationIdSchema = z
+ .string()
+ .regex(/^jsrg_relation_[a-f0-9]{64}$/u);
+const semanticUnknownIdSchema = z
+ .string()
+ .regex(/^jsrg_unknown_[a-f0-9]{64}$/u);
+
+/** Semantic entity kinds admitted by JavaScript Semantic Relation Graph v1. */
+export const JAVASCRIPT_SEMANTIC_NODE_KINDS = [
+ "module",
+ "function",
+ "parameter",
+ "binding",
+ "expression",
+ "literal",
+ "property-slot",
+ "call-site",
+ "return-site",
+ "closure-capture",
+ "promise",
+ "task",
+ "event",
+ "listener",
+ "timer",
+ "child-process",
+ "stdio",
+ "signal",
+ "config-source",
+ "request",
+ "response",
+ "boundary",
+ "resource",
+ "unknown-frontier",
+] as const;
+
+/** Required semantic-analysis coverage families. */
+export const JAVASCRIPT_SEMANTIC_RELATION_FAMILIES = [
+ "boundary",
+ "call-flow",
+ "child-process",
+ "closure",
+ "configuration",
+ "data-flow",
+ "event",
+ "object-flow",
+ "promise-ownership",
+ "request",
+ "resource-lifecycle",
+ "timer",
+] as const;
+
+/** Directed semantic relations admitted by graph v1. */
+export const JAVASCRIPT_SEMANTIC_RELATIONS = [
+ "acquires",
+ "aggregates",
+ "aliases",
+ "argument-to-parameter",
+ "awaits",
+ "calls",
+ "cancels-timer",
+ "captures",
+ "chains",
+ "coerces",
+ "connects-stdio",
+ "consumed-by",
+ "constructs-request",
+ "creates-promise",
+ "defaults",
+ "defines",
+ "destructures",
+ "detaches-task",
+ "dispatches-candidate",
+ "forwards-signal",
+ "listens-error",
+ "listens-exit",
+ "owns",
+ "overrides",
+ "parses",
+ "reads",
+ "reads-argv",
+ "reads-config",
+ "reads-environment",
+ "reads-property",
+ "registers-listener",
+ "releases",
+ "removes-listener",
+ "returns-task",
+ "returns-to-call",
+ "schedules-timer",
+ "spawns",
+ "spreads",
+ "supplies-argv",
+ "supplies-env",
+ "supplies-request-field",
+ "validates",
+ "writes",
+ "writes-property",
+] as const;
+
+/** Map each semantic relation to its coverage family. */
+export const JAVASCRIPT_SEMANTIC_RELATION_FAMILY = {
+ acquires: "resource-lifecycle",
+ aggregates: "promise-ownership",
+ aliases: "data-flow",
+ "argument-to-parameter": "call-flow",
+ awaits: "promise-ownership",
+ calls: "call-flow",
+ "cancels-timer": "timer",
+ captures: "closure",
+ chains: "promise-ownership",
+ coerces: "boundary",
+ "connects-stdio": "child-process",
+ "consumed-by": "request",
+ "constructs-request": "request",
+ "creates-promise": "promise-ownership",
+ defaults: "configuration",
+ defines: "data-flow",
+ destructures: "object-flow",
+ "detaches-task": "promise-ownership",
+ "dispatches-candidate": "event",
+ "forwards-signal": "child-process",
+ "listens-error": "child-process",
+ "listens-exit": "child-process",
+ owns: "promise-ownership",
+ overrides: "configuration",
+ parses: "boundary",
+ reads: "data-flow",
+ "reads-argv": "configuration",
+ "reads-config": "configuration",
+ "reads-environment": "configuration",
+ "reads-property": "object-flow",
+ "registers-listener": "event",
+ releases: "resource-lifecycle",
+ "removes-listener": "event",
+ "returns-task": "promise-ownership",
+ "returns-to-call": "call-flow",
+ "schedules-timer": "timer",
+ spawns: "child-process",
+ spreads: "object-flow",
+ "supplies-argv": "child-process",
+ "supplies-env": "child-process",
+ "supplies-request-field": "request",
+ validates: "boundary",
+ writes: "data-flow",
+ "writes-property": "object-flow",
+} as const satisfies Readonly<
+ Record<
+ (typeof JAVASCRIPT_SEMANTIC_RELATIONS)[number],
+ (typeof JAVASCRIPT_SEMANTIC_RELATION_FAMILIES)[number]
+ >
+>;
+
+const relativePathSchema = z
+ .string()
+ .min(1)
+ .max(4_096)
+ .refine(
+ (path) =>
+ !path.startsWith("/") &&
+ !path.includes("\\") &&
+ path.split("/").every((part) => !["", ".", ".."].includes(part)),
+ "Expected a normalized relative POSIX path without traversal",
+ );
+
+const sourcePointSchema = z.strictObject({
+ line: z.number().int().min(1),
+ column: z.number().int().min(0),
+});
+
+const sourceRangeSchema = z
+ .strictObject({ start: sourcePointSchema, end: sourcePointSchema })
+ .superRefine((range, context) => {
+ if (
+ range.end.line < range.start.line ||
+ (range.end.line === range.start.line &&
+ range.end.column < range.start.column)
+ )
+ context.addIssue({
+ code: "custom",
+ path: ["end"],
+ message: "Source range end must not precede its start",
+ });
+ });
+
+const semanticPropertiesSchema = z
+ .record(z.string().min(1).max(128), jsonValueSchema)
+ .superRefine((properties, context) => {
+ if (Object.keys(properties).length > 64)
+ context.addIssue({
+ code: "custom",
+ message: "Semantic properties exceed 64 keys",
+ });
+ if (
+ !isJsonWithinLimits(properties, {
+ maxDepth: 6,
+ maxNodes: 512,
+ maxStringLength: 4_096,
+ })
+ )
+ context.addIssue({
+ code: "custom",
+ message: "Semantic properties exceed structural limits",
+ });
+ });
+
+const semanticNodeIdentitySchema = z.strictObject({
+ artifact_sha256: digestSchema,
+ module_path: relativePathSchema,
+ source_range: sourceRangeSchema.nullable(),
+ role_key: z.string().min(1).max(1_024),
+});
+
+/** One semantic entity before its canonical identifier is derived. */
+export const javaScriptSemanticNodeInputSchema = z.strictObject({
+ kind: z.enum(JAVASCRIPT_SEMANTIC_NODE_KINDS),
+ identity: semanticNodeIdentitySchema,
+ function_node_id: semanticNodeIdSchema.nullable(),
+ application_node_ids: z
+ .array(z.string().regex(/^jag_node_[a-f0-9]{64}$/u))
+ .max(64),
+ label: z.string().min(1).max(1_024).nullable(),
+ properties: semanticPropertiesSchema,
+ evidence: applicationGraphEvidenceSchema,
+});
+
+/** One exact, artifact-version semantic entity. */
+export const javaScriptSemanticNodeSchema =
+ javaScriptSemanticNodeInputSchema.extend({
+ node_id: semanticNodeIdSchema,
+ identifier_strategy: z.strictObject({
+ strategy: z.literal("semantic-content-sha256"),
+ stability: z.literal("artifact-version"),
+ }),
+ });
+
+/** One directed semantic relationship before its ID is derived. */
+export const javaScriptSemanticRelationInputSchema = z.strictObject({
+ source_node_id: semanticNodeIdSchema,
+ target_node_id: semanticNodeIdSchema,
+ relation: z.enum(JAVASCRIPT_SEMANTIC_RELATIONS),
+ resolution: z.enum(["resolved", "candidate"]),
+ properties: semanticPropertiesSchema,
+ evidence: applicationGraphEvidenceSchema,
+});
+
+/** One canonical directed semantic relationship. */
+export const javaScriptSemanticRelationSchema =
+ javaScriptSemanticRelationInputSchema.extend({
+ relation_id: semanticRelationIdSchema,
+ identifier_strategy: z.strictObject({
+ strategy: z.literal("semantic-content-sha256"),
+ stability: z.literal("relationship-exact"),
+ }),
+ });
+
+/** Reasons semantic analysis can leave an explicit frontier. */
+export const JAVASCRIPT_SEMANTIC_UNKNOWN_REASONS = [
+ "ambiguous-target",
+ "bound-reached",
+ "dynamic-call",
+ "dynamic-property",
+ "eval-or-generated-code",
+ "incomplete-module",
+ "missing-source",
+ "unsupported-syntax",
+] as const;
+
+/** One unresolved semantic frontier before its ID is derived. */
+export const javaScriptSemanticUnknownInputSchema = z.strictObject({
+ node_id: semanticNodeIdSchema.nullable(),
+ family: z.enum(JAVASCRIPT_SEMANTIC_RELATION_FAMILIES),
+ relation_kinds: z.array(z.enum(JAVASCRIPT_SEMANTIC_RELATIONS)).min(1).max(45),
+ reason: z.enum(JAVASCRIPT_SEMANTIC_UNKNOWN_REASONS),
+ detail: boundedTextSchema,
+ candidate_node_ids: z.array(semanticNodeIdSchema).max(1_000),
+ evidence: applicationGraphEvidenceSchema,
+});
+
+/** One canonical unresolved semantic frontier. */
+export const javaScriptSemanticUnknownSchema =
+ javaScriptSemanticUnknownInputSchema.extend({
+ unknown_id: semanticUnknownIdSchema,
+ });
+
+const fingerprintComponentsSchema = z.strictObject({
+ parameter_arity: z.number().int().min(0).max(10_000),
+ normalized_ast_sha256: digestSchema,
+ control_flow_sha256: digestSchema,
+ relation_shape_sha256: digestSchema,
+ literal_set_sha256: digestSchema,
+ effects: z
+ .array(
+ z.enum([
+ "async",
+ "child-process",
+ "event",
+ "network",
+ "promise",
+ "resource",
+ "timer",
+ ]),
+ )
+ .max(7),
+});
+
+/** One bounded rename-resistant function fingerprint. */
+export const javaScriptSemanticFingerprintInputSchema = z.strictObject({
+ function_node_id: semanticNodeIdSchema,
+ algorithm: z.literal("rea.javascript-semantic-function/v1"),
+ status: z.enum(["complete", "partial", "unavailable"]),
+ components: fingerprintComponentsSchema,
+ limitations: z.array(boundedTextSchema).max(100),
+ evidence: applicationGraphEvidenceSchema,
+});
+
+/** One canonical function fingerprint record. */
+export const javaScriptSemanticFingerprintSchema =
+ javaScriptSemanticFingerprintInputSchema.extend({
+ fingerprint_id: z.string().regex(/^jsrg_fingerprint_[a-f0-9]{64}$/u),
+ fingerprint_sha256: digestSchema,
+ });
+
+const familyCoverageSchema = z.strictObject({
+ family: z.enum(JAVASCRIPT_SEMANTIC_RELATION_FAMILIES),
+ status: z.enum(["complete", "partial", "unknown", "unsupported"]),
+ retained_relations: z.number().int().min(0),
+ omitted_relations: z.number().int().min(0).nullable(),
+ unknown_ids: z.array(semanticUnknownIdSchema).max(100_000),
+});
+
+const graphCoverageSchema = z.strictObject({
+ status: z.enum(["complete", "partial", "unknown", "unavailable"]),
+ truncated: z.boolean(),
+ omitted_nodes: z.number().int().min(0).nullable(),
+ omitted_relations: z.number().int().min(0).nullable(),
+ limits: z
+ .array(
+ z.strictObject({
+ name: z.string().min(1).max(128),
+ value: z.number().int().min(0),
+ unit: z.enum(["items", "bytes", "milliseconds", "depth", "other"]),
+ }),
+ )
+ .max(32),
+ families: z.array(familyCoverageSchema).length(12),
+});
+
+/** Graph content before its top-level commitment is derived. */
+export const javaScriptSemanticGraphInputSchema = z.strictObject({
+ schema: z.literal("JavaScriptSemanticRelationGraph"),
+ schema_version: z.literal(1),
+ root_artifact_sha256: digestSchema,
+ application_graph_id: z.string().regex(/^jag_[a-f0-9]{64}$/u),
+ root_node_ids: z.array(semanticNodeIdSchema).min(1).max(10_000),
+ nodes: z.array(javaScriptSemanticNodeSchema).min(1).max(100_000),
+ relations: z.array(javaScriptSemanticRelationSchema).max(200_000),
+ fingerprints: z.array(javaScriptSemanticFingerprintSchema).max(20_000),
+ unknowns: z.array(javaScriptSemanticUnknownSchema).max(100_000),
+ coverage: graphCoverageSchema,
+ limitations: z.array(boundedTextSchema).max(1_000),
+});
+
+/** Stored JavaScript Semantic Relation Graph v1. */
+export const javaScriptSemanticGraphRecordSchema =
+ javaScriptSemanticGraphInputSchema.extend({
+ graph_id: z.string().regex(/^jsrg_[a-f0-9]{64}$/u),
+ });
+
+/** Canonical semantic node. */
+export type JavaScriptSemanticGraphNode = z.infer<
+ typeof javaScriptSemanticNodeSchema
+>;
+/** Canonical semantic relation. */
+export type JavaScriptSemanticGraphRelation = z.infer<
+ typeof javaScriptSemanticRelationSchema
+>;
+/** Canonical unresolved semantic frontier. */
+export type JavaScriptSemanticGraphUnknown = z.infer<
+ typeof javaScriptSemanticUnknownSchema
+>;
+/** Canonical graph content before graph ID derivation. */
+export type JavaScriptSemanticGraphInput = z.infer<
+ typeof javaScriptSemanticGraphInputSchema
+>;
diff --git a/src/domain/javascriptSemanticQuery.ts b/src/domain/javascriptSemanticQuery.ts
new file mode 100644
index 000000000..7dfe45094
--- /dev/null
+++ b/src/domain/javascriptSemanticQuery.ts
@@ -0,0 +1,568 @@
+import { createHash } from "node:crypto";
+
+import canonicalize from "canonicalize";
+
+import { compareCodePoints } from "./javascriptApplicationGraph.js";
+import type {
+ JavaScriptSemanticGraph,
+ JavaScriptSemanticGraphNode,
+ JavaScriptSemanticGraphRelation,
+} from "./javascriptSemanticGraph.js";
+import {
+ JAVASCRIPT_SEMANTIC_RELATION_FAMILY,
+ type JavaScriptSemanticGraphUnknown,
+} from "./javascriptSemanticGraphSchemas.js";
+import {
+ javaScriptSemanticQueryInputSchema,
+ javaScriptSemanticQueryResultSchema,
+ type JavaScriptSemanticQueryInput,
+ type JavaScriptSemanticQueryResult,
+} from "./javascriptSemanticQuerySchemas.js";
+import {
+ assessJavaScriptSemanticQuery,
+ type JavaScriptSemanticQueryFrontier,
+} from "./javascriptSemanticQueryAssessment.js";
+
+interface TraversalEntry {
+ readonly relation: JavaScriptSemanticGraphRelation;
+ readonly nextNodeId: string;
+}
+
+type QueryFrontier = JavaScriptSemanticQueryFrontier;
+
+interface Traversal {
+ readonly nodeIds: Set<string>;
+ readonly relationIds: Set<string>;
+ readonly functionIds: Set<string>;
+ readonly modules: Set<string>;
+ readonly frontier: QueryFrontier[];
+}
+
+interface SeedAdmission {
+ readonly nodeIds: string[];
+ readonly frontier: QueryFrontier[];
+}
+
+const canonicalJson = (value: unknown): string => {
+ const encoded = canonicalize(value);
+ if (encoded === undefined)
+ throw new TypeError(
+ "JavaScript semantic query could not canonicalize data",
+ );
+ return encoded;
+};
+
+const digest = (value: unknown): string =>
+ createHash("sha256").update(canonicalJson(value)).digest("hex");
+
+const uniqueSorted = (values: readonly string[]): string[] =>
+ [...new Set(values)].sort(compareCodePoints);
+
+/** Run one deterministic bounded traversal over a verified semantic graph. */
+export const queryJavaScriptSemanticGraph = (
+ graph: JavaScriptSemanticGraph,
+ rawInput: unknown,
+): JavaScriptSemanticQueryResult => {
+ 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 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 TypeError("Semantic query cursor is beyond the retained result");
+ const pageRelations = retainedRelations.slice(
+ offset,
+ offset + input.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 relevantUnknowns = relevantUnknownFrontiers(
+ graph,
+ traversal.nodeIds,
+ input,
+ );
+ const expectedMatches = expectedMatchesFor(
+ retainedNodes,
+ retainedRelations,
+ input,
+ );
+ const assessment = assessJavaScriptSemanticQuery({
+ graph,
+ totalSeeds: seeds.length,
+ retainedSeeds: retainedSeeds.length,
+ expectedMatches: expectedMatches.length,
+ hasExpectation: input.expected !== null,
+ frontier,
+ unknowns: relevantUnknowns,
+ });
+ const nextOffset = offset + pageRelations.length;
+ const nextCursor =
+ nextOffset < retainedRelations.length
+ ? createCursor(queryId, nextOffset)
+ : null;
+ 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: pageNodes,
+ relations: 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: relevantUnknowns.length,
+ },
+ coverage: assessment.coverage,
+ page: {
+ offset,
+ size: pageRelations.length,
+ next_cursor: nextCursor,
+ },
+ applied_limits: input.limits,
+ accepted_limit_ranges: assessment.acceptedLimitRanges,
+ limitations: assessment.limitations,
+ });
+};
+
+const queryIdentifier = (
+ graph: JavaScriptSemanticGraph,
+ input: JavaScriptSemanticQueryInput,
+): string => {
+ 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),
+ },
+ })}`;
+};
+
+const createCursor = (queryId: string, offset: number): string =>
+ `jsrqc_${String(offset)}_${digest({ query_id: queryId, offset })}`;
+
+const parseCursor = (cursor: string | null, queryId: string): number => {
+ 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 TypeError("Semantic query cursor is malformed");
+ const offset = Number(offsetText);
+ if (
+ !Number.isSafeInteger(offset) ||
+ offset < 0 ||
+ commitment !== digest({ query_id: queryId, offset })
+ )
+ throw new TypeError("Semantic query cursor does not match this query");
+ return offset;
+};
+
+const resolveSeeds = (
+ graph: JavaScriptSemanticGraph,
+ input: JavaScriptSemanticQueryInput,
+): string[] => {
+ const fingerprintFunctions = new Set(
+ input.seed.kind === "function"
+ ? graph.fingerprints
+ .filter(({ fingerprint_sha256 }) => {
+ const seed = input.seed;
+ return (
+ seed.kind === "function" &&
+ fingerprint_sha256 === 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: JavaScriptSemanticGraphNode,
+ input: JavaScriptSemanticQueryInput,
+ fingerprintFunctions: ReadonlySet<string>,
+): boolean => {
+ 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" &&
+ canonicalJson(node.properties.value) === canonicalJson(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;
+};
+
+const admitSeeds = (
+ graph: JavaScriptSemanticGraph,
+ seeds: readonly string[],
+ input: JavaScriptSemanticQueryInput,
+): SeedAdmission => {
+ const nodes = new Map(graph.nodes.map((node) => [node.node_id, node]));
+ const retained: string[] = [];
+ const functions = new Set<string>();
+ const modules = new Set<string>();
+ const frontier: QueryFrontier[] = [];
+ 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) };
+};
+
+interface SeedBounds {
+ readonly retained: readonly string[];
+ readonly functions: ReadonlySet<string>;
+ readonly modules: ReadonlySet<string>;
+ readonly input: JavaScriptSemanticQueryInput;
+}
+
+interface TraversalBounds {
+ readonly nodes: ReadonlyMap<string, JavaScriptSemanticGraphNode>;
+ readonly nodeIds: ReadonlySet<string>;
+ readonly relationIds: ReadonlySet<string>;
+ readonly functionIds: ReadonlySet<string>;
+ readonly modules: ReadonlySet<string>;
+ readonly input: JavaScriptSemanticQueryInput;
+}
+
+const seedBlockedReason = (
+ node: JavaScriptSemanticGraphNode,
+ bounds: SeedBounds,
+): QueryFrontier["reason"] | null => {
+ 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: readonly JavaScriptSemanticGraphRelation[],
+ input: JavaScriptSemanticQueryInput,
+): ReadonlyMap<string, TraversalEntry[]> => {
+ const adjacency = new Map<string, TraversalEntry[]>();
+ 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: Map<string, TraversalEntry[]>,
+ relation: JavaScriptSemanticGraphRelation,
+ direction: JavaScriptSemanticQueryInput["direction"],
+): void => {
+ 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 ownershipRelation = (
+ relation: JavaScriptSemanticGraphRelation["relation"],
+): boolean =>
+ [
+ "acquires",
+ "aggregates",
+ "awaits",
+ "chains",
+ "connects-stdio",
+ "creates-promise",
+ "detaches-task",
+ "owns",
+ "releases",
+ "returns-task",
+ "spawns",
+ ].includes(relation);
+
+const addEntry = (
+ adjacency: Map<string, TraversalEntry[]>,
+ from: string,
+ nextNodeId: string,
+ relation: JavaScriptSemanticGraphRelation,
+): void => {
+ const entries = adjacency.get(from) ?? [];
+ entries.push({ relation, nextNodeId });
+ adjacency.set(from, entries);
+};
+
+const traverse = (
+ graph: JavaScriptSemanticGraph,
+ seeds: readonly string[],
+ adjacency: ReadonlyMap<string, TraversalEntry[]>,
+ input: JavaScriptSemanticQueryInput,
+): Traversal => {
+ const nodes = new Map(graph.nodes.map((node) => [node.node_id, node]));
+ const nodeIds = new Set(seeds);
+ const relationIds = new Set<string>();
+ const functionIds = new Set<string>();
+ const modules = new Set<string>();
+ const frontier: QueryFrontier[] = [];
+ 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: TraversalBounds = {
+ 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: TraversalEntry,
+ depth: number,
+ bounds: TraversalBounds,
+): QueryFrontier["reason"] | null => {
+ 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: JavaScriptSemanticGraphNode | undefined,
+ functions: Set<string>,
+ modules: Set<string>,
+): void => {
+ if (node === undefined) return;
+ const functionId = functionOwner(node);
+ if (functionId !== null) functions.add(functionId);
+ modules.add(node.identity.module_path);
+};
+
+const functionOwner = (node: JavaScriptSemanticGraphNode): string | null =>
+ node.kind === "function" ? node.node_id : node.function_node_id;
+
+const uniqueFrontier = (frontier: readonly QueryFrontier[]): QueryFrontier[] =>
+ [
+ ...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: JavaScriptSemanticGraph,
+ nodeIds: ReadonlySet<string>,
+ input: JavaScriptSemanticQueryInput,
+): JavaScriptSemanticGraphUnknown[] => {
+ 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 expectedMatchesFor = (
+ nodes: readonly JavaScriptSemanticGraphNode[],
+ relations: readonly JavaScriptSemanticGraphRelation[],
+ input: JavaScriptSemanticQueryInput,
+): JavaScriptSemanticGraphNode[] => {
+ 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),
+ );
+};
+
+/** Return a relation's declared semantic coverage family. */
+export const javaScriptSemanticRelationFamily = (
+ relation: JavaScriptSemanticGraphRelation["relation"],
+) => JAVASCRIPT_SEMANTIC_RELATION_FAMILY[relation];
diff --git a/src/domain/javascriptSemanticQueryAssessment.ts b/src/domain/javascriptSemanticQueryAssessment.ts
new file mode 100644
index 000000000..b73590354
--- /dev/null
+++ b/src/domain/javascriptSemanticQueryAssessment.ts
@@ -0,0 +1,110 @@
+import { compareCodePoints } from "./javascriptApplicationGraph.js";
+import type { JavaScriptSemanticGraph } from "./javascriptSemanticGraph.js";
+import type { JavaScriptSemanticGraphUnknown } from "./javascriptSemanticGraphSchemas.js";
+import type { JavaScriptSemanticQueryResult } from "./javascriptSemanticQuerySchemas.js";
+
+/** One caller-limit frontier retained by deterministic query traversal. */
+export interface JavaScriptSemanticQueryFrontier {
+ readonly node_id: string;
+ readonly depth: number;
+ readonly reason:
+ | "max-depth"
+ | "max-edges"
+ | "max-functions"
+ | "max-modules"
+ | "max-nodes"
+ | "max-seed-matches";
+}
+
+/** Inputs needed to classify one completed semantic traversal. */
+export interface JavaScriptSemanticQueryAssessmentInput {
+ readonly graph: JavaScriptSemanticGraph;
+ readonly totalSeeds: number;
+ readonly retainedSeeds: number;
+ readonly expectedMatches: number;
+ readonly hasExpectation: boolean;
+ readonly frontier: readonly JavaScriptSemanticQueryFrontier[];
+ readonly unknowns: readonly JavaScriptSemanticGraphUnknown[];
+}
+
+/** Status, coverage, limits, and limitations derived from one traversal. */
+export interface JavaScriptSemanticQueryAssessment {
+ readonly status: JavaScriptSemanticQueryResult["status"];
+ readonly coverage: JavaScriptSemanticQueryResult["coverage"];
+ readonly limitations: string[];
+ readonly acceptedLimitRanges: JavaScriptSemanticQueryResult["accepted_limit_ranges"];
+}
+
+/** Classify a bounded semantic traversal without promoting unknowns to absence. */
+export const assessJavaScriptSemanticQuery = (
+ input: JavaScriptSemanticQueryAssessmentInput,
+): JavaScriptSemanticQueryAssessment => ({
+ 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 },
+ page_size: { minimum: 1, maximum: 1_000 },
+ },
+});
+
+const queryCoverage = (
+ input: JavaScriptSemanticQueryAssessmentInput,
+): JavaScriptSemanticQueryResult["coverage"] => ({
+ status:
+ input.graph.coverage.status === "unavailable"
+ ? "unavailable"
+ : input.frontier.length > 0
+ ? "truncated"
+ : input.unknowns.length > 0 ||
+ input.graph.coverage.status !== "complete"
+ ? "partial"
+ : "complete",
+ frontier: [...input.frontier],
+});
+
+const queryStatus = (
+ input: JavaScriptSemanticQueryAssessmentInput,
+): JavaScriptSemanticQueryResult["status"] => {
+ if (input.graph.coverage.status === "unavailable") return "unsupported";
+ if (input.frontier.length > 0) return "truncated";
+ if (input.unknowns.length > 0 || input.graph.coverage.status !== "complete")
+ return "partial";
+ if (
+ input.totalSeeds === 0 ||
+ (input.hasExpectation && input.expectedMatches === 0)
+ )
+ return "no-match";
+ return input.totalSeeds > 1 ? "ambiguous" : "found";
+};
+
+const queryLimitations = (
+ input: JavaScriptSemanticQueryAssessmentInput,
+): string[] =>
+ 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.",
+ ]),
+ ]);
+
+const uniqueSorted = (values: readonly string[]): string[] =>
+ [...new Set(values)].sort(compareCodePoints);
diff --git a/src/domain/javascriptSemanticQuerySchemas.ts b/src/domain/javascriptSemanticQuerySchemas.ts
new file mode 100644
index 000000000..00d3e8ca3
--- /dev/null
+++ b/src/domain/javascriptSemanticQuerySchemas.ts
@@ -0,0 +1,227 @@
+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 evidenceIdSchema = z.string().regex(/^ev_[a-f0-9]{64}$/u);
+
+/** Exact accepted ranges and defaults for one semantic traversal. */
+export const JAVASCRIPT_SEMANTIC_QUERY_LIMIT_RANGES = {
+ max_seed_matches: { minimum: 1, maximum: 1_000, default: 25 },
+ max_nodes: { minimum: 1, maximum: 50_000, default: 2_000 },
+ max_edges: { minimum: 1, maximum: 100_000, default: 4_000 },
+ max_depth: { minimum: 0, maximum: 64, default: 12 },
+ max_functions: { minimum: 1, maximum: 10_000, default: 500 },
+ max_modules: { minimum: 1, maximum: 10_000, default: 500 },
+ page_size: { minimum: 1, maximum: 1_000, default: 200 },
+} as const;
+
+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),
+ page_size: z.number().int().min(1).max(1_000).default(200),
+});
+
+const sourceMapAuthoritySchema = z.discriminatedUnion("authority", [
+ z.strictObject({ authority: z.literal("none") }),
+ z.strictObject({
+ authority: z.literal("authenticated"),
+ evidence_id: evidenceIdSchema,
+ source_map_sha256: digestSchema,
+ }),
+]);
+
+/** Parsed pure-domain query over one authenticated companion graph. */
+export const javaScriptSemanticQueryInputSchema = z.strictObject({
+ seed: javaScriptSemanticQuerySeedSchema,
+ direction: z.enum([
+ "backward-provenance",
+ "forward-influence",
+ "callers",
+ "consumers",
+ "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,
+ 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),
+ }),
+ 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),
+ }),
+ 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),
+});
+
+/** Validated semantic query input. */
+export type JavaScriptSemanticQueryInput = z.infer<
+ typeof javaScriptSemanticQueryInputSchema
+>;
+/** Validated semantic query result. */
+export type JavaScriptSemanticQueryResult = z.infer<
+ typeof javaScriptSemanticQueryResultSchema
+>;
diff --git a/tests/javascriptSemanticGraphQuery.test.ts b/tests/javascriptSemanticGraphQuery.test.ts
new file mode 100644
index 000000000..771e92ac4
--- /dev/null
+++ b/tests/javascriptSemanticGraphQuery.test.ts
@@ -0,0 +1,477 @@
+import { describe, expect, it } from "vitest";
+
+import type { ApplicationGraphEvidence } from "../src/domain/javascriptApplicationEvidenceSchemas.js";
+import {
+ JAVASCRIPT_SEMANTIC_NODE_KINDS,
+ JAVASCRIPT_SEMANTIC_RELATION_FAMILIES,
+ JAVASCRIPT_SEMANTIC_RELATIONS,
+} from "../src/domain/javascriptSemanticGraphSchemas.js";
+import {
+ createJavaScriptSemanticFingerprint,
+ createJavaScriptSemanticGraph,
+ createJavaScriptSemanticGraphNode,
+ createJavaScriptSemanticGraphRelation,
+ createJavaScriptSemanticGraphUnknown,
+ parseJavaScriptSemanticGraph,
+ serializeJavaScriptSemanticGraph,
+ type JavaScriptSemanticGraph,
+ type JavaScriptSemanticGraphNode,
+} from "../src/domain/javascriptSemanticGraph.js";
+import { queryJavaScriptSemanticGraph } from "../src/domain/javascriptSemanticQuery.js";
+import { javaScriptSemanticQueryInputSchema } from "../src/domain/javascriptSemanticQuerySchemas.js";
+
+const SHA = "a".repeat(64);
+const JAG_ID = `jag_${"b".repeat(64)}`;
+const completeCoverage = {
+ status: "complete" as const,
+ truncated: false,
+ omitted_count: 0,
+ limits: [],
+};
+
+const evidence = (
+ state: "observed" | "inferred" = "observed",
+): ApplicationGraphEvidence => ({
+ authority:
+ state === "observed"
+ ? "ast-static-analysis"
+ : "static-relationship-inference",
+ state,
+ confidence: state === "observed" ? "exact" : "high",
+ artifact: { available: true, artifact_id: `art_${SHA}`, sha256: SHA },
+ location: {
+ available: true,
+ value: {
+ kind: "source-range",
+ source: "bundle.js",
+ start: { line: 1, column: 0 },
+ end: { line: 1, column: 10 },
+ },
+ },
+ extractor: {
+ name: "test",
+ version: "1",
+ operation: "recover-semantic-relation",
+ executable_sha256: null,
+ },
+ coverage: completeCoverage,
+ limitations:
+ state === "observed"
+ ? []
+ : ["Static reachability does not prove runtime execution."],
+ evidence_ids: [],
+});
+
+const unknownEvidence = (): ApplicationGraphEvidence => ({
+ authority: "unknown",
+ state: "unknown",
+ confidence: "unknown",
+ artifact: {
+ available: false,
+ reason: "unknown",
+ detail: "Unknown artifact.",
+ },
+ location: {
+ available: false,
+ reason: "unresolved",
+ detail: "Dynamic call target.",
+ },
+ extractor: {
+ name: "test",
+ version: "1",
+ operation: "retain-dynamic-call",
+ executable_sha256: null,
+ },
+ coverage: {
+ status: "unknown",
+ truncated: false,
+ omitted_count: null,
+ limits: [],
+ },
+ limitations: ["Dynamic call target remains unknown."],
+ evidence_ids: [],
+});
+
+const node = (
+ kind: (typeof JAVASCRIPT_SEMANTIC_NODE_KINDS)[number],
+ role: string,
+ properties: Record<string, string | number | boolean | null> = {},
+ functionNodeId: string | null = null,
+): JavaScriptSemanticGraphNode =>
+ createJavaScriptSemanticGraphNode({
+ kind,
+ identity: {
+ artifact_sha256: SHA,
+ module_path: "bundle.js",
+ source_range: {
+ start: { line: 1, column: role.length },
+ end: { line: 1, column: role.length + 1 },
+ },
+ role_key: role,
+ },
+ function_node_id: functionNodeId,
+ application_node_ids: [],
+ label: role,
+ properties,
+ evidence: evidence(),
+ });
+
+const fixtureGraph = (withUnknown = false): JavaScriptSemanticGraph => {
+ const module = node("module", "module");
+ const literal = node("literal", "literal", { value: "TOKEN" });
+ const binding = node("binding", "binding");
+ const callable = node("function", "function");
+ const request = node("request", "request", {
+ endpoint: "https://example.invalid/v1",
+ });
+ const relations = [
+ createJavaScriptSemanticGraphRelation({
+ source_node_id: literal.node_id,
+ target_node_id: binding.node_id,
+ relation: "defines",
+ resolution: "resolved",
+ properties: {},
+ evidence: evidence("inferred"),
+ }),
+ createJavaScriptSemanticGraphRelation({
+ source_node_id: binding.node_id,
+ target_node_id: callable.node_id,
+ relation: "captures",
+ resolution: "resolved",
+ properties: {},
+ evidence: evidence("inferred"),
+ }),
+ createJavaScriptSemanticGraphRelation({
+ source_node_id: callable.node_id,
+ target_node_id: request.node_id,
+ relation: "constructs-request",
+ resolution: "resolved",
+ properties: {},
+ evidence: evidence("inferred"),
+ }),
+ ];
+ const dynamic = createJavaScriptSemanticGraphUnknown({
+ node_id: callable.node_id,
+ family: "call-flow",
+ relation_kinds: ["calls"],
+ reason: "dynamic-call",
+ detail: "Computed callee is unresolved.",
+ candidate_node_ids: [],
+ evidence: unknownEvidence(),
+ });
+ const unknowns = withUnknown ? [dynamic] : [];
+ const coverageFamilies = JAVASCRIPT_SEMANTIC_RELATION_FAMILIES.map(
+ (family) => ({
+ family,
+ status:
+ withUnknown && family === "call-flow"
+ ? ("unknown" as const)
+ : ("complete" as const),
+ retained_relations: relations.filter(({ relation }) =>
+ relation === "defines"
+ ? family === "data-flow"
+ : relation === "captures"
+ ? family === "closure"
+ : family === "request",
+ ).length,
+ omitted_relations: withUnknown && family === "call-flow" ? null : 0,
+ unknown_ids:
+ withUnknown && family === "call-flow" ? [dynamic.unknown_id] : [],
+ }),
+ );
+ const fingerprint = createJavaScriptSemanticFingerprint({
+ function_node_id: callable.node_id,
+ algorithm: "rea.javascript-semantic-function/v1",
+ status: "complete",
+ components: {
+ parameter_arity: 0,
+ normalized_ast_sha256: "1".repeat(64),
+ control_flow_sha256: "2".repeat(64),
+ relation_shape_sha256: "3".repeat(64),
+ literal_set_sha256: "4".repeat(64),
+ effects: ["network"],
+ },
+ limitations: [],
+ evidence: evidence("inferred"),
+ });
+ return createJavaScriptSemanticGraph({
+ schema: "JavaScriptSemanticRelationGraph",
+ schema_version: 1,
+ root_artifact_sha256: SHA,
+ application_graph_id: JAG_ID,
+ root_node_ids: [module.node_id],
+ nodes: [request, callable, binding, literal, module],
+ relations,
+ fingerprints: [fingerprint],
+ unknowns,
+ coverage: {
+ status: withUnknown ? "partial" : "complete",
+ truncated: false,
+ omitted_nodes: withUnknown ? null : 0,
+ omitted_relations: withUnknown ? null : 0,
+ limits: [],
+ families: coverageFamilies,
+ },
+ limitations: withUnknown ? ["Dynamic call target remains unknown."] : [],
+ });
+};
+
+const graphWithCandidateEdge = (): JavaScriptSemanticGraph => {
+ const graph = fixtureGraph();
+ const literal = graph.nodes.find(({ kind }) => kind === "literal");
+ const request = graph.nodes.find(({ kind }) => kind === "request");
+ if (literal === undefined || request === undefined)
+ throw new TypeError("Semantic fixture nodes are missing");
+ const candidate = createJavaScriptSemanticGraphRelation({
+ source_node_id: literal.node_id,
+ target_node_id: request.node_id,
+ relation: "supplies-request-field",
+ resolution: "candidate",
+ properties: { field: "authorization" },
+ evidence: evidence("inferred"),
+ });
+ const { graph_id: _graphId, ...input } = graph;
+ return createJavaScriptSemanticGraph({
+ ...input,
+ relations: [...graph.relations, candidate],
+ coverage: {
+ ...graph.coverage,
+ families: graph.coverage.families.map((family) =>
+ family.family === "request"
+ ? {
+ ...family,
+ retained_relations: family.retained_relations + 1,
+ }
+ : family,
+ ),
+ },
+ });
+};
+
+const graphWithDuplicateLiteral = (): JavaScriptSemanticGraph => {
+ const graph = fixtureGraph();
+ const duplicate = node("literal", "literal-copy", { value: "TOKEN" });
+ const { graph_id: _graphId, ...input } = graph;
+ return createJavaScriptSemanticGraph({
+ ...input,
+ nodes: [...graph.nodes, duplicate],
+ });
+};
+
+describe("JavaScript semantic relation graph", () => {
+ it("defines every required v1 relation family and canonicalizes records", () => {
+ expect(JAVASCRIPT_SEMANTIC_RELATIONS).toContain("argument-to-parameter");
+ expect(JAVASCRIPT_SEMANTIC_RELATIONS).toContain("detaches-task");
+ expect(JAVASCRIPT_SEMANTIC_RELATIONS).toContain("forwards-signal");
+ expect(JAVASCRIPT_SEMANTIC_RELATIONS).toContain("validates");
+ const graph = fixtureGraph();
+ expect(
+ parseJavaScriptSemanticGraph(
+ JSON.parse(serializeJavaScriptSemanticGraph(graph)),
+ ),
+ ).toEqual(graph);
+ expect(graph.nodes.map(({ node_id }) => node_id)).toEqual(
+ graph.nodes.map(({ node_id }) => node_id).toSorted(),
+ );
+ });
+
+ it("rejects stale identities, dangling endpoints, and incomplete coverage claims", () => {
+ const graph = fixtureGraph();
+ const { graph_id: _graphId, ...graphInput } = graph;
+ expect(() =>
+ parseJavaScriptSemanticGraph({
+ ...graph,
+ graph_id: `jsrg_${"0".repeat(64)}`,
+ }),
+ ).toThrow();
+ expect(() =>
+ createJavaScriptSemanticGraph({
+ ...graphInput,
+ relations: [
+ {
+ ...graph.relations[0],
+ target_node_id: `jsrg_node_${"f".repeat(64)}`,
+ },
+ ],
+ }),
+ ).toThrow();
+ expect(() =>
+ createJavaScriptSemanticGraph({
+ ...graphInput,
+ coverage: { ...graph.coverage, omitted_nodes: 1 },
+ }),
+ ).toThrow(/Complete graph coverage/u);
+ });
+});
+
+describe("JavaScript semantic query", () => {
+ it("traces deterministic forward influence and pages without changing identity", () => {
+ const graph = fixtureGraph();
+ const input = {
+ seed: { kind: "literal" as const, value: "TOKEN" },
+ direction: "forward-influence" as const,
+ expected: { role: "sink" as const, classes: ["request" as const] },
+ limits: {
+ max_seed_matches: 25,
+ max_nodes: 20,
+ max_edges: 20,
+ max_depth: 12,
+ max_functions: 10,
+ max_modules: 10,
+ page_size: 2,
+ },
+ };
+ const first = queryJavaScriptSemanticGraph(graph, input);
+ expect(first).toMatchObject({
+ status: "found",
+ summary: { traversed_nodes: 4, traversed_relations: 3 },
+ page: { offset: 0, size: 2 },
+ });
+ expect(first.expected_match_node_ids).toHaveLength(1);
+ expect(first.page.next_cursor).not.toBeNull();
+ const second = queryJavaScriptSemanticGraph(graph, {
+ ...input,
+ cursor: first.page.next_cursor,
+ });
+ expect(second.query_id).toBe(first.query_id);
+ expect(second.page).toMatchObject({
+ offset: 2,
+ size: 1,
+ next_cursor: null,
+ });
+ expect(second.relations[0]?.relation_id).not.toBe(
+ first.relations[0]?.relation_id,
+ );
+ });
+
+ it("keeps relevant dynamic frontiers unknown", () => {
+ const result = queryJavaScriptSemanticGraph(fixtureGraph(true), {
+ seed: { kind: "literal", value: "TOKEN" },
+ direction: "forward-influence",
+ });
+ expect(result.status).toBe("partial");
+ expect(result.coverage.status).toBe("partial");
+ expect(result.unknowns).toMatchObject([
+ { reason: "dynamic-call", relation_kinds: ["calls"] },
+ ]);
+ });
+
+ it("excludes candidate edges unless the caller explicitly opts in", () => {
+ const graph = graphWithCandidateEdge();
+ const input = {
+ seed: { kind: "literal" as const, value: "TOKEN" },
+ direction: "forward-influence" as const,
+ allowed_relations: ["supplies-request-field" as const],
+ };
+ const conservative = queryJavaScriptSemanticGraph(graph, input);
+ const optedIn = queryJavaScriptSemanticGraph(graph, {
+ ...input,
+ include_ambiguous_dynamic_edges: true,
+ });
+ expect(conservative.summary.traversed_relations).toBe(0);
+ expect(optedIn.summary.traversed_relations).toBe(1);
+ expect(optedIn.relations).toMatchObject([
+ { relation: "supplies-request-field", resolution: "candidate" },
+ ]);
+ });
+
+ it("bounds seed ambiguity before traversal", () => {
+ const result = queryJavaScriptSemanticGraph(graphWithDuplicateLiteral(), {
+ seed: { kind: "literal", value: "TOKEN" },
+ direction: "forward-influence",
+ limits: {
+ max_seed_matches: 1,
+ max_nodes: 20,
+ max_edges: 20,
+ max_depth: 12,
+ max_functions: 10,
+ max_modules: 10,
+ page_size: 10,
+ },
+ });
+ expect(result.summary).toMatchObject({
+ total_seed_matches: 2,
+ retained_seed_matches: 1,
+ });
+ expect(result.status).toBe("truncated");
+ expect(result.coverage.frontier).toContainEqual(
+ expect.objectContaining({ reason: "max-seed-matches", depth: 0 }),
+ );
+ });
+
+ it("reports exact caller limits and a deterministic truncation frontier", () => {
+ const result = queryJavaScriptSemanticGraph(fixtureGraph(), {
+ seed: { kind: "literal", value: "TOKEN" },
+ direction: "forward-influence",
+ limits: {
+ max_seed_matches: 1,
+ max_nodes: 2,
+ max_edges: 10,
+ max_depth: 12,
+ max_functions: 10,
+ max_modules: 10,
+ page_size: 10,
+ },
+ });
+ expect(result.status).toBe("truncated");
+ expect(result.coverage.frontier).toMatchObject([{ reason: "max-nodes" }]);
+ expect(result.applied_limits.max_nodes).toBe(2);
+ expect(result.accepted_limit_ranges.max_nodes).toEqual({
+ minimum: 1,
+ maximum: 50_000,
+ });
+ });
+
+ it.each([
+ {
+ limit: { max_edges: 1 },
+ reason: "max-edges",
+ },
+ {
+ limit: { max_depth: 0 },
+ reason: "max-depth",
+ },
+ ])("reports the $reason frontier", ({ limit, reason }) => {
+ const result = queryJavaScriptSemanticGraph(fixtureGraph(), {
+ seed: { kind: "literal", value: "TOKEN" },
+ direction: "forward-influence",
+ limits: {
+ max_seed_matches: 10,
+ max_nodes: 20,
+ max_edges: limit.max_edges ?? 20,
+ max_depth: limit.max_depth ?? 12,
+ max_functions: 10,
+ max_modules: 10,
+ page_size: 10,
+ },
+ });
+ expect(result.status).toBe("truncated");
+ expect(result.coverage.frontier).toContainEqual(
+ expect.objectContaining({ reason }),
+ );
+ });
+
+ it("rejects out-of-range limits and cursors from another query", () => {
+ expect(() =>
+ javaScriptSemanticQueryInputSchema.parse({
+ seed: { kind: "literal", value: "TOKEN" },
+ direction: "forward-influence",
+ limits: { max_nodes: 50_001 },
+ }),
+ ).toThrow();
+ const graph = fixtureGraph();
+ const first = queryJavaScriptSemanticGraph(graph, {
+ seed: { kind: "literal", value: "TOKEN" },
+ direction: "forward-influence",
+ limits: { page_size: 1 },
+ });
+ expect(() =>
+ queryJavaScriptSemanticGraph(graph, {
+ seed: { kind: "endpoint", value: "https://example.invalid/v1" },
+ direction: "backward-provenance",
+ limits: { page_size: 1 },
+ cursor: first.page.next_cursor,
+ }),
+ ).toThrow(/cursor does not match/u);
+ });
+});