@lucern/graph-primitives 1.0.48 → 1.0.52

package/dist/epistemicNodes.mutations.js

@@ -3,7 +3,7 @@ import { permissiveReturn } from '@lucern/contracts/schema-helpers/validators';
 import { v } from 'convex/values';
 import { unsafeConvexAnyApi } from '@lucern/contracts/convex/unsafeAnyApi';
 import { componentsGeneric, mutationGeneric } from 'convex/server';
-import { assertUuidV7Identity } from '@lucern/contracts/ids';
+import { assertUuidV7Identity, assertUuidV7Reference, isUuidV7 } from '@lucern/contracts/ids';
 import '@lucern/contracts/manifests/edge-policy-manifest';
 import '@lucern/contracts/manifests/edge-policy-manifest.data';
 import { isNodeType, getLayerForNodeType } from '@lucern/contracts/schema-helpers/spine/tables/epistemicNodes';
@@ -12,7 +12,6 @@ import { isNodeType, getLayerForNodeType } from '@lucern/contracts/schema-helper
 var unsafeApi = unsafeConvexAnyApi(
   "graph-primitives top-level module bundle lacks a committed Convex _generated/api surface"
 );
-var api = unsafeApi;
 componentsGeneric();
 var internal = unsafeApi;
 var mutation = mutationGeneric;
@@ -30,6 +29,9 @@ function debugGraphPrimitiveFallback(message, context) {
 }
 function insertEpistemicNode(ctx, doc) {
   assertUuidV7Identity("epistemicNodes", doc.globalId);
+  if (doc.topicId !== void 0 && doc.topicId !== null) {
+    assertUuidV7Reference("epistemicNodes.topicId", doc.topicId);
+  }
   return ctx.db.insert("epistemicNodes", doc);
 }
 
@@ -400,16 +402,36 @@ async function resolveTopicNodeScopeOrNull(ctx, ref) {
   if (!node) {
     return null;
   }
-  const scopeKey = normalizeScopeValue(node.topicId) ?? normalizeScopeValue(node.globalId);
+  const scopeKey = canonicalTopicGlobalId(node);
   if (!scopeKey) {
-    return null;
+    throw new Error(
+      `topic.uuidv7_identity_required: topic node ${ref} is missing a UUIDv7 globalId.`
+    );
   }
+  const metadata = node.metadata ?? {};
   return {
     topicId: scopeKey,
     projectId: asMappedProjectId(node),
-    source: "topic_node"
+    source: "topic_node",
+    tenantId: normalizeScopeValue(node.tenantId) ?? normalizeScopeValue(metadata.tenantId),
+    workspaceId: normalizeScopeValue(node.workspaceId) ?? normalizeScopeValue(metadata.workspaceId)
   };
 }
