@lucern/graph-primitives 0.1.0-alpha.2

package/dist/entityBridge.js

@@ -0,0 +1,663 @@
+import { v } from 'convex/values';
+import { componentsGeneric, queryGeneric, mutationGeneric, anyApi } from 'convex/server';
+
+// src/entityBridge.ts
+
+// ../access-control/src/auth.ts
+async function getCurrentUserId(ctx) {
+  const identity = await ctx.auth.getUserIdentity();
+  return identity?.subject ?? null;
+}
+var permissiveReturn = v.optional(v.any());
+var looseJsonObject = v.record(v.string(), v.any());
+var looseJsonArray = v.array(v.any());
+v.union(
+  v.string(),
+  v.number(),
+  v.boolean(),
+  v.null(),
+  looseJsonObject,
+  looseJsonArray
+);
+componentsGeneric();
+var internal = anyApi;
+var mutation = mutationGeneric;
+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 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 (fromLayer === "L3" && toLayer === "organizational") {
+    return true;
+  }
+  if (fromLayer === "organizational" && toLayer === "L3") {
+    return true;
+  }
+  const fromDepth = getLayerDepth(fromLayer);
+  const toDepth = getLayerDepth(toLayer);
+  if (Math.abs(fromDepth - toDepth) > 1) {
+    return false;
+  }
+  return true;
+}
+var EDGE_LAYER_RULES = {
+  // === 6 Canonical Epistemic Types ===
+  supports: {
+    from: ["L3"],
+    to: ["L3"],
+    description: "Belief bears on Belief (weight: +1 supports, -1 contradicts)"
+  },
+  informs: {
+    from: ["L2"],
+    to: ["L3"],
+    description: "Evidence -> Belief (L2 -> L3)"
+  },
+  depends_on: {
+    from: ["L3"],
+    to: ["L3"],
+    description: "Belief B requires Belief A (structural gate)"
+  },
+  derived_from: {
+    from: ["L2", "L3", "L4"],
+    to: ["L1", "L2", "L3"],
+    description: "A was produced from B (provenance chain)"
+  },
+  contains: {
+    from: ["L3", "L4", "ontological"],
+    to: ["L2", "L3", "ontological"],
+    description: "A scopes/aggregates B (hierarchy)"
+  },
+  tests: {
+    from: ["L3"],
+    to: ["L3"],
+    description: "Question -> Belief (L3 -> L3)"
+  },
+  // === Structural / Lifecycle ===
+  supersedes: {
+    from: ["L3"],
+    to: ["L3"],
+    description: "NewNode -> OldNode (fork lineage)"
+  },
+  responds_to: {
+    from: ["L2", "L3"],
+    to: ["L3"],
+    description: "Answer -> Question (L2/L3 -> L3)"
+  },
+  belongs_to: {
+    from: ["L2", "L3", "ontological"],
+    to: ["L3"],
+    description: "Membership (migrating to contains)"
+  },
+  relates_to_thesis: {
+    from: ["L3"],
+    to: ["L3"],
+    description: "Belief -> Theme (L3 -> L3)"
+  },
+  // === Ontological (entity-entity or entity-epistemic bridge) ===
+  works_at: {
+    from: ["ontological"],
+    to: ["ontological"],
+    description: "Person -> Company"
+  },
+  invested_in: {
+    from: ["ontological"],
+    to: ["ontological"],
+    description: "Investor -> Company"
+  },
+  competes_with: {
+    from: ["ontological"],
+    to: ["ontological"],
+    description: "Company -> Company"
+  },
+  participates_in: {
+    from: ["ontological"],
+    to: ["ontological"],
+    description: "Company -> ValueChain"
+  },
+  founded_by: {
+    from: ["ontological"],
+    to: ["ontological"],
+    description: "Company -> Person"
+  },
+  evaluates: {
+    from: ["ontological"],
+    to: ["ontological"],
+    description: "Deal -> Company"
+  },
+  performs: {
+    from: ["ontological"],
+    to: ["ontological"],
+    description: "Company -> Function"
+  },
+  function_in: {
+    from: ["ontological"],
+    to: ["ontological"],
+    description: "Function -> ValueChain"
+  },
+  impacts: {
+    from: ["ontological", "L3"],
+    to: ["ontological"],
+    description: "Theme/Entity -> ValueChain"
+  },
+  raised_from: {
+    from: ["ontological"],
+    to: ["ontological"],
+    description: "Company -> Investor"
+  },
+  mentioned_in: {
+    from: ["ontological"],
+    to: ["L1", "L2"],
+    description: "Entity -> Source/Evidence"
+  },
+  perspective_on: {
+    from: ["ontological"],
+    to: ["L3"],
+    description: "Person -> Belief/Theme"
+  },
+  plays_theme: {
+    from: ["ontological"],
+    to: ["L3"],
+    description: "Deal -> Theme"
+  }
+};
+function validateEdgeLayers(edgeType, fromLayer, toLayer) {
+  const rules = EDGE_LAYER_RULES[edgeType];
+  if (!rules) {
+    console.warn(
+      `[EdgeValidation] Unknown edge type: ${edgeType}, allowing by default`
+    );
+    return { valid: true };
+  }
+  if (edgeType === "supersedes") {
+    if (fromLayer !== toLayer) {
+      return {
+        valid: false,
+        reason: `${edgeType} edges must be between nodes of the same layer. Got ${fromLayer} -> ${toLayer}`
+      };
+    }
+    return { valid: true };
+  }
+  if (!rules.from.includes(fromLayer)) {
+    return {
+      valid: false,
+      reason: `Edge type '${edgeType}' does not allow source layer ${fromLayer}. Allowed: ${rules.from.join(", ")}`
+    };
+  }
+  if (!rules.to.includes(toLayer)) {
+    return {
+      valid: false,
+      reason: `Edge type '${edgeType}' does not allow target layer ${toLayer}. Allowed: ${rules.to.join(", ")}`
+    };
+  }
+  if (!isValidLayerConnection(fromLayer, toLayer)) {
+    return {
+      valid: false,
+      reason: `Layer transition ${fromLayer} -> ${toLayer} is not permitted`
+    };
+  }
+  return { valid: true };
+}
+function readMaterializedTopicTableId(topicNode) {
+  if (!topicNode) {
+    return;
+  }
+  const metadata = topicNode.metadata || {};
+  const topicTableId = metadata.topicTableId || metadata.topicId;
+  return typeof topicTableId === "string" && topicTableId.trim().length > 0 ? topicTableId.trim() : void 0;
+}
+({
+  projectId: v.optional(v.string()),
+  topicId: v.optional(v.string())
+});
+
+// src/entityBridge.ts
+var ENTITY_BRIDGE_EDGE_TYPES = [
+  "contains",
+  "evaluates",
+  "perspective_on",
+  "impacts",
+  "mentioned_in"
+];
+var getBeliefsForEntity = query({
+  args: {
+    entityNodeId: v.id("epistemicNodes"),
+    edgeTypes: v.optional(v.array(v.string()))
+  },
+  returns: permissiveReturn,
+  handler: async (ctx, args) => {
+    const entity = await ctx.db.get(args.entityNodeId);
+    if (!entity || entity.epistemicLayer !== "ontological") {
+      return { beliefs: [], entity: null };
+    }
+    const filterTypes = args.edgeTypes || [
+      "contains",
+      "evaluates",
+      "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 beliefNodeIds = /* @__PURE__ */ new Set();
+    const edgeMap = {};
+    for (const edge of inboundEdges) {
+      if (!filterTypes.includes(edge.edgeType) || !edge.fromNodeId) {
+        continue;
+      }
+      const id = String(edge.fromNodeId);
+      beliefNodeIds.add(id);
+      edgeMap[id] = {
+        edgeType: edge.edgeType,
+        weight: edge.weight ?? void 0,
+        context: edge.context ?? void 0
+      };
+    }
+    for (const edge of outboundEdges) {
+      const et = edge.edgeType;
+      if (!filterTypes.includes(et) || !edge.toNodeId || et === "mentioned_in") {
+        continue;
+      }
+      const id = String(edge.toNodeId);
+      beliefNodeIds.add(id);
+      edgeMap[id] = {
+        edgeType: edge.edgeType,
+        weight: edge.weight ?? void 0,
+        context: edge.context ?? void 0
+      };
+    }
+    const beliefs = await Promise.all(
+      [...beliefNodeIds].map(async (nodeId) => {
+        const node = await ctx.db.get(nodeId);
+        if (!node || node.status !== "active") {
+          return null;
+        }
+        return {
+          ...node,
+          _edge: edgeMap[nodeId]
+        };
+      })
+    );
+    return {
+      beliefs: beliefs.filter(Boolean),
+      entity: {
+        _id: entity._id,
+        globalId: entity.globalId,
+        nodeType: entity.nodeType,
+        title: entity.title,
+        metadata: entity.metadata
+      }
+    };
+  }
+});
+var getEntitiesForBelief = query({
+  args: {
+    beliefNodeId: v.id("epistemicNodes"),
+    edgeTypes: v.optional(v.array(v.string()))
+  },
+  returns: permissiveReturn,
+  handler: async (ctx, args) => {
+    const belief = await ctx.db.get(args.beliefNodeId);
+    if (!belief) {
+      return { entities: [], belief: null };
+    }
+    const filterTypes = args.edgeTypes || [
+      "contains",
+      "evaluates",
+      "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 entityNodeIds = /* @__PURE__ */ new Set();
+    const edgeMap = {};
+    for (const edge of outboundEdges) {
+      if (!filterTypes.includes(edge.edgeType) || !edge.toNodeId) {
+        continue;
+      }
+      const id = String(edge.toNodeId);
+      entityNodeIds.add(id);
+      edgeMap[id] = {
+        edgeType: edge.edgeType,
+        weight: edge.weight ?? void 0,
+        context: edge.context ?? void 0
+      };
+    }
+    for (const edge of inboundEdges) {
+      if (!filterTypes.includes(edge.edgeType) || !edge.fromNodeId) {
+        continue;
+      }
+      const id = String(edge.fromNodeId);
+      entityNodeIds.add(id);
+      edgeMap[id] = {
+        edgeType: edge.edgeType,
+        weight: edge.weight ?? void 0,
+        context: edge.context ?? void 0
+      };
+    }
+    const entities = await Promise.all(
+      [...entityNodeIds].map(async (nodeId) => {
+        const node = await ctx.db.get(nodeId);
+        if (!node || node.status !== "active" || node.epistemicLayer !== "ontological") {
+          return null;
+        }
+        return {
+          ...node,
+          _edge: edgeMap[nodeId]
+        };
+      })
+    );
+    return {
+      entities: entities.filter(Boolean),
+      belief: {
+        _id: belief._id,
+        globalId: belief.globalId,
+        nodeType: belief.nodeType,
+        title: belief.title,
+        canonicalText: belief.canonicalText
+      }
+    };
+  }
+});
+var getEntityTopicScope = query({
+  args: {
+    entityNodeId: v.id("epistemicNodes")
+  },
+  returns: permissiveReturn,
+  handler: async (ctx, args) => {
+    const entity = await ctx.db.get(args.entityNodeId);
+    if (!entity || 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 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);
+          }
+        }
+      }
+    }
+    return {
+      topics: [...topicIds],
+      projectIds: [...projectIds],
+      connectedNodeCount: connectedNodeIds.size
+    };
+  }
+});
+var getEvidenceForEntity = query({
+  args: {
+    entityNodeId: v.id("epistemicNodes"),
+    limit: v.optional(v.number())
+  },
+  returns: permissiveReturn,
+  handler: async (ctx, args) => {
+    const entity = await ctx.db.get(args.entityNodeId);
+    if (!entity || 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 evidenceEdges = outboundEdges.filter((e) => {
+      const et = e.edgeType;
+      return et === "contains" || et === "mentioned_in";
+    });
+    const results = await Promise.all(
+      evidenceEdges.slice(0, effectiveLimit).map(async (edge) => {
+        if (!edge.toNodeId) {
+          return null;
+        }
+        const node = await ctx.db.get(edge.toNodeId);
+        if (!node || node.status !== "active") {
+          return null;
+        }
+        return {
+          ...node,
+          _edge: {
+            edgeType: edge.edgeType,
+            weight: edge.weight,
+            context: edge.context
+          }
+        };
+      })
+    );
+    return results.filter(Boolean);
+  }
+});
+var linkEntityToBelief = mutation({
+  args: {
+    entityNodeId: v.id("epistemicNodes"),
+    beliefNodeId: v.id("epistemicNodes"),
+    edgeType: v.optional(v.string()),
+    weight: v.optional(v.number()),
+    context: v.optional(v.string())
+  },
+  returns: permissiveReturn,
+  handler: async (ctx, args) => {
+    const userId = await getCurrentUserId(ctx);
+    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") {
+      throw new Error("Source node must be an ontological entity.");
+    }
+    const belief = await ctx.db.get(args.beliefNodeId);
+    if (!belief) {
+      throw new Error("Target belief/question/theme node not found.");
+    }
+    if (!entity.globalId) {
+      throw new Error("Source entity is missing a globalId.");
+    }
+    if (!belief.globalId) {
+      throw new Error(
+        "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 (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 existing = await ctx.db.query("epistemicEdges").withIndex(
+      "by_from_to",
+      (q) => q.eq("fromNodeId", fromNodeId).eq("toNodeId", toNodeId)
+    ).first();
+    if (existing && existing.edgeType === effectiveEdgeType) {
+      return { edgeId: existing._id, existed: true };
+    }
+    const globalId = `edge-${effectiveEdgeType}-${fromNodeId}-${toNodeId}-${Date.now()}`;
+    await ctx.scheduler.runAfter(0, internal.neo4jEdgeAPI.createEdge, {
+      globalId,
+      fromGlobalId,
+      toGlobalId,
+      edgeType: effectiveEdgeType,
+      weight: args.weight ?? 1,
+      context: args.context || `Entity-belief bridge: ${effectiveEdgeType}`,
+      topicId: belief.projectId || entity.projectId ? String(belief.projectId || entity.projectId) : void 0,
+      createdBy: userId,
+      fromNodeType,
+      toNodeType,
+      fromLayer: edgeFromLayer,
+      toLayer: edgeToLayer
+    });
+    return { globalId, edgeType: effectiveEdgeType, existed: false };
+  }
+});
+
+export { getBeliefsForEntity, getEntitiesForBelief, getEntityTopicScope, getEvidenceForEntity, linkEntityToBelief };
+//# sourceMappingURL=entityBridge.js.map
+//# sourceMappingURL=entityBridge.js.map