rea-agents 6.1.0 → 6.3.0

package/dist/domain/javascript/javascriptSemanticGraph.js

@@ -1,26 +1,65 @@
 import { z } from "zod";
-import { canonicalDigest, canonicalJson } from "../comparisonSemantics.js";
-import { compareCodePoints, uniqueSorted } from "../canonicalOrdering.js";
+import { canonicalJson } from "../comparisonSemantics.js";
+import { digestCanonicalValue } from "../canonicalDigest.js";
+import { uniqueSorted } from "../canonicalOrdering.js";
+import { compareUnicodeCodePoints } from "../unicodeCodePointOrder.js";
+import { canonicalJsonDigestSteps } from "../canonicalJsonDigestSteps.js";
 import { freezeOwnedJsonSnapshotSteps } from "../immutableJson.js";
+import { applicationGraphEvidenceSchema } from "./javascriptApplicationEvidenceSchemas.js";
 import { JAVASCRIPT_SEMANTIC_RELATION_FAMILIES, JAVASCRIPT_SEMANTIC_RELATION_FAMILY, javaScriptSemanticFingerprintInputSchema, javaScriptSemanticFingerprintSchema, javaScriptSemanticGraphInputSchema, javaScriptSemanticGraphRecordSchema, javaScriptSemanticNodeInputSchema, javaScriptSemanticNodeSchema, javaScriptSemanticRelationInputSchema, javaScriptSemanticRelationSchema, javaScriptSemanticUnknownInputSchema, javaScriptSemanticUnknownSchema, } from "./javascriptSemanticGraphSchemas.js";
 const normalizeEvidence = (evidence) => ({
     ...evidence,
     coverage: {
         ...evidence.coverage,
-        limits: [...evidence.coverage.limits].sort((left, right) => compareCodePoints(canonicalJson(left, "JavaScript semantic graph"), canonicalJson(right, "JavaScript semantic graph"))),
+        limits: [...evidence.coverage.limits].sort((left, right) => compareUnicodeCodePoints(canonicalJson(left, "JavaScript semantic graph"), canonicalJson(right, "JavaScript semantic graph"))),
     },
     limitations: uniqueSorted(evidence.limitations),
     evidence_ids: uniqueSorted(evidence.evidence_ids),
 });
