@lucern/graph-primitives 1.0.29 → 1.0.31

package/dist/epistemicAnswers.js

@@ -1,17 +1,25 @@
-import { v } from 'convex/values';
-import { componentsGeneric, anyApi, mutationGeneric, internalMutationGeneric, queryGeneric } from 'convex/server';
 import { checkScopeAccess } from '@lucern/access-control/access';
-import { generateGlobalId, assertUuidV7Identity } from '@lucern/contracts/ids';
 import { permissiveReturn } from '@lucern/contracts/schema-helpers/validators';
+import { v } from 'convex/values';
+import { unsafeConvexAnyApi } from '@lucern/contracts/convex/unsafeAnyApi';
+import { componentsGeneric, mutationGeneric, internalMutationGeneric, queryGeneric } from 'convex/server';
 import '@lucern/contracts';
+import { generateGlobalId, assertUuidV7Identity } from '@lucern/contracts/ids';
 
 // src/epistemicAnswers.ts
-var api = anyApi;
+var unsafeApi = unsafeConvexAnyApi(
+  "graph-primitives top-level module bundle lacks a committed Convex _generated/api surface"
+);
+var api = unsafeApi;
 componentsGeneric();
-var internal = anyApi;
+var internal = unsafeApi;
 var internalMutation = internalMutationGeneric;
 var mutation = mutationGeneric;
 var query = queryGeneric;
+function insertEpistemicNode(ctx, doc) {
+  assertUuidV7Identity("epistemicNodes", doc.globalId);
+  return ctx.db.insert("epistemicNodes", doc);
+}
 
 // src/debug.ts
 function isGraphPrimitiveDebugEnabled() {
@@ -24,8 +32,6 @@ function debugGraphPrimitiveFallback(message, context) {
   }
   console.debug(message, context ?? {});
 }
