@lucern/graph-primitives 1.0.29 → 1.0.30

package/dist/epistemicNodeCreation.js

@@ -1,10 +1,14 @@
+import { unsafeConvexAnyApi } from '@lucern/contracts/convex/unsafeAnyApi';
+import { componentsGeneric } from 'convex/server';
 import { generateGlobalId, assertUuidV7Identity } from '@lucern/contracts/ids';
-import { componentsGeneric, anyApi } from 'convex/server';
 import '@lucern/contracts';
 
-// src/globalId.ts
+// 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/epistemicLayerRules.ts
 function getNodeLayer(nodeType) {
@@ -336,15 +340,73 @@ function validateEdgeLayers(edgeType, fromLayer, toLayer) {
 }
 
 // src/epistemicEdgeCreation.ts
+var EPISTEMIC_LAYERS = /* @__PURE__ */ new Set([
+  "L4",
+  "L3",
+  "L2",
+  "L1",
+  "ontological",
+  "organizational"
+]);
+function readOptionalString(value) {
+  return typeof value === "string" && value.trim().length > 0 ? value : void 0;
+}
+function readConvexId(value) {
+  const normalized = readOptionalString(value);
+  return normalized;
+}
+function readEpistemicLayer(value) {
+  const layer = readOptionalString(value);
+  return layer && EPISTEMIC_LAYERS.has(layer) ? layer : void 0;
+}
+function readRecord(value) {
+  return value && typeof value === "object" && !Array.isArray(value) ? value : void 0;
+}
+function readEdgeNodeRow(value) {
+  const record = readRecord(value);
+  if (!record) {
+    return null;
+  }
+  const id = readConvexId(record._id);
+  const globalId = readOptionalString(record.globalId);
+  const nodeType = readOptionalString(record.nodeType);
+  if (!(id && globalId && nodeType)) {
+    return null;
+  }
+  const node = { _id: id, globalId, nodeType };
+  const epistemicLayer = readEpistemicLayer(record.epistemicLayer);
+  if (epistemicLayer !== void 0) {
+    node.epistemicLayer = epistemicLayer;
+  }
+  const metadata = readRecord(record.metadata);
+  if (metadata !== void 0) {
+    node.metadata = metadata;
+  }
+  const projectId = readOptionalString(record.projectId);
+  if (projectId !== void 0) {
+    node.projectId = projectId;
+  }
+  return node;
+}
+function requireEdgeNodeRow(value, context) {
+  const node = readEdgeNodeRow(value);
+  if (!node) {
+    throw new Error(`${context} requires a canonical epistemic node row.`);
+  }
+  return node;
+}
 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) {
-    throw new Error("One or both nodes not found");
-  }
-  const fromLayer = fromNode.epistemicLayer || getNodeLayer(fromNode.nodeType);
-  const toLayer = toNode.epistemicLayer || getNodeLayer(toNode.nodeType);
+  const fromNode = requireEdgeNodeRow(
+    await ctx.db.get(params.fromNodeId),
+    "Create epistemic edge source"
+  );
+  const toNode = requireEdgeNodeRow(
+    await ctx.db.get(params.toNodeId),
+    "Create epistemic edge target"
+  );
+  const fromLayer = fromNode.epistemicLayer ?? getNodeLayer(fromNode.nodeType);
+  const toLayer = toNode.epistemicLayer ?? getNodeLayer(toNode.nodeType);
   if (!params.skipLayerValidation) {
     const validation = validateEdgeLayers(params.edgeType, fromLayer, toLayer);
     if (!validation.valid) {
@@ -370,7 +432,7 @@ async function createEpistemicEdge(ctx, params) {
   });
   return globalId;
 }
