@lucern/graph-primitives 0.3.0-alpha.1 → 0.3.0-alpha.11

package/dist/{epistemicEdges-DcA8ErUG.d.ts → epistemicEdges-CvlKnEyy.d.ts}

@@ -188,4 +188,4 @@ declare namespace epistemicEdges {
   export { epistemicEdges_batchCreate as batchCreate, epistemicEdges_cleanupDeprecatedEdges as cleanupDeprecatedEdges, epistemicEdges_create as create, epistemicEdges_deleteEdgeFromConvex as deleteEdgeFromConvex, epistemicEdges_deleteEdges as deleteEdges, epistemicEdges_edgeTypeValidator as edgeTypeValidator, epistemicEdges_epistemicLayerValidator as epistemicLayerValidator, epistemicEdges_findContradictions as findContradictions, epistemicEdges_findSupport as findSupport, epistemicEdges_get as get, epistemicEdges_getBetween as getBetween, epistemicEdges_getByGlobalId as getByGlobalId, epistemicEdges_getByNodes as getByNodes, epistemicEdges_getByProject as getByProject, epistemicEdges_getByProjectAndType as getByProjectAndType, epistemicEdges_getBySourceNode as getBySourceNode, epistemicEdges_getByTargetNode as getByTargetNode, epistemicEdges_getByTopic as getByTopic, epistemicEdges_getClusterEdges as getClusterEdges, epistemicEdges_getEvidenceForBelief as getEvidenceForBelief, epistemicEdges_getFromNode as getFromNode, epistemicEdges_getLineage as getLineage, epistemicEdges_getToNode as getToNode, epistemicEdges_listAll as listAll, epistemicEdges_mirrorEdgeToConvex as mirrorEdgeToConvex, epistemicEdges_remove as remove, epistemicEdges_removeBetween as removeBetween, epistemicEdges_update as update, epistemicEdges_updateEdgeInConvex as updateEdgeInConvex };
 }
 
-export { getClusterEdges as A, mirrorEdgeToConvex as B, deleteEdgeFromConvex as C, updateEdgeInConvex as D, epistemicLayerValidator as a, edgeTypeValidator as b, getByGlobalId as c, getFromNode as d, epistemicEdges as e, getToNode as f, get as g, getBySourceNode as h, getByTargetNode as i, getBetween as j, getByNodes as k, getByProjectAndType as l, getByProject as m, getByTopic as n, listAll as o, findContradictions as p, findSupport as q, create as r, remove as s, removeBetween as t, update as u, batchCreate as v, getLineage as w, getEvidenceForBelief as x, cleanupDeprecatedEdges as y, deleteEdges as z };
+export { remove as A, removeBetween as B, update as C, updateEdgeInConvex as D, create as a, batchCreate as b, cleanupDeprecatedEdges as c, deleteEdgeFromConvex as d, epistemicEdges as e, deleteEdges as f, edgeTypeValidator as g, epistemicLayerValidator as h, findContradictions as i, findSupport as j, get as k, getBetween as l, getByGlobalId as m, getByNodes as n, getByProject as o, getByProjectAndType as p, getBySourceNode as q, getByTargetNode as r, getByTopic as s, getClusterEdges as t, getEvidenceForBelief as u, getFromNode as v, getLineage as w, getToNode as x, listAll as y, mirrorEdgeToConvex as z };

package/dist/epistemicEdges.d.ts

@@ -1,2 +1,2 @@
 import 'convex/values';
-export { v as batchCreate, y as cleanupDeprecatedEdges, r as create, C as deleteEdgeFromConvex, z as deleteEdges, b as edgeTypeValidator, a as epistemicLayerValidator, p as findContradictions, q as findSupport, g as get, j as getBetween, c as getByGlobalId, k as getByNodes, m as getByProject, l as getByProjectAndType, h as getBySourceNode, i as getByTargetNode, n as getByTopic, A as getClusterEdges, x as getEvidenceForBelief, d as getFromNode, w as getLineage, f as getToNode, o as listAll, B as mirrorEdgeToConvex, s as remove, t as removeBetween, u as update, D as updateEdgeInConvex } from './epistemicEdges-DcA8ErUG.js';
+export { b as batchCreate, c as cleanupDeprecatedEdges, a as create, d as deleteEdgeFromConvex, f as deleteEdges, g as edgeTypeValidator, h as epistemicLayerValidator, i as findContradictions, j as findSupport, k as get, l as getBetween, m as getByGlobalId, n as getByNodes, o as getByProject, p as getByProjectAndType, q as getBySourceNode, r as getByTargetNode, s as getByTopic, t as getClusterEdges, u as getEvidenceForBelief, v as getFromNode, w as getLineage, x as getToNode, y as listAll, z as mirrorEdgeToConvex, A as remove, B as removeBetween, C as update, D as updateEdgeInConvex } from './epistemicEdges-CvlKnEyy.js';

