rea-agents 6.2.0 → 6.4.0

package/dist/domain/javascript/javascriptSemanticGraph.js

@@ -1,69 +1,124 @@
 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 { JAVASCRIPT_SEMANTIC_RELATION_FAMILIES, JAVASCRIPT_SEMANTIC_RELATION_FAMILY, javaScriptSemanticFingerprintInputSchema, javaScriptSemanticFingerprintSchema, javaScriptSemanticGraphInputSchema, javaScriptSemanticGraphRecordSchema, javaScriptSemanticNodeInputSchema, javaScriptSemanticNodeSchema, javaScriptSemanticRelationInputSchema, javaScriptSemanticRelationSchema, javaScriptSemanticUnknownInputSchema, javaScriptSemanticUnknownSchema, } from "./javascriptSemanticGraphSchemas.js";
+import { arrayContainerSchema, parseElementSteps, } from "../zodCollectionSteps.js";
+import { applicationGraphEvidenceSchema } from "./javascriptApplicationEvidenceSchemas.js";
+import { JAVASCRIPT_SEMANTIC_RELATION_FAMILIES, JAVASCRIPT_SEMANTIC_RELATION_FAMILY, javaScriptSemanticFingerprintInputSchema, javaScriptSemanticEvidenceContextSchema, javaScriptSemanticGraphInputSchema, javaScriptSemanticGraphRecordSchema, javaScriptSemanticNodeInputSchema, javaScriptSemanticRelationInputSchema, javaScriptSemanticUnknownInputSchema, } 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();
+    // Facts share a few contexts, so key them by canonical text and hash each
+    // distinct context once instead of on every fact.
+    #idsByCanonicalContext = new Map();
+    /** Intern normalized non-location provenance at fact construction. */
+    intern(evidence) {
+        const normalized = normalizeEvidence(evidence);
+        const { location, ...context } = normalized;
+        const canonicalContext = canonicalJson(context, "JavaScript semantic graph");
+        const internedId = this.#idsByCanonicalContext.get(canonicalContext);
+        if (internedId !== undefined)
+            return { context_id: internedId, location };
+        const contextId = evidenceContextId(context);
+        // This canonical context is new, so a row already stored under its
+        // digest holds different provenance.
+        if (this.#contexts.has(contextId))
+            throw new TypeError("JavaScript semantic evidence context digest collision");
+        this.#contexts.set(contextId, { ...context, context_id: contextId });
+        this.#idsByCanonicalContext.set(canonicalContext, contextId);
+        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();
+        this.#idsByCanonicalContext.clear();
+    }
+    /** Validate and intern provenance decoded in this realm from an analysis worker. */
+    adopt(input) {
+        const context = javaScriptSemanticEvidenceContextSchema.parse(input);
+        const { context_id: identifier, ...value } = context;
+        if (identifier !== evidenceContextId(value))
+            throw new TypeError("Transferred semantic evidence context identifier is stale");
+        const canonical = canonicalJson(value, "JavaScript semantic evidence context");
+        const existing = this.#contexts.get(identifier);
+        if (existing !== undefined) {
+            const { context_id: _existingIdentifier, ...existingValue } = existing;
+            if (canonical !==
+                canonicalJson(existingValue, "JavaScript semantic evidence context"))
+                throw new TypeError("Transferred semantic evidence context digest collision");
+        }
+        this.#contexts.set(identifier, context);
+        this.#idsByCanonicalContext.set(canonical, identifier);
+    }
+}
 /** 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),
-        identifier_strategy: {
-            strategy: "semantic-content-sha256",
-            stability: "artifact-version",
-        },
+        evidence: evidenceContexts.intern(parsed.evidence),
     };
-    return javaScriptSemanticNodeSchema.parse({
+    return {
         ...semantic,
         node_id: javaScriptSemanticNodeId(semantic),
-    });
+    };
 };
 /** 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),
-        identifier_strategy: {
-            strategy: "semantic-content-sha256",
-            stability: "relationship-exact",
-        },
+        evidence: evidenceContexts.intern(parsed.evidence),
     };
-    return javaScriptSemanticRelationSchema.parse({
+    return {
         ...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({
+    return {
         ...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,
@@ -72,22 +127,22 @@ 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");
-    return javaScriptSemanticFingerprintSchema.parse({
+    const fingerprintSha256 = digestCanonicalValue(semantic.components, "JavaScript semantic graph");
+    return {
         ...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,
         }, "JavaScript semantic graph")}`,
-    });
+    };
 };
 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",
@@ -159,12 +214,64 @@ function* checkCoverageSteps(graph, context) {
 }
 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);
 };
+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)
@@ -196,13 +303,14 @@ function* checkRootsSteps(graph, nodes, context) {
             });
     }
 }
-function* checkRelationsSteps(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"],
@@ -222,7 +330,7 @@ function* checkRelationsSteps(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"],
@@ -230,13 +338,14 @@ function* checkRelationsSteps(graph, nodes, context) {
             });
     }
 }
-function* checkUnknownsSteps(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"],
@@ -260,7 +369,8 @@ function* checkUnknownsSteps(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"],
@@ -289,14 +399,14 @@ function* checkFingerprintsSteps(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,
@@ -318,6 +428,11 @@ function* checkFingerprintsSteps(graph, nodes, context) {
 }
 function* checkGraphContentSteps(graph, context) {
     checkCanonicalOrder(graph, 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)
@@ -326,8 +441,8 @@ function* checkGraphContentSteps(graph, context) {
     }
     yield* checkNodesSteps(graph, nodes, context);
     yield* checkRootsSteps(graph, nodes, context);
-    yield* checkRelationsSteps(graph, nodes, context);
-    yield* checkUnknownsSteps(graph, nodes, context);
+    yield* checkRelationsSteps(graph, nodes, evidenceContexts, context);
+    yield* checkUnknownsSteps(graph, nodes, evidenceContexts, context);
     checkUnknownReferences(graph, context);
     yield* checkFingerprintsSteps(graph, nodes, context);
     yield* checkCoverageSteps(graph, context);
@@ -348,7 +463,7 @@ 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"],
@@ -357,22 +472,31 @@ 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),
-    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)),
+    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) => compareCodePoints(canonicalJson(left, "JavaScript semantic graph"), canonicalJson(right, "JavaScript semantic graph"))),
+        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) => compareCodePoints(left.family, right.family)),
+            .sort((left, right) => compareUnicodeCodePoints(left.family, right.family)),
     },
     limitations: uniqueSorted(parsed.limitations),
 });
@@ -384,7 +508,7 @@ export const createJavaScriptSemanticGraph = (input) => {
     // 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, {
@@ -397,8 +521,37 @@ export const createJavaScriptSemanticGraph = (input) => {
     return record;
 };
 const validatedImmutableSemanticGraphs = new WeakSet();
+const semanticGraphShape = javaScriptSemanticGraphInputSchema.shape;
+const semanticGraphContainerSchema = javaScriptSemanticGraphInputSchema.extend({
+    evidence_contexts: arrayContainerSchema(semanticGraphShape.evidence_contexts),
+    nodes: arrayContainerSchema(semanticGraphShape.nodes),
+    relations: arrayContainerSchema(semanticGraphShape.relations),
+    fingerprints: arrayContainerSchema(semanticGraphShape.fingerprints),
+    unknowns: arrayContainerSchema(semanticGraphShape.unknowns),
+});
 /** Clone input synchronously; commit, check and seal the owned graph in steps. */
 export const createImmutableJavaScriptSemanticGraphSteps = (input) => validateAndSealSemanticGraphSteps(normalizeGraphInput(javaScriptSemanticGraphInputSchema.parse(input)));
