@lucern/graph-primitives 1.0.29 → 1.0.31

package/dist/questionEvidenceLinks.js

@@ -1,12 +1,16 @@
-import { v } from 'convex/values';
 import { checkProjectAccess } from '@lucern/access-control/access';
 import { permissiveReturn } from '@lucern/contracts/schema-helpers/validators';
-import { componentsGeneric, mutationGeneric, anyApi, queryGeneric } from 'convex/server';
+import { v } from 'convex/values';
+import { unsafeConvexAnyApi } from '@lucern/contracts/convex/unsafeAnyApi';
+import { componentsGeneric, mutationGeneric, queryGeneric } from 'convex/server';
 
 // src/questionEvidenceLinks.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 mutation = mutationGeneric;
 var query = queryGeneric;
 
@@ -72,6 +76,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;
@@ -152,9 +160,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;
     }
@@ -174,8 +185,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,
@@ -244,90 +265,113 @@ async function patchTopicProjectOverlay(ctx, scopeId, value) {
   if (!topic) {
     return null;
   }
-  const nextMetadata = { ...readMetadata(topic) };
-  const patch = {};
-  const topicUpdateArgs = {
-    id: String(topic._id)
+  const plan = buildTopicProjectOverlayPatchPlan(topic, value);
+  await applyTopicProjectOverlayPatch(ctx, topic, plan);
+  return materializeTopicProjectOverlay({
+    ...topic,
+    ...plan.patch,
+    metadata: plan.nextMetadata
+  });
+}
+function buildTopicProjectOverlayPatchPlan(topic, value) {
+  const plan = {
+    nextMetadata: { ...readMetadata(topic) },
+    patch: {},
+    topicUpdateArgs: {
+      id: String(topic._id)
+    }
   };
   for (const [key, rawValue] of Object.entries(value)) {
-    switch (key) {
-      case "_id":
-      case "projectId":
-      case "topicId":
-      case "legacyProjectId":
-      case "storageProjectId":
-        break;
-      case "name":
-      case "description":
-        patch[key] = rawValue;
-        topicUpdateArgs[key] = rawValue;
-        break;
-      case "tenantId":
-      case "workspaceId":
-      case "ownerId":
-        throw new Error(
-          `patchTopicProjectOverlay cannot mutate ${key} via component-owned topics`
-        );
-      case "status": {
-        const status = coerceStatus(rawValue);
-        if (status) {
-          patch.status = status;
-          topicUpdateArgs.status = status;
-        }
-        break;
-      }
-      case "visibility": {
-        const visibility = coerceVisibility(rawValue);
-        if (visibility) {
-          patch.visibility = visibility;
-          topicUpdateArgs.visibility = visibility;
-        }
-        break;
-      }
-      case "type": {
-        const projectType = readNonEmptyString(rawValue);
-        if (projectType) {
-          nextMetadata.projectType = projectType;
-        } else {
-          delete nextMetadata.projectType;
-        }
-        break;
-      }
-      case "updatedAt":
-      case "createdAt":
-        break;
-      default:
-        if (rawValue === void 0) {
-          delete nextMetadata[key];
-        } else {
-          nextMetadata[key] = rawValue;
-        }
-    }
+    applyTopicProjectOverlayPatchEntry(plan, key, rawValue);
+  }
+  plan.patch.updatedAt = Date.now();
+  plan.patch.metadata = plan.nextMetadata;
+  plan.topicUpdateArgs.metadata = plan.nextMetadata;
+  return plan;
+}
+function applyTopicProjectOverlayPatchEntry(plan, key, rawValue) {
+  switch (key) {
+    case "_id":
+    case "projectId":
+    case "topicId":
+    case "legacyProjectId":
+    case "storageProjectId":
+    case "updatedAt":
+    case "createdAt":
+      return;
+    case "name":
+    case "description":
+      plan.patch[key] = rawValue;
+      plan.topicUpdateArgs[key] = rawValue;
+      return;
+    case "tenantId":
+    case "workspaceId":
+    case "ownerId":
+      throw new Error(
+        `patchTopicProjectOverlay cannot mutate ${key} via component-owned topics`
+      );
+    case "status":
+      applyTopicStatusPatch(plan, rawValue);
+      return;
+    case "visibility":
+      applyTopicVisibilityPatch(plan, rawValue);
+      return;
+    case "type":
+      applyTopicProjectTypePatch(plan, rawValue);
+      return;
+    default:
+      applyTopicMetadataPatch(plan, key, rawValue);
   }
-  patch.updatedAt = Date.now();
-  patch.metadata = nextMetadata;
-  topicUpdateArgs.metadata = nextMetadata;
+}
+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
@@ -355,7 +399,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(
@@ -422,13 +466,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") {
@@ -453,8 +499,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();
@@ -466,7 +513,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);
@@ -522,137 +569,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())
@@ -684,6 +709,251 @@ var matcherMetadataValidator = v.object({
   signalSnapshot: v.optional(v.any()),
   outcomeMetadata: v.optional(v.any())
 });