package/dist/epistemicEdges.js

@@ -1,7 +1,7 @@
 import { v } from 'convex/values';
 import { checkScopeAccess, requireProjectAccess } from '@lucern/access-control/access';
 import { permissiveReturn } from '@lucern/contracts/schema-helpers/validators';
-import { componentsGeneric, queryGeneric, mutationGeneric, anyApi, internalMutationGeneric } from 'convex/server';
+import { componentsGeneric, anyApi, queryGeneric, mutationGeneric, internalMutationGeneric } from 'convex/server';
 
 // src/epistemicEdges.ts
 var api = anyApi;
@@ -11,6 +11,18 @@ var internalMutation = internalMutationGeneric;
 var mutation = mutationGeneric;
 var query = queryGeneric;
 
+// src/debug.ts
+function isGraphPrimitiveDebugEnabled() {
+  const env = globalThis.process?.env;
+  return env?.LUCERN_COMPAT_FALLBACK_DEBUG === "1" || env?.LUCERN_GRAPH_DEBUG === "1";
+}
+function debugGraphPrimitiveFallback(message, context) {
+  if (!isGraphPrimitiveDebugEnabled()) {
+    return;
+  }
+  console.debug(message, context ?? {});
+}
+
 // src/graphTypes.ts
 var EDGE_TYPE_TO_REL = {
   // === THE SIX CANONICAL EPISTEMIC EDGE TYPES ===
@@ -394,19 +406,37 @@ function isProjectLikeTopic(topic) {
   return topic.type === "theme" || topic.type === "thematic" || topic.type === "deal" || topic.type === "monitoring" || readLegacyProjectId(topic) !== void 0 || readNonEmptyString(metadata.projectType) !== void 0;
 }
 function isMissingLucernChildComponentError(error) {
-  const message = error instanceof Error ? error.message : String(error);
+  const message = getErrorMessage(error);
   return message.includes(
     'Child component ComponentName(Identifier("lucern")) not found'
   ) || message.includes("Child component") && message.includes("lucern") && message.includes("not found");
 }
+function getErrorMessage(error) {
+  if (error instanceof Error) {
+    return error.message;
+  }
+  if (typeof error === "object" && error !== null && "message" in error && typeof error.message === "string") {
+    return error.message;
+  }
+  return "unknown error";
+}
 async function resolveTopicDoc(ctx, scopeId) {
   if (ctx?.db && typeof ctx.db.get === "function") {
     try {
-      const directTopic = await ctx.db.get(scopeId);
+      const directTopic = await ctx.db.get(
+        scopeId
+      );
       if (directTopic) {
         return directTopic;
       }
-    } catch {
+    } catch (error) {
+      debugGraphPrimitiveFallback(
+        "[topicProjectOverlay] Failed to resolve topic by direct ID",
+        {
+          error,
+          scopeId
+        }
+      );
     }
   }
   if (typeof ctx.runQuery !== "function") {
@@ -419,7 +449,14 @@ async function resolveTopicDoc(ctx, scopeId) {
     if (topic?.name !== void 0 && topic?.type !== void 0) {
       return topic;
     }
-  } catch {
+  } catch (error) {
+    debugGraphPrimitiveFallback(
+      "[topicProjectOverlay] Failed to resolve topic by ID query",
+      {
+        error,
+        scopeId
+      }
+    );
   }
   try {
     const topic = await ctx.runQuery(api.topics.getByLegacyScopeId, {
@@ -428,7 +465,11 @@ async function resolveTopicDoc(ctx, scopeId) {
     if (topic?.name !== void 0 && topic?.type !== void 0) {
       return topic;
     }
-  } catch {
+  } catch (error) {
+    debugGraphPrimitiveFallback(
+      "[topicProjectOverlay] Failed to resolve topic by legacy scope ID",
+      { error, scopeId }
+    );
   }
   return null;
 }
@@ -482,7 +523,11 @@ async function listTopicProjectOverlays(ctx, options = {}) {
   if (ctx?.db?.query && typeof ctx.db.query === "function") {
     try {
       allTopics = await ctx.db.query("topics").collect();
-    } catch {
+    } catch (error) {
+      debugGraphPrimitiveFallback(
+        "[topicProjectOverlay] Failed to read topics table; falling back to API",
+        { error }
+      );
       allTopics = [];
     }
   }
@@ -577,19 +622,28 @@ async function patchTopicProjectOverlay(ctx, scopeId, value) {
       "Cannot patch topic without component adapter (ctx.runMutation unavailable)"
     );
   }
-  return materializeTopicProjectOverlay(
-    {
-      ...topic,
-      ...patch,
-      metadata: nextMetadata
-    }
-  );
+  return materializeTopicProjectOverlay({
+    ...topic,
+    ...patch,
+    metadata: nextMetadata
+  });
 }
 
 // src/resolvers.ts
 function isMissingLucernChildComponentError2(error) {
-  const message = error instanceof Error ? error.message : String(error);
-  return message.includes('Child component ComponentName(Identifier("lucern")) not found') || message.includes("Child component") && message.includes("lucern") && message.includes("not found");
+  const message = getErrorMessage2(error);
+  return message.includes(
+    'Child component ComponentName(Identifier("lucern")) not found'
+  ) || message.includes("Child component") && message.includes("lucern") && message.includes("not found");
+}
+function getErrorMessage2(error) {
+  if (error instanceof Error) {
+    return error.message;
+  }
+  if (typeof error === "object" && error !== null && "message" in error && typeof error.message === "string") {
+    return error.message;
+  }
+  return "unknown error";
 }
 function isAdvisoryTopicPatch(value) {
   const advisoryKeys = /* @__PURE__ */ new Set(["lastActivityAt", "updatedAt"]);
@@ -603,32 +657,27 @@ async function patchProjectWithTolerance(ctx, projectId, value) {
     if (!isAdvisoryTopicPatch(value) || !isMissingLucernChildComponentError2(error)) {
       throw error;
     }
-    console.warn("[lucern graph-primitives] Non-fatal advisory topic patch failure", {
-      projectId,
-      keys: Object.keys(value),
-      error: error instanceof Error ? error.message : error
-    });
+    console.warn(
+      "[lucern graph-primitives] Non-fatal advisory topic patch failure",
+      {
+        projectId,
+        keys: Object.keys(value),
+        error: getErrorMessage2(error)
+      }
+    );
   }
 }
 function defaultResolvers() {
   return {
-    async getProject(ctx, projectId) {
-      return await resolveTopicProjectOverlay(ctx, projectId, {
-        idMode: "legacy",
-        projectLikeOnly: false
-      });
-    },
-    async patchProject(ctx, projectId, value) {
-      await patchProjectWithTolerance(ctx, projectId, value);
-    },
-    async listTopics(ctx) {
-      return await listTopicProjectOverlays(ctx, {
-        idMode: "legacy"
-      });
-    },
-    async getFinalArtifact(ctx, artifactId) {
-      return await ctx.db.get(artifactId);
-    }
+    getProject: (ctx, projectId) => resolveTopicProjectOverlay(ctx, projectId, {
+      idMode: "legacy",
+      projectLikeOnly: false
+    }),
+    patchProject: (ctx, projectId, value) => patchProjectWithTolerance(ctx, projectId, value),
+    listTopics: (ctx) => listTopicProjectOverlays(ctx, {
+      idMode: "legacy"
+    }),
+    getFinalArtifact: (ctx, artifactId) => ctx.db.get(artifactId)
   };
 }
 var resolverOverrides = {};
@@ -679,7 +728,14 @@ async function findTopicsByScopeAlias(ctx, scopeId) {
       "by_graph_scope_project",
       (q) => q.eq(LEGACY_SCOPE_FIELD2, scopeId)
     ).collect();
-  } catch {
+  } catch (error) {
+    debugGraphPrimitiveFallback(
+      "[topicScope] Failed to resolve scope alias via index",
+      {
+        error,
+        scopeId
+      }
+    );
     const topics = await ctx.db.query("topics").collect();
     return topics.filter((topic) => {
       const normalizedGlobalId = normalizeScopeValue(topic.globalId);
@@ -696,7 +752,14 @@ async function tryResolveHostTopicById(ctx, topicId) {
     return await ctx.runQuery(api.topics.get, {
       id: topicId
     }) ?? null;
-  } catch {
+  } catch (error) {
+    debugGraphPrimitiveFallback(
+      "[topicScope] Failed to resolve topic by host query",
+      {
+        error,
+        topicId
+      }
+    );
     return null;
   }
 }
@@ -708,7 +771,14 @@ async function tryResolveHostTopicByLegacyScope(ctx, legacyScopeId) {
     return await ctx.runQuery(api.topics.getByLegacyScopeId, {
       projectId: legacyScopeId
     }) ?? null;
-  } catch {
+  } catch (error) {
+    debugGraphPrimitiveFallback(
+      "[topicScope] Failed to resolve topic by legacy scope",
+      {
+        error,
+        legacyScopeId
+      }
+    );
     return null;
   }
 }
@@ -737,8 +807,17 @@ async function resolveTopicProjectScope(ctx, args) {
   if (args.topicId) {
     let topic = null;
     try {
-      topic = await ctx.db.get(args.topicId);
-    } catch {
+      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));
@@ -775,7 +854,14 @@ async function resolveTopicProjectScope(ctx, args) {
       directTopic = await ctx.db.get(
         args.projectId
       );
-    } catch {
+    } catch (error) {
+      debugGraphPrimitiveFallback(
+        "[topicScope] Failed to load direct project topic",
+        {
+          error,
+          projectId: args.projectId
+        }
+      );
     }
     if (directTopic) {
       const inherited = await resolveInheritedWorkspaceScope(ctx, directTopic);
@@ -982,6 +1068,34 @@ var edgeTypeValidator = v.union(
   v.literal("competes_with")
   // Company → Company (ontological → ontological)
 );
+function buildEdgeStatusSuccessResult() {
+  return { success: true };
+}
+function buildEdgeNotFoundResult() {
+  const result = {};
+  result.success = false;
+  result.error = "Edge not found";
+  return result;
+}
+function buildEdgeMirrorSkippedResult() {
+  return {
+    success: false,
+    reason: "source_not_in_convex"
+  };
+}
+function buildEdgeMirrorMissingResult() {
+  return {
+    success: false,
+    reason: "not_found"
+  };
+}
+function buildEdgeMirrorWriteResult(edgeId, existed) {
+  return {
+    success: true,
+    edgeId,
+    existed
+  };
+}
 var get = query({
   args: { edgeId: v.id("epistemicEdges") },
   returns: permissiveReturn,
@@ -1133,7 +1247,15 @@ var getByProjectAndType = query({
         projectId: args.projectId,
         topicId: args.topicId
       });
-    } catch {
+    } catch (error) {
+      debugGraphPrimitiveFallback(
+        "[epistemicEdges] Failed to resolve getAll scope",
+        {
+          error,
+          projectId: args.projectId,
+          topicId: args.topicId
+        }
+      );
       return [];
     }
     const projectEdges = await collectScopedEdges(ctx, scope, 5e3);
@@ -1159,7 +1281,15 @@ var getByProject = query({
         projectId: args.projectId,
         topicId: args.topicId
       });
-    } catch {
+    } catch (error) {
+      debugGraphPrimitiveFallback(
+        "[epistemicEdges] Failed to resolve getByProject scope",
+        {
+          error,
+          projectId: args.projectId,
+          topicId: args.topicId
+        }
+      );
       return [];
     }
     if (args.userId) {
@@ -1173,7 +1303,11 @@ var getByProject = query({
       }
     }
     const pageSize = Math.max(1, Math.min(Math.floor(args.limit ?? 500), 2e3));
-    const edges = await collectScopedEdges(ctx, scope, Math.min(pageSize * 3, 6e3));
+    const edges = await collectScopedEdges(
+      ctx,
+      scope,
+      Math.min(pageSize * 3, 6e3)
+    );
     return edges.filter((edge) => edgeMatchesWorkspaceReasoningScope(edge, scope)).slice(0, pageSize);
   }
 });
@@ -1407,7 +1541,7 @@ var update = mutation({
         projectId: edge.projectId
       });
     }
-    return { success: true };
+    return buildEdgeStatusSuccessResult();
   }
 });
 var remove = mutation({
@@ -1419,7 +1553,7 @@ var remove = mutation({
   handler: async (ctx, args) => {
     const edge = await ctx.db.get(args.edgeId);
     if (!edge) {
-      return { success: false, error: "Edge not found" };
+      return buildEdgeNotFoundResult();
     }
     if (edge.projectId && args.userId) {
       await requireProjectAccess(ctx, edge.projectId, args.userId);
@@ -1454,7 +1588,7 @@ var remove = mutation({
       globalId: edge.globalId
     });
     await ctx.db.delete(args.edgeId);
-    return { success: true };
+    return buildEdgeStatusSuccessResult();
   }
 });
 var removeBetween = mutation({
@@ -1614,9 +1748,7 @@ var getLineage = query({
       }
       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"
-      );
+      const lineageEdges = edges.filter((e) => e.edgeType === "derived_from");
       for (const edge of lineageEdges) {
         if (!edge.toNodeId) {
           continue;
@@ -1817,13 +1949,13 @@ var mirrorEdgeToConvex = internalMutation({
       console.log(
         `[Dual-Write] Skipping mirror - source node not in Convex: ${args.fromGlobalId}`
       );
-      return { success: false, reason: "source_not_in_convex" };
+      return buildEdgeMirrorSkippedResult();
     }
     const toNode = await ctx.db.query("epistemicNodes").withIndex("by_globalId", (q) => q.eq("globalId", args.toGlobalId)).first();
     const existing = await ctx.db.query("epistemicEdges").withIndex("by_globalId", (q) => q.eq("globalId", args.globalId)).first();
     if (existing) {
       console.log(`[Dual-Write] Edge already exists: ${args.globalId}`);
-      return { success: true, edgeId: existing._id, existed: true };
+      return buildEdgeMirrorWriteResult(existing._id, true);
     }
     const now = Date.now();
     const edgeId = await ctx.db.insert("epistemicEdges", {
@@ -1864,7 +1996,7 @@ var mirrorEdgeToConvex = internalMutation({
     console.log(
       `[Dual-Write] Mirrored edge to Convex: ${args.globalId} (${args.edgeType})`
     );
-    return { success: true, edgeId, existed: false };
+    return buildEdgeMirrorWriteResult(edgeId, false);
   }
 });
 var deleteEdgeFromConvex = internalMutation({
@@ -1875,11 +2007,11 @@ var deleteEdgeFromConvex = internalMutation({
   handler: async (ctx, args) => {
     const existing = await ctx.db.query("epistemicEdges").withIndex("by_globalId", (q) => q.eq("globalId", args.globalId)).first();
     if (!existing) {
-      return { success: false, reason: "not_found" };
+      return buildEdgeMirrorMissingResult();
     }
     await ctx.db.delete(existing._id);
     console.log(`[Dual-Write] Deleted edge from Convex: ${args.globalId}`);
-    return { success: true };
+    return buildEdgeStatusSuccessResult();
   }
 });
 var updateEdgeInConvex = internalMutation({
@@ -1900,7 +2032,7 @@ var updateEdgeInConvex = internalMutation({
   handler: async (ctx, args) => {
     const existing = await ctx.db.query("epistemicEdges").withIndex("by_globalId", (q) => q.eq("globalId", args.globalId)).first();
     if (!existing) {
-      return { success: false, reason: "not_found" };
+      return buildEdgeMirrorMissingResult();
     }
     const updates = {
       updatedAt: Date.now()
@@ -1937,7 +2069,7 @@ var updateEdgeInConvex = internalMutation({
     }
     await ctx.db.patch(existing._id, updates);
     console.log(`[Dual-Write] Updated edge in Convex: ${args.globalId}`);
-    return { success: true };
+    return buildEdgeStatusSuccessResult();
   }
 });