@lucern/graph-primitives 1.0.29 → 1.0.31

package/dist/epistemicBeliefs.links.js

@@ -1,82 +1,25 @@
-import { v } from 'convex/values';
 import { requireScopeWriteAccess } from '@lucern/access-control/access';
 import { permissiveReturn } from '@lucern/contracts/schema-helpers/validators';
-import { componentsGeneric, anyApi, mutationGeneric, queryGeneric } from 'convex/server';
-import { generateGlobalId, assertUuidV7Identity, assertStorageEdgeVocabulary, assertUuidShapedEdgeEndpoint } from '@lucern/contracts/ids';
-import { throwStructuredMutationError } from '@lucern/access-control/structuredMutationError';
-import { normalizeTupleContradictionPolicy } from '@lucern/confidence';
+import { v } from 'convex/values';
+import { unsafeConvexAnyApi } from '@lucern/contracts/convex/unsafeAnyApi';
+import { componentsGeneric, mutationGeneric, queryGeneric } from 'convex/server';
 import '@lucern/access-control/audience';
 import { getCurrentUserId } from '@lucern/access-control/auth';
+import { throwStructuredMutationError } from '@lucern/access-control/structuredMutationError';
+import { normalizeTupleContradictionPolicy } from '@lucern/confidence';
 import { assertEdgePolicyAllowed, edgePolicyManifest } from '@lucern/contracts';
+import { generateGlobalId, assertUuidV7Identity, assertStorageEdgeVocabulary, assertUuidShapedEdgeEndpoint } from '@lucern/contracts/ids';
 
 // src/epistemicBeliefs.links.ts
-var api = anyApi;
+var unsafeApi = unsafeConvexAnyApi(
+  "graph-primitives top-level module bundle lacks a committed Convex _generated/api surface"
+);
+var api = unsafeApi;
 componentsGeneric();
-var internal = anyApi;
+var internal = unsafeApi;
 var mutation = mutationGeneric;
 var query = queryGeneric;
 
