@lucern/graph-primitives 1.0.29 → 1.0.31

package/dist/entityLifecycle.js

@@ -1,39 +1,125 @@
-import { v } from 'convex/values';
 import { requireScopeWriteAccess } from '@lucern/access-control/access';
-import { throwStructuredMutationError } from '@lucern/access-control/structuredMutationError';
 import { getCurrentUserId } from '@lucern/access-control/auth';
+import { throwStructuredMutationError } from '@lucern/access-control/structuredMutationError';
 import { permissiveReturn } from '@lucern/contracts/schema-helpers/validators';
-import { componentsGeneric, anyApi, queryGeneric, mutationGeneric } from 'convex/server';
-import { generateGlobalId, assertUuidV7Identity, assertStorageEdgeVocabulary, assertUuidShapedEdgeEndpoint } from '@lucern/contracts/ids';
+import { v } from 'convex/values';
+import { unsafeConvexAnyApi } from '@lucern/contracts/convex/unsafeAnyApi';
+import { componentsGeneric, queryGeneric, mutationGeneric } from 'convex/server';
 import { assertEdgePolicyAllowed, edgePolicyManifest } from '@lucern/contracts';
+import { generateGlobalId, assertUuidV7Identity, assertStorageEdgeVocabulary, assertUuidShapedEdgeEndpoint } from '@lucern/contracts/ids';
 
 // src/entityLifecycle.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;
 
+// src/entityCanonicalMatch.ts
+function normalizeCanonicalEntityText(value) {
+  return value.trim().toLowerCase().replace(/\s+/g, " ");
+}
+function buildEntityTitle(canonicalText) {
+  return canonicalText.slice(0, 100) + (canonicalText.length > 100 ? "..." : "");
+}
+function matchesCanonicalEntityRecord(node, args) {
+  if (node.epistemicLayer !== "ontological") {
+    return false;
+  }
+  if (node.workspaceId !== void 0) {
+    return false;
+  }
+  if (args.nodeType && node.nodeType !== args.nodeType) {
+    return false;
+  }
+  if (args.contentHash && node.contentHash !== args.contentHash) {
+    return false;
+  }
+  const rowTenantId = typeof node.tenantId === "string" && node.tenantId.trim().length > 0 ? node.tenantId.trim() : void 0;
+  if (rowTenantId !== args.tenantId) {
+    return false;
+  }
+  if (args.includeArchived) {
+    return node.status !== "deleted";
+  }
+  return node.status === "active";
+}
+
 // src/entityValidation.ts
