@lucern/graph-primitives 1.0.27 → 1.0.29

package/dist/index.js

@@ -1,10 +1,11 @@
 import { normalizeTupleContradictionPolicy, mkOpinion, createInheritedContractRecord, confidenceFromSL, getRescoringSchedule, conditionalDeduction, project, dampedDependencyCascade, hasProjectedOpinionChanged, detectTupleContradiction, evaluateTupleContradictionTransition, readOpinionFromRecord, trustDiscount, applyNegativeSupport, cumulativeFusion, applyNegativeEvidence, computeEffectiveDecay, computeDeadlineUrgency, computeBaseDecay, bayesianUpdate, DECAY_TIERS, DEADLINE_URGENCY, parseEvidentialEvaluatorConfig, compareMetricValue, buildEvidentialRationale, parseMetricCheckerConfig, getEvaluatorInputRecord, pickFiniteNumber, resolveComparisonResult, buildComparisonRationale, parseReferenceCheckCounterConfig, parseTemporalDeadlineConfig, parseMarketIndexComparatorConfig } from '@lucern/confidence';
-import { v, ConvexError } from 'convex/values';
-import { checkScopeAccess, getAccessibleProjectIds, checkProjectAccess, requireProjectAccess } from '@lucern/access-control/access';
+import { v } from 'convex/values';
+import { throwStructuredMutationError } from '@lucern/access-control/structuredMutationError';
 import { canAudienceClassAccess, normalizeAudienceKey, classFromAudienceKey } from '@lucern/access-control/audience';
 import { getCurrentUserId } from '@lucern/access-control/auth';
 import { componentsGeneric, anyApi, internalMutationGeneric, mutationGeneric, queryGeneric, internalQueryGeneric, internalActionGeneric } from 'convex/server';
 import { isNodeType, getLayerForNodeType } from '@lucern/contracts/schema-helpers/spine/tables/epistemicNodes';
+import { requireScopeWriteAccess, checkScopeAccess, getAccessibleProjectIds, checkProjectAccess } from '@lucern/access-control/access';
 import { permissiveReturn } from '@lucern/contracts/schema-helpers/validators';
 import { assertSchemaEnumValue } from '@lucern/contracts/schema-helpers/enumValidation';
 import { generateGlobalId, assertUuidV7Identity, generateUuidV7, assertStorageEdgeVocabulary, assertUuidShapedEdgeEndpoint, isUuidV7 } from '@lucern/contracts/ids';
@@ -1745,26 +1746,6 @@ var DEFAULT_CONFIDENCE_POLICY = {
   scoringMode: "after_worktree",
   tupleContradiction: normalizeTupleContradictionPolicy()
 };
-function throwStructuredMutationError(args) {
-  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;
-  error.suggestion = args.suggestion;
-  error.details = args.details;
-  throw error;
-}
 function readFiniteNumber(value) {
   return typeof value === "number" && Number.isFinite(value) ? value : void 0;
 }
@@ -2098,23 +2079,6 @@ async function requireAuthenticatedUserId(ctx) {
   }
   return userId;
 }
-async function requireProjectWriteAccess(ctx, projectId, userId) {
-  const hasAccess = await checkProjectAccess(
-    ctx,
-    projectId,
-    userId
-  );
-  if (!hasAccess) {
-    throwStructuredMutationError({
-      message: `Project write access denied for topic ${projectId}.`,
-      status: 403,
-      code: "PROJECT_ACCESS_DENIED",
-      invariantCode: "policy.scope_required",
-      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 }
-    });
-  }
-}
 function resolveTraversalTargetNodeId(edge, direction) {
   const targetNodeId = direction === "outgoing" ? edge.toNodeId : edge.fromNodeId;
   return targetNodeId ?? void 0;
@@ -2275,7 +2239,7 @@ async function applyBeliefConfidenceChange(ctx, args) {
       details: { nodeId: args.nodeId }
     });
   }
