@lucern/graph-primitives 1.0.22 → 1.0.24

package/dist/epistemicEvidenceMutations.js

@@ -2,9 +2,10 @@ 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 { generateGlobalId, assertUuidV7Identity, assertStorageEdgeVocabulary, assertUuidShapedEdgeEndpoint } from '@lucern/contracts/ids';
 import { isNodeType, getLayerForNodeType } from '@lucern/contracts/schema-helpers/spine/tables/epistemicNodes';
 import '@lucern/access-control/audience';
+import { assertEdgePolicyAllowed, edgePolicyManifest } from '@lucern/contracts';
 
 // src/epistemicEvidenceMutations.ts
 var api = anyApi;
@@ -54,6 +55,35 @@ async function scheduleEmbeddingGeneration(args) {
   }
 }
 var LEGACY_SCOPE_FIELD = "graphScopeProjectId";
+async function resolveTopicNodeScopeOrNull(ctx, ref) {
+  if (!ctx?.db || typeof ctx.db.query !== "function") {
+    return null;
+  }
+  let node = null;
+  try {
+    const byGlobalId = await ctx.db.query("epistemicNodes").withIndex("by_globalId", (q) => q.eq("globalId", ref)).first();
+    if (byGlobalId && byGlobalId.nodeType === "topic") {
+      node = byGlobalId;
+    }
+  } catch (error) {
+    debugGraphPrimitiveFallback(
+      "[topicScope] topic-node scope lookup by globalId failed",
+      { error, ref }
+    );
+  }
+  if (!node) {
+    return null;
+  }
+  const scopeKey = normalizeScopeValue(node.topicId) ?? normalizeScopeValue(node.globalId);
+  if (!scopeKey) {
+    return null;
+  }
+  return {
+    topicId: scopeKey,
+    projectId: asMappedProjectId(node),
+    source: "topic_node"
+  };
+}
 function asMappedProjectId(topic) {
   if (!topic) {
     return;
@@ -194,6 +224,13 @@ async function resolveTopicProjectScope(ctx, args) {
       ) ?? null;
     }
     if (!topic) {
+      const nodeScope = await resolveTopicNodeScopeOrNull(
+        ctx,
+        String(args.topicId)
+      );
+      if (nodeScope) {
+        return nodeScope;
+      }
       throw new Error(`Topic not found: ${String(args.topicId)}`);
     }
     const inherited = await resolveInheritedWorkspaceScope(ctx, topic);
@@ -264,6 +301,16 @@ async function resolveTopicProjectScope(ctx, args) {
         source: "project_mapped_topic"
       };
     }
+    const nodeScope = await resolveTopicNodeScopeOrNull(
+      ctx,
+      String(args.projectId)
+    );
+    if (nodeScope) {
+      return {
+        ...nodeScope,
+        projectId: nodeScope.projectId ?? String(args.projectId)
+      };
+    }
     throw new Error(
       `Legacy project scope ${String(args.projectId)} has no mapped topic.`
     );
@@ -482,6 +529,9 @@ function materializeTopicProjectOverlay(topic, idMode = "legacy") {
     type: mapProjectType(topic, metadata),
     description: readNonEmptyString(topic.description),
     ownerId: readNonEmptyString(metadata.ownerId) || readNonEmptyString(topic.createdBy) || "system",
+    // FR.7 creator-grant: surface the principal-shaped owner field (column-first,
+    // metadata fallback for legacy rows that recorded it in metadata).
+    ownerPrincipalId: readNonEmptyString(topic.ownerPrincipalId) || readNonEmptyString(metadata.ownerPrincipalId),
     sharedWith: readStringArray(metadata.sharedWith),
     visibility,
     tenantId: readNonEmptyString(topic.tenantId) || readNonEmptyString(metadata.tenantId),
@@ -760,6 +810,52 @@ async function resolveEvidenceScopeOrNull(ctx, args) {
     return null;
   }
 }
