@lucern/graph-primitives 1.0.28 → 1.0.30

package/dist/epistemicNodes.mutations.js

@@ -1,15 +1,19 @@
-import { v } from 'convex/values';
-import { requireProjectAccess } from '@lucern/access-control/access';
+import { requireScopeWriteAccess } from '@lucern/access-control/access';
 import { permissiveReturn } from '@lucern/contracts/schema-helpers/validators';
-import { componentsGeneric, anyApi, mutationGeneric } from 'convex/server';
-import { isNodeType, getLayerForNodeType } from '@lucern/contracts/schema-helpers/spine/tables/epistemicNodes';
-import { assertUuidV7Identity } from '@lucern/contracts/ids';
+import { v } from 'convex/values';
+import { unsafeConvexAnyApi } from '@lucern/contracts/convex/unsafeAnyApi';
+import { componentsGeneric, mutationGeneric } from 'convex/server';
 import '@lucern/contracts';
+import { assertUuidV7Identity } from '@lucern/contracts/ids';
+import { isNodeType, getLayerForNodeType } from '@lucern/contracts/schema-helpers/spine/tables/epistemicNodes';
 
 // src/epistemicNodes.mutations.ts
-var api = anyApi;
+var unsafeApi = unsafeConvexAnyApi(
+  "graph-primitives top-level module bundle lacks a committed Convex _generated/api surface"
+);
+var api = unsafeApi;
 componentsGeneric();
-var internal = anyApi;
+var internal = unsafeApi;
 var mutation = mutationGeneric;
 
 // src/debug.ts
@@ -23,6 +27,119 @@ function debugGraphPrimitiveFallback(message, context) {
   }
   console.debug(message, context ?? {});
 }