+function canonicalTopicGlobalId(node) {
+  const globalId = normalizeScopeValue(node.globalId);
+  if (globalId && isUuidV7(globalId)) {
+    return globalId;
+  }
+  const topicId = normalizeScopeValue(node.topicId);
+  return topicId && isUuidV7(topicId) ? topicId : null;
+}
+function requireUuidV7TopicScope(field, value) {
+  if (!isUuidV7(value)) {
+    throw new Error(
+      `topic.uuidv7_required: ${field} must be a UUIDv7 public topic identifier.`
+    );
+  }
+}
 function asMappedProjectId(topic) {
   if (!topic) {
     return;
@@ -431,200 +453,25 @@ function normalizeScopeValue(value) {
   const normalized = value.trim();
   return normalized.length > 0 ? normalized : void 0;
 }
-function pickPrimaryTopic(candidates) {
-  return [...candidates].sort((a, b) => {
-    const depthA = a.depth ?? 9999;
-    const depthB = b.depth ?? 9999;
-    if (depthA !== depthB) {
-      return depthA - depthB;
-    }
-    const createdA = a.createdAt ?? Number.MAX_SAFE_INTEGER;
-    const createdB = b.createdAt ?? Number.MAX_SAFE_INTEGER;
-    if (createdA !== createdB) {
-      return createdA - createdB;
-    }
-    return String(a.name || "").localeCompare(String(b.name || ""));
-  })[0];
-}
-async function findTopicsByScopeAlias(ctx, scopeId) {
-  const query = ctx.db.query("topics");
-  try {
-    return await query.withIndex(
-      "by_graph_scope_project",
-      (q) => q.eq(LEGACY_SCOPE_FIELD, scopeId)
-    ).collect();
-  } catch (error) {
-    debugGraphPrimitiveFallback(
-      "[topicScope] Failed to resolve scope alias via index",
-      {
-        error,
-        scopeId
-      }
-    );
-    const topics = await query.collect();
-    return topics.filter((topic) => {
-      const normalizedGlobalId = normalizeScopeValue(topic.globalId);
-      const mappedProjectId = asMappedProjectId(topic);
-      return String(topic._id) === scopeId || normalizedGlobalId === scopeId || mappedProjectId === scopeId;
-    });
-  }
-}
-async function tryResolveHostTopicById(ctx, topicId) {
-  if (typeof ctx.runQuery !== "function") {
-    return null;
-  }
-  try {
-    return await ctx.runQuery(api.topics.get, {
-      id: topicId
-    }) ?? null;
-  } catch (error) {
-    debugGraphPrimitiveFallback(
-      "[topicScope] Failed to resolve topic by host query",
-      {
-        error,
-        topicId
-      }
-    );
-    return null;
-  }
-}
-async function tryResolveHostTopicByLegacyScope(ctx, legacyScopeId) {
-  if (typeof ctx.runQuery !== "function") {
-    return null;
-  }
-  try {
-    return await ctx.runQuery(api.topics.getByLegacyScopeId, {
-      projectId: legacyScopeId
-    }) ?? null;
-  } catch (error) {
-    debugGraphPrimitiveFallback(
-      "[topicScope] Failed to resolve topic by legacy scope",
-      {
-        error,
-        legacyScopeId
-      }
-    );
-    return null;
-  }
-}
-async function resolveInheritedWorkspaceScope(ctx, topic) {
-  const MAX_DEPTH = 10;
-  let tenantId = normalizeScopeValue(topic.tenantId);
-  let workspaceId = normalizeScopeValue(topic.workspaceId);
-  if (tenantId && workspaceId) {
-    return { tenantId, workspaceId };
-  }
-  let current = topic;
-  for (let i = 0; i < MAX_DEPTH && current?.parentTopicId; i++) {
-    current = await ctx.db.get(current.parentTopicId);
-    if (!current) {
-      break;
-    }
-    if (!tenantId) {
-      tenantId = normalizeScopeValue(current.tenantId);
-    }
-    if (!workspaceId) {
-      workspaceId = normalizeScopeValue(current.workspaceId);
-    }
-    if (tenantId && workspaceId) {
-      break;
-    }
-  }
-  return { tenantId, workspaceId };
-}
 async function resolveTopicProjectScope(ctx, args) {
   if (args.topicId) {
     return await resolveScopeFromTopicId(ctx, args.topicId);
   }
   if (args.projectId) {
-    return await resolveScopeFromLegacyProjectId(ctx, args.projectId);
+    throw new Error(
+      "topic.uuidv7_required: projectId scope aliases are retired; pass topicId as the UUIDv7 topic globalId."
+    );
   }
-  throw new Error(
-    "Missing scope: provide topicId (preferred) or legacy projectId alias."
-  );
+  throw new Error("topic.uuidv7_required: Missing scope: provide topicId.");
 }
 async function resolveScopeFromTopicId(ctx, topicId) {
-  const topic = await resolveTopicDocFromTopicId(ctx, topicId);
-  if (topic) {
-    return await buildTopicScope(ctx, topic, "topic");
-  }
-  const nodeScope = await resolveTopicNodeScopeOrNull(ctx, String(topicId));
+  const topicGlobalId = String(topicId);
+  requireUuidV7TopicScope("topicId", topicGlobalId);
+  const nodeScope = await resolveTopicNodeScopeOrNull(ctx, topicGlobalId);
   if (nodeScope) {
     return nodeScope;
   }
-  throw new Error(`Topic not found: ${String(topicId)}`);
-}
-async function resolveTopicDocFromTopicId(ctx, topicId) {
-  const direct = await tryReadTopicDoc(ctx, topicId, {
-    failureLog: "[topicScope] Failed to load topic by direct id",
-    idLogKey: "topicId"
-  });
-  if (direct) {
-    return direct;
-  }
-  const hostTopic = await tryResolveHostTopicById(ctx, String(topicId));
-  if (hostTopic) {
-    return hostTopic;
-  }
-  return pickPrimaryTopic(await findTopicsByScopeAlias(ctx, String(topicId))) ?? null;
-}
-async function resolveScopeFromLegacyProjectId(ctx, legacyProjectId) {
-  const directTopic = await resolveDirectLegacyProjectTopic(
-    ctx,
-    legacyProjectId
-  );
-  if (directTopic) {
-    return await buildTopicScope(ctx, directTopic, "topic_inferred", {
-      fallbackProjectId: legacyProjectId
-    });
-  }
-  const primary = pickPrimaryTopic(
-    await findTopicsByScopeAlias(ctx, legacyProjectId)
-  );
-  if (primary) {
-    return await buildTopicScope(ctx, primary, "project_mapped_topic", {
-      fallbackProjectId: legacyProjectId
-    });
-  }
-  const nodeScope = await resolveTopicNodeScopeOrNull(ctx, legacyProjectId);
-  if (nodeScope) {
-    return {
-      ...nodeScope,
-      projectId: nodeScope.projectId ?? legacyProjectId
-    };
-  }
-  throw new Error(
-    `Legacy project scope ${legacyProjectId} has no mapped topic.`
-  );
-}
-async function resolveDirectLegacyProjectTopic(ctx, legacyProjectId) {
-  const directTopic = await tryReadTopicDoc(ctx, legacyProjectId, {
-    failureLog: "[topicScope] Failed to load direct project topic",
-    idLogKey: "projectId"
-  });
-  return directTopic ?? tryResolveHostTopicByLegacyScope(ctx, legacyProjectId);
-}
-async function tryReadTopicDoc(ctx, id, log) {
-  try {
-    return await ctx.db.get(id);
-  } catch (error) {
-    debugGraphPrimitiveFallback(log.failureLog, {
-      error,
-      [log.idLogKey]: id
-    });
-    return null;
-  }
-}
-async function buildTopicScope(ctx, topic, source, options = {}) {
-  const inherited = await resolveInheritedWorkspaceScope(ctx, topic);
-  const mapped = asMappedProjectId(topic);
-  return {
-    topicId: topic._id,
-    ...mapped || options.fallbackProjectId ? { projectId: mapped ?? options.fallbackProjectId } : {},
-    tenantId: inherited.tenantId,
-    workspaceId: inherited.workspaceId,
-    source
-  };
+  throw new Error(`Topic not found: ${topicGlobalId}`);
 }
 var optionalScopeArgs = {
   projectId: v.optional(v.string()),

package/dist/epistemicNodes.queries.js

@@ -3,12 +3,12 @@ import { permissiveReturn } from '@lucern/contracts/schema-helpers/validators';
 import { v } from 'convex/values';
 import { unsafeConvexAnyApi } from '@lucern/contracts/convex/unsafeAnyApi';
 import { componentsGeneric, queryGeneric } from 'convex/server';
+import { isUuidV7 } from '@lucern/contracts/ids';
 
 // src/epistemicNodes.queries.ts
-var unsafeApi = unsafeConvexAnyApi(
+unsafeConvexAnyApi(
   "graph-primitives top-level module bundle lacks a committed Convex _generated/api surface"
 );
-var api = unsafeApi;
 componentsGeneric();
 var query = queryGeneric;
 
@@ -170,6 +170,8 @@ v.union(
   v.literal("contradicted"),
   v.literal("outdated")
 );
+
+// src/topicScope.ts
 var LEGACY_SCOPE_FIELD = "graphScopeProjectId";
 async function resolveTopicNodeScopeOrNull(ctx, ref) {
   if (!ctx?.db || typeof ctx.db.query !== "function") {
@@ -190,16 +192,36 @@ async function resolveTopicNodeScopeOrNull(ctx, ref) {
   if (!node) {
     return null;
   }
-  const scopeKey = normalizeScopeValue(node.topicId) ?? normalizeScopeValue(node.globalId);
+  const scopeKey = canonicalTopicGlobalId(node);
   if (!scopeKey) {
-    return null;
+    throw new Error(
+      `topic.uuidv7_identity_required: topic node ${ref} is missing a UUIDv7 globalId.`
+    );
   }
+  const metadata = node.metadata ?? {};
   return {
     topicId: scopeKey,
     projectId: asMappedProjectId(node),
-    source: "topic_node"
+    source: "topic_node",
+    tenantId: normalizeScopeValue(node.tenantId) ?? normalizeScopeValue(metadata.tenantId),
+    workspaceId: normalizeScopeValue(node.workspaceId) ?? normalizeScopeValue(metadata.workspaceId)
   };
 }
+function canonicalTopicGlobalId(node) {
+  const globalId = normalizeScopeValue(node.globalId);
+  if (globalId && isUuidV7(globalId)) {
+    return globalId;
+  }
+  const topicId = normalizeScopeValue(node.topicId);
+  return topicId && isUuidV7(topicId) ? topicId : null;
+}
+function requireUuidV7TopicScope(field, value) {
+  if (!isUuidV7(value)) {
+    throw new Error(
+      `topic.uuidv7_required: ${field} must be a UUIDv7 public topic identifier.`
+    );
+  }
+}
 function asMappedProjectId(topic) {
   if (!topic) {
     return;
@@ -221,200 +243,25 @@ function normalizeScopeValue(value) {
   const normalized = value.trim();
   return normalized.length > 0 ? normalized : void 0;
 }
-function pickPrimaryTopic(candidates) {
-  return [...candidates].sort((a, b) => {
-    const depthA = a.depth ?? 9999;
-    const depthB = b.depth ?? 9999;
-    if (depthA !== depthB) {
-      return depthA - depthB;
-    }
-    const createdA = a.createdAt ?? Number.MAX_SAFE_INTEGER;
-    const createdB = b.createdAt ?? Number.MAX_SAFE_INTEGER;
-    if (createdA !== createdB) {
-      return createdA - createdB;
-    }
-    return String(a.name || "").localeCompare(String(b.name || ""));
-  })[0];
-}
-async function findTopicsByScopeAlias(ctx, scopeId) {
-  const query2 = ctx.db.query("topics");
-  try {
-    return await query2.withIndex(
-      "by_graph_scope_project",
-      (q) => q.eq(LEGACY_SCOPE_FIELD, scopeId)
-    ).collect();
-  } catch (error) {
-    debugGraphPrimitiveFallback(
-      "[topicScope] Failed to resolve scope alias via index",
-      {
-        error,
-        scopeId
-      }
-    );
-    const topics = await query2.collect();
-    return topics.filter((topic) => {
-      const normalizedGlobalId = normalizeScopeValue(topic.globalId);
-      const mappedProjectId = asMappedProjectId(topic);
-      return String(topic._id) === scopeId || normalizedGlobalId === scopeId || mappedProjectId === scopeId;
-    });
-  }
-}
-async function tryResolveHostTopicById(ctx, topicId) {
-  if (typeof ctx.runQuery !== "function") {
-    return null;
-  }
-  try {
-    return await ctx.runQuery(api.topics.get, {
-      id: topicId
-    }) ?? null;
-  } catch (error) {
-    debugGraphPrimitiveFallback(
-      "[topicScope] Failed to resolve topic by host query",
-      {
-        error,
-        topicId
-      }
-    );
-    return null;
-  }
-}
-async function tryResolveHostTopicByLegacyScope(ctx, legacyScopeId) {
-  if (typeof ctx.runQuery !== "function") {
-    return null;
-  }
-  try {
-    return await ctx.runQuery(api.topics.getByLegacyScopeId, {
-      projectId: legacyScopeId
-    }) ?? null;
-  } catch (error) {
-    debugGraphPrimitiveFallback(
-      "[topicScope] Failed to resolve topic by legacy scope",
-      {
-        error,
-        legacyScopeId
-      }
-    );
-    return null;
-  }
-}
-async function resolveInheritedWorkspaceScope(ctx, topic) {
-  const MAX_DEPTH = 10;
-  let tenantId = normalizeScopeValue(topic.tenantId);
-  let workspaceId = normalizeScopeValue(topic.workspaceId);
-  if (tenantId && workspaceId) {
-    return { tenantId, workspaceId };
-  }
-  let current = topic;
-  for (let i = 0; i < MAX_DEPTH && current?.parentTopicId; i++) {
-    current = await ctx.db.get(current.parentTopicId);
-    if (!current) {
-      break;
-    }
-    if (!tenantId) {
-      tenantId = normalizeScopeValue(current.tenantId);
-    }
-    if (!workspaceId) {
-      workspaceId = normalizeScopeValue(current.workspaceId);
-    }
-    if (tenantId && workspaceId) {
-      break;
-    }
-  }
-  return { tenantId, workspaceId };
-}
 async function resolveTopicProjectScope(ctx, args) {
   if (args.topicId) {
     return await resolveScopeFromTopicId(ctx, args.topicId);
   }
   if (args.projectId) {
-    return await resolveScopeFromLegacyProjectId(ctx, args.projectId);
+    throw new Error(
+      "topic.uuidv7_required: projectId scope aliases are retired; pass topicId as the UUIDv7 topic globalId."
+    );
   }
-  throw new Error(
-    "Missing scope: provide topicId (preferred) or legacy projectId alias."
-  );
+  throw new Error("topic.uuidv7_required: Missing scope: provide topicId.");
 }
 async function resolveScopeFromTopicId(ctx, topicId) {
-  const topic = await resolveTopicDocFromTopicId(ctx, topicId);
-  if (topic) {
-    return await buildTopicScope(ctx, topic, "topic");
-  }
-  const nodeScope = await resolveTopicNodeScopeOrNull(ctx, String(topicId));
+  const topicGlobalId = String(topicId);
+  requireUuidV7TopicScope("topicId", topicGlobalId);
+  const nodeScope = await resolveTopicNodeScopeOrNull(ctx, topicGlobalId);
   if (nodeScope) {
     return nodeScope;
   }
-  throw new Error(`Topic not found: ${String(topicId)}`);
-}
-async function resolveTopicDocFromTopicId(ctx, topicId) {
-  const direct = await tryReadTopicDoc(ctx, topicId, {
-    failureLog: "[topicScope] Failed to load topic by direct id",
-    idLogKey: "topicId"
-  });
-  if (direct) {
-    return direct;
-  }
-  const hostTopic = await tryResolveHostTopicById(ctx, String(topicId));
-  if (hostTopic) {
-    return hostTopic;
-  }
-  return pickPrimaryTopic(await findTopicsByScopeAlias(ctx, String(topicId))) ?? null;
-}
-async function resolveScopeFromLegacyProjectId(ctx, legacyProjectId) {
-  const directTopic = await resolveDirectLegacyProjectTopic(
-    ctx,
-    legacyProjectId
-  );
-  if (directTopic) {
-    return await buildTopicScope(ctx, directTopic, "topic_inferred", {
-      fallbackProjectId: legacyProjectId
-    });
-  }
-  const primary = pickPrimaryTopic(
-    await findTopicsByScopeAlias(ctx, legacyProjectId)
-  );
-  if (primary) {
-    return await buildTopicScope(ctx, primary, "project_mapped_topic", {
-      fallbackProjectId: legacyProjectId
-    });
-  }
-  const nodeScope = await resolveTopicNodeScopeOrNull(ctx, legacyProjectId);
-  if (nodeScope) {
-    return {
-      ...nodeScope,
-      projectId: nodeScope.projectId ?? legacyProjectId
-    };
-  }
-  throw new Error(
-    `Legacy project scope ${legacyProjectId} has no mapped topic.`
-  );
-}
-async function resolveDirectLegacyProjectTopic(ctx, legacyProjectId) {
-  const directTopic = await tryReadTopicDoc(ctx, legacyProjectId, {
-    failureLog: "[topicScope] Failed to load direct project topic",
-    idLogKey: "projectId"
-  });
-  return directTopic ?? tryResolveHostTopicByLegacyScope(ctx, legacyProjectId);
-}
-async function tryReadTopicDoc(ctx, id, log) {
-  try {
-    return await ctx.db.get(id);
-  } catch (error) {
-    debugGraphPrimitiveFallback(log.failureLog, {
-      error,
-      [log.idLogKey]: id
-    });
-    return null;
-  }
-}
-async function buildTopicScope(ctx, topic, source, options = {}) {
-  const inherited = await resolveInheritedWorkspaceScope(ctx, topic);
-  const mapped = asMappedProjectId(topic);
-  return {
-    topicId: topic._id,
-    ...mapped || options.fallbackProjectId ? { projectId: mapped ?? options.fallbackProjectId } : {},
-    tenantId: inherited.tenantId,
-    workspaceId: inherited.workspaceId,
-    source
-  };
+  throw new Error(`Topic not found: ${topicGlobalId}`);
 }
 var optionalScopeArgs = {
   projectId: v.optional(v.string()),