@lucern/graph-primitives 1.0.16 → 1.0.18

package/dist/epistemicEvidenceMutations.js

@@ -2,6 +2,7 @@ import { v } from 'convex/values';
 import { requireProjectAccess, checkProjectAccess } from '@lucern/access-control/access';
 import { permissiveReturn } from '@lucern/contracts/schema-helpers/validators';
 import { componentsGeneric, anyApi, mutationGeneric, internalMutationGeneric } from 'convex/server';
+import { generateGlobalId } from '@lucern/contracts/ids';
 import { isNodeType, getLayerForNodeType } from '@lucern/contracts/schema-helpers/spine/tables/epistemicNodes';
 import '@lucern/access-control/audience';
 
@@ -52,18 +53,6 @@ async function scheduleEmbeddingGeneration(args) {
     );
   }
 }
-
-// src/globalId.ts
-function generateGlobalId() {
-  const bytes = new Uint8Array(16);
-  crypto.getRandomValues(bytes);
-  bytes[6] = bytes[6] & 15 | 64;
-  bytes[8] = bytes[8] & 63 | 128;
-  const hex = Array.from(bytes, (b) => b.toString(16).padStart(2, "0")).join(
-    ""
-  );
-  return `${hex.slice(0, 8)}-${hex.slice(8, 12)}-${hex.slice(12, 16)}-${hex.slice(16, 20)}-${hex.slice(20)}`;
-}
 var LEGACY_SCOPE_FIELD = "graphScopeProjectId";
 function asMappedProjectId(topic) {
   if (!topic) {
@@ -773,6 +762,91 @@ async function resolveEvidenceScopeOrNull(ctx, args) {
 }
 
 // src/epistemicEvidenceMutations.ts
+function assertSignedImpactScore(value, context) {
+  if (typeof value !== "number" || !Number.isFinite(value) || value === 0 || value < -1 || value > 1) {
+    throw new Error(`${context} requires explicit nonzero weight in [-1, 1]`);
+  }
+  return value;
+}
+function normalizeEvidenceRelation(relation, weight, context) {
+  if (relation === "supports" || relation === "contradicts") {
+    if (relation === "supports" && weight < 0) {
+      throw new Error(`${context} supports relation requires positive weight`);
+    }
+    if (relation === "contradicts" && weight > 0) {
+      throw new Error(`${context} contradicts relation requires negative weight`);
+    }
+    return relation;
+  }
+  return weight < 0 ? "contradicts" : "supports";
+}
+async function createEvidenceBeliefEdge(ctx, args) {
+  const edgeGlobalId = crypto.randomUUID();
+  const confidence = Math.abs(args.weight);
+  const existingEdges = await ctx.db.query("epistemicEdges").withIndex(
+    "by_from_to",
+    (q) => q.eq("fromNodeId", args.evidenceNodeId).eq("toNodeId", args.beliefNodeId)
+  ).collect();
+  const existing = existingEdges.find((edge) => edge.edgeType === "informs");
+  const edgeDoc = {
+    globalId: edgeGlobalId,
+    fromNodeId: args.evidenceNodeId,
+    toNodeId: args.beliefNodeId,
+    sourceGlobalId: args.evidenceGlobalId,
+    targetGlobalId: args.beliefGlobalId,
+    edgeType: "informs",
+    weight: args.weight,
+    confidence,
+    context: args.rationale,
+    reasoningMethod: "testimonial",
+    derivationType: "evidence_sl_scoring",
+    metadata: {
+      relation: args.relation,
+      confidence,
+      impactScore: args.weight,
+      invariant: "evidence.belief_impact_required"
+    },
+    createdBy: args.userId,
+    createdAt: Date.now(),
+    updatedAt: Date.now(),
+    topicId: args.topicId,
+    projectId: args.projectId,
+    fromNodeType: "evidence",
+    toNodeType: "belief",
+    fromLayer: "L2",
+    toLayer: "L3"
+  };
+  if (existing) {
+    await ctx.db.patch(existing._id, {
+      ...edgeDoc,
+      globalId: existing.globalId,
+      createdAt: existing.createdAt ?? edgeDoc.createdAt
+    });
+  } else {
+    await ctx.db.insert("epistemicEdges", edgeDoc);
+  }
+  await ctx.scheduler.runAfter(5e3, internal.neo4jEdgeAPI.createEdge, {
+    globalId: existing?.globalId ?? edgeGlobalId,
+    fromGlobalId: args.evidenceGlobalId,
+    toGlobalId: args.beliefGlobalId,
+    edgeType: "informs",
+    weight: args.weight,
+    confidence,
+    createdBy: args.userId,
+    topicId: args.projectId ?? args.topicId,
+    fromNodeType: "evidence",
+    toNodeType: "belief",
+    fromLayer: "L2",
+    toLayer: "L3",
+    metadata: {
+      relation: args.relation,
+      confidence,
+      impactScore: args.weight,
+      invariant: "evidence.belief_impact_required"
+    }
+  });
+  return existing?.globalId ?? edgeGlobalId;
+}
 var create = mutation({
   args: {
     ...optionalEvidenceScopeArgs,
@@ -793,11 +867,12 @@ var create = mutation({
     informationAsymmetry: v.optional(v.string()),
     sourceDescription: v.optional(v.string()),
     metadata: v.optional(v.any()),
-    // Optional linking to beliefs
-    linkedBeliefNodeId: v.optional(v.id("epistemicNodes")),
+    // Required belief impact link.
+    linkedBeliefNodeId: v.id("epistemicNodes"),
     evidenceRelation: v.optional(
       v.union(v.literal("supports"), v.literal("contradicts"))
     ),
+    weight: v.number(),
     confidence: v.optional(v.number())
   },
   returns: permissiveReturn,
@@ -819,6 +894,16 @@ var create = mutation({
     const contentHash = generateContentHash(args.text);
     const kind = normalizeKind(args.kind);
     const sourceType = normalizeSourceType(args.sourceType);
+    const weight = assertSignedImpactScore(args.weight, "Evidence creation");
+    const evidenceRelation = normalizeEvidenceRelation(
+      args.evidenceRelation,
+      weight,
+      "Evidence creation"
+    );
+    const linkedBeliefNode = await ctx.db.get(args.linkedBeliefNodeId);
+    if (!linkedBeliefNode || linkedBeliefNode.nodeType !== "belief") {
+      throw new Error("Evidence creation requires a linked belief node");
+    }
     const additionalMetadata = args.metadata && typeof args.metadata === "object" ? args.metadata : {};
     const nodeId = await ctx.db.insert("epistemicNodes", {
       globalId,
@@ -846,8 +931,10 @@ var create = mutation({
         sourceQuestionId: args.sourceQuestionId,
         rationale: args.rationale,
         linkedBeliefNodeId: args.linkedBeliefNodeId,
-        evidenceRelation: args.evidenceRelation,
-        confidence: args.confidence,
+        evidenceRelation,
+        confidence: Math.abs(weight),
+        weight,
+        impactScore: weight,
         methodology: args.methodology,
         informationAsymmetry: args.informationAsymmetry,
         sourceDescription: args.sourceDescription,
@@ -867,29 +954,18 @@ var create = mutation({
       nodeType: "evidence",
       text: args.text
     });
-    if (args.linkedBeliefNodeId && args.evidenceRelation) {
-      const beliefNode = await ctx.db.get(args.linkedBeliefNodeId);
-      if (beliefNode) {
-        const weight = args.evidenceRelation === "supports" ? 1 : -1;
-        await ctx.scheduler.runAfter(5e3, internal.neo4jEdgeAPI.createEdge, {
-          globalId: crypto.randomUUID(),
-          fromGlobalId: globalId,
-          toGlobalId: beliefNode.globalId,
-          edgeType: "informs",
-          weight: weight * (args.confidence || 0.7),
-          createdBy: args.userId,
-          topicId: scope.projectId ? String(scope.projectId) : void 0,
-          fromNodeType: "evidence",
-          toNodeType: "belief",
-          fromLayer: "L2",
-          toLayer: "L3",
-          metadata: {
-            relation: args.evidenceRelation,
-            confidence: args.confidence
-          }
-        });
-      }
-    }
+    await createEvidenceBeliefEdge(ctx, {
+      evidenceNodeId: nodeId,
+      evidenceGlobalId: globalId,
+      beliefNodeId: args.linkedBeliefNodeId,
+      beliefGlobalId: linkedBeliefNode.globalId,
+      relation: evidenceRelation,
+      weight,
+      userId: args.userId,
+      topicId: scope.topicId ? String(scope.topicId) : void 0,
+      projectId: scope.projectId ? String(scope.projectId) : void 0,
+      rationale: args.rationale
+    });
     await ctx.db.insert("epistemicAudit", {
       entityType: "evidence",
       entityId: nodeId,
@@ -904,7 +980,8 @@ var create = mutation({
         kind,
         sourceType,
         linkedBeliefNodeId: args.linkedBeliefNodeId,
-        evidenceRelation: args.evidenceRelation
+        evidenceRelation,
+        weight
       }
     });
     if (scope.projectId || scope.topicId) {
@@ -947,6 +1024,7 @@ var createAndLink = mutation({
     userId: v.string(),
     beliefNodeId: v.id("epistemicNodes"),
     relation: v.union(v.literal("supports"), v.literal("contradicts")),
+    weight: v.number(),
     confidence: v.optional(v.number())
   },
   returns: permissiveReturn,
@@ -961,7 +1039,17 @@ var createAndLink = mutation({
     const contentHash = generateContentHash(args.text);
     const kind = normalizeKind(args.kind);
     const sourceType = normalizeSourceType(args.sourceType);
-    const confidence = args.confidence ?? 0.7;
+    const weight = assertSignedImpactScore(args.weight, "Evidence createAndLink");
+    const relation = normalizeEvidenceRelation(
+      args.relation,
+      weight,
+      "Evidence createAndLink"
+    );
+    const confidence = Math.abs(weight);
+    const beliefNode = await ctx.db.get(args.beliefNodeId);
+    if (!beliefNode || beliefNode.nodeType !== "belief") {
+      throw new Error("Belief node not found for edge creation");
+    }
     const nodeId = await ctx.db.insert("epistemicNodes", {
       globalId,
       topicId: scope.topicId,
@@ -981,36 +1069,26 @@ var createAndLink = mutation({
         kind,
         tags: args.tags || [],
         linkedBeliefNodeId: args.beliefNodeId,
-        evidenceRelation: args.relation,
-        confidence
+        evidenceRelation: relation,
+        confidence,
+        weight,
+        impactScore: weight
       }
     });
     await ctx.scheduler.runAfter(0, internal.neo4jSync.syncNodeToNeo4j, {
       nodeId,
       operation: "upsert"
     });
-    const beliefNode = await ctx.db.get(args.beliefNodeId);
-    if (!beliefNode) {
-      throw new Error("Belief node not found for edge creation");
-    }
-    const weight = args.relation === "supports" ? confidence : -confidence;
-    const edgeGlobalId = crypto.randomUUID();
-    await ctx.scheduler.runAfter(5e3, internal.neo4jEdgeAPI.createEdge, {
-      globalId: edgeGlobalId,
-      fromGlobalId: globalId,
-      toGlobalId: beliefNode.globalId,
-      edgeType: "informs",
+    const edgeGlobalId = await createEvidenceBeliefEdge(ctx, {
+      evidenceNodeId: nodeId,
+      evidenceGlobalId: globalId,
+      beliefNodeId: args.beliefNodeId,
+      beliefGlobalId: beliefNode.globalId,
+      relation,
       weight,
-      createdBy: args.userId,
-      topicId: scope.projectId,
-      fromNodeType: "evidence",
-      toNodeType: "belief",
-      fromLayer: "L2",
-      toLayer: "L3",
-      metadata: {
-        relation: args.relation,
-        confidence
-      }
+      userId: args.userId,
+      topicId: scope.topicId ? String(scope.topicId) : void 0,
+      projectId: scope.projectId ? String(scope.projectId) : void 0
     });
     await markProjectGraphDirty(ctx, scope.projectId, String(scope.topicId));
     return { nodeId, edgeGlobalId };
@@ -1071,8 +1149,9 @@ var internalCreate = internalMutation({
     sourceQuestionId: v.optional(v.string()),
     userId: v.string(),
     rationale: v.string(),
-    linkedBeliefNodeId: v.optional(v.id("epistemicNodes")),
+    linkedBeliefNodeId: v.id("epistemicNodes"),
     evidenceRelation: v.optional(v.string()),
+    weight: v.number(),
     confidence: v.optional(v.number()),
     metadata: v.optional(v.any()),
     runtimeToolName: v.optional(v.string()),
@@ -1107,6 +1186,16 @@ var internalCreate = internalMutation({
     const contentHash = generateContentHash(args.text);
     const kind = normalizeKind(args.kind);
     const sourceType = normalizeSourceType(args.sourceType);
+    const weight = assertSignedImpactScore(args.weight, "Internal evidence creation");
+    const evidenceRelation = normalizeEvidenceRelation(
+      args.evidenceRelation,
+      weight,
+      "Internal evidence creation"
+    );
+    const linkedBeliefNode = await ctx.db.get(args.linkedBeliefNodeId);
+    if (!linkedBeliefNode || linkedBeliefNode.nodeType !== "belief") {
+      throw new Error("Internal evidence creation requires a linked belief node");
+    }
     const additionalMetadata = args.metadata && typeof args.metadata === "object" ? args.metadata : {};
     const nodeId = await ctx.db.insert("epistemicNodes", {
       globalId,
@@ -1134,8 +1223,10 @@ var internalCreate = internalMutation({
         sourceQuestionId: args.sourceQuestionId,
         rationale: args.rationale,
         linkedBeliefNodeId: args.linkedBeliefNodeId,
-        evidenceRelation: args.evidenceRelation,
-        confidence: args.confidence,
+        evidenceRelation,
+        confidence: Math.abs(weight),
+        weight,
+        impactScore: weight,
         ...additionalMetadata
       }
     });
@@ -1155,8 +1246,9 @@ var internalCreate = internalMutation({
         externalSourceType: args.externalSourceType,
         sourceUrl: args.sourceUrl,
         linkedBeliefNodeId: args.linkedBeliefNodeId,
-        evidenceRelation: args.evidenceRelation,
-        confidence: args.confidence
+        evidenceRelation,
+        confidence: Math.abs(weight),
+        weight
       },
       triggeringAction: "epistemicEvidence.internalCreate"
     });
@@ -1164,30 +1256,18 @@ var internalCreate = internalMutation({
       nodeId,
       operation: "upsert"
     });
-    if (args.linkedBeliefNodeId && args.evidenceRelation) {
-      const beliefNode = await ctx.db.get(args.linkedBeliefNodeId);
-      if (beliefNode) {
-        const confidence = args.confidence ?? 0.7;
-        const weight = args.evidenceRelation === "supports" ? confidence : -confidence;
-        await ctx.scheduler.runAfter(5e3, internal.neo4jEdgeAPI.createEdge, {
-          globalId: crypto.randomUUID(),
-          fromGlobalId: globalId,
-          toGlobalId: beliefNode.globalId,
-          edgeType: "informs",
-          weight,
-          createdBy: args.userId,
-          topicId: scope.projectId ? String(scope.projectId) : void 0,
-          fromNodeType: "evidence",
-          toNodeType: "belief",
-          fromLayer: "L2",
-          toLayer: "L3",
-          metadata: {
-            relation: args.evidenceRelation,
-            confidence
-          }
-        });
-      }
-    }
+    await createEvidenceBeliefEdge(ctx, {
+      evidenceNodeId: nodeId,
+      evidenceGlobalId: globalId,
+      beliefNodeId: args.linkedBeliefNodeId,
+      beliefGlobalId: linkedBeliefNode.globalId,
+      relation: evidenceRelation,
+      weight,
+      userId: args.userId,
+      topicId: scope.topicId ? String(scope.topicId) : void 0,
+      projectId: scope.projectId ? String(scope.projectId) : void 0,
+      rationale: args.rationale
+    });
     if (scope.projectId || scope.topicId) {
       await ctx.scheduler.runAfter(
         0,