@lucern/graph-primitives 1.0.22 → 1.0.24

package/dist/entityLifecycle.js

@@ -1,9 +1,10 @@
-import { v } from 'convex/values';
+import { v, ConvexError } from 'convex/values';
 import { checkProjectAccess } from '@lucern/access-control/access';
 import { getCurrentUserId } from '@lucern/access-control/auth';
 import { permissiveReturn } from '@lucern/contracts/schema-helpers/validators';
 import { componentsGeneric, anyApi, queryGeneric, mutationGeneric } from 'convex/server';
-import { generateGlobalId } from '@lucern/contracts/ids';
+import { generateGlobalId, assertUuidV7Identity, assertStorageEdgeVocabulary, assertUuidShapedEdgeEndpoint } from '@lucern/contracts/ids';
+import { assertEdgePolicyAllowed, edgePolicyManifest } from '@lucern/contracts';
 
 // src/entityLifecycle.ts
 var api = anyApi;
@@ -76,6 +77,36 @@ async function validateEntityMetadata(ctx, nodeType, metadata, tenantId) {
   };
 }
 
+// src/entityCanonicalMatch.ts
+function normalizeCanonicalEntityText(value) {
+  return value.trim().toLowerCase().replace(/\s+/g, " ");
+}
+function buildEntityTitle(canonicalText) {
+  return canonicalText.slice(0, 100) + (canonicalText.length > 100 ? "..." : "");
+}
+function matchesCanonicalEntityRecord(node, args) {
+  if (node.epistemicLayer !== "ontological") {
+    return false;
+  }
+  if (node.workspaceId !== void 0) {
+    return false;
+  }
+  if (args.nodeType && node.nodeType !== args.nodeType) {
+    return false;
+  }
+  if (args.contentHash && node.contentHash !== args.contentHash) {
+    return false;
+  }
+  const rowTenantId = typeof node.tenantId === "string" && node.tenantId.trim().length > 0 ? node.tenantId.trim() : void 0;
+  if (rowTenantId !== args.tenantId) {
+    return false;
+  }
+  if (args.includeArchived) {
+    return node.status !== "deleted";
+  }
+  return node.status === "active";
+}
+
 // src/topicOntologyResolver.ts
 var MAX_RESOLUTION_DEPTH = 10;
 async function resolveTopicOntologyInternal(ctx, topicId) {
@@ -285,6 +316,9 @@ function materializeTopicProjectOverlay(topic, idMode = "legacy") {
     type: mapProjectType(topic, metadata),
     description: readNonEmptyString(topic.description),
     ownerId: readNonEmptyString(metadata.ownerId) || readNonEmptyString(topic.createdBy) || "system",
+    // FR.7 creator-grant: surface the principal-shaped owner field (column-first,
+    // metadata fallback for legacy rows that recorded it in metadata).
+    ownerPrincipalId: readNonEmptyString(topic.ownerPrincipalId) || readNonEmptyString(metadata.ownerPrincipalId),
     sharedWith: readStringArray(metadata.sharedWith),
     visibility,
     tenantId: readNonEmptyString(topic.tenantId) || readNonEmptyString(metadata.tenantId),
@@ -479,6 +513,35 @@ function resolveGraphPrimitivesAppResolvers(_ctx) {
   };
 }
 var LEGACY_SCOPE_FIELD2 = "graphScopeProjectId";
+async function resolveTopicNodeScopeOrNull(ctx, ref) {
+  if (!ctx?.db || typeof ctx.db.query !== "function") {
+    return null;
+  }
+  let node = null;
+  try {
+    const byGlobalId = await ctx.db.query("epistemicNodes").withIndex("by_globalId", (q) => q.eq("globalId", ref)).first();
+    if (byGlobalId && byGlobalId.nodeType === "topic") {
+      node = byGlobalId;
+    }
+  } catch (error) {
+    debugGraphPrimitiveFallback(
+      "[topicScope] topic-node scope lookup by globalId failed",
+      { error, ref }
+    );
+  }
+  if (!node) {
+    return null;
+  }
+  const scopeKey = normalizeScopeValue(node.topicId) ?? normalizeScopeValue(node.globalId);
+  if (!scopeKey) {
+    return null;
+  }
+  return {
+    topicId: scopeKey,
+    projectId: asMappedProjectId(node),
+    source: "topic_node"
+  };
+}
 function asMappedProjectId(topic) {
   if (!topic) {
     return;
@@ -619,6 +682,13 @@ async function resolveTopicProjectScope(ctx, args) {
       ) ?? null;
     }
     if (!topic) {
+      const nodeScope = await resolveTopicNodeScopeOrNull(
+        ctx,
+        String(args.topicId)
+      );
+      if (nodeScope) {
+        return nodeScope;
+      }
       throw new Error(`Topic not found: ${String(args.topicId)}`);
     }
     const inherited = await resolveInheritedWorkspaceScope(ctx, topic);
@@ -689,6 +759,16 @@ async function resolveTopicProjectScope(ctx, args) {
         source: "project_mapped_topic"
       };
     }
+    const nodeScope = await resolveTopicNodeScopeOrNull(
+      ctx,
+      String(args.projectId)
+    );
+    if (nodeScope) {
+      return {
+        ...nodeScope,
+        projectId: nodeScope.projectId ?? String(args.projectId)
+      };
+    }
     throw new Error(
       `Legacy project scope ${String(args.projectId)} has no mapped topic.`
     );
@@ -701,10 +781,67 @@ var optionalScopeArgs = {
   projectId: v.optional(v.string()),
   topicId: v.optional(v.string())
 };
+async function insertEpistemicNode(ctx, doc) {
+  assertUuidV7Identity("epistemicNodes", doc.globalId);
+  return ctx.db.insert("epistemicNodes", doc);
+}
+async function assertExistingNodeEndpoint(ctx, endpointRole, endpoint) {
+  assertUuidShapedEdgeEndpoint(endpointRole, endpoint);
+  const node = await ctx.db.query("epistemicNodes").withIndex("by_globalId", (q) => q.eq("globalId", endpoint)).first();
+  if (!node) {
+    throw new Error(
+      `edge_endpoint_not_canonical: epistemicEdges insert requires ${endpointRole} to be the globalId of an existing epistemicNodes row, received ${endpoint} (no node with that globalId)`
+    );
+  }
+}
+async function insertEpistemicEdge(ctx, doc) {
+  assertUuidV7Identity("epistemicEdges", doc.globalId);
+  assertStorageEdgeVocabulary(doc.edgeType);
+  if (!doc.fromNodeId || typeof doc.fromNodeId !== "string") {
+    throw new Error(
+      "edge_endpoint_missing: epistemicEdges insert requires a non-empty fromNodeId"
+    );
+  }
+  if (!doc.toNodeId || typeof doc.toNodeId !== "string") {
+    throw new Error(
+      "edge_endpoint_missing: epistemicEdges insert requires a non-empty toNodeId"
+    );
+  }
+  await assertExistingNodeEndpoint(ctx, "fromNodeId", doc.fromNodeId);
+  await assertExistingNodeEndpoint(ctx, "toNodeId", doc.toNodeId);
+  if (doc.fromNodeType && doc.toNodeType && doc.edgeType !== "extracted_from") {
+    assertEdgePolicyAllowed(
+      edgePolicyManifest,
+      doc.edgeType,
+      {
+        kind: "epistemic_node",
+        nodeId: doc.fromNodeId,
+        nodeType: doc.fromNodeType
+      },
+      {
+        kind: "epistemic_node",
+        nodeId: doc.toNodeId,
+        nodeType: doc.toNodeType
+      }
+    );
+  }
+  return ctx.db.insert("epistemicEdges", doc);
+}
 
 // src/entityLifecycle.ts
 function throwStructuredMutationError(args) {
-  const error = new Error(args.message);
+  const data = {
+    structuredMutationError: true,
+    message: args.message,
+    status: args.status,
+    code: args.code,
+    invariantCode: args.invariantCode,
+    suggestion: args.suggestion,
+    details: args.details
+  };
+  const error = new ConvexError(
+    data
+  );
   error.status = args.status;
   error.code = args.code;
   error.invariantCode = args.invariantCode;
@@ -729,12 +866,12 @@ async function requireProjectWriteAccess(ctx, projectId, userId) {
   const hasAccess = await checkProjectAccess(ctx, projectId, userId);
   if (!hasAccess) {
     throwStructuredMutationError({
-      message: "Project access required.",
+      message: `Project write access denied for topic ${projectId}.`,
       status: 403,
-      code: "FORBIDDEN",
+      code: "PROJECT_ACCESS_DENIED",
       invariantCode: "policy.scope_required",
-      suggestion: "Request write access for the project and retry.",
-      details: { projectId, userId }
+      suggestion: "The acting principal lacks project-write access to this topic. Request a topic grant (or, if the principal created this topic, run the creator-grant backfill) and retry.",
+      details: { topicId: projectId, principalId: userId }
     });
   }
 }
@@ -758,12 +895,6 @@ var ONTOLOGICAL_NODE_TYPE_SET = new Set(ONTOLOGICAL_NODE_TYPES);
 var isOntologicalNodeType = ONTOLOGICAL_NODE_TYPE_SET.has.bind(
   ONTOLOGICAL_NODE_TYPE_SET
 );
-function normalizeCanonicalEntityText(value) {
-  return value.trim().toLowerCase().replace(/\s+/g, " ");
-}
-function buildEntityTitle(canonicalText) {
-  return canonicalText.slice(0, 100) + (canonicalText.length > 100 ? "..." : "");
-}
 async function resolveCanonicalEntityScope(ctx, args) {
   const scope = await resolveTopicProjectScope(ctx, args);
   const topic = scope.topicId ? await ctx.db.get(scope.topicId) ?? null : null;
@@ -779,28 +910,6 @@ async function resolveCanonicalEntityScope(ctx, args) {
     project
   };
 }
-function matchesCanonicalEntityRecord(node, args) {
-  if (node.epistemicLayer !== "ontological") {
-    return false;
-  }
-  if (node.workspaceId !== void 0) {
-    return false;
-  }
-  if (args.nodeType && node.nodeType !== args.nodeType) {
-    return false;
-  }
-  if (args.contentHash && node.contentHash !== args.contentHash) {
-    return false;
-  }
-  const rowTenantId = typeof node.tenantId === "string" && node.tenantId.trim().length > 0 ? node.tenantId.trim() : void 0;
-  if (rowTenantId !== args.tenantId) {
-    return false;
-  }
-  if (args.includeArchived) {
-    return node.status !== "deleted";
-  }
-  return node.status === "active";
-}
 async function findExistingCanonicalEntity(ctx, args) {
   const contentHash = generateContentHash(args.nodeType, args.canonicalText);
   const candidates = await ctx.db.query("epistemicNodes").withIndex(
@@ -966,7 +1075,7 @@ var createEntity = mutation({
       };
     }
     const entityGlobalId = generateGlobalId();
-    const nodeId = await ctx.db.insert("epistemicNodes", {
+    const nodeId = await insertEpistemicNode(ctx, {
       globalId: entityGlobalId,
       nodeType: args.nodeType,
       epistemicLayer: "ontological",
@@ -1218,10 +1327,11 @@ var mergeEntities = mutation({
       );
     }
     const edgeGlobalId = generateGlobalId();
-    await ctx.db.insert("epistemicEdges", {
+    await insertEpistemicEdge(ctx, {
       globalId: edgeGlobalId,
-      fromNodeId: args.duplicateNodeId,
-      toNodeId: args.canonicalNodeId,
+      // C2-RR.4 Defect E — canonical UUIDv7 endpoints, not Convex doc ids.
+      fromNodeId: duplicate.globalId,
+      toNodeId: canonical.globalId,
       sourceGlobalId: duplicate.globalId,
       targetGlobalId: canonical.globalId,
       edgeType: "derived_from",