-// src/logicalRoleInference.ts
-var PILLAR_IMPORTANCE = {
-  market: 1,
-  competition: 2,
-  product: 3,
-  team: 4,
-  financials: 5,
-  timing: 6,
-  other: 10
-};
-async function computeLogicalRole(ctx, evidenceId, beliefId) {
-  const belief = await ctx.db.get(beliefId);
-  if (!belief || belief.nodeType !== "belief") {
-    return "contributory";
-  }
-  const beliefMetadata = belief.metadata;
-  const pillar = beliefMetadata?.pillar || "other";
-  const pillarRank = PILLAR_IMPORTANCE[pillar] ?? 10;
-  const isSynthesized = await checkIfSynthesizedHypothesis(ctx, beliefId);
-  const testingQuestions = await getTestingQuestionsForBelief(ctx, beliefId);
-  const answeredQuestions = await getQuestionsAnsweredByEvidence(
-    ctx,
-    evidenceId
-  );
-  const directlyTests = testingQuestions.filter(
-    (questionId) => answeredQuestions.includes(questionId)
-  );
-  if (directlyTests.length === 0) {
-    return "contributory";
-  }
-  if (isSynthesized && pillarRank <= 2) {
-    return directlyTests.length > 1 ? "necessary_sufficient" : "necessary";
-  }
-  if (isSynthesized) {
-    return "necessary";
-  }
-  return directlyTests.length > 1 ? "necessary" : "contributory";
-}
-async function checkIfSynthesizedHypothesis(ctx, beliefId) {
-  const belief = await ctx.db.get(beliefId);
-  if (!belief) {
-    return false;
-  }
-  const metadata = belief.metadata;
-  return metadata?.isSynthesized === true || metadata?.beliefStatus === "hypothesis";
-}
-async function getTestingQuestionsForBelief(ctx, beliefId) {
-  const testEdges = await ctx.db.query("epistemicEdges").withIndex(
-    "by_to_type",
-    (q) => q.eq("toNodeId", beliefId).eq("edgeType", "tests")
-  ).collect();
-  return testEdges.map((edge) => edge.fromNodeId).filter((id) => id !== void 0);
-}
-async function getQuestionsAnsweredByEvidence(ctx, evidenceId) {
-  const answerEdges = await ctx.db.query("epistemicEdges").withIndex(
-    "by_from_type",
-    (q) => q.eq("fromNodeId", evidenceId).eq("edgeType", "derived_from")
-  ).collect();
-  return answerEdges.map((edge) => edge.toNodeId).filter((id) => id !== void 0);
-}
-
 // src/debug.ts
 function isGraphPrimitiveDebugEnabled() {
   const env = globalThis.process?.env;
@@ -122,13 +65,15 @@ function asMappedProjectId(topic) {
   if (!topic) {
     return;
   }
-  const directLegacyProjectId = normalizeScopeValue(topic[LEGACY_SCOPE_FIELD]);
+  const directLegacyProjectId = normalizeScopeValue(
+    topic[LEGACY_SCOPE_FIELD]
+  );
   if (directLegacyProjectId) {
     return directLegacyProjectId;
   }
   const metadata = topic.metadata || {};
   const candidate = metadata[LEGACY_SCOPE_FIELD] || metadata.legacyProjectId || metadata.projectId || metadata.scopeProjectId;
-  return candidate ? candidate : void 0;
+  return typeof candidate === "string" ? normalizeScopeValue(candidate) : void 0;
 }
 function normalizeScopeValue(value) {
   if (typeof value !== "string") {
@@ -153,8 +98,9 @@ function pickPrimaryTopic(candidates) {
   })[0];
 }
 async function findTopicsByScopeAlias(ctx, scopeId) {
+  const query2 = ctx.db.query("topics");
   try {
-    return await ctx.db.query("topics").withIndex(
+    return await query2.withIndex(
       "by_graph_scope_project",
       (q) => q.eq(LEGACY_SCOPE_FIELD, scopeId)
     ).collect();
@@ -166,7 +112,7 @@ async function findTopicsByScopeAlias(ctx, scopeId) {
         scopeId
       }
     );
-    const topics = await ctx.db.query("topics").collect();
+    const topics = await query2.collect();
     return topics.filter((topic) => {
       const normalizedGlobalId = normalizeScopeValue(topic.globalId);
       const mappedProjectId = asMappedProjectId(topic);
@@ -222,143 +168,119 @@ async function resolveInheritedWorkspaceScope(ctx, topic) {
   let current = topic;
   for (let i = 0; i < MAX_DEPTH && current?.parentTopicId; i++) {
     current = await ctx.db.get(current.parentTopicId);
-    if (!current) break;
+    if (!current) {
+      break;
+    }
     if (!tenantId) {
       tenantId = normalizeScopeValue(current.tenantId);
     }
     if (!workspaceId) {
       workspaceId = normalizeScopeValue(current.workspaceId);
     }
-    if (tenantId && workspaceId) break;
+    if (tenantId && workspaceId) {
+      break;
+    }
   }
   return { tenantId, workspaceId };
 }
 async function resolveTopicProjectScope(ctx, args) {
   if (args.topicId) {
-    let topic = null;
-    try {
-      topic = await ctx.db.get(
-        args.topicId
-      );
-    } catch (error) {
-      debugGraphPrimitiveFallback(
-        "[topicScope] Failed to load topic by direct id",
-        {
-          error,
-          topicId: args.topicId
-        }
-      );
-    }
-    if (!topic) {
-      topic = await tryResolveHostTopicById(ctx, String(args.topicId));
-    }
-    if (!topic) {
-      topic = pickPrimaryTopic(
-        await findTopicsByScopeAlias(ctx, String(args.topicId))
-      ) ?? 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);
-    const mapped = asMappedProjectId(topic);
-    if (mapped) {
-      return {
-        topicId: topic._id,
-        projectId: mapped,
-        tenantId: inherited.tenantId,
-        workspaceId: inherited.workspaceId,
-        source: "topic"
-      };
-    }
-    return {
-      topicId: topic._id,
-      tenantId: inherited.tenantId,
-      workspaceId: inherited.workspaceId,
-      source: "topic"
-    };
+    return await resolveScopeFromTopicId(ctx, args.topicId);
   }
   if (args.projectId) {
-    let directTopic = null;
-    try {
-      directTopic = await ctx.db.get(
-        args.projectId
-      );
-    } catch (error) {
-      debugGraphPrimitiveFallback(
-        "[topicScope] Failed to load direct project topic",
-        {
-          error,
-          projectId: args.projectId
-        }
-      );
-    }
-    if (directTopic) {
-      const inherited = await resolveInheritedWorkspaceScope(ctx, directTopic);
-      const mapped = asMappedProjectId(directTopic);
-      return {
-        topicId: directTopic._id,
-        projectId: mapped ?? args.projectId,
-        tenantId: inherited.tenantId,
-        workspaceId: inherited.workspaceId,
-        source: "topic_inferred"
-      };
-    }
-    directTopic = await tryResolveHostTopicByLegacyScope(ctx, args.projectId);
-    if (directTopic) {
-      const inherited = await resolveInheritedWorkspaceScope(ctx, directTopic);
-      const mapped = asMappedProjectId(directTopic);
-      return {
-        topicId: directTopic._id,
-        projectId: mapped ?? args.projectId,
-        tenantId: inherited.tenantId,
-        workspaceId: inherited.workspaceId,
-        source: "topic_inferred"
-      };
-    }
-    const topics = await findTopicsByScopeAlias(ctx, args.projectId);
-    const primary = pickPrimaryTopic(topics);
-    if (primary) {
-      const inherited = await resolveInheritedWorkspaceScope(ctx, primary);
-      return {
-        topicId: primary._id,
-        projectId: args.projectId,
-        tenantId: inherited.tenantId,
-        workspaceId: inherited.workspaceId,
-        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.`
-    );
+    return await resolveScopeFromLegacyProjectId(ctx, args.projectId);
   }
   throw new Error(
     "Missing scope: provide topicId (preferred) or legacy projectId alias."
   );
 }
+async function resolveScopeFromTopicId(ctx, topicId) {
+  const topic = await resolveTopicDocFromTopicId(ctx, topicId);
+  if (topic) {
+    return await buildTopicScope(ctx, topic, "topic");
+  }
+  const nodeScope = await resolveTopicNodeScopeOrNull(ctx, String(topicId));
+  if (nodeScope) {
+    return nodeScope;
+  }
+  throw new Error(`Topic not found: ${String(topicId)}`);
+}
+async function resolveTopicDocFromTopicId(ctx, topicId) {
+  const direct = await tryReadTopicDoc(ctx, topicId, {
+    failureLog: "[topicScope] Failed to load topic by direct id",
+    idLogKey: "topicId"
+  });
+  if (direct) {
+    return direct;
+  }
+  const hostTopic = await tryResolveHostTopicById(ctx, String(topicId));
+  if (hostTopic) {
+    return hostTopic;
+  }
+  return pickPrimaryTopic(await findTopicsByScopeAlias(ctx, String(topicId))) ?? null;
+}
+async function resolveScopeFromLegacyProjectId(ctx, legacyProjectId) {
+  const directTopic = await resolveDirectLegacyProjectTopic(
+    ctx,
+    legacyProjectId
+  );
+  if (directTopic) {
+    return await buildTopicScope(ctx, directTopic, "topic_inferred", {
+      fallbackProjectId: legacyProjectId
+    });
+  }
+  const primary = pickPrimaryTopic(
+    await findTopicsByScopeAlias(ctx, legacyProjectId)
+  );
+  if (primary) {
+    return await buildTopicScope(ctx, primary, "project_mapped_topic", {
+      fallbackProjectId: legacyProjectId
+    });
+  }
+  const nodeScope = await resolveTopicNodeScopeOrNull(ctx, legacyProjectId);
+  if (nodeScope) {
+    return {
+      ...nodeScope,
+      projectId: nodeScope.projectId ?? legacyProjectId
+    };
+  }
+  throw new Error(
+    `Legacy project scope ${legacyProjectId} has no mapped topic.`
+  );
+}
+async function resolveDirectLegacyProjectTopic(ctx, legacyProjectId) {
+  const directTopic = await tryReadTopicDoc(ctx, legacyProjectId, {
+    failureLog: "[topicScope] Failed to load direct project topic",
+    idLogKey: "projectId"
+  });
+  return directTopic ?? tryResolveHostTopicByLegacyScope(ctx, legacyProjectId);
+}
+async function tryReadTopicDoc(ctx, id, log) {
+  try {
+    return await ctx.db.get(id);
+  } catch (error) {
+    debugGraphPrimitiveFallback(log.failureLog, {
+      error,
+      [log.idLogKey]: id
+    });
+    return null;
+  }
+}
+async function buildTopicScope(ctx, topic, source, options = {}) {
+  const inherited = await resolveInheritedWorkspaceScope(ctx, topic);
+  const mapped = asMappedProjectId(topic);
+  return {
+    topicId: topic._id,
+    ...mapped || options.fallbackProjectId ? { projectId: mapped ?? options.fallbackProjectId } : {},
+    tenantId: inherited.tenantId,
+    workspaceId: inherited.workspaceId,
+    source
+  };
+}
 var optionalScopeArgs = {
   projectId: v.optional(v.string()),
   topicId: v.optional(v.string())
 };
-
-// src/epistemicBeliefs.helpers.ts
 var insightIdUnion = v.id("epistemicNodes");
 var optionalBeliefScopeArgs = optionalScopeArgs;
 ({
@@ -374,7 +296,7 @@ function buildBeliefEvidenceNotFoundResult() {
   return result;
 }
 async function resolveBeliefScopeOrNull(ctx, args) {
-  if (!args.projectId && !args.topicId) {
+  if (!(args.projectId || args.topicId)) {
     return null;
   }
   try {
@@ -411,7 +333,10 @@ async function requireAuthenticatedUserId(ctx) {
 }
 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();
+  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)`
@@ -452,7 +377,193 @@ async function insertEpistemicEdge(ctx, doc) {
   return ctx.db.insert("epistemicEdges", doc);
 }
 
+// src/logicalRoleInference.ts
+var PILLAR_IMPORTANCE = {
+  market: 1,
+  competition: 2,
+  product: 3,
+  team: 4,
+  financials: 5,
+  timing: 6,
+  other: 10
+};
+async function computeLogicalRole(ctx, evidenceId, beliefId) {
+  const belief = await ctx.db.get(beliefId);
+  if (belief?.nodeType !== "belief") {
+    return "contributory";
+  }
+  const beliefMetadata = belief.metadata;
+  const pillar = beliefMetadata?.pillar || "other";
+  const pillarRank = PILLAR_IMPORTANCE[pillar] ?? 10;
+  const isSynthesized = await checkIfSynthesizedHypothesis(ctx, beliefId);
+  const testingQuestions = await getTestingQuestionsForBelief(ctx, beliefId);
+  const answeredQuestions = await getQuestionsAnsweredByEvidence(
+    ctx,
+    evidenceId
+  );
+  const directlyTests = testingQuestions.filter(
+    (questionId) => answeredQuestions.includes(questionId)
+  );
+  if (directlyTests.length === 0) {
+    return "contributory";
+  }
+  if (isSynthesized && pillarRank <= 2) {
+    return directlyTests.length > 1 ? "necessary_sufficient" : "necessary";
+  }
+  if (isSynthesized) {
+    return "necessary";
+  }
+  return directlyTests.length > 1 ? "necessary" : "contributory";
+}
+async function checkIfSynthesizedHypothesis(ctx, beliefId) {
+  const belief = await ctx.db.get(beliefId);
+  if (!belief) {
+    return false;
+  }
+  const metadata = belief.metadata;
+  return metadata?.isSynthesized === true || metadata?.beliefStatus === "hypothesis";
+}
+async function getTestingQuestionsForBelief(ctx, beliefId) {
+  const testEdges = await ctx.db.query("epistemicEdges").withIndex(
+    "by_to_type",
+    (q) => q.eq("toNodeId", beliefId).eq("edgeType", "tests")
+  ).collect();
+  return testEdges.map((edge) => edge.fromNodeId).filter((id) => id !== void 0);
+}
+async function getQuestionsAnsweredByEvidence(ctx, evidenceId) {
+  const answerEdges = await ctx.db.query("epistemicEdges").withIndex(
+    "by_from_type",
+    (q) => q.eq("fromNodeId", evidenceId).eq("edgeType", "derived_from")
+  ).collect();
+  return answerEdges.map((edge) => edge.toNodeId).filter((id) => id !== void 0);
+}
+
 // src/epistemicBeliefs.links.ts
+function isRecord(value) {
+  return Boolean(value) && typeof value === "object" && !Array.isArray(value);
+}
+function readOptionalNumber(value) {
+  return typeof value === "number" && Number.isFinite(value) ? value : void 0;
+}
+function readOptionalString(value) {
+  return typeof value === "string" && value.trim().length > 0 ? value : void 0;
+}
+function readRecord(value) {
+  return isRecord(value) ? value : void 0;
+}
+function readConvexId(value) {
+  const normalized = readOptionalString(value);
+  return normalized;
+}
+function readEpistemicNodeRow(value) {
+  if (!isRecord(value)) {
+    return null;
+  }
+  const id = readConvexId(value._id);
+  const nodeType = readOptionalString(value.nodeType);
+  if (!(id && nodeType)) {
+    return null;
+  }
+  const row = { _id: id, nodeType };
+  const globalId = readOptionalString(value.globalId);
+  if (globalId !== void 0) {
+    row.globalId = globalId;
+  }
+  const metadata = readRecord(value.metadata);
+  if (metadata !== void 0) {
+    row.metadata = metadata;
+  }
+  const projectId = readOptionalString(value.projectId);
+  if (projectId !== void 0) {
+    row.projectId = projectId;
+  }
+  const status = readOptionalString(value.status);
+  if (status !== void 0) {
+    row.status = status;
+  }
+  const topicId = readOptionalString(value.topicId);
+  if (topicId !== void 0) {
+    row.topicId = topicId;
+  }
+  return row;
+}
+function requireEpistemicNodeRow(value, nodeType, message) {
+  const node = readEpistemicNodeRow(value);
+  if (!node || node.nodeType !== nodeType) {
+    throw new Error(message);
+  }
+  return node;
+}
+function requireNodeGlobalId(node, context) {
+  if (!node.globalId) {
+    throw new Error(
+      `${context} requires node.globalId for canonical edge endpoints`
+    );
+  }
+  return node.globalId;
+}
+function readEpistemicEdgeRow(value) {
+  if (!isRecord(value)) {
+    return null;
+  }
+  const id = readConvexId(value._id);
+  const globalId = readOptionalString(value.globalId);
+  if (!(id && globalId)) {
+    return null;
+  }
+  const row = { _id: id, globalId };
+  const edgeType = readOptionalString(value.edgeType);
+  if (edgeType !== void 0) {
+    row.edgeType = edgeType;
+  }
+  const fromGlobalId = readOptionalString(value.fromGlobalId);
+  if (fromGlobalId !== void 0) {
+    row.fromGlobalId = fromGlobalId;
+  }
+  const fromNodeId = readOptionalString(value.fromNodeId);
+  if (fromNodeId !== void 0) {
+    row.fromNodeId = fromNodeId;
+  }
+  const fromNodeType = readOptionalString(value.fromNodeType);
+  if (fromNodeType !== void 0) {
+    row.fromNodeType = fromNodeType;
+  }
+  const fromUuid = readOptionalString(value.fromUuid);
+  if (fromUuid !== void 0) {
+    row.fromUuid = fromUuid;
+  }
+  const sourceGlobalId = readOptionalString(value.sourceGlobalId);
+  if (sourceGlobalId !== void 0) {
+    row.sourceGlobalId = sourceGlobalId;
+  }
+  const targetGlobalId = readOptionalString(value.targetGlobalId);
+  if (targetGlobalId !== void 0) {
+    row.targetGlobalId = targetGlobalId;
+  }
+  const toGlobalId = readOptionalString(value.toGlobalId);
+  if (toGlobalId !== void 0) {
+    row.toGlobalId = toGlobalId;
+  }
+  const toNodeId = readOptionalString(value.toNodeId);
+  if (toNodeId !== void 0) {
+    row.toNodeId = toNodeId;
+  }
+  const toUuid = readOptionalString(value.toUuid);
+  if (toUuid !== void 0) {
+    row.toUuid = toUuid;
+  }
+  const weight = readOptionalNumber(value.weight);
+  if (weight !== void 0) {
+    row.weight = weight;
+  }
+  return row;
+}
+function readEpistemicEdgeRows(values) {
+  return values.flatMap((value) => {
+    const row = readEpistemicEdgeRow(value);
+    return row ? [row] : [];
+  });
+}
 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]`);
@@ -483,10 +594,11 @@ var updatePillar = mutation({
   handler: async (ctx, args) => {
     const authenticatedUserId = await requireAuthenticatedUserId(ctx);
     const now = Date.now();
-    const existingNode = await ctx.db.get(args.nodeId);
-    if (!existingNode || existingNode.nodeType !== "belief") {
-      throw new Error("Belief not found");
-    }
+    const existingNode = requireEpistemicNodeRow(
+      await ctx.db.get(args.nodeId),
+      "belief",
+      "Belief not found"
+    );
     if (!existingNode.projectId) {
       throw new Error("Belief has no project scope");
     }
@@ -496,7 +608,7 @@ var updatePillar = mutation({
       authenticatedUserId
     );
     let previousPillar = null;
-    const metadata = existingNode.metadata || {};
+    const metadata = existingNode.metadata ?? {};
     previousPillar = metadata.pillar;
     await ctx.db.patch(args.nodeId, {
       metadata: {
@@ -512,7 +624,7 @@ var updatePillar = mutation({
     });
     await ctx.db.insert("epistemicAudit", {
       entityType: "belief",
-      entityId: args.nodeId,
+      entityId: String(args.nodeId),
       changeType: "pillar_changed",
       projectId: existingNode.projectId,
       changedBy: authenticatedUserId,
@@ -538,10 +650,13 @@ var getCountByStatus = query({
     if (!scope) {
       return { active: 0, superseded: 0, archived: 0, total: 0 };
     }
-    const nodes = await ctx.db.query("epistemicNodes").withIndex(
+    const nodes = (await ctx.db.query("epistemicNodes").withIndex(
       "by_topic_type",
       (q) => q.eq("topicId", scope.topicId).eq("nodeType", "belief")
-    ).collect();
+    ).collect()).flatMap((row) => {
+      const node = readEpistemicNodeRow(row);
+      return node?.nodeType === "belief" ? [node] : [];
+    });
     const counts = {
       active: 0,
       superseded: 0,
@@ -582,31 +697,31 @@ var linkBeliefs = mutation({
   returns: permissiveReturn,
   handler: async (ctx, args) => {
     const authenticatedUserId = await requireAuthenticatedUserId(ctx);
-    const fromNode = await ctx.db.get(args.fromNodeId);
-    const toNode = await ctx.db.get(args.toNodeId);
-    if (!fromNode || !toNode) {
-      throw new Error("One or both belief nodes not found");
-    }
-    if (fromNode.nodeType !== "belief" || toNode.nodeType !== "belief") {
-      throw new Error("Both nodes must be beliefs");
-    }
+    const fromNode = requireEpistemicNodeRow(
+      await ctx.db.get(args.fromNodeId),
+      "belief",
+      "One or both belief nodes not found"
+    );
+    const toNode = requireEpistemicNodeRow(
+      await ctx.db.get(args.toNodeId),
+      "belief",
+      "One or both belief nodes not found"
+    );
     if (fromNode.projectId !== toNode.projectId) {
       throw new Error("Cannot link beliefs across different projects");
     }
     if (!fromNode.projectId) {
       throw new Error("Belief has no project scope");
     }
-    await requireScopeWriteAccess(
-      ctx,
-      fromNode.projectId,
-      authenticatedUserId
-    );
+    await requireScopeWriteAccess(ctx, fromNode.projectId, authenticatedUserId);
+    const fromGlobalId = requireNodeGlobalId(fromNode, "Belief link");
+    const toGlobalId = requireNodeGlobalId(toNode, "Belief link");
     const now = Date.now();
     const edgeGlobalId = generateGlobalId();
     await ctx.scheduler.runAfter(0, internal.neo4jEdgeAPI.createEdge, {
       globalId: edgeGlobalId,
-      fromGlobalId: fromNode.globalId,
-      toGlobalId: toNode.globalId,
+      fromGlobalId,
+      toGlobalId,
       edgeType: args.edgeType,
       weight: args.weight ?? 1,
       context: args.context,
@@ -645,23 +760,26 @@ var linkEvidence = mutation({
   returns: permissiveReturn,
   handler: async (ctx, args) => {
     const authenticatedUserId = await requireAuthenticatedUserId(ctx);
-    const belief = await ctx.db.get(args.beliefNodeId);
-    if (!belief || belief.nodeType !== "belief") {
-      throw new Error("Belief not found");
-    }
+    const belief = requireEpistemicNodeRow(
+      await ctx.db.get(args.beliefNodeId),
+      "belief",
+      "Belief not found"
+    );
     if (!belief.projectId) {
       throw new Error("Belief has no project scope");
     }
     await requireScopeWriteAccess(ctx, belief.projectId, authenticatedUserId);
-    const insight = await ctx.db.get(args.insightId);
-    if (!insight || insight.nodeType !== "evidence") {
-      throw new Error("Insight not found");
-    }
-    if ("projectId" in insight && insight.projectId && insight.projectId !== belief.projectId) {
+    const insight = requireEpistemicNodeRow(
+      await ctx.db.get(args.insightId),
+      "evidence",
+      "Insight not found"
+    );
+    if (insight.projectId && insight.projectId !== belief.projectId) {
       throw new Error("Insight belongs to a different project");
     }
     const evidenceNodeId = insight._id;
-    const evidenceGlobalId = insight.globalId;
+    const evidenceGlobalId = requireNodeGlobalId(insight, "Evidence link");
+    const beliefGlobalId = requireNodeGlobalId(belief, "Evidence link");
     const weight = assertSignedImpactScore(args.weight, "Evidence link");
     if (args.type === "supporting" && weight < 0) {
       throw new Error("Supporting evidence links require positive weight");
@@ -677,9 +795,9 @@ var linkEvidence = mutation({
       globalId: edgeGlobalId,
       // C2-RR.4 Defect E — canonical UUIDv7 endpoints, not Convex doc ids.
       fromNodeId: evidenceGlobalId,
-      toNodeId: belief.globalId,
+      toNodeId: beliefGlobalId,
       sourceGlobalId: evidenceGlobalId,
-      targetGlobalId: belief.globalId,
+      targetGlobalId: beliefGlobalId,
       edgeType,
       weight,
       confidence,
@@ -707,7 +825,7 @@ var linkEvidence = mutation({
     await ctx.scheduler.runAfter(0, internal.neo4jEdgeAPI.createEdge, {
       globalId: edgeGlobalId,
       fromGlobalId: evidenceGlobalId,
-      toGlobalId: belief.globalId,
+      toGlobalId: beliefGlobalId,
       edgeType,
       weight,
       confidence,
@@ -736,8 +854,9 @@ var unlinkEvidence = mutation({
   handler: async (ctx, args) => {
     const authenticatedUserId = await requireAuthenticatedUserId(ctx);
     const now = Date.now();
-    const evidenceNode = await ctx.db.get(args.insightId);
-    if (!evidenceNode || evidenceNode.nodeType !== "evidence") {
+    const evidenceNodeRaw = await ctx.db.get(args.insightId);
+    const evidenceNode = readEpistemicNodeRow(evidenceNodeRaw);
+    if (evidenceNode?.nodeType !== "evidence") {
       return buildBeliefEvidenceNotFoundResult();
     }
     if (!evidenceNode.projectId) {
@@ -748,17 +867,25 @@ var unlinkEvidence = mutation({
       evidenceNode.projectId,
       authenticatedUserId
     );
-    const beliefNode = await ctx.db.get(args.beliefNodeId);
-    if (!beliefNode || beliefNode.nodeType !== "belief") {
-      throw new Error("Belief not found");
-    }
+    const beliefNode = requireEpistemicNodeRow(
+      await ctx.db.get(args.beliefNodeId),
+      "belief",
+      "Belief not found"
+    );
     if (beliefNode.projectId !== evidenceNode.projectId) {
       throw new Error("Belief and evidence belong to different projects");
     }
-    const edge = await ctx.db.query("epistemicEdges").withIndex(
-      "by_from_to",
-      (q) => q.eq("fromNodeId", evidenceNode._id).eq("toNodeId", args.beliefNodeId)
-    ).first();
+    const evidenceGlobalId = requireNodeGlobalId(
+      evidenceNode,
+      "Evidence unlink"
+    );
+    const beliefGlobalId = requireNodeGlobalId(beliefNode, "Evidence unlink");
+    const edge = readEpistemicEdgeRow(
+      await ctx.db.query("epistemicEdges").withIndex(
+        "by_from_to",
+        (q) => q.eq("fromNodeId", evidenceGlobalId).eq("toNodeId", beliefGlobalId)
+      ).first()
+    );
     if (edge) {
       await ctx.scheduler.runAfter(0, internal.neo4jEdgeAPI.deleteEdge, {
         globalId: edge.globalId
@@ -788,25 +915,31 @@ var getWithEvidence = query({
   },
   returns: permissiveReturn,
   handler: async (ctx, args) => {
-    const belief = await ctx.db.get(args.nodeId);
-    if (!belief || belief.nodeType !== "belief") {
+    const belief = readEpistemicNodeRow(await ctx.db.get(args.nodeId));
+    if (belief?.nodeType !== "belief") {
       return null;
     }
-    const incomingEdges = await ctx.db.query("epistemicEdges").withIndex(
-      "by_to_type",
-      (q) => q.eq("toNodeId", args.nodeId).eq("edgeType", "informs")
-    ).collect();
-    const evidenceNodeIds = incomingEdges.filter((e) => e.fromNodeType === "evidence").map((e) => e.fromNodeId);
-    const evidenceNodes = await Promise.all(
-      evidenceNodeIds.map((id) => ctx.db.get(id))
+    const beliefGlobalId = requireNodeGlobalId(belief, "Belief evidence read");
+    const incomingEdges = readEpistemicEdgeRows(
+      await ctx.db.query("epistemicEdges").withIndex(
+        "by_to_type",
+        (q) => q.eq("toNodeId", beliefGlobalId).eq("edgeType", "informs")
+      ).collect()
     );
     const supporting = [];
     const contradicting = [];
-    for (let i = 0; i < evidenceNodes.length; i++) {
-      const node = evidenceNodes[i];
-      const edge = incomingEdges[i];
-      if (node) {
-        if ((edge.weight || 0) >= 0) {
+    for (const edge of incomingEdges.filter(
+      (incomingEdge) => incomingEdge.fromNodeType === "evidence"
+    )) {
+      const node = readEpistemicNodeRow(
+        await resolveRelationshipEndpoint(
+          ctx,
+          edge.fromNodeId,
+          edge.sourceGlobalId ?? edge.fromGlobalId ?? edge.fromUuid
+        )
+      );
+      if (node?.nodeType === "evidence") {
+        if ((edge.weight ?? 0) >= 0) {
           supporting.push(node);
         } else {
           contradicting.push(node);
@@ -834,13 +967,13 @@ async function collectRelationshipNodeRefs(ctx, nodeId) {
 }
 function endpointMatches(q, fields, refs) {
   return q.or(
-    ...fields.flatMap(
-      (field) => refs.map((ref) => q.eq(q.field(field), ref))
-    )
+    ...fields.flatMap((field) => refs.map((ref) => q.eq(q.field(field), ref)))
   );
 }
 async function resolveRelationshipEndpoint(ctx, endpointId, globalEndpointId) {
-  const candidates = [endpointId, globalEndpointId].map((value) => typeof value === "string" ? value.trim() : "").filter((value, index, values) => value.length > 0 && values.indexOf(value) === index);
+  const candidates = [endpointId, globalEndpointId].map((value) => typeof value === "string" ? value.trim() : "").filter(
+    (value, index, values) => value.length > 0 && values.indexOf(value) === index
+  );
   for (const candidate of candidates) {
     try {
       const direct = await ctx.db.get(candidate);
@@ -872,13 +1005,15 @@ var getRelationships = query({
     };
     const nodeRefs = await collectRelationshipNodeRefs(ctx, args.nodeId);
     if (direction === "in" || direction === "both") {
-      const inEdges = await ctx.db.query("epistemicEdges").filter(
-        (q) => endpointMatches(
-          q,
-          ["toNodeId", "targetGlobalId", "toGlobalId", "toUuid"],
-          nodeRefs
-        )
-      ).collect();
+      const inEdges = readEpistemicEdgeRows(
+        await ctx.db.query("epistemicEdges").filter(
+          (q) => endpointMatches(
+            q,
+            ["toNodeId", "targetGlobalId", "toGlobalId", "toUuid"],
+            nodeRefs
+          )
+        ).collect()
+      );
       for (const edge of inEdges) {
         const sourceNode = await resolveRelationshipEndpoint(
           ctx,
@@ -889,13 +1024,15 @@ var getRelationships = query({
       }
     }
     if (direction === "out" || direction === "both") {
-      const outEdges = await ctx.db.query("epistemicEdges").filter(
-        (q) => endpointMatches(
-          q,
-          ["fromNodeId", "sourceGlobalId", "fromGlobalId", "fromUuid"],
-          nodeRefs
-        )
-      ).collect();
+      const outEdges = readEpistemicEdgeRows(
+        await ctx.db.query("epistemicEdges").filter(
+          (q) => endpointMatches(
+            q,
+            ["fromNodeId", "sourceGlobalId", "fromGlobalId", "fromUuid"],
+            nodeRefs
+          )
+        ).collect()
+      );
       for (const edge of outEdges) {
         const targetNode = await resolveRelationshipEndpoint(
           ctx,