@lucern/graph-primitives 1.0.29 → 1.0.31

package/dist/epistemicEvidence.js

@@ -1,14 +1,25 @@
 import { canAudienceClassAccess, normalizeAudienceKey, classFromAudienceKey } from '@lucern/access-control/audience';
-import { componentsGeneric, anyApi, mutationGeneric, internalMutationGeneric, queryGeneric, internalQueryGeneric } from 'convex/server';
+import { unsafeConvexAnyApi } from '@lucern/contracts/convex/unsafeAnyApi';
+import { componentsGeneric, mutationGeneric, internalMutationGeneric, queryGeneric, internalQueryGeneric } from 'convex/server';
 import { v } from 'convex/values';
 import { requireScopeWriteAccess, checkScopeAccess } from '@lucern/access-control/access';
+import { EVIDENCE_SOURCE_QUALITY_VALUES, EVIDENCE_METHODOLOGY_VALUES, EVIDENCE_INFORMATION_ASYMMETRY_VALUES, assertEdgePolicyAllowed, edgePolicyManifest } from '@lucern/contracts';
 import { permissiveReturn } from '@lucern/contracts/schema-helpers/validators';
 import { generateGlobalId, assertUuidV7Identity, assertStorageEdgeVocabulary, assertUuidShapedEdgeEndpoint } from '@lucern/contracts/ids';
 import { isNodeType, getLayerForNodeType } from '@lucern/contracts/schema-helpers/spine/tables/epistemicNodes';
-import { assertEdgePolicyAllowed, edgePolicyManifest } from '@lucern/contracts';
 import { listAudienceRegistryRows } from '@lucern/access-control/audienceRegistry';
 
 // src/epistemicEvidenceHelpers.ts
+var unsafeApi = unsafeConvexAnyApi(
+  "graph-primitives top-level module bundle lacks a committed Convex _generated/api surface"
+);
+var api = unsafeApi;
+componentsGeneric();
+var internal = unsafeApi;
+var internalMutation = internalMutationGeneric;
+var internalQuery = internalQueryGeneric;
+var mutation = mutationGeneric;
+var query = queryGeneric;
 
 // src/debug.ts
 function isGraphPrimitiveDebugEnabled() {
@@ -21,13 +32,6 @@ function debugGraphPrimitiveFallback(message, context) {
   }
   console.debug(message, context ?? {});
 }
-var api = anyApi;
-componentsGeneric();
-var internal = anyApi;
-var internalMutation = internalMutationGeneric;
-var internalQuery = internalQueryGeneric;
-var mutation = mutationGeneric;
-var query = queryGeneric;
 
 // src/topicProjectOverlay.ts
 var LEGACY_SCOPE_FIELD = "graphScopeProjectId";
@@ -47,6 +51,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;
@@ -127,9 +135,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;
     }
@@ -149,8 +160,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,
@@ -219,90 +240,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);
   }