+function isObjectLike(value) {
+  return value !== null && typeof value === "object";
+}
+function isEntitySchemaConfigField(value) {
+  if (!isObjectLike(value)) {
+    return false;
+  }
+  const required = value.required;
+  const type = value.type;
+  return typeof required === "boolean" && (type === "string" || type === "number" || type === "boolean");
+}
+function readEntitySchema(value) {
+  if (!isObjectLike(value)) {
+    return {};
+  }
+  const schema = {};
+  for (const [fieldName, fieldValue] of Object.entries(value)) {
+    if (!isEntitySchemaConfigField(fieldValue)) {
+      continue;
+    }
+    schema[fieldName] = fieldValue;
+  }
+  return schema;
+}
+function readSchemaEnumConfigRow(row) {
+  if (!isObjectLike(row)) {
+    return null;
+  }
+  const value = row.value;
+  if (typeof value !== "string") {
+    return null;
+  }
+  return {
+    value,
+    status: typeof row.status === "string" ? row.status : void 0,
+    metadata: isObjectLike(row.metadata) ? row.metadata : void 0
+  };
+}
+function readEntitySchemaFromConfig(row) {
+  const parsed = readSchemaEnumConfigRow(row);
+  if (parsed?.status !== "active" || !parsed?.metadata) {
+    return null;
+  }
+  const schema = parsed.metadata.schema;
+  if (!schema) {
+    return null;
+  }
+  return readEntitySchema(schema);
+}
 async function getEntityTypeSchema(ctx, nodeType, tenantId) {
   if (tenantId) {
-    const tenantEntry = await ctx.db.query("schemaEnumConfig").withIndex(
+    const tenantEntries = await ctx.db.query("schemaEnumConfig").withIndex(
       "by_tenant_category",
       (q) => q.eq("tenantId", tenantId).eq("category", "entity_type")
     ).collect();
-    const tenantMatch = tenantEntry.find(
-      (e) => e.value === nodeType && e.status === "active"
-    );
-    if (tenantMatch?.metadata?.schema) {
-      return tenantMatch.metadata.schema;
+    const tenantMatch = tenantEntries.find((entry) => {
+      const parsed = readSchemaEnumConfigRow(entry);
+      return parsed !== null && parsed.value === nodeType && parsed.status === "active";
+    });
+    const tenantSchema = readEntitySchemaFromConfig(tenantMatch);
+    if (tenantSchema !== null) {
+      return tenantSchema;
     }
   }
   const platformEntry = await ctx.db.query("schemaEnumConfig").withIndex(
     "by_category_value",
     (q) => q.eq("category", "entity_type").eq("value", nodeType)
   ).first();
-  if (platformEntry?.metadata?.schema && platformEntry.status === "active") {
-    return platformEntry.metadata.schema;
+  const platformSchema = readEntitySchemaFromConfig(platformEntry);
+  if (platformSchema !== null) {
+    return platformSchema;
   }
   return null;
 }
@@ -77,99 +163,54 @@ async function validateEntityMetadata(ctx, nodeType, metadata, tenantId) {
     errors
   };
 }
-
-// src/entityCanonicalMatch.ts
-function normalizeCanonicalEntityText(value) {
-  return value.trim().toLowerCase().replace(/\s+/g, " ");
-}
-function buildEntityTitle(canonicalText) {
-  return canonicalText.slice(0, 100) + (canonicalText.length > 100 ? "..." : "");
-}
-function matchesCanonicalEntityRecord(node, args) {
-  if (node.epistemicLayer !== "ontological") {
-    return false;
-  }
-  if (node.workspaceId !== void 0) {
-    return false;
-  }
-  if (args.nodeType && node.nodeType !== args.nodeType) {
-    return false;
-  }
-  if (args.contentHash && node.contentHash !== args.contentHash) {
-    return false;
-  }
-  const rowTenantId = typeof node.tenantId === "string" && node.tenantId.trim().length > 0 ? node.tenantId.trim() : void 0;
-  if (rowTenantId !== args.tenantId) {
-    return false;
-  }
-  if (args.includeArchived) {
-    return node.status !== "deleted";
-  }
-  return node.status === "active";
+function insertEpistemicNode(ctx, doc) {
+  assertUuidV7Identity("epistemicNodes", doc.globalId);
+  return ctx.db.insert("epistemicNodes", doc);
 }
-
-// src/topicOntologyResolver.ts
-var MAX_RESOLUTION_DEPTH = 10;
-async function resolveTopicOntologyInternal(ctx, topicId) {
-  let current = await ctx.db.get(topicId);
-  if (!current) {
-    return null;
-  }
-  const startTopicId = topicId;
-  for (let i = 0; i < MAX_RESOLUTION_DEPTH && current; i++) {
-    if (current.ontologyId) {
-      const ontologyDef = await ctx.db.get(
-        current.ontologyId
-      );
-      if (!ontologyDef || ontologyDef.status === "archived") {
-        if (current.parentTopicId) {
-          current = await ctx.db.get(
-            current.parentTopicId
-          );
-          continue;
-        }
-        return null;
-      }
-      const versions = await ctx.db.query("ontologyVersions").withIndex(
-        "by_ontologyId",
-        (q) => q.eq("ontologyId", current?.ontologyId)
-      ).collect();
-      const published = versions.filter((v3) => v3.status === "published").sort((a, b) => (b.publishedAt ?? 0) - (a.publishedAt ?? 0));
-      const latestPublished = published[0] ?? null;
-      return {
-        ontologyId: ontologyDef._id,
-        ontologyKey: ontologyDef.ontologyKey,
-        ontologyName: ontologyDef.name,
-        tier: ontologyDef.tier,
-        source: current._id === startTopicId ? "direct" : "inherited",
-        sourceTopicId: current._id,
-        validEntityTypes: latestPublished ? latestPublished.entityTypes.map((et) => et.value) : [],
-        validEdgeTypes: latestPublished ? latestPublished.edgeTypes.map((et) => et.value) : [],
-        publishedVersion: latestPublished
-      };
-    }
-    if (!current.parentTopicId) {
-      break;
-    }
-    current = await ctx.db.get(current.parentTopicId);
+async function assertExistingNodeEndpoint(ctx, endpointRole, endpoint) {
+  assertUuidShapedEdgeEndpoint(endpointRole, endpoint);
+  const node = await ctx.db.query("epistemicNodes").withIndex(
+    "by_globalId",
+    (q) => q.eq("globalId", endpoint)
+  ).first();
+  if (!node) {
+    throw new Error(
+      `edge_endpoint_not_canonical: epistemicEdges insert requires ${endpointRole} to be the globalId of an existing epistemicNodes row, received ${endpoint} (no node with that globalId)`
+    );
   }
-  return null;
 }
-async function validateEntityTypeForTopic(ctx, topicId, nodeType) {
-  const resolved = await resolveTopicOntologyInternal(ctx, topicId);
-  if (!resolved) {
-    return { valid: true };
+async function insertEpistemicEdge(ctx, doc) {
+  assertUuidV7Identity("epistemicEdges", doc.globalId);
+  assertStorageEdgeVocabulary(doc.edgeType);
+  if (!doc.fromNodeId || typeof doc.fromNodeId !== "string") {
+    throw new Error(
+      "edge_endpoint_missing: epistemicEdges insert requires a non-empty fromNodeId"
+    );
   }
-  if (resolved.validEntityTypes.length === 0) {
-    return { valid: true };
+  if (!doc.toNodeId || typeof doc.toNodeId !== "string") {
+    throw new Error(
+      "edge_endpoint_missing: epistemicEdges insert requires a non-empty toNodeId"
+    );
   }
-  if (resolved.validEntityTypes.includes(nodeType)) {
-    return { valid: true };
+  await assertExistingNodeEndpoint(ctx, "fromNodeId", doc.fromNodeId);
+  await assertExistingNodeEndpoint(ctx, "toNodeId", doc.toNodeId);
+  if (doc.fromNodeType && doc.toNodeType && doc.edgeType !== "extracted_from") {
+    assertEdgePolicyAllowed(
+      edgePolicyManifest,
+      doc.edgeType,
+      {
+        kind: "epistemic_node",
+        nodeId: doc.fromNodeId,
+        nodeType: doc.fromNodeType
+      },
+      {
+        kind: "epistemic_node",
+        nodeId: doc.toNodeId,
+        nodeType: doc.toNodeType
+      }
+    );
   }
-  return {
-    valid: false,
-    error: `Entity type "${nodeType}" is not defined in the ontology "${resolved.ontologyKey}" (${resolved.ontologyName}). Valid entity types: ${resolved.validEntityTypes.join(", ")}. Source: ${resolved.source} from topic ${resolved.sourceTopicId}.`
-  };
+  return ctx.db.insert("epistemicEdges", doc);
 }
 
 // src/debug.ts
@@ -202,6 +243,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;
@@ -282,9 +327,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;
     }
@@ -304,8 +352,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,
@@ -374,90 +432,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);
+  }
+}
+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;
   }
-  patch.updatedAt = Date.now();
-  patch.metadata = nextMetadata;
-  topicUpdateArgs.metadata = nextMetadata;
+  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
@@ -485,7 +566,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(
@@ -518,6 +599,92 @@ function resolveGraphPrimitivesAppResolvers(_ctx) {
     ...resolverOverrides
   };
 }
+
+// src/topicOntologyResolver.ts
+var MAX_RESOLUTION_DEPTH = 10;
+async function loadTopic(ctx, topicId) {
+  return await ctx.db.get(topicId);
+}
+async function loadOntologyDefinition(ctx, ontologyId) {
+  return await ctx.db.get(ontologyId);
+}
+async function loadPublishedOntologyVersions(ctx, ontologyId) {
+  const versions = await ctx.db.query("ontologyVersions").withIndex("by_ontologyId", (q) => q.eq("ontologyId", ontologyId)).collect();
+  return versions.filter((version) => version.status === "published").sort((a, b) => (b.publishedAt ?? 0) - (a.publishedAt ?? 0));
+}
+function resolvedTopicOntology(args) {
+  return {
+    ontologyId: args.ontologyDef._id,
+    ontologyKey: args.ontologyDef.ontologyKey,
+    ontologyName: args.ontologyDef.name,
+    publishedVersion: args.latestPublished,
+    source: args.source,
+    sourceTopicId: args.sourceTopicId,
+    tier: args.ontologyDef.tier,
+    validEdgeTypes: args.latestPublished?.edgeTypes.map((edgeType) => edgeType.value) ?? [],
+    validEntityTypes: args.latestPublished?.entityTypes.map((entityType) => entityType.value) ?? []
+  };
+}
+async function resolveCurrentTopicOntology(args) {
+  if (!args.current.ontologyId) {
+    return "continue";
+  }
+  const ontologyDef = await loadOntologyDefinition(
+    args.ctx,
+    args.current.ontologyId
+  );
+  if (!ontologyDef || ontologyDef.status === "archived") {
+    return args.current.parentTopicId ? "continue" : null;
+  }
+  const published = await loadPublishedOntologyVersions(
+    args.ctx,
+    args.current.ontologyId
+  );
+  return resolvedTopicOntology({
+    latestPublished: published[0] ?? null,
+    ontologyDef,
+    source: args.current._id === args.startTopicId ? "direct" : "inherited",
+    sourceTopicId: args.current._id
+  });
+}
+async function resolveTopicOntologyInternal(ctx, topicId) {
+  let current = await loadTopic(ctx, topicId);
+  if (!current) {
+    return null;
+  }
+  const startTopicId = topicId;
+  for (let i = 0; i < MAX_RESOLUTION_DEPTH && current; i++) {
+    const resolved = await resolveCurrentTopicOntology({
+      ctx,
+      current,
+      startTopicId
+    });
+    if (resolved !== "continue") {
+      return resolved;
+    }
+    if (!current.parentTopicId) {
+      break;
+    }
+    current = await loadTopic(ctx, current.parentTopicId);
+  }
+  return null;
+}
+async function validateEntityTypeForTopic(ctx, topicId, nodeType) {
+  const resolved = await resolveTopicOntologyInternal(ctx, topicId);
+  if (!resolved) {
+    return { valid: true };
+  }
+  if (resolved.validEntityTypes.length === 0) {
+    return { valid: true };
+  }
+  if (resolved.validEntityTypes.includes(nodeType)) {
+    return { valid: true };
+  }
+  return {
+    valid: false,
+    error: `Entity type "${nodeType}" is not defined in the ontology "${resolved.ontologyKey}" (${resolved.ontologyName}). Valid entity types: ${resolved.validEntityTypes.join(", ")}. Source: ${resolved.source} from topic ${resolved.sourceTopicId}.`
+  };
+}
 var LEGACY_SCOPE_FIELD2 = "graphScopeProjectId";
 async function resolveTopicNodeScopeOrNull(ctx, ref) {
   if (!ctx?.db || typeof ctx.db.query !== "function") {
@@ -552,13 +719,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") {
@@ -583,8 +752,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();
@@ -596,7 +766,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);
@@ -652,187 +822,119 @@ 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."
   );
 }
-var optionalScopeArgs = {
-  projectId: v.optional(v.string()),
-  topicId: v.optional(v.string())
-};
-async function insertEpistemicNode(ctx, doc) {
-  assertUuidV7Identity("epistemicNodes", doc.globalId);
-  return ctx.db.insert("epistemicNodes", doc);
+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 assertExistingNodeEndpoint(ctx, endpointRole, endpoint) {
-  assertUuidShapedEdgeEndpoint(endpointRole, endpoint);
-  const node = await ctx.db.query("epistemicNodes").withIndex("by_globalId", (q) => q.eq("globalId", endpoint)).first();
-  if (!node) {
-    throw new Error(
-      `edge_endpoint_not_canonical: epistemicEdges insert requires ${endpointRole} to be the globalId of an existing epistemicNodes row, received ${endpoint} (no node with that globalId)`
-    );
+async function 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 insertEpistemicEdge(ctx, doc) {
-  assertUuidV7Identity("epistemicEdges", doc.globalId);
-  assertStorageEdgeVocabulary(doc.edgeType);
-  if (!doc.fromNodeId || typeof doc.fromNodeId !== "string") {
-    throw new Error(
-      "edge_endpoint_missing: epistemicEdges insert requires a non-empty fromNodeId"
-    );
+async function resolveScopeFromLegacyProjectId(ctx, legacyProjectId) {
+  const directTopic = await resolveDirectLegacyProjectTopic(
+    ctx,
+    legacyProjectId
+  );
+  if (directTopic) {
+    return await buildTopicScope(ctx, directTopic, "topic_inferred", {
+      fallbackProjectId: legacyProjectId
+    });
   }
-  if (!doc.toNodeId || typeof doc.toNodeId !== "string") {
-    throw new Error(
-      "edge_endpoint_missing: epistemicEdges insert requires a non-empty toNodeId"
-    );
+  const primary = pickPrimaryTopic(
+    await findTopicsByScopeAlias(ctx, legacyProjectId)
+  );
+  if (primary) {
+    return await buildTopicScope(ctx, primary, "project_mapped_topic", {
+      fallbackProjectId: legacyProjectId
+    });
   }
-  await assertExistingNodeEndpoint(ctx, "fromNodeId", doc.fromNodeId);
-  await assertExistingNodeEndpoint(ctx, "toNodeId", doc.toNodeId);
-  if (doc.fromNodeType && doc.toNodeType && doc.edgeType !== "extracted_from") {
-    assertEdgePolicyAllowed(
-      edgePolicyManifest,
-      doc.edgeType,
-      {
-        kind: "epistemic_node",
-        nodeId: doc.fromNodeId,
-        nodeType: doc.fromNodeType
-      },
-      {
-        kind: "epistemic_node",
-        nodeId: doc.toNodeId,
-        nodeType: doc.toNodeType
-      }
-    );
+  const 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;
   }
-  return ctx.db.insert("epistemicEdges", doc);
 }
+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())
+};
 
 // src/entityLifecycle.ts
 async function requireAuthenticatedUserId(ctx) {
@@ -868,14 +970,227 @@ var ONTOLOGICAL_NODE_TYPE_SET = new Set(ONTOLOGICAL_NODE_TYPES);
 var isOntologicalNodeType = ONTOLOGICAL_NODE_TYPE_SET.has.bind(
   ONTOLOGICAL_NODE_TYPE_SET
 );
+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 readOptionalString(value) {
+  return typeof value === "string" && value.trim().length > 0 ? value : void 0;
+}
+function readRecord(value) {
+  return isRecord(value) ? value : void 0;
+}
+function readStringArray2(value) {
+  return Array.isArray(value) ? value.filter((entry) => typeof entry === "string") : void 0;
+}
+function readEntityUpdateMetadata(value) {
+  if (!isRecord(value)) {
+    return;
+  }
+  const metadata = {};
+  const crunchbase = readOptionalString(value.crunchbase);
+  const linkedin = readOptionalString(value.linkedin);
+  const pitchbook = readOptionalString(value.pitchbook);
+  const twitter = readOptionalString(value.twitter);
+  const website = readOptionalString(value.website);
+  if (crunchbase !== void 0) {
+    metadata.crunchbase = crunchbase;
+  }
+  if (linkedin !== void 0) {
+    metadata.linkedin = linkedin;
+  }
+  if (pitchbook !== void 0) {
+    metadata.pitchbook = pitchbook;
+  }
+  if (twitter !== void 0) {
+    metadata.twitter = twitter;
+  }
+  if (website !== void 0) {
+    metadata.website = website;
+  }
+  return metadata;
+}
+function readCanonicalEntityRecord(value) {
+  if (!isRecord(value)) {
+    return null;
+  }
+  const id = readConvexId(value._id);
+  if (!id) {
+    return null;
+  }
+  const record = { _id: id };
+  const canonicalText = readOptionalString(value.canonicalText);
+  const contentHash = readOptionalString(value.contentHash);
+  const domain = readOptionalString(value.domain);
+  const epistemicLayer = readOptionalString(value.epistemicLayer);
+  const externalIds = readRecord(value.externalIds);
+  const globalId = readOptionalString(value.globalId);
+  const metadata = readRecord(value.metadata);
+  const nodeType = readOptionalString(value.nodeType);
+  const projectId = readOptionalString(value.projectId);
+  const status = readOptionalString(value.status);
+  const subtype = readOptionalString(value.subtype);
+  const tags = readStringArray2(value.tags);
+  const tenantId = readOptionalString(value.tenantId);
+  const title = readOptionalString(value.title);
+  const verificationStatus = readOptionalString(value.verificationStatus);
+  const workspaceId = readOptionalString(value.workspaceId);
+  if (canonicalText !== void 0) {
+    record.canonicalText = canonicalText;
+  }
+  if (contentHash !== void 0) {
+    record.contentHash = contentHash;
+  }
+  if (domain !== void 0) {
+    record.domain = domain;
+  }
+  if (epistemicLayer !== void 0) {
+    record.epistemicLayer = epistemicLayer;
+  }
+  if (externalIds !== void 0) {
+    record.externalIds = externalIds;
+  }
+  if (globalId !== void 0) {
+    record.globalId = globalId;
+  }
+  if (metadata !== void 0) {
+    record.metadata = metadata;
+  }
+  if (nodeType !== void 0) {
+    record.nodeType = nodeType;
+  }
+  if (projectId !== void 0) {
+    record.projectId = projectId;
+  }
+  if (status !== void 0) {
+    record.status = status;
+  }
+  if (subtype !== void 0) {
+    record.subtype = subtype;
+  }
+  if (tags !== void 0) {
+    record.tags = tags;
+  }
+  if (tenantId !== void 0) {
+    record.tenantId = tenantId;
+  }
+  if (title !== void 0) {
+    record.title = title;
+  }
+  if (verificationStatus !== void 0) {
+    record.verificationStatus = verificationStatus;
+  }
+  if (workspaceId !== void 0) {
+    record.workspaceId = workspaceId;
+  }
+  return record;
+}
+function readEntityEdgeRecord(value) {
+  if (!isRecord(value)) {
+    return null;
+  }
+  const id = readConvexId(value._id);
+  if (!id) {
+    return null;
+  }
+  const edge = { _id: id };
+  const fromNodeId = readConvexId(value.fromNodeId);
+  const toNodeId = readConvexId(value.toNodeId);
+  if (fromNodeId !== void 0) {
+    edge.fromNodeId = fromNodeId;
+  }
+  if (toNodeId !== void 0) {
+    edge.toNodeId = toNodeId;
+  }
+  return edge;
+}
+function readRowList(values, reader) {
+  return values.flatMap((value) => {
+    const row = reader(value);
+    return row ? [row] : [];
+  });
+}
+function readScopeTopicDoc(value) {
+  if (!isRecord(value)) {
+    return null;
+  }
+  const id = readConvexId(value._id);
+  if (!id) {
+    return null;
+  }
+  const topic = { _id: id };
+  const tenantId = readOptionalString(value.tenantId);
+  const workspaceId = readOptionalString(value.workspaceId);
+  if (tenantId !== void 0) {
+    topic.tenantId = tenantId;
+  }
+  if (workspaceId !== void 0) {
+    topic.workspaceId = workspaceId;
+  }
+  return topic;
+}
+function readScopeProjectDoc(value) {
+  if (!isRecord(value)) {
+    return null;
+  }
+  const id = readOptionalString(value._id);
+  if (!id) {
+    return null;
+  }
+  const project = { _id: id };
+  const tenantId = readOptionalString(value.tenantId);
+  const workspaceId = readOptionalString(value.workspaceId);
+  if (tenantId !== void 0) {
+    project.tenantId = tenantId;
+  }
+  if (workspaceId !== void 0) {
+    project.workspaceId = workspaceId;
+  }
+  return project;
+}
+function readEntityUpdateNode(value) {
+  const node = readCanonicalEntityRecord(value);
+  const nodeType = node?.nodeType;
+  if (!(node?.canonicalText && nodeType && isOntologicalNodeType(nodeType))) {
+    return null;
+  }
+  return {
+    _id: node._id,
+    canonicalText: node.canonicalText,
+    domain: node.domain,
+    externalIds: readEntityUpdateMetadata(node.externalIds),
+    globalId: node.globalId,
+    metadata: node.metadata,
+    nodeType,
+    projectId: node.projectId,
+    status: node.status,
+    subtype: node.subtype,
+    tags: node.tags,
+    tenantId: node.tenantId,
+    title: node.title,
+    verificationStatus: node.verificationStatus
+  };
+}
 async function resolveCanonicalEntityScope(ctx, args) {
   const scope = await resolveTopicProjectScope(ctx, args);
-  const topic = scope.topicId ? await ctx.db.get(scope.topicId) ?? null : null;
-  const project = scope.projectId !== void 0 ? await resolveGraphPrimitivesAppResolvers().getProject(
-    ctx,
-    scope.projectId
-  ) ?? null : null;
-  const tenantId = typeof topic?.tenantId === "string" && topic.tenantId.trim().length > 0 ? topic.tenantId.trim() : typeof project?.tenantId === "string" && project.tenantId.trim().length > 0 ? project.tenantId.trim() : void 0;
+  const topic = scope.topicId ? readScopeTopicDoc(await ctx.db.get(scope.topicId)) : null;
+  const project = scope.projectId === void 0 ? null : readScopeProjectDoc(
+    await resolveGraphPrimitivesAppResolvers().getProject(
+      ctx,
+      scope.projectId
+    )
+  );
+  let tenantId;
+  if (typeof topic?.tenantId === "string") {
+    const trimmedTopicTenantId = topic.tenantId.trim();
+    tenantId = trimmedTopicTenantId.length > 0 ? trimmedTopicTenantId : void 0;
+  }
+  if (tenantId === void 0 && typeof project?.tenantId === "string") {
+    const trimmedProjectTenantId = project.tenantId.trim();
+    tenantId = trimmedProjectTenantId.length > 0 ? trimmedProjectTenantId : void 0;
+  }
   return {
     ...scope,
     tenantId,
@@ -885,10 +1200,13 @@ async function resolveCanonicalEntityScope(ctx, args) {
 }
 async function findExistingCanonicalEntity(ctx, args) {
   const contentHash = generateContentHash(args.nodeType, args.canonicalText);
-  const candidates = await ctx.db.query("epistemicNodes").withIndex(
-    "by_contentHash",
-    (q) => q.eq("contentHash", contentHash)
-  ).collect();
+  const candidates = readRowList(
+    await ctx.db.query("epistemicNodes").withIndex(
+      "by_contentHash",
+      (q) => q.eq("contentHash", contentHash)
+    ).collect(),
+    readCanonicalEntityRecord
+  );
   return candidates.find(
     (node) => matchesCanonicalEntityRecord(node, {
       nodeType: args.nodeType,
@@ -898,13 +1216,29 @@ async function findExistingCanonicalEntity(ctx, args) {
   ) ?? null;
 }
 async function listCanonicalEntitiesForScope(ctx, args) {
-  const baseRows = args.tenantId !== void 0 ? await ctx.db.query("epistemicNodes").withIndex(
-    "by_tenantId",
-    (q) => q.eq("tenantId", args.tenantId)
-  ).collect() : args.nodeType ? await ctx.db.query("epistemicNodes").withIndex(
-    "by_nodeType",
-    (q) => q.eq("nodeType", args.nodeType)
-  ).collect() : await ctx.db.query("epistemicNodes").collect();
+  let baseRows = readRowList(
+    await ctx.db.query("epistemicNodes").collect(),
+    readCanonicalEntityRecord
+  );
+  if (args.tenantId === void 0) {
+    if (args.nodeType !== void 0) {
+      baseRows = readRowList(
+        await ctx.db.query("epistemicNodes").withIndex(
+          "by_nodeType",
+          (q) => q.eq("nodeType", args.nodeType)
+        ).collect(),
+        readCanonicalEntityRecord
+      );
+    }
+  } else {
+    baseRows = readRowList(
+      await ctx.db.query("epistemicNodes").withIndex(
+        "by_tenantId",
+        (q) => q.eq("tenantId", args.tenantId)
+      ).collect(),
+      readCanonicalEntityRecord
+    );
+  }
   const normalizedSearch = typeof args.searchTerm === "string" && args.searchTerm.trim().length > 0 ? normalizeCanonicalEntityText(args.searchTerm) : void 0;
   return baseRows.filter(
     (node) => matchesCanonicalEntityRecord(node, {
@@ -995,11 +1329,7 @@ var createEntity = mutation({
       projectId: args.projectId
     });
     if (scope.projectId) {
-      await requireScopeWriteAccess(
-        ctx,
-        scope.projectId,
-        authenticatedUserId
-      );
+      await requireScopeWriteAccess(ctx, scope.projectId, authenticatedUserId);
     }
     if (scope.topicId) {
       const ontologyValidation = await validateEntityTypeForTopic(
@@ -1018,7 +1348,7 @@ var createEntity = mutation({
         });
       }
     }
-    const metadata = args.metadata || {};
+    const metadata = readRecord(args.metadata) ?? {};
     const validation = await validateEntityMetadata(
       ctx,
       args.nodeType,
@@ -1093,6 +1423,100 @@ var createEntity = mutation({
     return { nodeId, globalId: entityGlobalId, isDuplicate: false };
   }
 });
+function normalizeEntityMetadataPatch(metadata) {
+  return metadata === null || metadata === void 0 ? {} : metadata;
+}
+function resolveScopeProjectId(node) {
+  return typeof node.projectId === "string" && node.projectId.trim().length > 0 ? node.projectId : void 0;
+}
+function prepareEntityAttributePlan(node, args) {
+  const existingMetadata = node.metadata ?? {};
+  const mergedMetadata = {
+    ...existingMetadata,
+    ...normalizeEntityMetadataPatch(args.metadata)
+  };
+  if (args.subtype !== void 0) {
+    mergedMetadata.subtype = args.subtype;
+  }
+  const nextCanonicalText = args.canonicalText === void 0 ? node.canonicalText : args.canonicalText.trim();
+  if (nextCanonicalText.length === 0) {
+    throwStructuredMutationError({
+      message: "canonicalText cannot be empty.",
+      status: 400,
+      code: "INVALID_REQUEST",
+      invariantCode: "entity.update_requires_entity_lifecycle"
+    });
+  }
+  return {
+    nextCanonicalText,
+    existingMetadata,
+    mergedMetadata
+  };
+}
+async function loadEntityForUpdate(ctx, nodeId) {
+  const node = readEntityUpdateNode(await ctx.db.get(nodeId));
+  if (!node) {
+    throwStructuredMutationError({
+      message: "Entity not found.",
+      status: 404,
+      code: "NOT_FOUND",
+      details: { nodeId }
+    });
+  }
+  return node;
+}
+async function assertCanonicalEntityUnique(ctx, node, nodeId, canonicalText) {
+  const duplicate = await findExistingCanonicalEntity(ctx, {
+    nodeType: node.nodeType,
+    canonicalText,
+    tenantId: typeof node.tenantId === "string" ? node.tenantId : void 0
+  });
+  if (duplicate && String(duplicate._id) !== String(nodeId)) {
+    throwStructuredMutationError({
+      message: "A canonical entity with this name already exists in the tenant scope.",
+      status: 409,
+      code: "CONFLICT",
+      invariantCode: "entity.canonical_text_unique_per_tenant",
+      suggestion: "Merge the duplicate entity instead of renaming this node onto an existing canonical record.",
+      details: {
+        nodeId,
+        duplicateNodeId: duplicate._id,
+        canonicalText
+      }
+    });
+  }
+}
+function buildEntityAttributeUpdates(node, args, plan) {
+  const updates = {
+    metadata: plan.mergedMetadata
+  };
+  if (args.canonicalText !== void 0) {
+    updates.canonicalText = plan.nextCanonicalText;
+    updates.contentHash = generateContentHash(
+      node.nodeType,
+      plan.nextCanonicalText
+    );
+    updates.title = args.title === void 0 ? buildEntityTitle(plan.nextCanonicalText) : args.title;
+  } else if (args.title !== void 0) {
+    updates.title = args.title;
+  }
+  if (args.subtype !== void 0) {
+    updates.subtype = args.subtype;
+  }
+  if (args.domain !== void 0) {
+    updates.domain = args.domain;
+  }
+  if (args.tags !== void 0) {
+    updates.tags = args.tags;
+  }
+  if (args.verificationStatus !== void 0) {
+    updates.verificationStatus = args.verificationStatus;
+  }
+  if (args.externalIds !== void 0) {
+    updates.externalIds = args.externalIds;
+  }
+  return updates;
+}
 var updateEntityAttributes = mutation({
   args: {
     nodeId: v.id("epistemicNodes"),
@@ -1118,68 +1542,33 @@ var updateEntityAttributes = mutation({
   handler: async (ctx, args) => {
     const authenticatedUserId = await requireAuthenticatedUserId(ctx);
     const now = Date.now();
-    const node = await ctx.db.get(args.nodeId);
-    if (!node) {
-      throwStructuredMutationError({
-        message: "Entity not found.",
-        status: 404,
-        code: "NOT_FOUND",
-        details: { nodeId: args.nodeId }
-      });
-    }
-    if (!isOntologicalNodeType(node.nodeType)) {
-      throwStructuredMutationError({
-        message: `Node "${args.nodeId}" is a ${node.nodeType}, not an entity. Use belief/question APIs for epistemic nodes.`,
-        status: 400,
-        code: "LIFECYCLE_VIOLATION",
-        invariantCode: "entity.type_check",
-        suggestion: "Only ontological entities can be updated via updateEntityAttributes."
-      });
-    }
-    const scopeProjectId = typeof node.projectId === "string" && node.projectId.trim().length > 0 ? node.projectId : void 0;
-    if (scopeProjectId) {
+    const node = await loadEntityForUpdate(ctx, args.nodeId);
+    const scopeProjectId = resolveScopeProjectId(node);
+    if (scopeProjectId !== void 0) {
       await requireScopeWriteAccess(ctx, scopeProjectId, authenticatedUserId);
     }
-    const existingMetadata = node.metadata || {};
-    const newMetadataFields = args.metadata !== void 0 ? args.metadata || {} : {};
-    const mergedMetadata = { ...existingMetadata, ...newMetadataFields };
-    if (args.subtype !== void 0) {
-      mergedMetadata.subtype = args.subtype;
-    }
-    if (args.canonicalText !== void 0 && args.canonicalText.trim().length === 0) {
-      throwStructuredMutationError({
-        message: "canonicalText cannot be empty.",
-        status: 400,
-        code: "INVALID_REQUEST",
-        invariantCode: "entity.update_requires_entity_lifecycle"
-      });
-    }
-    const nextCanonicalText = typeof args.canonicalText === "string" && args.canonicalText.trim().length > 0 ? args.canonicalText.trim() : node.canonicalText;
+    const plan = prepareEntityAttributePlan(node, {
+      canonicalText: args.canonicalText,
+      metadata: args.metadata,
+      subtype: args.subtype,
+      domain: args.domain,
+      title: args.title,
+      tags: args.tags,
+      verificationStatus: args.verificationStatus,
+      externalIds: args.externalIds
+    });
     if (args.canonicalText !== void 0) {
-      const duplicate = await findExistingCanonicalEntity(ctx, {
-        nodeType: node.nodeType,
-        canonicalText: nextCanonicalText,
-        tenantId: typeof node.tenantId === "string" ? node.tenantId : void 0
-      });
-      if (duplicate && String(duplicate._id) !== String(args.nodeId)) {
-        throwStructuredMutationError({
-          message: "A canonical entity with this name already exists in the tenant scope.",
-          status: 409,
-          code: "CONFLICT",
-          invariantCode: "entity.canonical_text_unique_per_tenant",
-          suggestion: "Merge the duplicate entity instead of renaming this node onto an existing canonical record.",
-          details: {
-            nodeId: args.nodeId,
-            duplicateNodeId: duplicate._id,
-            canonicalText: nextCanonicalText
-          }
-        });
-      }
+      await assertCanonicalEntityUnique(
+        ctx,
+        node,
+        args.nodeId,
+        plan.nextCanonicalText
+      );
     }
     const validation = await validateEntityMetadata(
       ctx,
       node.nodeType,
-      mergedMetadata,
+      plan.mergedMetadata,
       typeof node.tenantId === "string" ? node.tenantId : void 0
     );
     if (!validation.valid) {
@@ -1192,31 +1581,22 @@ var updateEntityAttributes = mutation({
       });
     }
     const updates = {
-      metadata: mergedMetadata,
+      ...buildEntityAttributeUpdates(
+        node,
+        {
+          canonicalText: args.canonicalText,
+          title: args.title,
+          metadata: args.metadata,
+          subtype: args.subtype,
+          domain: args.domain,
+          tags: args.tags,
+          verificationStatus: args.verificationStatus,
+          externalIds: args.externalIds
+        },
+        plan
+      ),
       updatedAt: now
     };
-    if (args.canonicalText !== void 0) {
-      updates.canonicalText = nextCanonicalText;
-      updates.contentHash = generateContentHash(node.nodeType, nextCanonicalText);
-      updates.title = args.title !== void 0 ? args.title : buildEntityTitle(nextCanonicalText);
-    } else if (args.title !== void 0) {
-      updates.title = args.title;
-    }
-    if (args.subtype !== void 0) {
-      updates.subtype = args.subtype;
-    }
-    if (args.domain !== void 0) {
-      updates.domain = args.domain;
-    }
-    if (args.tags !== void 0) {
-      updates.tags = args.tags;
-    }
-    if (args.verificationStatus !== void 0) {
-      updates.verificationStatus = args.verificationStatus;
-    }
-    if (args.externalIds !== void 0) {
-      updates.externalIds = args.externalIds;
-    }
     await ctx.db.patch(args.nodeId, updates);
     await ctx.scheduler.runAfter(0, internal.neo4jSync.syncNodeToNeo4j, {
       nodeId: args.nodeId,
@@ -1237,7 +1617,7 @@ var updateEntityAttributes = mutation({
         tags: node.tags,
         verificationStatus: node.verificationStatus,
         externalIds: node.externalIds,
-        metadata: existingMetadata
+        metadata: plan.existingMetadata
       },
       newState: updates,
       projectId: scopeProjectId
@@ -1254,9 +1634,13 @@ var mergeEntities = mutation({
   handler: async (ctx, args) => {
     const authenticatedUserId = await requireAuthenticatedUserId(ctx);
     const now = Date.now();
-    const canonical = await ctx.db.get(args.canonicalNodeId);
-    const duplicate = await ctx.db.get(args.duplicateNodeId);
-    if (!canonical || !duplicate) {
+    const canonical = readEntityUpdateNode(
+      await ctx.db.get(args.canonicalNodeId)
+    );
+    const duplicate = readEntityUpdateNode(
+      await ctx.db.get(args.duplicateNodeId)
+    );
+    if (!(canonical && duplicate)) {
       throwStructuredMutationError({
         message: "One or both entity nodes not found.",
         status: 404,
@@ -1267,14 +1651,6 @@ var mergeEntities = mutation({
         }
       });
     }
-    if (!isOntologicalNodeType(canonical.nodeType) || !isOntologicalNodeType(duplicate.nodeType)) {
-      throwStructuredMutationError({
-        message: "Both nodes must be ontological entities to merge.",
-        status: 400,
-        code: "LIFECYCLE_VIOLATION",
-        invariantCode: "entity.type_check"
-      });
-    }
     if (args.canonicalNodeId === args.duplicateNodeId) {
       throwStructuredMutationError({
         message: "Cannot merge an entity with itself.",
@@ -1285,6 +1661,18 @@ var mergeEntities = mutation({
         details: { canonicalNodeId: args.canonicalNodeId }
       });
     }
+    if (!(canonical.globalId && duplicate.globalId)) {
+      throwStructuredMutationError({
+        message: "Both entity nodes must have globalId values to merge.",
+        status: 400,
+        code: "LIFECYCLE_VIOLATION",
+        invariantCode: "entity.global_id_required",
+        details: {
+          canonicalNodeId: args.canonicalNodeId,
+          duplicateNodeId: args.duplicateNodeId
+        }
+      });
+    }
     if (canonical.nodeType !== duplicate.nodeType) {
       throwStructuredMutationError({
         message: `Cannot merge different entity types: ${canonical.nodeType} vs ${duplicate.nodeType}.`,
@@ -1314,10 +1702,13 @@ var mergeEntities = mutation({
       createdAt: now,
       updatedAt: now
     });
-    const outgoingEdges = await ctx.db.query("epistemicEdges").withIndex(
-      "by_from",
-      (q) => q.eq("fromNodeId", args.duplicateNodeId)
-    ).collect();
+    const outgoingEdges = readRowList(
+      await ctx.db.query("epistemicEdges").withIndex(
+        "by_from",
+        (q) => q.eq("fromNodeId", args.duplicateNodeId)
+      ).collect(),
+      readEntityEdgeRecord
+    );
     for (const edge of outgoingEdges) {
       if (edge.toNodeId === args.canonicalNodeId) {
         continue;
@@ -1328,10 +1719,13 @@ var mergeEntities = mutation({
         updatedAt: now
       });
     }
-    const incomingEdges = await ctx.db.query("epistemicEdges").withIndex(
-      "by_to",
-      (q) => q.eq("toNodeId", args.duplicateNodeId)
-    ).collect();
+    const incomingEdges = readRowList(
+      await ctx.db.query("epistemicEdges").withIndex(
+        "by_to",
+        (q) => q.eq("toNodeId", args.duplicateNodeId)
+      ).collect(),
+      readEntityEdgeRecord
+    );
     for (const edge of incomingEdges) {
       if (edge.fromNodeId === args.canonicalNodeId) {
         continue;
@@ -1342,7 +1736,7 @@ var mergeEntities = mutation({
         updatedAt: now
       });
     }
-    const duplicateMetadata = duplicate.metadata || {};
+    const duplicateMetadata = duplicate.metadata ?? {};
     await ctx.db.patch(args.duplicateNodeId, {
       status: "superseded",
       metadata: {
@@ -1407,29 +1801,9 @@ var archiveEntity = mutation({
   handler: async (ctx, args) => {
     const authenticatedUserId = await requireAuthenticatedUserId(ctx);
     const now = Date.now();
-    const node = await ctx.db.get(args.nodeId);
-    if (!node) {
-      throwStructuredMutationError({
-        message: "Entity not found.",
-        status: 404,
-        code: "NOT_FOUND",
-        details: { nodeId: args.nodeId }
-      });
-    }
-    if (!isOntologicalNodeType(node.nodeType)) {
-      throwStructuredMutationError({
-        message: `Node "${args.nodeId}" is a ${node.nodeType}, not an entity. Use belief archive APIs for epistemic nodes.`,
-        status: 400,
-        code: "LIFECYCLE_VIOLATION",
-        invariantCode: "entity.type_check"
-      });
-    }
+    const node = await loadEntityForUpdate(ctx, args.nodeId);
     if (node.projectId) {
-      await requireScopeWriteAccess(
-        ctx,
-        node.projectId,
-        authenticatedUserId
-      );
+      await requireScopeWriteAccess(ctx, node.projectId, authenticatedUserId);
     }
     await ctx.db.patch(args.nodeId, {
       status: "archived",