-  await requireProjectWriteAccess(
+  await requireScopeWriteAccess(
     ctx,
     node.projectId,
     args.authenticatedUserId
@@ -2839,8 +2803,6 @@ async function scheduleEmbeddingGeneration(args) {
     );
   }
 }
-
-// src/epistemicBeliefs.core.ts
 var create = mutation({
   args: {
     ...optionalBeliefScopeArgs,
@@ -2919,7 +2881,7 @@ var create = mutation({
       context: "epistemicBeliefs.create"
     });
     if (scope.projectId) {
-      await requireProjectWriteAccess(
+      await requireScopeWriteAccess(
         ctx,
         scope.projectId,
         authenticatedUserId
@@ -3159,7 +3121,7 @@ var refineBelief = mutation({
         details: { nodeId: args.nodeId }
       });
     }
-    await requireProjectWriteAccess(ctx, node.projectId, authenticatedUserId);
+    await requireScopeWriteAccess(ctx, node.projectId, authenticatedUserId);
     if (typeof node.confidence === "number" && Number.isFinite(node.confidence)) {
       throwStructuredMutationError({
         message: "Scored beliefs are immutable. Use forkBelief to evolve a scored belief.",
@@ -3379,7 +3341,7 @@ var forkBelief = mutation({
         details: { parentNodeId: args.parentNodeId }
       });
     }
-    await requireProjectWriteAccess(ctx, parent.projectId, authenticatedUserId);
+    await requireScopeWriteAccess(ctx, parent.projectId, authenticatedUserId);
     const metadata = parent.metadata;
     const forkBeliefStatus = "hypothesis";
     const forkMode = args.forkMode ?? "supersede";
@@ -3677,7 +3639,7 @@ var updateStatus = mutation({
     if (!node.projectId) {
       throw new Error("Belief has no project scope");
     }
-    await requireProjectWriteAccess(ctx, node.projectId, authenticatedUserId);
+    await requireScopeWriteAccess(ctx, node.projectId, authenticatedUserId);
     const previousStatus = node.status;
     const metadata = node.metadata || {};
     await ctx.db.patch(args.nodeId, {
@@ -3722,7 +3684,7 @@ var archive = mutation({
     if (!node.projectId) {
       throw new Error("Belief has no project scope");
     }
-    await requireProjectWriteAccess(ctx, node.projectId, authenticatedUserId);
+    await requireScopeWriteAccess(ctx, node.projectId, authenticatedUserId);
     return await ctx.runMutation(
       // Use updateStatus internally
       internal.epistemicBeliefs.updateStatusInternal,
@@ -3752,7 +3714,7 @@ var updateRationale = mutation({
     if (!node.projectId) {
       throw new Error("Belief has no project scope");
     }
-    await requireProjectWriteAccess(ctx, node.projectId, authenticatedUserId);
+    await requireScopeWriteAccess(ctx, node.projectId, authenticatedUserId);
     const metadata = node.metadata || {};
     const previousRationale = typeof metadata.rationale === "string" ? metadata.rationale : void 0;
     const nextRationale = args.rationale?.trim();
@@ -4015,7 +3977,7 @@ var updatePillar = mutation({
     if (!existingNode.projectId) {
       throw new Error("Belief has no project scope");
     }
-    await requireProjectWriteAccess(
+    await requireScopeWriteAccess(
       ctx,
       existingNode.projectId,
       authenticatedUserId
@@ -4121,7 +4083,7 @@ var linkBeliefs = mutation({
     if (!fromNode.projectId) {
       throw new Error("Belief has no project scope");
     }
-    await requireProjectWriteAccess(
+    await requireScopeWriteAccess(
       ctx,
       fromNode.projectId,
       authenticatedUserId
@@ -4177,7 +4139,7 @@ var linkEvidence = mutation({
     if (!belief.projectId) {
       throw new Error("Belief has no project scope");
     }
-    await requireProjectWriteAccess(ctx, belief.projectId, authenticatedUserId);
+    await requireScopeWriteAccess(ctx, belief.projectId, authenticatedUserId);
     const insight = await ctx.db.get(args.insightId);
     if (!insight || insight.nodeType !== "evidence") {
       throw new Error("Insight not found");
@@ -4268,7 +4230,7 @@ var unlinkEvidence = mutation({
     if (!evidenceNode.projectId) {
       throw new Error("Evidence has no project scope");
     }
-    await requireProjectWriteAccess(
+    await requireScopeWriteAccess(
       ctx,
       evidenceNode.projectId,
       authenticatedUserId
@@ -4449,7 +4411,7 @@ var deleteRelationship = mutation({
     if (!edge.projectId) {
       throw new Error("Edge has no project scope");
     }
-    await requireProjectWriteAccess(ctx, edge.projectId, authenticatedUserId);
+    await requireScopeWriteAccess(ctx, edge.projectId, authenticatedUserId);
     const previousState = {
       fromNodeId: edge.fromNodeId,
       toNodeId: edge.toNodeId,
@@ -4496,7 +4458,7 @@ var updateCriticality = mutation({
     if (!node.projectId) {
       throw new Error("Belief has no project scope");
     }
-    await requireProjectWriteAccess(ctx, node.projectId, authenticatedUserId);
+    await requireScopeWriteAccess(ctx, node.projectId, authenticatedUserId);
     const metadata = node.metadata || {};
     const previousCriticality = metadata.criticality;
     await ctx.db.patch(args.nodeId, {
@@ -4565,7 +4527,7 @@ var batchUpdateCriticality = mutation({
           results.push({ beliefId: update5.beliefId, success: false });
           continue;
         }
-        await requireProjectWriteAccess(
+        await requireScopeWriteAccess(
           ctx,
           node.projectId,
           authenticatedUserId
@@ -7953,7 +7915,7 @@ var updateStatus2 = mutation({
       throw new Error("Contradiction not found");
     }
     if (existing.projectId && args.userId) {
-      await requireProjectAccess(ctx, existing.projectId, args.userId);
+      await requireScopeWriteAccess(ctx, existing.projectId, args.userId);
     }
     const now = Date.now();
     const update5 = { status: args.status };
@@ -8004,7 +7966,7 @@ var resolve = mutation({
       throw new Error("Contradiction not found");
     }
     if (existing.projectId) {
-      await requireProjectAccess(ctx, existing.projectId, args.resolvedBy);
+      await requireScopeWriteAccess(ctx, existing.projectId, args.resolvedBy);
     }
     const now = Date.now();
     await ctx.db.patch(args.contradictionId, {
@@ -8756,30 +8718,10 @@ async function validateEntityTypeForTopic(ctx, topicId, nodeType) {
 }
 
 // src/entityLifecycle.ts
-function throwStructuredMutationError2(args) {
-  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;
-  error.suggestion = args.suggestion;
-  error.details = args.details;
-  throw error;
-}
 async function requireAuthenticatedUserId3(ctx) {
   const userId = await getCurrentUserId(ctx);
   if (!userId) {
-    throwStructuredMutationError2({
+    throwStructuredMutationError({
       message: "Authentication required.",
       status: 401,
       code: "AUTHENTICATION_REQUIRED",
@@ -8789,19 +8731,6 @@ async function requireAuthenticatedUserId3(ctx) {
   }
   return userId;
 }
-async function requireProjectWriteAccess3(ctx, projectId, userId) {
-  const hasAccess = await checkProjectAccess(ctx, projectId, userId);
-  if (!hasAccess) {
-    throwStructuredMutationError2({
-      message: `Project write access denied for topic ${projectId}.`,
-      status: 403,
-      code: "PROJECT_ACCESS_DENIED",
-      invariantCode: "policy.scope_required",
-      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 }
-    });
-  }
-}
 function generateContentHash3(nodeType, text) {
   const content = `${nodeType}:${text.trim().toLowerCase().replace(/\s+/g, " ")}`;
   let hash = 5381;
@@ -8928,7 +8857,7 @@ var createEntity = mutation({
     const now = Date.now();
     const canonicalText = args.canonicalText.trim();
     if (!canonicalText) {
-      throwStructuredMutationError2({
+      throwStructuredMutationError({
         message: "canonicalText is required.",
         status: 400,
         code: "INVALID_REQUEST",
@@ -8936,7 +8865,7 @@ var createEntity = mutation({
       });
     }
     if (!isOntologicalNodeType(args.nodeType)) {
-      throwStructuredMutationError2({
+      throwStructuredMutationError({
         message: `"${args.nodeType}" is not an ontological entity type. Use epistemicBeliefs.create for epistemic nodes.`,
         status: 400,
         code: "INVALID_NODE_TYPE",
@@ -8949,7 +8878,7 @@ var createEntity = mutation({
       projectId: args.projectId
     });
     if (scope.projectId) {
-      await requireProjectWriteAccess3(
+      await requireScopeWriteAccess(
         ctx,
         scope.projectId,
         authenticatedUserId
@@ -8962,7 +8891,7 @@ var createEntity = mutation({
         args.nodeType
       );
       if (!ontologyValidation.valid) {
-        throwStructuredMutationError2({
+        throwStructuredMutationError({
           message: `Ontology validation failed: ${ontologyValidation.error}`,
           status: 400,
           code: "ONTOLOGY_VALIDATION_ERROR",
@@ -8980,7 +8909,7 @@ var createEntity = mutation({
       scope.tenantId
     );
     if (!validation.valid) {
-      throwStructuredMutationError2({
+      throwStructuredMutationError({
         message: `Entity metadata validation failed: ${validation.errors.join("; ")}`,
         status: 400,
         code: "VALIDATION_ERROR",
@@ -9074,7 +9003,7 @@ var updateEntityAttributes = mutation({
     const now = Date.now();
     const node = await ctx.db.get(args.nodeId);
     if (!node) {
-      throwStructuredMutationError2({
+      throwStructuredMutationError({
         message: "Entity not found.",
         status: 404,
         code: "NOT_FOUND",
@@ -9082,7 +9011,7 @@ var updateEntityAttributes = mutation({
       });
     }
     if (!isOntologicalNodeType(node.nodeType)) {
-      throwStructuredMutationError2({
+      throwStructuredMutationError({
         message: `Node "${args.nodeId}" is a ${node.nodeType}, not an entity. Use belief/question APIs for epistemic nodes.`,
         status: 400,
         code: "LIFECYCLE_VIOLATION",
@@ -9092,7 +9021,7 @@ var updateEntityAttributes = mutation({
     }
     const scopeProjectId = typeof node.projectId === "string" && node.projectId.trim().length > 0 ? node.projectId : void 0;
     if (scopeProjectId) {
-      await requireProjectWriteAccess3(ctx, scopeProjectId, authenticatedUserId);
+      await requireScopeWriteAccess(ctx, scopeProjectId, authenticatedUserId);
     }
     const existingMetadata = node.metadata || {};
     const newMetadataFields = args.metadata !== void 0 ? args.metadata || {} : {};
@@ -9101,7 +9030,7 @@ var updateEntityAttributes = mutation({
       mergedMetadata.subtype = args.subtype;
     }
     if (args.canonicalText !== void 0 && args.canonicalText.trim().length === 0) {
-      throwStructuredMutationError2({
+      throwStructuredMutationError({
         message: "canonicalText cannot be empty.",
         status: 400,
         code: "INVALID_REQUEST",
@@ -9116,7 +9045,7 @@ var updateEntityAttributes = mutation({
         tenantId: typeof node.tenantId === "string" ? node.tenantId : void 0
       });
       if (duplicate && String(duplicate._id) !== String(args.nodeId)) {
-        throwStructuredMutationError2({
+        throwStructuredMutationError({
           message: "A canonical entity with this name already exists in the tenant scope.",
           status: 409,
           code: "CONFLICT",
@@ -9137,7 +9066,7 @@ var updateEntityAttributes = mutation({
       typeof node.tenantId === "string" ? node.tenantId : void 0
     );
     if (!validation.valid) {
-      throwStructuredMutationError2({
+      throwStructuredMutationError({
         message: `Entity metadata validation failed: ${validation.errors.join("; ")}`,
         status: 400,
         code: "VALIDATION_ERROR",
@@ -9211,7 +9140,7 @@ var mergeEntities = mutation({
     const canonical = await ctx.db.get(args.canonicalNodeId);
     const duplicate = await ctx.db.get(args.duplicateNodeId);
     if (!canonical || !duplicate) {
-      throwStructuredMutationError2({
+      throwStructuredMutationError({
         message: "One or both entity nodes not found.",
         status: 404,
         code: "NOT_FOUND",
@@ -9222,7 +9151,7 @@ var mergeEntities = mutation({
       });
     }
     if (!isOntologicalNodeType(canonical.nodeType) || !isOntologicalNodeType(duplicate.nodeType)) {
-      throwStructuredMutationError2({
+      throwStructuredMutationError({
         message: "Both nodes must be ontological entities to merge.",
         status: 400,
         code: "LIFECYCLE_VIOLATION",
@@ -9230,7 +9159,7 @@ var mergeEntities = mutation({
       });
     }
     if (args.canonicalNodeId === args.duplicateNodeId) {
-      throwStructuredMutationError2({
+      throwStructuredMutationError({
         message: "Cannot merge an entity with itself.",
         status: 400,
         code: "SELF_MERGE",
@@ -9240,14 +9169,14 @@ var mergeEntities = mutation({
       });
     }
     if (canonical.nodeType !== duplicate.nodeType) {
-      throwStructuredMutationError2({
+      throwStructuredMutationError({
         message: `Cannot merge different entity types: ${canonical.nodeType} vs ${duplicate.nodeType}.`,
         status: 400,
         code: "TYPE_MISMATCH"
       });
     }
     if (canonical.projectId) {
-      await requireProjectWriteAccess3(
+      await requireScopeWriteAccess(
         ctx,
         canonical.projectId,
         authenticatedUserId
@@ -9363,7 +9292,7 @@ var archiveEntity = mutation({
     const now = Date.now();
     const node = await ctx.db.get(args.nodeId);
     if (!node) {
-      throwStructuredMutationError2({
+      throwStructuredMutationError({
         message: "Entity not found.",
         status: 404,
         code: "NOT_FOUND",
@@ -9371,7 +9300,7 @@ var archiveEntity = mutation({
       });
     }
     if (!isOntologicalNodeType(node.nodeType)) {
-      throwStructuredMutationError2({
+      throwStructuredMutationError({
         message: `Node "${args.nodeId}" is a ${node.nodeType}, not an entity. Use belief archive APIs for epistemic nodes.`,
         status: 400,
         code: "LIFECYCLE_VIOLATION",
@@ -9379,7 +9308,7 @@ var archiveEntity = mutation({
       });
     }
     if (node.projectId) {
-      await requireProjectWriteAccess3(
+      await requireScopeWriteAccess(
         ctx,
         node.projectId,
         authenticatedUserId
@@ -11670,7 +11599,7 @@ var create5 = mutation({
     }) : void 0;
     const resolvedProjectId = resolvedScope?.projectId ?? args.projectId;
     if (resolvedProjectId) {
-      await requireProjectAccess(ctx, resolvedProjectId, args.createdBy);
+      await requireScopeWriteAccess(ctx, resolvedProjectId, args.createdBy);
     }
     const fromLayer = fromNode.epistemicLayer || getNodeLayer(fromNode.nodeType);
     const toLayer = toNode.epistemicLayer || getNodeLayer(toNode.nodeType);
@@ -11772,7 +11701,7 @@ var update2 = mutation({
       throw new Error("Edge not found");
     }
     if (edge.projectId && userId) {
-      await requireProjectAccess(ctx, edge.projectId, userId);
+      await requireScopeWriteAccess(ctx, edge.projectId, userId);
     }
     const cleanUpdates = {};
     for (const [key, value] of Object.entries(updates)) {
@@ -11813,7 +11742,7 @@ var remove2 = mutation({
       return buildEdgeNotFoundResult();
     }
     if (edge.projectId && args.userId) {
-      await requireProjectAccess(ctx, edge.projectId, args.userId);
+      await requireScopeWriteAccess(ctx, edge.projectId, args.userId);
     }
     if (edge.projectId) {
       await ctx.db.insert("epistemicAudit", {
@@ -12548,7 +12477,7 @@ var create6 = mutation({
       mutationName: "epistemicEvidence.create"
     });
     if (scope.projectId) {
-      await requireProjectAccess(ctx, scope.projectId, args.userId);
+      await requireScopeWriteAccess(ctx, scope.projectId, args.userId);
     }
     const now = Date.now();
     const globalId = generateGlobalId();
@@ -12718,7 +12647,7 @@ var createAndLink = mutation({
     if (!scope) {
       throw new Error("Invalid scope: projectId or topicId is required");
     }
-    await requireProjectAccess(ctx, String(scope.topicId), args.userId);
+    await requireScopeWriteAccess(ctx, String(scope.topicId), args.userId);
     const now = Date.now();
     const globalId = generateGlobalId();
     const contentHash = generateContentHash5(args.text);
@@ -13054,7 +12983,7 @@ var update3 = mutation({
     if (!node.projectId) {
       throw new Error("Evidence has no project scope");
     }
-    await checkProjectAccess(ctx, node.projectId, args.userId);
+    await requireScopeWriteAccess(ctx, node.projectId, args.userId);
     const now = Date.now();
     const existingMeta = node.metadata || {};
     const metaUpdates = { ...existingMeta };
@@ -13121,7 +13050,7 @@ var flagAsIncorrect = mutation({
     if (!node.projectId) {
       throw new Error("Evidence has no project scope");
     }
-    await checkProjectAccess(ctx, node.projectId, args.userId);
+    await requireScopeWriteAccess(ctx, node.projectId, args.userId);
     const existingMeta = node.metadata || {};
     await ctx.db.patch(node._id, {
       verificationStatus: "contradicted",
@@ -14596,7 +14525,7 @@ var update4 = mutation({
       throw new Error("Node not found");
     }
     if (node.projectId && userId) {
-      await requireProjectAccess(ctx, node.projectId, userId);
+      await requireScopeWriteAccess(ctx, node.projectId, userId);
     }
     const cleanUpdates = {};
     for (const [key, value] of Object.entries(updates)) {
@@ -14657,7 +14586,7 @@ var supersede = mutation({
       throw new Error("Node not found");
     }
     if (oldNode.projectId) {
-      await requireProjectAccess(ctx, oldNode.projectId, args.createdBy);
+      await requireScopeWriteAccess(ctx, oldNode.projectId, args.createdBy);
     }
     assertBeliefNodeSupersedeAllowed({
       node: oldNode,
@@ -14733,7 +14662,7 @@ var archive2 = mutation({
       throw new Error("Node not found");
     }
     if (node.projectId && args.userId) {
-      await requireProjectAccess(ctx, node.projectId, args.userId);
+      await requireScopeWriteAccess(ctx, node.projectId, args.userId);
     }
     assertBeliefNodeArchiveAllowed({
       node,
@@ -18374,7 +18303,7 @@ var upsertSource = mutation({
       mutationName: "epistemicSources.upsertSource"
     });
     if (scope.projectId) {
-      await requireProjectAccess(ctx, scope.projectId, args.userId);
+      await requireScopeWriteAccess(ctx, scope.projectId, args.userId);
     }
     const globalId = generateGlobalId();
     const title = normalizeString(args.title);