+/**
+ * Seal a graph whose input the caller transfers: the caller neither retains nor
+ * mutates any part of it afterwards. Only the graph's own fields are validated
+ * synchronously; collection elements are validated and cloned in steps, because
+ * a whole-graph parse of a large application held the event loop for seconds.
+ */
+export const sealTransferredJavaScriptSemanticGraphSteps = (input) => parseAndSealSemanticGraphSteps(semanticGraphContainerSchema.parse(input));
+function* parseAndSealSemanticGraphSteps(container) {
+    const issues = [];
+    const parsed = {
+        ...container,
+        evidence_contexts: yield* parseElementSteps(semanticGraphShape.evidence_contexts.element, container.evidence_contexts, ["evidence_contexts"], issues),
+        nodes: yield* parseElementSteps(semanticGraphShape.nodes.element, container.nodes, ["nodes"], issues),
+        relations: yield* parseElementSteps(semanticGraphShape.relations.element, container.relations, ["relations"], issues),
+        fingerprints: yield* parseElementSteps(semanticGraphShape.fingerprints.element, container.fingerprints, ["fingerprints"], issues),
+        unknowns: yield* parseElementSteps(semanticGraphShape.unknowns.element, container.unknowns, ["unknowns"], issues),
+    };
+    if (issues.length > 0)
+        throw new z.ZodError(issues);
+    return yield* validateAndSealSemanticGraphSteps(normalizeGraphInput(parsed));
+}
 function* validateAndSealSemanticGraphSteps(semantic) {
     const graph = {
         ...semantic,

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,11 +200,8 @@ export const javaScriptSemanticNodeInputSchema = z.strictObject({
 });
 /** 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"),
-    }),
+    evidence: javaScriptSemanticEvidenceReferenceSchema,
+    node_id: semanticNodeIdSchema.describe("SHA-256 of the node kind and identity; stable for one artifact version."),
 });
 /** One directed semantic relationship before its ID is derived. */
 export const javaScriptSemanticRelationInputSchema = z.strictObject({
@@ -205,11 +214,8 @@ export const javaScriptSemanticRelationInputSchema = z.strictObject({
 });
 /** 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"),
-    }),
+    evidence: javaScriptSemanticEvidenceReferenceSchema,
+    relation_id: semanticRelationIdSchema.describe("SHA-256 of the exact relation content, including its evidence reference."),
 });
 /** Reasons semantic analysis can leave an explicit frontier. */
 export const JAVASCRIPT_SEMANTIC_UNKNOWN_REASONS = [
@@ -222,6 +228,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 +243,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 +273,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 +302,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",

package/dist/domain/javascript/javascriptSemanticIterationSources.js

@@ -0,0 +1,139 @@
+import * as t from "@babel/types";
+import { semanticObjectPatternKeys, semanticStaticPropertyKey, } from "./javascriptAstValues.js";
+import { semanticArrayIndex, } from "./javascriptSemanticPropertyPaths.js";
+import { compareUnicodeCodePoints } from "../unicodeCodePointOrder.js";
+const add = (sources, source, mutation, guards, kind = "iteration") => {
+    sources.push({
+        kind,
+        node: source.node,
+        projection: source.projection,
+        mutation,
+        ...guards,
+    });
+};
+const project = (source, key) => {
+    if (source === undefined)
+        return undefined;
+    const index = key === null ? null : semanticArrayIndex(key);
+    return {
+        node: source.node,
+        projection: [
+            ...source.projection,
+            source.restStartIndex !== undefined && index !== null
+                ? source.restStartIndex + index
+                : key,
+        ],
+    };
+};
+const visit = (context, pattern, source, guards = {}) => {
+    const { sources, mutation } = context;
+    if (t.isMemberExpression(pattern)) {
+        // Property stores have no lexical alias binding. Preserve the selected
+        // reference's escape rather than claiming later writes cannot reach it.
+        if (source !== undefined)
+            add(sources, source.restStartIndex === undefined
+                ? source
+                : {
+                    node: source.node,
+                    projection: [
+                        ...source.projection,
+                        { excludedKeys: [], startIndex: source.restStartIndex },
+                    ],
+                }, mutation, guards, "reference-store");
+        return;
+    }
+    if (t.isTSParameterProperty(pattern)) {
+        visit(context, pattern.parameter, source, guards);
+        return;
+    }
+    if (t.isAssignmentPattern(pattern)) {
+        visit(context, pattern.left, source, {
+            ...guards,
+            requiredSources: [
+                ...(guards.requiredSources ?? []),
+                ...(source === undefined ? [] : [source]),
+            ],
+        });
+        visit(context, pattern.left, { node: pattern.right, projection: [] }, {
+            ...guards,
+            fallbackSources: [
+                ...(guards.fallbackSources ?? []),
+                ...(source === undefined ? [] : [source]),
+            ],
+        });
+        return;
+    }
+    if (t.isObjectPattern(pattern)) {
+        for (const property of pattern.properties) {
+            if (t.isRestElement(property)) {
+                // A rest copy owns its scalar slots; only selected child references
+                // escape when that fresh copy is stored through a member target.
+                visit(context, property.argument, source === undefined
+                    ? undefined
+                    : {
+                        node: source.node,
+                        projection: [
+                            ...source.projection,
+                            {
+                                excludedKeys: [
+                                    ...new Set(semanticObjectPatternKeys(pattern)),
+                                ].sort(compareUnicodeCodePoints),
+                            },
+                        ],
+                    }, guards);
+                continue;
+            }
+            visit(context, property.value, project(source, semanticStaticPropertyKey(property.key, property.computed)), guards);
+        }
+        return;
+    }
+    if (t.isArrayPattern(pattern)) {
+        if (source !== undefined && source.restStartIndex === undefined)
+            add(sources, source, mutation, guards);
+        pattern.elements.forEach((element, index) => {
+            if (element === null)
+                return;
+            if (t.isRestElement(element))
+                visit(context, element.argument, source === undefined
+                    ? undefined
+                    : {
+                        node: source.node,
+                        projection: source.projection,
+                        restStartIndex: (source.restStartIndex ?? 0) + index,
+                    }, guards);
+            else
+                visit(context, element, project(source, index), guards);
+        });
+        return;
+    }
+    if (t.isRestElement(pattern))
+        visit(context, pattern.argument, undefined, guards);
+};
+/** Describe iterator receivers and property reference stores without evaluation. */
+export const semanticIterationSources = (node, parent) => {
+    const sources = [];
+    const context = { sources, mutation: node };
+    if (t.isVariableDeclarator(node) && node.init != null)
+        visit(context, node.id, { node: node.init, projection: [] });
+    else if (t.isAssignmentExpression(node) &&
+        ["=", "||=", "&&=", "??="].includes(node.operator))
+        visit(context, node.left, { node: node.right, projection: [] });
+    else if (t.isForOfStatement(node)) {
+        add(sources, { node: node.right, projection: [] }, node, {});
+        const source = { node: node.right, projection: [null] };
+        if (t.isVariableDeclaration(node.left)) {
+            for (const declaration of node.left.declarations)
+                visit(context, declaration.id, source);
+        }
+        else
+            visit(context, node.left, source);
+    }
+    else if (t.isSpreadElement(node) && t.isArrayExpression(parent))
+        add(sources, { node: node.argument, projection: [] }, node, {});
+    else if (t.isYieldExpression(node) && node.delegate && node.argument != null)
+        add(sources, { node: node.argument, projection: [] }, node, {});
+    else if (t.isFunction(node))
+        for (const parameter of node.params)
+            visit(context, parameter, undefined);
+    return sources;
+};