+async function insertEpistemicNode(ctx, doc) {
+  assertUuidV7Identity("epistemicNodes", doc.globalId);
+  return ctx.db.insert("epistemicNodes", doc);
+}
+async function assertExistingNodeEndpoint(ctx, endpointRole, endpoint) {
+  assertUuidShapedEdgeEndpoint(endpointRole, endpoint);
+  const node = await ctx.db.query("epistemicNodes").withIndex("by_globalId", (q) => q.eq("globalId", endpoint)).first();
+  if (!node) {
+    throw new Error(
+      `edge_endpoint_not_canonical: epistemicEdges insert requires ${endpointRole} to be the globalId of an existing epistemicNodes row, received ${endpoint} (no node with that globalId)`
+    );
+  }
+}
+async function insertEpistemicEdge(ctx, doc) {
+  assertUuidV7Identity("epistemicEdges", doc.globalId);
+  assertStorageEdgeVocabulary(doc.edgeType);
+  if (!doc.fromNodeId || typeof doc.fromNodeId !== "string") {
+    throw new Error(
+      "edge_endpoint_missing: epistemicEdges insert requires a non-empty fromNodeId"
+    );
+  }
+  if (!doc.toNodeId || typeof doc.toNodeId !== "string") {
+    throw new Error(
+      "edge_endpoint_missing: epistemicEdges insert requires a non-empty toNodeId"
+    );
+  }
+  await assertExistingNodeEndpoint(ctx, "fromNodeId", doc.fromNodeId);
+  await assertExistingNodeEndpoint(ctx, "toNodeId", doc.toNodeId);
+  if (doc.fromNodeType && doc.toNodeType && doc.edgeType !== "extracted_from") {
+    assertEdgePolicyAllowed(
+      edgePolicyManifest,
+      doc.edgeType,
+      {
+        kind: "epistemic_node",
+        nodeId: doc.fromNodeId,
+        nodeType: doc.fromNodeType
+      },
+      {
+        kind: "epistemic_node",
+        nodeId: doc.toNodeId,
+        nodeType: doc.toNodeType
+      }
+    );
+  }
+  return ctx.db.insert("epistemicEdges", doc);
+}
 
 // src/epistemicEvidenceMutations.ts
 function assertSignedImpactScore(value, context) {
@@ -781,17 +877,17 @@ function normalizeEvidenceRelation(relation, weight, context) {
   return weight < 0 ? "contradicts" : "supports";
 }
 async function createEvidenceBeliefEdge(ctx, args) {
-  const edgeGlobalId = crypto.randomUUID();
+  const edgeGlobalId = generateGlobalId();
   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)
+    (q) => q.eq("fromNodeId", args.evidenceGlobalId).eq("toNodeId", args.beliefGlobalId)
   ).collect();
   const existing = existingEdges.find((edge) => edge.edgeType === "informs");
   const edgeDoc = {
     globalId: edgeGlobalId,
-    fromNodeId: args.evidenceNodeId,
-    toNodeId: args.beliefNodeId,
+    fromNodeId: args.evidenceGlobalId,
+    toNodeId: args.beliefGlobalId,
     sourceGlobalId: args.evidenceGlobalId,
     targetGlobalId: args.beliefGlobalId,
     edgeType: "informs",
@@ -823,7 +919,7 @@ async function createEvidenceBeliefEdge(ctx, args) {
       createdAt: existing.createdAt ?? edgeDoc.createdAt
     });
   } else {
-    await ctx.db.insert("epistemicEdges", edgeDoc);
+    await insertEpistemicEdge(ctx, edgeDoc);
   }
   await ctx.scheduler.runAfter(5e3, internal.neo4jEdgeAPI.createEdge, {
     globalId: existing?.globalId ?? edgeGlobalId,
@@ -862,10 +958,23 @@ var create = mutation({
     sourceQuestionId: v.optional(v.string()),
     userId: v.string(),
     rationale: v.string(),
-    // Classification fields (from AI tools)
+    // RC.1 taxonomy fields — top-level projection (mirroring kernel evidenceCreate.ts)
+    sourceRef: v.optional(v.string()),
+    sourceQuality: v.optional(
+      v.union(
+        v.literal("primary"),
+        v.literal("analyzed"),
+        v.literal("secondary"),
+        v.literal("tertiary"),
+        v.literal("unknown")
+      )
+    ),
     methodology: v.optional(v.string()),
     informationAsymmetry: v.optional(v.string()),
     sourceDescription: v.optional(v.string()),
+    // signedImpact is derived from weight; accepted as an explicit override for
+    // callers that already have the signed value (kernel parity).
+    signedImpact: v.optional(v.number()),
     metadata: v.optional(v.any()),
     // Required belief impact link.
     linkedBeliefNodeId: v.id("epistemicNodes"),
@@ -895,6 +1004,7 @@ var create = mutation({
     const kind = normalizeKind(args.kind);
     const sourceType = normalizeSourceType(args.sourceType);
     const weight = assertSignedImpactScore(args.weight, "Evidence creation");
+    const signedImpact = args.signedImpact !== void 0 ? assertSignedImpactScore(args.signedImpact, "Evidence creation signedImpact") : weight;
     const evidenceRelation = normalizeEvidenceRelation(
       args.evidenceRelation,
       weight,
@@ -905,7 +1015,7 @@ var create = mutation({
       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", {
+    const nodeId = await insertEpistemicNode(ctx, {
       globalId,
       topicId: scope.topicId,
       projectId: scope.projectId,
@@ -920,6 +1030,15 @@ var create = mutation({
       status: "active",
       epistemicLayer: "L2",
       sourceType,
+      // RC.1 taxonomy fields — top-level projection
+      evidenceRelation,
+      signedImpact,
+      targetBeliefId: String(args.linkedBeliefNodeId),
+      ...typeof args.sourceRef === "string" && args.sourceRef.trim().length > 0 ? { sourceRef: args.sourceRef.trim() } : {},
+      ...typeof args.sourceQuality === "string" && args.sourceQuality.length > 0 ? { sourceQuality: args.sourceQuality } : {},
+      ...typeof args.methodology === "string" && args.methodology.length > 0 ? { methodology: args.methodology } : {},
+      ...typeof args.informationAsymmetry === "string" && args.informationAsymmetry.length > 0 ? { informationAsymmetry: args.informationAsymmetry } : {},
+      ...typeof args.sourceDescription === "string" && args.sourceDescription.trim().length > 0 ? { sourceDescription: args.sourceDescription.trim() } : {},
       createdAt: now,
       updatedAt: now,
       createdBy: args.userId,
@@ -955,7 +1074,6 @@ var create = mutation({
       text: args.text
     });
     await createEvidenceBeliefEdge(ctx, {
-      evidenceNodeId: nodeId,
       evidenceGlobalId: globalId,
       beliefNodeId: args.linkedBeliefNodeId,
       beliefGlobalId: linkedBeliefNode.globalId,
@@ -1025,7 +1143,22 @@ var createAndLink = mutation({
     beliefNodeId: v.id("epistemicNodes"),
     relation: v.union(v.literal("supports"), v.literal("contradicts")),
     weight: v.number(),
-    confidence: v.optional(v.number())
+    confidence: v.optional(v.number()),
+    // RC.1 taxonomy fields — top-level projection (mirroring kernel evidenceCreate.ts)
+    sourceRef: v.optional(v.string()),
+    sourceQuality: v.optional(
+      v.union(
+        v.literal("primary"),
+        v.literal("analyzed"),
+        v.literal("secondary"),
+        v.literal("tertiary"),
+        v.literal("unknown")
+      )
+    ),
+    methodology: v.optional(v.string()),
+    informationAsymmetry: v.optional(v.string()),
+    sourceDescription: v.optional(v.string()),
+    signedImpact: v.optional(v.number())
   },
   returns: permissiveReturn,
   handler: async (ctx, args) => {
@@ -1040,6 +1173,7 @@ var createAndLink = mutation({
     const kind = normalizeKind(args.kind);
     const sourceType = normalizeSourceType(args.sourceType);
     const weight = assertSignedImpactScore(args.weight, "Evidence createAndLink");
+    const signedImpact = args.signedImpact !== void 0 ? assertSignedImpactScore(args.signedImpact, "Evidence createAndLink signedImpact") : weight;
     const relation = normalizeEvidenceRelation(
       args.relation,
       weight,
@@ -1050,7 +1184,7 @@ var createAndLink = mutation({
     if (!beliefNode || beliefNode.nodeType !== "belief") {
       throw new Error("Belief node not found for edge creation");
     }
-    const nodeId = await ctx.db.insert("epistemicNodes", {
+    const nodeId = await insertEpistemicNode(ctx, {
       globalId,
       topicId: scope.topicId,
       projectId: scope.projectId,
@@ -1062,6 +1196,15 @@ var createAndLink = mutation({
       status: "active",
       epistemicLayer: "L2",
       sourceType,
+      // RC.1 taxonomy fields — top-level projection
+      evidenceRelation: relation,
+      signedImpact,
+      targetBeliefId: String(args.beliefNodeId),
+      ...typeof args.sourceRef === "string" && args.sourceRef.trim().length > 0 ? { sourceRef: args.sourceRef.trim() } : {},
+      ...typeof args.sourceQuality === "string" && args.sourceQuality.length > 0 ? { sourceQuality: args.sourceQuality } : {},
+      ...typeof args.methodology === "string" && args.methodology.length > 0 ? { methodology: args.methodology } : {},
+      ...typeof args.informationAsymmetry === "string" && args.informationAsymmetry.length > 0 ? { informationAsymmetry: args.informationAsymmetry } : {},
+      ...typeof args.sourceDescription === "string" && args.sourceDescription.trim().length > 0 ? { sourceDescription: args.sourceDescription.trim() } : {},
       createdAt: now,
       updatedAt: now,
       createdBy: args.userId,
@@ -1080,7 +1223,6 @@ var createAndLink = mutation({
       operation: "upsert"
     });
     const edgeGlobalId = await createEvidenceBeliefEdge(ctx, {
-      evidenceNodeId: nodeId,
       evidenceGlobalId: globalId,
       beliefNodeId: args.beliefNodeId,
       beliefGlobalId: beliefNode.globalId,
@@ -1153,6 +1295,21 @@ var internalCreate = internalMutation({
     evidenceRelation: v.optional(v.string()),
     weight: v.number(),
     confidence: v.optional(v.number()),
+    // RC.1 taxonomy fields — top-level projection (mirroring kernel evidenceCreate.ts)
+    sourceRef: v.optional(v.string()),
+    sourceQuality: v.optional(
+      v.union(
+        v.literal("primary"),
+        v.literal("analyzed"),
+        v.literal("secondary"),
+        v.literal("tertiary"),
+        v.literal("unknown")
+      )
+    ),
+    methodology: v.optional(v.string()),
+    informationAsymmetry: v.optional(v.string()),
+    sourceDescription: v.optional(v.string()),
+    signedImpact: v.optional(v.number()),
     metadata: v.optional(v.any()),
     runtimeToolName: v.optional(v.string()),
     runtimePackKey: v.optional(v.string()),
@@ -1187,6 +1344,7 @@ var internalCreate = internalMutation({
     const kind = normalizeKind(args.kind);
     const sourceType = normalizeSourceType(args.sourceType);
     const weight = assertSignedImpactScore(args.weight, "Internal evidence creation");
+    const signedImpact = args.signedImpact !== void 0 ? assertSignedImpactScore(args.signedImpact, "Internal evidence creation signedImpact") : weight;
     const evidenceRelation = normalizeEvidenceRelation(
       args.evidenceRelation,
       weight,
@@ -1197,7 +1355,7 @@ var internalCreate = internalMutation({
       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", {
+    const nodeId = await insertEpistemicNode(ctx, {
       globalId,
       topicId: scope.topicId,
       projectId: scope.projectId,
@@ -1212,6 +1370,15 @@ var internalCreate = internalMutation({
       status: "active",
       epistemicLayer: "L2",
       sourceType,
+      // RC.1 taxonomy fields — top-level projection
+      evidenceRelation,
+      signedImpact,
+      targetBeliefId: String(args.linkedBeliefNodeId),
+      ...typeof args.sourceRef === "string" && args.sourceRef.trim().length > 0 ? { sourceRef: args.sourceRef.trim() } : {},
+      ...typeof args.sourceQuality === "string" && args.sourceQuality.length > 0 ? { sourceQuality: args.sourceQuality } : {},
+      ...typeof args.methodology === "string" && args.methodology.length > 0 ? { methodology: args.methodology } : {},
+      ...typeof args.informationAsymmetry === "string" && args.informationAsymmetry.length > 0 ? { informationAsymmetry: args.informationAsymmetry } : {},
+      ...typeof args.sourceDescription === "string" && args.sourceDescription.trim().length > 0 ? { sourceDescription: args.sourceDescription.trim() } : {},
       createdAt: now,
       updatedAt: now,
       createdBy: args.userId,
@@ -1257,7 +1424,6 @@ var internalCreate = internalMutation({
       operation: "upsert"
     });
     await createEvidenceBeliefEdge(ctx, {
-      evidenceNodeId: nodeId,
       evidenceGlobalId: globalId,
       beliefNodeId: args.linkedBeliefNodeId,
       beliefGlobalId: linkedBeliefNode.globalId,