-  patch.updatedAt = Date.now();
-  patch.metadata = nextMetadata;
-  topicUpdateArgs.metadata = nextMetadata;
+  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;
+  }
+  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
@@ -330,7 +374,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(
@@ -397,13 +441,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") {
@@ -428,8 +474,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();
@@ -441,7 +488,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);
@@ -497,137 +544,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())
@@ -670,7 +695,7 @@ function normalizeSourceType(sourceType) {
 async function markProjectGraphDirty(ctx, projectId, topicId) {
   const normalizedProjectId = typeof projectId === "string" && projectId.trim().length > 0 ? projectId : void 0;
   const normalizedTopicId = typeof topicId === "string" && topicId.trim().length > 0 ? topicId : void 0;
-  if (!normalizedProjectId && !normalizedTopicId) {
+  if (!(normalizedProjectId || normalizedTopicId)) {
     return;
   }
   if (normalizedProjectId) {
@@ -691,9 +716,15 @@ async function markProjectGraphDirty(ctx, projectId, topicId) {
       }
     );
   }
+  const activityScopeId = normalizedTopicId ?? normalizedProjectId;
+  if (!activityScopeId) {
+    throw new Error(
+      "Expected evidence graph dirty scope to include a topic or project id."
+    );
+  }
   await resolveGraphPrimitivesAppResolvers().patchProject(
     ctx,
-    normalizedTopicId ?? normalizedProjectId,
+    activityScopeId,
     {
       lastActivityAt: Date.now()
     }
@@ -722,7 +753,15 @@ function dedupeEvidenceNodes(nodes) {
   return deduped;
 }
 function evidenceMatchesScope(node, scope) {
-  return scope.topicId !== void 0 && node.topicId === scope.topicId || scope.projectId !== void 0 && node.projectId === scope.projectId;
+  const record = node && typeof node === "object" && !Array.isArray(node) ? node : null;
+  if (!record) {
+    return false;
+  }
+  const nodeTopicId = typeof record.topicId === "string" ? record.topicId : void 0;
+  const nodeProjectId = typeof record.projectId === "string" ? record.projectId : void 0;
+  const scopeTopicId = scope.topicId === void 0 ? void 0 : String(scope.topicId);
+  const scopeProjectId = scope.projectId === void 0 ? void 0 : String(scope.projectId);
+  return scopeTopicId !== void 0 && nodeTopicId === scopeTopicId || scopeProjectId !== void 0 && nodeProjectId === scopeProjectId;
 }
 function resolveEvidenceLinkedWorktreeId(metadata) {
   const worktreeId = metadata?.linkedWorktreeId;
@@ -733,7 +772,7 @@ function resolveEvidenceLinkedWorktreeId(metadata) {
   return typeof sprintId === "string" && sprintId.trim().length > 0 ? sprintId : void 0;
 }
 async function resolveEvidenceScopeOrNull(ctx, args) {
-  if (!args.projectId && !args.topicId) {
+  if (!(args.projectId || args.topicId)) {
     return null;
   }
   try {
@@ -829,22 +868,19 @@ function formatEvidenceNode(n) {
 }
 
 // src/embeddingTrigger.ts
+var embeddingActionRef = "embeddingActions:generateEpistemicNodeEmbedding";
 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
-      }
-    );
+    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",
@@ -856,6 +892,55 @@ async function scheduleEmbeddingGeneration(args) {
     );
   }
 }
+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();
+  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)`
+    );
+  }
+}
+async function insertEpistemicEdge(ctx, doc) {
+  assertUuidV7Identity("epistemicEdges", doc.globalId);
+  assertStorageEdgeVocabulary(doc.edgeType);
+  if (!doc.fromNodeId || typeof doc.fromNodeId !== "string") {
+    throw new Error(
+      "edge_endpoint_missing: epistemicEdges insert requires a non-empty fromNodeId"
+    );
+  }
+  if (!doc.toNodeId || typeof doc.toNodeId !== "string") {
+    throw new Error(
+      "edge_endpoint_missing: epistemicEdges insert requires a non-empty toNodeId"
+    );
+  }
+  await assertExistingNodeEndpoint(ctx, "fromNodeId", doc.fromNodeId);
+  await assertExistingNodeEndpoint(ctx, "toNodeId", doc.toNodeId);
+  if (doc.fromNodeType && doc.toNodeType && doc.edgeType !== "extracted_from") {
+    assertEdgePolicyAllowed(
+      edgePolicyManifest,
+      doc.edgeType,
+      {
+        kind: "epistemic_node",
+        nodeId: doc.fromNodeId,
+        nodeType: doc.fromNodeType
+      },
+      {
+        kind: "epistemic_node",
+        nodeId: doc.toNodeId,
+        nodeType: doc.toNodeType
+      }
+    );
+  }
+  return ctx.db.insert("epistemicEdges", doc);
+}
 function normalizeScopeValue2(value) {
   if (typeof value !== "string") {
     return;
@@ -917,7 +1002,7 @@ function nodeMatchesWorkspaceReasoningScope(node, scope) {
   return scopeWorkspaceId === nodeWorkspaceId;
 }
 function resolveRuntimePackMutationContext(args) {
-  if (!args.runtimeToolName && !args.runtimePackKey && !args.runtimePackInstallScope) {
+  if (!(args.runtimeToolName || args.runtimePackKey || args.runtimePackInstallScope)) {
     return;
   }
   return {
@@ -949,54 +1034,118 @@ function assertTenantPackWorkspaceMutationAllowed(args) {
     }
   });
 }
-async function insertEpistemicNode(ctx, doc) {
-  assertUuidV7Identity("epistemicNodes", doc.globalId);
-  return ctx.db.insert("epistemicNodes", doc);
+
+// src/epistemicEvidenceMutations.ts
+var EMBEDDING_GENERATION_ACTION = "embeddingActions:generateEpistemicNodeEmbedding";
+function isRecord(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
 }
-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();
-  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)`
-    );
+function metadataRecord(value) {
+  return isRecord(value) ? value : {};
+}
+function readOptionalString(value) {
+  if (typeof value !== "string") {
+    return;
   }
+  const trimmed = value.trim();
+  return trimmed.length > 0 ? trimmed : void 0;
 }
-async function insertEpistemicEdge(ctx, doc) {
-  assertUuidV7Identity("epistemicEdges", doc.globalId);
-  assertStorageEdgeVocabulary(doc.edgeType);
-  if (!doc.fromNodeId || typeof doc.fromNodeId !== "string") {
-    throw new Error(
-      "edge_endpoint_missing: epistemicEdges insert requires a non-empty fromNodeId"
-    );
+function readConvexId(value) {
+  const normalized = readOptionalString(value);
+  return normalized;
+}
+function assertBeliefNode(node, errorMessage) {
+  if (!isRecord(node) || node.nodeType !== "belief" || typeof node.globalId !== "string") {
+    throw new Error(errorMessage);
   }
-  if (!doc.toNodeId || typeof doc.toNodeId !== "string") {
-    throw new Error(
-      "edge_endpoint_missing: epistemicEdges insert requires a non-empty toNodeId"
-    );
+  return node;
+}
+function assertEvidenceNode(node, errorMessage) {
+  if (!isRecord(node)) {
+    throw new Error(errorMessage);
   }
-  await assertExistingNodeEndpoint(ctx, "fromNodeId", doc.fromNodeId);
-  await assertExistingNodeEndpoint(ctx, "toNodeId", doc.toNodeId);
-  if (doc.fromNodeType && doc.toNodeType && doc.edgeType !== "extracted_from") {
-    assertEdgePolicyAllowed(
-      edgePolicyManifest,
-      doc.edgeType,
-      {
-        kind: "epistemic_node",
-        nodeId: doc.fromNodeId,
-        nodeType: doc.fromNodeType
-      },
-      {
-        kind: "epistemic_node",
-        nodeId: doc.toNodeId,
-        nodeType: doc.toNodeType
+  const id = readConvexId(node._id);
+  if (!(id && node.nodeType === "evidence")) {
+    throw new Error(errorMessage);
+  }
+  const evidence = { _id: id, nodeType: "evidence" };
+  const canonicalText = readOptionalString(node.canonicalText);
+  if (canonicalText !== void 0) {
+    evidence.canonicalText = canonicalText;
+  }
+  const createdBy = readOptionalString(node.createdBy);
+  if (createdBy !== void 0) {
+    evidence.createdBy = createdBy;
+  }
+  if ("metadata" in node) {
+    evidence.metadata = node.metadata;
+  }
+  const projectId = readOptionalString(node.projectId);
+  if (projectId !== void 0) {
+    evidence.projectId = projectId;
+  }
+  const status = readOptionalString(node.status);
+  if (status !== void 0) {
+    evidence.status = status;
+  }
+  const topicId = readOptionalString(node.topicId);
+  if (topicId !== void 0) {
+    evidence.topicId = topicId;
+  }
+  return evidence;
+}
+function readEvidenceNodeOrNull(node) {
+  if (!isRecord(node) || node.nodeType !== "evidence") {
+    return null;
+  }
+  try {
+    return assertEvidenceNode(node, "Evidence node not found");
+  } catch {
+    return null;
+  }
+}
+function optionalTrimmedString(value) {
+  if (typeof value !== "string") {
+    return;
+  }
+  const trimmed = value.trim();
+  return trimmed.length > 0 ? trimmed : void 0;
+}
+async function resolveEvidenceNodeId(ctx, args) {
+  if (args.nodeId) {
+    return args.nodeId;
+  }
+  const insightId = readOptionalString(args.insightId);
+  if (!insightId) {
+    throw new Error("Either nodeId or insightId is required");
+  }
+  const normalizedId = ctx.db.normalizeId?.("epistemicNodes", insightId) ?? readConvexId(insightId);
+  if (normalizedId) {
+    try {
+      const direct = readEvidenceNodeOrNull(await ctx.db.get(normalizedId));
+      if (direct) {
+        return direct._id;
       }
-    );
+    } catch {
+    }
   }
-  return ctx.db.insert("epistemicEdges", doc);
+  const byGlobalId = readEvidenceNodeOrNull(
+    await ctx.db.query("epistemicNodes").withIndex("by_globalId", (q) => q.eq("globalId", insightId)).first()
+  );
+  if (!byGlobalId) {
+    throw new Error("Evidence node not found");
+  }
+  return byGlobalId._id;
+}
+function optionalLiteral(values, value, fieldName) {
+  if (typeof value !== "string" || value.length === 0) {
+    return;
+  }
+  if (values.includes(value)) {
+    return value;
+  }
+  throw new Error(`Evidence ${fieldName} must be one of: ${values.join(", ")}`);
 }
-
-// src/epistemicEvidenceMutations.ts
 function assertSignedImpactScore(value, context) {
   if (typeof value !== "number" || !Number.isFinite(value) || value === 0 || value < -1 || value > 1) {
     throw new Error(`${context} requires explicit nonzero weight in [-1, 1]`);
@@ -1009,12 +1158,121 @@ function normalizeEvidenceRelation(relation, weight, context) {
       throw new Error(`${context} supports relation requires positive weight`);
     }
     if (relation === "contradicts" && weight > 0) {
-      throw new Error(`${context} contradicts relation requires negative weight`);
+      throw new Error(
+        `${context} contradicts relation requires negative weight`
+      );
     }
     return relation;
   }
   return weight < 0 ? "contradicts" : "supports";
 }
+function planEvidenceImpact(args, context) {
+  const weight = assertSignedImpactScore(args.weight, context);
+  const signedImpact = args.signedImpact === void 0 ? weight : assertSignedImpactScore(args.signedImpact, `${context} signedImpact`);
+  return {
+    confidence: Math.abs(weight),
+    evidenceRelation: normalizeEvidenceRelation(
+      args.evidenceRelation,
+      weight,
+      context
+    ),
+    signedImpact,
+    weight
+  };
+}
+function evidenceTaxonomyProjection(args) {
+  const sourceRef = optionalTrimmedString(args.sourceRef);
+  const sourceQuality = optionalLiteral(
+    EVIDENCE_SOURCE_QUALITY_VALUES,
+    args.sourceQuality,
+    "sourceQuality"
+  );
+  const methodology = optionalLiteral(
+    EVIDENCE_METHODOLOGY_VALUES,
+    args.methodology,
+    "methodology"
+  );
+  const informationAsymmetry = optionalLiteral(
+    EVIDENCE_INFORMATION_ASYMMETRY_VALUES,
+    args.informationAsymmetry,
+    "informationAsymmetry"
+  );
+  const sourceDescription = optionalTrimmedString(args.sourceDescription);
+  return {
+    ...sourceRef ? { sourceRef } : {},
+    ...sourceQuality ? { sourceQuality } : {},
+    ...methodology ? { methodology } : {},
+    ...informationAsymmetry ? { informationAsymmetry } : {},
+    ...sourceDescription ? { sourceDescription } : {}
+  };
+}
+function evidenceTextProjection(args) {
+  const title = optionalTrimmedString(args.title);
+  const contentType = optionalTrimmedString(args.contentType);
+  return {
+    ...title ? { title } : {},
+    ...typeof args.content === "string" && args.content.length > 0 ? { content: args.content } : {},
+    ...contentType ? { contentType } : {}
+  };
+}
+function evidenceMetadata(args, impact, kind, profile) {
+  const base = {
+    kind,
+    tags: args.tags || [],
+    linkedBeliefNodeId: args.linkedBeliefNodeId,
+    evidenceRelation: impact.evidenceRelation,
+    confidence: impact.confidence,
+    weight: impact.weight,
+    impactScore: impact.weight
+  };
+  const sourceContext = profile === "createAndLink" ? {} : {
+    externalSourceType: args.externalSourceType,
+    sourceUrl: args.sourceUrl,
+    sourceQuestionId: args.sourceQuestionId,
+    rationale: args.rationale
+  };
+  const publicCreateTaxonomy = profile === "create" ? {
+    methodology: args.methodology,
+    informationAsymmetry: args.informationAsymmetry,
+    sourceDescription: args.sourceDescription
+  } : {};
+  return {
+    ...base,
+    ...sourceContext,
+    ...publicCreateTaxonomy,
+    ...metadataRecord(args.metadata)
+  };
+}
+function buildEvidenceNodeInsert(args) {
+  return {
+    globalId: args.globalId,
+    topicId: args.scope.topicId,
+    projectId: args.scope.projectId,
+    tenantId: args.scope.tenantId,
+    workspaceId: args.scope.workspaceId,
+    nodeType: "evidence",
+    canonicalText: args.write.text,
+    contentHash: generateContentHash(args.write.text),
+    ...evidenceTextProjection(args.write),
+    status: "active",
+    epistemicLayer: "L2",
+    sourceType: args.sourceType,
+    // RC.1 taxonomy fields — top-level projection
+    evidenceRelation: args.impact.evidenceRelation,
+    signedImpact: args.impact.signedImpact,
+    targetBeliefId: String(args.linkedBeliefNodeId),
+    ...evidenceTaxonomyProjection(args.write),
+    createdAt: args.now,
+    updatedAt: args.now,
+    createdBy: args.write.userId,
+    metadata: evidenceMetadata(
+      args.write,
+      args.impact,
+      args.kind,
+      args.metadataProfile
+    )
+  };
+}
 async function createEvidenceBeliefEdge(ctx, args) {
   const edgeGlobalId = generateGlobalId();
   const confidence = Math.abs(args.weight);
@@ -1139,66 +1397,27 @@ var create = mutation({
     }
     const now = Date.now();
     const globalId = generateGlobalId();
-    const contentHash = generateContentHash(args.text);
     const kind = normalizeKind(args.kind);
     const sourceType = normalizeSourceType(args.sourceType);
-    const weight = assertSignedImpactScore(args.weight, "Evidence creation");
-    const signedImpact = args.signedImpact !== void 0 ? assertSignedImpactScore(args.signedImpact, "Evidence creation signedImpact") : weight;
-    const evidenceRelation = normalizeEvidenceRelation(
-      args.evidenceRelation,
-      weight,
-      "Evidence creation"
+    const impact = planEvidenceImpact(args, "Evidence creation");
+    const linkedBeliefNode = assertBeliefNode(
+      await ctx.db.get(args.linkedBeliefNodeId),
+      "Evidence creation requires a linked belief node"
     );
-    const linkedBeliefNode = await ctx.db.get(args.linkedBeliefNodeId);
-    if (!linkedBeliefNode || linkedBeliefNode.nodeType !== "belief") {
-      throw new Error("Evidence creation requires a linked belief node");
-    }
-    const additionalMetadata = args.metadata && typeof args.metadata === "object" ? args.metadata : {};
-    const nodeId = await insertEpistemicNode(ctx, {
-      globalId,
-      topicId: scope.topicId,
-      projectId: scope.projectId,
-      tenantId: scope.tenantId,
-      workspaceId: scope.workspaceId,
-      nodeType: "evidence",
-      canonicalText: args.text,
-      contentHash,
-      ...typeof args.title === "string" && args.title.trim().length > 0 ? { title: args.title.trim() } : {},
-      ...typeof args.content === "string" && args.content.length > 0 ? { content: args.content } : {},
-      ...typeof args.contentType === "string" && args.contentType.trim().length > 0 ? { contentType: args.contentType.trim() } : {},
-      status: "active",
-      epistemicLayer: "L2",
-      sourceType,
-      // RC.1 taxonomy fields — top-level projection
-      evidenceRelation,
-      signedImpact,
-      targetBeliefId: String(args.linkedBeliefNodeId),
-      ...typeof args.sourceRef === "string" && args.sourceRef.trim().length > 0 ? { sourceRef: args.sourceRef.trim() } : {},
-      ...typeof args.sourceQuality === "string" && args.sourceQuality.length > 0 ? { sourceQuality: args.sourceQuality } : {},
-      ...typeof args.methodology === "string" && args.methodology.length > 0 ? { methodology: args.methodology } : {},
-      ...typeof args.informationAsymmetry === "string" && args.informationAsymmetry.length > 0 ? { informationAsymmetry: args.informationAsymmetry } : {},
-      ...typeof args.sourceDescription === "string" && args.sourceDescription.trim().length > 0 ? { sourceDescription: args.sourceDescription.trim() } : {},
-      createdAt: now,
-      updatedAt: now,
-      createdBy: args.userId,
-      metadata: {
+    const nodeId = await insertEpistemicNode(
+      ctx,
+      buildEvidenceNodeInsert({
+        globalId,
+        impact,
         kind,
-        tags: args.tags || [],
-        externalSourceType: args.externalSourceType,
-        sourceUrl: args.sourceUrl,
-        sourceQuestionId: args.sourceQuestionId,
-        rationale: args.rationale,
         linkedBeliefNodeId: args.linkedBeliefNodeId,
-        evidenceRelation,
-        confidence: Math.abs(weight),
-        weight,
-        impactScore: weight,
-        methodology: args.methodology,
-        informationAsymmetry: args.informationAsymmetry,
-        sourceDescription: args.sourceDescription,
-        ...additionalMetadata
-      }
-    });
+        metadataProfile: "create",
+        now,
+        scope,
+        sourceType,
+        write: args
+      })
+    );
     await ctx.scheduler.runAfter(0, internal.neo4jSync.syncNodeToNeo4j, {
       nodeId,
       operation: "upsert"
@@ -1216,8 +1435,8 @@ var create = mutation({
       evidenceGlobalId: globalId,
       beliefNodeId: args.linkedBeliefNodeId,
       beliefGlobalId: linkedBeliefNode.globalId,
-      relation: evidenceRelation,
-      weight,
+      relation: impact.evidenceRelation,
+      weight: impact.weight,
       userId: args.userId,
       topicId: scope.topicId ? String(scope.topicId) : void 0,
       projectId: scope.projectId ? String(scope.projectId) : void 0,
@@ -1237,23 +1456,19 @@ var create = mutation({
         kind,
         sourceType,
         linkedBeliefNodeId: args.linkedBeliefNodeId,
-        evidenceRelation,
-        weight
+        evidenceRelation: impact.evidenceRelation,
+        weight: impact.weight
       }
     });
     if (scope.projectId || scope.topicId) {
-      await ctx.scheduler.runAfter(
-        0,
-        "embeddingActions:generateEpistemicNodeEmbedding",
-        {
-          nodeId,
-          projectId: scope.projectId,
-          topicId: scope.topicId ? String(scope.topicId) : void 0,
-          createdBy: args.userId,
-          nodeType: "evidence",
-          text: args.text
-        }
-      );
+      await ctx.scheduler.runAfter(0, EMBEDDING_GENERATION_ACTION, {
+        nodeId,
+        projectId: scope.projectId,
+        topicId: scope.topicId ? String(scope.topicId) : void 0,
+        createdBy: args.userId,
+        nodeType: "evidence",
+        text: args.text
+      });
     }
     if (scope.projectId || scope.topicId) {
       await ctx.scheduler.runAfter(
@@ -1267,7 +1482,11 @@ var create = mutation({
         }
       );
     }
-    await markProjectGraphDirty(ctx, scope.projectId, String(scope.topicId));
+    await markProjectGraphDirty(
+      ctx,
+      scope.projectId,
+      scope.topicId ? String(scope.topicId) : void 0
+    );
     return { nodeId };
   }
 });
@@ -1305,58 +1524,39 @@ var createAndLink = mutation({
     if (!scope) {
       throw new Error("Invalid scope: projectId or topicId is required");
     }
-    await requireScopeWriteAccess(ctx, String(scope.topicId), args.userId);
+    const accessScopeId = scope.projectId ?? (scope.topicId ? String(scope.topicId) : void 0);
+    if (!accessScopeId) {
+      throw new Error("Resolved evidence scope has no access-control id");
+    }
+    await requireScopeWriteAccess(ctx, accessScopeId, args.userId);
     const now = Date.now();
     const globalId = generateGlobalId();
-    const contentHash = generateContentHash(args.text);
     const kind = normalizeKind(args.kind);
     const sourceType = normalizeSourceType(args.sourceType);
-    const weight = assertSignedImpactScore(args.weight, "Evidence createAndLink");
-    const signedImpact = args.signedImpact !== void 0 ? assertSignedImpactScore(args.signedImpact, "Evidence createAndLink signedImpact") : weight;
-    const relation = normalizeEvidenceRelation(
-      args.relation,
-      weight,
-      "Evidence createAndLink"
+    const write = {
+      ...args,
+      evidenceRelation: args.relation,
+      linkedBeliefNodeId: args.beliefNodeId
+    };
+    const impact = planEvidenceImpact(write, "Evidence createAndLink");
+    const beliefNode = assertBeliefNode(
+      await ctx.db.get(args.beliefNodeId),
+      "Belief node not found for edge creation"
     );
-    const confidence = Math.abs(weight);
-    const beliefNode = await ctx.db.get(args.beliefNodeId);
-    if (!beliefNode || beliefNode.nodeType !== "belief") {
-      throw new Error("Belief node not found for edge creation");
-    }
-    const nodeId = await insertEpistemicNode(ctx, {
-      globalId,
-      topicId: scope.topicId,
-      projectId: scope.projectId,
-      tenantId: scope.tenantId,
-      workspaceId: scope.workspaceId,
-      nodeType: "evidence",
-      canonicalText: args.text,
-      contentHash,
-      status: "active",
-      epistemicLayer: "L2",
-      sourceType,
-      // RC.1 taxonomy fields — top-level projection
-      evidenceRelation: relation,
-      signedImpact,
-      targetBeliefId: String(args.beliefNodeId),
-      ...typeof args.sourceRef === "string" && args.sourceRef.trim().length > 0 ? { sourceRef: args.sourceRef.trim() } : {},
-      ...typeof args.sourceQuality === "string" && args.sourceQuality.length > 0 ? { sourceQuality: args.sourceQuality } : {},
-      ...typeof args.methodology === "string" && args.methodology.length > 0 ? { methodology: args.methodology } : {},
-      ...typeof args.informationAsymmetry === "string" && args.informationAsymmetry.length > 0 ? { informationAsymmetry: args.informationAsymmetry } : {},
-      ...typeof args.sourceDescription === "string" && args.sourceDescription.trim().length > 0 ? { sourceDescription: args.sourceDescription.trim() } : {},
-      createdAt: now,
-      updatedAt: now,
-      createdBy: args.userId,
-      metadata: {
+    const nodeId = await insertEpistemicNode(
+      ctx,
+      buildEvidenceNodeInsert({
+        globalId,
+        impact,
         kind,
-        tags: args.tags || [],
         linkedBeliefNodeId: args.beliefNodeId,
-        evidenceRelation: relation,
-        confidence,
-        weight,
-        impactScore: weight
-      }
-    });
+        metadataProfile: "createAndLink",
+        now,
+        scope,
+        sourceType,
+        write
+      })
+    );
     await ctx.scheduler.runAfter(0, internal.neo4jSync.syncNodeToNeo4j, {
       nodeId,
       operation: "upsert"
@@ -1365,13 +1565,17 @@ var createAndLink = mutation({
       evidenceGlobalId: globalId,
       beliefNodeId: args.beliefNodeId,
       beliefGlobalId: beliefNode.globalId,
-      relation,
-      weight,
+      relation: impact.evidenceRelation,
+      weight: impact.weight,
       userId: args.userId,
       topicId: scope.topicId ? String(scope.topicId) : void 0,
       projectId: scope.projectId ? String(scope.projectId) : void 0
     });
-    await markProjectGraphDirty(ctx, scope.projectId, String(scope.topicId));
+    await markProjectGraphDirty(
+      ctx,
+      scope.projectId,
+      scope.topicId ? String(scope.topicId) : void 0
+    );
     return { nodeId, edgeGlobalId };
   }
 });
@@ -1387,10 +1591,10 @@ var updateStatus = mutation({
   },
   returns: permissiveReturn,
   handler: async (ctx, args) => {
-    const node = await ctx.db.get(args.nodeId);
-    if (!node || node.nodeType !== "evidence") {
-      throw new Error("Evidence not found");
-    }
+    const node = assertEvidenceNode(
+      await ctx.db.get(args.nodeId),
+      "Evidence not found"
+    );
     const now = Date.now();
     await ctx.db.patch(args.nodeId, {
       status: args.status,
@@ -1479,63 +1683,27 @@ var internalCreate = internalMutation({
       mutationName: "epistemicEvidence.internalCreate"
     });
     const globalId = generateGlobalId();
-    const contentHash = generateContentHash(args.text);
     const kind = normalizeKind(args.kind);
     const sourceType = normalizeSourceType(args.sourceType);
-    const weight = assertSignedImpactScore(args.weight, "Internal evidence creation");
-    const signedImpact = args.signedImpact !== void 0 ? assertSignedImpactScore(args.signedImpact, "Internal evidence creation signedImpact") : weight;
-    const evidenceRelation = normalizeEvidenceRelation(
-      args.evidenceRelation,
-      weight,
-      "Internal evidence creation"
+    const impact = planEvidenceImpact(args, "Internal evidence creation");
+    const linkedBeliefNode = assertBeliefNode(
+      await ctx.db.get(args.linkedBeliefNodeId),
+      "Internal evidence creation requires a linked belief node"
     );
-    const linkedBeliefNode = await ctx.db.get(args.linkedBeliefNodeId);
-    if (!linkedBeliefNode || linkedBeliefNode.nodeType !== "belief") {
-      throw new Error("Internal evidence creation requires a linked belief node");
-    }
-    const additionalMetadata = args.metadata && typeof args.metadata === "object" ? args.metadata : {};
-    const nodeId = await insertEpistemicNode(ctx, {
-      globalId,
-      topicId: scope.topicId,
-      projectId: scope.projectId,
-      tenantId: scope.tenantId,
-      workspaceId: scope.workspaceId,
-      nodeType: "evidence",
-      canonicalText: args.text,
-      contentHash,
-      ...typeof args.title === "string" && args.title.trim().length > 0 ? { title: args.title.trim() } : {},
-      ...typeof args.content === "string" && args.content.length > 0 ? { content: args.content } : {},
-      ...typeof args.contentType === "string" && args.contentType.trim().length > 0 ? { contentType: args.contentType.trim() } : {},
-      status: "active",
-      epistemicLayer: "L2",
-      sourceType,
-      // RC.1 taxonomy fields — top-level projection
-      evidenceRelation,
-      signedImpact,
-      targetBeliefId: String(args.linkedBeliefNodeId),
-      ...typeof args.sourceRef === "string" && args.sourceRef.trim().length > 0 ? { sourceRef: args.sourceRef.trim() } : {},
-      ...typeof args.sourceQuality === "string" && args.sourceQuality.length > 0 ? { sourceQuality: args.sourceQuality } : {},
-      ...typeof args.methodology === "string" && args.methodology.length > 0 ? { methodology: args.methodology } : {},
-      ...typeof args.informationAsymmetry === "string" && args.informationAsymmetry.length > 0 ? { informationAsymmetry: args.informationAsymmetry } : {},
-      ...typeof args.sourceDescription === "string" && args.sourceDescription.trim().length > 0 ? { sourceDescription: args.sourceDescription.trim() } : {},
-      createdAt: now,
-      updatedAt: now,
-      createdBy: args.userId,
-      metadata: {
+    const nodeId = await insertEpistemicNode(
+      ctx,
+      buildEvidenceNodeInsert({
+        globalId,
+        impact,
         kind,
-        tags: args.tags || [],
-        externalSourceType: args.externalSourceType,
-        sourceUrl: args.sourceUrl,
-        sourceQuestionId: args.sourceQuestionId,
-        rationale: args.rationale,
         linkedBeliefNodeId: args.linkedBeliefNodeId,
-        evidenceRelation,
-        confidence: Math.abs(weight),
-        weight,
-        impactScore: weight,
-        ...additionalMetadata
-      }
-    });
+        metadataProfile: "internalCreate",
+        now,
+        scope,
+        sourceType,
+        write: args
+      })
+    );
     await ctx.db.insert("epistemicAudit", {
       entityType: "evidence",
       entityId: String(nodeId),
@@ -1552,9 +1720,9 @@ var internalCreate = internalMutation({
         externalSourceType: args.externalSourceType,
         sourceUrl: args.sourceUrl,
         linkedBeliefNodeId: args.linkedBeliefNodeId,
-        evidenceRelation,
-        confidence: Math.abs(weight),
-        weight
+        evidenceRelation: impact.evidenceRelation,
+        confidence: impact.confidence,
+        weight: impact.weight
       },
       triggeringAction: "epistemicEvidence.internalCreate"
     });
@@ -1566,28 +1734,28 @@ var internalCreate = internalMutation({
       evidenceGlobalId: globalId,
       beliefNodeId: args.linkedBeliefNodeId,
       beliefGlobalId: linkedBeliefNode.globalId,
-      relation: evidenceRelation,
-      weight,
+      relation: impact.evidenceRelation,
+      weight: impact.weight,
       userId: args.userId,
       topicId: scope.topicId ? String(scope.topicId) : void 0,
       projectId: scope.projectId ? String(scope.projectId) : void 0,
       rationale: args.rationale
     });
     if (scope.projectId || scope.topicId) {
-      await ctx.scheduler.runAfter(
-        0,
-        "embeddingActions:generateEpistemicNodeEmbedding",
-        {
-          nodeId,
-          projectId: scope.projectId,
-          topicId: scope.topicId ? String(scope.topicId) : void 0,
-          createdBy: args.userId,
-          nodeType: "evidence",
-          text: args.text
-        }
-      );
+      await ctx.scheduler.runAfter(0, EMBEDDING_GENERATION_ACTION, {
+        nodeId,
+        projectId: scope.projectId,
+        topicId: scope.topicId ? String(scope.topicId) : void 0,
+        createdBy: args.userId,
+        nodeType: "evidence",
+        text: args.text
+      });
     }
-    await markProjectGraphDirty(ctx, scope.projectId, String(scope.topicId));
+    await markProjectGraphDirty(
+      ctx,
+      scope.projectId,
+      scope.topicId ? String(scope.topicId) : void 0
+    );
     return { nodeId };
   }
 });
@@ -1600,11 +1768,11 @@ var updateVerificationStatus = mutation({
   },
   returns: permissiveReturn,
   handler: async (ctx, args) => {
-    const node = await ctx.db.get(args.nodeId);
-    if (!node || node.nodeType !== "evidence") {
-      throw new Error("Evidence node not found");
-    }
-    const metadata = node.metadata || {};
+    const node = assertEvidenceNode(
+      await ctx.db.get(args.nodeId),
+      "Evidence node not found"
+    );
+    const metadata = metadataRecord(node.metadata);
     await ctx.db.patch(args.nodeId, {
       metadata: {
         ...metadata,
@@ -1630,20 +1798,17 @@ var update = mutation({
   },
   returns: permissiveReturn,
   handler: async (ctx, args) => {
-    const resolvedId = args.nodeId ?? args.insightId;
-    if (!resolvedId) {
-      throw new Error("Either nodeId or insightId is required");
-    }
-    const node = await ctx.db.get(resolvedId);
-    if (!node || node.nodeType !== "evidence") {
-      throw new Error("Evidence node not found");
-    }
+    const resolvedId = await resolveEvidenceNodeId(ctx, args);
+    const node = assertEvidenceNode(
+      await ctx.db.get(resolvedId),
+      "Evidence node not found"
+    );
     if (!node.projectId) {
       throw new Error("Evidence has no project scope");
     }
     await requireScopeWriteAccess(ctx, node.projectId, args.userId);
     const now = Date.now();
-    const existingMeta = node.metadata || {};
+    const existingMeta = metadataRecord(node.metadata);
     const metaUpdates = { ...existingMeta };
     if (args.kind !== void 0) {
       metaUpdates.kind = args.kind;
@@ -1675,17 +1840,13 @@ var update = mutation({
       newState: { text: (args.text ?? node.canonicalText)?.slice(0, 200) }
     });
     if (args.text !== void 0) {
-      await ctx.scheduler.runAfter(
-        0,
-        "embeddingActions:generateEpistemicNodeEmbedding",
-        {
-          nodeId: resolvedId,
-          topicId: node.projectId,
-          createdBy: node.createdBy,
-          nodeType: "evidence",
-          text: args.text
-        }
-      );
+      await ctx.scheduler.runAfter(0, EMBEDDING_GENERATION_ACTION, {
+        nodeId: resolvedId,
+        topicId: node.projectId,
+        createdBy: node.createdBy ?? args.userId,
+        nodeType: "evidence",
+        text: args.text
+      });
     }
     await markProjectGraphDirty(ctx, node.projectId, node.topicId);
     return { nodeId: resolvedId };
@@ -1701,15 +1862,15 @@ var flagAsIncorrect = mutation({
   returns: permissiveReturn,
   handler: async (ctx, args) => {
     const now = Date.now();
-    const node = await ctx.db.get(args.insightId);
-    if (!node || node.nodeType !== "evidence") {
-      throw new Error("Evidence not found in epistemic spine");
-    }
+    const node = assertEvidenceNode(
+      await ctx.db.get(args.insightId),
+      "Evidence not found in epistemic spine"
+    );
     if (!node.projectId) {
       throw new Error("Evidence has no project scope");
     }
     await requireScopeWriteAccess(ctx, node.projectId, args.userId);
-    const existingMeta = node.metadata || {};
+    const existingMeta = metadataRecord(node.metadata);
     await ctx.db.patch(node._id, {
       verificationStatus: "contradicted",
       metadata: {
@@ -1765,14 +1926,11 @@ var remove = mutation({
   },
   returns: permissiveReturn,
   handler: async (ctx, args) => {
-    const resolvedId = args.nodeId ?? args.insightId;
-    if (!resolvedId) {
-      throw new Error("Either nodeId or insightId is required");
-    }
-    const node = await ctx.db.get(resolvedId);
-    if (!node || node.nodeType !== "evidence") {
-      throw new Error("Evidence node not found");
-    }
+    const resolvedId = await resolveEvidenceNodeId(ctx, args);
+    const node = assertEvidenceNode(
+      await ctx.db.get(resolvedId),
+      "Evidence node not found"
+    );
     if (node.createdBy !== args.userId) {
       throw new Error("Only the creator can archive this evidence");
     }
@@ -1800,6 +1958,224 @@ var remove = mutation({
     return { nodeId: resolvedId };
   }
 });
+function readOptionalString2(value) {
+  return typeof value === "string" && value.trim().length > 0 ? value : void 0;
+}
+function readOptionalNumber(value) {
+  return typeof value === "number" && Number.isFinite(value) ? value : void 0;
+}
+function readConvexId2(value) {
+  const normalized = readOptionalString2(value);
+  return normalized;
+}
+function readRecord(value) {
+  return value && typeof value === "object" && !Array.isArray(value) ? value : null;
+}
+function readOptionalStringArray(value) {
+  return Array.isArray(value) && value.every((item) => typeof item === "string") ? value : void 0;
+}
+function readEvidenceNodeRow(value, fallbackProjectId) {
+  const record = readRecord(value);
+  if (!record) {
+    return null;
+  }
+  const id = readConvexId2(record._id);
+  const canonicalText = readOptionalString2(record.canonicalText);
+  const createdAt = readOptionalNumber(record.createdAt);
+  const createdBy = readOptionalString2(record.createdBy);
+  const nodeType = readOptionalString2(record.nodeType);
+  const sourceType = readOptionalString2(record.sourceType);
+  const status = readOptionalString2(record.status);
+  const updatedAt = readOptionalNumber(record.updatedAt);
+  if (!(id && canonicalText && createdAt !== void 0 && createdBy && nodeType === "evidence" && sourceType && status && updatedAt !== void 0)) {
+    return null;
+  }
+  const metadata = readRecord(record.metadata) ?? void 0;
+  const node = {
+    ...record,
+    _id: id,
+    canonicalText,
+    createdAt,
+    createdBy,
+    nodeType: "evidence",
+    sourceType,
+    status,
+    updatedAt
+  };
+  const projectId = readOptionalString2(record.projectId) ?? readOptionalString2(fallbackProjectId);
+  if (projectId !== void 0) {
+    node.projectId = projectId;
+  }
+  const topicId = readOptionalString2(record.topicId);
+  if (topicId !== void 0) {
+    node.topicId = topicId;
+  }
+  const tenantId = readOptionalString2(record.tenantId);
+  if (tenantId !== void 0) {
+    node.tenantId = tenantId;
+  }
+  const workspaceId = readOptionalString2(record.workspaceId);
+  if (workspaceId !== void 0) {
+    node.workspaceId = workspaceId;
+  }
+  const globalId = readOptionalString2(record.globalId);
+  if (globalId !== void 0) {
+    node.globalId = globalId;
+  }
+  const title = readOptionalString2(record.title);
+  if (title !== void 0) {
+    node.title = title;
+  }
+  const audienceLabel = readOptionalString2(record.audienceLabel);
+  if (audienceLabel !== void 0) {
+    node.audienceLabel = audienceLabel;
+  }
+  const epistemicLayer = readOptionalString2(record.epistemicLayer);
+  if (epistemicLayer !== void 0) {
+    node.epistemicLayer = epistemicLayer;
+  }
+  const sensitivityTier = readOptionalString2(record.sensitivityTier);
+  if (sensitivityTier !== void 0) {
+    node.sensitivityTier = sensitivityTier;
+  }
+  const exportClass = readOptionalString2(record.exportClass);
+  if (exportClass !== void 0) {
+    node.exportClass = exportClass;
+  }
+  const policyTags = readOptionalStringArray(record.policyTags);
+  if (policyTags !== void 0) {
+    node.policyTags = policyTags;
+  }
+  if (metadata !== void 0) {
+    node.metadata = metadata;
+  }
+  return node;
+}
+function readEvidenceNodeRows(values, fallbackProjectId) {
+  return values.flatMap((value) => {
+    const node = readEvidenceNodeRow(value, fallbackProjectId);
+    return node ? [node] : [];
+  });
+}
+function dedupeEvidenceNodeRows(nodes) {
+  const seen = /* @__PURE__ */ new Set();
+  const deduped = [];
+  for (const node of nodes) {
+    const id = String(node._id);
+    if (seen.has(id)) {
+      continue;
+    }
+    seen.add(id);
+    deduped.push(node);
+  }
+  return deduped;
+}
+function readEvidenceEdgeRow(value) {
+  const record = readRecord(value);
+  if (!record) {
+    return null;
+  }
+  const id = readConvexId2(record._id);
+  const edgeType = readOptionalString2(record.edgeType);
+  if (!(id && edgeType)) {
+    return null;
+  }
+  const edge = { _id: id, edgeType };
+  const weight = readOptionalNumber(record.weight);
+  if (weight !== void 0) {
+    edge.weight = weight;
+  }
+  for (const field of [
+    "fromNodeId",
+    "toNodeId",
+    "sourceGlobalId",
+    "targetGlobalId",
+    "fromGlobalId",
+    "toGlobalId",
+    "fromLayer",
+    "toLayer",
+    "topicId"
+  ]) {
+    const valueForField = readOptionalString2(record[field]);
+    if (valueForField !== void 0) {
+      edge[field] = valueForField;
+    }
+  }
+  return edge;
+}
+function readEvidenceEdgeRows(values) {
+  return values.flatMap((value) => {
+    const edge = readEvidenceEdgeRow(value);
+    return edge ? [edge] : [];
+  });
+}
+function dedupeEvidenceEdges(edges) {
+  const seen = /* @__PURE__ */ new Set();
+  const deduped = [];
+  for (const edge of edges) {
+    const id = String(edge._id);
+    if (seen.has(id)) {
+      continue;
+    }
+    seen.add(id);
+    deduped.push(edge);
+  }
+  return deduped;
+}
+function evidenceSourceRef(edge) {
+  return edge.sourceGlobalId ?? edge.fromGlobalId ?? edge.fromNodeId;
+}
+async function resolveEvidenceNodeSoft(ctx, nodeRef) {
+  const normalizedId = ctx.db.normalizeId?.("epistemicNodes", nodeRef) ?? readConvexId2(nodeRef);
+  if (normalizedId) {
+    try {
+      const direct = readEvidenceNodeRow(await ctx.db.get(normalizedId));
+      if (direct) {
+        return direct;
+      }
+    } catch (error) {
+      debugGraphPrimitiveFallback(
+        "[epistemicEvidence] Direct evidence lookup failed",
+        { error, nodeRef }
+      );
+    }
+  }
+  return readEvidenceNodeRow(
+    await ctx.db.query("epistemicNodes").withIndex("by_globalId", (q) => q.eq("globalId", nodeRef)).first()
+  );
+}
+async function collectNodeReferenceIds(ctx, nodeId) {
+  const refs = /* @__PURE__ */ new Set([String(nodeId)]);
+  const node = await ctx.db.get(nodeId);
+  const globalId = readOptionalString2(readRecord(node)?.globalId);
+  if (globalId) {
+    refs.add(globalId);
+  }
+  return [...refs];
+}
+async function collectInformsEdgesToNode(ctx, nodeId) {
+  const refs = await collectNodeReferenceIds(ctx, nodeId);
+  const reads = [];
+  for (const ref of refs) {
+    reads.push(
+      ctx.db.query("epistemicEdges").withIndex(
+        "by_to_type",
+        (q) => q.eq("toNodeId", ref).eq("edgeType", "informs")
+      ).collect(),
+      ctx.db.query("epistemicEdges").withIndex(
+        "by_target_global_id",
+        (q) => q.eq("targetGlobalId", ref)
+      ).collect()
+    );
+  }
+  const edges = readEvidenceEdgeRows((await Promise.all(reads)).flat()).filter(
+    (edge) => edge.edgeType === "informs"
+  );
+  return dedupeEvidenceEdges(edges);
+}
+function hasProjectId(node) {
+  return typeof node.projectId === "string" && node.projectId.length > 0;
+}
 var getById = query({
   args: {
     nodeId: v.optional(v.id("epistemicNodes")),
@@ -1812,11 +2188,7 @@ var getById = query({
     if (!id) {
       return null;
     }
-    const node = await ctx.db.get(id);
-    if (!node || node.nodeType !== "evidence") {
-      return null;
-    }
-    return node;
+    return await resolveEvidenceNodeSoft(ctx, String(id));
   }
 });
 var getByProject = query({
@@ -1828,7 +2200,7 @@ var getByProject = query({
   },
   returns: permissiveReturn,
   handler: async (ctx, args) => {
-    if (!args.projectId && !args.topicId) {
+    if (!(args.projectId || args.topicId)) {
       return [];
     }
     const pageSize = clampEvidenceLimit(args.limit);
@@ -1864,9 +2236,9 @@ var getByProject = query({
       "by_topic_type",
       (q) => q.eq("topicId", scope.topicId).eq("nodeType", "evidence")
     ).order("desc").take(scanLimit);
-    const scopedNodes = dedupeEvidenceNodes(topicNodes).filter(
-      (node) => evidenceMatchesScope(node, scope)
-    );
+    const scopedNodes = dedupeEvidenceNodeRows(
+      readEvidenceNodeRows(topicNodes, scope.projectId)
+    ).filter((node) => evidenceMatchesScope(node, scope));
     const filteredNodes = args.status ? scopedNodes.filter((node) => node.status === args.status) : scopedNodes;
     return filteredNodes.map(flattenEvidenceNode).slice(0, pageSize);
   }
@@ -1889,9 +2261,9 @@ var getByTopic = query({
       "by_topic_type",
       (q) => q.eq("topicId", scope.topicId).eq("nodeType", "evidence")
     ).order("desc").take(scanLimit);
-    const scopedNodes = dedupeEvidenceNodes(topicNodes).filter(
-      (node) => evidenceMatchesScope(node, scope)
-    );
+    const scopedNodes = dedupeEvidenceNodeRows(
+      readEvidenceNodeRows(topicNodes, scope.projectId)
+    ).filter((node) => evidenceMatchesScope(node, scope));
     const filteredNodes = args.status ? scopedNodes.filter((node) => node.status === args.status) : scopedNodes;
     return filteredNodes.map(flattenEvidenceNode).slice(0, pageSize);
   }
@@ -1902,20 +2274,29 @@ var getForBelief = query({
   },
   returns: permissiveReturn,
   handler: async (ctx, args) => {
-    const edges = await ctx.db.query("epistemicEdges").withIndex(
-      "by_to_type",
-      (q) => q.eq("toNodeId", args.beliefNodeId).eq("edgeType", "informs")
-    ).collect();
-    const evidenceNodeIds = edges.map((e) => e.fromNodeId);
+    const edges = await collectInformsEdgesToNode(ctx, args.beliefNodeId);
+    const evidenceNodeIds = edges.flatMap((edge) => {
+      const sourceRef = evidenceSourceRef(edge);
+      return sourceRef ? [sourceRef] : [];
+    });
     const evidenceNodes = await Promise.all(
-      evidenceNodeIds.map((id) => ctx.db.get(id))
+      evidenceNodeIds.map((id) => resolveEvidenceNodeSoft(ctx, id))
     );
-    return evidenceNodes.filter((e) => e !== null && e.nodeType === "evidence").map((e, i) => ({
-      ...e,
-      relation: (edges[i]?.weight ?? 0) >= 0 ? "supports" : "contradicts",
-      confidence: Math.abs(edges[i]?.weight ?? 0),
-      edgeId: edges[i]?._id
-    }));
+    return evidenceNodes.flatMap((e, i) => {
+      const edge = edges[i];
+      if (!(e && edge)) {
+        return [];
+      }
+      const weight = edge.weight ?? 0;
+      return [
+        {
+          ...e,
+          relation: weight >= 0 ? "supports" : "contradicts",
+          confidence: Math.abs(weight),
+          edgeId: edge._id
+        }
+      ];
+    });
   }
 });
 var internalGetByProject = internalQuery({
@@ -1934,21 +2315,30 @@ var internalGetByProject = internalQuery({
       return [];
     }
     const audienceMode = args.audienceMode ?? "internal";
+    const projectScopeId = scope.topicId ? String(scope.topicId) : scope.projectId;
+    if (!projectScopeId) {
+      return [];
+    }
     const project = await resolveGraphPrimitivesAppResolvers().getProject(
       ctx,
-      scope.topicId ? String(scope.topicId) : scope.projectId
+      projectScopeId
     );
+    const tenantId = project?.tenantId;
+    const workspaceId = project?.workspaceId;
     const registryRows = await listAudienceRegistryRows(ctx, {
-      tenantId: project?.tenantId,
-      workspaceId: project?.workspaceId
+      tenantId,
+      workspaceId
     });
     const resolveAudienceClass = createEvidenceAudienceResolver(registryRows);
     const viewerClass = resolveAudienceClass(audienceMode, "public");
-    const nodes = await getEvidenceNodesForScope(ctx, scope, { scanLimit });
+    const nodes = readEvidenceNodeRows(
+      await getEvidenceNodesForScope(ctx, scope, { scanLimit }),
+      scope.projectId
+    );
     const workspaceScopedNodes = nodes.filter(
       (node) => nodeMatchesWorkspaceReasoningScope(node, {
-        tenantId: project?.tenantId,
-        workspaceId: project?.workspaceId
+        tenantId,
+        workspaceId
       })
     );
     return workspaceScopedNodes.filter(
@@ -2007,7 +2397,10 @@ var internalGetByTopic = internalQuery({
       "by_topic_type",
       (q) => q.eq("topicId", args.topicId).eq("nodeType", "evidence")
     ).order("desc").take(scanLimit);
-    const workspaceScopedNodes = nodes.filter(
+    const workspaceScopedNodes = readEvidenceNodeRows(
+      nodes,
+      scope.projectId
+    ).filter(
       (node) => nodeMatchesWorkspaceReasoningScope(node, {
         tenantId: scope.tenantId,
         workspaceId: scope.workspaceId
@@ -2058,13 +2451,16 @@ var getByProjectSystem = query({
     if (!scope) {
       return [];
     }
-    const nodes = await getEvidenceNodesForScope(ctx, scope, { scanLimit });
+    const nodes = readEvidenceNodeRows(
+      await getEvidenceNodesForScope(ctx, scope, { scanLimit }),
+      scope.projectId
+    );
     const filtered = args.kind ? nodes.filter((n) => {
       const meta = n.metadata || {};
       return meta.kind === args.kind;
     }) : nodes;
     filtered.sort((a, b) => b.createdAt - a.createdAt);
-    return filtered.slice(0, pageSize).map((n) => formatEvidenceNode(n));
+    return filtered.filter(hasProjectId).slice(0, pageSize).map((n) => formatEvidenceNode(n));
   }
 });
 var getEvidenceBalance = query({
@@ -2078,16 +2474,21 @@ var getEvidenceBalance = query({
       topicId: args.topicId,
       projectId: args.projectId
     });
-    const hasAccess = await checkScopeAccess(
-      ctx,
-      scope.topicId ? String(scope.topicId) : scope.projectId,
-      args.userId
-    );
+    const scopeId = scope.topicId ? String(scope.topicId) : scope.projectId;
+    if (!scopeId) {
+      return { supporting: 0, challenging: 0, total: 0 };
+    }
+    const hasAccess = await checkScopeAccess(ctx, scopeId, args.userId);
     if (!hasAccess) {
       return { supporting: 0, challenging: 0, total: 0 };
     }
     const resolvedTopicId = scope.topicId || scope.projectId;
-    const edges = resolvedTopicId ? await ctx.db.query("epistemicEdges").withIndex("by_topic", (q) => q.eq("topicId", resolvedTopicId)).collect() : [];
+    const edges = resolvedTopicId ? readEvidenceEdgeRows(
+      await ctx.db.query("epistemicEdges").withIndex(
+        "by_topic",
+        (q) => q.eq("topicId", resolvedTopicId)
+      ).collect()
+    ) : [];
     const evidenceEdges = edges.filter(
       (e) => e.edgeType === "informs" && e.fromLayer === "L2" && e.toLayer === "L3"
     );