@lucern/graph-primitives 1.0.28 → 1.0.30

package/dist/helpers.js

@@ -1,9 +1,13 @@
-import { componentsGeneric, anyApi } from 'convex/server';
+import { unsafeConvexAnyApi } from '@lucern/contracts/convex/unsafeAnyApi';
+import { componentsGeneric } from 'convex/server';
 import { generateGlobalId } from '@lucern/contracts/ids';
 
 // src/convex.ts
+var unsafeApi = unsafeConvexAnyApi(
+  "graph-primitives top-level module bundle lacks a committed Convex _generated/api surface"
+);
 componentsGeneric();
-var internal = anyApi;
+var internal = unsafeApi;
 
 // src/graphTypes.ts
 function getNodeLayer(nodeType) {
@@ -42,6 +46,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":
@@ -59,37 +71,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);
@@ -228,61 +216,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];
@@ -323,15 +531,27 @@ function validateEdgeLayers(edgeType, fromLayer, toLayer) {
 }
 
 // src/helpers.ts
+function readOptionalString(value) {
+  return typeof value === "string" && value.trim().length > 0 ? value : void 0;
+}
 async function createEpistemicEdge(ctx, params) {
   const globalId = generateGlobalId();
   const fromNode = await ctx.db.get(params.fromNodeId);
   const toNode = await ctx.db.get(params.toNodeId);
-  if (!fromNode || !toNode) {
+  if (!(fromNode && toNode)) {
     throw new Error("One or both nodes not found");
   }
-  const fromLayer = fromNode.epistemicLayer || getNodeLayer(fromNode.nodeType);
-  const toLayer = toNode.epistemicLayer || getNodeLayer(toNode.nodeType);
+  const fromNodeType = readOptionalString(fromNode.nodeType);
+  const toNodeType = readOptionalString(toNode.nodeType);
+  const fromGlobalId = readOptionalString(fromNode.globalId);
+  const toGlobalId = readOptionalString(toNode.globalId);
+  if (!(fromNodeType && toNodeType && fromGlobalId && toGlobalId)) {
+    throw new Error(
+      "Cannot create epistemic edge without canonical nodeType and globalId on both endpoints"
+    );
+  }
+  const fromLayer = readOptionalString(fromNode.epistemicLayer) ?? getNodeLayer(fromNodeType);
+  const toLayer = readOptionalString(toNode.epistemicLayer) ?? getNodeLayer(toNodeType);
   if (!params.skipLayerValidation) {
     const validation = validateEdgeLayers(
       params.edgeType,
@@ -340,22 +560,22 @@ async function createEpistemicEdge(ctx, params) {
     );
     if (!validation.valid) {
       throw new Error(
-        `[EdgeValidation] Invalid edge: ${validation.reason}. Attempted: ${params.edgeType} from ${fromNode.nodeType}(${fromLayer}) \u2192 ${toNode.nodeType}(${toLayer})`
+        `[EdgeValidation] Invalid edge: ${validation.reason}. Attempted: ${params.edgeType} from ${fromNodeType}(${fromLayer}) \u2192 ${toNodeType}(${toLayer})`
       );
     }
   }
   await ctx.scheduler.runAfter(0, internal.neo4jEdgeAPI.createEdge, {
     globalId,
-    fromGlobalId: fromNode.globalId,
-    toGlobalId: toNode.globalId,
+    fromGlobalId,
+    toGlobalId,
     edgeType: params.edgeType,
     weight: params.weight,
     confidence: params.confidence,
     context: params.context,
     createdBy: params.createdBy,
     topicId: params.projectId ? String(params.projectId) : void 0,
-    fromNodeType: fromNode.nodeType,
-    toNodeType: toNode.nodeType,
+    fromNodeType,
+    toNodeType,
     fromLayer,
     toLayer
   });