@lucern/graph-primitives 1.0.16 → 1.0.18

package/dist/epistemicBeliefs.core.js

@@ -4,11 +4,123 @@ import { assertSchemaEnumValue } from '@lucern/contracts/schema-helpers/enumVali
 import { permissiveReturn } from '@lucern/contracts/schema-helpers/validators';
 import { componentsGeneric, anyApi, mutationGeneric, queryGeneric } from 'convex/server';
 import { normalizeTupleContradictionPolicy, createInheritedContractRecord, confidenceFromSL } from '@lucern/confidence';
-import { isNodeType, getLayerForNodeType } from '@lucern/contracts/schema-helpers/spine/tables/epistemicNodes';
 import '@lucern/access-control/audience';
 import { getCurrentUserId } from '@lucern/access-control/auth';
+import { isNodeType, getLayerForNodeType } from '@lucern/contracts/schema-helpers/spine/tables/epistemicNodes';
+import { generateGlobalId } from '@lucern/contracts/ids';
 
 // src/epistemicBeliefs.core.ts
+
+// src/beliefLifecycle.ts
+var BELIEF_STATUS_VALUES = [
+  "assumption",
+  "hypothesis",
+  "active",
+  "superseded",
+  "resolved_true",
+  "resolved_false"
+];
+function isBeliefLifecycleStatus(value) {
+  return typeof value === "string" && BELIEF_STATUS_VALUES.includes(value);
+}
+function normalizeLegacyBeliefStatus(value) {
+  if (isBeliefLifecycleStatus(value)) {
+    return value;
+  }
+  if (value === "belief" || value === "established" || value === "emerging") {
+    return "active";
+  }
+  if (value === "fact" || value === "confirmed") {
+    return "resolved_true";
+  }
+  if (value === "disconfirmed" || value === "expired") {
+    return "resolved_false";
+  }
+  if (value === "deprecated") {
+    return "superseded";
+  }
+  return null;
+}
+function normalizeBeliefConfidence(confidence) {
+  if (typeof confidence !== "number" || !Number.isFinite(confidence)) {
+    return null;
+  }
+  if (confidence >= 0 && confidence <= 1) {
+    return confidence;
+  }
+  if (confidence > 1 && confidence <= 100) {
+    return confidence / 100;
+  }
+  return null;
+}
+function isResolvedByConfidence(confidence) {
+  const normalized = normalizeBeliefConfidence(confidence);
+  if (normalized === null) {
+    return false;
+  }
+  return normalized <= 0 || normalized >= 1;
+}
+function getPredictionMetaFromMetadata(metadata) {
+  return metadata?.predictionMeta;
+}
+function resolvedPredictionStatus(predictionMeta) {
+  if (!predictionMeta || typeof predictionMeta !== "object") {
+    return null;
+  }
+  const outcome = predictionMeta.outcome;
+  if (outcome === "confirmed") {
+    return "resolved_true";
+  }
+  if (outcome === "disconfirmed" || outcome === "expired") {
+    return "resolved_false";
+  }
+  return null;
+}
+function shouldTreatBeliefAsResolved(opts) {
+  if (isResolvedByConfidence(opts.confidence)) {
+    const normalized = normalizeBeliefConfidence(opts.confidence);
+    return normalized === 0 ? "resolved_false" : "resolved_true";
+  }
+  const directPredictionStatus = resolvedPredictionStatus(opts.predictionMeta);
+  if (directPredictionStatus) {
+    return directPredictionStatus;
+  }
+  const metadataPredictionStatus = resolvedPredictionStatus(
+    getPredictionMetaFromMetadata(opts.metadata)
+  );
+  if (metadataPredictionStatus) {
+    return metadataPredictionStatus;
+  }
+  return null;
+}
+function resolveBeliefLifecycleStatus(opts) {
+  const resolvedStatus = shouldTreatBeliefAsResolved(opts);
+  if (resolvedStatus) {
+    return resolvedStatus;
+  }
+  const direct = opts.beliefStatus;
+  const normalizedDirect = normalizeLegacyBeliefStatus(direct);
+  if (normalizedDirect) {
+    const normalized = normalizeBeliefConfidence(opts.confidence);
+    if (normalized !== null && isPreValidationBeliefStatus(normalizedDirect)) {
+      return "active";
+    }
+    return normalizedDirect;
+  }
+  const metaStatus = opts.metadata?.beliefStatus;
+  const normalizedMetaStatus = normalizeLegacyBeliefStatus(metaStatus);
+  if (normalizedMetaStatus) {
+    const normalized = normalizeBeliefConfidence(opts.confidence);
+    if (normalized !== null && isPreValidationBeliefStatus(normalizedMetaStatus)) {
+      return "active";
+    }
+    return normalizedMetaStatus;
+  }
+  return "assumption";
+}
+function isPreValidationBeliefStatus(status) {
+  return status === "assumption" || status === "hypothesis";
+}
 var api = anyApi;
 componentsGeneric();
 var internal = anyApi;
@@ -27,655 +139,614 @@ function debugGraphPrimitiveFallback(message, context) {
   console.debug(message, context ?? {});
 }
 
-// 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/globalId.ts
-function generateGlobalId() {
-  const bytes = new Uint8Array(16);
-  crypto.getRandomValues(bytes);
-  bytes[6] = bytes[6] & 15 | 64;
-  bytes[8] = bytes[8] & 63 | 128;
-  const hex = Array.from(bytes, (b) => b.toString(16).padStart(2, "0")).join(
-    ""
-  );
-  return `${hex.slice(0, 8)}-${hex.slice(8, 12)}-${hex.slice(12, 16)}-${hex.slice(16, 20)}-${hex.slice(20)}`;
-}
+// src/topicProjectOverlay.ts
 var LEGACY_SCOPE_FIELD = "graphScopeProjectId";