+const evidenceContextId = (context) => `jsrg_evidence_${digestCanonicalValue(context, "JavaScript semantic evidence context")}`;
+/** Graph-scoped owner for canonical provenance shared by semantic facts. */
+export class JavaScriptSemanticEvidenceContextRegistry {
+    #contexts = new Map();
+    /** Intern normalized non-location provenance at fact construction. */
+    intern(evidence) {
+        const normalized = normalizeEvidence(evidence);
+        const { location, ...context } = normalized;
+        const contextId = evidenceContextId(context);
+        const row = { ...context, context_id: contextId };
+        const existing = this.#contexts.get(contextId);
+        if (existing !== undefined &&
+            canonicalJson(existing, "JavaScript semantic graph") !==
+                canonicalJson(row, "JavaScript semantic graph"))
+            throw new TypeError("JavaScript semantic evidence context digest collision");
+        this.#contexts.set(contextId, row);
+        return { context_id: contextId, location };
+    }
+    /** Resolve one already interned fact reference for derived evidence. */
+    resolve(reference) {
+        const context = this.#contexts.get(reference.context_id);
+        if (context === undefined)
+            throw new TypeError("Semantic evidence reference names an absent context");
+        const { context_id: _contextId, ...evidenceContext } = context;
+        return { ...evidenceContext, location: reference.location };
+    }
+    /** Return the deterministic context table owned by this graph projection. */
+    get contexts() {
+        return [...this.#contexts.values()].sort((left, right) => compareUnicodeCodePoints(left.context_id, right.context_id));
+    }
+    /** Release interned contexts after the owning graph is finalized. */
+    clear() {
+        this.#contexts.clear();
+    }
+}
 /** Derive a semantic node ID from its kind and exact artifact identity. */
-export const javaScriptSemanticNodeId = (node) => `jsrg_node_${canonicalDigest({ kind: node.kind, identity: node.identity }, "JavaScript semantic graph")}`;
+export const javaScriptSemanticNodeId = (node) => `jsrg_node_${digestCanonicalValue({ kind: node.kind, identity: node.identity }, "JavaScript semantic graph")}`;
 /** Normalize one semantic entity and derive its artifact-version identifier. */
-export const createJavaScriptSemanticGraphNode = (input) => {
+export const createJavaScriptSemanticGraphNode = (input, evidenceContexts) => {
     const parsed = javaScriptSemanticNodeInputSchema.parse(input);
     const semantic = {
         ...parsed,
         application_node_ids: uniqueSorted(parsed.application_node_ids),
-        evidence: normalizeEvidence(parsed.evidence),
+        evidence: evidenceContexts.intern(parsed.evidence),
         identifier_strategy: {
             strategy: "semantic-content-sha256",
             stability: "artifact-version",
@@ -32,11 +71,11 @@ export const createJavaScriptSemanticGraphNode = (input) => {
     });
 };
 /** Normalize one semantic relationship and derive its exact identifier. */
-export const createJavaScriptSemanticGraphRelation = (input) => {
+export const createJavaScriptSemanticGraphRelation = (input, evidenceContexts) => {
     const parsed = javaScriptSemanticRelationInputSchema.parse(input);
     const semantic = {
         ...parsed,
-        evidence: normalizeEvidence(parsed.evidence),
+        evidence: evidenceContexts.intern(parsed.evidence),
         identifier_strategy: {
             strategy: "semantic-content-sha256",
             stability: "relationship-exact",
@@ -44,25 +83,25 @@ export const createJavaScriptSemanticGraphRelation = (input) => {
     };
     return javaScriptSemanticRelationSchema.parse({
         ...semantic,
-        relation_id: `jsrg_relation_${canonicalDigest(semantic, "JavaScript semantic graph")}`,
+        relation_id: `jsrg_relation_${digestCanonicalValue(semantic, "JavaScript semantic graph")}`,
     });
 };
 /** Normalize one unresolved semantic frontier and derive its identifier. */
-export const createJavaScriptSemanticGraphUnknown = (input) => {
+export const createJavaScriptSemanticGraphUnknown = (input, evidenceContexts) => {
     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),
+        evidence: evidenceContexts.intern(parsed.evidence),
     };
     return javaScriptSemanticUnknownSchema.parse({
         ...semantic,
-        unknown_id: `jsrg_unknown_${canonicalDigest(semantic, "JavaScript semantic graph")}`,
+        unknown_id: `jsrg_unknown_${digestCanonicalValue(semantic, "JavaScript semantic graph")}`,
     });
 };
 /** Normalize one function fingerprint and derive its component commitment. */
-export const createJavaScriptSemanticFingerprint = (input) => {
+export const createJavaScriptSemanticFingerprint = (input, evidenceContexts) => {
     const parsed = javaScriptSemanticFingerprintInputSchema.parse(input);
     const semantic = {
         ...parsed,
@@ -71,13 +110,13 @@ export const createJavaScriptSemanticFingerprint = (input) => {
             effects: uniqueSorted(parsed.components.effects),
         },
         limitations: uniqueSorted(parsed.limitations),
-        evidence: normalizeEvidence(parsed.evidence),
+        evidence: evidenceContexts.intern(parsed.evidence),
     };
-    const fingerprintSha256 = canonicalDigest(semantic.components, "JavaScript semantic graph");
+    const fingerprintSha256 = digestCanonicalValue(semantic.components, "JavaScript semantic graph");
     return javaScriptSemanticFingerprintSchema.parse({
         ...semantic,
         fingerprint_sha256: fingerprintSha256,
-        fingerprint_id: `jsrg_fingerprint_${canonicalDigest({
+        fingerprint_id: `jsrg_fingerprint_${digestCanonicalValue({
             function_node_id: semantic.function_node_id,
             algorithm: semantic.algorithm,
             fingerprint_sha256: fingerprintSha256,
@@ -86,7 +125,7 @@ export const createJavaScriptSemanticFingerprint = (input) => {
 };
 const sortedUniqueIssue = (values, path, label, context) => {
     for (let index = 1; index < values.length; index += 1) {
-        if (compareCodePoints(values[index - 1] ?? "", values[index] ?? "") < 0)
+        if (compareUnicodeCodePoints(values[index - 1] ?? "", values[index] ?? "") < 0)
             continue;
         context.addIssue({
             code: "custom",
@@ -96,7 +135,7 @@ const sortedUniqueIssue = (values, path, label, context) => {
         return;
     }
 };
-const checkCoverage = (graph, context) => {
+function* checkCoverageSteps(graph, context) {
     const families = graph.coverage.families.map(({ family }) => family);
     if (canonicalJson(families, "JavaScript semantic graph") !==
         canonicalJson(JAVASCRIPT_SEMANTIC_RELATION_FAMILIES, "JavaScript semantic graph"))
@@ -122,11 +161,18 @@ const checkCoverage = (graph, context) => {
             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) {
+    for (const [index, relation] of graph.relations.entries()) {
+        if (index % 256 === 0)
+            yield;
         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]));
+    const unknownsById = new Map();
+    for (const [index, unknown] of graph.unknowns.entries()) {
+        if (index % 256 === 0)
+            yield;
+        unknownsById.set(unknown.unknown_id, unknown);
+    }
     for (const [index, family] of graph.coverage.families.entries()) {
         if (family.retained_relations !== relationsByFamily.get(family.family))
             context.addIssue({
@@ -148,17 +194,71 @@ const checkCoverage = (graph, context) => {
                 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.evidence_contexts.map(({ context_id }) => context_id), ["evidence_contexts"], "Evidence contexts", 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) => {
+function* checkEvidenceContextReferencesSteps(graph, context) {
+    const contexts = new Map(graph.evidence_contexts.map((value) => [value.context_id, value]));
+    const referenced = new Set();
+    const validateReferences = function* (entities, entityKind) {
+        for (const [index, { evidence }] of entities.entries()) {
+            if (index % 256 === 0)
+                yield;
+            referenced.add(evidence.context_id);
+            const evidenceContext = contexts.get(evidence.context_id);
+            if (evidenceContext === undefined) {
+                context.addIssue({
+                    code: "custom",
+                    path: [entityKind, index, "evidence", "context_id"],
+                    message: "Evidence reference names an absent context",
+                });
+                continue;
+            }
+            const { context_id: _contextId, ...evidenceValue } = evidenceContext;
+            if (!applicationGraphEvidenceSchema.safeParse({
+                ...evidenceValue,
+                location: evidence.location,
+            }).success)
+                context.addIssue({
+                    code: "custom",
+                    path: [entityKind, index, "evidence"],
+                    message: "Evidence context is incompatible with its fact location",
+                });
+        }
+    };
+    yield* validateReferences(graph.nodes, "nodes");
+    yield* validateReferences(graph.relations, "relations");
+    yield* validateReferences(graph.unknowns, "unknowns");
+    yield* validateReferences(graph.fingerprints, "fingerprints");
+    for (const [index, evidenceContext] of graph.evidence_contexts.entries()) {
+        if (index % 256 === 0)
+            yield;
+        const { context_id: identifier, ...value } = evidenceContext;
+        if (identifier !== evidenceContextId(value))
+            context.addIssue({
+                code: "custom",
+                path: ["evidence_contexts", index, "context_id"],
+                message: "Evidence context identifier is stale",
+            });
+        if (!referenced.has(identifier))
+            context.addIssue({
+                code: "custom",
+                path: ["evidence_contexts", index],
+                message: "Evidence context is not referenced by a graph fact",
+            });
+    }
+}
+function* checkNodesSteps(graph, nodes, context) {
     for (const [index, node] of graph.nodes.entries()) {
+        if (index % 256 === 0)
+            yield;
         if (node.node_id !== javaScriptSemanticNodeId(node))
             context.addIssue({
                 code: "custom",
@@ -173,21 +273,27 @@ const checkNodes = (graph, nodes, context) => {
                 message: "Function owner must name a function node",
             });
     }
-};
-const checkRoots = (graph, nodes, context) => {
-    for (const root of graph.root_node_ids)
+}
+function* checkRootsSteps(graph, nodes, context) {
+    for (const [index, root] of graph.root_node_ids.entries()) {
+        if (index % 256 === 0)
+            yield;
         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) => {
+    }
+}
+function* checkRelationsSteps(graph, nodes, evidenceContexts, context) {
     for (const [index, relation] of graph.relations.entries()) {
+        if (index % 256 === 0)
+            yield;
         const { relation_id: identifier, ...semantic } = relation;
         if (identifier !==
-            "jsrg_relation_" + canonicalDigest(semantic, "JavaScript semantic graph"))
+            "jsrg_relation_" +
+                digestCanonicalValue(semantic, "JavaScript semantic graph"))
             context.addIssue({
                 code: "custom",
                 path: ["relations", index, "relation_id"],
@@ -207,19 +313,22 @@ const checkRelations = (graph, nodes, context) => {
                 message: "Semantic relations cannot be self-referential",
             });
         if (relation.resolution === "candidate" &&
-            relation.evidence.state === "observed")
+            evidenceContexts.get(relation.evidence.context_id)?.state === "observed")
             context.addIssue({
                 code: "custom",
                 path: ["relations", index, "evidence", "state"],
                 message: "Candidate relations cannot claim observed resolution",
             });
     }
-};
-const checkUnknowns = (graph, nodes, context) => {
+}
+function* checkUnknownsSteps(graph, nodes, evidenceContexts, context) {
     for (const [index, unknown] of graph.unknowns.entries()) {
+        if (index % 256 === 0)
+            yield;
         const { unknown_id: identifier, ...semantic } = unknown;
         if (identifier !==
-            "jsrg_unknown_" + canonicalDigest(semantic, "JavaScript semantic graph"))
+            "jsrg_unknown_" +
+                digestCanonicalValue(semantic, "JavaScript semantic graph"))
             context.addIssue({
                 code: "custom",
                 path: ["unknowns", index, "unknown_id"],
@@ -243,14 +352,15 @@ const checkUnknowns = (graph, nodes, context) => {
                 path: ["unknowns", index, "relation_kinds"],
                 message: "Unknown relation kinds must belong to their declared family",
             });
-        if (!["unknown", "unavailable"].includes(unknown.evidence.state))
+        const evidenceState = evidenceContexts.get(unknown.evidence.context_id)?.state;
+        if (evidenceState !== "unknown" && evidenceState !== "unavailable")
             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())
@@ -261,8 +371,10 @@ const checkUnknownReferences = (graph, context) => {
                 message: "Family coverage references an absent unknown frontier",
             });
 };
-const checkFingerprints = (graph, nodes, context) => {
+function* checkFingerprintsSteps(graph, nodes, context) {
     for (const [index, fingerprint] of graph.fingerprints.entries()) {
+        if (index % 256 === 0)
+            yield;
         if (nodes.get(fingerprint.function_node_id)?.kind !== "function")
             context.addIssue({
                 code: "custom",
@@ -270,14 +382,14 @@ const checkFingerprints = (graph, nodes, context) => {
                 message: "Fingerprint must name a function node",
             });
         if (fingerprint.fingerprint_sha256 !==
-            canonicalDigest(fingerprint.components, "JavaScript semantic graph"))
+            digestCanonicalValue(fingerprint.components, "JavaScript semantic graph"))
             context.addIssue({
                 code: "custom",
                 path: ["fingerprints", index, "fingerprint_sha256"],
                 message: "Fingerprint component commitment is stale",
             });
         const expectedIdentifier = "jsrg_fingerprint_" +
-            canonicalDigest({
+            digestCanonicalValue({
                 function_node_id: fingerprint.function_node_id,
                 algorithm: fingerprint.algorithm,
                 fingerprint_sha256: fingerprint.fingerprint_sha256,
@@ -296,29 +408,45 @@ const checkFingerprints = (graph, nodes, context) => {
                 message: "Incomplete fingerprints require a limitation",
             });
     }
-};
-const checkGraphContent = (graph, context) => {
+}
+function* checkGraphContentSteps(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);
+    yield* checkEvidenceContextReferencesSteps(graph, context);
+    const evidenceContexts = new Map(graph.evidence_contexts.map((evidenceContext) => [
+        evidenceContext.context_id,
+        evidenceContext,
+    ]));
+    const nodes = new Map();
+    for (const [index, node] of graph.nodes.entries()) {
+        if (index % 256 === 0)
+            yield;
+        nodes.set(node.node_id, node);
+    }
+    yield* checkNodesSteps(graph, nodes, context);
+    yield* checkRootsSteps(graph, nodes, context);
+    yield* checkRelationsSteps(graph, nodes, evidenceContexts, context);
+    yield* checkUnknownsSteps(graph, nodes, evidenceContexts, context);
     checkUnknownReferences(graph, context);
-    checkFingerprints(graph, nodes, context);
-    checkCoverage(graph, context);
+    yield* checkFingerprintsSteps(graph, nodes, context);
+    yield* checkCoverageSteps(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 checkGraphContent = (graph, context) => {
+    const steps = checkGraphContentSteps(graph, context);
+    while (!steps.next().done) {
+        // Synchronous callers apply the same integrity checks without scheduling.
+    }
 };
 const checkGraph = (graph, context) => {
     checkGraphContent(graph, context);
     const { graph_id: identifier, ...semantic } = graph;
     if (identifier !==
-        "jsrg_" + canonicalDigest(semantic, "JavaScript semantic graph"))
+        "jsrg_" + digestCanonicalValue(semantic, "JavaScript semantic graph"))
         context.addIssue({
             code: "custom",
             path: ["graph_id"],
@@ -327,34 +455,43 @@ const checkGraph = (graph, context) => {
 };
 /** Strict semantic graph schema with verified canonical commitments. */
 export const javaScriptSemanticGraphSchema = javaScriptSemanticGraphRecordSchema.superRefine(checkGraph);
+/** Resolve one fact's compact provenance without changing its stored shape. */
+export const resolveJavaScriptSemanticEvidence = (graph, reference) => {
+    const context = graph.evidence_contexts.find(({ context_id }) => context_id === reference.context_id);
+    if (context === undefined)
+        throw new TypeError("Semantic evidence reference names an absent context");
+    const { context_id: _contextId, ...evidenceContext } = context;
+    return { ...evidenceContext, location: reference.location };
+};
+const normalizeGraphInput = (parsed) => ({
+    ...parsed,
+    root_node_ids: uniqueSorted(parsed.root_node_ids),
+    evidence_contexts: [...parsed.evidence_contexts].sort((left, right) => compareUnicodeCodePoints(left.context_id, right.context_id)),
+    nodes: [...parsed.nodes].sort((left, right) => compareUnicodeCodePoints(left.node_id, right.node_id)),
+    relations: [...parsed.relations].sort((left, right) => compareUnicodeCodePoints(left.relation_id, right.relation_id)),
+    fingerprints: [...parsed.fingerprints].sort((left, right) => compareUnicodeCodePoints(left.fingerprint_id, right.fingerprint_id)),
+    unknowns: [...parsed.unknowns].sort((left, right) => compareUnicodeCodePoints(left.unknown_id, right.unknown_id)),
+    coverage: {
+        ...parsed.coverage,
+        limits: [...parsed.coverage.limits].sort((left, right) => compareUnicodeCodePoints(canonicalJson(left, "JavaScript semantic graph"), canonicalJson(right, "JavaScript semantic graph"))),
+        families: [...parsed.coverage.families]
+            .map((family) => ({
+            ...family,
+            unknown_ids: uniqueSorted(family.unknown_ids),
+        }))
+            .sort((left, right) => compareUnicodeCodePoints(left.family, right.family)),
+    },
+    limitations: uniqueSorted(parsed.limitations),
+});
 /** 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, "JavaScript semantic graph"), canonicalJson(right, "JavaScript semantic graph"))),
-            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),
-    };
+    const semantic = normalizeGraphInput(javaScriptSemanticGraphInputSchema.parse(input));
     // The input schema already cloned and validated every field. Validate the
     // normalized relationships in place, then derive the only added field. The
     // public schema still verifies arbitrary records and their commitments.
     const record = {
         ...semantic,
-        graph_id: `jsrg_${canonicalDigest(semantic, "JavaScript semantic graph")}`,
+        graph_id: `jsrg_${digestCanonicalValue(semantic, "JavaScript semantic graph")}`,
     };
     const issues = [];
     checkGraphContent(record, {
@@ -367,9 +504,21 @@ export const createJavaScriptSemanticGraph = (input) => {
     return record;
 };
 const validatedImmutableSemanticGraphs = new WeakSet();
-/** Clone and validate synchronously, then return steps to seal the owned graph. */
-export const createImmutableJavaScriptSemanticGraphSteps = (input) => sealValidatedSemanticGraphSteps(createJavaScriptSemanticGraph(input));
-function* sealValidatedSemanticGraphSteps(graph) {
+/** Clone input synchronously; commit, check and seal the owned graph in steps. */
+export const createImmutableJavaScriptSemanticGraphSteps = (input) => validateAndSealSemanticGraphSteps(normalizeGraphInput(javaScriptSemanticGraphInputSchema.parse(input)));
+function* validateAndSealSemanticGraphSteps(semantic) {
+    const graph = {
+        ...semantic,
+        graph_id: `jsrg_${yield* canonicalJsonDigestSteps(semantic)}`,
+    };
+    const issues = [];
+    yield* checkGraphContentSteps(graph, {
+        addIssue: (issue) => {
+            issues.push(issue);
+        },
+    });
+    if (issues.length > 0)
+        throw new z.ZodError(issues);
     yield* freezeOwnedJsonSnapshotSteps(graph);
     validatedImmutableSemanticGraphs.add(graph);
     return graph;

package/dist/domain/javascript/javascriptSemanticGraphSchemas.js

@@ -1,5 +1,5 @@
 import { z } from "zod";
-import { applicationGraphEvidenceSchema } from "./javascriptApplicationEvidenceSchemas.js";
+import { applicationGraphEvidenceContextSchema, applicationGraphEvidenceLocationSchema, applicationGraphEvidenceSchema, } from "./javascriptApplicationEvidenceSchemas.js";
 import { jsonValueSchema } from "../jsonValue.js";
 import { digestSchema } from "../digests.js";
 import { prefixedDigestSchema } from "../digests.js";
@@ -11,6 +11,18 @@ const semanticRelationIdSchema = z
 const semanticUnknownIdSchema = z
     .string()
     .regex(/^jsrg_unknown_[a-f0-9]{64}$/u);
+const semanticEvidenceContextIdSchema = z
+    .string()
+    .regex(/^jsrg_evidence_[a-f0-9]{64}$/u);
+/** One canonical owner for provenance shared by semantic graph facts. */
+export const javaScriptSemanticEvidenceContextSchema = applicationGraphEvidenceContextSchema.extend({
+    context_id: semanticEvidenceContextIdSchema,
+});
+/** Location-specific reference to one exact graph-level evidence context. */
+export const javaScriptSemanticEvidenceReferenceSchema = z.strictObject({
+    context_id: semanticEvidenceContextIdSchema,
+    location: applicationGraphEvidenceLocationSchema,
+});
 /** Semantic entity kinds admitted by JavaScript Semantic Relation Graph. */
 export const JAVASCRIPT_SEMANTIC_NODE_KINDS = [
     "module",
@@ -188,6 +200,7 @@ export const javaScriptSemanticNodeInputSchema = z.strictObject({
 });
 /** One exact, artifact-version semantic entity. */
 export const javaScriptSemanticNodeSchema = javaScriptSemanticNodeInputSchema.extend({
+    evidence: javaScriptSemanticEvidenceReferenceSchema,
     node_id: semanticNodeIdSchema,
     identifier_strategy: z.strictObject({
         strategy: z.literal("semantic-content-sha256"),
@@ -205,6 +218,7 @@ export const javaScriptSemanticRelationInputSchema = z.strictObject({
 });
 /** One canonical directed semantic relationship. */
 export const javaScriptSemanticRelationSchema = javaScriptSemanticRelationInputSchema.extend({
+    evidence: javaScriptSemanticEvidenceReferenceSchema,
     relation_id: semanticRelationIdSchema,
     identifier_strategy: z.strictObject({
         strategy: z.literal("semantic-content-sha256"),
@@ -222,6 +236,7 @@ export const JAVASCRIPT_SEMANTIC_UNKNOWN_REASONS = [
     "incomplete-module",
     "missing-source",
     "resource-limit",
+    "unknown-value",
     "unsupported-syntax",
 ];
 /** One unresolved semantic frontier before its ID is derived. */
@@ -236,6 +251,7 @@ export const javaScriptSemanticUnknownInputSchema = z.strictObject({
 });
 /** One canonical unresolved semantic frontier. */
 export const javaScriptSemanticUnknownSchema = javaScriptSemanticUnknownInputSchema.extend({
+    evidence: javaScriptSemanticEvidenceReferenceSchema,
     unknown_id: semanticUnknownIdSchema,
 });
 const fingerprintComponentsSchema = z.strictObject({
@@ -265,6 +281,7 @@ export const javaScriptSemanticFingerprintInputSchema = z.strictObject({
 });
 /** One canonical function fingerprint record. */
 export const javaScriptSemanticFingerprintSchema = javaScriptSemanticFingerprintInputSchema.extend({
+    evidence: javaScriptSemanticEvidenceReferenceSchema,
     fingerprint_id: prefixedDigestSchema("jsrg_fingerprint"),
     fingerprint_sha256: digestSchema,
 });
@@ -293,6 +310,7 @@ export const javaScriptSemanticGraphInputSchema = z.strictObject({
     root_artifact_sha256: digestSchema,
     application_graph_id: prefixedDigestSchema("jag"),
     root_node_ids: z.array(semanticNodeIdSchema).min(1),
+    evidence_contexts: z.array(javaScriptSemanticEvidenceContextSchema),
     nodes: z.array(javaScriptSemanticNodeSchema).min(1),
     relations: z.array(javaScriptSemanticRelationSchema),
     fingerprints: z.array(javaScriptSemanticFingerprintSchema),

package/dist/domain/javascript/javascriptSemanticIr.js

@@ -1,7 +1,3 @@
-/** Find the innermost resolved reference at one source coordinate. */
-export const semanticReferenceAt = (ir, line, column) => ir.references.find(({ location }) => location.start.line === line && location.start.column === column);
-/** Read one binding by its deterministic semantic identifier. */
-export const semanticBinding = (ir, bindingId) => ir.bindings.find(({ bindingId: candidate }) => candidate === bindingId);
 /** Fail-closed result when Babel cannot produce an inert syntax tree. */
 export const failedJavaScriptSemanticIr = () => ({
     schema: "JavaScriptSemanticIR",