@lucern/graph-primitives 1.0.28 → 1.0.30

package/dist/epistemicSources.js

@@ -1,15 +1,19 @@
-import { v } from 'convex/values';
-import { checkScopeAccess, requireProjectAccess } from '@lucern/access-control/access';
+import { checkScopeAccess, requireScopeWriteAccess } from '@lucern/access-control/access';
 import { permissiveReturn } from '@lucern/contracts/schema-helpers/validators';
-import { componentsGeneric, anyApi, mutationGeneric, queryGeneric } from 'convex/server';
+import { v } from 'convex/values';
+import { unsafeConvexAnyApi } from '@lucern/contracts/convex/unsafeAnyApi';
+import { componentsGeneric, mutationGeneric, queryGeneric } from 'convex/server';
+import '@lucern/contracts';
 import { generateGlobalId, assertUuidV7Identity } from '@lucern/contracts/ids';
 import { isNodeType, getLayerForNodeType } from '@lucern/contracts/schema-helpers/spine/tables/epistemicNodes';
-import '@lucern/contracts';
 
 // src/epistemicSources.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;
 
@@ -26,22 +30,19 @@ function debugGraphPrimitiveFallback(message, context) {
 }
 
 // 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",
@@ -53,6 +54,10 @@ async function scheduleEmbeddingGeneration(args) {
     );
   }
 }
+function insertEpistemicNode(ctx, doc) {
+  assertUuidV7Identity("epistemicNodes", doc.globalId);
+  return ctx.db.insert("epistemicNodes", doc);
+}
 var LEGACY_SCOPE_FIELD = "graphScopeProjectId";
 async function resolveTopicNodeScopeOrNull(ctx, ref) {
   if (!ctx?.db || typeof ctx.db.query !== "function") {
@@ -87,13 +92,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") {
@@ -118,8 +125,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();
@@ -131,7 +139,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);
@@ -187,137 +195,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
+  };
+}
 ({
   projectId: v.optional(v.string()),
   topicId: v.optional(v.string())
@@ -359,12 +345,11 @@ function assertWorkspaceScopedEpistemicNodeScope(args) {
     }
   });
 }
-async function insertEpistemicNode(ctx, doc) {
-  assertUuidV7Identity("epistemicNodes", doc.globalId);
-  return ctx.db.insert("epistemicNodes", doc);
-}
 
 // src/epistemicSources.ts
