@lucern/graph-primitives 1.0.28 → 1.0.30

package/dist/entityBridge.js

@@ -1,11 +1,15 @@
-import { v } from 'convex/values';
 import { getCurrentUserId } from '@lucern/access-control/auth';
 import { permissiveReturn } from '@lucern/contracts/schema-helpers/validators';
-import { componentsGeneric, anyApi, queryGeneric, mutationGeneric } from 'convex/server';
+import { v } from 'convex/values';
+import { unsafeConvexAnyApi } from '@lucern/contracts/convex/unsafeAnyApi';
+import { componentsGeneric, queryGeneric, mutationGeneric } from 'convex/server';
 
 // src/entityBridge.ts
+var unsafeApi = unsafeConvexAnyApi(
+  "graph-primitives top-level module bundle lacks a committed Convex _generated/api surface"
+);
 componentsGeneric();
-var internal = anyApi;
+var internal = unsafeApi;
 var mutation = mutationGeneric;
 var query = queryGeneric;
 
@@ -46,6 +50,14 @@ function getNodeLayer(nodeType) {
 }
 
 // src/edgeValidation.ts
+var VALID_LAYER_CONNECTIONS = {
+  ontological: /* @__PURE__ */ new Set(["ontological", "L1", "L2", "L3"]),
+  L1: /* @__PURE__ */ new Set(["L1", "L2"]),
+  L2: /* @__PURE__ */ new Set(["L1", "L2", "L3", "ontological"]),
+  L3: /* @__PURE__ */ new Set(["L2", "L3", "L4", "ontological", "organizational"]),
+  L4: /* @__PURE__ */ new Set(["L3", "L4"]),
+  organizational: /* @__PURE__ */ new Set(["organizational", "L3"])
+};
 function getLayerDepth(layer) {
   switch (layer) {
     case "L4":
@@ -63,37 +75,13 @@ function getLayerDepth(layer) {
   }
 }
 function isValidLayerConnection(fromLayer, toLayer) {
-  if (fromLayer === toLayer) {
-    return true;
-  }
-  if (fromLayer === "ontological" && toLayer === "ontological") {
-    return true;
-  }
-  if (fromLayer === "ontological" && (toLayer === "L3" || toLayer === "L2" || toLayer === "L1")) {
-    return true;
-  }
-  if ((fromLayer === "L3" || fromLayer === "L2" || fromLayer === "L1") && toLayer === "ontological") {
-    return true;
-  }
-  if (fromLayer === "L2" && toLayer === "L1") {
-    return true;
-  }
-  if (fromLayer === "L2" && toLayer === "L3") {
-    return true;
-  }
-  if (fromLayer === "L3" && toLayer === "L2") {
-    return true;
-  }
-  if (fromLayer === "L3" && toLayer === "L4") {
-    return true;
-  }
-  if (fromLayer === "L4" && toLayer === "L3") {
-    return true;
+  if (!VALID_LAYER_CONNECTIONS[fromLayer].has(toLayer)) {
+    return false;
   }
-  if (fromLayer === "L3" && toLayer === "organizational") {
+  if (fromLayer === "ontological" || toLayer === "ontological") {
     return true;
   }
-  if (fromLayer === "organizational" && toLayer === "L3") {
+  if (fromLayer === "organizational" || toLayer === "organizational") {
     return true;
   }
   const fromDepth = getLayerDepth(fromLayer);
@@ -232,61 +220,281 @@ var EDGE_LAYER_RULES = {
     to: ["L1", "L2", "L3"],
     description: "Legacy storage migration alias for derived_from; public writes use derived_from"
   },
-  qualifies: { from: ["L2", "L3"], to: ["L3"], description: "Evidence/Belief qualifies a Belief" },
-  contradicts: { from: ["L2", "L3"], to: ["L3"], description: "Evidence/Belief contradicts a Belief" },
-  reinforces: { from: ["L2", "L3"], to: ["L3"], description: "Evidence/Belief reinforces a Belief" },
-  corroborates: { from: ["L2", "L3"], to: ["L3"], description: "Independent evidence/belief corroborates a Belief" },
-  strengthened_by: { from: ["L3"], to: ["L2", "L3"], description: "Belief is strengthened by Evidence/Belief" },
-  weakened_by: { from: ["L3"], to: ["L2", "L3"], description: "Belief is weakened by Evidence/Belief" },
-  validated_by: { from: ["L3"], to: ["L2", "L3"], description: "Belief is validated by Evidence/Belief" },
-  falsified_by: { from: ["L3"], to: ["L2", "L3"], description: "Belief is falsified by Evidence/Belief" },
-  amplifies: { from: ["L3"], to: ["L3"], description: "Belief amplifies another Belief" },
-  precondition_for: { from: ["L3"], to: ["L3"], description: "Belief is a precondition for another Belief" },
-  prerequisite_for: { from: ["L3"], to: ["L3"], description: "Belief is a prerequisite for another Belief" },
-  required_for: { from: ["L3"], to: ["L3"], description: "Belief is required for another Belief" },
-  in_tension_with: { from: ["L3"], to: ["L3"], description: "Belief is in tension with another Belief" },
-  mutually_exclusive: { from: ["L3"], to: ["L3"], description: "Beliefs cannot both hold" },
-  exclusive_with: { from: ["L3"], to: ["L3"], description: "Belief is exclusive with another Belief" },
-  alternative_to: { from: ["L3"], to: ["L3"], description: "Belief is an alternative to another Belief" },
-  subsumes: { from: ["L3"], to: ["L3"], description: "Belief subsumes a narrower Belief" },
-  extends: { from: ["L3"], to: ["L3"], description: "Belief extends another Belief" },
-  refines: { from: ["L3"], to: ["L3"], description: "Belief refines another Belief" },
-  implements: { from: ["L3"], to: ["L3"], description: "Belief implements an abstract Belief" },
-  violates: { from: ["L3"], to: ["L3"], description: "Belief violates a constraint Belief" },
-  assumes: { from: ["L3"], to: ["L3"], description: "Belief assumes another Belief" },
-  would_predict: { from: ["L3"], to: ["L3"], description: "Belief would predict another Belief" },
-  analogous_to: { from: ["L3"], to: ["L3"], description: "Belief is analogous to another Belief" },
-  independent_of: { from: ["L3"], to: ["L3"], description: "Belief is independent of another Belief" },
-  correlates_with: { from: ["L3"], to: ["L3"], description: "Belief correlates with another Belief" },
-  co_changes_with: { from: ["L3"], to: ["L3"], description: "Belief co-changes with another Belief" },
-  counterfactual_of: { from: ["L3"], to: ["L3"], description: "Belief is a counterfactual of another Belief" },
-  parallel_to: { from: ["L3"], to: ["L3"], description: "Belief runs parallel to another Belief" },
-  cascade_from: { from: ["L3"], to: ["L3"], description: "Cascade from an upstream Belief" },
-  cascade_to: { from: ["L3"], to: ["L3"], description: "Cascade to a downstream Belief" },
-  collapses_if: { from: ["L3"], to: ["L3"], description: "Belief collapses if another fails" },
-  branches_from: { from: ["L3"], to: ["L3"], description: "Belief branches from an ancestor Belief" },
-  same_as: { from: ["L2", "L3", "ontological"], to: ["L2", "L3", "ontological"], description: "Two nodes are the same entity" },
-  answers: { from: ["L2", "L3"], to: ["L3"], description: "Answer/Belief answers a Question" },
-  partially_answers: { from: ["L2", "L3"], to: ["L3"], description: "Answer/Belief partially answers a Question" },
-  explores: { from: ["L3"], to: ["L3"], description: "Question explores a Belief/Theme" },
-  informed_by_theme: { from: ["L3"], to: ["L3"], description: "Belief is informed by a Theme" },
-  same_theme_as: { from: ["L3"], to: ["L3"], description: "Two Beliefs share a Theme" },
-  based_on: { from: ["L4"], to: ["L3"], description: "Decision is based on a Belief/Question" },
-  based_on_belief: { from: ["L4"], to: ["L3"], description: "Decision is based on a Belief" },
-  based_on_question: { from: ["L4"], to: ["L3"], description: "Decision is based on a Question" },
-  blocked_by_contradiction: { from: ["L4"], to: ["L3"], description: "Decision is blocked by a Contradiction" },
-  parent_of: { from: ["L3", "L4", "ontological", "organizational"], to: ["L2", "L3", "ontological", "organizational"], description: "A is the parent of B" },
-  child_of: { from: ["L2", "L3", "ontological", "organizational"], to: ["L3", "L4", "ontological", "organizational"], description: "A is the child of B" },
-  scoped_by: { from: ["L2", "L3"], to: ["L3", "organizational"], description: "Object is scoped by a Topic/Theme" },
-  cites: { from: ["L2", "L3"], to: ["L1", "L2"], description: "Evidence/Belief cites a Source/Excerpt" },
-  summarizes: { from: ["L2", "L3"], to: ["L1", "L2"], description: "Synthesis/Evidence summarizes a Source/Evidence" },
-  same_source_as: { from: ["L1", "L2"], to: ["L1", "L2"], description: "Two nodes derive from the same Source" },
-  migrating_from: { from: ["L2", "L3", "L4"], to: ["L1", "L2", "L3"], description: "Migration lineage: from an ancestor" },
-  migrating_to: { from: ["L1", "L2", "L3"], to: ["L2", "L3", "L4"], description: "Migration lineage: to a successor" },
-  about_entity: { from: ["L2", "L3"], to: ["ontological"], description: "Belief/Evidence is about an Entity" },
-  entity_referenced_in: { from: ["ontological"], to: ["L1", "L2"], description: "Entity is referenced in a Source/Evidence" },
-  related_to: { from: ["L2", "L3", "ontological", "organizational"], to: ["L2", "L3", "ontological", "organizational"], description: "Lateral adjacency; no confidence pressure" },
-  blocks: { from: ["L3", "L4"], to: ["L3", "L4"], description: "A blocks B (structural gate)" }
+  qualifies: {
+    from: ["L2", "L3"],
+    to: ["L3"],
+    description: "Evidence/Belief qualifies a Belief"
+  },
+  contradicts: {
+    from: ["L2", "L3"],
+    to: ["L3"],
+    description: "Evidence/Belief contradicts a Belief"
+  },
+  reinforces: {
+    from: ["L2", "L3"],
+    to: ["L3"],
+    description: "Evidence/Belief reinforces a Belief"
+  },
+  corroborates: {
+    from: ["L2", "L3"],
+    to: ["L3"],
+    description: "Independent evidence/belief corroborates a Belief"
+  },
+  strengthened_by: {
+    from: ["L3"],
+    to: ["L2", "L3"],
+    description: "Belief is strengthened by Evidence/Belief"
+  },
+  weakened_by: {
+    from: ["L3"],
+    to: ["L2", "L3"],
+    description: "Belief is weakened by Evidence/Belief"
+  },
+  validated_by: {
+    from: ["L3"],
+    to: ["L2", "L3"],
+    description: "Belief is validated by Evidence/Belief"
+  },
+  falsified_by: {
+    from: ["L3"],
+    to: ["L2", "L3"],
+    description: "Belief is falsified by Evidence/Belief"
+  },
+  amplifies: {
+    from: ["L3"],
+    to: ["L3"],
+    description: "Belief amplifies another Belief"
+  },
+  precondition_for: {
+    from: ["L3"],
+    to: ["L3"],
+    description: "Belief is a precondition for another Belief"
+  },
+  prerequisite_for: {
+    from: ["L3"],
+    to: ["L3"],
+    description: "Belief is a prerequisite for another Belief"
+  },
+  required_for: {
+    from: ["L3"],
+    to: ["L3"],
+    description: "Belief is required for another Belief"
+  },
+  in_tension_with: {
+    from: ["L3"],
+    to: ["L3"],
+    description: "Belief is in tension with another Belief"
+  },
+  mutually_exclusive: {
+    from: ["L3"],
+    to: ["L3"],
+    description: "Beliefs cannot both hold"
+  },
+  exclusive_with: {
+    from: ["L3"],
+    to: ["L3"],
+    description: "Belief is exclusive with another Belief"
+  },
+  alternative_to: {
+    from: ["L3"],
+    to: ["L3"],
+    description: "Belief is an alternative to another Belief"
+  },
+  subsumes: {
+    from: ["L3"],
+    to: ["L3"],
+    description: "Belief subsumes a narrower Belief"
+  },
+  extends: {
+    from: ["L3"],
+    to: ["L3"],
+    description: "Belief extends another Belief"
+  },
+  refines: {
+    from: ["L3"],
+    to: ["L3"],
+    description: "Belief refines another Belief"
+  },
+  implements: {
+    from: ["L3"],
+    to: ["L3"],
+    description: "Belief implements an abstract Belief"
+  },
+  violates: {
+    from: ["L3"],
+    to: ["L3"],
+    description: "Belief violates a constraint Belief"
+  },
+  assumes: {
+    from: ["L3"],
+    to: ["L3"],
+    description: "Belief assumes another Belief"
+  },
+  would_predict: {
+    from: ["L3"],
+    to: ["L3"],
+    description: "Belief would predict another Belief"
+  },
+  analogous_to: {
+    from: ["L3"],
+    to: ["L3"],
+    description: "Belief is analogous to another Belief"
+  },
+  independent_of: {
+    from: ["L3"],
+    to: ["L3"],
+    description: "Belief is independent of another Belief"
+  },
+  correlates_with: {
+    from: ["L3"],
+    to: ["L3"],
+    description: "Belief correlates with another Belief"
+  },
+  co_changes_with: {
+    from: ["L3"],
+    to: ["L3"],
+    description: "Belief co-changes with another Belief"
+  },
+  counterfactual_of: {
+    from: ["L3"],
+    to: ["L3"],
+    description: "Belief is a counterfactual of another Belief"
+  },
+  parallel_to: {
+    from: ["L3"],
+    to: ["L3"],
+    description: "Belief runs parallel to another Belief"
+  },
+  cascade_from: {
+    from: ["L3"],
+    to: ["L3"],
+    description: "Cascade from an upstream Belief"
+  },
+  cascade_to: {
+    from: ["L3"],
+    to: ["L3"],
+    description: "Cascade to a downstream Belief"
+  },
+  collapses_if: {
+    from: ["L3"],
+    to: ["L3"],
+    description: "Belief collapses if another fails"
+  },
+  branches_from: {
+    from: ["L3"],
+    to: ["L3"],
+    description: "Belief branches from an ancestor Belief"
+  },
+  same_as: {
+    from: ["L2", "L3", "ontological"],
+    to: ["L2", "L3", "ontological"],
+    description: "Two nodes are the same entity"
+  },
+  answers: {
+    from: ["L2", "L3"],
+    to: ["L3"],
+    description: "Answer/Belief answers a Question"
+  },
+  partially_answers: {
+    from: ["L2", "L3"],
+    to: ["L3"],
+    description: "Answer/Belief partially answers a Question"
+  },
+  explores: {
+    from: ["L3"],
+    to: ["L3"],
+    description: "Question explores a Belief/Theme"
+  },
+  informed_by_theme: {
+    from: ["L3"],
+    to: ["L3"],
+    description: "Belief is informed by a Theme"
+  },
+  same_theme_as: {
+    from: ["L3"],
+    to: ["L3"],
+    description: "Two Beliefs share a Theme"
+  },
+  based_on: {
+    from: ["L4"],
+    to: ["L3"],
+    description: "Decision is based on a Belief/Question"
+  },
+  based_on_belief: {
+    from: ["L4"],
+    to: ["L3"],
+    description: "Decision is based on a Belief"
+  },
+  based_on_question: {
+    from: ["L4"],
+    to: ["L3"],
+    description: "Decision is based on a Question"
+  },
+  blocked_by_contradiction: {
+    from: ["L4"],
+    to: ["L3"],
+    description: "Decision is blocked by a Contradiction"
+  },
+  parent_of: {
+    from: ["L3", "L4", "ontological", "organizational"],
+    to: ["L2", "L3", "ontological", "organizational"],
+    description: "A is the parent of B"
+  },
+  child_of: {
+    from: ["L2", "L3", "ontological", "organizational"],
+    to: ["L3", "L4", "ontological", "organizational"],
+    description: "A is the child of B"
+  },
+  scoped_by: {
+    from: ["L2", "L3"],
+    to: ["L3", "organizational"],
+    description: "Object is scoped by a Topic/Theme"
+  },
+  cites: {
+    from: ["L2", "L3"],
+    to: ["L1", "L2"],
+    description: "Evidence/Belief cites a Source/Excerpt"
+  },
+  summarizes: {
+    from: ["L2", "L3"],
+    to: ["L1", "L2"],
+    description: "Synthesis/Evidence summarizes a Source/Evidence"
+  },
+  same_source_as: {
+    from: ["L1", "L2"],
+    to: ["L1", "L2"],
+    description: "Two nodes derive from the same Source"
+  },
+  migrating_from: {
+    from: ["L2", "L3", "L4"],
+    to: ["L1", "L2", "L3"],
+    description: "Migration lineage: from an ancestor"
+  },
+  migrating_to: {
+    from: ["L1", "L2", "L3"],
+    to: ["L2", "L3", "L4"],
+    description: "Migration lineage: to a successor"
+  },
+  about_entity: {
+    from: ["L2", "L3"],
+    to: ["ontological"],
+    description: "Belief/Evidence is about an Entity"
+  },
+  entity_referenced_in: {
+    from: ["ontological"],
+    to: ["L1", "L2"],
+    description: "Entity is referenced in a Source/Evidence"
+  },
+  related_to: {
+    from: ["L2", "L3", "ontological", "organizational"],
+    to: ["L2", "L3", "ontological", "organizational"],
+    description: "Lateral adjacency; no confidence pressure"
+  },
+  blocks: {
+    from: ["L3", "L4"],
+    to: ["L3", "L4"],
+    description: "A blocks B (structural gate)"
+  }
 };
 function validateEdgeLayers(edgeType, fromLayer, toLayer) {
   const rules = EDGE_LAYER_RULES[edgeType];
@@ -346,6 +554,252 @@ var ENTITY_BRIDGE_EDGE_TYPES = [
   "impacts",
   "mentioned_in"
 ];
+var ENTITY_BRIDGE_EDGE_TYPE_SET = new Set(ENTITY_BRIDGE_EDGE_TYPES);
+function isRecord(value) {
+  return Boolean(value) && typeof value === "object" && !Array.isArray(value);
+}
+function readConvexId(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 readOptionalString(value) {
+  return typeof value === "string" && value.trim().length > 0 ? value : void 0;
+}
+function readRecord(value) {
+  return isRecord(value) ? value : void 0;
+}
+function readBridgeEdge(value) {
+  if (!isRecord(value)) {
+    return null;
+  }
+  const edgeType = readOptionalString(value.edgeType);
+  if (!edgeType) {
+    return null;
+  }
+  const edge = { edgeType };
+  const context = readOptionalString(value.context);
+  const fromNodeId = readConvexId(value.fromNodeId);
+  const toNodeId = readConvexId(value.toNodeId);
+  const weight = readOptionalNumber(value.weight);
+  if (context !== void 0) {
+    edge.context = context;
+  }
+  if (fromNodeId !== void 0) {
+    edge.fromNodeId = fromNodeId;
+  }
+  if (toNodeId !== void 0) {
+    edge.toNodeId = toNodeId;
+  }
+  if (weight !== void 0) {
+    edge.weight = weight;
+  }
+  return edge;
+}
+function readBridgeNode(value) {
+  if (!isRecord(value)) {
+    return null;
+  }
+  const id = readConvexId(value._id);
+  if (!id) {
+    return null;
+  }
+  const node = { ...value, _id: id };
+  const canonicalText = readOptionalString(value.canonicalText);
+  const epistemicLayer = readOptionalString(value.epistemicLayer);
+  const globalId = readOptionalString(value.globalId);
+  const metadata = readRecord(value.metadata);
+  const nodeType = readOptionalString(value.nodeType);
+  const projectId = readOptionalString(value.projectId);
+  const status = readOptionalString(value.status);
+  const title = readOptionalString(value.title);
+  const topicId = readOptionalString(value.topicId);
+  if (canonicalText !== void 0) {
+    node.canonicalText = canonicalText;
+  }
+  if (epistemicLayer !== void 0) {
+    node.epistemicLayer = epistemicLayer;
+  }
+  if (globalId !== void 0) {
+    node.globalId = globalId;
+  }
+  if (metadata !== void 0) {
+    node.metadata = metadata;
+  }
+  if (nodeType !== void 0) {
+    node.nodeType = nodeType;
+  }
+  if (projectId !== void 0) {
+    node.projectId = projectId;
+  }
+  if (status !== void 0) {
+    node.status = status;
+  }
+  if (title !== void 0) {
+    node.title = title;
+  }
+  if (topicId !== void 0) {
+    node.topicId = topicId;
+  }
+  return node;
+}
+function readRowList(values, reader) {
+  return values.flatMap((value) => {
+    const row = reader(value);
+    return row ? [row] : [];
+  });
+}
+function readTopicScopeNode(value) {
+  return readBridgeNode(value);
+}
+function isEntityScopeBridgeEdge(edgeType) {
+  if (!edgeType) {
+    return false;
+  }
+  return ENTITY_BRIDGE_EDGE_TYPE_SET.has(edgeType);
+}
+async function queryEdgesByTarget(ctx, nodeId) {
+  return readRowList(
+    await ctx.db.query("epistemicEdges").withIndex("by_to", (q) => q.eq("toNodeId", nodeId)).collect(),
+    readBridgeEdge
+  );
+}
+async function queryEdgesBySource(ctx, nodeId) {
+  return readRowList(
+    await ctx.db.query("epistemicEdges").withIndex("by_from", (q) => q.eq("fromNodeId", nodeId)).collect(),
+    readBridgeEdge
+  );
+}
+async function readNodeById(ctx, nodeId) {
+  return readBridgeNode(await ctx.db.get(nodeId));
+}
+async function readNodeByIdForMutation(ctx, nodeId) {
+  return readBridgeNode(await ctx.db.get(nodeId));
+}
+function collectConnectedEntityNodeIds(connectedNodeIds, edges, mapFromInbound) {
+  for (const edge of edges) {
+    if (!isEntityScopeBridgeEdge(edge.edgeType)) {
+      continue;
+    }
+    const nextId = mapFromInbound ? edge.fromNodeId : edge.toNodeId;
+    if (!nextId) {
+      continue;
+    }
+    connectedNodeIds.add(String(nextId));
+  }
+}
+async function collectEntityTopicContextIds(ctx, connectedNodeIds) {
+  const topicIds = /* @__PURE__ */ new Set();
+  const projectIds = /* @__PURE__ */ new Set();
+  for (const nodeId of connectedNodeIds) {
+    const node = readTopicScopeNode(
+      await ctx.db.get(nodeId)
+    );
+    if (node?.status !== "active") {
+      continue;
+    }
+    if (node.projectId) {
+      projectIds.add(String(node.projectId));
+    }
+    if (node.topicId) {
+      topicIds.add(String(node.topicId));
+    }
+  }
+  return { topicIds, projectIds };
+}
+async function collectScopedTopicIdsFromConnectedNodes(ctx, connectedNodeIds) {
+  const scopedTopicIds = await Promise.all(
+    [...connectedNodeIds].map(async (nodeId) => {
+      const scopeEdges = await queryEdgesBySource(
+        ctx,
+        nodeId
+      );
+      const mappedTopicIds = scopeEdges.map(async (edge) => {
+        if (edge.edgeType !== "contains" || !edge.toNodeId) {
+          return;
+        }
+        const scopedTopicNode = readTopicScopeNode(
+          await ctx.db.get(edge.toNodeId)
+        );
+        const canonicalTopicId = readMaterializedTopicTableId(scopedTopicNode);
+        if (!canonicalTopicId) {
+          return;
+        }
+        return String(canonicalTopicId);
+      });
+      return Promise.all(mappedTopicIds);
+    })
+  );
+  return scopedTopicIds.flat().filter((topicId) => Boolean(topicId));
+}
+function buildEntityBeliefEdgeDirection(args, entity, belief) {
+  const { edgeType, entityNodeId, beliefNodeId } = args;
+  const effectiveEdgeType = edgeType || "contains";
+  const entityLayer = getNodeLayer(entity.nodeType);
+  const beliefLayer = getNodeLayer(belief.nodeType);
+  if (effectiveEdgeType === "contains" && entity.epistemicLayer === "ontological") {
+    return {
+      fromNodeId: beliefNodeId,
+      toNodeId: entityNodeId,
+      fromGlobalId: belief.globalId,
+      toGlobalId: entity.globalId,
+      fromNodeType: belief.nodeType,
+      toNodeType: entity.nodeType,
+      edgeFromLayer: beliefLayer,
+      edgeToLayer: "ontological"
+    };
+  }
+  if (effectiveEdgeType === "mentioned_in" || effectiveEdgeType === "perspective_on") {
+    return {
+      fromNodeId: entityNodeId,
+      toNodeId: beliefNodeId,
+      fromGlobalId: entity.globalId,
+      toGlobalId: belief.globalId,
+      fromNodeType: entity.nodeType,
+      toNodeType: belief.nodeType,
+      edgeFromLayer: "ontological",
+      edgeToLayer: beliefLayer
+    };
+  }
+  const directValidation = validateEdgeLayers(
+    effectiveEdgeType,
+    entityLayer,
+    beliefLayer
+  );
+  if (directValidation.valid) {
+    return {
+      fromNodeId: entityNodeId,
+      toNodeId: beliefNodeId,
+      fromGlobalId: entity.globalId,
+      toGlobalId: belief.globalId,
+      fromNodeType: entity.nodeType,
+      toNodeType: belief.nodeType,
+      edgeFromLayer: entityLayer,
+      edgeToLayer: beliefLayer
+    };
+  }
+  const reversedValidation = validateEdgeLayers(
+    effectiveEdgeType,
+    beliefLayer,
+    entityLayer
+  );
+  if (!reversedValidation.valid) {
+    throw new Error(
+      `Edge type '${effectiveEdgeType}' is not valid between ${entity.nodeType} (${entityLayer}) and ${belief.nodeType} (${beliefLayer}): ${directValidation.reason}`
+    );
+  }
+  return {
+    fromNodeId: beliefNodeId,
+    toNodeId: entityNodeId,
+    fromGlobalId: belief.globalId,
+    toGlobalId: entity.globalId,
+    fromNodeType: belief.nodeType,
+    toNodeType: entity.nodeType,
+    edgeFromLayer: beliefLayer,
+    edgeToLayer: entityLayer
+  };
+}
 var getBeliefsForEntity = query({
   args: {
     entityNodeId: v.id("epistemicNodes"),
@@ -353,8 +807,8 @@ var getBeliefsForEntity = query({
   },
   returns: permissiveReturn,
   handler: async (ctx, args) => {
-    const entity = await ctx.db.get(args.entityNodeId);
-    if (!entity || entity.epistemicLayer !== "ontological") {
+    const entity = await readNodeById(ctx, args.entityNodeId);
+    if (entity?.epistemicLayer !== "ontological") {
       return { beliefs: [], entity: null };
     }
     const filterTypes = args.edgeTypes || [
@@ -363,12 +817,12 @@ var getBeliefsForEntity = query({
       "perspective_on",
       "impacts"
     ];
-    const inboundEdges = await ctx.db.query("epistemicEdges").withIndex("by_to", (q) => q.eq("toNodeId", args.entityNodeId)).collect();
-    const outboundEdges = await ctx.db.query("epistemicEdges").withIndex("by_from", (q) => q.eq("fromNodeId", args.entityNodeId)).collect();
+    const inboundEdges = await queryEdgesByTarget(ctx, args.entityNodeId);
+    const outboundEdges = await queryEdgesBySource(ctx, args.entityNodeId);
     const beliefNodeIds = /* @__PURE__ */ new Set();
     const edgeMap = {};
     for (const edge of inboundEdges) {
-      if (!filterTypes.includes(edge.edgeType) || !edge.fromNodeId) {
+      if (!(filterTypes.includes(edge.edgeType) && edge.fromNodeId)) {
         continue;
       }
       const id = String(edge.fromNodeId);
@@ -381,7 +835,7 @@ var getBeliefsForEntity = query({
     }
     for (const edge of outboundEdges) {
       const et = edge.edgeType;
-      if (!filterTypes.includes(et) || !edge.toNodeId || et === "mentioned_in") {
+      if (!(filterTypes.includes(et) && edge.toNodeId) || et === "mentioned_in") {
         continue;
       }
       const id = String(edge.toNodeId);
@@ -394,8 +848,8 @@ var getBeliefsForEntity = query({
     }
     const beliefs = await Promise.all(
       [...beliefNodeIds].map(async (nodeId) => {
-        const node = await ctx.db.get(nodeId);
-        if (!node || node.status !== "active") {
+        const node = await readNodeById(ctx, nodeId);
+        if (node?.status !== "active") {
           return null;
         }
         return {
@@ -423,7 +877,7 @@ var getEntitiesForBelief = query({
   },
   returns: permissiveReturn,
   handler: async (ctx, args) => {
-    const belief = await ctx.db.get(args.beliefNodeId);
+    const belief = await readNodeById(ctx, args.beliefNodeId);
     if (!belief) {
       return { entities: [], belief: null };
     }
@@ -433,12 +887,12 @@ var getEntitiesForBelief = query({
       "perspective_on",
       "impacts"
     ];
-    const outboundEdges = await ctx.db.query("epistemicEdges").withIndex("by_from", (q) => q.eq("fromNodeId", args.beliefNodeId)).collect();
-    const inboundEdges = await ctx.db.query("epistemicEdges").withIndex("by_to", (q) => q.eq("toNodeId", args.beliefNodeId)).collect();
+    const outboundEdges = await queryEdgesBySource(ctx, args.beliefNodeId);
+    const inboundEdges = await queryEdgesByTarget(ctx, args.beliefNodeId);
     const entityNodeIds = /* @__PURE__ */ new Set();
     const edgeMap = {};
     for (const edge of outboundEdges) {
-      if (!filterTypes.includes(edge.edgeType) || !edge.toNodeId) {
+      if (!(filterTypes.includes(edge.edgeType) && edge.toNodeId)) {
         continue;
       }
       const id = String(edge.toNodeId);
@@ -450,7 +904,7 @@ var getEntitiesForBelief = query({
       };
     }
     for (const edge of inboundEdges) {
-      if (!filterTypes.includes(edge.edgeType) || !edge.fromNodeId) {
+      if (!(filterTypes.includes(edge.edgeType) && edge.fromNodeId)) {
         continue;
       }
       const id = String(edge.fromNodeId);
@@ -463,8 +917,8 @@ var getEntitiesForBelief = query({
     }
     const entities = await Promise.all(
       [...entityNodeIds].map(async (nodeId) => {
-        const node = await ctx.db.get(nodeId);
-        if (!node || node.status !== "active" || node.epistemicLayer !== "ontological") {
+        const node = await readNodeById(ctx, nodeId);
+        if (node?.status !== "active" || node.epistemicLayer !== "ontological") {
           return null;
         }
         return {
@@ -491,59 +945,27 @@ var getEntityTopicScope = query({
   },
   returns: permissiveReturn,
   handler: async (ctx, args) => {
-    const entity = await ctx.db.get(args.entityNodeId);
-    if (!entity || entity.epistemicLayer !== "ontological") {
+    const entity = await readNodeById(ctx, args.entityNodeId);
+    if (entity?.epistemicLayer !== "ontological") {
       return { topics: [], projectIds: [] };
     }
-    const inboundEdges = await ctx.db.query("epistemicEdges").withIndex("by_to", (q) => q.eq("toNodeId", args.entityNodeId)).collect();
-    const outboundEdges = await ctx.db.query("epistemicEdges").withIndex("by_from", (q) => q.eq("fromNodeId", args.entityNodeId)).collect();
+    const [inboundEdges, outboundEdges] = await Promise.all([
+      queryEdgesByTarget(ctx, args.entityNodeId),
+      queryEdgesBySource(ctx, args.entityNodeId)
+    ]);
     const connectedNodeIds = /* @__PURE__ */ new Set();
-    for (const edge of inboundEdges) {
-      if (ENTITY_BRIDGE_EDGE_TYPES.includes(
-        edge.edgeType
-      ) && edge.fromNodeId) {
-        connectedNodeIds.add(String(edge.fromNodeId));
-      }
-    }
-    for (const edge of outboundEdges) {
-      if (ENTITY_BRIDGE_EDGE_TYPES.includes(
-        edge.edgeType
-      ) && edge.toNodeId) {
-        connectedNodeIds.add(String(edge.toNodeId));
-      }
-    }
-    const projectIds = /* @__PURE__ */ new Set();
-    const topicIds = /* @__PURE__ */ new Set();
-    for (const nodeId of connectedNodeIds) {
-      const node = await ctx.db.get(nodeId);
-      if (!node || node.status !== "active") {
-        continue;
-      }
-      if (node.projectId) {
-        projectIds.add(String(node.projectId));
-      }
-      if (node.topicId) {
-        topicIds.add(String(node.topicId));
-      }
-    }
-    for (const nodeId of connectedNodeIds) {
-      const scopeEdges = await ctx.db.query("epistemicEdges").withIndex(
-        "by_from",
-        (q) => q.eq("fromNodeId", nodeId)
-      ).collect();
-      for (const edge of scopeEdges) {
-        if (edge.edgeType === "contains" && edge.toNodeId) {
-          const scopedTopicNode = await ctx.db.get(
-            edge.toNodeId
-          );
-          const canonicalTopicId = readMaterializedTopicTableId(
-            scopedTopicNode
-          );
-          if (canonicalTopicId) {
-            topicIds.add(canonicalTopicId);
-          }
-        }
-      }
+    collectConnectedEntityNodeIds(connectedNodeIds, inboundEdges, true);
+    collectConnectedEntityNodeIds(connectedNodeIds, outboundEdges, false);
+    const { topicIds, projectIds } = await collectEntityTopicContextIds(
+      ctx,
+      connectedNodeIds
+    );
+    const inferredTopicIds = await collectScopedTopicIdsFromConnectedNodes(
+      ctx,
+      connectedNodeIds
+    );
+    for (const topicId of inferredTopicIds) {
+      topicIds.add(topicId);
     }
     return {
       topics: [...topicIds],
@@ -559,15 +981,12 @@ var getEvidenceForEntity = query({
   },
   returns: permissiveReturn,
   handler: async (ctx, args) => {
-    const entity = await ctx.db.get(args.entityNodeId);
-    if (!entity || entity.epistemicLayer !== "ontological") {
+    const entity = await readNodeById(ctx, args.entityNodeId);
+    if (entity?.epistemicLayer !== "ontological") {
       return [];
     }
     const effectiveLimit = args.limit ?? 50;
-    const outboundEdges = await ctx.db.query("epistemicEdges").withIndex(
-      "by_from",
-      (q) => q.eq("fromNodeId", args.entityNodeId)
-    ).collect();
+    const outboundEdges = await queryEdgesBySource(ctx, args.entityNodeId);
     const evidenceEdges = outboundEdges.filter((e) => {
       const et = e.edgeType;
       return et === "contains" || et === "mentioned_in";
@@ -577,8 +996,8 @@ var getEvidenceForEntity = query({
         if (!edge.toNodeId) {
           return null;
         }
-        const node = await ctx.db.get(edge.toNodeId);
-        if (!node || node.status !== "active") {
+        const node = await readNodeById(ctx, edge.toNodeId);
+        if (node?.status !== "active") {
           return null;
         }
         return {
@@ -608,11 +1027,11 @@ var linkEntityToBelief = mutation({
     if (!userId) {
       throw new Error("Authentication required to create entity-belief links.");
     }
-    const entity = await ctx.db.get(args.entityNodeId);
-    if (!entity || entity.epistemicLayer !== "ontological") {
+    const entity = await readNodeByIdForMutation(ctx, args.entityNodeId);
+    if (entity?.epistemicLayer !== "ontological") {
       throw new Error("Source node must be an ontological entity.");
     }
-    const belief = await ctx.db.get(args.beliefNodeId);
+    const belief = await readNodeByIdForMutation(ctx, args.beliefNodeId);
     if (!belief) {
       throw new Error("Target belief/question/theme node not found.");
     }
@@ -624,71 +1043,29 @@ var linkEntityToBelief = mutation({
         "Target belief/question/theme node is missing a globalId."
       );
     }
-    const effectiveEdgeType = args.edgeType || "contains";
-    const fromLayer = getNodeLayer(entity.nodeType);
-    const toLayer = getNodeLayer(belief.nodeType);
-    let fromNodeId;
-    let toNodeId;
-    let fromGlobalId;
-    let toGlobalId;
-    let fromNodeType;
-    let toNodeType;
-    let edgeFromLayer;
-    let edgeToLayer;
-    if (effectiveEdgeType === "contains" && entity.epistemicLayer === "ontological") {
-      fromNodeId = args.beliefNodeId;
-      toNodeId = args.entityNodeId;
-      fromGlobalId = belief.globalId;
-      toGlobalId = entity.globalId;
-      fromNodeType = belief.nodeType;
-      toNodeType = entity.nodeType;
-      edgeFromLayer = getNodeLayer(belief.nodeType);
-      edgeToLayer = "ontological";
-    } else if (effectiveEdgeType === "mentioned_in" || effectiveEdgeType === "perspective_on") {
-      fromNodeId = args.entityNodeId;
-      toNodeId = args.beliefNodeId;
-      fromGlobalId = entity.globalId;
-      toGlobalId = belief.globalId;
-      fromNodeType = entity.nodeType;
-      toNodeType = belief.nodeType;
-      edgeFromLayer = "ontological";
-      edgeToLayer = getNodeLayer(belief.nodeType);
-    } else {
-      const validation = validateEdgeLayers(
-        effectiveEdgeType,
-        fromLayer,
-        toLayer
+    if (!entity.nodeType) {
+      throw new Error("Source entity is missing a nodeType.");
+    }
+    if (!belief.nodeType) {
+      throw new Error(
+        "Target belief/question/theme node is missing a nodeType."
       );
-      if (validation.valid) {
-        fromNodeId = args.entityNodeId;
-        toNodeId = args.beliefNodeId;
-        fromGlobalId = entity.globalId;
-        toGlobalId = belief.globalId;
-        fromNodeType = entity.nodeType;
-        toNodeType = belief.nodeType;
-        edgeFromLayer = fromLayer;
-        edgeToLayer = toLayer;
-      } else {
-        const reversed = validateEdgeLayers(
-          effectiveEdgeType,
-          toLayer,
-          fromLayer
-        );
-        if (!reversed.valid) {
-          throw new Error(
-            `Edge type '${effectiveEdgeType}' is not valid between ${entity.nodeType} (${fromLayer}) and ${belief.nodeType} (${toLayer}): ${validation.reason}`
-          );
-        }
-        fromNodeId = args.beliefNodeId;
-        toNodeId = args.entityNodeId;
-        fromGlobalId = belief.globalId;
-        toGlobalId = entity.globalId;
-        fromNodeType = belief.nodeType;
-        toNodeType = entity.nodeType;
-        edgeFromLayer = toLayer;
-        edgeToLayer = fromLayer;
-      }
     }
+    const edgeDirection = buildEntityBeliefEdgeDirection(
+      args,
+      {
+        nodeType: entity.nodeType,
+        globalId: entity.globalId,
+        epistemicLayer: entity.epistemicLayer
+      },
+      {
+        nodeType: belief.nodeType,
+        globalId: belief.globalId
+      }
+    );
+    const { fromNodeId, toNodeId, fromGlobalId, toGlobalId } = edgeDirection;
+    const { fromNodeType, toNodeType, edgeFromLayer, edgeToLayer } = edgeDirection;
+    const effectiveEdgeType = args.edgeType || "contains";
     const existing = await ctx.db.query("epistemicEdges").withIndex(
       "by_from_to",
       (q) => q.eq("fromNodeId", fromNodeId).eq("toNodeId", toNodeId)