+function isRecord(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function readConvexId(value) {
+  return typeof value === "string" && value.length > 0 ? value : null;
+}
+function readOptionalNumber(value) {
+  return typeof value === "number" && Number.isFinite(value) ? value : void 0;
+}
+function readRequiredNumber(value, fieldName) {
+  const numberValue = readOptionalNumber(value);
+  if (numberValue === void 0) {
+    throw new Error(`questionEvidenceLinks row has invalid ${fieldName}.`);
+  }
+  return numberValue;
+}
+function readOptionalString(value) {
+  return typeof value === "string" ? value : void 0;
+}
+function readStringArray2(value) {
+  return Array.isArray(value) ? value.filter((item) => typeof item === "string") : [];
+}
+function readLinkSuggestionStatus(value) {
+  if (value === void 0) {
+    return;
+  }
+  if (value === "suggested" || value === "approved" || value === "dismissed") {
+    return value;
+  }
+  throw new Error("questionEvidenceLinks row has invalid status.");
+}
+function readEvidenceImpact(value) {
+  if (value === void 0) {
+    return;
+  }
+  if (value === "supports" || value === "contradicts" || value === "neutral") {
+    return value;
+  }
+  throw new Error("questionEvidenceLinks row has invalid impact.");
+}
+function readMatcherReviewStatus(value) {
+  if (value === void 0) {
+    return;
+  }
+  if (value === "pending" || value === "accepted" || value === "rejected" || value === "auto_accepted" || value === "superseded") {
+    return value;
+  }
+  throw new Error("matcher metadata has invalid reviewStatus.");
+}
+function readMatcherMetadata(value) {
+  if (value === void 0) {
+    return;
+  }
+  if (!isRecord(value) || typeof value.surface !== "string") {
+    throw new Error("matcher metadata must include a string surface.");
+  }
+  return {
+    configSnapshot: value.configSnapshot,
+    matcherFamily: readOptionalString(value.matcherFamily),
+    matcherKey: readOptionalString(value.matcherKey),
+    matcherVersion: readOptionalString(value.matcherVersion),
+    outcomeMetadata: value.outcomeMetadata,
+    reviewStatus: readMatcherReviewStatus(value.reviewStatus),
+    signalSnapshot: value.signalSnapshot,
+    surface: value.surface
+  };
+}
+function readMetadata2(value) {
+  return isRecord(value) ? value : void 0;
+}
+function readEpistemicNode(value) {
+  if (!isRecord(value)) {
+    return null;
+  }
+  const id = readConvexId(value._id);
+  if (!id) {
+    return null;
+  }
+  return {
+    _creationTime: readOptionalNumber(value._creationTime),
+    _id: id,
+    canonicalText: readOptionalString(value.canonicalText),
+    createdAt: readOptionalNumber(value.createdAt),
+    globalId: readOptionalString(value.globalId),
+    metadata: readMetadata2(value.metadata),
+    nodeType: readOptionalString(value.nodeType),
+    projectId: readOptionalString(value.projectId),
+    status: readOptionalString(value.status),
+    title: readOptionalString(value.title),
+    topicId: readOptionalString(value.topicId),
+    verificationStatus: readOptionalString(value.verificationStatus)
+  };
+}
+function requireEpistemicNode(value, message) {
+  const node = readEpistemicNode(value);
+  if (!node) {
+    throw new Error(message);
+  }
+  return node;
+}
+function readQuestionEvidenceLink(value, context = "questionEvidenceLinks row") {
+  if (!isRecord(value)) {
+    throw new Error(`${context} must be an object.`);
+  }
+  const id = readConvexId(value._id);
+  const questionId = readConvexId(value.questionId);
+  const insightId = readConvexId(value.insightId);
+  const createdBy = readOptionalString(value.createdBy);
+  if (!(id && questionId && insightId && createdBy)) {
+    throw new Error(`${context} has invalid required identifiers.`);
+  }
+  if (typeof value.helpsAnswer !== "boolean") {
+    throw new Error(`${context} has invalid helpsAnswer.`);
+  }
+  return {
+    _id: id,
+    createdAt: readRequiredNumber(value.createdAt, "createdAt"),
+    createdBy,
+    helpsAnswer: value.helpsAnswer,
+    impact: readEvidenceImpact(value.impact),
+    impactScore: readOptionalNumber(value.impactScore),
+    insightId,
+    questionId,
+    rationale: readOptionalString(value.rationale),
+    relevance: readOptionalNumber(value.relevance),
+    status: readLinkSuggestionStatus(value.status)
+  };
+}
+function readQuestionEvidenceLinks(values) {
+  return values.map(
+    (value, index) => readQuestionEvidenceLink(value, `questionEvidenceLinks[${index}]`)
+  );
+}
+function readEpistemicEdge(value) {
+  if (!isRecord(value)) {
+    return null;
+  }
+  const id = readConvexId(value._id);
+  const createdAt = readOptionalNumber(value.createdAt);
+  if (!(id && createdAt !== void 0)) {
+    return null;
+  }
+  return {
+    _id: id,
+    context: readOptionalString(value.context),
+    createdAt,
+    createdBy: readOptionalString(value.createdBy),
+    fromGlobalId: readOptionalString(value.fromGlobalId),
+    fromNodeId: readConvexId(value.fromNodeId) ?? void 0,
+    globalId: readOptionalString(value.globalId),
+    weight: readOptionalNumber(value.weight)
+  };
+}
+async function fetchOperationalQuestionEvidenceLinks(ctx, questionId) {
+  const links = readQuestionEvidenceLinks(
+    await ctx.db.query("questionEvidenceLinks").withIndex("by_questionId", (q) => q.eq("questionId", questionId)).collect()
+  );
+  return await Promise.all(
+    links.filter((link) => isOperationalLinkStatus(link.status)).map(async (link) => {
+      const insight = readEpistemicNode(await ctx.db.get(link.insightId));
+      return {
+        ...link,
+        insight
+      };
+    })
+  );
+}
+function calculateEdgeImpact(edgeWeight) {
+  return edgeWeight == null ? 0 : Math.round(edgeWeight * 10);
+}
+async function buildEvidenceDetailFromEdge(ctx, edge, questionId, seenEvidenceIds) {
+  if (!edge.fromNodeId) {
+    return null;
+  }
+  const fromNodeId = String(edge.fromNodeId);
+  if (seenEvidenceIds.has(fromNodeId)) {
+    return null;
+  }
+  seenEvidenceIds.add(fromNodeId);
+  const evidenceNode = readEpistemicNode(await ctx.db.get(edge.fromNodeId));
+  if (evidenceNode?.nodeType !== "evidence" || evidenceNode.status !== "active") {
+    return null;
+  }
+  const meta = evidenceNode.metadata || {};
+  const impactScore = calculateEdgeImpact(edge.weight);
+  return {
+    _id: edge._id,
+    _creationTime: edge.createdAt,
+    questionId,
+    insightId: edge.fromNodeId,
+    impact: deriveImpact(impactScore, void 0),
+    impactScore,
+    rationale: edge.context ?? null,
+    userId: edge.createdBy,
+    createdAt: edge.createdAt,
+    insight: {
+      _id: evidenceNode._id,
+      _creationTime: evidenceNode.createdAt,
+      insight: evidenceNode.canonicalText || evidenceNode.title || readOptionalString(meta.snippet) || null,
+      text: evidenceNode.canonicalText || evidenceNode.title || readOptionalString(meta.snippet) || null,
+      title: evidenceNode.title ?? null,
+      canonicalText: evidenceNode.canonicalText ?? null,
+      source: readOptionalString(meta.sourceTitle) ?? null,
+      sourceUrl: readOptionalString(meta.sourceUrl) ?? null,
+      verificationStatus: evidenceNode.verificationStatus ?? "unverified"
+    }
+  };
+}
+async function fetchDerivedFromEdgesWithDetails(ctx, questionId, seenEvidenceIds) {
+  const edges = (await ctx.db.query("epistemicEdges").withIndex(
+    "by_to_type",
+    (q) => q.eq("toNodeId", questionId).eq("edgeType", "derived_from")
+  ).collect()).flatMap((edge) => {
+    const edgeRow = readEpistemicEdge(edge);
+    return edgeRow ? [edgeRow] : [];
+  });
+  const rows = [];
+  for (const edge of edges) {
+    const edgeRow = await buildEvidenceDetailFromEdge(
+      ctx,
+      edge,
+      questionId,
+      seenEvidenceIds
+    );
+    if (edgeRow) {
+      rows.push(edgeRow);
+    }
+  }
+  return rows;
+}
+function deriveImpact(impactScore, fallback) {
+  if (impactScore === void 0) {
+    return fallback;
+  }
+  if (impactScore > 0) {
+    return "supports";
+  }
+  if (impactScore < 0) {
+    return "contradicts";
+  }
+  return "neutral";
+}
+function readEpistemicMetadata(node) {
+  return node?.metadata ?? {};
+}
 async function markProjectGraphDirty(ctx, projectId) {
   if (!projectId) {
     return;
@@ -724,8 +994,8 @@ async function recordMatcherDecision(ctx, args) {
   });
 }
 async function applyOperationalLinkEffects(ctx, args) {
-  const meta = args.questionNode.metadata || {};
-  const currentRelated = meta.relatedInsightIds || [];
+  const meta = readEpistemicMetadata(args.questionNode);
+  const currentRelated = readStringArray2(meta.relatedInsightIds);
   if (!currentRelated.includes(args.insightId)) {
     await ctx.db.patch(args.questionId, {
       updatedAt: Date.now(),
@@ -736,8 +1006,8 @@ async function applyOperationalLinkEffects(ctx, args) {
     });
   }
   try {
-    const questionNode = await ctx.db.get(args.questionId);
-    const evidenceNode = await ctx.db.get(args.insightId);
+    const questionNode = readEpistemicNode(await ctx.db.get(args.questionId));
+    const evidenceNode = readEpistemicNode(await ctx.db.get(args.insightId));
     if (questionNode && questionNode.nodeType === "question" && evidenceNode && evidenceNode.nodeType === "evidence" && questionNode.globalId && evidenceNode.globalId) {
       const existingEdge = await ctx.db.query("epistemicEdges").withIndex(
         "by_from_to",
@@ -751,7 +1021,7 @@ async function applyOperationalLinkEffects(ctx, args) {
           toGlobalId: questionNode.globalId,
           edgeType: "derived_from",
           weight: args.relevance ?? 0.5,
-          context: args.rationale || "Linked from question evidence links",
+          context: args.rationale ?? "Linked from question evidence links",
           projectId: args.questionNode.projectId ? String(args.questionNode.projectId) : void 0,
           createdBy: args.createdBy,
           fromNodeType: "evidence",
@@ -765,47 +1035,42 @@ async function applyOperationalLinkEffects(ctx, args) {
     console.error("[EpistemicSpine] Failed to create derived_from edge:", e);
   }
   if (args.questionNode.projectId) {
-    await ctx.scheduler.runAfter(
-      0,
-      "verificationActions:deepVerifyEvidence",
-      {
-        insightId: args.insightId,
-        targetType: "question",
-        targetId: args.questionId,
-        projectId: args.questionNode.projectId,
-        userId: args.createdBy
-      }
-    );
+    await ctx.scheduler.runAfter(0, "verificationActions:deepVerifyEvidence", {
+      insightId: args.insightId,
+      targetType: "question",
+      targetId: args.questionId,
+      projectId: args.questionNode.projectId,
+      userId: args.createdBy
+    });
   }
 }
 async function removeOperationalLinkEffects(ctx, args) {
-  const question = await ctx.db.get(args.questionId);
+  const question = readEpistemicNode(await ctx.db.get(args.questionId));
   if (question) {
-    const meta = question.metadata || {};
-    const currentRelated = meta.relatedInsightIds || [];
+    const meta = readEpistemicMetadata(question);
+    const currentRelated = readStringArray2(meta.relatedInsightIds);
     await ctx.db.patch(args.questionId, {
       updatedAt: Date.now(),
       metadata: {
         ...meta,
-        relatedInsightIds: currentRelated.filter(
-          (id) => id !== args.insightId
-        )
+        relatedInsightIds: currentRelated.filter((id) => id !== args.insightId)
       }
     });
   }
   try {
-    const questionNode = await ctx.db.get(args.questionId);
-    const evidenceNode = await ctx.db.get(args.insightId);
+    const questionNode = readEpistemicNode(await ctx.db.get(args.questionId));
+    const evidenceNode = readEpistemicNode(await ctx.db.get(args.insightId));
     if (questionNode && questionNode.nodeType === "question" && evidenceNode && evidenceNode.nodeType === "evidence") {
       const edge = await ctx.db.query("epistemicEdges").withIndex(
         "by_from_to",
         (q) => q.eq("fromNodeId", evidenceNode._id).eq("toNodeId", questionNode._id)
       ).first();
-      if (edge) {
+      const edgeRow = readEpistemicEdge(edge);
+      if (edgeRow?.globalId) {
         await ctx.scheduler.runAfter(0, internal.neo4jEdgeAPI.deleteEdge, {
-          globalId: edge.globalId
+          globalId: edgeRow.globalId
         });
-        await ctx.db.delete(edge._id);
+        await ctx.db.delete(edgeRow._id);
       }
     }
   } catch (e) {
@@ -833,23 +1098,29 @@ var create = mutation({
   },
   returns: permissiveReturn,
   handler: async (ctx, args) => {
-    const question = await ctx.db.get(args.questionId);
-    if (!question) {
+    const matcherMetadata = readMatcherMetadata(args.matcherMetadata);
+    const question = requireEpistemicNode(
+      await ctx.db.get(args.questionId),
+      "Question not found"
+    );
+    if (question.nodeType !== "question") {
       throw new Error("Question not found");
     }
-    const insight = await ctx.db.get(args.insightId);
-    if (!insight) {
+    const insight = requireEpistemicNode(
+      await ctx.db.get(args.insightId),
+      "Insight not found"
+    );
+    if (insight.nodeType !== "evidence") {
       throw new Error("Insight not found");
     }
-    const existingLinks = await ctx.db.query("questionEvidenceLinks").withIndex(
-      "by_questionId",
-      (q) => q.eq("questionId", args.questionId)
-    ).collect();
+    const existingLinks = readQuestionEvidenceLinks(
+      await ctx.db.query("questionEvidenceLinks").withIndex("by_questionId", (q) => q.eq("questionId", args.questionId)).collect()
+    );
     const duplicate = existingLinks.find(
       (link) => link.insightId === args.insightId
     );
     const impactScore = args.impactScore;
-    const derivedImpact = impactScore !== void 0 ? impactScore > 0 ? "supports" : impactScore < 0 ? "contradicts" : "neutral" : args.impact;
+    const derivedImpact = deriveImpact(impactScore, args.impact);
     if (duplicate) {
       const nextStatus = mergeLinkSuggestionStatus(
         duplicate.status,
@@ -863,9 +1134,7 @@ var create = mutation({
         impact: derivedImpact,
         status: nextStatus
       });
-      if (isOperationalLinkStatus(nextStatus) && !isOperationalLinkStatus(
-        duplicate.status
-      )) {
+      if (isOperationalLinkStatus(nextStatus) && !isOperationalLinkStatus(duplicate.status)) {
         await applyOperationalLinkEffects(ctx, {
           questionNode: question,
           questionId: args.questionId,
@@ -881,7 +1150,7 @@ var create = mutation({
         insightId: args.insightId,
         linkId: duplicate._id,
         linkStatus: nextStatus,
-        matcherMetadata: args.matcherMetadata
+        matcherMetadata
       });
       await markProjectGraphDirty(ctx, question.projectId);
       return duplicate._id;
@@ -904,7 +1173,7 @@ var create = mutation({
       insightId: args.insightId,
       linkId,
       linkStatus: args.status,
-      matcherMetadata: args.matcherMetadata
+      matcherMetadata
     });
     if (isOperationalLinkStatus(args.status)) {
       await applyOperationalLinkEffects(ctx, {
@@ -935,12 +1204,13 @@ var updateImpact = mutation({
   },
   returns: permissiveReturn,
   handler: async (ctx, args) => {
-    const link = await ctx.db.get(args.linkId);
-    if (!link) {
+    const rawLink = await ctx.db.get(args.linkId);
+    if (!rawLink) {
       throw new Error("Link not found");
     }
+    const link = readQuestionEvidenceLink(rawLink, "updateImpact.link");
     const newImpactScore = args.impactScore;
-    const newImpact = newImpactScore !== void 0 ? newImpactScore > 0 ? "supports" : newImpactScore < 0 ? "contradicts" : "neutral" : args.impact;
+    const newImpact = deriveImpact(newImpactScore, args.impact);
     const updateData = {};
     if (newImpact) {
       updateData.impact = newImpact;
@@ -949,7 +1219,7 @@ var updateImpact = mutation({
       updateData.impactScore = newImpactScore;
     }
     await ctx.db.patch(args.linkId, updateData);
-    const question = await ctx.db.get(link.questionId);
+    const question = readEpistemicNode(await ctx.db.get(link.questionId));
     await markProjectGraphDirty(ctx, question?.projectId);
     return { success: true, newImpact, newImpactScore };
   }
@@ -963,11 +1233,12 @@ var reviewSuggestion = mutation({
   },
   returns: permissiveReturn,
   handler: async (ctx, args) => {
-    const link = await ctx.db.get(args.linkId);
-    if (!link) {
+    const rawLink = await ctx.db.get(args.linkId);
+    if (!rawLink) {
       throw new Error("Link not found");
     }
-    const question = await ctx.db.get(link.questionId);
+    const link = readQuestionEvidenceLink(rawLink, "reviewSuggestion.link");
+    const question = readEpistemicNode(await ctx.db.get(link.questionId));
     if (!question) {
       throw new Error("Question not found");
     }
@@ -1024,14 +1295,15 @@ var remove = mutation({
   },
   returns: permissiveReturn,
   handler: async (ctx, args) => {
-    const link = await ctx.db.get(args.linkId);
-    if (!link) {
+    const rawLink = await ctx.db.get(args.linkId);
+    if (!rawLink) {
       throw new Error("Link not found");
     }
+    const link = readQuestionEvidenceLink(rawLink, "remove.link");
     if (link.createdBy !== args.userId) {
       throw new Error("Only the creator can remove this link");
     }
-    const question = await ctx.db.get(link.questionId);
+    const question = readEpistemicNode(await ctx.db.get(link.questionId));
     if (isOperationalLinkStatus(link.status)) {
       await removeOperationalLinkEffects(ctx, {
         questionId: link.questionId,
@@ -1048,13 +1320,10 @@ var getByQuestion = query({
   },
   returns: permissiveReturn,
   handler: async (ctx, args) => {
-    const links = await ctx.db.query("questionEvidenceLinks").withIndex(
-      "by_questionId",
-      (q) => q.eq("questionId", args.questionId)
-    ).collect();
-    return links.filter(
-      (link) => isOperationalLinkStatus(link.status)
+    const links = readQuestionEvidenceLinks(
+      await ctx.db.query("questionEvidenceLinks").withIndex("by_questionId", (q) => q.eq("questionId", args.questionId)).collect()
     );
+    return links.filter((link) => isOperationalLinkStatus(link.status));
   }
 });
 var getPendingSuggestions = query({
@@ -1063,10 +1332,9 @@ var getPendingSuggestions = query({
   },
   returns: permissiveReturn,
   handler: async (ctx, args) => {
-    const links = await ctx.db.query("questionEvidenceLinks").withIndex(
-      "by_questionId",
-      (q) => q.eq("questionId", args.questionId)
-    ).collect();
+    const links = readQuestionEvidenceLinks(
+      await ctx.db.query("questionEvidenceLinks").withIndex("by_questionId", (q) => q.eq("questionId", args.questionId)).collect()
+    );
     return links.filter((link) => link.status === "suggested");
   }
 });
@@ -1076,13 +1344,10 @@ var getByInsight = query({
   },
   returns: permissiveReturn,
   handler: async (ctx, args) => {
-    const links = await ctx.db.query("questionEvidenceLinks").withIndex(
-      "by_insightId",
-      (q) => q.eq("insightId", args.insightId)
-    ).collect();
-    return links.filter(
-      (link) => isOperationalLinkStatus(link.status)
+    const links = readQuestionEvidenceLinks(
+      await ctx.db.query("questionEvidenceLinks").withIndex("by_insightId", (q) => q.eq("insightId", args.insightId)).collect()
     );
+    return links.filter((link) => isOperationalLinkStatus(link.status));
   }
 });
 var getEvidenceWithDetails = query({
@@ -1091,68 +1356,27 @@ var getEvidenceWithDetails = query({
   },
   returns: permissiveReturn,
   handler: async (ctx, args) => {
-    const questionNode = await ctx.db.get(args.questionId);
-    if (!questionNode || questionNode.nodeType !== "question") {
+    const questionNode = readEpistemicNode(await ctx.db.get(args.questionId));
+    if (questionNode?.nodeType !== "question") {
       return [];
     }
-    const links = await ctx.db.query("questionEvidenceLinks").withIndex(
-      "by_questionId",
-      (q) => q.eq("questionId", args.questionId)
-    ).collect();
-    const linksWithDetails = await Promise.all(
-      links.filter(
-        (link) => isOperationalLinkStatus(
-          link.status
-        )
-      ).map(async (link) => {
-        const insight = await ctx.db.get(link.insightId);
-        return {
-          ...link,
-          insight
-        };
-      })
+    const linksWithInsight = await fetchOperationalQuestionEvidenceLinks(
+      ctx,
+      args.questionId
     );
-    const filtered = linksWithDetails.filter((l) => l.insight !== null);
-    const epistemicEdgeResults = [];
-    const seenEvidenceIds = new Set(filtered.map((l) => String(l.insightId)));
-    const edges = await ctx.db.query("epistemicEdges").withIndex(
-      "by_to_type",
-      (q) => q.eq("toNodeId", args.questionId).eq("edgeType", "derived_from")
-    ).collect();
-    for (const edge of edges) {
-      if (!edge.fromNodeId || seenEvidenceIds.has(String(edge.fromNodeId))) {
-        continue;
-      }
-      seenEvidenceIds.add(String(edge.fromNodeId));
-      const evidenceNode = await ctx.db.get(edge.fromNodeId);
-      if (!evidenceNode || evidenceNode.nodeType !== "evidence" || evidenceNode.status !== "active") {
-        continue;
-      }
-      const meta = evidenceNode.metadata || {};
-      epistemicEdgeResults.push({
-        _id: edge._id,
-        _creationTime: edge.createdAt,
-        questionId: args.questionId,
-        insightId: edge.fromNodeId,
-        impact: (edge.weight ?? 0) > 0 ? "supports" : (edge.weight ?? 0) < 0 ? "contradicts" : "neutral",
-        impactScore: edge.weight != null ? Math.round(edge.weight * 10) : 0,
-        rationale: edge.context || null,
-        userId: edge.createdBy,
-        createdAt: edge.createdAt,
-        insight: {
-          _id: evidenceNode._id,
-          _creationTime: evidenceNode.createdAt,
-          insight: evidenceNode.canonicalText || evidenceNode.title || meta.snippet || null,
-          text: evidenceNode.canonicalText || evidenceNode.title || meta.snippet || null,
-          title: evidenceNode.title || null,
-          canonicalText: evidenceNode.canonicalText || null,
-          source: meta.sourceTitle || null,
-          sourceUrl: meta.sourceUrl || null,
-          verificationStatus: evidenceNode.verificationStatus || "unverified"
-        }
-      });
-    }
-    return [...filtered, ...epistemicEdgeResults];
+    const filteredLinks = linksWithInsight.filter(
+      (link) => link.insight !== null
+    );
+    const seenEvidenceIds = new Set(
+      filteredLinks.map((link) => String(link.insightId))
+    );
+    const edgeRows = await fetchDerivedFromEdgesWithDetails(
+      ctx,
+      args.questionId,
+      seenEvidenceIds
+    );
+    const evidenceRows = [...filteredLinks, ...edgeRows];
+    return evidenceRows;
   }
 });
 var getByProject = query({
@@ -1193,32 +1417,30 @@ var getByProject = query({
     }
     const pageSize = Math.max(1, Math.min(Math.floor(args.limit ?? 300), 1e3));
     const questionScanLimit = Math.min(pageSize * 2, 1e3);
-    const questions = await ctx.db.query("epistemicNodes").withIndex(
+    const questions = (await ctx.db.query("epistemicNodes").withIndex(
       "by_topic_type",
       (q) => q.eq("topicId", scope.topicId).eq("nodeType", "question")
-    ).order("desc").take(questionScanLimit);
+    ).order("desc").take(questionScanLimit)).flatMap((question) => {
+      const row = readEpistemicNode(question);
+      return row?.nodeType === "question" ? [row] : [];
+    });
     const questionIds = questions.slice(0, pageSize).map((q) => q._id);
     const allLinks = await Promise.all(
       questionIds.map(async (questionId) => {
-        const links = await ctx.db.query("questionEvidenceLinks").withIndex(
-          "by_questionId",
-          (q) => q.eq("questionId", questionId)
-        ).collect();
-        return links.filter(
-          (link) => isOperationalLinkStatus(
-            link.status
-          )
+        const links = readQuestionEvidenceLinks(
+          await ctx.db.query("questionEvidenceLinks").withIndex("by_questionId", (q) => q.eq("questionId", questionId)).collect()
         );
+        return links.filter((link) => isOperationalLinkStatus(link.status));
       })
     );
     const flattenedLinks = allLinks.flat().slice(0, pageSize * 5);
     const questionDetails = {};
     for (const question of questions) {
       const meta = question.metadata || {};
-      questionDetails[question._id] = {
-        _id: question._id,
-        question: question.canonicalText || question.title || "",
-        status: meta.status || question.status || "active"
+      questionDetails[String(question._id)] = {
+        _id: String(question._id),
+        question: question.canonicalText ?? question.title ?? "",
+        status: readOptionalString(meta.status) ?? question.status ?? "active"
       };
     }
     return {
@@ -1233,17 +1455,12 @@ var getLinkedQuestionsForInsight = query({
   },
   returns: permissiveReturn,
   handler: async (ctx, args) => {
-    const links = await ctx.db.query("questionEvidenceLinks").withIndex(
-      "by_insightId",
-      (q) => q.eq("insightId", args.insightId)
-    ).collect();
+    const links = readQuestionEvidenceLinks(
+      await ctx.db.query("questionEvidenceLinks").withIndex("by_insightId", (q) => q.eq("insightId", args.insightId)).collect()
+    );
     const linkedQuestions = await Promise.all(
-      links.filter(
-        (link) => isOperationalLinkStatus(
-          link.status
-        )
-      ).map(async (link) => {
-        const question = await ctx.db.get(link.questionId);
+      links.filter((link) => isOperationalLinkStatus(link.status)).map(async (link) => {
+        const question = readEpistemicNode(await ctx.db.get(link.questionId));
         return {
           linkId: link._id,
           questionId: link.questionId,
@@ -1254,7 +1471,7 @@ var getLinkedQuestionsForInsight = query({
           createdAt: link.createdAt,
           question: question ? {
             _id: question._id,
-            question: question.question || question.canonicalText || "",
+            question: question.canonicalText || question.title || "",
             status: question.status
           } : null
         };