@lucern/graph-primitives 1.0.28 → 1.0.30

package/dist/epistemicBeliefs.core.js

@@ -1,14 +1,16 @@
-import { v, ConvexError } from 'convex/values';
-import { checkScopeAccess, checkProjectAccess } from '@lucern/access-control/access';
+import { requireScopeWriteAccess, checkScopeAccess } from '@lucern/access-control/access';
 import { assertSchemaEnumValue } from '@lucern/contracts/schema-helpers/enumValidation';
 import { permissiveReturn } from '@lucern/contracts/schema-helpers/validators';
-import { componentsGeneric, anyApi, mutationGeneric, queryGeneric } from 'convex/server';
-import { normalizeTupleContradictionPolicy, createInheritedContractRecord, confidenceFromSL } from '@lucern/confidence';
+import { v } from 'convex/values';
+import { unsafeConvexAnyApi } from '@lucern/contracts/convex/unsafeAnyApi';
+import { componentsGeneric, mutationGeneric, queryGeneric } from 'convex/server';
 import '@lucern/access-control/audience';
 import { getCurrentUserId } from '@lucern/access-control/auth';
+import { throwStructuredMutationError } from '@lucern/access-control/structuredMutationError';
+import { normalizeTupleContradictionPolicy, createInheritedContractRecord, confidenceFromSL } from '@lucern/confidence';
 import { isNodeType, getLayerForNodeType } from '@lucern/contracts/schema-helpers/spine/tables/epistemicNodes';
-import { generateGlobalId, assertUuidV7Identity, generateUuidV7, assertStorageEdgeVocabulary, assertUuidShapedEdgeEndpoint } from '@lucern/contracts/ids';
 import { assertEdgePolicyAllowed, edgePolicyManifest } from '@lucern/contracts';
+import { generateGlobalId, assertUuidV7Identity, generateUuidV7, assertStorageEdgeVocabulary, assertUuidShapedEdgeEndpoint } from '@lucern/contracts/ids';
 
 // src/epistemicBeliefs.core.ts
 