-function asMappedProjectId(topic) {
-  if (!topic) {
+function readNonEmptyString(value) {
+  if (typeof value !== "string") {
     return;
   }
-  const directLegacyProjectId = normalizeScopeValue(topic[LEGACY_SCOPE_FIELD]);
-  if (directLegacyProjectId) {
-    return directLegacyProjectId;
+  const normalized = value.trim();
+  return normalized.length > 0 ? normalized : void 0;
+}
+function readStringArray(value) {
+  if (!Array.isArray(value)) {
+    return [];
   }
-  const metadata = topic.metadata || {};
-  const candidate = metadata[LEGACY_SCOPE_FIELD] || metadata.legacyProjectId || metadata.projectId || metadata.scopeProjectId;
-  return candidate ? candidate : void 0;
+  return value.map((entry) => readNonEmptyString(entry)).filter((entry) => Boolean(entry));
 }
-function normalizeScopeValue(value) {
-  if (typeof value !== "string") {
+function readMetadata(topic) {
+  return topic.metadata && typeof topic.metadata === "object" ? topic.metadata : {};
+}
+function readLegacyProjectId(value) {
+  if (!value) {
     return;
   }
-  const normalized = value.trim();
-  return normalized.length > 0 ? normalized : void 0;
+  return readNonEmptyString(value[LEGACY_SCOPE_FIELD]);
 }
-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];
+function coerceVisibility(value) {
+  return value === "private" || value === "team" || value === "firm" || value === "external" || value === "public" ? value : void 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,
+function coerceStatus(value) {
+  return value === "active" || value === "archived" || value === "watching" ? value : void 0;
+}
+function mapProjectType(topic, metadata) {
+  const explicit = readNonEmptyString(metadata.projectType);
+  if (explicit) {
+    return explicit;
+  }
+  if (topic.type === "theme") {
+    return "thematic";
+  }
+  return readNonEmptyString(topic.type) || "general";
+}
+function isProjectLikeTopic(topic) {
+  const metadata = readMetadata(topic);
+  return topic.type === "theme" || topic.type === "thematic" || topic.type === "deal" || topic.type === "monitoring" || readLegacyProjectId(topic) !== void 0 || readNonEmptyString(metadata.projectType) !== void 0;
+}
+function isMissingLucernChildComponentError(error) {
+  const message = getErrorMessage(error);
+  return message.includes(
+    'Child component ComponentName(Identifier("lucern")) not found'
+  ) || message.includes("Child component") && message.includes("lucern") && message.includes("not found");
+}
+function getErrorMessage(error) {
+  if (error instanceof Error) {
+    return error.message;
+  }
+  if (typeof error === "object" && error !== null && "message" in error && typeof error.message === "string") {
+    return error.message;
+  }
+  return "unknown error";
+}
+async function resolveTopicDoc(ctx, scopeId) {
+  if (ctx?.db && typeof ctx.db.get === "function") {
+    try {
+      const directTopic = await ctx.db.get(
         scopeId
+      );
+      if (directTopic) {
+        return directTopic;
       }
-    );
-    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;
-    });
+    } catch (error) {
+      debugGraphPrimitiveFallback(
+        "[topicProjectOverlay] Failed to resolve topic by direct ID",
+        {
+          error,
+          scopeId
+        }
+      );
+    }
   }
-}
-async function tryResolveHostTopicById(ctx, topicId) {
   if (typeof ctx.runQuery !== "function") {
     return null;
   }
   try {
-    return await ctx.runQuery(api.topics.get, {
-      id: topicId
-    }) ?? null;
+    const topic = await ctx.runQuery(api.topics.get, {
+      id: String(scopeId)
+    });
+    if (topic?.name !== void 0 && topic?.type !== void 0) {
+      return topic;
+    }
   } catch (error) {
     debugGraphPrimitiveFallback(
-      "[topicScope] Failed to resolve topic by host query",
+      "[topicProjectOverlay] Failed to resolve topic by ID query",
       {
         error,
-        topicId
+        scopeId
       }
     );
-    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;
+    const topic = await ctx.runQuery(api.topics.getByLegacyScopeId, {
+      projectId: String(scopeId)
+    });
+    if (topic?.name !== void 0 && topic?.type !== void 0) {
+      return topic;
+    }
   } catch (error) {
     debugGraphPrimitiveFallback(
-      "[topicScope] Failed to resolve topic by legacy scope",
-      {
-        error,
-        legacyScopeId
-      }
+      "[topicProjectOverlay] Failed to resolve topic by legacy scope ID",
+      { error, scopeId }
     );
-    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 };
+  return null;
 }
-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"
-    };
+function materializeTopicProjectOverlay(topic, idMode = "legacy") {
+  const metadata = readMetadata(topic);
+  const topicId = String(topic._id);
+  const legacyProjectId = readLegacyProjectId(topic) || readLegacyProjectId(metadata) || readNonEmptyString(metadata.legacyProjectId);
+  const storageProjectId = legacyProjectId || topicId;
+  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;
+  return {
+    ...metadata,
+    _id: outwardId,
+    projectId: outwardId,
+    topicId,
+    storageProjectId,
+    legacyProjectId,
+    name: readNonEmptyString(topic.name) || "Untitled Theme",
+    type: mapProjectType(topic, metadata),
+    description: readNonEmptyString(topic.description),
+    ownerId: readNonEmptyString(metadata.ownerId) || readNonEmptyString(topic.createdBy) || "system",
+    sharedWith: readStringArray(metadata.sharedWith),
+    visibility,
+    tenantId: readNonEmptyString(topic.tenantId) || readNonEmptyString(metadata.tenantId),
+    workspaceId: readNonEmptyString(topic.workspaceId) || readNonEmptyString(metadata.workspaceId),
+    status,
+    tags: readStringArray(metadata.tags),
+    chatCount: typeof metadata.chatCount === "number" ? metadata.chatCount : 0,
+    artifactCount: typeof metadata.artifactCount === "number" ? metadata.artifactCount : 0,
+    lastActivityAt: typeof metadata.lastActivityAt === "number" ? metadata.lastActivityAt : updatedAt,
+    _creationTime: typeof topic._creationTime === "number" ? topic._creationTime : createdAt,
+    createdAt,
+    updatedAt
+  };
+}
+async function resolveTopicProjectOverlay(ctx, scopeId, options = {}) {
+  const topic = await resolveTopicDoc(ctx, scopeId);
+  if (!topic) {
+    return null;
   }
-  if (args.projectId) {
-    let directTopic = null;
+  if (options.projectLikeOnly !== false && !isProjectLikeTopic(topic)) {
+    return null;
+  }
+  return materializeTopicProjectOverlay(topic, options.idMode);
+}
+async function listTopicProjectOverlays(ctx, options = {}) {
+  let allTopics = [];
+  if (ctx?.db?.query && typeof ctx.db.query === "function") {
     try {
-      directTopic = await ctx.db.get(
-        args.projectId
-      );
+      allTopics = await ctx.db.query("topics").collect();
     } catch (error) {
       debugGraphPrimitiveFallback(
-        "[topicScope] Failed to load direct project topic",
-        {
-          error,
-          projectId: args.projectId
-        }
+        "[topicProjectOverlay] Failed to read topics table; falling back to API",
+        { error }
       );
+      allTopics = [];
     }
-    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())
-};
-function normalizeScopeValue2(value) {
-  if (typeof value !== "string") {
-    return;
+  if (allTopics.length === 0 && typeof ctx.runQuery === "function") {
+    allTopics = (await ctx.runQuery(api.topics.list, {}) ?? []) || [];
   }
-  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;
+  return allTopics.filter(
+    (topic) => options.projectLikeOnly === false || isProjectLikeTopic(topic)
+  ).map((topic) => materializeTopicProjectOverlay(topic, options.idMode));
 }
-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;
+async function patchTopicProjectOverlay(ctx, scopeId, value) {
+  const topic = await resolveTopicDoc(ctx, scopeId);
+  if (!topic) {
+    return null;
   }
-  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
+  const nextMetadata = { ...readMetadata(topic) };
+  const patch = {};
+  const 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;
+        }
     }
-  });
-}
-function nodeMatchesWorkspaceReasoningScope(node, scope) {
-  if (!node) {
-    return false;
-  }
-  const scopeTenantId = normalizeScopeValue2(scope.tenantId);
-  const scopeWorkspaceId = normalizeScopeValue2(scope.workspaceId);
-  const nodeTenantId = normalizeScopeValue2(node.tenantId);
-  const nodeWorkspaceId = normalizeScopeValue2(node.workspaceId);
-  const epistemicLayer = typeof node.epistemicLayer === "string" ? node.epistemicLayer : void 0;
-  if (scopeTenantId && nodeTenantId && scopeTenantId !== nodeTenantId) {
-    return false;
-  }
-  if (epistemicLayer === "ontological" && nodeWorkspaceId === void 0) {
-    return true;
-  }
-  if (!scopeWorkspaceId && node.publicationStatus === "published") {
-    return true;
   }
-  if (!scopeWorkspaceId) {
-    return nodeWorkspaceId === void 0;
+  patch.updatedAt = Date.now();
+  patch.metadata = nextMetadata;
+  topicUpdateArgs.metadata = nextMetadata;
+  if (typeof ctx.runMutation === "function") {
+    try {
+      await ctx.runMutation(api.topics.update, topicUpdateArgs);
+    } catch (error) {
+      if (!isMissingLucernChildComponentError(error) || !ctx?.db || typeof ctx.db.patch !== "function") {
+        throw error;
+      }
+      await ctx.db.patch(String(topic._id), patch);
+    }
+  } else if (ctx?.db && typeof ctx.db.patch === "function") {
+    await ctx.db.patch(String(topic._id), patch);
+  } else {
+    throw new Error(
+      "Cannot patch topic without component adapter (ctx.runMutation unavailable)"
+    );
   }
-  return scopeWorkspaceId === nodeWorkspaceId;
+  return materializeTopicProjectOverlay({
+    ...topic,
+    ...patch,
+    metadata: nextMetadata
+  });
 }
 
-// src/topicProjectOverlay.ts
-var LEGACY_SCOPE_FIELD2 = "graphScopeProjectId";
-function readNonEmptyString(value) {
-  if (typeof value !== "string") {
-    return;
-  }
-  const normalized = value.trim();
-  return normalized.length > 0 ? normalized : void 0;
+// src/resolvers.ts
+function isMissingLucernChildComponentError2(error) {
+  const message = getErrorMessage2(error);
+  return message.includes(
+    'Child component ComponentName(Identifier("lucern")) not found'
+  ) || message.includes("Child component") && message.includes("lucern") && message.includes("not found");
 }
-function readStringArray(value) {
-  if (!Array.isArray(value)) {
-    return [];
+function getErrorMessage2(error) {
+  if (error instanceof Error) {
+    return error.message;
   }
-  return value.map((entry) => readNonEmptyString(entry)).filter((entry) => Boolean(entry));
+  if (typeof error === "object" && error !== null && "message" in error && typeof error.message === "string") {
+    return error.message;
+  }
+  return "unknown error";
 }
-function readMetadata(topic) {
-  return topic.metadata && typeof topic.metadata === "object" ? topic.metadata : {};
+function isAdvisoryTopicPatch(value) {
+  const advisoryKeys = /* @__PURE__ */ new Set(["lastActivityAt", "updatedAt"]);
+  const keys = Object.keys(value);
+  return keys.length > 0 && keys.every((key) => advisoryKeys.has(key));
 }
-function readLegacyProjectId(value) {
-  if (!value) {
-    return;
+async function patchProjectWithTolerance(ctx, projectId, value) {
+  try {
+    await patchTopicProjectOverlay(ctx, projectId, value);
+  } catch (error) {
+    if (!isAdvisoryTopicPatch(value) || !isMissingLucernChildComponentError2(error)) {
+      throw error;
+    }
+    console.warn(
+      "[lucern graph-primitives] Non-fatal advisory topic patch failure",
+      {
+        projectId,
+        keys: Object.keys(value),
+        error: getErrorMessage2(error)
+      }
+    );
   }
-  return readNonEmptyString(value[LEGACY_SCOPE_FIELD2]);
 }
-function coerceVisibility(value) {
-  return value === "private" || value === "team" || value === "firm" || value === "external" || value === "public" ? value : void 0;
+function defaultResolvers() {
+  return {
+    getProject: (ctx, projectId) => resolveTopicProjectOverlay(ctx, projectId, {
+      idMode: "legacy",
+      projectLikeOnly: false
+    }),
+    patchProject: (ctx, projectId, value) => patchProjectWithTolerance(ctx, projectId, value),
+    listTopics: (ctx) => listTopicProjectOverlays(ctx, {
+      idMode: "legacy"
+    }),
+    getFinalArtifact: (ctx, artifactId) => ctx.db.get(artifactId)
+  };
 }
-function coerceStatus(value) {
-  return value === "active" || value === "archived" || value === "watching" ? value : void 0;
+var resolverOverrides = {};
+function resolveGraphPrimitivesAppResolvers(_ctx) {
+  return {
+    ...defaultResolvers(),
+    ...resolverOverrides
+  };
 }
-function mapProjectType(topic, metadata) {
-  const explicit = readNonEmptyString(metadata.projectType);
-  if (explicit) {
-    return explicit;
+var LEGACY_SCOPE_FIELD2 = "graphScopeProjectId";
+function asMappedProjectId(topic) {
+  if (!topic) {
+    return;
   }
-  if (topic.type === "theme") {
-    return "thematic";
+  const directLegacyProjectId = normalizeScopeValue(topic[LEGACY_SCOPE_FIELD2]);
+  if (directLegacyProjectId) {
+    return directLegacyProjectId;
   }
-  return readNonEmptyString(topic.type) || "general";
-}
-function isProjectLikeTopic(topic) {
-  const metadata = readMetadata(topic);
-  return topic.type === "theme" || topic.type === "thematic" || topic.type === "deal" || topic.type === "monitoring" || readLegacyProjectId(topic) !== void 0 || readNonEmptyString(metadata.projectType) !== void 0;
-}
-function isMissingLucernChildComponentError(error) {
-  const message = getErrorMessage(error);
-  return message.includes(
-    'Child component ComponentName(Identifier("lucern")) not found'
-  ) || message.includes("Child component") && message.includes("lucern") && message.includes("not found");
+  const metadata = topic.metadata || {};
+  const candidate = metadata[LEGACY_SCOPE_FIELD2] || metadata.legacyProjectId || metadata.projectId || metadata.scopeProjectId;
+  return candidate ? candidate : void 0;
 }
-function getErrorMessage(error) {
-  if (error instanceof Error) {
-    return error.message;
-  }
-  if (typeof error === "object" && error !== null && "message" in error && typeof error.message === "string") {
-    return error.message;
+function normalizeScopeValue(value) {
+  if (typeof value !== "string") {
+    return;
   }
-  return "unknown error";
+  const normalized = value.trim();
+  return normalized.length > 0 ? normalized : void 0;
 }
-async function resolveTopicDoc(ctx, scopeId) {
-  if (ctx?.db && typeof ctx.db.get === "function") {
-    try {
-      const directTopic = await ctx.db.get(
+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_FIELD2, scopeId)
+    ).collect();
+  } catch (error) {
+    debugGraphPrimitiveFallback(
+      "[topicScope] Failed to resolve scope alias via index",
+      {
+        error,
         scopeId
-      );
-      if (directTopic) {
-        return directTopic;
       }
-    } catch (error) {
-      debugGraphPrimitiveFallback(
-        "[topicProjectOverlay] Failed to resolve topic by direct ID",
-        {
-          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 {
-    const topic = await ctx.runQuery(api.topics.get, {
-      id: String(scopeId)
-    });
-    if (topic?.name !== void 0 && topic?.type !== void 0) {
-      return topic;
-    }
+    return await ctx.runQuery(api.topics.get, {
+      id: topicId
+    }) ?? null;
   } catch (error) {
     debugGraphPrimitiveFallback(
-      "[topicProjectOverlay] Failed to resolve topic by ID query",
+      "[topicScope] Failed to resolve topic by host query",
       {
         error,
-        scopeId
+        topicId
       }
     );
+    return null;
+  }
+}
+async function tryResolveHostTopicByLegacyScope(ctx, legacyScopeId) {
+  if (typeof ctx.runQuery !== "function") {
+    return null;
   }
   try {
-    const topic = await ctx.runQuery(api.topics.getByLegacyScopeId, {
-      projectId: String(scopeId)
-    });
-    if (topic?.name !== void 0 && topic?.type !== void 0) {
-      return topic;
-    }
+    return await ctx.runQuery(api.topics.getByLegacyScopeId, {
+      projectId: legacyScopeId
+    }) ?? null;
   } catch (error) {
     debugGraphPrimitiveFallback(
-      "[topicProjectOverlay] Failed to resolve topic by legacy scope ID",
-      { error, scopeId }
+      "[topicScope] Failed to resolve topic by legacy scope",
+      {
+        error,
+        legacyScopeId
+      }
     );
+    return null;
   }
-  return null;
-}
-function materializeTopicProjectOverlay(topic, idMode = "legacy") {
-  const metadata = readMetadata(topic);
-  const topicId = String(topic._id);
-  const legacyProjectId = readLegacyProjectId(topic) || readLegacyProjectId(metadata) || readNonEmptyString(metadata.legacyProjectId);
-  const storageProjectId = legacyProjectId || topicId;
-  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;
-  return {
-    ...metadata,
-    _id: outwardId,
-    projectId: outwardId,
-    topicId,
-    storageProjectId,
-    legacyProjectId,
-    name: readNonEmptyString(topic.name) || "Untitled Theme",
-    type: mapProjectType(topic, metadata),
-    description: readNonEmptyString(topic.description),
-    ownerId: readNonEmptyString(metadata.ownerId) || readNonEmptyString(topic.createdBy) || "system",
-    sharedWith: readStringArray(metadata.sharedWith),
-    visibility,
-    tenantId: readNonEmptyString(topic.tenantId) || readNonEmptyString(metadata.tenantId),
-    workspaceId: readNonEmptyString(topic.workspaceId) || readNonEmptyString(metadata.workspaceId),
-    status,
-    tags: readStringArray(metadata.tags),
-    chatCount: typeof metadata.chatCount === "number" ? metadata.chatCount : 0,
-    artifactCount: typeof metadata.artifactCount === "number" ? metadata.artifactCount : 0,
-    lastActivityAt: typeof metadata.lastActivityAt === "number" ? metadata.lastActivityAt : updatedAt,
-    _creationTime: typeof topic._creationTime === "number" ? topic._creationTime : createdAt,
-    createdAt,
-    updatedAt
-  };
 }
-async function resolveTopicProjectOverlay(ctx, scopeId, options = {}) {
-  const topic = await resolveTopicDoc(ctx, scopeId);
-  if (!topic) {
-    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 };
   }
-  if (options.projectLikeOnly !== false && !isProjectLikeTopic(topic)) {
-    return null;
+  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 materializeTopicProjectOverlay(topic, options.idMode);
+  return { tenantId, workspaceId };
 }
-async function listTopicProjectOverlays(ctx, options = {}) {
-  let allTopics = [];
-  if (ctx?.db?.query && typeof ctx.db.query === "function") {
+async function resolveTopicProjectScope(ctx, args) {
+  if (args.topicId) {
+    let topic = null;
     try {
-      allTopics = await ctx.db.query("topics").collect();
+      topic = await ctx.db.get(
+        args.topicId
+      );
     } catch (error) {
       debugGraphPrimitiveFallback(
-        "[topicProjectOverlay] Failed to read topics table; falling back to API",
-        { error }
+        "[topicScope] Failed to load topic by direct id",
+        {
+          error,
+          topicId: args.topicId
+        }
       );
-      allTopics = [];
     }
-  }
-  if (allTopics.length === 0 && typeof ctx.runQuery === "function") {
-    allTopics = (await ctx.runQuery(api.topics.list, {}) ?? []) || [];
-  }
-  return allTopics.filter(
-    (topic) => options.projectLikeOnly === false || isProjectLikeTopic(topic)
-  ).map((topic) => materializeTopicProjectOverlay(topic, options.idMode));
-}
-async function patchTopicProjectOverlay(ctx, scopeId, value) {
-  const topic = await resolveTopicDoc(ctx, scopeId);
-  if (!topic) {
-    return null;
-  }
-  const nextMetadata = { ...readMetadata(topic) };
-  const patch = {};
-  const 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;
-        }
+    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"
+    };
   }
-  patch.updatedAt = Date.now();
-  patch.metadata = nextMetadata;
-  topicUpdateArgs.metadata = nextMetadata;
-  if (typeof ctx.runMutation === "function") {
+  if (args.projectId) {
+    let directTopic = null;
     try {
-      await ctx.runMutation(api.topics.update, topicUpdateArgs);
+      directTopic = await ctx.db.get(
+        args.projectId
+      );
     } catch (error) {
-      if (!isMissingLucernChildComponentError(error) || !ctx?.db || typeof ctx.db.patch !== "function") {
-        throw error;
-      }
-      await ctx.db.patch(String(topic._id), patch);
+      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"
+      };
     }
-  } else if (ctx?.db && typeof ctx.db.patch === "function") {
-    await ctx.db.patch(String(topic._id), patch);
-  } else {
     throw new Error(
-      "Cannot patch topic without component adapter (ctx.runMutation unavailable)"
+      `Legacy project scope ${String(args.projectId)} has no mapped topic.`
     );
   }
-  return materializeTopicProjectOverlay({
-    ...topic,
-    ...patch,
-    metadata: nextMetadata
-  });
-}
-
-// src/resolvers.ts
-function isMissingLucernChildComponentError2(error) {
-  const message = getErrorMessage2(error);
-  return message.includes(
-    'Child component ComponentName(Identifier("lucern")) not found'
-  ) || message.includes("Child component") && message.includes("lucern") && message.includes("not found");
+  throw new Error(
+    "Missing scope: provide topicId (preferred) or legacy projectId alias."
+  );
 }
-function getErrorMessage2(error) {
-  if (error instanceof Error) {
-    return error.message;
-  }
-  if (typeof error === "object" && error !== null && "message" in error && typeof error.message === "string") {
-    return error.message;
+var optionalScopeArgs = {
+  projectId: v.optional(v.string()),
+  topicId: v.optional(v.string())
+};
+function normalizeScopeValue2(value) {
+  if (typeof value !== "string") {
+    return;
   }
-  return "unknown error";
+  const normalized = value.trim();
+  return normalized.length > 0 ? normalized : void 0;
 }
-function isAdvisoryTopicPatch(value) {
-  const advisoryKeys = /* @__PURE__ */ new Set(["lastActivityAt", "updatedAt"]);
-  const keys = Object.keys(value);
-  return keys.length > 0 && keys.every((key) => advisoryKeys.has(key));
+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;
 }
-async function patchProjectWithTolerance(ctx, projectId, value) {
-  try {
-    await patchTopicProjectOverlay(ctx, projectId, value);
-  } catch (error) {
-    if (!isAdvisoryTopicPatch(value) || !isMissingLucernChildComponentError2(error)) {
-      throw error;
-    }
-    console.warn(
-      "[lucern graph-primitives] Non-fatal advisory topic patch failure",
-      {
-        projectId,
-        keys: Object.keys(value),
-        error: getErrorMessage2(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 defaultResolvers() {
-  return {
-    getProject: (ctx, projectId) => resolveTopicProjectOverlay(ctx, projectId, {
-      idMode: "legacy",
-      projectLikeOnly: false
-    }),
-    patchProject: (ctx, projectId, value) => patchProjectWithTolerance(ctx, projectId, value),
-    listTopics: (ctx) => listTopicProjectOverlays(ctx, {
-      idMode: "legacy"
-    }),
-    getFinalArtifact: (ctx, artifactId) => ctx.db.get(artifactId)
-  };
-}
-var resolverOverrides = {};
-function resolveGraphPrimitivesAppResolvers(_ctx) {
-  return {
-    ...defaultResolvers(),
-    ...resolverOverrides
-  };
+function nodeMatchesWorkspaceReasoningScope(node, scope) {
+  if (!node) {
+    return false;
+  }
+  const scopeTenantId = normalizeScopeValue2(scope.tenantId);
+  const scopeWorkspaceId = normalizeScopeValue2(scope.workspaceId);
+  const nodeTenantId = normalizeScopeValue2(node.tenantId);
+  const nodeWorkspaceId = normalizeScopeValue2(node.workspaceId);
+  const epistemicLayer = typeof node.epistemicLayer === "string" ? node.epistemicLayer : void 0;
+  if (scopeTenantId && nodeTenantId && scopeTenantId !== nodeTenantId) {
+    return false;
+  }
+  if (epistemicLayer === "ontological" && nodeWorkspaceId === void 0) {
+    return true;
+  }
+  if (!scopeWorkspaceId && node.publicationStatus === "published") {
+    return true;
+  }
+  if (!scopeWorkspaceId) {
+    return nodeWorkspaceId === void 0;
+  }
+  return scopeWorkspaceId === nodeWorkspaceId;
 }
 
 // src/epistemicBeliefs.helpers.ts
@@ -722,7 +793,7 @@ function buildBeliefConfidenceRow(args) {
     disbelief: args.disbelief,
     uncertainty: args.uncertainty,
     baseRate: args.baseRate,
-    slOperator: args.slOperator ?? "manual_assessment",
+    slOperator: args.slOperator ?? "prior_seed",
     trigger: args.trigger,
     ...args.rationale ? { rationale: args.rationale } : {},
     assessedBy: args.assessedBy,
@@ -856,10 +927,234 @@ async function requireProjectWriteAccess(ctx, projectId, userId) {
   }
 }
 
+// src/epistemicBeliefs.forkEvidence.ts
+function normalizeForkTriggerRelation(value) {
+  if (value === "supports" || value === "supporting") {
+    return "supports";
+  }
+  if (value === "contradicts" || value === "contradicting") {
+    return "contradicts";
+  }
+  return null;
+}
+async function resolveForkTriggerEvidence(ctx, args) {
+  const evidence = await ctx.db.get(args.triggeringEvidenceId);
+  if (!evidence || evidence.nodeType !== "evidence") {
+    throwStructuredMutationError({
+      message: "Fork requires an existing evidence node.",
+      status: 400,
+      code: "INVALID_ARGUMENT",
+      invariantCode: "belief.fork_requires_evidence",
+      suggestion: "Create or link evidence first, then fork with triggeringEvidenceId.",
+      details: { triggeringEvidenceId: args.triggeringEvidenceId }
+    });
+  }
+  if (evidence.topicId && evidence.topicId !== args.parent.topicId) {
+    throwStructuredMutationError({
+      message: "Fork evidence belongs to a different topic scope.",
+      status: 400,
+      code: "INVALID_ARGUMENT",
+      invariantCode: "belief.fork_evidence_scope",
+      suggestion: "Use evidence from the same topic/workspace scope as the parent belief.",
+      details: {
+        parentNodeId: args.parentNodeId,
+        triggeringEvidenceId: args.triggeringEvidenceId
+      }
+    });
+  }
+  const evidenceMetadata = evidence.metadata && typeof evidence.metadata === "object" ? evidence.metadata : {};
+  const parentRefs = new Set(
+    [
+      String(args.parentNodeId),
+      String(args.parent.globalId ?? ""),
+      String(args.parent._id)
+    ].filter(Boolean)
+  );
+  const evidenceRefs = new Set(
+    [
+      String(args.triggeringEvidenceId),
+      String(evidence.globalId ?? ""),
+      String(evidence._id)
+    ].filter(Boolean)
+  );
+  let relation = null;
+  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)));
+      if (matched) {
+        relation = normalizeForkTriggerRelation(matched.relation);
+        break;
+      }
+    }
+  }
+  if (!relation) {
+    throwStructuredMutationError({
+      message: "Fork evidence must already be attached to the parent belief through an SL evidence relation.",
+      status: 409,
+      code: "CONFLICT",
+      invariantCode: "belief.fork_requires_attached_evidence",
+      suggestion: "Attach the evidence to the parent belief as supports or contradicts before forking.",
+      details: {
+        parentNodeId: args.parentNodeId,
+        triggeringEvidenceId: args.triggeringEvidenceId
+      }
+    });
+  }
+  if (args.forkMode === "supersede" && relation !== "contradicts") {
+    throwStructuredMutationError({
+      message: "Superseding fork requires contradicting evidence against the parent belief.",
+      status: 409,
+      code: "CONFLICT",
+      invariantCode: "belief.supersede_requires_contradiction",
+      suggestion: "Use forkMode='branch' for a non-replacing fork, or attach contradicting evidence before superseding.",
+      details: {
+        parentNodeId: args.parentNodeId,
+        triggeringEvidenceId: args.triggeringEvidenceId,
+        relation
+      }
+    });
+  }
+  return { evidenceNodeId: args.triggeringEvidenceId, relation };
+}
+
+// src/epistemicBeliefs.topicAnchor.ts
+function cleanString(value) {
+  return typeof value === "string" && value.trim().length > 0 ? value.trim() : void 0;
+}
+function topicNodeCandidates(topicRef) {
+  const normalized = topicRef.trim();
+  if (!normalized) {
+    return [];
+  }
+  const candidates = [normalized];
+  if (normalized.startsWith("top_")) {
+    candidates.push(normalized.slice(4));
+  }
+  return [...new Set(candidates)];
+}
+function readTopicNodeRef(args) {
+  return cleanString(args.topicGlobalId) ?? cleanString(args.topicNodeId) ?? cleanString(args.topicId);
+}
+async function resolveRequiredTopicAnchor(ctx, topicRef) {
+  for (const candidate of topicNodeCandidates(topicRef)) {
+    try {
+      const direct = await ctx.db.get(candidate);
+      if (direct?.nodeType === "topic" && cleanString(direct.globalId)) {
+        return direct;
+      }
+    } catch (_) {
+    }
+    const byGlobalId = await ctx.db.query("epistemicNodes").withIndex("by_globalId", (q) => q.eq("globalId", candidate)).first();
+    if (byGlobalId?.nodeType === "topic" && cleanString(byGlobalId.globalId)) {
+      return byGlobalId;
+    }
+  }
+  throw new Error(
+    "Belief creation requires topicGlobalId or topicNodeId for a topic node in epistemicNodes. Legacy topics-table IDs are not valid belief anchors."
+  );
+}
+function scopeFromTopicAnchor(topicNode) {
+  return {
+    topicId: topicNode.globalId,
+    projectId: cleanString(topicNode.projectId),
+    tenantId: cleanString(topicNode.tenantId),
+    workspaceId: cleanString(topicNode.workspaceId),
+    source: "topic"
+  };
+}
+async function createRequiredBeliefTopicEdge(ctx, args) {
+  const topicGlobalId = args.topicNode.globalId;
+  const edgeGlobalId = `edge:${args.beliefGlobalId}:${topicGlobalId}:scoped_by`;
+  const now = Date.now();
+  const existing = await ctx.db.query("epistemicEdges").withIndex("by_globalId", (q) => q.eq("globalId", edgeGlobalId)).first();
+  if (!existing) {
+    await ctx.db.insert("epistemicEdges", {
+      globalId: edgeGlobalId,
+      fromNodeId: String(args.beliefNodeId),
+      toNodeId: String(args.topicNode._id),
+      sourceGlobalId: args.beliefGlobalId,
+      targetGlobalId: topicGlobalId,
+      edgeType: "scoped_by",
+      weight: 1,
+      confidence: 1,
+      context: "Belief creation topic anchor invariant.",
+      reasoningMethod: "implicit",
+      derivationType: "topic_scope_invariant",
+      metadata: { invariant: "belief.topic_edge_required" },
+      createdBy: args.createdBy,
+      createdAt: now,
+      updatedAt: now,
+      projectId: cleanString(args.topicNode.projectId),
+      topicId: topicGlobalId,
+      tenantId: cleanString(args.topicNode.tenantId),
+      workspaceId: cleanString(args.topicNode.workspaceId),
+      fromNodeType: "belief",
+      toNodeType: "topic",
+      fromLayer: "L3",
+      toLayer: args.topicNode.epistemicLayer ?? "ontological"
+    });
+  }
+  await ctx.scheduler.runAfter(0, internal.neo4jEdgeAPI.createEdge, {
+    globalId: edgeGlobalId,
+    fromGlobalId: args.beliefGlobalId,
+    toGlobalId: topicGlobalId,
+    edgeType: "scoped_by",
+    weight: 1,
+    confidence: 1,
+    context: "Belief creation topic anchor invariant.",
+    projectId: cleanString(args.topicNode.projectId),
+    topicId: topicGlobalId,
+    createdBy: args.createdBy,
+    fromNodeType: "belief",
+    toNodeType: "topic",
+    fromLayer: "L3",
+    toLayer: args.topicNode.epistemicLayer ?? "ontological",
+    metadata: { invariant: "belief.topic_edge_required" }
+  });
+}
+
+// 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 create = mutation({
   args: {
     ...optionalBeliefScopeArgs,
+    topicNodeId: v.optional(v.string()),
+    topicGlobalId: v.optional(v.string()),
     formulation: v.string(),
     beliefType: v.optional(v.string()),
     rationale: v.optional(v.string()),
@@ -904,20 +1199,32 @@ var create = mutation({
   returns: permissiveReturn,
   handler: async (ctx, args) => {
     const authenticatedUserId = await requireAuthenticatedUserId(ctx);
-    const scope = await resolveTopicProjectScope(ctx, {
-      topicId: args.topicId,
-      projectId: args.projectId
-    });
+    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 topic = await ctx.db.get(scope.topicId);
     const normalizedBeliefType = await assertSchemaEnumValue(ctx, {
       category: "belief_type",
       value: args.beliefType,
-      tenantId: topic?.tenantId,
+      tenantId: scope.tenantId,
       context: "epistemicBeliefs.create"
     });
     if (scope.projectId) {
@@ -950,7 +1257,7 @@ var create = mutation({
       title: args.formulation.slice(0, 100) + (args.formulation.length > 100 ? "..." : ""),
       metadata: {
         pillar,
-        // No confidenceLevel — only set after worktree completion via modulateConfidence()
+        // No confidenceLevel — only set after evidence-backed SL scoring.
         status: "active",
         worktreeId: args.worktreeId,
         beliefStatus: initialBeliefStatus,
@@ -994,9 +1301,15 @@ var create = mutation({
         rationale: "LKC-2 mandatory prior: seeded vacuous opinion at belief creation.",
         assessedBy: authenticatedUserId,
         assessedAt: now,
-        slOperator: "manual_assessment"
+        slOperator: "prior_seed"
       })
     );
+    await createRequiredBeliefTopicEdge(ctx, {
+      beliefNodeId: nodeId,
+      beliefGlobalId,
+      topicNode,
+      createdBy: authenticatedUserId
+    });
     await ctx.scheduler.runAfter(0, internal.neo4jSync.syncNodeToNeo4j, {
       nodeId,
       operation: "upsert"
@@ -1333,9 +1646,10 @@ var forkBelief = mutation({
       v.literal("refinement"),
       v.literal("contradiction_response"),
       v.literal("scope_change"),
-      v.literal("confidence_collapse"),
-      v.literal("manual")
+      v.literal("confidence_collapse")
     ),
+    forkMode: v.optional(v.union(v.literal("supersede"), v.literal("branch"))),
+    triggeringEvidenceId: v.id("epistemicNodes"),
     rationale: v.optional(v.string()),
     userId: v.string()
   },
@@ -1378,6 +1692,33 @@ var forkBelief = mutation({
     await requireProjectWriteAccess(ctx, parent.projectId, authenticatedUserId);
     const metadata = parent.metadata;
     const forkBeliefStatus = "hypothesis";
+    const forkMode = args.forkMode ?? "supersede";
+    const triggerEvidence = await resolveForkTriggerEvidence(ctx, {
+      parentNodeId: args.parentNodeId,
+      parent,
+      triggeringEvidenceId: args.triggeringEvidenceId,
+      forkMode
+    });
+    const parentLifecycleStatus = resolveBeliefLifecycleStatus({
+      beliefStatus: parent.beliefStatus,
+      confidence: parent.confidence,
+      predictionMeta: parent.predictionMeta,
+      metadata
+    });
+    if (forkMode === "supersede" && parentLifecycleStatus !== "active") {
+      throwStructuredMutationError({
+        message: "Superseding fork requires an active parent belief. Attach evidence first so the lifecycle can promote deterministically.",
+        status: 409,
+        code: "CONFLICT",
+        invariantCode: "belief.supersede_requires_active_parent",
+        suggestion: "Attach the contradicting evidence to the parent belief, let the evidence path promote it to active, then supersede.",
+        details: {
+          parentNodeId: args.parentNodeId,
+          parentLifecycleStatus,
+          triggeringEvidenceId: args.triggeringEvidenceId
+        }
+      });
+    }
     const newBeliefGlobalId = generateGlobalId();
     const newNodeId = await ctx.db.insert("epistemicNodes", {
       globalId: newBeliefGlobalId,
@@ -1391,6 +1732,9 @@ var forkBelief = mutation({
         ...metadata,
         forkedFrom: args.parentNodeId,
         forkReason: args.forkReason,
+        forkMode,
+        triggeringEvidenceId: args.triggeringEvidenceId,
+        triggeringEvidenceRelation: triggerEvidence.relation,
         forkTimestamp: now,
         forkedBy: authenticatedUserId,
         status: "active",
@@ -1409,6 +1753,27 @@ var forkBelief = mutation({
       createdAt: now,
       updatedAt: now
     });
+    if (forkMode === "supersede") {
+      await ctx.db.patch(args.parentNodeId, {
+        status: "superseded",
+        beliefStatus: "superseded",
+        epistemicStatus: "superseded",
+        supersededBy: newNodeId,
+        updatedAt: now,
+        metadata: {
+          ...metadata ?? {},
+          status: "superseded",
+          beliefStatus: "superseded",
+          epistemicStatus: "superseded",
+          supersededBy: String(newNodeId),
+          supersededByEvidenceId: String(triggerEvidence.evidenceNodeId)
+        }
+      });
+      await ctx.scheduler.runAfter(0, internal.neo4jSync.syncNodeToNeo4j, {
+        nodeId: args.parentNodeId,
+        operation: "upsert"
+      });
+    }
     const inheritedContracts = await ctx.db.query("epistemicContracts").withIndex(
       "by_belief",
       (q) => q.eq("beliefNodeId", args.parentNodeId)
@@ -1435,12 +1800,17 @@ var forkBelief = mutation({
       globalId: generateGlobalId(),
       fromGlobalId: newBeliefGlobalId,
       toGlobalId: parent.globalId,
-      edgeType: "supersedes",
-      context: `Fork reason: ${args.forkReason}`,
+      edgeType: forkMode === "supersede" ? "supersedes" : "derived_from",
+      context: `Fork reason: ${args.forkReason}; triggering evidence: ${triggerEvidence.evidenceNodeId}`,
       createdBy: authenticatedUserId,
       topicId: parent.projectId ? String(parent.projectId) : void 0,
       fromNodeType: "belief",
-      toNodeType: "belief"
+      toNodeType: "belief",
+      metadata: {
+        forkMode,
+        triggeringEvidenceId: String(triggerEvidence.evidenceNodeId),
+        triggeringEvidenceRelation: triggerEvidence.relation
+      }
     });
     await scheduleEmbeddingGeneration({
       ctx,
@@ -1465,6 +1835,9 @@ var forkBelief = mutation({
       newState: {
         formulation: args.newFormulation,
         forkReason: args.forkReason,
+        forkMode,
+        triggeringEvidenceId: String(triggerEvidence.evidenceNodeId),
+        triggeringEvidenceRelation: triggerEvidence.relation,
         tupleContradicted: false
       },
       projectId: parent.projectId,
@@ -1499,7 +1872,14 @@ var forkBelief = mutation({
       projectId: parent.projectId,
       topicId: parent.topicId
     });
-    return { newNodeId, parentNodeId: args.parentNodeId };
+    return {
+      newNodeId,
+      parentNodeId: args.parentNodeId,
+      forkMode,
+      forkReason: args.forkReason,
+      triggeringEvidenceId: triggerEvidence.evidenceNodeId,
+      triggeringEvidenceRelation: triggerEvidence.relation
+    };
   }
 });