@lucern/graph-primitives 1.0.28 → 1.0.30

package/dist/epistemicEdges.queries.js

@@ -1,9 +1,16 @@
-import { v } from 'convex/values';
 import { checkScopeAccess } from '@lucern/access-control/access';
 import { permissiveReturn } from '@lucern/contracts/schema-helpers/validators';
-import { componentsGeneric, queryGeneric, anyApi } from 'convex/server';
+import { v } from 'convex/values';
+import { unsafeConvexAnyApi } from '@lucern/contracts/convex/unsafeAnyApi';
+import { componentsGeneric, queryGeneric } from 'convex/server';
 
 // src/epistemicEdges.queries.ts
+var unsafeApi = unsafeConvexAnyApi(
+  "graph-primitives top-level module bundle lacks a committed Convex _generated/api surface"
+);
+var api = unsafeApi;
+componentsGeneric();
+var query = queryGeneric;
 
 // src/debug.ts
 function isGraphPrimitiveDebugEnabled() {
@@ -16,9 +23,127 @@ function debugGraphPrimitiveFallback(message, context) {
   }
   console.debug(message, context ?? {});
 }
-var api = anyApi;
-componentsGeneric();
-var query = queryGeneric;
+
+// src/graphTypes.ts
+function getNodeLayer(nodeType) {
+  const L4_TYPES = ["decision"];
+  const L3_TYPES = ["belief", "question", "theme", "deal"];
+  const L2_TYPES = ["claim", "evidence", "synthesis", "answer"];
+  const L1_TYPES = ["atomic_fact", "excerpt", "source"];
+  const ONTOLOGICAL_TYPES = [
+    "company",
+    "person",
+    "investor",
+    "function",
+    "value_chain"
+  ];
+  const ORGANIZATIONAL_TYPES = ["topic"];
+  if (L4_TYPES.includes(nodeType)) {
+    return "L4";
+  }
+  if (L3_TYPES.includes(nodeType)) {
+    return "L3";
+  }
+  if (L2_TYPES.includes(nodeType)) {
+    return "L2";
+  }
+  if (L1_TYPES.includes(nodeType)) {
+    return "L1";
+  }
+  if (ONTOLOGICAL_TYPES.includes(nodeType)) {
+    return "ontological";
+  }
+  if (ORGANIZATIONAL_TYPES.includes(nodeType)) {
+    return "organizational";
+  }
+  console.warn(`[GraphTypes] Unknown nodeType "${nodeType}", defaulting to L2`);
+  return "L2";
+}
+
+// src/edgeValidation.ts
+function getLayerDepth(layer) {
+  switch (layer) {
+    case "L4":
+      return 4;
+    case "L3":
+      return 3;
+    case "L2":
+      return 2;
+    case "L1":
+      return 1;
+    case "ontological":
+      return 0;
+    default:
+      return -1;
+  }
+}
+function shouldContinueTraversal(currentLayer, targetLayer, options) {
+  const currentDepth = getLayerDepth(currentLayer);
+  const targetDepth = getLayerDepth(targetLayer);
+  if (options.minLayer !== void 0 && targetDepth < options.minLayer) {
+    return false;
+  }
+  if (options.maxLayer !== void 0 && targetDepth > options.maxLayer) {
+    return false;
+  }
+  switch (options.mode) {
+    case "anchor_down":
+      return targetDepth <= currentDepth;
+    case "anchor_up":
+      return targetDepth >= currentDepth;
+    case "same_layer":
+      return targetDepth === currentDepth;
+    case "decision_trace":
+      return currentDepth === 4 ? targetDepth === 3 : targetDepth === currentDepth;
+    default:
+      return true;
+  }
+}
+function getDefaultMinLayer(mode) {
+  switch (mode) {
+    case "anchor_down":
+      return 1;
+    case "anchor_up":
+      return 2;
+    case "same_layer":
+      return 1;
+    case "decision_trace":
+      return 3;
+    default:
+      return 1;
+  }
+}
+function readOptionalString(value) {
+  return typeof value === "string" && value.trim().length > 0 ? value : void 0;
+}
+function readConvexId(value) {
+  const normalized = readOptionalString(value);
+  return normalized;
+}
+function readRecord(value) {
+  return value && typeof value === "object" && !Array.isArray(value) ? value : null;
+}
+function readWorkspaceScopedEdge(value) {
+  const record = readRecord(value);
+  if (!record) {
+    return null;
+  }
+  const id = readConvexId(record._id);
+  const edgeType = readOptionalString(record.edgeType);
+  if (!(id && edgeType)) {
+    return null;
+  }
+  const edge = { _id: id, edgeType };
+  const projectId = readOptionalString(record.projectId);
+  if (projectId !== void 0) {
+    edge.projectId = projectId;
+  }
+  const topicId = readOptionalString(record.topicId);
+  if (topicId !== void 0) {
+    edge.topicId = topicId;
+  }
+  return edge;
+}
 v.union(
   v.literal("L4"),
   v.literal("L3"),
@@ -113,7 +238,7 @@ var edgeTypeValidator = v.union(
   v.literal("competes_with")
 );
 function edgeMatchesWorkspaceReasoningScope(edge, scope) {
-  return scope.topicId !== void 0 && edge.topicId === scope.topicId || scope.projectId !== void 0 && edge.projectId === scope.projectId;
+  return scope.topicId !== void 0 && edge.topicId === String(scope.topicId) || scope.projectId !== void 0 && (edge.projectId === scope.projectId || edge.topicId === scope.projectId);
 }
 async function collectScopedEdges(ctx, scope, scanLimit) {
   const queries = [];
@@ -136,7 +261,11 @@ async function collectScopedEdges(ctx, scope, scanLimit) {
   const seen = /* @__PURE__ */ new Set();
   const deduped = [];
   const flattened = (await Promise.all(queries)).flat();
-  for (const edge of flattened) {
+  for (const value of flattened) {
+    const edge = readWorkspaceScopedEdge(value);
+    if (!edge) {
+      continue;
+    }
     const key = String(edge._id);
     if (seen.has(key)) {
       continue;
@@ -146,96 +275,6 @@ async function collectScopedEdges(ctx, scope, scanLimit) {
   }
   return deduped;
 }
-
-// src/graphTypes.ts
-function getNodeLayer(nodeType) {
-  const L4_TYPES = ["decision"];
-  const L3_TYPES = ["belief", "question", "theme", "deal"];
-  const L2_TYPES = ["claim", "evidence", "synthesis", "answer"];
-  const L1_TYPES = ["atomic_fact", "excerpt", "source"];
-  const ONTOLOGICAL_TYPES = [
-    "company",
-    "person",
-    "investor",
-    "function",
-    "value_chain"
-  ];
-  const ORGANIZATIONAL_TYPES = ["topic"];
-  if (L4_TYPES.includes(nodeType)) {
-    return "L4";
-  }
-  if (L3_TYPES.includes(nodeType)) {
-    return "L3";
-  }
-  if (L2_TYPES.includes(nodeType)) {
-    return "L2";
-  }
-  if (L1_TYPES.includes(nodeType)) {
-    return "L1";
-  }
-  if (ONTOLOGICAL_TYPES.includes(nodeType)) {
-    return "ontological";
-  }
-  if (ORGANIZATIONAL_TYPES.includes(nodeType)) {
-    return "organizational";
-  }
-  console.warn(`[GraphTypes] Unknown nodeType "${nodeType}", defaulting to L2`);
-  return "L2";
-}
-
-// src/edgeValidation.ts
-function getLayerDepth(layer) {
-  switch (layer) {
-    case "L4":
-      return 4;
-    case "L3":
-      return 3;
-    case "L2":
-      return 2;
-    case "L1":
-      return 1;
-    case "ontological":
-      return 0;
-    default:
-      return -1;
-  }
-}
-function shouldContinueTraversal(currentLayer, targetLayer, options) {
-  const currentDepth = getLayerDepth(currentLayer);
-  const targetDepth = getLayerDepth(targetLayer);
-  if (options.minLayer !== void 0 && targetDepth < options.minLayer) {
-    return false;
-  }
-  if (options.maxLayer !== void 0 && targetDepth > options.maxLayer) {
-    return false;
-  }
-  switch (options.mode) {
-    case "anchor_down":
-      return targetDepth <= currentDepth;
-    case "anchor_up":
-      return targetDepth >= currentDepth;
-    case "same_layer":
-      return targetDepth === currentDepth;
-    case "decision_trace":
-      return currentDepth === 4 ? targetDepth === 3 : targetDepth === currentDepth;
-    default:
-      return true;
-  }
-}
-function getDefaultMinLayer(mode) {
-  switch (mode) {
-    case "anchor_down":
-      return 1;
-    case "anchor_up":
-      return 2;
-    case "same_layer":
-      return 1;
-    case "decision_trace":
-      return 3;
-    default:
-      return 1;
-  }
-}
 var LEGACY_SCOPE_FIELD = "graphScopeProjectId";
 async function resolveTopicNodeScopeOrNull(ctx, ref) {
   if (!ctx?.db || typeof ctx.db.query !== "function") {
@@ -270,13 +309,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") {
@@ -301,8 +342,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();
@@ -314,7 +356,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);
@@ -370,156 +412,455 @@ 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 await resolveScopeFromTopicId(ctx, args.topicId);
+  }
+  if (args.projectId) {
+    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 {
-      topicId: topic._id,
-      tenantId: inherited.tenantId,
-      workspaceId: inherited.workspaceId,
-      source: "topic"
+      ...nodeScope,
+      projectId: nodeScope.projectId ?? legacyProjectId
     };
   }
-  if (args.projectId) {
-    let directTopic = null;
+  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/epistemicEdges.queries.ts
+var DERIVED_FROM_EDGE_TYPE = "derived_from";
+var EPISTEMIC_LAYERS = /* @__PURE__ */ new Set([
+  "L4",
+  "L3",
+  "L2",
+  "L1",
+  "ontological",
+  "organizational"
+]);
+function readOptionalString2(value) {
+  return typeof value === "string" && value.trim().length > 0 ? value : void 0;
+}
+function readOptionalNumber(value) {
+  return typeof value === "number" && Number.isFinite(value) ? value : void 0;
+}
+function readConvexId2(value) {
+  const normalized = readOptionalString2(value);
+  return normalized;
+}
+function readRecord2(value) {
+  return value && typeof value === "object" && !Array.isArray(value) ? value : null;
+}
+function readEpistemicLayer(value) {
+  const layer = readOptionalString2(value);
+  return layer && EPISTEMIC_LAYERS.has(layer) ? layer : void 0;
+}
+function readEdgeNodeRow(value) {
+  const record = readRecord2(value);
+  if (!record) {
+    return null;
+  }
+  const id = readConvexId2(record._id);
+  const nodeType = readOptionalString2(record.nodeType);
+  if (!(id && nodeType)) {
+    return null;
+  }
+  const node = { ...record, _id: id, nodeType };
+  const globalId = readOptionalString2(record.globalId);
+  if (globalId !== void 0) {
+    node.globalId = globalId;
+  }
+  const epistemicLayer = readEpistemicLayer(record.epistemicLayer);
+  if (epistemicLayer !== void 0) {
+    node.epistemicLayer = epistemicLayer;
+  }
+  return node;
+}
+function readEdgeRow(value) {
+  const record = readRecord2(value);
+  if (!record) {
+    return null;
+  }
+  const id = readConvexId2(record._id);
+  const edgeType = readOptionalString2(record.edgeType);
+  if (!(id && edgeType)) {
+    return null;
+  }
+  const edge = { ...record, _id: id, edgeType };
+  const globalId = readOptionalString2(record.globalId);
+  if (globalId !== void 0) {
+    edge.globalId = globalId;
+  }
+  const fromNodeId = readOptionalString2(record.fromNodeId);
+  if (fromNodeId !== void 0) {
+    edge.fromNodeId = fromNodeId;
+  }
+  const toNodeId = readOptionalString2(record.toNodeId);
+  if (toNodeId !== void 0) {
+    edge.toNodeId = toNodeId;
+  }
+  const sourceGlobalId = readOptionalString2(record.sourceGlobalId);
+  if (sourceGlobalId !== void 0) {
+    edge.sourceGlobalId = sourceGlobalId;
+  }
+  const targetGlobalId = readOptionalString2(record.targetGlobalId);
+  if (targetGlobalId !== void 0) {
+    edge.targetGlobalId = targetGlobalId;
+  }
+  const fromGlobalId = readOptionalString2(record.fromGlobalId);
+  if (fromGlobalId !== void 0) {
+    edge.fromGlobalId = fromGlobalId;
+  }
+  const toGlobalId = readOptionalString2(record.toGlobalId);
+  if (toGlobalId !== void 0) {
+    edge.toGlobalId = toGlobalId;
+  }
+  const toLayer = readEpistemicLayer(record.toLayer);
+  if (toLayer !== void 0) {
+    edge.toLayer = toLayer;
+  }
+  const weight = readOptionalNumber(record.weight);
+  if (weight !== void 0) {
+    edge.weight = weight;
+  }
+  return edge;
+}
+function readEdgeRows(values) {
+  return values.flatMap((value) => {
+    const edge = readEdgeRow(value);
+    return edge ? [edge] : [];
+  });
+}
+function dedupeEdges(edges) {
+  const seen = /* @__PURE__ */ new Set();
+  const deduped = [];
+  for (const edge of edges) {
+    const key = String(edge._id);
+    if (seen.has(key)) {
+      continue;
+    }
+    seen.add(key);
+    deduped.push(edge);
+  }
+  return deduped;
+}
+function filterEdgesByType(edges, edgeType) {
+  return edgeType ? edges.filter((edge) => edge.edgeType === edgeType) : [...edges];
+}
+function nodeEndpointRefs(node) {
+  const refs = /* @__PURE__ */ new Set([String(node._id)]);
+  if (node.globalId) {
+    refs.add(node.globalId);
+  }
+  return [...refs];
+}
+function edgeSourceRefs(edge) {
+  return [edge.fromNodeId, edge.sourceGlobalId, edge.fromGlobalId].flatMap(
+    (value) => value ? [value] : []
+  );
+}
+function edgeTargetRefs(edge) {
+  return [edge.toNodeId, edge.targetGlobalId, edge.toGlobalId].flatMap(
+    (value) => value ? [value] : []
+  );
+}
+function primaryEdgeSourceRef(edge) {
+  return edge.sourceGlobalId ?? edge.fromGlobalId ?? edge.fromNodeId;
+}
+function primaryEdgeTargetRef(edge) {
+  return edge.targetGlobalId ?? edge.toGlobalId ?? edge.toNodeId;
+}
+function hasVisitedNode(node, visited) {
+  return nodeEndpointRefs(node).some((ref) => visited.has(ref));
+}
+function markVisitedNode(node, visited) {
+  for (const ref of nodeEndpointRefs(node)) {
+    visited.add(ref);
+  }
+}
+async function resolveNodeRefSoft(ctx, nodeRef) {
+  const normalizedId = ctx.db.normalizeId?.("epistemicNodes", nodeRef) ?? readConvexId2(nodeRef);
+  if (normalizedId) {
     try {
-      directTopic = await ctx.db.get(
-        args.projectId
-      );
+      const direct = readEdgeNodeRow(await ctx.db.get(normalizedId));
+      if (direct) {
+        return direct;
+      }
     } catch (error) {
       debugGraphPrimitiveFallback(
-        "[topicScope] Failed to load direct project topic",
-        {
-          error,
-          projectId: args.projectId
-        }
+        "[epistemicEdges] Direct node-ref lookup failed",
+        { error, nodeRef }
       );
     }
-    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"
-      };
+  }
+  return readEdgeNodeRow(
+    await ctx.db.query("epistemicNodes").withIndex("by_globalId", (q) => q.eq("globalId", nodeRef)).first()
+  );
+}
+async function collectNodeReferenceIds(ctx, nodeRef) {
+  const refs = /* @__PURE__ */ new Set([nodeRef]);
+  const node = await resolveNodeRefSoft(ctx, nodeRef);
+  if (node) {
+    for (const ref of nodeEndpointRefs(node)) {
+      refs.add(ref);
     }
-    const nodeScope = await resolveTopicNodeScopeOrNull(
-      ctx,
-      String(args.projectId)
+  }
+  return [...refs];
+}
+async function collectEdgesFromRefs(ctx, refs, edgeType) {
+  const reads = [];
+  for (const ref of refs) {
+    reads.push(
+      edgeType ? ctx.db.query("epistemicEdges").withIndex(
+        "by_from_type",
+        (q) => q.eq("fromNodeId", ref).eq("edgeType", edgeType)
+      ).collect() : ctx.db.query("epistemicEdges").withIndex("by_from", (q) => q.eq("fromNodeId", ref)).collect(),
+      ctx.db.query("epistemicEdges").withIndex("by_source_global_id", (q) => q.eq("sourceGlobalId", ref)).collect()
+    );
+  }
+  const edges = readEdgeRows((await Promise.all(reads)).flat());
+  return dedupeEdges(filterEdgesByType(edges, edgeType));
+}
+async function collectEdgesToRefs(ctx, refs, edgeType) {
+  const reads = [];
+  for (const ref of refs) {
+    reads.push(
+      edgeType ? ctx.db.query("epistemicEdges").withIndex(
+        "by_to_type",
+        (q) => q.eq("toNodeId", ref).eq("edgeType", edgeType)
+      ).collect() : ctx.db.query("epistemicEdges").withIndex("by_to", (q) => q.eq("toNodeId", ref)).collect(),
+      ctx.db.query("epistemicEdges").withIndex("by_target_global_id", (q) => q.eq("targetGlobalId", ref)).collect()
     );
-    if (nodeScope) {
-      return {
-        ...nodeScope,
-        projectId: nodeScope.projectId ?? String(args.projectId)
-      };
+  }
+  const edges = readEdgeRows((await Promise.all(reads)).flat());
+  return dedupeEdges(filterEdgesByType(edges, edgeType));
+}
+async function collectEdgesFromNodeRef(ctx, nodeRef, edgeType) {
+  return collectEdgesFromRefs(
+    ctx,
+    await collectNodeReferenceIds(ctx, nodeRef),
+    edgeType
+  );
+}
+async function collectEdgesToNodeRef(ctx, nodeRef, edgeType) {
+  return collectEdgesToRefs(
+    ctx,
+    await collectNodeReferenceIds(ctx, nodeRef),
+    edgeType
+  );
+}
+async function collectEdgesBetweenRefs(ctx, fromRefs, toRefs) {
+  const reads = [];
+  for (const fromRef of fromRefs) {
+    for (const toRef of toRefs) {
+      reads.push(
+        ctx.db.query("epistemicEdges").withIndex(
+          "by_from_to",
+          (q) => q.eq("fromNodeId", fromRef).eq("toNodeId", toRef)
+        ).collect()
+      );
     }
-    throw new Error(
-      `Legacy project scope ${String(args.projectId)} has no mapped topic.`
+    reads.push(
+      ctx.db.query("epistemicEdges").withIndex(
+        "by_source_global_id",
+        (q) => q.eq("sourceGlobalId", fromRef)
+      ).collect()
     );
   }
-  throw new Error(
-    "Missing scope: provide topicId (preferred) or legacy projectId alias."
+  for (const toRef of toRefs) {
+    reads.push(
+      ctx.db.query("epistemicEdges").withIndex("by_target_global_id", (q) => q.eq("targetGlobalId", toRef)).collect()
+    );
+  }
+  const fromRefSet = new Set(fromRefs);
+  const toRefSet = new Set(toRefs);
+  const edges = readEdgeRows((await Promise.all(reads)).flat()).filter(
+    (edge) => edgeSourceRefs(edge).some((ref) => fromRefSet.has(ref)) && edgeTargetRefs(edge).some((ref) => toRefSet.has(ref))
   );
+  return dedupeEdges(edges);
+}
+async function collectEdgesBetweenNodeRefs(ctx, fromNodeRef, toNodeRef) {
+  const [fromRefs, toRefs] = await Promise.all([
+    collectNodeReferenceIds(ctx, fromNodeRef),
+    collectNodeReferenceIds(ctx, toNodeRef)
+  ]);
+  return collectEdgesBetweenRefs(ctx, fromRefs, toRefs);
+}
+function buildLineageTraversalConfig(args) {
+  const mode = args.mode ?? "anchor_down";
+  return {
+    maxDepth: args.maxDepth ?? 10,
+    mode,
+    minLayer: args.minLayer ?? getDefaultMinLayer(mode),
+    maxLayer: args.maxLayer ?? 4
+  };
+}
+function buildLineageQueueSeed(node) {
+  return {
+    node,
+    depth: 0,
+    currentLayer: node.epistemicLayer ?? getNodeLayer(node.nodeType)
+  };
+}
+function shouldSkipLineageNode(item, state, visited) {
+  if (item.depth >= state.maxDepth) {
+    return true;
+  }
+  return hasVisitedNode(item.node, visited);
+}
+function resolveLineageTargetLayer(edge, targetNode) {
+  return edge.toLayer ?? targetNode.epistemicLayer ?? getNodeLayer(targetNode.nodeType);
+}
+function collectDerivedFromEdges(ctx, node) {
+  return collectEdgesFromRefs(
+    ctx,
+    nodeEndpointRefs(node),
+    DERIVED_FROM_EDGE_TYPE
+  );
+}
+function shouldAdvanceLineage(currentLayer, targetLayer, state) {
+  return shouldContinueTraversal(currentLayer, targetLayer, {
+    mode: state.mode,
+    minLayer: state.minLayer,
+    maxLayer: state.maxLayer
+  });
+}
+async function appendLineageEdges(ctx, current, state, lineage, queue, visited) {
+  const lineageEdges = await collectDerivedFromEdges(ctx, current.node);
+  for (const edge of lineageEdges) {
+    const targetRef = primaryEdgeTargetRef(edge);
+    if (!targetRef) {
+      continue;
+    }
+    const targetNode = await resolveNodeRefSoft(ctx, targetRef);
+    if (!targetNode || hasVisitedNode(targetNode, visited)) {
+      continue;
+    }
+    const targetLayer = resolveLineageTargetLayer(edge, targetNode);
+    if (!shouldAdvanceLineage(current.currentLayer, targetLayer, state)) {
+      continue;
+    }
+    const nextDepth = current.depth + 1;
+    lineage.push({
+      node: targetNode,
+      depth: nextDepth,
+      edgeType: edge.edgeType,
+      layer: targetLayer
+    });
+    queue.push({
+      node: targetNode,
+      depth: nextDepth,
+      currentLayer: targetLayer
+    });
+  }
 }
-var optionalScopeArgs = {
-  projectId: v.optional(v.string()),
-  topicId: v.optional(v.string())
-};
-
-// src/epistemicEdges.queries.ts
 var get = query({
   args: { edgeId: v.id("epistemicEdges") },
   returns: permissiveReturn,
-  handler: async (ctx, args) => {
-    return await ctx.db.get(args.edgeId);
-  }
+  handler: async (ctx, args) => await ctx.db.get(args.edgeId)
 });
 var getByGlobalId = query({
   args: { globalId: v.string() },
   returns: permissiveReturn,
-  handler: async (ctx, args) => {
-    return await ctx.db.query("epistemicEdges").withIndex("by_globalId", (q) => q.eq("globalId", args.globalId)).first();
-  }
+  handler: async (ctx, args) => await ctx.db.query("epistemicEdges").withIndex("by_globalId", (q) => q.eq("globalId", args.globalId)).first()
 });
 var getFromNode = query({
   args: {
@@ -527,16 +868,7 @@ var getFromNode = query({
     edgeType: v.optional(edgeTypeValidator)
   },
   returns: permissiveReturn,
-  handler: async (ctx, args) => {
-    const { edgeType } = args;
-    if (edgeType) {
-      return await ctx.db.query("epistemicEdges").withIndex(
-        "by_from_type",
-        (q) => q.eq("fromNodeId", args.fromNodeId).eq("edgeType", edgeType)
-      ).collect();
-    }
-    return await ctx.db.query("epistemicEdges").withIndex("by_from", (q) => q.eq("fromNodeId", args.fromNodeId)).collect();
-  }
+  handler: async (ctx, args) => await collectEdgesFromNodeRef(ctx, String(args.fromNodeId), args.edgeType)
 });
 var getToNode = query({
   args: {
@@ -544,16 +876,7 @@ var getToNode = query({
     edgeType: v.optional(edgeTypeValidator)
   },
   returns: permissiveReturn,
-  handler: async (ctx, args) => {
-    const { edgeType } = args;
-    if (edgeType) {
-      return await ctx.db.query("epistemicEdges").withIndex(
-        "by_to_type",
-        (q) => q.eq("toNodeId", args.toNodeId).eq("edgeType", edgeType)
-      ).collect();
-    }
-    return await ctx.db.query("epistemicEdges").withIndex("by_to", (q) => q.eq("toNodeId", args.toNodeId)).collect();
-  }
+  handler: async (ctx, args) => await collectEdgesToNodeRef(ctx, String(args.toNodeId), args.edgeType)
 });
 var getBySourceNode = query({
   args: {
@@ -561,27 +884,7 @@ var getBySourceNode = query({
     edgeType: v.optional(v.string())
   },
   returns: permissiveReturn,
-  handler: async (ctx, args) => {
-    const isConvexId = args.sourceNodeId.length === 32 || args.sourceNodeId.includes("epistemicNodes");
-    if (isConvexId) {
-      const query2 = args.edgeType ? ctx.db.query("epistemicEdges").withIndex(
-        "by_from_type",
-        (q) => q.eq("fromNodeId", args.sourceNodeId).eq("edgeType", args.edgeType)
-      ) : ctx.db.query("epistemicEdges").withIndex(
-        "by_from",
-        (q) => q.eq("fromNodeId", args.sourceNodeId)
-      );
-      return await query2.collect();
-    }
-    const byGlobalId = await ctx.db.query("epistemicEdges").withIndex(
-      "by_source_global_id",
-      (q) => q.eq("sourceGlobalId", args.sourceNodeId)
-    ).collect();
-    if (args.edgeType) {
-      return byGlobalId.filter((edge) => edge.edgeType === args.edgeType);
-    }
-    return byGlobalId;
-  }
+  handler: async (ctx, args) => await collectEdgesFromNodeRef(ctx, args.sourceNodeId, args.edgeType)
 });
 var getByTargetNode = query({
   args: {
@@ -589,27 +892,7 @@ var getByTargetNode = query({
     edgeType: v.optional(v.string())
   },
   returns: permissiveReturn,
-  handler: async (ctx, args) => {
-    const isConvexId = args.targetNodeId.length === 32 || args.targetNodeId.includes("epistemicNodes");
-    if (isConvexId) {
-      const query2 = args.edgeType ? ctx.db.query("epistemicEdges").withIndex(
-        "by_to_type",
-        (q) => q.eq("toNodeId", args.targetNodeId).eq("edgeType", args.edgeType)
-      ) : ctx.db.query("epistemicEdges").withIndex(
-        "by_to",
-        (q) => q.eq("toNodeId", args.targetNodeId)
-      );
-      return await query2.collect();
-    }
-    const byGlobalId = await ctx.db.query("epistemicEdges").withIndex(
-      "by_target_global_id",
-      (q) => q.eq("targetGlobalId", args.targetNodeId)
-    ).collect();
-    if (args.edgeType) {
-      return byGlobalId.filter((edge) => edge.edgeType === args.edgeType);
-    }
-    return byGlobalId;
-  }
+  handler: async (ctx, args) => await collectEdgesToNodeRef(ctx, args.targetNodeId, args.edgeType)
 });
 var getBetween = query({
   args: {
@@ -618,16 +901,14 @@ var getBetween = query({
     edgeType: v.optional(edgeTypeValidator)
   },
   returns: permissiveReturn,
-  handler: async (ctx, args) => {
-    const edges = await ctx.db.query("epistemicEdges").withIndex(
-      "by_from_to",
-      (q) => q.eq("fromNodeId", args.fromNodeId).eq("toNodeId", args.toNodeId)
-    ).collect();
-    if (args.edgeType) {
-      return edges.filter((e) => e.edgeType === args.edgeType);
-    }
-    return edges;
-  }
+  handler: async (ctx, args) => filterEdgesByType(
+    await collectEdgesBetweenNodeRefs(
+      ctx,
+      String(args.fromNodeId),
+      String(args.toNodeId)
+    ),
+    args.edgeType
+  )
 });
 var getByNodes = query({
   args: {
@@ -635,12 +916,11 @@ var getByNodes = query({
     toNodeId: v.id("epistemicNodes")
   },
   returns: permissiveReturn,
-  handler: async (ctx, args) => {
-    return await ctx.db.query("epistemicEdges").withIndex(
-      "by_from_to",
-      (q) => q.eq("fromNodeId", args.fromNodeId).eq("toNodeId", args.toNodeId)
-    ).first();
-  }
+  handler: async (ctx, args) => (await collectEdgesBetweenNodeRefs(
+    ctx,
+    String(args.fromNodeId),
+    String(args.toNodeId)
+  ))[0] ?? null
 });
 var getByProjectAndType = query({
   args: {
@@ -649,7 +929,7 @@ var getByProjectAndType = query({
   },
   returns: permissiveReturn,
   handler: async (ctx, args) => {
-    if (!args.projectId && !args.topicId) {
+    if (!(args.projectId || args.topicId)) {
       return [];
     }
     let scope;
@@ -683,7 +963,7 @@ var getByProject = query({
   },
   returns: permissiveReturn,
   handler: async (ctx, args) => {
-    if (!args.projectId && !args.topicId) {
+    if (!(args.projectId || args.topicId)) {
       return [];
     }
     let scope;
@@ -741,10 +1021,11 @@ var findContradictions = query({
   },
   returns: permissiveReturn,
   handler: async (ctx, args) => {
-    const edges = await ctx.db.query("epistemicEdges").withIndex(
-      "by_to_type",
-      (q) => q.eq("toNodeId", args.nodeId).eq("edgeType", "informs")
-    ).collect();
+    const edges = await collectEdgesToNodeRef(
+      ctx,
+      String(args.nodeId),
+      "informs"
+    );
     return edges.filter((e) => (e.weight ?? 0) < 0);
   }
 });
@@ -754,10 +1035,11 @@ var findSupport = query({
   },
   returns: permissiveReturn,
   handler: async (ctx, args) => {
-    const edges = await ctx.db.query("epistemicEdges").withIndex(
-      "by_to_type",
-      (q) => q.eq("toNodeId", args.nodeId).eq("edgeType", "informs")
-    ).collect();
+    const edges = await collectEdgesToNodeRef(
+      ctx,
+      String(args.nodeId),
+      "informs"
+    );
     return edges.filter((e) => (e.weight ?? 0) >= 0);
   }
 });
@@ -780,59 +1062,29 @@ var getLineage = query({
   },
   returns: permissiveReturn,
   handler: async (ctx, args) => {
-    const maxDepth = args.maxDepth ?? 10;
-    const mode = args.mode ?? "anchor_down";
-    const minLayer = args.minLayer ?? getDefaultMinLayer(mode);
-    const maxLayer = args.maxLayer ?? 4;
+    const traversalState = buildLineageTraversalConfig(args);
     const lineage = [];
+    const queue = [];
     const visited = /* @__PURE__ */ new Set();
-    const startNode = await ctx.db.get(args.nodeId);
+    const startNode = readEdgeNodeRow(await ctx.db.get(args.nodeId));
     if (!startNode) {
       return lineage;
     }
-    const startLayer = startNode.epistemicLayer || getNodeLayer(startNode.nodeType);
-    const queue = [{ nodeId: args.nodeId, depth: 0, currentLayer: startLayer }];
+    queue.push(buildLineageQueueSeed(startNode));
     while (queue.length > 0) {
       const current = queue.shift();
-      if (!current || current.depth >= maxDepth) {
-        continue;
-      }
-      const nodeIdStr = current.nodeId.toString();
-      if (visited.has(nodeIdStr)) {
+      if (!current || shouldSkipLineageNode(current, traversalState, visited)) {
         continue;
       }
-      visited.add(nodeIdStr);
-      const edges = await ctx.db.query("epistemicEdges").withIndex("by_from", (q) => q.eq("fromNodeId", current.nodeId)).collect();
-      const lineageEdges = edges.filter((e) => e.edgeType === "derived_from");
-      for (const edge of lineageEdges) {
-        if (!edge.toNodeId) {
-          continue;
-        }
-        const targetNode = await ctx.db.get(edge.toNodeId);
-        if (!targetNode || visited.has(edge.toNodeId.toString())) {
-          continue;
-        }
-        const targetLayer = edge.toLayer || targetNode.epistemicLayer || getNodeLayer(targetNode.nodeType);
-        const shouldContinue = shouldContinueTraversal(
-          current.currentLayer,
-          targetLayer,
-          { mode, minLayer, maxLayer }
-        );
-        if (!shouldContinue) {
-          continue;
-        }
-        lineage.push({
-          node: targetNode,
-          depth: current.depth + 1,
-          edgeType: edge.edgeType,
-          layer: targetLayer
-        });
-        queue.push({
-          nodeId: edge.toNodeId,
-          depth: current.depth + 1,
-          currentLayer: targetLayer
-        });
-      }
+      markVisitedNode(current.node, visited);
+      await appendLineageEdges(
+        ctx,
+        current,
+        traversalState,
+        lineage,
+        queue,
+        visited
+      );
     }
     return lineage;
   }
@@ -843,25 +1095,34 @@ var getEvidenceForBelief = query({
   },
   returns: permissiveReturn,
   handler: async (ctx, args) => {
-    const informsEdges = await ctx.db.query("epistemicEdges").withIndex(
-      "by_to_type",
-      (q) => q.eq("toNodeId", args.beliefNodeId).eq("edgeType", "informs")
-    ).collect();
+    const informsEdges = await collectEdgesToNodeRef(
+      ctx,
+      String(args.beliefNodeId),
+      "informs"
+    );
     const supportEdges = informsEdges.filter((e) => (e.weight ?? 0) >= 0);
     const contradictEdges = informsEdges.filter((e) => (e.weight ?? 0) < 0);
     const supportingEvidence = await Promise.all(
-      supportEdges.map(async (edge) => ({
-        edge,
-        node: await ctx.db.get(edge.fromNodeId)
-      }))
+      supportEdges.map(async (edge) => {
+        const sourceRef = primaryEdgeSourceRef(edge);
+        return {
+          edge,
+          node: sourceRef ? await resolveNodeRefSoft(ctx, sourceRef) : null
+        };
+      })
     );
     const contradictingEvidence = await Promise.all(
-      contradictEdges.map(async (edge) => ({
-        edge,
-        node: await ctx.db.get(edge.fromNodeId)
-      }))
+      contradictEdges.map(async (edge) => {
+        const sourceRef = primaryEdgeSourceRef(edge);
+        return {
+          edge,
+          node: sourceRef ? await resolveNodeRefSoft(ctx, sourceRef) : null
+        };
+      })
+    );
+    const filteredSupporting = supportingEvidence.filter(
+      (e) => e.node !== null
     );
-    const filteredSupporting = supportingEvidence.filter((e) => e.node !== null);
     const filteredContradicting = contradictingEvidence.filter(
       (e) => e.node !== null
     );
@@ -882,11 +1143,22 @@ var getClusterEdges = query({
     if (args.beliefIds.length === 0) {
       return [];
     }
-    const beliefIdSet = new Set(args.beliefIds);
-    const allEdges = await ctx.db.query("epistemicEdges").collect();
+    const beliefIdSet = /* @__PURE__ */ new Set();
+    for (const beliefId of args.beliefIds) {
+      for (const ref of await collectNodeReferenceIds(ctx, beliefId)) {
+        beliefIdSet.add(ref);
+      }
+    }
+    const allEdges = readEdgeRows(
+      await ctx.db.query("epistemicEdges").collect()
+    );
     return allEdges.filter((edge) => {
-      const fromInCluster = beliefIdSet.has(String(edge.fromNodeId)) || edge.sourceGlobalId && beliefIdSet.has(edge.sourceGlobalId);
-      const toInCluster = beliefIdSet.has(String(edge.toNodeId)) || edge.targetGlobalId && beliefIdSet.has(edge.targetGlobalId);
+      const fromInCluster = edgeSourceRefs(edge).some(
+        (ref) => beliefIdSet.has(ref)
+      );
+      const toInCluster = edgeTargetRefs(edge).some(
+        (ref) => beliefIdSet.has(ref)
+      );
       return fromInCluster && toInCluster;
     });
   }