@lucern/graph-primitives 1.0.50 → 1.0.53

package/dist/contradictions.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, mutationGeneric } from 'convex/server';
+import { isUuidV7 } from '@lucern/contracts/ids';
 
 // src/contradictions.ts
 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;
@@ -25,6 +25,8 @@ function debugGraphPrimitiveFallback(message, context) {
   }
   console.debug(message, context ?? {});
 }
+
+// src/topicScope.ts
 var LEGACY_SCOPE_FIELD = "graphScopeProjectId";
 async function resolveTopicNodeScopeOrNull(ctx, ref) {
   if (!ctx?.db || typeof ctx.db.query !== "function") {
@@ -45,16 +47,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;
@@ -76,200 +98,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()),

package/dist/entityLifecycle.js

@@ -5,7 +5,7 @@ import { permissiveReturn } from '@lucern/contracts/schema-helpers/validators';
 import { v } from 'convex/values';
 import { unsafeConvexAnyApi } from '@lucern/contracts/convex/unsafeAnyApi';
 import { componentsGeneric, queryGeneric, mutationGeneric } from 'convex/server';
-import { generateGlobalId, assertUuidV7Identity, assertStorageEdgeVocabulary, assertUuidShapedEdgeEndpoint } from '@lucern/contracts/ids';
+import { generateGlobalId, assertUuidV7Identity, assertUuidV7Reference, assertStorageEdgeVocabulary, assertUuidShapedEdgeEndpoint, isUuidV7 } from '@lucern/contracts/ids';
 import { assertEdgePolicyAllowed } from '@lucern/contracts/manifests/edge-policy-manifest';
 import { edgePolicyManifest } from '@lucern/contracts/manifests/edge-policy-manifest.data';
 
@@ -166,6 +166,9 @@ async function validateEntityMetadata(ctx, nodeType, metadata, tenantId) {
 }
 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);
 }
 async function assertExistingNodeEndpoint(ctx, endpointRole, endpoint) {
@@ -603,8 +606,47 @@ function resolveGraphPrimitivesAppResolvers(_ctx) {
 
 // src/topicOntologyResolver.ts
 var MAX_RESOLUTION_DEPTH = 10;
-async function loadTopic(ctx, topicId) {
-  return await ctx.db.get(topicId);
+async function loadTopic(ctx, topicGlobalId) {
+  requireUuidV7TopicGlobalId(topicGlobalId);
+  const topic = await ctx.db.query("epistemicNodes").withIndex("by_globalId", (q) => q.eq("globalId", topicGlobalId)).first();
+  return requireTopicGlobalId(topic);
+}
+function requireUuidV7TopicGlobalId(topicGlobalId) {
+  if (!isUuidV7(topicGlobalId)) {
+    throw new Error(
+      `topic.uuidv7_required: topic ontology resolution requires a UUIDv7 topic globalId, received ${topicGlobalId}.`
+    );
+  }
+}
+function requireTopicGlobalId(topic) {
+  if (!topic) {
+    return null;
+  }
+  if (topic.nodeType !== "topic") {
+    return null;
+  }
+  if (!isUuidV7(topic.globalId)) {
+    throw new Error(
+      `topic.uuidv7_required: topic node ${String(topic._id)} is missing a UUIDv7 globalId.`
+    );
+  }
+  return topic;
+}
+function metadataString(topic, field) {
+  const value = topic.metadata?.[field];
+  return typeof value === "string" && value.trim() ? value : null;
+}
+function topicOntologyId(topic) {
+  const ontologyId = metadataString(topic, "ontologyId");
+  return ontologyId ? ontologyId : null;
+}
+function parentTopicGlobalId(topic) {
+  const parent = metadataString(topic, "parentTopicGlobalId");
+  if (!parent) {
+    return null;
+  }
+  requireUuidV7TopicGlobalId(parent);
+  return parent;
 }
 async function loadOntologyDefinition(ctx, ontologyId) {
   return await ctx.db.get(ontologyId);
@@ -627,25 +669,20 @@ function resolvedTopicOntology(args) {
   };
 }
 async function resolveCurrentTopicOntology(args) {
-  if (!args.current.ontologyId) {
+  const ontologyId = topicOntologyId(args.current);
+  if (!ontologyId) {
     return "continue";
   }
-  const ontologyDef = await loadOntologyDefinition(
-    args.ctx,
-    args.current.ontologyId
-  );
+  const ontologyDef = await loadOntologyDefinition(args.ctx, ontologyId);
   if (!ontologyDef || ontologyDef.status === "archived") {
-    return args.current.parentTopicId ? "continue" : null;
+    return parentTopicGlobalId(args.current) ? "continue" : null;
   }
-  const published = await loadPublishedOntologyVersions(
-    args.ctx,
-    args.current.ontologyId
-  );
+  const published = await loadPublishedOntologyVersions(args.ctx, ontologyId);
   return resolvedTopicOntology({
     latestPublished: published[0] ?? null,
     ontologyDef,
-    source: args.current._id === args.startTopicId ? "direct" : "inherited",
-    sourceTopicId: args.current._id
+    source: args.current.globalId === args.startTopicGlobalId ? "direct" : "inherited",
+    sourceTopicId: args.current.globalId
   });
 }
 async function resolveTopicOntologyInternal(ctx, topicId) {
@@ -653,20 +690,21 @@ async function resolveTopicOntologyInternal(ctx, topicId) {
   if (!current) {
     return null;
   }
-  const startTopicId = topicId;
+  const startTopicGlobalId = topicId;
   for (let i = 0; i < MAX_RESOLUTION_DEPTH && current; i++) {
     const resolved = await resolveCurrentTopicOntology({
       ctx,
       current,
-      startTopicId
+      startTopicGlobalId
     });
     if (resolved !== "continue") {
       return resolved;
     }
-    if (!current.parentTopicId) {
+    const parent = parentTopicGlobalId(current);
+    if (!parent) {
       break;
     }
-    current = await loadTopic(ctx, current.parentTopicId);
+    current = await loadTopic(ctx, parent);
   }
   return null;
 }
@@ -706,16 +744,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;
@@ -737,200 +795,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_FIELD2, 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()),