@lucern/graph-primitives 1.0.0 → 1.0.1

package/dist/epistemicNodes.mutations.js

@@ -0,0 +1,1153 @@
+import { v } from 'convex/values';
+import { requireProjectAccess } 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';
+
+// src/epistemicNodes.mutations.ts
+var api = anyApi;
+componentsGeneric();
+var internal = anyApi;
+var mutation = mutationGeneric;
+
+// src/debug.ts
+function isGraphPrimitiveDebugEnabled() {
+  const env = globalThis.process?.env;
+  return env?.LUCERN_COMPAT_FALLBACK_DEBUG === "1" || env?.LUCERN_GRAPH_DEBUG === "1";
+}
+function debugGraphPrimitiveFallback(message, context) {
+  if (!isGraphPrimitiveDebugEnabled()) {
+    return;
+  }
+  console.debug(message, context ?? {});
+}
+
+// src/graphTypes.ts
+function getNodeLayer(nodeType) {
+  const L4_TYPES = ["decision"];
+  const L3_TYPES = ["belief", "question", "theme", "deal"];
+  const L2_TYPES = ["claim", "evidence", "synthesis", "answer"];
+  const L1_TYPES = ["atomic_fact", "excerpt", "source"];
+  const ONTOLOGICAL_TYPES = [
+    "company",
+    "person",
+    "investor",
+    "function",
+    "value_chain"
+  ];
+  const ORGANIZATIONAL_TYPES = ["topic"];
+  if (L4_TYPES.includes(nodeType)) {
+    return "L4";
+  }
+  if (L3_TYPES.includes(nodeType)) {
+    return "L3";
+  }
+  if (L2_TYPES.includes(nodeType)) {
+    return "L2";
+  }
+  if (L1_TYPES.includes(nodeType)) {
+    return "L1";
+  }
+  if (ONTOLOGICAL_TYPES.includes(nodeType)) {
+    return "ontological";
+  }
+  if (ORGANIZATIONAL_TYPES.includes(nodeType)) {
+    return "organizational";
+  }
+  console.warn(`[GraphTypes] Unknown nodeType "${nodeType}", defaulting to L2`);
+  return "L2";
+}
+var LEGACY_SCOPE_FIELD = "graphScopeProjectId";
+function asMappedProjectId(topic) {
+  if (!topic) {
+    return;
+  }
+  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;
+}
+function normalizeScopeValue(value) {
+  if (typeof value !== "string") {
+    return;
+  }
+  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) {
+  try {
+    return await ctx.db.query("topics").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 ctx.db.query("topics").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) {
+    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) {
+      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"
+      };
+    }
+    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.modulateConfidence() 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.modulateConfidence() 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
+    }
+  });
+}
+function normalizeScopeValue2(value) {
+  if (typeof value !== "string") {
+    return;
+  }
+  const normalized = value.trim();
+  return normalized.length > 0 ? normalized : void 0;
+}
+function throwWorkspaceIsolationError(args) {
+  const error = new Error(args.message);
+  error.status = 409;
+  error.code = "INVARIANT_VIOLATION";
+  error.invariantCode = args.invariantCode;
+  error.suggestion = args.suggestion;
+  error.details = args.details;
+  throw error;
+}
+function assertWorkspaceScopedEpistemicNodeScope(args) {
+  const layer = isNodeType(args.nodeType) ? getLayerForNodeType(args.nodeType) : void 0;
+  if (layer === "ontological") {
+    return;
+  }
+  const workspaceId = normalizeScopeValue2(args.scope.workspaceId);
+  if (workspaceId) {
+    return;
+  }
+  throwWorkspaceIsolationError({
+    message: "Workspace-scoped reasoning isolation requires workspaceId on non-ontological node creation.",
+    invariantCode: "workspace.scope_required_for_epistemic_nodes",
+    suggestion: "Resolve the topic/project scope through a workspace-bound topic before creating epistemic nodes.",
+    details: {
+      mutationName: args.mutationName,
+      nodeType: args.nodeType,
+      topicId: args.scope.topicId,
+      projectId: args.scope.projectId
+    }
+  });
+}
+function resolveRuntimePackMutationContext(args) {
+  if (!args.runtimeToolName && !args.runtimePackKey && !args.runtimePackInstallScope) {
+    return;
+  }
+  return {
+    toolName: args.runtimeToolName,
+    packKey: args.runtimePackKey,
+    packInstallScope: args.runtimePackInstallScope
+  };
+}
+function assertTenantPackWorkspaceMutationAllowed(args) {
+  if (!args.runtime?.packKey || args.runtime.packInstallScope !== "tenant") {
+    return;
+  }
+  const targetWorkspaceId = normalizeScopeValue2(args.target.workspaceId);
+  const targetLayer = typeof args.target.epistemicLayer === "string" ? args.target.epistemicLayer : void 0;
+  if (!targetWorkspaceId || targetLayer === "ontological") {
+    return;
+  }
+  throwWorkspaceIsolationError({
+    message: `Tenant-scoped pack "${args.runtime.packKey}" cannot mutate workspace-scoped reasoning state.`,
+    invariantCode: "workspace.tenant_pack_reasoning_write_forbidden",
+    suggestion: "Use a workspace-scoped pack for workspace-local graph mutations, or route the change through tenant-global canonical entity flows.",
+    details: {
+      mutationName: args.mutationName,
+      toolName: args.runtime.toolName,
+      packKey: args.runtime.packKey,
+      targetWorkspaceId,
+      targetNodeType: args.target.nodeType,
+      targetLayer
+    }
+  });
+}
+
+// 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/epistemicNodes.mutations.ts
+var optionalNodeScopeArgs = optionalScopeArgs;
+var create = mutation({
+  args: {
+    globalId: v.string(),
+    nodeType: nodeTypeValidator,
+    subtype: v.optional(v.string()),
+    // company: private|corporate|portfolio, investor: vc|lp|cvc|pe|etc
+    canonicalText: v.string(),
+    contentHash: v.string(),
+    content: v.optional(v.string()),
+    contentType: v.optional(v.string()),
+    title: v.optional(v.string()),
+    tags: v.optional(v.array(v.string())),
+    domain: v.optional(v.string()),
+    // For companies: website domain
+    metadata: v.optional(v.any()),
+    externalIds: v.optional(
+      v.object({
+        crunchbase: v.optional(v.string()),
+        linkedin: v.optional(v.string()),
+        pitchbook: v.optional(v.string()),
+        twitter: v.optional(v.string()),
+        website: v.optional(v.string())
+      })
+    ),
+    sourceType: sourceTypeValidator,
+    aiProvider: v.optional(v.string()),
+    extractedFromNodeId: v.optional(v.id("epistemicNodes")),
+    confidence: v.optional(v.number()),
+    verificationStatus: v.optional(verificationStatusValidator),
+    ...optionalNodeScopeArgs,
+    createdBy: v.string(),
+    runtimeToolName: v.optional(v.string()),
+    runtimePackKey: v.optional(v.string()),
+    runtimePackInstallScope: v.optional(
+      v.union(v.literal("tenant"), v.literal("workspace"))
+    )
+  },
+  returns: permissiveReturn,
+  handler: async (ctx, args) => {
+    const now = Date.now();
+    assertOntologicalNodeGenericCreateAllowed({
+      nodeType: args.nodeType,
+      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 epistemicLayer = getNodeLayer(args.nodeType);
+    const resolvedScope = args.topicId || args.projectId ? await resolveTopicProjectScope(ctx, {
+      topicId: args.topicId,
+      projectId: args.projectId
+    }) : void 0;
+    if (resolvedScope) {
+      assertWorkspaceScopedEpistemicNodeScope({
+        scope: resolvedScope,
+        nodeType: args.nodeType,
+        mutationName: "epistemicNodes.create"
+      });
+      assertTenantPackWorkspaceMutationAllowed({
+        runtime: resolveRuntimePackMutationContext(args),
+        target: {
+          tenantId: resolvedScope.tenantId,
+          workspaceId: resolvedScope.workspaceId,
+          nodeType: args.nodeType,
+          epistemicLayer
+        },
+        mutationName: "epistemicNodes.create"
+      });
+    } else if (epistemicLayer !== "ontological") {
+      throw new Error(
+        "Workspace-scoped reasoning isolation requires topicId or projectId for non-ontological node creation."
+      );
+    }
+    const nodeId = await ctx.db.insert("epistemicNodes", {
+      globalId: args.globalId,
+      nodeType: args.nodeType,
+      epistemicLayer,
+      // Phase 2B: Auto-derived from nodeType
+      subtype: args.subtype,
+      canonicalText: args.canonicalText,
+      contentHash: args.contentHash,
+      content: args.content,
+      contentType: args.contentType,
+      title: args.title,
+      tags: args.tags,
+      domain: args.domain,
+      metadata: args.metadata,
+      externalIds: args.externalIds,
+      sourceType: args.sourceType,
+      aiProvider: args.aiProvider,
+      extractedFromNodeId: args.extractedFromNodeId,
+      confidence: args.confidence,
+      verificationStatus: args.verificationStatus ?? "unverified",
+      status: "active",
+      topicId: resolvedScope?.topicId ?? args.topicId,
+      projectId: resolvedScope?.projectId ?? args.projectId,
+      tenantId: resolvedScope?.tenantId,
+      workspaceId: resolvedScope?.workspaceId,
+      createdBy: args.createdBy,
+      createdAt: now,
+      updatedAt: now
+    });
+    await ctx.db.insert("epistemicAudit", {
+      entityType: "node",
+      entityId: String(nodeId),
+      changeType: "created",
+      changedAt: now,
+      changedBy: args.createdBy,
+      isAgent: false,
+      newState: {
+        nodeType: args.nodeType,
+        canonicalText: args.canonicalText.slice(0, 200),
+        status: "active",
+        verificationStatus: args.verificationStatus ?? "unverified",
+        confidence: args.confidence
+      },
+      projectId: resolvedScope?.projectId ?? args.projectId,
+      triggeringAction: "epistemicNodes.create"
+    });
+    await ctx.scheduler.runAfter(0, internal.neo4jSync.syncNodeToNeo4j, {
+      nodeId,
+      operation: "upsert"
+    });
+    return { nodeId, isDuplicate: false };
+  }
+});
+var update = mutation({
+  args: {
+    nodeId: v.id("epistemicNodes"),
+    subtype: v.optional(v.string()),
+    canonicalText: v.optional(v.string()),
+    contentHash: v.optional(v.string()),
+    content: v.optional(v.string()),
+    contentType: v.optional(v.string()),
+    title: v.optional(v.string()),
+    tags: v.optional(v.array(v.string())),
+    domain: v.optional(v.string()),
+    metadata: v.optional(v.any()),
+    externalIds: v.optional(
+      v.object({
+        crunchbase: v.optional(v.string()),
+        linkedin: v.optional(v.string()),
+        pitchbook: v.optional(v.string()),
+        twitter: v.optional(v.string()),
+        website: v.optional(v.string())
+      })
+    ),
+    confidence: v.optional(v.number()),
+    verificationStatus: v.optional(verificationStatusValidator),
+    status: v.optional(statusValidator),
+    userId: v.optional(v.string()),
+    // EK-4: SL opinion fields (Kernel v2)
+    opinion_b: v.optional(v.number()),
+    opinion_d: v.optional(v.number()),
+    opinion_u: v.optional(v.number()),
+    opinion_a: v.optional(v.number())
+  },
+  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");
+    }
+    if (node.projectId && userId) {
+      await requireProjectAccess(ctx, node.projectId, userId);
+    }
+    const cleanUpdates = {};
+    for (const [key, value] of Object.entries(updates)) {
+      if (value !== void 0) {
+        cleanUpdates[key] = value;
+      }
+    }
+    if (node.nodeType === "belief") {
+      assertBeliefNodeGenericUpdateAllowed({
+        node,
+        updates: cleanUpdates,
+        mutationName: "epistemicNodes.update"
+      });
+    }
+    assertOntologicalNodeGenericUpdateAllowed({
+      node,
+      mutationName: "epistemicNodes.update"
+    });
+    cleanUpdates.updatedAt = Date.now();
+    await ctx.db.patch(nodeId, cleanUpdates);
+    if (node.projectId) {
+      await ctx.db.insert("epistemicAudit", {
+        entityType: "node",
+        entityId: String(nodeId),
+        changeType: "updated",
+        changedAt: Date.now(),
+        changedBy: userId || node.createdBy,
+        isAgent: false,
+        previousState: {
+          status: node.status,
+          confidence: node.confidence,
+          canonicalText: node.canonicalText?.slice(0, 200)
+        },
+        newState: cleanUpdates,
+        projectId: node.projectId
+      });
+    }
+    await ctx.scheduler.runAfter(0, internal.neo4jSync.syncNodeToNeo4j, {
+      nodeId,
+      operation: "upsert"
+    });
+    return buildNodeStatusSuccessResult();
+  }
+});
+var supersede = mutation({
+  args: {
+    oldNodeId: v.id("epistemicNodes"),
+    newGlobalId: v.string(),
+    newCanonicalText: v.string(),
+    newContentHash: v.string(),
+    createdBy: v.string(),
+    reason: v.optional(v.string())
+  },
+  returns: permissiveReturn,
+  handler: async (ctx, args) => {
+    const oldNode = await ctx.db.get(args.oldNodeId);
+    if (!oldNode) {
+      throw new Error("Node not found");
+    }
+    if (oldNode.projectId) {
+      await requireProjectAccess(ctx, oldNode.projectId, args.createdBy);
+    }
+    assertBeliefNodeSupersedeAllowed({
+      node: oldNode,
+      mutationName: "epistemicNodes.supersede"
+    });
+    assertOntologicalNodeSupersedeAllowed({
+      node: oldNode,
+      mutationName: "epistemicNodes.supersede"
+    });
+    const now = Date.now();
+    const epistemicLayer = oldNode.epistemicLayer || getNodeLayer(oldNode.nodeType);
+    const newNodeId = await ctx.db.insert("epistemicNodes", {
+      globalId: args.newGlobalId,
+      nodeType: oldNode.nodeType,
+      epistemicLayer,
+      // Phase 2B: Inherit layer (supersession is same-layer only)
+      canonicalText: args.newCanonicalText,
+      contentHash: args.newContentHash,
+      content: oldNode.content,
+      contentType: oldNode.contentType,
+      title: oldNode.title,
+      tags: oldNode.tags,
+      metadata: oldNode.metadata,
+      sourceType: "human",
+      // Supersession is always human-initiated
+      confidence: oldNode.confidence,
+      verificationStatus: "unverified",
+      // New version needs re-verification
+      status: "active",
+      projectId: oldNode.projectId,
+      createdBy: args.createdBy,
+      createdAt: now,
+      updatedAt: now
+    });
+    await ctx.db.patch(args.oldNodeId, {
+      status: "superseded",
+      supersededBy: newNodeId,
+      updatedAt: now
+    });
+    if (oldNode.projectId) {
+      await ctx.db.insert("epistemicAudit", {
+        entityType: "node",
+        entityId: String(args.oldNodeId),
+        changeType: "superseded",
+        changedAt: now,
+        changedBy: args.createdBy,
+        isAgent: false,
+        previousState: {
+          status: oldNode.status,
+          canonicalText: oldNode.canonicalText?.slice(0, 200)
+        },
+        newState: {
+          status: "superseded",
+          supersededBy: String(newNodeId),
+          newCanonicalText: args.newCanonicalText.slice(0, 200)
+        },
+        rationale: args.reason,
+        projectId: oldNode.projectId
+      });
+    }
+    return { newNodeId, oldNodeId: args.oldNodeId };
+  }
+});
+var archive = mutation({
+  args: {
+    nodeId: v.id("epistemicNodes"),
+    userId: v.optional(v.string())
+  },
+  returns: permissiveReturn,
+  handler: async (ctx, args) => {
+    const node = await ctx.db.get(args.nodeId);
+    if (!node) {
+      throw new Error("Node not found");
+    }
+    if (node.projectId && args.userId) {
+      await requireProjectAccess(ctx, node.projectId, args.userId);
+    }
+    assertBeliefNodeArchiveAllowed({
+      node,
+      mutationName: "epistemicNodes.archive"
+    });
+    assertOntologicalNodeArchiveAllowed({
+      node,
+      mutationName: "epistemicNodes.archive"
+    });
+    await ctx.db.patch(args.nodeId, {
+      status: "archived",
+      updatedAt: Date.now()
+    });
+    if (node.projectId) {
+      await ctx.db.insert("epistemicAudit", {
+        entityType: "node",
+        entityId: String(args.nodeId),
+        changeType: "archived",
+        changedAt: Date.now(),
+        changedBy: args.userId || node.createdBy,
+        isAgent: false,
+        previousState: { status: node.status },
+        newState: { status: "archived" },
+        projectId: node.projectId
+      });
+    }
+    return buildNodeArchivedResult();
+  }
+});
+var verify = mutation({
+  args: {
+    nodeId: v.id("epistemicNodes"),
+    verificationStatus: verificationStatusValidator,
+    confidence: v.optional(v.number()),
+    userId: v.optional(v.string())
+  },
+  returns: permissiveReturn,
+  handler: async (ctx, args) => {
+    const node = await ctx.db.get(args.nodeId);
+    if (!node) {
+      throw new Error("Node not found");
+    }
+    assertBeliefNodeVerifyAllowed({
+      node,
+      confidence: args.confidence,
+      mutationName: "epistemicNodes.verify"
+    });
+    const updates = {
+      verificationStatus: args.verificationStatus,
+      updatedAt: Date.now()
+    };
+    if (args.confidence !== void 0) {
+      updates.confidence = args.confidence;
+    }
+    await ctx.db.patch(args.nodeId, updates);
+    await ctx.db.insert("epistemicAudit", {
+      entityType: "node",
+      entityId: String(args.nodeId),
+      changeType: "updated",
+      changedAt: Date.now(),
+      changedBy: args.userId ?? node.createdBy ?? "system:verification",
+      isAgent: false,
+      previousState: {
+        verificationStatus: node.verificationStatus,
+        confidence: node.confidence
+      },
+      newState: {
+        verificationStatus: args.verificationStatus,
+        confidence: args.confidence ?? node.confidence
+      },
+      projectId: node.projectId,
+      triggeringAction: "epistemicNodes.verify"
+    });
+    return buildNodeStatusSuccessResult();
+  }
+});
+var batchCreate = mutation({
+  args: {
+    nodes: v.array(
+      v.object({
+        ...optionalNodeScopeArgs,
+        globalId: v.string(),
+        nodeType: nodeTypeValidator,
+        subtype: v.optional(v.string()),
+        canonicalText: v.string(),
+        contentHash: v.string(),
+        content: v.optional(v.string()),
+        contentType: v.optional(v.string()),
+        title: v.optional(v.string()),
+        tags: v.optional(v.array(v.string())),
+        domain: v.optional(v.string()),
+        metadata: v.optional(v.any()),
+        externalIds: v.optional(
+          v.object({
+            crunchbase: v.optional(v.string()),
+            linkedin: v.optional(v.string()),
+            pitchbook: v.optional(v.string()),
+            twitter: v.optional(v.string()),
+            website: v.optional(v.string())
+          })
+        ),
+        sourceType: sourceTypeValidator,
+        aiProvider: v.optional(v.string()),
+        confidence: v.optional(v.number()),
+        verificationStatus: v.optional(verificationStatusValidator),
+        createdBy: v.string()
+      })
+    )
+  },
+  returns: permissiveReturn,
+  handler: async (ctx, args) => {
+    const resolveNodeScope = async (node) => {
+      if (!(node.topicId || node.projectId)) {
+        return void 0;
+      }
+      try {
+        return await resolveTopicProjectScope(ctx, {
+          topicId: node.topicId,
+          projectId: node.projectId
+        });
+      } catch (error) {
+        debugGraphPrimitiveFallback(
+          "[epistemicNodes] Failed to resolve scope for batch create node",
+          {
+            error,
+            topicId: node.topicId,
+            projectId: node.projectId
+          }
+        );
+        return void 0;
+      }
+    };
+    const now = Date.now();
+    const results = [];
+    for (const node of args.nodes) {
+      assertOntologicalNodeGenericCreateAllowed({
+        nodeType: node.nodeType,
+        mutationName: "epistemicNodes.batchCreate"
+      });
+      const epistemicLayer = getNodeLayer(node.nodeType);
+      const resolvedScope = await resolveNodeScope(node);
+      const nodeId = await ctx.db.insert("epistemicNodes", {
+        ...node,
+        epistemicLayer,
+        // Phase 2B: Auto-derived from nodeType
+        verificationStatus: node.verificationStatus ?? "unverified",
+        status: "active",
+        topicId: resolvedScope?.topicId ?? node.topicId,
+        projectId: resolvedScope?.projectId ?? node.projectId,
+        createdAt: now,
+        updatedAt: now
+      });
+      results.push({ globalId: node.globalId, nodeId });
+      await ctx.db.insert("epistemicAudit", {
+        entityType: "node",
+        entityId: String(nodeId),
+        changeType: "created",
+        changedAt: now,
+        changedBy: node.createdBy,
+        isAgent: false,
+        newState: {
+          nodeType: node.nodeType,
+          canonicalText: node.canonicalText.slice(0, 200),
+          status: "active",
+          verificationStatus: node.verificationStatus ?? "unverified",
+          confidence: node.confidence
+        },
+        projectId: resolvedScope?.projectId ?? node.projectId,
+        triggeringAction: "epistemicNodes.batchCreate"
+      });
+      await ctx.scheduler.runAfter(0, internal.neo4jSync.syncNodeToNeo4j, {
+        nodeId,
+        operation: "upsert"
+      });
+    }
+    return { created: results.length, results };
+  }
+});
+
+export { archive, batchCreate, create, supersede, update, verify };
+//# sourceMappingURL=epistemicNodes.mutations.js.map
+//# sourceMappingURL=epistemicNodes.mutations.js.map