rea-agents 2.1.0 → 2.3.0

package/dist/domain/javascriptSemanticGraph.js

@@ -0,0 +1,356 @@
+import { createHash } from "node:crypto";
+import canonicalize from "canonicalize";
+import { z } from "zod";
+import { compareCodePoints } from "./javascriptApplicationGraph.js";
+import { JAVASCRIPT_SEMANTIC_RELATION_FAMILIES, JAVASCRIPT_SEMANTIC_RELATION_FAMILY, javaScriptSemanticFingerprintInputSchema, javaScriptSemanticFingerprintSchema, javaScriptSemanticGraphInputSchema, javaScriptSemanticGraphRecordSchema, javaScriptSemanticNodeInputSchema, javaScriptSemanticNodeSchema, javaScriptSemanticRelationInputSchema, javaScriptSemanticRelationSchema, javaScriptSemanticUnknownInputSchema, javaScriptSemanticUnknownSchema, } from "./javascriptSemanticGraphSchemas.js";
+const canonicalJson = (value) => {
+    const encoded = canonicalize(value);
+    if (encoded === undefined)
+        throw new TypeError("JavaScript semantic graph could not canonicalize data");
+    return encoded;
+};
+const digestCanonical = (value) => createHash("sha256").update(canonicalJson(value)).digest("hex");
+const uniqueSorted = (values) => [...new Set(values)].sort(compareCodePoints);
+const normalizeEvidence = (evidence) => ({
+    ...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 nodeId = (node) => `jsrg_node_${digestCanonical({ kind: node.kind, identity: node.identity })}`;
+/** Normalize one semantic entity and derive its artifact-version identifier. */
+export const createJavaScriptSemanticGraphNode = (input) => {
+    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",
+            stability: "artifact-version",
+        },
+    };
+    return javaScriptSemanticNodeSchema.parse({
+        ...semantic,
+        node_id: nodeId(semantic),
+    });
+};
+/** Normalize one semantic relationship and derive its exact identifier. */
+export const createJavaScriptSemanticGraphRelation = (input) => {
+    const parsed = javaScriptSemanticRelationInputSchema.parse(input);
+    const semantic = {
+        ...parsed,
+        evidence: normalizeEvidence(parsed.evidence),
+        identifier_strategy: {
+            strategy: "semantic-content-sha256",
+            stability: "relationship-exact",
+        },
+    };
+    return javaScriptSemanticRelationSchema.parse({
+        ...semantic,
+        relation_id: `jsrg_relation_${digestCanonical(semantic)}`,
+    });
+};
+/** Normalize one unresolved semantic frontier and derive its identifier. */
+export const createJavaScriptSemanticGraphUnknown = (input) => {
+    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) => {
+    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,
+        })}`,
+    });
+};
+const sortedUniqueIssue = (values, path, label, context) => {
+    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, context) => {
+    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, context) => {
+    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, nodes, context) => {
+    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, nodes, context) => {
+    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, nodes, context) => {
+    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, nodes, context) => {
+    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.candidate_node_ids.some((nodeId) => !nodes.has(nodeId)))
+            context.addIssue({
+                code: "custom",
+                path: ["unknowns", index, "candidate_node_ids"],
+                message: "Unknown frontier candidate 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, context) => {
+    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, nodes, context) => {
+    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, context) => {
+    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);
+/** Normalize a complete companion graph and derive its graph ID. */
+export const createJavaScriptSemanticGraph = (input) => {
+    const parsed = javaScriptSemanticGraphInputSchema.parse(input);
+    const semantic = {
+        ...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)}`,
+    });
+};

package/dist/domain/javascriptSemanticGraphSchemas.js

@@ -0,0 +1,329 @@
+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",
+];
+/** 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",
+];
+/** 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",
+];
+/** 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",
+};
+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",
+];
+/** 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),
+});