@@ -122,9 +124,12 @@ function resolveBeliefLifecycleStatus(opts) {
 function isPreValidationBeliefStatus(status) {
   return status === "assumption" || status === "hypothesis";
 }
-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;
 var query = queryGeneric;
 
@@ -140,6 +145,32 @@ function debugGraphPrimitiveFallback(message, context) {
   console.debug(message, context ?? {});
 }
 
+// src/embeddingTrigger.ts
+var embeddingActionRef = "embeddingActions:generateEpistemicNodeEmbedding";
+async function scheduleEmbeddingGeneration(args) {
+  try {
+    await args.ctx.scheduler.runAfter(0, embeddingActionRef, {
+      nodeId: args.nodeId,
+      projectId: args.projectId ? String(args.projectId) : void 0,
+      topicId: args.topicId ? String(args.topicId) : void 0,
+      createdBy: args.createdBy,
+      nodeType: args.nodeType,
+      text: args.text.slice(0, 2e4),
+      hasAnswer: args.hasAnswer,
+      confidence: args.confidence
+    });
+  } catch (error) {
+    debugGraphPrimitiveFallback(
+      "[embeddingTrigger] Failed to schedule embedding generation",
+      {
+        error,
+        nodeId: String(args.nodeId),
+        nodeType: args.nodeType
+      }
+    );
+  }
+}
+
 // src/topicProjectOverlay.ts
 var LEGACY_SCOPE_FIELD = "graphScopeProjectId";
 function readNonEmptyString(value) {
@@ -158,6 +189,10 @@ function readStringArray(value) {
 function readMetadata(topic) {
   return topic.metadata && typeof topic.metadata === "object" ? topic.metadata : {};
 }
+function omitMetadataKey(metadata, key) {
+  const { [key]: _omitted, ...rest } = metadata;
+  return rest;
+}
 function readLegacyProjectId(value) {
   if (!value) {
     return;
@@ -238,9 +273,12 @@ async function resolveTopicDoc(ctx, scopeId) {
     );
   }
   try {
-    const topic = await ctx.runQuery(api.topics.getByLegacyScopeId, {
-      projectId: String(scopeId)
-    });
+    const topic = await ctx.runQuery(
+      api.topics.getByLegacyScopeId,
+      {
+        projectId: String(scopeId)
+      }
+    );
     if (topic?.name !== void 0 && topic?.type !== void 0) {
       return topic;
     }
@@ -260,8 +298,18 @@ function materializeTopicProjectOverlay(topic, idMode = "legacy") {
   const outwardId = idMode === "topic" ? topicId : storageProjectId;
   const visibility = coerceVisibility(topic.visibility) || coerceVisibility(metadata.visibility) || "private";
   const status = coerceStatus(topic.status) || coerceStatus(metadata.status) || "active";
-  const createdAt = typeof topic.createdAt === "number" ? topic.createdAt : typeof topic._creationTime === "number" ? topic._creationTime : 0;
-  const updatedAt = typeof topic.updatedAt === "number" ? topic.updatedAt : typeof metadata.updatedAt === "number" ? metadata.updatedAt : createdAt;
+  let createdAt = 0;
+  if (typeof topic.createdAt === "number") {
+    createdAt = topic.createdAt;
+  } else if (typeof topic._creationTime === "number") {
+    createdAt = topic._creationTime;
+  }
+  let updatedAt = createdAt;
+  if (typeof topic.updatedAt === "number") {
+    updatedAt = topic.updatedAt;
+  } else if (typeof metadata.updatedAt === "number") {
+    updatedAt = metadata.updatedAt;
+  }
   return {
     ...metadata,
     _id: outwardId,
@@ -330,90 +378,113 @@ async function patchTopicProjectOverlay(ctx, scopeId, value) {
   if (!topic) {
     return null;
   }
-  const nextMetadata = { ...readMetadata(topic) };
-  const patch = {};
-  const topicUpdateArgs = {
-    id: String(topic._id)
+  const plan = buildTopicProjectOverlayPatchPlan(topic, value);
+  await applyTopicProjectOverlayPatch(ctx, topic, plan);
+  return materializeTopicProjectOverlay({
+    ...topic,
+    ...plan.patch,
+    metadata: plan.nextMetadata
+  });
+}
+function buildTopicProjectOverlayPatchPlan(topic, value) {
+  const plan = {
+    nextMetadata: { ...readMetadata(topic) },
+    patch: {},
+    topicUpdateArgs: {
+      id: String(topic._id)
+    }
   };
   for (const [key, rawValue] of Object.entries(value)) {
-    switch (key) {
-      case "_id":
-      case "projectId":
-      case "topicId":
-      case "legacyProjectId":
-      case "storageProjectId":
-        break;
-      case "name":
-      case "description":
-        patch[key] = rawValue;
-        topicUpdateArgs[key] = rawValue;
-        break;
-      case "tenantId":
-      case "workspaceId":
-      case "ownerId":
-        throw new Error(
-          `patchTopicProjectOverlay cannot mutate ${key} via component-owned topics`
-        );
-      case "status": {
-        const status = coerceStatus(rawValue);
-        if (status) {
-          patch.status = status;
-          topicUpdateArgs.status = status;
-        }
-        break;
-      }
-      case "visibility": {
-        const visibility = coerceVisibility(rawValue);
-        if (visibility) {
-          patch.visibility = visibility;
-          topicUpdateArgs.visibility = visibility;
-        }
-        break;
-      }
-      case "type": {
-        const projectType = readNonEmptyString(rawValue);
-        if (projectType) {
-          nextMetadata.projectType = projectType;
-        } else {
-          delete nextMetadata.projectType;
-        }
-        break;
-      }
-      case "updatedAt":
-      case "createdAt":
-        break;
-      default:
-        if (rawValue === void 0) {
-          delete nextMetadata[key];
-        } else {
-          nextMetadata[key] = rawValue;
-        }
-    }
+    applyTopicProjectOverlayPatchEntry(plan, key, rawValue);
+  }
+  plan.patch.updatedAt = Date.now();
+  plan.patch.metadata = plan.nextMetadata;
+  plan.topicUpdateArgs.metadata = plan.nextMetadata;
+  return plan;
+}
+function applyTopicProjectOverlayPatchEntry(plan, key, rawValue) {
+  switch (key) {
+    case "_id":
+    case "projectId":
+    case "topicId":
+    case "legacyProjectId":
+    case "storageProjectId":
+    case "updatedAt":
+    case "createdAt":
+      return;
+    case "name":
+    case "description":
+      plan.patch[key] = rawValue;
+      plan.topicUpdateArgs[key] = rawValue;
+      return;
+    case "tenantId":
+    case "workspaceId":
+    case "ownerId":
+      throw new Error(
+        `patchTopicProjectOverlay cannot mutate ${key} via component-owned topics`
+      );
+    case "status":
+      applyTopicStatusPatch(plan, rawValue);
+      return;
+    case "visibility":
+      applyTopicVisibilityPatch(plan, rawValue);
+      return;
+    case "type":
+      applyTopicProjectTypePatch(plan, rawValue);
+      return;
+    default:
+      applyTopicMetadataPatch(plan, key, rawValue);
+  }
+}
+function applyTopicStatusPatch(plan, rawValue) {
+  const status = coerceStatus(rawValue);
+  if (status) {
+    plan.patch.status = status;
+    plan.topicUpdateArgs.status = status;
+  }
+}
+function applyTopicVisibilityPatch(plan, rawValue) {
+  const visibility = coerceVisibility(rawValue);
+  if (visibility) {
+    plan.patch.visibility = visibility;
+    plan.topicUpdateArgs.visibility = visibility;
+  }
+}
+function applyTopicProjectTypePatch(plan, rawValue) {
+  const projectType = readNonEmptyString(rawValue);
+  if (projectType) {
+    plan.nextMetadata.projectType = projectType;
+    return;
+  }
+  plan.nextMetadata = omitMetadataKey(plan.nextMetadata, "projectType");
+}
+function applyTopicMetadataPatch(plan, key, rawValue) {
+  if (rawValue === void 0) {
+    plan.nextMetadata = omitMetadataKey(plan.nextMetadata, key);
+    return;
   }
-  patch.updatedAt = Date.now();
-  patch.metadata = nextMetadata;
-  topicUpdateArgs.metadata = nextMetadata;
+  plan.nextMetadata[key] = rawValue;
+}
+async function applyTopicProjectOverlayPatch(ctx, topic, plan) {
   if (typeof ctx.runMutation === "function") {
     try {
-      await ctx.runMutation(api.topics.update, topicUpdateArgs);
+      await ctx.runMutation(api.topics.update, plan.topicUpdateArgs);
     } catch (error) {
-      if (!isMissingLucernChildComponentError(error) || !ctx?.db || typeof ctx.db.patch !== "function") {
+      if (!canPatchTopicViaLocalDb(ctx, error)) {
         throw error;
       }
-      await ctx.db.patch(String(topic._id), patch);
+      await ctx.db.patch(topic._id, plan.patch);
     }
   } else if (ctx?.db && typeof ctx.db.patch === "function") {
-    await ctx.db.patch(String(topic._id), patch);
+    await ctx.db.patch(topic._id, plan.patch);
   } else {
     throw new Error(
       "Cannot patch topic without component adapter (ctx.runMutation unavailable)"
     );
   }
-  return materializeTopicProjectOverlay({
-    ...topic,
-    ...patch,
-    metadata: nextMetadata
-  });
+}
+function canPatchTopicViaLocalDb(ctx, error) {
+  return isMissingLucernChildComponentError(error) && Boolean(ctx?.db) && typeof ctx.db?.patch === "function";
 }
 
 // src/resolvers.ts
@@ -441,7 +512,7 @@ async function patchProjectWithTolerance(ctx, projectId, value) {
   try {
     await patchTopicProjectOverlay(ctx, projectId, value);
   } catch (error) {
-    if (!isAdvisoryTopicPatch(value) || !isMissingLucernChildComponentError2(error)) {
+    if (!(isAdvisoryTopicPatch(value) && isMissingLucernChildComponentError2(error))) {
       throw error;
     }
     console.warn(
@@ -508,13 +579,15 @@ function asMappedProjectId(topic) {
   if (!topic) {
     return;
   }
-  const directLegacyProjectId = normalizeScopeValue(topic[LEGACY_SCOPE_FIELD2]);
+  const directLegacyProjectId = normalizeScopeValue(
+    topic[LEGACY_SCOPE_FIELD2]
+  );
   if (directLegacyProjectId) {
     return directLegacyProjectId;
   }
   const metadata = topic.metadata || {};
   const candidate = metadata[LEGACY_SCOPE_FIELD2] || 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") {
@@ -539,8 +612,9 @@ function pickPrimaryTopic(candidates) {
   })[0];
 }
 async function findTopicsByScopeAlias(ctx, scopeId) {
+  const query2 = ctx.db.query("topics");
   try {
-    return await ctx.db.query("topics").withIndex(
+    return await query2.withIndex(
       "by_graph_scope_project",
       (q) => q.eq(LEGACY_SCOPE_FIELD2, scopeId)
     ).collect();
@@ -552,7 +626,7 @@ async function findTopicsByScopeAlias(ctx, scopeId) {
         scopeId
       }
     );
-    const topics = await ctx.db.query("topics").collect();
+    const topics = await query2.collect();
     return topics.filter((topic) => {
       const normalizedGlobalId = normalizeScopeValue(topic.globalId);
       const mappedProjectId = asMappedProjectId(topic);
@@ -608,137 +682,115 @@ 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;
+    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"
-    };
+    return await resolveScopeFromTopicId(ctx, args.topicId);
   }
   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.`
-    );
+    return await resolveScopeFromLegacyProjectId(ctx, args.projectId);
   }
   throw new Error(
     "Missing scope: provide topicId (preferred) or legacy projectId alias."
   );
 }
+async function resolveScopeFromTopicId(ctx, topicId) {
+  const topic = await resolveTopicDocFromTopicId(ctx, topicId);
+  if (topic) {
+    return await buildTopicScope(ctx, topic, "topic");
+  }
+  const nodeScope = await resolveTopicNodeScopeOrNull(ctx, String(topicId));
+  if (nodeScope) {
+    return nodeScope;
+  }
+  throw new Error(`Topic not found: ${String(topicId)}`);
+}
+async function resolveTopicDocFromTopicId(ctx, topicId) {
+  const direct = await tryReadTopicDoc(ctx, topicId, {
+    failureLog: "[topicScope] Failed to load topic by direct id",
+    idLogKey: "topicId"
+  });
+  if (direct) {
+    return direct;
+  }
+  const hostTopic = await tryResolveHostTopicById(ctx, String(topicId));
+  if (hostTopic) {
+    return hostTopic;
+  }
+  return pickPrimaryTopic(await findTopicsByScopeAlias(ctx, String(topicId))) ?? null;
+}
+async function resolveScopeFromLegacyProjectId(ctx, legacyProjectId) {
+  const directTopic = await resolveDirectLegacyProjectTopic(
+    ctx,
+    legacyProjectId
+  );
+  if (directTopic) {
+    return await buildTopicScope(ctx, directTopic, "topic_inferred", {
+      fallbackProjectId: legacyProjectId
+    });
+  }
+  const primary = pickPrimaryTopic(
+    await findTopicsByScopeAlias(ctx, legacyProjectId)
+  );
+  if (primary) {
+    return await buildTopicScope(ctx, primary, "project_mapped_topic", {
+      fallbackProjectId: legacyProjectId
+    });
+  }
+  const nodeScope = await resolveTopicNodeScopeOrNull(ctx, legacyProjectId);
+  if (nodeScope) {
+    return {
+      ...nodeScope,
+      projectId: nodeScope.projectId ?? legacyProjectId
+    };
+  }
+  throw new Error(
+    `Legacy project scope ${legacyProjectId} has no mapped topic.`
+  );
+}
+async function resolveDirectLegacyProjectTopic(ctx, legacyProjectId) {
+  const directTopic = await tryReadTopicDoc(ctx, legacyProjectId, {
+    failureLog: "[topicScope] Failed to load direct project topic",
+    idLogKey: "projectId"
+  });
+  return directTopic ?? tryResolveHostTopicByLegacyScope(ctx, legacyProjectId);
+}
+async function tryReadTopicDoc(ctx, id, log) {
+  try {
+    return await ctx.db.get(id);
+  } catch (error) {
+    debugGraphPrimitiveFallback(log.failureLog, {
+      error,
+      [log.idLogKey]: id
+    });
+    return null;
+  }
+}
+async function buildTopicScope(ctx, topic, source, options = {}) {
+  const inherited = await resolveInheritedWorkspaceScope(ctx, topic);
+  const mapped = asMappedProjectId(topic);
+  return {
+    topicId: topic._id,
+    ...mapped || options.fallbackProjectId ? { projectId: mapped ?? options.fallbackProjectId } : {},
+    tenantId: inherited.tenantId,
+    workspaceId: inherited.workspaceId,
+    source
+  };
+}
 var optionalScopeArgs = {
   projectId: v.optional(v.string()),
   topicId: v.optional(v.string())
@@ -803,8 +855,6 @@ function nodeMatchesWorkspaceReasoningScope(node, scope) {
   }
   return scopeWorkspaceId === nodeWorkspaceId;
 }
-
-// src/epistemicBeliefs.helpers.ts
 v.id("epistemicNodes");
 var DEFAULT_PROJECT_BELIEF_LIMIT = 250;
 var MAX_PROJECT_BELIEF_LIMIT = 1e3;
@@ -813,26 +863,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 assertBaseRateInRange(baseRate, field = "baseRate") {
   if (baseRate < 0 || baseRate > 1) {
     throwStructuredMutationError({
@@ -916,7 +946,7 @@ function normalizePillar(pillar) {
 async function markBeliefGraphDirty(ctx, scope) {
   const projectId = typeof scope.projectId === "string" && scope.projectId.trim().length > 0 ? scope.projectId : void 0;
   const topicId = typeof scope.topicId === "string" && scope.topicId.trim().length > 0 ? scope.topicId : void 0;
-  if (!projectId && !topicId) {
+  if (!(projectId || topicId)) {
     return;
   }
   if (projectId) {
@@ -933,9 +963,15 @@ async function markBeliefGraphDirty(ctx, scope) {
       { topicId }
     );
   }
+  const activityScopeId = topicId ?? projectId;
+  if (!activityScopeId) {
+    throw new Error(
+      "Expected belief graph dirty scope to include a topic or project id."
+    );
+  }
   await resolveGraphPrimitivesAppResolvers().patchProject(
     ctx,
-    topicId ?? projectId,
+    activityScopeId,
     {
       lastActivityAt: Date.now()
     }
@@ -943,7 +979,10 @@ async function markBeliefGraphDirty(ctx, scope) {
 }
 async function getActiveConfidencePolicy(ctx) {
   try {
-    const activeConfig = await ctx.db.query("logicSprintScoring").withIndex("by_active", (q) => q.eq("isActive", true)).first();
+    const activeConfig = await ctx.db.query("logicSprintScoring").withIndex(
+      "by_active",
+      (q) => q.eq("isActive", true)
+    ).first();
     return {
       scoringMode: activeConfig?.confidencePolicy === "always" ? "always" : DEFAULT_CONFIDENCE_POLICY.scoringMode,
       tupleContradiction: normalizeTupleContradictionPolicy(
@@ -975,23 +1014,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 }
-    });
-  }
-}
 
 // src/epistemicBeliefs.forkEvidence.ts
 function normalizeForkTriggerRelation(value) {
@@ -1005,7 +1027,7 @@ function normalizeForkTriggerRelation(value) {
 }
 async function resolveForkTriggerEvidence(ctx, args) {
   const evidence = await ctx.db.get(args.triggeringEvidenceId);
-  if (!evidence || evidence.nodeType !== "evidence") {
+  if (evidence?.nodeType !== "evidence") {
     throwStructuredMutationError({
       message: "Fork requires an existing evidence node.",
       status: 400,
@@ -1044,16 +1066,16 @@ async function resolveForkTriggerEvidence(ctx, args) {
     ].filter(Boolean)
   );
   let relation = null;
-  const linkedBeliefNodeId = String(
-    evidenceMetadata.linkedBeliefNodeId ?? ""
-  );
+  const linkedBeliefNodeId = String(evidenceMetadata.linkedBeliefNodeId ?? "");
   if (linkedBeliefNodeId && parentRefs.has(linkedBeliefNodeId)) {
     relation = normalizeForkTriggerRelation(evidenceMetadata.evidenceRelation);
   }
   if (!relation) {
     for (const parentRef of parentRefs) {
       const links = await ctx.db.query("beliefEvidenceLinks").withIndex("by_beliefId", (q) => q.eq("beliefId", parentRef)).collect();
-      const matched = links.find((link) => evidenceRefs.has(String(link.insightId)));
+      const matched = links.find(
+        (link) => evidenceRefs.has(String(link.insightId))
+      );
       if (matched) {
         relation = normalizeForkTriggerRelation(matched.relation);
         break;
@@ -1089,13 +1111,16 @@ async function resolveForkTriggerEvidence(ctx, args) {
   }
   return { evidenceNodeId: args.triggeringEvidenceId, relation };
 }
-async function insertEpistemicNode(ctx, doc) {
+function insertEpistemicNode(ctx, doc) {
   assertUuidV7Identity("epistemicNodes", doc.globalId);
   return ctx.db.insert("epistemicNodes", doc);
 }
 async function assertExistingNodeEndpoint(ctx, endpointRole, endpoint) {
   assertUuidShapedEdgeEndpoint(endpointRole, endpoint);
-  const node = await ctx.db.query("epistemicNodes").withIndex("by_globalId", (q) => q.eq("globalId", endpoint)).first();
+  const node = await ctx.db.query("epistemicNodes").withIndex(
+    "by_globalId",
+    (q) => q.eq("globalId", endpoint)
+  ).first();
   if (!node) {
     throw new Error(
       `edge_endpoint_not_canonical: epistemicEdges insert requires ${endpointRole} to be the globalId of an existing epistemicNodes row, received ${endpoint} (no node with that globalId)`
@@ -1161,7 +1186,7 @@ async function resolveRequiredTopicAnchor(ctx, topicRef) {
       if (direct?.nodeType === "topic" && cleanString(direct.globalId)) {
         return direct;
       }
-    } catch (_) {
+    } catch {
     }
     const byGlobalId = await ctx.db.query("epistemicNodes").withIndex("by_globalId", (q) => q.eq("globalId", candidate)).first();
     if (byGlobalId?.nodeType === "topic" && cleanString(byGlobalId.globalId)) {
@@ -1246,36 +1271,279 @@ async function createRequiredBeliefTopicEdge(ctx, args) {
   });
 }
 
-// src/embeddingTrigger.ts
-async function scheduleEmbeddingGeneration(args) {
-  try {
-    await args.ctx.scheduler.runAfter(
-      0,
-      "embeddingActions:generateEpistemicNodeEmbedding",
-      {
-        nodeId: args.nodeId,
-        projectId: args.projectId ? String(args.projectId) : void 0,
-        topicId: args.topicId ? String(args.topicId) : void 0,
-        createdBy: args.createdBy,
-        nodeType: args.nodeType,
-        text: args.text.slice(0, 2e4),
-        hasAnswer: args.hasAnswer,
-        confidence: args.confidence
-      }
-    );
-  } catch (error) {
-    debugGraphPrimitiveFallback(
-      "[embeddingTrigger] Failed to schedule embedding generation",
-      {
-        error,
-        nodeId: String(args.nodeId),
-        nodeType: args.nodeType
-      }
-    );
+// src/epistemicBeliefs.core.ts
+var CONTRACT_CONDITION_TYPES = /* @__PURE__ */ new Set(["assertion", "temporal", "evidential", "threshold", "composite"]);
+var CONTRACT_DIRECTIONS = /* @__PURE__ */ new Set([
+  "confirms",
+  "falsifies"
+]);
+var CONTRACT_LINEAGE_SOURCES = /* @__PURE__ */ new Set(["declared", "inherited"]);
+var CONTRACT_SCHEDULES = /* @__PURE__ */ new Set([
+  "on_demand",
+  "on_evidence",
+  "periodic",
+  "event_driven"
+]);
+var CONTRACT_STATUSES = /* @__PURE__ */ new Set([
+  "active",
+  "satisfied",
+  "violated",
+  "expired",
+  "suspended",
+  "archived"
+]);
+function isRecord(value) {
+  return Boolean(value) && typeof value === "object" && !Array.isArray(value);
+}
+function readConvexId(value) {
+  return typeof value === "string" && value.trim().length > 0 ? value : void 0;
+}
+function readOptionalBoolean(value) {
+  return typeof value === "boolean" ? value : void 0;
+}
+function readOptionalNumber(value) {
+  return typeof value === "number" && Number.isFinite(value) ? value : void 0;
+}
+function readOptionalString(value) {
+  return typeof value === "string" && value.trim().length > 0 ? value : void 0;
+}
+function readRecord(value) {
+  return isRecord(value) ? value : void 0;
+}
+function readStringList(value) {
+  if (!Array.isArray(value)) {
+    return;
   }
+  const strings = value.filter(
+    (item) => typeof item === "string" && item.length > 0
+  );
+  return strings.length === value.length ? strings : void 0;
+}
+function readEnumValue(value, allowed) {
+  return typeof value === "string" && allowed.has(value) ? value : void 0;
+}
+function readContractCondition(value) {
+  const record = readRecord(value);
+  const evaluator = readOptionalString(record?.evaluator);
+  const expression = readOptionalString(record?.expression);
+  if (!(record && evaluator && expression)) {
+    return;
+  }
+  return {
+    evaluator,
+    expression,
+    evaluatorConfig: record.evaluatorConfig
+  };
+}
+function readContractModulation(value) {
+  const record = readRecord(value);
+  const onConfirmed = readRecord(record?.onConfirmed);
+  const onDisconfirmed = readRecord(record?.onDisconfirmed);
+  const confirmedDelta = readOptionalNumber(onConfirmed?.delta);
+  const disconfirmedDelta = readOptionalNumber(onDisconfirmed?.delta);
+  if (!(record && onConfirmed && onDisconfirmed)) {
+    return;
+  }
+  if (confirmedDelta === void 0 || disconfirmedDelta === void 0) {
+    return;
+  }
+  const modulation = {
+    onConfirmed: { delta: confirmedDelta },
+    onDisconfirmed: { delta: disconfirmedDelta }
+  };
+  const confirmedCeiling = readOptionalNumber(onConfirmed.ceiling);
+  if (confirmedCeiling !== void 0) {
+    modulation.onConfirmed.ceiling = confirmedCeiling;
+  }
+  const disconfirmedFloor = readOptionalNumber(onDisconfirmed.floor);
+  if (disconfirmedFloor !== void 0) {
+    modulation.onDisconfirmed.floor = disconfirmedFloor;
+  }
+  const onExpired = readRecord(record.onExpired);
+  const expiredDelta = readOptionalNumber(onExpired?.delta);
+  if (expiredDelta !== void 0) {
+    modulation.onExpired = { delta: expiredDelta };
+  }
+  const onPartial = readRecord(record.onPartial);
+  const partialDelta = readOptionalNumber(onPartial?.delta);
+  const partialThreshold = readOptionalNumber(onPartial?.threshold);
+  if (partialDelta !== void 0 && partialThreshold !== void 0) {
+    modulation.onPartial = {
+      delta: partialDelta,
+      threshold: partialThreshold
+    };
+  }
+  return modulation;
+}
+function readBeliefNodeDoc(value) {
+  if (!isRecord(value)) {
+    return null;
+  }
+  const id = readConvexId(value._id);
+  const nodeType = readOptionalString(value.nodeType);
+  const projectId = readOptionalString(value.projectId);
+  if (!(id && nodeType === "belief" && projectId)) {
+    return null;
+  }
+  const node = { _id: id, nodeType, projectId };
+  const canonicalText = readOptionalString(value.canonicalText);
+  const confidence = readOptionalNumber(value.confidence);
+  const content = readOptionalString(value.content);
+  const epistemicLayer = readOptionalString(value.epistemicLayer);
+  const globalId = readOptionalString(value.globalId);
+  const metadata = readRecord(value.metadata);
+  const predictionMeta = readRecord(value.predictionMeta);
+  const sourceType = readOptionalString(value.sourceType);
+  const status = readOptionalString(value.status);
+  const tenantId = readOptionalString(value.tenantId);
+  const title = readOptionalString(value.title);
+  const topicId = readConvexId(value.topicId);
+  const tupleContradicted = readOptionalBoolean(value.tupleContradicted);
+  const workspaceId = readOptionalString(value.workspaceId);
+  if (canonicalText !== void 0) {
+    node.canonicalText = canonicalText;
+  }
+  if (confidence !== void 0) {
+    node.confidence = confidence;
+  }
+  if (content !== void 0) {
+    node.content = content;
+  }
+  if (epistemicLayer !== void 0) {
+    node.epistemicLayer = epistemicLayer;
+  }
+  if (globalId !== void 0) {
+    node.globalId = globalId;
+  }
+  if (metadata !== void 0) {
+    node.metadata = metadata;
+  }
+  if (predictionMeta !== void 0) {
+    node.predictionMeta = predictionMeta;
+  }
+  if (sourceType !== void 0) {
+    node.sourceType = sourceType;
+  }
+  if (status !== void 0) {
+    node.status = status;
+  }
+  if (tenantId !== void 0) {
+    node.tenantId = tenantId;
+  }
+  if (title !== void 0) {
+    node.title = title;
+  }
+  if (topicId !== void 0) {
+    node.topicId = topicId;
+  }
+  if (tupleContradicted !== void 0) {
+    node.tupleContradicted = tupleContradicted;
+  }
+  if (workspaceId !== void 0) {
+    node.workspaceId = workspaceId;
+  }
+  return node;
+}
+function readContractRow(value) {
+  if (!isRecord(value)) {
+    return null;
+  }
+  const beliefNodeId = readConvexId(value.beliefNodeId);
+  const condition = readContractCondition(value.condition);
+  const conditionType = readEnumValue(
+    value.conditionType,
+    CONTRACT_CONDITION_TYPES
+  );
+  const contractId = readOptionalString(value.contractId);
+  const createdAt = readOptionalNumber(value.createdAt);
+  const createdBy = readOptionalString(value.createdBy);
+  const direction = readEnumValue(value.direction, CONTRACT_DIRECTIONS);
+  const evaluationSchedule = readEnumValue(
+    value.evaluationSchedule,
+    CONTRACT_SCHEDULES
+  );
+  const lineageSource = readEnumValue(
+    value.lineageSource,
+    CONTRACT_LINEAGE_SOURCES
+  );
+  const modulation = readContractModulation(value.modulation);
+  const status = readEnumValue(value.status, CONTRACT_STATUSES);
+  const title = readOptionalString(value.title);
+  const updatedAt = readOptionalNumber(value.updatedAt);
+  if (!(beliefNodeId && condition && conditionType && contractId && createdAt !== void 0 && createdBy && direction && evaluationSchedule && lineageSource && modulation && status && title && updatedAt !== void 0)) {
+    return null;
+  }
+  const row = {
+    beliefNodeId,
+    condition,
+    conditionType,
+    contractId,
+    createdAt,
+    createdBy,
+    direction,
+    evaluationSchedule,
+    lineageSource,
+    modulation,
+    status,
+    title,
+    updatedAt
+  };
+  const compositeOf = readStringList(value.compositeOf);
+  if (compositeOf !== void 0) {
+    row.compositeOf = compositeOf;
+  }
+  const compositeOperator = readOptionalString(value.compositeOperator);
+  if (compositeOperator === "all" || compositeOperator === "any" || compositeOperator === "majority") {
+    row.compositeOperator = compositeOperator;
+  }
+  const deadline = readOptionalNumber(value.deadline);
+  if (deadline !== void 0) {
+    row.deadline = deadline;
+  }
+  const description = readOptionalString(value.description);
+  if (description !== void 0) {
+    row.description = description;
+  }
+  const evaluationCount = readOptionalNumber(value.evaluationCount);
+  if (evaluationCount !== void 0) {
+    row.evaluationCount = evaluationCount;
+  }
+  const inheritedAt = readOptionalNumber(value.inheritedAt);
+  if (inheritedAt !== void 0) {
+    row.inheritedAt = inheritedAt;
+  }
+  const inheritedFromBeliefNodeId = readConvexId(
+    value.inheritedFromBeliefNodeId
+  );
+  if (inheritedFromBeliefNodeId !== void 0) {
+    row.inheritedFromBeliefNodeId = inheritedFromBeliefNodeId;
+  }
+  const inheritedFromContractId = readOptionalString(
+    value.inheritedFromContractId
+  );
+  if (inheritedFromContractId !== void 0) {
+    row.inheritedFromContractId = inheritedFromContractId;
+  }
+  const lastEvaluatedAt = readOptionalNumber(value.lastEvaluatedAt);
+  if (lastEvaluatedAt !== void 0) {
+    row.lastEvaluatedAt = lastEvaluatedAt;
+  }
+  const periodicIntervalMs = readOptionalNumber(value.periodicIntervalMs);
+  if (periodicIntervalMs !== void 0) {
+    row.periodicIntervalMs = periodicIntervalMs;
+  }
+  const topicId = readConvexId(value.topicId) ?? readOptionalString(value.topicId);
+  if (topicId !== void 0) {
+    row.topicId = topicId;
+  }
+  return row;
+}
+function readRowList(values, reader) {
+  return values.flatMap((value) => {
+    const row = reader(value);
+    return row ? [row] : [];
+  });
 }
-
-// src/epistemicBeliefs.core.ts
 var create = mutation({
   args: {
     ...optionalBeliefScopeArgs,
@@ -1325,41 +1593,7 @@ var create = mutation({
   returns: permissiveReturn,
   handler: async (ctx, args) => {
     const authenticatedUserId = await requireAuthenticatedUserId(ctx);
-    const topicRef = readTopicNodeRef(args);
-    if (!topicRef) {
-      throwStructuredMutationError({
-        message: "Belief creation requires an explicit topic epistemic node.",
-        status: 400,
-        code: "INVALID_ARGUMENT",
-        invariantCode: "belief.topic_node_required",
-        suggestion: "Pass topicGlobalId or topicNodeId for a topic in epistemicNodes before creating a belief.",
-        details: {
-          topicId: args.topicId,
-          topicNodeId: args.topicNodeId,
-          topicGlobalId: args.topicGlobalId
-        }
-      });
-    }
-    const topicNode = await resolveRequiredTopicAnchor(ctx, topicRef);
-    const scope = scopeFromTopicAnchor(topicNode);
-    assertWorkspaceScopedEpistemicNodeScope({
-      scope,
-      nodeType: "belief",
-      mutationName: "epistemicBeliefs.create"
-    });
-    const normalizedBeliefType = await assertSchemaEnumValue(ctx, {
-      category: "belief_type",
-      value: args.beliefType,
-      tenantId: scope.tenantId,
-      context: "epistemicBeliefs.create"
-    });
-    if (scope.projectId) {
-      await requireProjectWriteAccess(
-        ctx,
-        scope.projectId,
-        authenticatedUserId
-      );
-    }
+    const { normalizedBeliefType, scope, topicNode } = await resolveCreateBeliefAdmission(ctx, args, authenticatedUserId);
     const now = Date.now();
     const baseRate = assertBaseRateInRange(args.baseRate ?? 0.5);
     const initialBeliefStatus = args.worktreeId ? "hypothesis" : "assumption";
@@ -1371,7 +1605,7 @@ var create = mutation({
       opinion_a: baseRate
     };
     const pillar = normalizePillar(args.pillar);
-    const additionalMeta = args.metadata || {};
+    const additionalMeta = readRecord(args.metadata) ?? {};
     const beliefGlobalId = generateGlobalId();
     const nodeId = await insertEpistemicNode(ctx, {
       globalId: beliefGlobalId,
@@ -1533,6 +1767,44 @@ Rationale: ${args.rationale}` : args.formulation
     return { nodeId };
   }
 });
+async function resolveCreateBeliefAdmission(ctx, args, authenticatedUserId) {
+  const topicRef = readTopicNodeRef(args);
+  if (!topicRef) {
+    throwStructuredMutationError({
+      message: "Belief creation requires an explicit topic epistemic node.",
+      status: 400,
+      code: "INVALID_ARGUMENT",
+      invariantCode: "belief.topic_node_required",
+      suggestion: "Pass topicGlobalId or topicNodeId for a topic in epistemicNodes before creating a belief.",
+      details: {
+        topicId: args.topicId,
+        topicNodeId: args.topicNodeId,
+        topicGlobalId: args.topicGlobalId
+      }
+    });
+  }
+  const topicNode = await resolveRequiredTopicAnchor(ctx, topicRef);
+  const anchoredScope = scopeFromTopicAnchor(topicNode);
+  const scope = {
+    ...anchoredScope,
+    topicId: anchoredScope.topicId
+  };
+  assertWorkspaceScopedEpistemicNodeScope({
+    scope,
+    nodeType: "belief",
+    mutationName: "epistemicBeliefs.create"
+  });
+  const normalizedBeliefType = await assertSchemaEnumValue(ctx, {
+    category: "belief_type",
+    value: args.beliefType,
+    tenantId: scope.tenantId,
+    context: "epistemicBeliefs.create"
+  });
+  if (scope.projectId) {
+    await requireScopeWriteAccess(ctx, scope.projectId, authenticatedUserId);
+  }
+  return { normalizedBeliefType, scope, topicNode };
+}
 var getById = query({
   args: {
     nodeId: v.optional(v.id("epistemicNodes")),
@@ -1544,8 +1816,8 @@ var getById = query({
     if (!id) {
       return null;
     }
-    const node = await ctx.db.get(id);
-    if (!node || node.nodeType !== "belief") {
+    const node = readBeliefNodeDoc(await ctx.db.get(id));
+    if (!node) {
       return null;
     }
     return node;
@@ -1563,48 +1835,8 @@ var refineBelief = mutation({
   handler: async (ctx, args) => {
     const authenticatedUserId = await requireAuthenticatedUserId(ctx);
     const now = Date.now();
-    const node = await ctx.db.get(args.nodeId);
-    if (!node) {
-      throwStructuredMutationError({
-        message: "Belief not found.",
-        status: 404,
-        code: "NOT_FOUND",
-        invariantCode: "belief.exists",
-        suggestion: "Verify nodeId points to an existing belief before refining.",
-        details: { nodeId: args.nodeId }
-      });
-    }
-    if (node.nodeType !== "belief") {
-      throwStructuredMutationError({
-        message: `refineBelief only applies to belief nodes. Received nodeType "${node.nodeType}".`,
-        status: 400,
-        code: "INVALID_ARGUMENT",
-        invariantCode: "entity.no_refine",
-        suggestion: "Use entityLifecycle.updateEntityAttributes for entity mutations.",
-        details: { nodeId: args.nodeId, nodeType: node.nodeType }
-      });
-    }
-    if (!node.projectId) {
-      throwStructuredMutationError({
-        message: "Belief has no project scope.",
-        status: 400,
-        code: "MISSING_SCOPE",
-        invariantCode: "belief.project_required",
-        suggestion: "Belief must have a projectId to refine.",
-        details: { nodeId: args.nodeId }
-      });
-    }
-    await requireProjectWriteAccess(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.",
-        status: 409,
-        code: "CONFLICT",
-        invariantCode: "belief.versioning.scored_immutable",
-        suggestion: "Use forkBelief() to create a new version instead of refining in place.",
-        details: { nodeId: args.nodeId, confidence: node.confidence }
-      });
-    }
+    const node = await requireRefinableBelief(ctx, args.nodeId);
+    await requireScopeWriteAccess(ctx, node.projectId, authenticatedUserId);
     const nextText = typeof args.canonicalText === "string" && args.canonicalText.trim().length > 0 ? args.canonicalText.trim() : void 0;
     const nextTitle = typeof args.title === "string" && args.title.trim().length > 0 ? args.title.trim() : void 0;
     const patch = { updatedAt: now };
@@ -1665,6 +1897,110 @@ Rationale: ${args.rationale}` : nextText
     return { nodeId: args.nodeId };
   }
 });
+async function requireRefinableBelief(ctx, nodeId) {
+  const node = await ctx.db.get(nodeId);
+  if (!node) {
+    throwStructuredMutationError({
+      message: "Belief not found.",
+      status: 404,
+      code: "NOT_FOUND",
+      invariantCode: "belief.exists",
+      suggestion: "Verify nodeId points to an existing belief before refining.",
+      details: { nodeId }
+    });
+  }
+  const nodeType = isRecord(node) ? readOptionalString(node.nodeType) : void 0;
+  if (nodeType !== "belief") {
+    throwStructuredMutationError({
+      message: `refineBelief only applies to belief nodes. Received nodeType "${nodeType}".`,
+      status: 400,
+      code: "INVALID_ARGUMENT",
+      invariantCode: "entity.no_refine",
+      suggestion: "Use entityLifecycle.updateEntityAttributes for entity mutations.",
+      details: { nodeId, nodeType }
+    });
+  }
+  const projectId = isRecord(node) ? readOptionalString(node.projectId) : void 0;
+  if (!projectId) {
+    throwStructuredMutationError({
+      message: "Belief has no project scope.",
+      status: 400,
+      code: "MISSING_SCOPE",
+      invariantCode: "belief.project_required",
+      suggestion: "Belief must have a projectId to refine.",
+      details: { nodeId }
+    });
+  }
+  const confidence = isRecord(node) ? readOptionalNumber(node.confidence) : void 0;
+  if (confidence !== void 0) {
+    throwStructuredMutationError({
+      message: "Scored beliefs are immutable. Use forkBelief to evolve a scored belief.",
+      status: 409,
+      code: "CONFLICT",
+      invariantCode: "belief.versioning.scored_immutable",
+      suggestion: "Use forkBelief() to create a new version instead of refining in place.",
+      details: { nodeId, confidence }
+    });
+  }
+  const beliefNode = readBeliefNodeDoc(node);
+  if (!beliefNode) {
+    throwStructuredMutationError({
+      message: "Belief row is missing required typed fields.",
+      status: 400,
+      code: "MISSING_SCOPE",
+      invariantCode: "belief.typed_row_required",
+      suggestion: "Backfill belief project/topic/global scope before refining.",
+      details: { nodeId }
+    });
+  }
+  return beliefNode;
+}
+async function requireForkParentAdmission(ctx, args, authenticatedUserId) {
+  const parentRaw = await ctx.db.get(args.parentNodeId);
+  if (!parentRaw) {
+    throwStructuredMutationError({
+      message: "Parent node not found.",
+      status: 404,
+      code: "NOT_FOUND",
+      invariantCode: "belief.exists",
+      suggestion: "Verify parentNodeId points to an existing node before forking.",
+      details: { parentNodeId: args.parentNodeId }
+    });
+  }
+  const parent = readBeliefNodeDoc(parentRaw);
+  const parentNodeType = isRecord(parentRaw) ? readOptionalString(parentRaw.nodeType) : void 0;
+  if (!parent) {
+    throwStructuredMutationError({
+      message: `forkBelief only applies to fully scoped belief nodes. Received nodeType "${parentNodeType}". Entity nodes (company, person, investor, etc.) are mutable \u2014 use entityLifecycle.updateEntityAttributes instead of forking.`,
+      status: 400,
+      code: "INVALID_ARGUMENT",
+      invariantCode: "entity.no_fork",
+      suggestion: "Use entityLifecycle.updateEntityAttributes for entity mutations. forkBelief is for belief nodes only, and parent beliefs must carry project scope.",
+      details: {
+        parentNodeId: args.parentNodeId,
+        nodeType: parentNodeType
+      }
+    });
+  }
+  const parentGlobalId = parent.globalId;
+  if (!parentGlobalId) {
+    throwStructuredMutationError({
+      message: "Parent belief has no globalId for lineage edge creation.",
+      status: 400,
+      code: "INVALID_ARGUMENT",
+      invariantCode: "belief.global_id_required",
+      suggestion: "Backfill parent belief globalId before forking so Neo4j lineage edges can use canonical endpoints.",
+      details: { parentNodeId: args.parentNodeId }
+    });
+  }
+  await requireScopeWriteAccess(ctx, parent.projectId, authenticatedUserId);
+  return {
+    metadata: parent.metadata,
+    parent,
+    parentGlobalId,
+    parentRaw
+  };
+}
 var getByProject = query({
   args: {
     ...optionalBeliefScopeArgs,
@@ -1680,7 +2016,7 @@ var getByProject = query({
   },
   returns: permissiveReturn,
   handler: async (ctx, args) => {
-    if (!args.projectId && !args.topicId) {
+    if (!(args.projectId || args.topicId)) {
       return [];
     }
     const pageSize = clampBeliefLimit(args.limit);
@@ -1712,11 +2048,14 @@ var getByProject = query({
         return [];
       }
     }
-    const query3 = ctx.db.query("epistemicNodes").withIndex(
+    const query2 = ctx.db.query("epistemicNodes").withIndex(
       "by_topic_type",
       (q) => q.eq("topicId", scope.topicId).eq("nodeType", "belief")
     );
-    const nodes = await query3.order("desc").take(scanLimit);
+    const nodes = readRowList(
+      await query2.order("desc").take(scanLimit),
+      readBeliefNodeDoc
+    );
     const scopedNodes = nodes.filter(
       (node) => nodeMatchesWorkspaceReasoningScope(node, scope)
     );
@@ -1746,11 +2085,14 @@ var getByTopic = query({
     const scope = await resolveTopicProjectScope(ctx, {
       topicId: args.topicId
     });
-    const query3 = ctx.db.query("epistemicNodes").withIndex(
+    const query2 = ctx.db.query("epistemicNodes").withIndex(
       "by_topic_type",
       (q) => q.eq("topicId", args.topicId).eq("nodeType", "belief")
     );
-    const nodes = await query3.order("desc").take(scanLimit);
+    const nodes = readRowList(
+      await query2.order("desc").take(scanLimit),
+      readBeliefNodeDoc
+    );
     const scopedNodes = nodes.filter(
       (node) => nodeMatchesWorkspaceReasoningScope(node, {
         tenantId: scope.tenantId,
@@ -1783,44 +2125,12 @@ var forkBelief = mutation({
     const authenticatedUserId = await requireAuthenticatedUserId(ctx);
     const now = Date.now();
     await getActiveConfidencePolicy(ctx);
-    const parent = await ctx.db.get(args.parentNodeId);
-    if (!parent) {
-      throwStructuredMutationError({
-        message: "Parent node not found.",
-        status: 404,
-        code: "NOT_FOUND",
-        invariantCode: "belief.exists",
-        suggestion: "Verify parentNodeId points to an existing node before forking.",
-        details: { parentNodeId: args.parentNodeId }
-      });
-    }
-    if (parent.nodeType !== "belief") {
-      throwStructuredMutationError({
-        message: `forkBelief only applies to belief nodes. Received nodeType "${parent.nodeType}". Entity nodes (company, person, investor, etc.) are mutable \u2014 use entityLifecycle.updateEntityAttributes instead of forking.`,
-        status: 400,
-        code: "INVALID_ARGUMENT",
-        invariantCode: "entity.no_fork",
-        suggestion: "Use entityLifecycle.updateEntityAttributes for entity mutations. forkBelief is for belief nodes only.",
-        details: { parentNodeId: args.parentNodeId, nodeType: parent.nodeType }
-      });
-    }
-    if (!parent.projectId) {
-      throwStructuredMutationError({
-        message: "Parent belief has no project scope.",
-        status: 400,
-        code: "MISSING_SCOPE",
-        invariantCode: "belief.project_required",
-        suggestion: "Belief must have a projectId to fork.",
-        details: { parentNodeId: args.parentNodeId }
-      });
-    }
-    await requireProjectWriteAccess(ctx, parent.projectId, authenticatedUserId);
-    const metadata = parent.metadata;
+    const { metadata, parent, parentGlobalId, parentRaw } = await requireForkParentAdmission(ctx, args, authenticatedUserId);
     const forkBeliefStatus = "hypothesis";
     const forkMode = args.forkMode ?? "supersede";
     const triggerEvidence = await resolveForkTriggerEvidence(ctx, {
       parentNodeId: args.parentNodeId,
-      parent,
+      parent: parentRaw,
       triggeringEvidenceId: args.triggeringEvidenceId,
       forkMode
     });
@@ -1867,7 +2177,7 @@ var forkBelief = mutation({
         tupleContradicted: false
       },
       beliefStatus: forkBeliefStatus,
-      sourceType: parent.sourceType,
+      sourceType: parent.sourceType ?? "human",
       confidence: void 0,
       tupleContradicted: false,
       verificationStatus: "unverified",
@@ -1899,23 +2209,21 @@ var forkBelief = mutation({
         operation: "upsert"
       });
     }
-    const inheritedContracts = await ctx.db.query("epistemicContracts").withIndex(
-      "by_belief",
-      (q) => q.eq("beliefNodeId", args.parentNodeId)
-    ).collect();
+    const inheritedContracts = readRowList(
+      await ctx.db.query("epistemicContracts").withIndex("by_belief", (q) => q.eq("beliefNodeId", args.parentNodeId)).collect(),
+      readContractRow
+    );
     for (const contract of inheritedContracts) {
       if (contract.status === "archived") {
         continue;
       }
-      await ctx.db.insert(
-        "epistemicContracts",
-        createInheritedContractRecord(contract, {
-          beliefNodeId: newNodeId,
-          topicId: parent.topicId,
-          createdBy: authenticatedUserId,
-          now
-        })
-      );
+      const inheritedContract = createInheritedContractRecord(contract, {
+        beliefNodeId: newNodeId,
+        topicId: parent.topicId,
+        createdBy: authenticatedUserId,
+        now
+      });
+      await ctx.db.insert("epistemicContracts", { ...inheritedContract });
     }
     await ctx.scheduler.runAfter(0, internal.neo4jSync.syncNodeToNeo4j, {
       nodeId: newNodeId,
@@ -1924,7 +2232,7 @@ var forkBelief = mutation({
     await ctx.scheduler.runAfter(5e3, internal.neo4jEdgeAPI.createEdge, {
       globalId: generateGlobalId(),
       fromGlobalId: newBeliefGlobalId,
-      toGlobalId: parent.globalId,
+      toGlobalId: parentGlobalId,
       edgeType: forkMode === "supersede" ? "supersedes" : "derived_from",
       context: `Fork reason: ${args.forkReason}; triggering evidence: ${triggerEvidence.evidenceNodeId}`,
       createdBy: authenticatedUserId,