-async function insertEpistemicNode(ctx, doc) {
+function insertEpistemicNode(ctx, doc) {
   assertUuidV7Identity("epistemicNodes", doc.globalId);
   return ctx.db.insert("epistemicNodes", doc);
 }
@@ -380,8 +442,11 @@ function generateContentHash(nodeType, text) {
   const content = `${nodeType}:${normalizeText(text)}`;
   let hash = 5381;
   for (let i = 0; i < content.length; i++) {
-    hash = (hash << 5) + hash + content.charCodeAt(i);
-    hash &= hash;
+    const nextHash = hash * 33 + content.charCodeAt(i);
+    hash = nextHash - Math.floor(nextHash / 4294967296) * 4294967296;
+    if (hash >= 2147483648) {
+      hash -= 4294967296;
+    }
   }
   const hashHex = Math.abs(hash).toString(16).padStart(8, "0");
   const lengthHex = content.length.toString(16).padStart(4, "0");
@@ -391,6 +456,71 @@ function generateContentHash(nodeType, text) {
 function normalizeText(text) {
   return text.trim().toLowerCase().replace(/\s+/g, " ");
 }
+function readOptionalString2(value) {
+  return typeof value === "string" && value.trim().length > 0 ? value : void 0;
+}
+function readOptionalBoolean(value) {
+  return typeof value === "boolean" ? value : void 0;
+}
+function readRecord2(value) {
+  return value && typeof value === "object" && !Array.isArray(value) ? value : null;
+}
+function readConvexId2(value) {
+  const normalized = readOptionalString2(value);
+  return normalized ? normalized : null;
+}
+function readExistingEpistemicNodeRow(value) {
+  const record = readRecord2(value);
+  if (!record) {
+    return null;
+  }
+  const id = readConvexId2(record._id);
+  if (!id) {
+    return null;
+  }
+  const node = { _id: id };
+  const metadata = readRecord2(record.metadata);
+  if (metadata) {
+    node.metadata = metadata;
+  }
+  const projectId = readOptionalString2(record.projectId);
+  if (projectId !== void 0) {
+    node.projectId = projectId;
+  }
+  const status = readOptionalString2(record.status);
+  if (status !== void 0) {
+    node.status = status;
+  }
+  return node;
+}
+function readSourceArtifactRow(value) {
+  const record = readRecord2(value);
+  if (!record) {
+    return null;
+  }
+  const artifact = {};
+  const content = readOptionalString2(record.content);
+  if (content !== void 0) {
+    artifact.content = content;
+  }
+  const metadata = readRecord2(record.metadata);
+  if (metadata) {
+    artifact.metadata = metadata;
+  }
+  const projectId = readOptionalString2(record.projectId);
+  if (projectId !== void 0) {
+    artifact.projectId = projectId;
+  }
+  const stage = readOptionalString2(record.stage);
+  if (stage !== void 0) {
+    artifact.stage = stage;
+  }
+  const topicId = readOptionalString2(record.topicId);
+  if (topicId !== void 0) {
+    artifact.topicId = topicId;
+  }
+  return artifact;
+}
 function mapInsightSourceType(sourceType) {
   switch (sourceType) {
     case "verified":
@@ -413,16 +543,38 @@ function mapVerificationStatus(status) {
       return "unverified";
   }
 }
+function inferInsightConfidence(verificationStatus) {
+  if (verificationStatus === "manually_verified") {
+    return 0.9;
+  }
+  if (verificationStatus === "deep_verified") {
+    return 0.7;
+  }
+  if (verificationStatus === "pre_screened") {
+    return 0.5;
+  }
+  return 0.3;
+}
+function mapQuestionSourceType(source) {
+  if (source === "manual") {
+    return "human";
+  }
+  if (source === "ai_suggested") {
+    return "ai_generated";
+  }
+  return "ai_extracted";
+}
 async function createEpistemicNodeForInsight(ctx, _insightId, insight) {
   const now = Date.now();
   const globalId = generateGlobalId();
   const contentHash = generateContentHash("evidence", insight.text);
   const existing = await ctx.db.query("epistemicNodes").withIndex("by_contentHash", (q) => q.eq("contentHash", contentHash)).first();
-  if (existing && existing.status === "active") {
-    await ctx.db.patch(existing._id, {
+  const existingInsightNode = readExistingEpistemicNodeRow(existing);
+  if (existingInsightNode?.status === "active") {
+    await ctx.db.patch(existingInsightNode._id, {
       updatedAt: now
     });
-    return existing._id;
+    return existingInsightNode._id;
   }
   const nodeId = await insertEpistemicNode(ctx, {
     globalId,
@@ -458,7 +610,7 @@ async function createEpistemicNodeForInsight(ctx, _insightId, insight) {
     },
     sourceType: mapInsightSourceType(insight.sourceType),
     aiProvider: insight.aiProvider,
-    confidence: insight.verificationStatus === "manually_verified" ? 0.9 : insight.verificationStatus === "deep_verified" ? 0.7 : insight.verificationStatus === "pre_screened" ? 0.5 : 0.3,
+    confidence: inferInsightConfidence(insight.verificationStatus),
     verificationStatus: mapVerificationStatus(insight.verificationStatus),
     status: "active",
     topicId: insight.projectId,
@@ -490,15 +642,16 @@ async function createEpistemicNodeForBelief(ctx, beliefId, belief) {
   const globalId = generateGlobalId();
   const contentHash = generateContentHash("belief", belief.belief);
   const existing = await ctx.db.query("epistemicNodes").withIndex("by_contentHash", (q) => q.eq("contentHash", contentHash)).first();
-  if (existing && existing.status === "active") {
-    await ctx.db.patch(existing._id, {
+  const existingBeliefNode = readExistingEpistemicNodeRow(existing);
+  if (existingBeliefNode?.status === "active") {
+    await ctx.db.patch(existingBeliefNode._id, {
       metadata: {
-        ...existing.metadata || {},
+        ...existingBeliefNode.metadata ?? {},
         sourceBeliefId: beliefId
       },
       updatedAt: now
     });
-    return existing._id;
+    return existingBeliefNode._id;
   }
   const nodeId = await insertEpistemicNode(ctx, {
     globalId,
@@ -541,13 +694,14 @@ async function createEpistemicNodeForQuestion(ctx, _questionId, question) {
   const globalId = generateGlobalId();
   const contentHash = generateContentHash("question", question.question);
   const existing = await ctx.db.query("epistemicNodes").withIndex("by_contentHash", (q) => q.eq("contentHash", contentHash)).first();
-  if (existing && existing.status === "active") {
-    await ctx.db.patch(existing._id, {
+  const existingQuestionNode = readExistingEpistemicNodeRow(existing);
+  if (existingQuestionNode?.status === "active") {
+    await ctx.db.patch(existingQuestionNode._id, {
       updatedAt: now
     });
-    return existing._id;
+    return existingQuestionNode._id;
   }
-  const sourceType = question.source === "manual" ? "human" : question.source === "ai_suggested" ? "ai_generated" : "ai_extracted";
+  const sourceType = mapQuestionSourceType(question.source);
   const nodeId = await insertEpistemicNode(ctx, {
     globalId,
     nodeType: "question",
@@ -588,8 +742,9 @@ async function createEpistemicNodeForArtifact(ctx, artifactId, artifact) {
       artifact.title + artifact.content.slice(0, 500)
     );
     const existing2 = await ctx.db.query("epistemicNodes").withIndex("by_contentHash", (q) => q.eq("contentHash", contentHash2)).first();
-    if (existing2 && existing2.status === "active") {
-      return existing2._id;
+    const existingSynthesisNode = readExistingEpistemicNodeRow(existing2);
+    if (existingSynthesisNode?.status === "active") {
+      return existingSynthesisNode._id;
     }
     throw new Error("SKIP_SYNTHESIS_NODE_CREATION");
   }
@@ -598,15 +753,16 @@ async function createEpistemicNodeForArtifact(ctx, artifactId, artifact) {
     artifact.title + artifact.content.slice(0, 500)
   );
   const existing = await ctx.db.query("epistemicNodes").withIndex("by_contentHash", (q) => q.eq("contentHash", contentHash)).first();
-  if (existing && existing.status === "active") {
-    await ctx.db.patch(existing._id, {
+  const existingArtifactNode = readExistingEpistemicNodeRow(existing);
+  if (existingArtifactNode?.status === "active") {
+    await ctx.db.patch(existingArtifactNode._id, {
       metadata: {
-        ...existing.metadata || {},
+        ...existingArtifactNode.metadata ?? {},
         legacyArtifactId: artifactId
       },
       updatedAt: now
     });
-    return existing._id;
+    return existingArtifactNode._id;
   }
   const epistemicLayer = "L1";
   const nodeId = await insertEpistemicNode(ctx, {
@@ -635,21 +791,28 @@ async function createEpistemicNodeForArtifact(ctx, artifactId, artifact) {
   return nodeId;
 }
 async function findOrCreateSourceNode(ctx, artifactId, createdBy, scopeProjectId) {
-  const artifact = await ctx.db.get(artifactId);
+  const artifact = readSourceArtifactRow(await ctx.db.get(artifactId));
   const effectiveProjectId = scopeProjectId || artifact?.projectId;
   const effectiveTopicId = artifact?.topicId;
   let existingNodes;
   if (effectiveTopicId) {
-    existingNodes = await ctx.db.query("epistemicNodes").withIndex("by_topic", (q) => q.eq("topicId", effectiveTopicId)).collect();
+    const collectedNodes = await ctx.db.query("epistemicNodes").withIndex("by_topic", (q) => q.eq("topicId", effectiveTopicId)).collect();
+    existingNodes = collectedNodes.flatMap((node) => {
+      const row = readExistingEpistemicNodeRow(node);
+      return row ? [row] : [];
+    });
   } else {
-    existingNodes = await ctx.db.query("epistemicNodes").withIndex("by_nodeType", (q) => q.eq("nodeType", "source")).collect();
+    const collectedNodes = await ctx.db.query("epistemicNodes").withIndex("by_nodeType", (q) => q.eq("nodeType", "source")).collect();
+    existingNodes = collectedNodes.flatMap((node) => {
+      const row = readExistingEpistemicNodeRow(node);
+      return row ? [row] : [];
+    });
   }
   const existing = existingNodes.find((n) => {
     if (effectiveProjectId && n.projectId && n.projectId !== effectiveProjectId) {
       return false;
     }
-    const metadata = n.metadata;
-    return metadata?.legacyArtifactId === artifactId;
+    return n.metadata?.legacyArtifactId === artifactId;
   });
   if (existing) {
     return existing._id;
@@ -659,18 +822,18 @@ async function findOrCreateSourceNode(ctx, artifactId, createdBy, scopeProjectId
   }
   const now = Date.now();
   const globalId = generateGlobalId();
-  const artifactType = artifact.metadata?.type || "";
-  const isDeepResearch = artifact.metadata?.isDeepResearch;
+  const artifactType = readOptionalString2(artifact.metadata?.type) ?? "";
+  const isDeepResearch = readOptionalBoolean(artifact.metadata?.isDeepResearch) ?? false;
   let nodeType = "source";
   if (isDeepResearch || artifactType.includes("deep") || artifactType.includes("research")) {
     nodeType = "synthesis";
   } else if (artifactType.includes("primer")) {
     nodeType = "synthesis";
   }
-  const title = artifact.metadata?.title || artifact.metadata?.theme || "Untitled";
+  const title = readOptionalString2(artifact.metadata?.title) || readOptionalString2(artifact.metadata?.theme) || "Untitled";
   const contentHash = generateContentHash(
     nodeType,
-    title + (artifact.content?.slice(0, 500) || "")
+    title + (artifact.content?.slice(0, 500) ?? "")
   );
   const epistemicLayer = nodeType === "synthesis" ? "L2" : "L1";
   const nodeId = await insertEpistemicNode(ctx, {