+var TRAILING_SLASHES_PATTERN = /\/+$/;
+var HASH_MODULUS = 2 ** 32;
+var HASH_SIGN_BOUNDARY = 2 ** 31;
 function throwStructuredSourceError(args) {
   const error = new Error(args.message);
   error.status = args.status;
@@ -376,28 +361,39 @@ function throwStructuredSourceError(args) {
 }
 function normalizeString(value) {
   if (typeof value !== "string") {
-    return void 0;
+    return;
   }
   const normalized = value.trim();
   return normalized.length > 0 ? normalized : void 0;
 }
+function readConvexId(value) {
+  const normalized = normalizeString(value);
+  return normalized ? normalized : null;
+}
 function normalizeNumber(value) {
   return typeof value === "number" && Number.isFinite(value) ? value : void 0;
 }
 function asRecord(value) {
   return value && typeof value === "object" && !Array.isArray(value) ? value : {};
 }
+function isSourceNodeDoc(value) {
+  const record = asRecord(value);
+  return readConvexId(record._id) !== null && normalizeString(record.nodeType) === "source";
+}
 function normalizeMetadata(metadata) {
   const record = asRecord(metadata);
   const { url: _ignoredUrl, contentSha: _ignoredSha, ...rest } = record;
   return rest;
 }
+function toSignedInt32(value) {
+  const normalized = (value % HASH_MODULUS + HASH_MODULUS) % HASH_MODULUS;
+  return normalized >= HASH_SIGN_BOUNDARY ? normalized - HASH_MODULUS : normalized;
+}
 function generateSourceContentHash(identity) {
   const content = `source:${identity.trim().toLowerCase()}`;
   let hash = 5381;
   for (let index = 0; index < content.length; index += 1) {
-    hash = (hash << 5) + hash + content.charCodeAt(index);
-    hash &= hash;
+    hash = toSignedInt32(hash * 33 + content.charCodeAt(index));
   }
   return Math.abs(hash).toString(16).padStart(8, "0");
 }
@@ -428,7 +424,7 @@ function normalizeSourceUrl(url) {
   const protocol = parsed.protocol.toLowerCase();
   const hostname = parsed.hostname.toLowerCase();
   const port = parsed.port ? `:${parsed.port}` : "";
-  const pathname = parsed.pathname === "/" ? "" : parsed.pathname.replace(/\/+$/, "");
+  const pathname = parsed.pathname === "/" ? "" : parsed.pathname.replace(TRAILING_SLASHES_PATTERN, "");
   const sortedEntries = [...parsed.searchParams.entries()].sort(
     ([aKey, aValue], [bKey, bValue]) => aKey === bKey ? aValue.localeCompare(bValue) : aKey.localeCompare(bKey)
   );
@@ -440,13 +436,13 @@ function normalizeSourceUrl(url) {
   return `${protocol}//${hostname}${port}${pathname}${search.length > 0 ? `?${search}` : ""}`;
 }
 async function findSourceByIdentity(ctx, args) {
-  const sourceNodes = await ctx.db.query("epistemicNodes").withIndex(
-    "by_nodeType",
-    (q) => q.eq("nodeType", "source")
-  ).collect();
+  const sourceNodes = await ctx.db.query("epistemicNodes").withIndex("by_nodeType", (q) => q.eq("nodeType", "source")).collect();
   let urlMatch = null;
   let shaMatch = null;
   for (const node of sourceNodes) {
+    if (!isSourceNodeDoc(node)) {
+      continue;
+    }
     const metadata = asRecord(node.metadata);
     if (args.normalizedUrl && normalizeString(metadata.url) === args.normalizedUrl && !urlMatch) {
       urlMatch = node;
@@ -483,18 +479,198 @@ function buildSourceMetadata(args) {
   if (args.capturedAt !== void 0) {
     nextMetadata.capturedAt = args.capturedAt;
   }
-  if (!Object.prototype.hasOwnProperty.call(existingMetadata, "url") && args.normalizedUrl) {
+  if (!Object.hasOwn(existingMetadata, "url") && args.normalizedUrl) {
     nextMetadata.url = args.normalizedUrl;
-  } else if (Object.prototype.hasOwnProperty.call(existingMetadata, "url")) {
+  } else if (Object.hasOwn(existingMetadata, "url")) {
     nextMetadata.url = existingMetadata.url;
   }
-  if (!Object.prototype.hasOwnProperty.call(existingMetadata, "contentSha") && args.sha) {
+  if (!Object.hasOwn(existingMetadata, "contentSha") && args.sha) {
     nextMetadata.contentSha = args.sha;
-  } else if (Object.prototype.hasOwnProperty.call(existingMetadata, "contentSha")) {
+  } else if (Object.hasOwn(existingMetadata, "contentSha")) {
     nextMetadata.contentSha = existingMetadata.contentSha;
   }
   return nextMetadata;
 }
+function readSourceIdentity(args) {
+  const sourceUrl = normalizeString(args.url);
+  const normalizedUrl = sourceUrl ? normalizeSourceUrl(sourceUrl) : void 0;
+  const sha = normalizeString(args.sha);
+  if (!(normalizedUrl || sha)) {
+    throwStructuredSourceError({
+      message: "Source identity requires a URL or content SHA.",
+      status: 400,
+      code: "INVALID_REQUEST",
+      invariantCode: "source.identity.required",
+      suggestion: "Provide url or sha."
+    });
+  }
+  return { normalizedUrl, sha };
+}
+async function syncSourceNodeToNeo4j(args) {
+  await args.ctx.scheduler.runAfter(0, internal.neo4jSync.syncNodeToNeo4j, {
+    nodeId: args.nodeId,
+    operation: "upsert"
+  });
+}
+async function insertSourceAudit(ctx, audit) {
+  await ctx.db.insert("epistemicAudit", { ...audit });
+}
+async function updateExistingSource(args) {
+  if (args.existing.topicId && !await checkScopeAccess(
+    args.ctx,
+    String(args.existing.topicId),
+    args.userId
+  )) {
+    throwStructuredSourceError({
+      message: "Access denied to existing source scope.",
+      status: 403,
+      code: "FORBIDDEN",
+      invariantCode: "policy.scope_required",
+      suggestion: "Request access to the source topic scope and retry.",
+      details: { topicId: args.existing.topicId }
+    });
+  }
+  const existingMetadata = asRecord(args.existing.metadata);
+  const existingSha = normalizeString(existingMetadata.contentSha);
+  if (args.sha && existingSha && existingSha !== args.sha) {
+    throwStructuredSourceError({
+      message: "Same URL cannot be reused with a different content hash.",
+      status: 409,
+      code: "CONTENT_SHA_MISMATCH",
+      invariantCode: "source.content_hash_immutable",
+      suggestion: "Same URL, different content. Create a new source with a distinct URL or use fork semantics.",
+      details: {
+        sourceId: String(args.existing._id),
+        url: existingMetadata.url,
+        existingSha,
+        receivedSha: args.sha
+      }
+    });
+  }
+  const nextMetadata = buildSourceMetadata({
+    existingMetadata,
+    kind: args.kind,
+    capturedAt: normalizeNumber(args.capturedAt),
+    metadata: args.metadataPatch
+  });
+  const patch = {
+    metadata: nextMetadata,
+    updatedAt: args.now
+  };
+  const title = normalizeString(args.title);
+  if (title) {
+    patch.title = title;
+    patch.canonicalText = title;
+  }
+  await args.ctx.db.patch(args.existing._id, patch);
+  await syncSourceNodeToNeo4j({
+    ctx: args.ctx,
+    nodeId: args.existing._id
+  });
+  await insertSourceAudit(args.ctx, {
+    entityType: "source",
+    entityId: String(args.existing._id),
+    changeType: "source_metadata_updated",
+    changedAt: args.now,
+    changedBy: args.userId,
+    isAgent: false,
+    topicId: args.existing.topicId ? String(args.existing.topicId) : void 0,
+    previousState: {
+      title: args.existing.title,
+      metadata: existingMetadata
+    },
+    newState: {
+      title: title ?? args.existing.title,
+      metadata: nextMetadata
+    }
+  });
+  const updated = await args.ctx.db.get(args.existing._id);
+  return isSourceNodeDoc(updated) ? updated : args.existing;
+}
+async function createSource(args) {
+  if (!normalizeString(args.topicId)) {
+    throwStructuredSourceError({
+      message: "topicId is required when creating a new source.",
+      status: 400,
+      code: "INVALID_REQUEST",
+      invariantCode: "source.context_required",
+      suggestion: "Provide topicId when creating a new source node."
+    });
+  }
+  const scope = await resolveTopicProjectScope(args.ctx, {
+    topicId: args.topicId
+  });
+  assertWorkspaceScopedEpistemicNodeScope({
+    scope,
+    nodeType: "source",
+    mutationName: "epistemicSources.upsertSource"
+  });
+  if (scope.projectId) {
+    await requireScopeWriteAccess(args.ctx, scope.projectId, args.userId);
+  }
+  const globalId = generateGlobalId();
+  const title = normalizeString(args.title);
+  const nextMetadata = buildSourceMetadata({
+    normalizedUrl: args.normalizedUrl,
+    sha: args.sha,
+    kind: args.kind,
+    capturedAt: normalizeNumber(args.capturedAt),
+    metadata: args.metadataPatch
+  });
+  const nodeId = await insertEpistemicNode(args.ctx, {
+    globalId,
+    topicId: scope.topicId,
+    projectId: scope.projectId,
+    tenantId: scope.tenantId,
+    workspaceId: scope.workspaceId,
+    nodeType: "source",
+    epistemicLayer: "L1",
+    canonicalText: title ?? args.normalizedUrl ?? "source",
+    contentHash: args.sha ?? generateSourceContentHash(args.normalizedUrl ?? title ?? "source"),
+    ...title ? { title } : {},
+    status: "active",
+    createdAt: args.now,
+    updatedAt: args.now,
+    createdBy: args.userId,
+    metadata: nextMetadata
+  });
+  await syncSourceNodeToNeo4j({
+    ctx: args.ctx,
+    nodeId
+  });
+  await scheduleEmbeddingGeneration({
+    ctx: args.ctx,
+    nodeId,
+    projectId: scope.projectId,
+    topicId: scope.topicId,
+    createdBy: args.userId,
+    nodeType: "source",
+    text: sourceEmbeddingText({
+      title,
+      url: args.normalizedUrl,
+      kind: args.kind,
+      metadata: nextMetadata
+    })
+  });
+  await insertSourceAudit(args.ctx, {
+    entityType: "source",
+    entityId: String(nodeId),
+    changeType: "source_created",
+    changedAt: args.now,
+    changedBy: args.userId,
+    isAgent: false,
+    topicId: scope.topicId ? String(scope.topicId) : void 0,
+    previousState: null,
+    newState: {
+      title,
+      url: args.normalizedUrl,
+      contentSha: args.sha,
+      kind: args.kind
+    }
+  });
+  const created = await args.ctx.db.get(nodeId);
+  return isSourceNodeDoc(created) ? created : null;
+}
 function sourceEmbeddingText(args) {
   const lines = [
     normalizeString(args.title),
@@ -517,169 +693,35 @@ var upsertSource = mutation({
   },
   returns: permissiveReturn,
   handler: async (ctx, args) => {
-    const sourceUrl = normalizeString(args.url);
-    const normalizedUrl = sourceUrl ? normalizeSourceUrl(sourceUrl) : void 0;
-    const sha = normalizeString(args.sha);
-    if (!normalizedUrl && !sha) {
-      throwStructuredSourceError({
-        message: "Source identity requires a URL or content SHA.",
-        status: 400,
-        code: "INVALID_REQUEST",
-        invariantCode: "source.identity.required",
-        suggestion: "Provide url or sha."
-      });
-    }
+    const { normalizedUrl, sha } = readSourceIdentity(args);
     const now = Date.now();
     const metadataPatch = normalizeMetadata(args.metadata);
     const existing = await findSourceByIdentity(ctx, { normalizedUrl, sha });
     if (existing) {
-      if (existing.topicId && !await checkScopeAccess(ctx, String(existing.topicId), args.userId)) {
-        throwStructuredSourceError({
-          message: "Access denied to existing source scope.",
-          status: 403,
-          code: "FORBIDDEN",
-          invariantCode: "policy.scope_required",
-          suggestion: "Request access to the source topic scope and retry.",
-          details: { topicId: existing.topicId }
-        });
-      }
-      const existingMetadata = asRecord(existing.metadata);
-      const existingSha = normalizeString(existingMetadata.contentSha);
-      if (sha && existingSha && existingSha !== sha) {
-        throwStructuredSourceError({
-          message: "Same URL cannot be reused with a different content hash.",
-          status: 409,
-          code: "CONTENT_SHA_MISMATCH",
-          invariantCode: "source.content_hash_immutable",
-          suggestion: "Same URL, different content. Create a new source with a distinct URL or use fork semantics.",
-          details: {
-            sourceId: String(existing._id),
-            url: existingMetadata.url,
-            existingSha,
-            receivedSha: sha
-          }
-        });
-      }
-      const nextMetadata2 = buildSourceMetadata({
-        existingMetadata,
+      return await updateExistingSource({
+        ctx,
+        existing,
         kind: args.kind,
-        capturedAt: normalizeNumber(args.capturedAt),
-        metadata: metadataPatch
+        capturedAt: args.capturedAt,
+        metadataPatch,
+        now,
+        sha,
+        title: args.title,
+        userId: args.userId
       });
-      const patch = {
-        metadata: nextMetadata2,
-        updatedAt: now
-      };
-      const title2 = normalizeString(args.title);
-      if (title2) {
-        patch.title = title2;
-        patch.canonicalText = title2;
-      }
-      await ctx.db.patch(existing._id, patch);
-      await ctx.scheduler.runAfter(0, internal.neo4jSync.syncNodeToNeo4j, {
-        nodeId: existing._id,
-        operation: "upsert"
-      });
-      await ctx.db.insert("epistemicAudit", {
-        entityType: "source",
-        entityId: existing._id,
-        changeType: "source_metadata_updated",
-        changedAt: now,
-        changedBy: args.userId,
-        isAgent: false,
-        topicId: existing.topicId ? String(existing.topicId) : void 0,
-        previousState: {
-          title: existing.title,
-          metadata: existingMetadata
-        },
-        newState: {
-          title: title2 ?? existing.title,
-          metadata: nextMetadata2
-        }
-      });
-      return await ctx.db.get(existing._id) ?? existing;
     }
-    if (!normalizeString(args.topicId)) {
-      throwStructuredSourceError({
-        message: "topicId is required when creating a new source.",
-        status: 400,
-        code: "INVALID_REQUEST",
-        invariantCode: "source.context_required",
-        suggestion: "Provide topicId when creating a new source node."
-      });
-    }
-    const scope = await resolveTopicProjectScope(ctx, {
-      topicId: args.topicId
-    });
-    assertWorkspaceScopedEpistemicNodeScope({
-      scope,
-      nodeType: "source",
-      mutationName: "epistemicSources.upsertSource"
-    });
-    if (scope.projectId) {
-      await requireProjectAccess(ctx, scope.projectId, args.userId);
-    }
-    const globalId = generateGlobalId();
-    const title = normalizeString(args.title);
-    const nextMetadata = buildSourceMetadata({
+    return await createSource({
+      ctx,
       normalizedUrl,
       sha,
       kind: args.kind,
-      capturedAt: normalizeNumber(args.capturedAt),
-      metadata: metadataPatch
+      capturedAt: args.capturedAt,
+      metadataPatch,
+      now,
+      title: args.title,
+      topicId: args.topicId,
+      userId: args.userId
     });
-    const nodeId = await insertEpistemicNode(ctx, {
-      globalId,
-      topicId: scope.topicId,
-      projectId: scope.projectId,
-      tenantId: scope.tenantId,
-      workspaceId: scope.workspaceId,
-      nodeType: "source",
-      epistemicLayer: "L1",
-      canonicalText: title ?? normalizedUrl ?? "source",
-      contentHash: sha ?? generateSourceContentHash(normalizedUrl ?? title ?? "source"),
-      ...title ? { title } : {},
-      status: "active",
-      createdAt: now,
-      updatedAt: now,
-      createdBy: args.userId,
-      metadata: nextMetadata
-    });
-    await ctx.scheduler.runAfter(0, internal.neo4jSync.syncNodeToNeo4j, {
-      nodeId,
-      operation: "upsert"
-    });
-    await scheduleEmbeddingGeneration({
-      ctx,
-      nodeId,
-      projectId: scope.projectId,
-      topicId: scope.topicId,
-      createdBy: args.userId,
-      nodeType: "source",
-      text: sourceEmbeddingText({
-        title,
-        url: normalizedUrl,
-        kind: args.kind,
-        metadata: nextMetadata
-      })
-    });
-    await ctx.db.insert("epistemicAudit", {
-      entityType: "source",
-      entityId: nodeId,
-      changeType: "source_created",
-      changedAt: now,
-      changedBy: args.userId,
-      isAgent: false,
-      topicId: scope.topicId ? String(scope.topicId) : void 0,
-      previousState: null,
-      newState: {
-        title,
-        url: normalizedUrl,
-        contentSha: sha,
-        kind: args.kind
-      }
-    });
-    return await ctx.db.get(nodeId);
   }
 });
 var getById = query({
@@ -689,14 +731,12 @@ var getById = query({
   },
   returns: permissiveReturn,
   handler: async (ctx, args) => {
-    const id = args.nodeId ?? args.sourceId;
+    const id = args.nodeId ?? readConvexId(args.sourceId);
     if (!id) {
       return null;
     }
-    const node = await ctx.db.get(
-      id
-    );
-    if (!node || node.nodeType !== "source") {
+    const node = await ctx.db.get(id);
+    if (!isSourceNodeDoc(node)) {
       return null;
     }
     return node;
@@ -710,7 +750,7 @@ var findByUrl = query({
   handler: async (ctx, args) => {
     const normalizedUrl = normalizeSourceUrl(args.url);
     const node = await findSourceByIdentity(ctx, { normalizedUrl });
-    return node && node.nodeType === "source" ? node : null;
+    return node?.nodeType === "source" ? node : null;
   }
 });
 var findBySha = query({
@@ -724,7 +764,7 @@ var findBySha = query({
       return null;
     }
     const node = await findSourceByIdentity(ctx, { sha });
-    return node && node.nodeType === "source" ? node : null;
+    return node?.nodeType === "source" ? node : null;
   }
 });