+function insertEpistemicNode(ctx, doc) {
+  assertUuidV7Identity("epistemicNodes", doc.globalId);
+  return ctx.db.insert("epistemicNodes", doc);
+}
+
+// src/epistemicNodes.helpers.ts
+function buildNodeStatusSuccessResult() {
+  return { success: true };
+}
+function buildNodeArchivedResult() {
+  return {
+    success: true,
+    effectiveStatus: "archived"
+  };
+}
+v.union(
+  v.literal("L4"),
+  v.literal("L3"),
+  v.literal("L2"),
+  v.literal("L1"),
+  v.literal("ontological"),
+  v.literal("organizational")
+);
+v.union(v.literal("decision"));
+v.union(
+  v.literal("belief"),
+  v.literal("question"),
+  v.literal("theme"),
+  v.literal("deal")
+);
+v.union(
+  v.literal("claim"),
+  v.literal("evidence"),
+  v.literal("synthesis")
+);
+v.union(
+  v.literal("atomic_fact"),
+  v.literal("excerpt"),
+  v.literal("source")
+);
+v.union(
+  // L4: Audit targets
+  v.literal("decision"),
+  // L3: Traversal anchors
+  v.literal("belief"),
+  v.literal("question"),
+  v.literal("theme"),
+  v.literal("deal"),
+  // L2: Compression boundary
+  v.literal("claim"),
+  v.literal("evidence"),
+  v.literal("synthesis"),
+  v.literal("answer"),
+  // L1: Terminal leaves
+  v.literal("atomic_fact"),
+  v.literal("excerpt"),
+  v.literal("source")
+);
+v.union(
+  v.literal("company"),
+  v.literal("person"),
+  v.literal("investor"),
+  v.literal("function"),
+  v.literal("value_chain")
+);
+v.union(v.literal("topic"));
+var nodeTypeValidator = v.union(
+  // L4: Audit targets
+  v.literal("decision"),
+  // L3: Traversal anchors
+  v.literal("belief"),
+  v.literal("question"),
+  v.literal("theme"),
+  v.literal("deal"),
+  // L2: Compression boundary
+  v.literal("claim"),
+  v.literal("evidence"),
+  v.literal("synthesis"),
+  v.literal("answer"),
+  // L1: Terminal leaves
+  v.literal("atomic_fact"),
+  v.literal("excerpt"),
+  v.literal("source"),
+  // Ontological
+  v.literal("company"),
+  v.literal("person"),
+  v.literal("investor"),
+  v.literal("function"),
+  v.literal("value_chain"),
+  // Organizational
+  v.literal("topic")
+);
+var sourceTypeValidator = v.union(
+  v.literal("human"),
+  v.literal("ai_extracted"),
+  v.literal("ai_generated"),
+  v.literal("imported"),
+  v.literal("system")
+  // System-generated (migrations, classifiers)
+);
+var statusValidator = v.union(
+  v.literal("active"),
+  v.literal("superseded"),
+  v.literal("archived"),
+  v.literal("deleted")
+);
+var verificationStatusValidator = v.union(
+  v.literal("unverified"),
+  v.literal("human_verified"),
+  v.literal("ai_verified"),
+  v.literal("contradicted"),
+  v.literal("outdated")
+);
 
 // src/graphTypes.ts
 function getNodeLayer(nodeType) {
@@ -59,6 +176,209 @@ function getNodeLayer(nodeType) {
   console.warn(`[GraphTypes] Unknown nodeType "${nodeType}", defaulting to L2`);
   return "L2";
 }
+
+// src/beliefLifecycle.ts
+var RESOLVED_PREDICTION_OUTCOMES = [
+  "confirmed",
+  "disconfirmed",
+  "partial",
+  "expired"
+];
+function hasResolvedPredictionOutcome(predictionMeta) {
+  if (!predictionMeta || typeof predictionMeta !== "object") {
+    return false;
+  }
+  const outcome = predictionMeta.outcome;
+  return typeof outcome === "string" && RESOLVED_PREDICTION_OUTCOMES.includes(outcome);
+}
+
+// src/invariantEnforcement.ts
+var FORBIDDEN_GENERIC_BELIEF_METADATA_KEYS = /* @__PURE__ */ new Set([
+  "beliefStatus",
+  "epistemicStatus",
+  "forkedBy",
+  "forkedFrom",
+  "forkReason",
+  "forkTimestamp",
+  "status",
+  "supersededBy",
+  "supersedes"
+]);
+var ONTOLOGICAL_NODE_TYPES = /* @__PURE__ */ new Set([
+  "company",
+  "person",
+  "investor",
+  "function",
+  "value_chain"
+]);
+function throwInvariantError(args) {
+  const error = new Error(args.message);
+  error.status = args.status ?? 409;
+  error.code = args.code ?? "INVARIANT_VIOLATION";
+  error.invariantCode = args.invariantCode;
+  error.suggestion = args.suggestion;
+  error.details = args.details;
+  throw error;
+}
+function isBeliefNode(node) {
+  return node?.nodeType === "belief";
+}
+function isOntologicalNode(node) {
+  return typeof node?.nodeType === "string" && ONTOLOGICAL_NODE_TYPES.has(node.nodeType);
+}
+function isScoredBeliefNode(node) {
+  if (!isBeliefNode(node)) {
+    return false;
+  }
+  const metadata = node.metadata && typeof node.metadata === "object" ? node.metadata : void 0;
+  const numericConfidence = typeof node.confidence === "number" && Number.isFinite(node.confidence);
+  if (numericConfidence) {
+    return true;
+  }
+  return hasResolvedPredictionOutcome(node.predictionMeta) || hasResolvedPredictionOutcome(metadata?.predictionMeta);
+}
+function getForbiddenMetadataKeys(metadata) {
+  if (!metadata || typeof metadata !== "object" || Array.isArray(metadata)) {
+    return [];
+  }
+  return Object.keys(metadata).filter(
+    (key) => FORBIDDEN_GENERIC_BELIEF_METADATA_KEYS.has(key)
+  );
+}
+function assertBeliefNodeGenericUpdateAllowed(args) {
+  if (!isBeliefNode(args.node)) {
+    return;
+  }
+  if (Object.hasOwn(args.updates, "confidence")) {
+    throwInvariantError({
+      message: "Belief confidence is append-only. Generic node updates cannot set confidence directly.",
+      invariantCode: "belief.confidence_append_only",
+      suggestion: "Use epistemicBeliefs.appendSlScoring() so the beliefConfidence ledger and audit trail are updated together.",
+      details: { mutationName: args.mutationName, nodeId: args.node._id }
+    });
+  }
+  if (Object.hasOwn(args.updates, "status")) {
+    throwInvariantError({
+      message: "Belief status transitions must use the dedicated belief lifecycle APIs.",
+      invariantCode: "belief.status_transition_requires_belief_api",
+      suggestion: "Use epistemicBeliefs.updateStatus() or epistemicBeliefs.archive() so status transitions emit the correct audit event.",
+      details: { mutationName: args.mutationName, nodeId: args.node._id }
+    });
+  }
+  const forbiddenMetadataKeys = getForbiddenMetadataKeys(args.updates.metadata);
+  if (forbiddenMetadataKeys.length > 0) {
+    throwInvariantError({
+      message: "Belief lineage and lifecycle metadata cannot be rewritten through generic node updates.",
+      invariantCode: "belief.lineage_requires_fork_belief",
+      suggestion: "Use epistemicBeliefs.forkBelief() for lineage changes and dedicated belief lifecycle mutations for status changes.",
+      details: {
+        mutationName: args.mutationName,
+        nodeId: args.node._id,
+        forbiddenMetadataKeys
+      }
+    });
+  }
+  if (isScoredBeliefNode(args.node) && (Object.hasOwn(args.updates, "canonicalText") || Object.hasOwn(args.updates, "contentHash"))) {
+    throwInvariantError({
+      message: "Cannot refine a scored belief in place. Scored formulations are immutable.",
+      invariantCode: "belief.formulation_immutable_after_scoring",
+      suggestion: "Use epistemicBeliefs.forkBelief() to evolve the formulation while preserving lineage.",
+      details: { mutationName: args.mutationName, nodeId: args.node._id }
+    });
+  }
+}
+function assertBeliefNodeArchiveAllowed(args) {
+  if (!isBeliefNode(args.node)) {
+    return;
+  }
+  throwInvariantError({
+    message: "Belief archiving must go through the dedicated belief lifecycle API.",
+    invariantCode: "belief.status_transition_requires_belief_api",
+    suggestion: "Use epistemicBeliefs.archive() so the belief lifecycle audit trail stays consistent.",
+    details: { mutationName: args.mutationName, nodeId: args.node._id }
+  });
+}
+function assertBeliefNodeVerifyAllowed(args) {
+  if (!isBeliefNode(args.node) || args.confidence === void 0) {
+    return;
+  }
+  throwInvariantError({
+    message: "Belief verification cannot set confidence directly. Confidence changes must stay append-only.",
+    invariantCode: "belief.confidence_append_only",
+    suggestion: "Call epistemicBeliefs.appendSlScoring() after verification so the confidence history is preserved.",
+    details: { mutationName: args.mutationName, nodeId: args.node._id }
+  });
+}
+function assertBeliefNodeSupersedeAllowed(args) {
+  if (!isBeliefNode(args.node)) {
+    return;
+  }
+  throwInvariantError({
+    message: "Belief lineage changes must use forkBelief(), not the generic supersede path.",
+    invariantCode: "belief.lineage_requires_fork_belief",
+    suggestion: "Use epistemicBeliefs.forkBelief() so the child belief, supersedes edge, and audit trail are created together.",
+    details: { mutationName: args.mutationName, nodeId: args.node._id }
+  });
+}
+function assertOntologicalNodeGenericCreateAllowed(args) {
+  if (!ONTOLOGICAL_NODE_TYPES.has(args.nodeType)) {
+    return;
+  }
+  throwInvariantError({
+    message: "Ontological entities must be created through the dedicated entity lifecycle API.",
+    invariantCode: "entity.create_requires_entity_lifecycle",
+    suggestion: "Use entityLifecycle.createEntity() so tenant-global canonical scope and deduplication are enforced.",
+    details: {
+      mutationName: args.mutationName,
+      nodeType: args.nodeType
+    }
+  });
+}
+function assertOntologicalNodeGenericUpdateAllowed(args) {
+  if (!isOntologicalNode(args.node)) {
+    return;
+  }
+  throwInvariantError({
+    message: "Ontological entities must be updated through the dedicated entity lifecycle API.",
+    invariantCode: "entity.update_requires_entity_lifecycle",
+    suggestion: "Use entityLifecycle.updateEntityAttributes() so canonical entity mutations stay type-safe and audited.",
+    details: {
+      mutationName: args.mutationName,
+      nodeId: args.node._id,
+      nodeType: args.node.nodeType
+    }
+  });
+}
+function assertOntologicalNodeArchiveAllowed(args) {
+  if (!isOntologicalNode(args.node)) {
+    return;
+  }
+  throwInvariantError({
+    message: "Ontological entities must be archived through the dedicated entity lifecycle API.",
+    invariantCode: "entity.archive_requires_entity_lifecycle",
+    suggestion: "Use entityLifecycle.archiveEntity() so entity archival emits the correct audit trail and review hooks.",
+    details: {
+      mutationName: args.mutationName,
+      nodeId: args.node._id,
+      nodeType: args.node.nodeType
+    }
+  });
+}
+function assertOntologicalNodeSupersedeAllowed(args) {
+  if (!isOntologicalNode(args.node)) {
+    return;
+  }
+  throwInvariantError({
+    message: "Ontological entities do not use the generic supersede path.",
+    invariantCode: "entity.supersede_requires_entity_lifecycle",
+    suggestion: "Use entityLifecycle.updateEntityAttributes() to edit an entity in place or entityLifecycle.mergeEntities() to collapse duplicates.",
+    details: {
+      mutationName: args.mutationName,
+      nodeId: args.node._id,
+      nodeType: args.node.nodeType
+    }
+  });
+}
 var LEGACY_SCOPE_FIELD = "graphScopeProjectId";
 async function resolveTopicNodeScopeOrNull(ctx, ref) {
   if (!ctx?.db || typeof ctx.db.query !== "function") {
@@ -93,13 +413,15 @@ function asMappedProjectId(topic) {
   if (!topic) {
     return;
   }
-  const directLegacyProjectId = normalizeScopeValue(topic[LEGACY_SCOPE_FIELD]);
+  const directLegacyProjectId = normalizeScopeValue(
+    topic[LEGACY_SCOPE_FIELD]
+  );
   if (directLegacyProjectId) {
     return directLegacyProjectId;
   }
   const metadata = topic.metadata || {};
   const candidate = metadata[LEGACY_SCOPE_FIELD] || metadata.legacyProjectId || metadata.projectId || metadata.scopeProjectId;
-  return candidate ? candidate : void 0;
+  return typeof candidate === "string" ? normalizeScopeValue(candidate) : void 0;
 }
 function normalizeScopeValue(value) {
   if (typeof value !== "string") {
@@ -124,8 +446,9 @@ function pickPrimaryTopic(candidates) {
   })[0];
 }
 async function findTopicsByScopeAlias(ctx, scopeId) {
+  const query = ctx.db.query("topics");
   try {
-    return await ctx.db.query("topics").withIndex(
+    return await query.withIndex(
       "by_graph_scope_project",
       (q) => q.eq(LEGACY_SCOPE_FIELD, scopeId)
     ).collect();
@@ -137,7 +460,7 @@ async function findTopicsByScopeAlias(ctx, scopeId) {
         scopeId
       }
     );
-    const topics = await ctx.db.query("topics").collect();
+    const topics = await query.collect();
     return topics.filter((topic) => {
       const normalizedGlobalId = normalizeScopeValue(topic.globalId);
       const mappedProjectId = asMappedProjectId(topic);
@@ -193,344 +516,119 @@ async function resolveInheritedWorkspaceScope(ctx, topic) {
   let current = topic;
   for (let i = 0; i < MAX_DEPTH && current?.parentTopicId; i++) {
     current = await ctx.db.get(current.parentTopicId);
-    if (!current) break;
+    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) {
-    let topic = null;
-    try {
-      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));
-    }
-    if (!topic) {
-      topic = pickPrimaryTopic(
-        await findTopicsByScopeAlias(ctx, String(args.topicId))
-      ) ?? 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);
-    const mapped = asMappedProjectId(topic);
-    if (mapped) {
-      return {
-        topicId: topic._id,
-        projectId: mapped,
-        tenantId: inherited.tenantId,
-        workspaceId: inherited.workspaceId,
-        source: "topic"
-      };
-    }
-    return {
-      topicId: topic._id,
-      tenantId: inherited.tenantId,
-      workspaceId: inherited.workspaceId,
-      source: "topic"
-    };
-  }
-  if (args.projectId) {
-    let directTopic = null;
-    try {
-      directTopic = await ctx.db.get(
-        args.projectId
-      );
-    } catch (error) {
-      debugGraphPrimitiveFallback(
-        "[topicScope] Failed to load direct project topic",
-        {
-          error,
-          projectId: args.projectId
-        }
-      );
-    }
-    if (directTopic) {
-      const inherited = await resolveInheritedWorkspaceScope(ctx, directTopic);
-      const mapped = asMappedProjectId(directTopic);
-      return {
-        topicId: directTopic._id,
-        projectId: mapped ?? args.projectId,
-        tenantId: inherited.tenantId,
-        workspaceId: inherited.workspaceId,
-        source: "topic_inferred"
-      };
-    }
-    directTopic = await tryResolveHostTopicByLegacyScope(ctx, args.projectId);
-    if (directTopic) {
-      const inherited = await resolveInheritedWorkspaceScope(ctx, directTopic);
-      const mapped = asMappedProjectId(directTopic);
-      return {
-        topicId: directTopic._id,
-        projectId: mapped ?? args.projectId,
-        tenantId: inherited.tenantId,
-        workspaceId: inherited.workspaceId,
-        source: "topic_inferred"
-      };
-    }
-    const topics = await findTopicsByScopeAlias(ctx, args.projectId);
-    const primary = pickPrimaryTopic(topics);
-    if (primary) {
-      const inherited = await resolveInheritedWorkspaceScope(ctx, primary);
-      return {
-        topicId: primary._id,
-        projectId: args.projectId,
-        tenantId: inherited.tenantId,
-        workspaceId: inherited.workspaceId,
-        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.`
-    );
-  }
-  throw new Error(
-    "Missing scope: provide topicId (preferred) or legacy projectId alias."
-  );
-}
-var optionalScopeArgs = {
-  projectId: v.optional(v.string()),
-  topicId: v.optional(v.string())
-};
-
-// src/beliefLifecycle.ts
-var RESOLVED_PREDICTION_OUTCOMES = [
-  "confirmed",
-  "disconfirmed",
-  "partial",
-  "expired"
-];
-function hasResolvedPredictionOutcome(predictionMeta) {
-  if (!predictionMeta || typeof predictionMeta !== "object") {
-    return false;
-  }
-  const outcome = predictionMeta.outcome;
-  return typeof outcome === "string" && RESOLVED_PREDICTION_OUTCOMES.includes(outcome);
-}
-
-// src/invariantEnforcement.ts
-var FORBIDDEN_GENERIC_BELIEF_METADATA_KEYS = /* @__PURE__ */ new Set([
-  "beliefStatus",
-  "epistemicStatus",
-  "forkedBy",
-  "forkedFrom",
-  "forkReason",
-  "forkTimestamp",
-  "status",
-  "supersededBy",
-  "supersedes"
-]);
-var ONTOLOGICAL_NODE_TYPES = /* @__PURE__ */ new Set([
-  "company",
-  "person",
-  "investor",
-  "function",
-  "value_chain"
-]);
-function throwInvariantError(args) {
-  const error = new Error(args.message);
-  error.status = args.status ?? 409;
-  error.code = args.code ?? "INVARIANT_VIOLATION";
-  error.invariantCode = args.invariantCode;
-  error.suggestion = args.suggestion;
-  error.details = args.details;
-  throw error;
-}
-function isBeliefNode(node) {
-  return node?.nodeType === "belief";
-}
-function isOntologicalNode(node) {
-  return typeof node?.nodeType === "string" && ONTOLOGICAL_NODE_TYPES.has(node.nodeType);
-}
-function isScoredBeliefNode(node) {
-  if (!isBeliefNode(node)) {
-    return false;
-  }
-  const metadata = node.metadata && typeof node.metadata === "object" ? node.metadata : void 0;
-  const numericConfidence = typeof node.confidence === "number" && Number.isFinite(node.confidence);
-  if (numericConfidence) {
-    return true;
-  }
-  return hasResolvedPredictionOutcome(node.predictionMeta) || hasResolvedPredictionOutcome(metadata?.predictionMeta);
-}
-function getForbiddenMetadataKeys(metadata) {
-  if (!metadata || typeof metadata !== "object" || Array.isArray(metadata)) {
-    return [];
-  }
-  return Object.keys(metadata).filter(
-    (key) => FORBIDDEN_GENERIC_BELIEF_METADATA_KEYS.has(key)
-  );
-}
-function assertBeliefNodeGenericUpdateAllowed(args) {
-  if (!isBeliefNode(args.node)) {
-    return;
-  }
-  if (Object.hasOwn(args.updates, "confidence")) {
-    throwInvariantError({
-      message: "Belief confidence is append-only. Generic node updates cannot set confidence directly.",
-      invariantCode: "belief.confidence_append_only",
-      suggestion: "Use epistemicBeliefs.appendSlScoring() so the beliefConfidence ledger and audit trail are updated together.",
-      details: { mutationName: args.mutationName, nodeId: args.node._id }
-    });
-  }
-  if (Object.hasOwn(args.updates, "status")) {
-    throwInvariantError({
-      message: "Belief status transitions must use the dedicated belief lifecycle APIs.",
-      invariantCode: "belief.status_transition_requires_belief_api",
-      suggestion: "Use epistemicBeliefs.updateStatus() or epistemicBeliefs.archive() so status transitions emit the correct audit event.",
-      details: { mutationName: args.mutationName, nodeId: args.node._id }
-    });
-  }
-  const forbiddenMetadataKeys = getForbiddenMetadataKeys(args.updates.metadata);
-  if (forbiddenMetadataKeys.length > 0) {
-    throwInvariantError({
-      message: "Belief lineage and lifecycle metadata cannot be rewritten through generic node updates.",
-      invariantCode: "belief.lineage_requires_fork_belief",
-      suggestion: "Use epistemicBeliefs.forkBelief() for lineage changes and dedicated belief lifecycle mutations for status changes.",
-      details: {
-        mutationName: args.mutationName,
-        nodeId: args.node._id,
-        forbiddenMetadataKeys
-      }
-    });
-  }
-  if (isScoredBeliefNode(args.node) && (Object.hasOwn(args.updates, "canonicalText") || Object.hasOwn(args.updates, "contentHash"))) {
-    throwInvariantError({
-      message: "Cannot refine a scored belief in place. Scored formulations are immutable.",
-      invariantCode: "belief.formulation_immutable_after_scoring",
-      suggestion: "Use epistemicBeliefs.forkBelief() to evolve the formulation while preserving lineage.",
-      details: { mutationName: args.mutationName, nodeId: args.node._id }
-    });
-  }
-}
-function assertBeliefNodeArchiveAllowed(args) {
-  if (!isBeliefNode(args.node)) {
-    return;
+    if (tenantId && workspaceId) {
+      break;
+    }
   }
-  throwInvariantError({
-    message: "Belief archiving must go through the dedicated belief lifecycle API.",
-    invariantCode: "belief.status_transition_requires_belief_api",
-    suggestion: "Use epistemicBeliefs.archive() so the belief lifecycle audit trail stays consistent.",
-    details: { mutationName: args.mutationName, nodeId: args.node._id }
-  });
+  return { tenantId, workspaceId };
 }
-function assertBeliefNodeVerifyAllowed(args) {
-  if (!isBeliefNode(args.node) || args.confidence === void 0) {
-    return;
+async function resolveTopicProjectScope(ctx, args) {
+  if (args.topicId) {
+    return await resolveScopeFromTopicId(ctx, args.topicId);
   }
-  throwInvariantError({
-    message: "Belief verification cannot set confidence directly. Confidence changes must stay append-only.",
-    invariantCode: "belief.confidence_append_only",
-    suggestion: "Call epistemicBeliefs.appendSlScoring() after verification so the confidence history is preserved.",
-    details: { mutationName: args.mutationName, nodeId: args.node._id }
-  });
-}
-function assertBeliefNodeSupersedeAllowed(args) {
-  if (!isBeliefNode(args.node)) {
-    return;
+  if (args.projectId) {
+    return await resolveScopeFromLegacyProjectId(ctx, args.projectId);
   }
-  throwInvariantError({
-    message: "Belief lineage changes must use forkBelief(), not the generic supersede path.",
-    invariantCode: "belief.lineage_requires_fork_belief",
-    suggestion: "Use epistemicBeliefs.forkBelief() so the child belief, supersedes edge, and audit trail are created together.",
-    details: { mutationName: args.mutationName, nodeId: args.node._id }
-  });
+  throw new Error(
+    "Missing scope: provide topicId (preferred) or legacy projectId alias."
+  );
 }
-function assertOntologicalNodeGenericCreateAllowed(args) {
-  if (!ONTOLOGICAL_NODE_TYPES.has(args.nodeType)) {
-    return;
+async function resolveScopeFromTopicId(ctx, topicId) {
+  const topic = await resolveTopicDocFromTopicId(ctx, topicId);
+  if (topic) {
+    return await buildTopicScope(ctx, topic, "topic");
   }
-  throwInvariantError({
-    message: "Ontological entities must be created through the dedicated entity lifecycle API.",
-    invariantCode: "entity.create_requires_entity_lifecycle",
-    suggestion: "Use entityLifecycle.createEntity() so tenant-global canonical scope and deduplication are enforced.",
-    details: {
-      mutationName: args.mutationName,
-      nodeType: args.nodeType
-    }
-  });
-}
-function assertOntologicalNodeGenericUpdateAllowed(args) {
-  if (!isOntologicalNode(args.node)) {
-    return;
+  const nodeScope = await resolveTopicNodeScopeOrNull(ctx, String(topicId));
+  if (nodeScope) {
+    return nodeScope;
   }
-  throwInvariantError({
-    message: "Ontological entities must be updated through the dedicated entity lifecycle API.",
-    invariantCode: "entity.update_requires_entity_lifecycle",
-    suggestion: "Use entityLifecycle.updateEntityAttributes() so canonical entity mutations stay type-safe and audited.",
-    details: {
-      mutationName: args.mutationName,
-      nodeId: args.node._id,
-      nodeType: args.node.nodeType
-    }
+  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;
 }
-function assertOntologicalNodeArchiveAllowed(args) {
-  if (!isOntologicalNode(args.node)) {
-    return;
+async function resolveScopeFromLegacyProjectId(ctx, legacyProjectId) {
+  const directTopic = await resolveDirectLegacyProjectTopic(
+    ctx,
+    legacyProjectId
+  );
+  if (directTopic) {
+    return await buildTopicScope(ctx, directTopic, "topic_inferred", {
+      fallbackProjectId: legacyProjectId
+    });
   }
-  throwInvariantError({
-    message: "Ontological entities must be archived through the dedicated entity lifecycle API.",
-    invariantCode: "entity.archive_requires_entity_lifecycle",
-    suggestion: "Use entityLifecycle.archiveEntity() so entity archival emits the correct audit trail and review hooks.",
-    details: {
-      mutationName: args.mutationName,
-      nodeId: args.node._id,
-      nodeType: args.node.nodeType
-    }
+  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);
 }
-function assertOntologicalNodeSupersedeAllowed(args) {
-  if (!isOntologicalNode(args.node)) {
-    return;
+async function tryReadTopicDoc(ctx, id, log) {
+  try {
+    return await ctx.db.get(id);
+  } catch (error) {
+    debugGraphPrimitiveFallback(log.failureLog, {
+      error,
+      [log.idLogKey]: id
+    });
+    return null;
   }
-  throwInvariantError({
-    message: "Ontological entities do not use the generic supersede path.",
-    invariantCode: "entity.supersede_requires_entity_lifecycle",
-    suggestion: "Use entityLifecycle.updateEntityAttributes() to edit an entity in place or entityLifecycle.mergeEntities() to collapse duplicates.",
-    details: {
-      mutationName: args.mutationName,
-      nodeId: args.node._id,
-      nodeType: args.node.nodeType
-    }
-  });
 }
+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
+  };
+}
+var optionalScopeArgs = {
+  projectId: v.optional(v.string()),
+  topicId: v.optional(v.string())
+};
 function normalizeScopeValue2(value) {
   if (typeof value !== "string") {
     return;
@@ -569,7 +667,7 @@ function assertWorkspaceScopedEpistemicNodeScope(args) {
   });
 }
 function resolveRuntimePackMutationContext(args) {
-  if (!args.runtimeToolName && !args.runtimePackKey && !args.runtimePackInstallScope) {
+  if (!(args.runtimeToolName || args.runtimePackKey || args.runtimePackInstallScope)) {
     return;
   }
   return {
@@ -602,121 +700,116 @@ function assertTenantPackWorkspaceMutationAllowed(args) {
   });
 }
 
-// src/epistemicNodes.helpers.ts
-function buildNodeStatusSuccessResult() {
-  return { success: true };
+// src/epistemicNodes.mutations.ts
+var optionalNodeScopeArgs = optionalScopeArgs;
+var EPISTEMIC_LAYERS = /* @__PURE__ */ new Set([
+  "L4",
+  "L3",
+  "L2",
+  "L1",
+  "ontological",
+  "organizational"
+]);
+function readOptionalString(value) {
+  return typeof value === "string" && value.trim().length > 0 ? value : void 0;
 }
-function buildNodeArchivedResult() {
-  return {
-    success: true,
-    effectiveStatus: "archived"
-  };
+function readOptionalNumber(value) {
+  return typeof value === "number" && Number.isFinite(value) ? value : void 0;
 }
-v.union(
-  v.literal("L4"),
-  v.literal("L3"),
-  v.literal("L2"),
-  v.literal("L1"),
-  v.literal("ontological"),
-  v.literal("organizational")
-);
-v.union(v.literal("decision"));
-v.union(
-  v.literal("belief"),
-  v.literal("question"),
-  v.literal("theme"),
-  v.literal("deal")
-);
-v.union(
-  v.literal("claim"),
-  v.literal("evidence"),
-  v.literal("synthesis")
-);
-v.union(
-  v.literal("atomic_fact"),
-  v.literal("excerpt"),
-  v.literal("source")
-);
-v.union(
-  // L4: Audit targets
-  v.literal("decision"),
-  // L3: Traversal anchors
-  v.literal("belief"),
-  v.literal("question"),
-  v.literal("theme"),
-  v.literal("deal"),
-  // L2: Compression boundary
-  v.literal("claim"),
-  v.literal("evidence"),
-  v.literal("synthesis"),
-  v.literal("answer"),
-  // L1: Terminal leaves
-  v.literal("atomic_fact"),
-  v.literal("excerpt"),
-  v.literal("source")
-);
-v.union(
-  v.literal("company"),
-  v.literal("person"),
-  v.literal("investor"),
-  v.literal("function"),
-  v.literal("value_chain")
-);
-v.union(v.literal("topic"));
-var nodeTypeValidator = v.union(
-  // L4: Audit targets
-  v.literal("decision"),
-  // L3: Traversal anchors
-  v.literal("belief"),
-  v.literal("question"),
-  v.literal("theme"),
-  v.literal("deal"),
-  // L2: Compression boundary
-  v.literal("claim"),
-  v.literal("evidence"),
-  v.literal("synthesis"),
-  v.literal("answer"),
-  // L1: Terminal leaves
-  v.literal("atomic_fact"),
-  v.literal("excerpt"),
-  v.literal("source"),
-  // Ontological
-  v.literal("company"),
-  v.literal("person"),
-  v.literal("investor"),
-  v.literal("function"),
-  v.literal("value_chain"),
-  // Organizational
-  v.literal("topic")
-);
-var sourceTypeValidator = v.union(
-  v.literal("human"),
-  v.literal("ai_extracted"),
-  v.literal("ai_generated"),
-  v.literal("imported"),
-  v.literal("system")
-  // System-generated (migrations, classifiers)
-);
-var statusValidator = v.union(
-  v.literal("active"),
-  v.literal("superseded"),
-  v.literal("archived"),
-  v.literal("deleted")
-);
-var verificationStatusValidator = v.union(
-  v.literal("unverified"),
-  v.literal("human_verified"),
-  v.literal("ai_verified"),
-  v.literal("contradicted"),
-  v.literal("outdated")
-);
-async function insertEpistemicNode(ctx, doc) {
-  assertUuidV7Identity("epistemicNodes", doc.globalId);
-  return ctx.db.insert("epistemicNodes", doc);
+function readConvexId(value) {
+  const normalized = readOptionalString(value);
+  return normalized ? normalized : null;
+}
+function readRecord(value) {
+  return value && typeof value === "object" && !Array.isArray(value) ? value : null;
+}
+function readStringArray(value) {
+  return Array.isArray(value) && value.every((item) => typeof item === "string") ? value : void 0;
+}
+function readEpistemicLayer(value) {
+  const layer = readOptionalString(value);
+  return layer && EPISTEMIC_LAYERS.has(layer) ? layer : void 0;
+}
+function readEpistemicNodeRow(value) {
+  const record = readRecord(value);
+  if (!record) {
+    return null;
+  }
+  const id = readConvexId(record._id);
+  const nodeType = readOptionalString(record.nodeType);
+  if (!(id && nodeType)) {
+    return null;
+  }
+  const node = { _id: id, nodeType };
+  const canonicalText = readOptionalString(record.canonicalText);
+  if (canonicalText !== void 0) {
+    node.canonicalText = canonicalText;
+  }
+  const confidence = readOptionalNumber(record.confidence);
+  if (confidence !== void 0) {
+    node.confidence = confidence;
+  }
+  const content = readOptionalString(record.content);
+  if (content !== void 0) {
+    node.content = content;
+  }
+  const contentType = readOptionalString(record.contentType);
+  if (contentType !== void 0) {
+    node.contentType = contentType;
+  }
+  const createdBy = readOptionalString(record.createdBy);
+  if (createdBy !== void 0) {
+    node.createdBy = createdBy;
+  }
+  const epistemicLayer = readEpistemicLayer(record.epistemicLayer);
+  if (epistemicLayer !== void 0) {
+    node.epistemicLayer = epistemicLayer;
+  }
+  const metadata = readRecord(record.metadata);
+  if (metadata) {
+    node.metadata = metadata;
+  }
+  const projectId = readOptionalString(record.projectId);
+  if (projectId !== void 0) {
+    node.projectId = projectId;
+  }
+  const status = readOptionalString(record.status);
+  if (status !== void 0) {
+    node.status = status;
+  }
+  const tags = readStringArray(record.tags);
+  if (tags !== void 0) {
+    node.tags = tags;
+  }
+  const tenantId = readOptionalString(record.tenantId);
+  if (tenantId !== void 0) {
+    node.tenantId = tenantId;
+  }
+  const title = readOptionalString(record.title);
+  if (title !== void 0) {
+    node.title = title;
+  }
+  const topicId = readOptionalString(record.topicId);
+  if (topicId !== void 0) {
+    node.topicId = topicId;
+  }
+  const verificationStatus = readOptionalString(record.verificationStatus);
+  if (verificationStatus !== void 0) {
+    node.verificationStatus = verificationStatus;
+  }
+  const workspaceId = readOptionalString(record.workspaceId);
+  if (workspaceId !== void 0) {
+    node.workspaceId = workspaceId;
+  }
+  return node;
+}
+function requireEpistemicNodeRow(value, context) {
+  const node = readEpistemicNodeRow(value);
+  if (!node) {
+    throw new Error(`${context} requires a stored epistemic node.`);
+  }
+  return node;
 }
-
-// src/epistemicNodes.mutations.ts
-var optionalNodeScopeArgs = optionalScopeArgs;
 var create = mutation({
   args: {
     globalId: v.string(),
@@ -762,8 +855,9 @@ var create = mutation({
       mutationName: "epistemicNodes.create"
     });
     const existing = await ctx.db.query("epistemicNodes").withIndex("by_contentHash", (q) => q.eq("contentHash", args.contentHash)).first();
-    if (existing && existing.status === "active") {
-      return { nodeId: existing._id, isDuplicate: true };
+    const existingNode = readEpistemicNodeRow(existing);
+    if (existingNode?.status === "active") {
+      return { nodeId: existingNode._id, isDuplicate: true };
     }
     const epistemicLayer = getNodeLayer(args.nodeType);
     const resolvedScope = args.topicId || args.projectId ? await resolveTopicProjectScope(ctx, {
@@ -878,12 +972,12 @@ var update = mutation({
   returns: permissiveReturn,
   handler: async (ctx, args) => {
     const { nodeId, userId, ...updates } = args;
-    const node = await ctx.db.get(nodeId);
-    if (!node) {
-      throw new Error("Node not found");
-    }
+    const node = requireEpistemicNodeRow(
+      await ctx.db.get(nodeId),
+      "Update node"
+    );
     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)) {
@@ -910,7 +1004,7 @@ var update = mutation({
         entityId: String(nodeId),
         changeType: "updated",
         changedAt: Date.now(),
-        changedBy: userId || node.createdBy,
+        changedBy: userId ?? node.createdBy ?? "system:update",
         isAgent: false,
         previousState: {
           status: node.status,
@@ -939,12 +1033,12 @@ var supersede = mutation({
   },
   returns: permissiveReturn,
   handler: async (ctx, args) => {
-    const oldNode = await ctx.db.get(args.oldNodeId);
-    if (!oldNode) {
-      throw new Error("Node not found");
-    }
+    const oldNode = requireEpistemicNodeRow(
+      await ctx.db.get(args.oldNodeId),
+      "Supersede node"
+    );
     if (oldNode.projectId) {
-      await requireProjectAccess(ctx, oldNode.projectId, args.createdBy);
+      await requireScopeWriteAccess(ctx, oldNode.projectId, args.createdBy);
     }
     assertBeliefNodeSupersedeAllowed({
       node: oldNode,
@@ -974,7 +1068,10 @@ var supersede = mutation({
       verificationStatus: "unverified",
       // New version needs re-verification
       status: "active",
+      topicId: oldNode.topicId,
       projectId: oldNode.projectId,
+      tenantId: oldNode.tenantId,
+      workspaceId: oldNode.workspaceId,
       createdBy: args.createdBy,
       createdAt: now,
       updatedAt: now
@@ -1015,12 +1112,12 @@ var archive = mutation({
   },
   returns: permissiveReturn,
   handler: async (ctx, args) => {
-    const node = await ctx.db.get(args.nodeId);
-    if (!node) {
-      throw new Error("Node not found");
-    }
+    const node = requireEpistemicNodeRow(
+      await ctx.db.get(args.nodeId),
+      "Archive node"
+    );
     if (node.projectId && args.userId) {
-      await requireProjectAccess(ctx, node.projectId, args.userId);
+      await requireScopeWriteAccess(ctx, node.projectId, args.userId);
     }
     assertBeliefNodeArchiveAllowed({
       node,
@@ -1040,7 +1137,7 @@ var archive = mutation({
         entityId: String(args.nodeId),
         changeType: "archived",
         changedAt: Date.now(),
-        changedBy: args.userId || node.createdBy,
+        changedBy: args.userId ?? node.createdBy ?? "system:archive",
         isAgent: false,
         previousState: { status: node.status },
         newState: { status: "archived" },
@@ -1059,10 +1156,10 @@ var verify = mutation({
   },
   returns: permissiveReturn,
   handler: async (ctx, args) => {
-    const node = await ctx.db.get(args.nodeId);
-    if (!node) {
-      throw new Error("Node not found");
-    }
+    const node = requireEpistemicNodeRow(
+      await ctx.db.get(args.nodeId),
+      "Verify node"
+    );
     assertBeliefNodeVerifyAllowed({
       node,
       confidence: args.confidence,
@@ -1134,7 +1231,7 @@ var batchCreate = mutation({
   handler: async (ctx, args) => {
     const resolveNodeScope = async (node) => {
       if (!(node.topicId || node.projectId)) {
-        return void 0;
+        return;
       }
       try {
         return await resolveTopicProjectScope(ctx, {
@@ -1150,7 +1247,7 @@ var batchCreate = mutation({
             projectId: node.projectId
           }
         );
-        return void 0;
+        return;
       }
     };
     const now = Date.now();