-
-// src/topicScope.ts
 var LEGACY_SCOPE_FIELD = "graphScopeProjectId";
 async function resolveTopicNodeScopeOrNull(ctx, ref) {
   if (!ctx?.db || typeof ctx.db.query !== "function") {
@@ -60,13 +66,15 @@ function asMappedProjectId(topic) {
   if (!topic) {
     return;
   }
-  const directLegacyProjectId = normalizeScopeValue(topic[LEGACY_SCOPE_FIELD]);
+  const directLegacyProjectId = normalizeScopeValue(
+    topic[LEGACY_SCOPE_FIELD]
+  );
   if (directLegacyProjectId) {
     return directLegacyProjectId;
   }
   const metadata = topic.metadata || {};
   const candidate = metadata[LEGACY_SCOPE_FIELD] || metadata.legacyProjectId || metadata.projectId || metadata.scopeProjectId;
-  return candidate ? candidate : void 0;
+  return typeof candidate === "string" ? normalizeScopeValue(candidate) : void 0;
 }
 function normalizeScopeValue(value) {
   if (typeof value !== "string") {
@@ -91,8 +99,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_FIELD, scopeId)
     ).collect();
@@ -104,7 +113,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);
@@ -160,137 +169,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())
@@ -308,7 +295,7 @@ function normalizeScopeValue2(value) {
 async function resolveScope(ctx, args) {
   const topicId = normalizeScopeValue2(args.topicId);
   const projectId = normalizeScopeValue2(args.projectId);
-  if (!topicId && !projectId) {
+  if (!(topicId || projectId)) {
     return null;
   }
   try {
@@ -328,12 +315,84 @@ async function resolveScope(ctx, args) {
     return null;
   }
 }
-async function insertEpistemicNode(ctx, doc) {
-  assertUuidV7Identity("epistemicNodes", doc.globalId);
-  return ctx.db.insert("epistemicNodes", doc);
-}
 
 // src/epistemicAnswers.ts
+function isRecord(value) {
+  return Boolean(value) && typeof value === "object" && !Array.isArray(value);
+}
+function readConvexId(value) {
+  return typeof value === "string" && value.trim().length > 0 ? value : void 0;
+}
+function readOptionalNumber(value) {
+  return typeof value === "number" && Number.isFinite(value) ? value : void 0;
+}
+function readOptionalString(value) {
+  return typeof value === "string" && value.trim().length > 0 ? value : void 0;
+}
+function readRecord(value) {
+  return isRecord(value) ? value : void 0;
+}
+function readAnswerNodeRow(value) {
+  if (!isRecord(value)) {
+    return null;
+  }
+  const id = readConvexId(value._id);
+  const globalId = readOptionalString(value.globalId);
+  if (!(id && globalId)) {
+    return null;
+  }
+  const row = { _id: id, globalId };
+  const canonicalText = readOptionalString(value.canonicalText);
+  const createdAt = readOptionalNumber(value.createdAt);
+  const createdBy = readOptionalString(value.createdBy);
+  const metadata = readRecord(value.metadata);
+  const nodeType = readOptionalString(value.nodeType);
+  const projectId = readOptionalString(value.projectId);
+  const status = readOptionalString(value.status);
+  const supersededBy = readConvexId(value.supersededBy);
+  const topicId = readConvexId(value.topicId);
+  if (canonicalText !== void 0) {
+    row.canonicalText = canonicalText;
+  }
+  if (createdAt !== void 0) {
+    row.createdAt = createdAt;
+  }
+  if (createdBy !== void 0) {
+    row.createdBy = createdBy;
+  }
+  if (metadata !== void 0) {
+    row.metadata = metadata;
+  }
+  if (nodeType !== void 0) {
+    row.nodeType = nodeType;
+  }
+  if (projectId !== void 0) {
+    row.projectId = projectId;
+  }
+  if (status !== void 0) {
+    row.status = status;
+  }
+  if (supersededBy !== void 0) {
+    row.supersededBy = supersededBy;
+  }
+  if (topicId !== void 0) {
+    row.topicId = topicId;
+  }
+  return row;
+}
+function readAnswerEdgeRow(value) {
+  if (!isRecord(value)) {
+    return null;
+  }
+  const fromNodeId = readConvexId(value.fromNodeId);
+  return fromNodeId ? { fromNodeId } : null;
+}
+function readRowList(values, reader) {
+  return values.flatMap((value) => {
+    const row = reader(value);
+    return row ? [row] : [];
+  });
+}
 function generateContentHash(text) {
   const content = `answer:${text.trim().toLowerCase().replace(/\s+/g, " ").slice(0, 500)}`;
   let hash = 5381;
@@ -343,6 +402,283 @@ function generateContentHash(text) {
   }
   return Math.abs(hash).toString(16).padStart(8, "0");
 }
+async function getActiveAnswersForQuestion(ctx, questionNode, topicId, questionNodeId) {
+  const answers = readRowList(
+    await ctx.db.query("epistemicNodes").withIndex(
+      "by_topic_type",
+      (q) => q.eq("topicId", questionNode.topicId ?? topicId).eq("nodeType", "answer")
+    ).collect(),
+    readAnswerNodeRow
+  );
+  return answers.filter((answerNode) => {
+    const answerMeta = answerNode.metadata ?? {};
+    return answerMeta.questionNodeId === questionNodeId && answerMeta.isLatest === true && answerNode.status === "active";
+  });
+}
+function getNextAnswerVersion(activeAnswers) {
+  if (activeAnswers.length === 0) {
+    return 1;
+  }
+  return Math.max(
+    ...activeAnswers.map((answerNode) => {
+      const answerMeta = answerNode.metadata ?? {};
+      return readOptionalNumber(answerMeta.versionNumber) ?? 0;
+    })
+  ) + 1;
+}
+async function supersedeActiveAnswers(ctx, activeAnswers, now, clearSupersededByBeforeInsert) {
+  for (const activeAnswer of activeAnswers) {
+    const metadata = {
+      ...activeAnswer.metadata ?? {},
+      isLatest: false
+    };
+    await ctx.db.patch(activeAnswer._id, {
+      status: "superseded",
+      updatedAt: now,
+      metadata,
+      ...clearSupersededByBeforeInsert ? {
+        supersededBy: void 0
+      } : {}
+    });
+  }
+}
+async function collectEvidenceGlobalIds(ctx, evidenceNodeIds) {
+  const evidenceGlobalIds = [];
+  if (!evidenceNodeIds) {
+    return evidenceGlobalIds;
+  }
+  for (const evidenceNodeId of evidenceNodeIds) {
+    const evidenceNode = readAnswerNodeRow(await ctx.db.get(evidenceNodeId));
+    if (evidenceNode) {
+      evidenceGlobalIds.push(evidenceNode.globalId);
+    }
+  }
+  return evidenceGlobalIds;
+}
+function resolveAnswerSource(answerSource) {
+  return answerSource === "human" ? "human" : "ai_generated";
+}
+function insertAnswerNodeRecord(ctx, args) {
+  return insertEpistemicNode(ctx, {
+    globalId: args.globalId,
+    projectId: args.topicId,
+    topicId: args.questionNode.topicId,
+    nodeType: "answer",
+    epistemicLayer: "L2",
+    canonicalText: args.answerText,
+    contentHash: args.contentHash,
+    status: "active",
+    sourceType: resolveAnswerSource(args.args.answerSource),
+    createdBy: args.args.userId,
+    createdAt: args.now,
+    updatedAt: args.now,
+    metadata: {
+      questionGlobalId: args.questionNode.globalId,
+      questionNodeId: String(args.questionNode._id),
+      versionNumber: args.versionNumber,
+      isLatest: true,
+      evidenceGlobalIds: args.evidenceGlobalIds,
+      evidenceCount: args.evidenceGlobalIds.length,
+      answeredBy: args.args.userId,
+      answerSource: args.args.answerSource || "human",
+      sprintId: args.args.sprintId,
+      ...args.args.backfilledFromQuestionId ? {
+        backfilledFromQuestionId: args.args.backfilledFromQuestionId
+      } : {}
+    }
+  });
+}
+async function setAnswerSupersession(ctx, activeAnswers, newNodeId) {
+  for (const activeAnswer of activeAnswers) {
+    await ctx.db.patch(activeAnswer._id, {
+      supersededBy: newNodeId
+    });
+  }
+}
+async function scheduleAnswerSyncJobs(ctx, args) {
+  await ctx.scheduler.runAfter(0, internal.neo4jSync.syncNodeToNeo4j, {
+    nodeId: args.nodeId,
+    operation: "upsert"
+  });
+  await ctx.scheduler.runAfter(
+    0,
+    api.embeddingActions.generateEpistemicNodeEmbedding,
+    {
+      nodeId: args.nodeId,
+      projectId: args.topicId,
+      topicId: args.questionNode.topicId ? String(args.questionNode.topicId) : void 0,
+      createdBy: args.userId,
+      nodeType: "answer",
+      text: args.answerText.slice(0, 2e4)
+    }
+  );
+  await ctx.scheduler.runAfter(
+    0,
+    internal.sprints.embedProjectThemeCollectiveInternal,
+    {
+      projectId: args.topicId,
+      userId: args.userId
+    }
+  );
+}
+async function scheduleAnswerGraphEdges(ctx, args) {
+  await ctx.scheduler.runAfter(0, internal.neo4jEdgeAPI.createEdge, {
+    globalId: generateGlobalId(),
+    fromGlobalId: args.answerGlobalId,
+    toGlobalId: args.questionNode.globalId,
+    edgeType: "responds_to",
+    weight: 1,
+    createdBy: args.userId,
+    topicId: args.edgeTopicId,
+    fromNodeType: "answer",
+    toNodeType: "question",
+    fromLayer: "L2",
+    toLayer: "L3"
+  });
+  for (const activeAnswer of args.activeAnswers) {
+    await ctx.scheduler.runAfter(0, internal.neo4jEdgeAPI.createEdge, {
+      globalId: generateGlobalId(),
+      fromGlobalId: args.answerGlobalId,
+      toGlobalId: activeAnswer.globalId,
+      edgeType: "supersedes",
+      createdBy: args.userId,
+      topicId: args.edgeTopicId,
+      fromNodeType: "answer",
+      toNodeType: "answer",
+      fromLayer: "L2",
+      toLayer: "L2"
+    });
+  }
+  if (args.evidenceNodeIds) {
+    for (const evidenceNodeId of args.evidenceNodeIds) {
+      const evidenceNode = readAnswerNodeRow(await ctx.db.get(evidenceNodeId));
+      if (evidenceNode) {
+        await ctx.scheduler.runAfter(0, internal.neo4jEdgeAPI.createEdge, {
+          globalId: generateGlobalId(),
+          fromGlobalId: args.answerGlobalId,
+          toGlobalId: evidenceNode.globalId,
+          edgeType: "derived_from",
+          createdBy: args.userId,
+          topicId: args.edgeTopicId,
+          fromNodeType: "answer",
+          toNodeType: "evidence",
+          fromLayer: "L2",
+          toLayer: "L2"
+        });
+      }
+    }
+  }
+  const evidenceEdges = readRowList(
+    await ctx.db.query("epistemicEdges").withIndex(
+      "by_to_type",
+      (q) => q.eq("toNodeId", args.questionNodeId).eq("edgeType", "derived_from")
+    ).collect(),
+    readAnswerEdgeRow
+  );
+  for (const evidenceEdge of evidenceEdges) {
+    const evidenceNode = readAnswerNodeRow(
+      await ctx.db.get(evidenceEdge.fromNodeId)
+    );
+    if (!evidenceNode) {
+      continue;
+    }
+    await ctx.scheduler.runAfter(0, internal.neo4jEdgeAPI.createEdge, {
+      globalId: generateGlobalId(),
+      fromGlobalId: evidenceNode.globalId,
+      toGlobalId: args.answerGlobalId,
+      edgeType: "derived_from",
+      createdBy: args.userId,
+      topicId: args.edgeTopicId,
+      fromNodeType: "evidence",
+      toNodeType: "answer",
+      fromLayer: "L2",
+      toLayer: "L2"
+    });
+  }
+}
+async function createAnswerMutationResult(ctx, args) {
+  const now = Date.now();
+  const answerText = args.answerText;
+  const globalId = generateGlobalId();
+  const contentHash = generateContentHash(answerText);
+  const activeAnswers = await getActiveAnswersForQuestion(
+    ctx,
+    args.questionNode,
+    args.topicId,
+    args.questionNodeId
+  );
+  const versionNumber = getNextAnswerVersion(activeAnswers);
+  await supersedeActiveAnswers(
+    ctx,
+    activeAnswers,
+    now,
+    !!args.clearSupersededByBeforeInsert
+  );
+  const evidenceGlobalIds = await collectEvidenceGlobalIds(
+    ctx,
+    args.evidenceNodeIds
+  );
+  const nodeId = await insertAnswerNodeRecord(ctx, {
+    questionNode: args.questionNode,
+    topicId: args.topicId,
+    answerText,
+    contentHash,
+    versionNumber,
+    evidenceGlobalIds,
+    globalId,
+    now,
+    args: {
+      answerSource: args.answerSource,
+      sprintId: args.sprintId,
+      userId: args.userId,
+      backfilledFromQuestionId: args.backfilledFromQuestionId
+    }
+  });
+  await setAnswerSupersession(ctx, activeAnswers, nodeId);
+  await scheduleAnswerSyncJobs(ctx, {
+    nodeId,
+    topicId: args.topicId,
+    questionNode: args.questionNode,
+    userId: args.userId,
+    answerText
+  });
+  await scheduleAnswerGraphEdges(ctx, {
+    questionNode: args.questionNode,
+    questionNodeId: args.questionNodeId,
+    userId: args.userId,
+    evidenceNodeIds: args.evidenceNodeIds,
+    activeAnswers,
+    answerGlobalId: globalId,
+    edgeTopicId: args.edgeTopicId
+  });
+  const answerQuality = args.confidence || "moderate";
+  await ctx.db.patch(args.questionNodeId, {
+    answerQuality,
+    updatedAt: now
+  });
+  const auditState = args.backfilledFromQuestionId ? {
+    answerText: answerText.slice(0, 200),
+    versionNumber,
+    questionNodeId: String(args.questionNodeId),
+    backfilled: true
+  } : {
+    answerText: answerText.slice(0, 200),
+    versionNumber,
+    questionNodeId: String(args.questionNodeId),
+    confidence: answerQuality
+  };
+  await ctx.db.insert("epistemicAudit", {
+    entityType: "answer",
+    entityId: nodeId,
+    changeType: "created",
+    changedAt: now,
+    changedBy: args.userId,
+    isAgent: false,
+    projectId: args.topicId,
+    newState: auditState
+  });
+  return { nodeId, globalId, versionNumber };
+}
 var create = mutation({
   args: {
     ...scopeArgs,
@@ -367,190 +703,25 @@ var create = mutation({
     const scope = await resolveScope(ctx, args);
     const topicId = scope?.topicId ? String(scope.topicId) : args.topicId || "";
     await checkScopeAccess(ctx, topicId, args.userId);
-    const questionNode = await ctx.db.get(args.questionNodeId);
-    if (!questionNode || questionNode.nodeType !== "question") {
-      throw new Error("Question node not found or not a question type");
-    }
-    const now = Date.now();
-    const globalId = generateGlobalId();
-    const contentHash = generateContentHash(args.answerText);
-    const existingAnswers = await ctx.db.query("epistemicNodes").withIndex(
-      "by_topic_type",
-      (q) => q.eq("topicId", questionNode.topicId ?? topicId).eq("nodeType", "answer")
-    ).collect();
-    const activeAnswersForQuestion = existingAnswers.filter((n) => {
-      const meta = n.metadata || {};
-      return meta.questionNodeId === args.questionNodeId && meta.isLatest === true && n.status === "active";
-    });
-    const versionNumber = activeAnswersForQuestion.length > 0 ? Math.max(
-      ...activeAnswersForQuestion.map((a) => {
-        const meta = a.metadata || {};
-        return meta.versionNumber || 0;
-      })
-    ) + 1 : 1;
-    for (const oldAnswer of activeAnswersForQuestion) {
-      await ctx.db.patch(oldAnswer._id, {
-        status: "superseded",
-        supersededBy: void 0,
-        // Will be set after insert
-        updatedAt: now,
-        metadata: {
-          ...oldAnswer.metadata || {},
-          isLatest: false
-        }
-      });
-    }
-    const evidenceGlobalIds = [];
-    if (args.evidenceNodeIds) {
-      for (const evId of args.evidenceNodeIds) {
-        const evNode = await ctx.db.get(evId);
-        if (evNode) {
-          evidenceGlobalIds.push(evNode.globalId);
-        }
-      }
-    }
-    const nodeId = await insertEpistemicNode(ctx, {
-      globalId,
-      projectId: topicId,
-      topicId: questionNode.topicId,
-      nodeType: "answer",
-      epistemicLayer: "L2",
-      canonicalText: args.answerText,
-      contentHash,
-      status: "active",
-      sourceType: args.answerSource === "human" ? "human" : "ai_generated",
-      createdBy: args.userId,
-      createdAt: now,
-      updatedAt: now,
-      metadata: {
-        questionGlobalId: questionNode.globalId,
-        questionNodeId: String(args.questionNodeId),
-        versionNumber,
-        isLatest: true,
-        evidenceGlobalIds,
-        evidenceCount: evidenceGlobalIds.length,
-        answeredBy: args.userId,
-        answerSource: args.answerSource || "human",
-        sprintId: args.sprintId
-      }
-    });
-    for (const oldAnswer of activeAnswersForQuestion) {
-      await ctx.db.patch(oldAnswer._id, {
-        supersededBy: nodeId
-      });
-    }
-    await ctx.scheduler.runAfter(0, internal.neo4jSync.syncNodeToNeo4j, {
-      nodeId,
-      operation: "upsert"
-    });
-    await ctx.scheduler.runAfter(
-      0,
-      api.embeddingActions.generateEpistemicNodeEmbedding,
-      {
-        nodeId,
-        projectId: topicId,
-        topicId: questionNode.topicId ? String(questionNode.topicId) : void 0,
-        createdBy: args.userId,
-        nodeType: "answer",
-        text: args.answerText.slice(0, 2e4)
-      }
-    );
-    await ctx.scheduler.runAfter(
-      0,
-      internal.sprints.embedProjectThemeCollectiveInternal,
-      {
-        projectId: topicId,
-        userId: args.userId
-      }
+    const questionNode = readAnswerNodeRow(
+      await ctx.db.get(args.questionNodeId)
     );
-    await ctx.scheduler.runAfter(0, internal.neo4jEdgeAPI.createEdge, {
-      globalId: generateGlobalId(),
-      fromGlobalId: globalId,
-      toGlobalId: questionNode.globalId,
-      edgeType: "responds_to",
-      weight: 1,
-      createdBy: args.userId,
-      topicId: String(args.topicId ?? ""),
-      fromNodeType: "answer",
-      toNodeType: "question",
-      fromLayer: "L2",
-      toLayer: "L3"
-    });
-    for (const oldAnswer of activeAnswersForQuestion) {
-      await ctx.scheduler.runAfter(0, internal.neo4jEdgeAPI.createEdge, {
-        globalId: generateGlobalId(),
-        fromGlobalId: globalId,
-        toGlobalId: oldAnswer.globalId,
-        edgeType: "supersedes",
-        createdBy: args.userId,
-        topicId: String(args.topicId ?? ""),
-        fromNodeType: "answer",
-        toNodeType: "answer",
-        fromLayer: "L2",
-        toLayer: "L2"
-      });
-    }
-    if (args.evidenceNodeIds) {
-      for (const evId of args.evidenceNodeIds) {
-        const evNode = await ctx.db.get(evId);
-        if (evNode) {
-          await ctx.scheduler.runAfter(0, internal.neo4jEdgeAPI.createEdge, {
-            globalId: generateGlobalId(),
-            fromGlobalId: globalId,
-            toGlobalId: evNode.globalId,
-            edgeType: "derived_from",
-            createdBy: args.userId,
-            topicId: String(args.topicId ?? ""),
-            fromNodeType: "answer",
-            toNodeType: "evidence",
-            fromLayer: "L2",
-            toLayer: "L2"
-          });
-        }
-      }
-    }
-    const evidenceEdges = await ctx.db.query("epistemicEdges").withIndex(
-      "by_to_type",
-      (q) => q.eq("toNodeId", args.questionNodeId).eq("edgeType", "derived_from")
-    ).collect();
-    for (const edge of evidenceEdges) {
-      const evidenceNode = await ctx.db.get(edge.fromNodeId);
-      if (evidenceNode) {
-        await ctx.scheduler.runAfter(0, internal.neo4jEdgeAPI.createEdge, {
-          globalId: generateGlobalId(),
-          fromGlobalId: evidenceNode.globalId,
-          toGlobalId: globalId,
-          edgeType: "derived_from",
-          createdBy: args.userId,
-          topicId: String(args.topicId ?? ""),
-          fromNodeType: "evidence",
-          toNodeType: "answer",
-          fromLayer: "L2",
-          toLayer: "L2"
-        });
-      }
+    if (questionNode?.nodeType !== "question") {
+      throw new Error("Question node not found or not a question type");
     }
-    const answerQuality = args.confidence || "moderate";
-    await ctx.db.patch(args.questionNodeId, {
-      answerQuality,
-      updatedAt: now
-    });
-    await ctx.db.insert("epistemicAudit", {
-      entityType: "answer",
-      entityId: nodeId,
-      changeType: "created",
-      changedAt: now,
-      changedBy: args.userId,
-      isAgent: false,
-      projectId: topicId,
-      newState: {
-        answerText: args.answerText.slice(0, 200),
-        versionNumber,
-        questionNodeId: String(args.questionNodeId),
-        confidence: answerQuality
-      }
+    return createAnswerMutationResult(ctx, {
+      questionNode,
+      questionNodeId: args.questionNodeId,
+      answerText: args.answerText,
+      confidence: args.confidence,
+      evidenceNodeIds: args.evidenceNodeIds,
+      answerSource: args.answerSource,
+      sprintId: args.sprintId,
+      userId: args.userId,
+      topicId,
+      edgeTopicId: String(args.topicId ?? ""),
+      clearSupersededByBeforeInsert: true
     });
-    return { nodeId, globalId, versionNumber };
   }
 });
 var createInternal = internalMutation({
@@ -569,189 +740,25 @@ var createInternal = internalMutation({
   handler: async (ctx, args) => {
     const scope = await resolveScope(ctx, args);
     const topicId = scope?.topicId ? String(scope.topicId) : args.topicId || "";
-    const questionNode = await ctx.db.get(args.questionNodeId);
-    if (!questionNode || questionNode.nodeType !== "question") {
-      throw new Error("Question node not found or not a question type");
-    }
-    const now = Date.now();
-    const globalId = generateGlobalId();
-    const contentHash = generateContentHash(args.answerText);
-    const existingAnswers = await ctx.db.query("epistemicNodes").withIndex(
-      "by_topic_type",
-      (q) => q.eq("topicId", questionNode.topicId ?? topicId).eq("nodeType", "answer")
-    ).collect();
-    const activeAnswersForQuestion = existingAnswers.filter((n) => {
-      const meta = n.metadata || {};
-      return meta.questionNodeId === String(args.questionNodeId) && meta.isLatest === true && n.status === "active";
-    });
-    const versionNumber = activeAnswersForQuestion.length > 0 ? Math.max(
-      ...activeAnswersForQuestion.map((a) => {
-        const meta = a.metadata || {};
-        return meta.versionNumber || 0;
-      })
-    ) + 1 : 1;
-    for (const oldAnswer of activeAnswersForQuestion) {
-      await ctx.db.patch(oldAnswer._id, {
-        status: "superseded",
-        updatedAt: now,
-        metadata: {
-          ...oldAnswer.metadata || {},
-          isLatest: false
-        }
-      });
-    }
-    const evidenceGlobalIds = [];
-    if (args.evidenceNodeIds) {
-      for (const evId of args.evidenceNodeIds) {
-        const evNode = await ctx.db.get(evId);
-        if (evNode) {
-          evidenceGlobalIds.push(evNode.globalId);
-        }
-      }
-    }
-    const nodeId = await insertEpistemicNode(ctx, {
-      globalId,
-      projectId: topicId,
-      topicId: questionNode.topicId,
-      nodeType: "answer",
-      epistemicLayer: "L2",
-      canonicalText: args.answerText,
-      contentHash,
-      status: "active",
-      sourceType: args.answerSource === "human" ? "human" : "ai_generated",
-      createdBy: args.userId,
-      createdAt: now,
-      updatedAt: now,
-      metadata: {
-        questionGlobalId: questionNode.globalId,
-        questionNodeId: String(args.questionNodeId),
-        versionNumber,
-        isLatest: true,
-        evidenceGlobalIds,
-        evidenceCount: evidenceGlobalIds.length,
-        answeredBy: args.userId,
-        answerSource: args.answerSource || "human",
-        sprintId: args.sprintId,
-        backfilledFromQuestionId: args.backfilledFromQuestionId
-      }
-    });
-    for (const oldAnswer of activeAnswersForQuestion) {
-      await ctx.db.patch(oldAnswer._id, {
-        supersededBy: nodeId
-      });
-    }
-    await ctx.scheduler.runAfter(0, internal.neo4jSync.syncNodeToNeo4j, {
-      nodeId,
-      operation: "upsert"
-    });
-    await ctx.scheduler.runAfter(
-      0,
-      api.embeddingActions.generateEpistemicNodeEmbedding,
-      {
-        nodeId,
-        projectId: topicId,
-        topicId: questionNode.topicId ? String(questionNode.topicId) : void 0,
-        createdBy: args.userId,
-        nodeType: "answer",
-        text: args.answerText.slice(0, 2e4)
-      }
-    );
-    await ctx.scheduler.runAfter(
-      0,
-      internal.sprints.embedProjectThemeCollectiveInternal,
-      {
-        projectId: topicId,
-        userId: args.userId
-      }
+    const questionNode = readAnswerNodeRow(
+      await ctx.db.get(args.questionNodeId)
     );
-    await ctx.scheduler.runAfter(0, internal.neo4jEdgeAPI.createEdge, {
-      globalId: generateGlobalId(),
-      fromGlobalId: globalId,
-      toGlobalId: questionNode.globalId,
-      edgeType: "responds_to",
-      weight: 1,
-      createdBy: args.userId,
-      topicId: String(args.topicId ?? ""),
-      fromNodeType: "answer",
-      toNodeType: "question",
-      fromLayer: "L2",
-      toLayer: "L3"
-    });
-    for (const oldAnswer of activeAnswersForQuestion) {
-      await ctx.scheduler.runAfter(0, internal.neo4jEdgeAPI.createEdge, {
-        globalId: generateGlobalId(),
-        fromGlobalId: globalId,
-        toGlobalId: oldAnswer.globalId,
-        edgeType: "supersedes",
-        createdBy: args.userId,
-        topicId: String(args.topicId ?? ""),
-        fromNodeType: "answer",
-        toNodeType: "answer",
-        fromLayer: "L2",
-        toLayer: "L2"
-      });
-    }
-    if (args.evidenceNodeIds) {
-      for (const evId of args.evidenceNodeIds) {
-        const evNode = await ctx.db.get(evId);
-        if (evNode) {
-          await ctx.scheduler.runAfter(0, internal.neo4jEdgeAPI.createEdge, {
-            globalId: generateGlobalId(),
-            fromGlobalId: globalId,
-            toGlobalId: evNode.globalId,
-            edgeType: "derived_from",
-            createdBy: args.userId,
-            topicId: String(args.topicId ?? ""),
-            fromNodeType: "answer",
-            toNodeType: "evidence",
-            fromLayer: "L2",
-            toLayer: "L2"
-          });
-        }
-      }
-    }
-    const evidenceEdges = await ctx.db.query("epistemicEdges").withIndex(
-      "by_to_type",
-      (q) => q.eq("toNodeId", args.questionNodeId).eq("edgeType", "derived_from")
-    ).collect();
-    for (const edge of evidenceEdges) {
-      const evidenceNode = await ctx.db.get(edge.fromNodeId);
-      if (evidenceNode) {
-        await ctx.scheduler.runAfter(0, internal.neo4jEdgeAPI.createEdge, {
-          globalId: generateGlobalId(),
-          fromGlobalId: evidenceNode.globalId,
-          toGlobalId: globalId,
-          edgeType: "derived_from",
-          createdBy: args.userId,
-          topicId: String(args.topicId ?? ""),
-          fromNodeType: "evidence",
-          toNodeType: "answer",
-          fromLayer: "L2",
-          toLayer: "L2"
-        });
-      }
+    if (questionNode?.nodeType !== "question") {
+      throw new Error("Question node not found or not a question type");
     }
-    const answerQuality = args.confidence || "moderate";
-    await ctx.db.patch(args.questionNodeId, {
-      answerQuality,
-      updatedAt: now
-    });
-    await ctx.db.insert("epistemicAudit", {
-      entityType: "answer",
-      entityId: nodeId,
-      changeType: "created",
-      changedAt: now,
-      changedBy: args.userId,
-      isAgent: false,
-      projectId: topicId,
-      newState: {
-        answerText: args.answerText.slice(0, 200),
-        versionNumber,
-        questionNodeId: String(args.questionNodeId),
-        backfilled: !!args.backfilledFromQuestionId
-      }
+    return createAnswerMutationResult(ctx, {
+      questionNode,
+      questionNodeId: args.questionNodeId,
+      answerText: args.answerText,
+      confidence: args.confidence,
+      evidenceNodeIds: args.evidenceNodeIds,
+      answerSource: args.answerSource,
+      sprintId: args.sprintId,
+      userId: args.userId,
+      topicId,
+      edgeTopicId: String(args.topicId ?? ""),
+      backfilledFromQuestionId: args.backfilledFromQuestionId
     });
-    return { nodeId, globalId, versionNumber };
   }
 });
 var getByQuestion = query({
@@ -761,30 +768,35 @@ var getByQuestion = query({
   },
   returns: permissiveReturn,
   handler: async (ctx, args) => {
-    const questionNode = await ctx.db.get(args.questionNodeId);
-    if (!questionNode || questionNode.nodeType !== "question") {
+    const questionNode = readAnswerNodeRow(
+      await ctx.db.get(args.questionNodeId)
+    );
+    if (questionNode?.nodeType !== "question") {
       return [];
     }
     const topicId = questionNode.topicId;
     if (!topicId) {
       return [];
     }
-    const answers = await ctx.db.query("epistemicNodes").withIndex(
-      "by_topic_type",
-      (q) => q.eq("topicId", topicId).eq("nodeType", "answer")
-    ).collect();
+    const answers = readRowList(
+      await ctx.db.query("epistemicNodes").withIndex(
+        "by_topic_type",
+        (q) => q.eq("topicId", topicId).eq("nodeType", "answer")
+      ).collect(),
+      readAnswerNodeRow
+    );
     const questionIdStr = String(args.questionNodeId);
     const filtered = answers.filter((a) => {
-      const meta = a.metadata || {};
+      const meta = a.metadata ?? {};
       return meta.questionNodeId === questionIdStr;
     });
     if (!args.includeSuperseded) {
       return filtered.filter((a) => a.status === "active");
     }
     filtered.sort((a, b) => {
-      const metaA = a.metadata || {};
-      const metaB = b.metadata || {};
-      return (metaB.versionNumber || 0) - (metaA.versionNumber || 0);
+      const metaA = a.metadata ?? {};
+      const metaB = b.metadata ?? {};
+      return (readOptionalNumber(metaB.versionNumber) ?? 0) - (readOptionalNumber(metaA.versionNumber) ?? 0);
     });
     return filtered;
   }
@@ -795,20 +807,26 @@ var getLatestForQuestion = query({
   },
   returns: permissiveReturn,
   handler: async (ctx, args) => {
-    const questionNode = await ctx.db.get(args.questionNodeId);
-    if (!questionNode || questionNode.nodeType !== "question") {
+    const questionNode = readAnswerNodeRow(
+      await ctx.db.get(args.questionNodeId)
+    );
+    if (questionNode?.nodeType !== "question") {
       return null;
     }
-    if (!questionNode.topicId) {
+    const topicId = questionNode.topicId;
+    if (!topicId) {
       return null;
     }
-    const answers = await ctx.db.query("epistemicNodes").withIndex(
-      "by_topic_type",
-      (q) => q.eq("topicId", questionNode.topicId).eq("nodeType", "answer")
-    ).filter((q) => q.eq(q.field("status"), "active")).collect();
+    const answers = readRowList(
+      await ctx.db.query("epistemicNodes").withIndex(
+        "by_topic_type",
+        (q) => q.eq("topicId", topicId).eq("nodeType", "answer")
+      ).filter((q) => q.eq(q.field("status"), "active")).collect(),
+      readAnswerNodeRow
+    );
     const questionIdStr = String(args.questionNodeId);
     const latest = answers.find((a) => {
-      const meta = a.metadata || {};
+      const meta = a.metadata ?? {};
       return meta.questionNodeId === questionIdStr && meta.isLatest === true;
     });
     return latest || null;
@@ -820,38 +838,44 @@ var getVersionHistory = query({
   },
   returns: permissiveReturn,
   handler: async (ctx, args) => {
-    const questionNode = await ctx.db.get(args.questionNodeId);
-    if (!questionNode || questionNode.nodeType !== "question") {
+    const questionNode = readAnswerNodeRow(
+      await ctx.db.get(args.questionNodeId)
+    );
+    if (questionNode?.nodeType !== "question") {
       return [];
     }
-    if (!questionNode.topicId) {
+    const topicId = questionNode.topicId;
+    if (!topicId) {
       return [];
     }
-    const answers = await ctx.db.query("epistemicNodes").withIndex(
-      "by_topic_type",
-      (q) => q.eq("topicId", questionNode.topicId).eq("nodeType", "answer")
-    ).filter(
-      (q) => q.or(
-        q.eq(q.field("status"), "active"),
-        q.eq(q.field("status"), "superseded")
-      )
-    ).collect();
+    const answers = readRowList(
+      await ctx.db.query("epistemicNodes").withIndex(
+        "by_topic_type",
+        (q) => q.eq("topicId", topicId).eq("nodeType", "answer")
+      ).filter(
+        (q) => q.or(
+          q.eq(q.field("status"), "active"),
+          q.eq(q.field("status"), "superseded")
+        )
+      ).collect(),
+      readAnswerNodeRow
+    );
     const questionIdStr = String(args.questionNodeId);
     const history = answers.filter((a) => {
-      const meta = a.metadata || {};
+      const meta = a.metadata ?? {};
       return meta.questionNodeId === questionIdStr;
     }).map((a) => {
-      const meta = a.metadata || {};
+      const meta = a.metadata ?? {};
       return {
         _id: a._id,
         globalId: a.globalId,
         answerText: a.canonicalText,
-        versionNumber: meta.versionNumber || 1,
-        isLatest: meta.isLatest || false,
+        versionNumber: readOptionalNumber(meta.versionNumber) ?? 1,
+        isLatest: meta.isLatest === true,
         status: a.status,
-        answeredBy: meta.answeredBy || a.createdBy,
-        answerSource: meta.answerSource,
-        evidenceCount: meta.evidenceCount || 0,
+        answeredBy: readOptionalString(meta.answeredBy) ?? a.createdBy,
+        answerSource: readOptionalString(meta.answerSource),
+        evidenceCount: readOptionalNumber(meta.evidenceCount) ?? 0,
         createdAt: a.createdAt,
         supersededBy: a.supersededBy
       };
@@ -868,25 +892,39 @@ var backfillAnswerNodes = internalMutation({
   returns: permissiveReturn,
   handler: async (ctx, args) => {
     const scope = await resolveScope(ctx, args);
-    const topicId = scope?.topicId ?? args.topicId;
+    const topicId = scope?.topicId ? String(scope.topicId) : args.topicId;
     const dryRun = args.dryRun ?? false;
-    const questions = await ctx.db.query("epistemicNodes").withIndex(
-      "by_topic_type",
-      (q) => q.eq("topicId", topicId).eq("nodeType", "question")
-    ).collect();
+    if (!topicId) {
+      return {
+        questionsWithAnswers: 0,
+        alreadyHaveNodes: 0,
+        needsBackfill: 0,
+        backfilled: 0
+      };
+    }
+    const questions = readRowList(
+      await ctx.db.query("epistemicNodes").withIndex(
+        "by_topic_type",
+        (q) => q.eq("topicId", topicId).eq("nodeType", "question")
+      ).collect(),
+      readAnswerNodeRow
+    );
     const questionsWithAnswers = questions.filter((q) => {
-      const meta = q.metadata || {};
-      const answer = meta.answer;
+      const meta = q.metadata ?? {};
+      const answer = readOptionalString(meta.answer);
       return answer && answer.trim().length > 0;
     });
-    const existingAnswers = await ctx.db.query("epistemicNodes").withIndex(
-      "by_topic_type",
-      (q) => q.eq("topicId", topicId).eq("nodeType", "answer")
-    ).collect();
+    const existingAnswers = readRowList(
+      await ctx.db.query("epistemicNodes").withIndex(
+        "by_topic_type",
+        (q) => q.eq("topicId", topicId).eq("nodeType", "answer")
+      ).collect(),
+      readAnswerNodeRow
+    );
     const questionIdsWithAnswerNodes = new Set(
       existingAnswers.map((a) => {
-        const meta = a.metadata || {};
-        return meta.questionNodeId;
+        const meta = a.metadata ?? {};
+        return readOptionalString(meta.questionNodeId);
       })
     );
     const needsBackfill = questionsWithAnswers.filter(
@@ -904,14 +942,18 @@ var backfillAnswerNodes = internalMutation({
           id: q._id,
           globalId: q.globalId,
           text: q.canonicalText?.slice(0, 80),
-          answer: q.metadata?.answer?.slice(0, 80)
+          answer: readOptionalString(q.metadata?.answer)?.slice(0, 80)
         }))
       };
     }
     let created = 0;
     for (const question of needsBackfill) {
-      const meta = question.metadata || {};
-      const answerText = meta.answer;
+      const meta = question.metadata ?? {};
+      const answerText = readOptionalString(meta.answer);
+      if (!answerText) {
+        continue;
+      }
+      const answeredBy = readOptionalString(meta.answeredBy);
       await ctx.scheduler.runAfter(
         0,
         internal.epistemicAnswers.createInternal,
@@ -920,8 +962,8 @@ var backfillAnswerNodes = internalMutation({
           // TC-C: migrated from projectId
           questionNodeId: question._id,
           answerText,
-          answerSource: meta.answeredBy ? "human" : "ai_generated",
-          userId: meta.answeredBy || args.userId,
+          answerSource: answeredBy ? "human" : "ai_generated",
+          userId: answeredBy ?? args.userId,
           backfilledFromQuestionId: String(question._id)
         }
       );