@lucern/graph-primitives 0.1.0-alpha.2

package/dist/entityLifecycle.js

@@ -0,0 +1,2083 @@
+import { v } from 'convex/values';
+import { componentsGeneric, queryGeneric, mutationGeneric, anyApi } from 'convex/server';
+
+// src/entityLifecycle.ts
+var api = anyApi;
+componentsGeneric();
+
+// ../access-control/src/topicProjectOverlay.ts
+var LEGACY_SCOPE_FIELD = "graphScopeProjectId";
+function readNonEmptyString(value) {
+  if (typeof value !== "string") {
+    return;
+  }
+  const normalized = value.trim();
+  return normalized.length > 0 ? normalized : void 0;
+}
+function readStringArray(value) {
+  if (!Array.isArray(value)) {
+    return [];
+  }
+  return value.map((entry) => readNonEmptyString(entry)).filter((entry) => Boolean(entry));
+}
+function readMetadata(topic) {
+  return topic.metadata && typeof topic.metadata === "object" ? topic.metadata : {};
+}
+function readLegacyProjectId(value) {
+  if (!value) {
+    return;
+  }
+  return readNonEmptyString(value[LEGACY_SCOPE_FIELD]);
+}
+function coerceVisibility(value) {
+  return value === "private" || value === "team" || value === "firm" || value === "external" || value === "public" ? value : void 0;
+}
+function coerceStatus(value) {
+  return value === "active" || value === "archived" || value === "watching" ? value : void 0;
+}
+function mapProjectType(topic, metadata) {
+  const explicit = readNonEmptyString(metadata.projectType);
+  if (explicit) {
+    return explicit;
+  }
+  if (topic.type === "theme") {
+    return "thematic";
+  }
+  return readNonEmptyString(topic.type) || "general";
+}
+function isProjectLikeTopic(topic) {
+  const metadata = readMetadata(topic);
+  return topic.type === "theme" || topic.type === "thematic" || topic.type === "deal" || topic.type === "monitoring" || readLegacyProjectId(topic) !== void 0 || readNonEmptyString(metadata.projectType) !== void 0;
+}
+async function resolveTopicDoc(ctx, scopeId) {
+  if (ctx?.db && typeof ctx.db.get === "function") {
+    try {
+      const directTopic = await ctx.db.get(scopeId);
+      if (directTopic) {
+        return directTopic;
+      }
+    } catch {
+    }
+  }
+  if (typeof ctx.runQuery !== "function") {
+    return null;
+  }
+  try {
+    const topic = await ctx.runQuery(api.topics.get, {
+      id: String(scopeId)
+    });
+    if (topic?.name !== void 0 && topic?.type !== void 0) {
+      return topic;
+    }
+  } catch {
+  }
+  try {
+    const topic = await ctx.runQuery(api.topics.getByLegacyScopeId, {
+      projectId: String(scopeId)
+    });
+    if (topic?.name !== void 0 && topic?.type !== void 0) {
+      return topic;
+    }
+  } catch {
+  }
+  return null;
+}
+function materializeTopicProjectOverlay(topic, idMode = "legacy") {
+  const metadata = readMetadata(topic);
+  const topicId = String(topic._id);
+  const legacyProjectId = readLegacyProjectId(topic) || readLegacyProjectId(metadata) || readNonEmptyString(metadata.legacyProjectId);
+  const storageProjectId = legacyProjectId || topicId;
+  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;
+  return {
+    ...metadata,
+    _id: outwardId,
+    projectId: outwardId,
+    topicId,
+    storageProjectId,
+    legacyProjectId,
+    name: readNonEmptyString(topic.name) || "Untitled Theme",
+    type: mapProjectType(topic, metadata),
+    description: readNonEmptyString(topic.description),
+    ownerId: readNonEmptyString(metadata.ownerId) || readNonEmptyString(topic.createdBy) || "system",
+    sharedWith: readStringArray(metadata.sharedWith),
+    visibility,
+    tenantId: readNonEmptyString(topic.tenantId) || readNonEmptyString(metadata.tenantId),
+    workspaceId: readNonEmptyString(topic.workspaceId) || readNonEmptyString(metadata.workspaceId),
+    status,
+    tags: readStringArray(metadata.tags),
+    chatCount: typeof metadata.chatCount === "number" ? metadata.chatCount : 0,
+    artifactCount: typeof metadata.artifactCount === "number" ? metadata.artifactCount : 0,
+    lastActivityAt: typeof metadata.lastActivityAt === "number" ? metadata.lastActivityAt : updatedAt,
+    _creationTime: typeof topic._creationTime === "number" ? topic._creationTime : createdAt,
+    createdAt,
+    updatedAt
+  };
+}
+async function resolveTopicProjectOverlay(ctx, scopeId, options = {}) {
+  const topic = await resolveTopicDoc(ctx, scopeId);
+  if (!topic) {
+    return null;
+  }
+  if (options.projectLikeOnly !== false && !isProjectLikeTopic(topic)) {
+    return null;
+  }
+  return materializeTopicProjectOverlay(topic, options.idMode);
+}
+async function listTopicProjectOverlays(ctx, options = {}) {
+  let allTopics = [];
+  if (ctx?.db?.query && typeof ctx.db.query === "function") {
+    try {
+      allTopics = await ctx.db.query("topics").collect();
+    } catch {
+      allTopics = [];
+    }
+  }
+  if (allTopics.length === 0 && typeof ctx.runQuery === "function") {
+    allTopics = (await ctx.runQuery(api.topics.list, {}) ?? []) || [];
+  }
+  return allTopics.filter(
+    (topic) => options.projectLikeOnly === false || isProjectLikeTopic(topic)
+  ).map((topic) => materializeTopicProjectOverlay(topic, options.idMode));
+}
+
+// ../access-control/src/projectGrantsBridge.ts
+var PROJECT_GRANT_STATUSES = ["active", "revoked", "expired"];
+function normalizeString(value) {
+  if (typeof value !== "string") {
+    return;
+  }
+  const trimmed = value.trim();
+  return trimmed.length > 0 ? trimmed : void 0;
+}
+async function resolveGrantScopeIds(ctx, args) {
+  const topicId = normalizeString(args.topicId);
+  const projectId = normalizeString(args.projectId);
+  for (const scopeId of [topicId, projectId]) {
+    if (!scopeId) {
+      continue;
+    }
+    try {
+      const overlay = await resolveTopicProjectOverlay(ctx, scopeId, {
+        idMode: "legacy",
+        projectLikeOnly: false
+      });
+      if (overlay) {
+        return {
+          topicId: normalizeString(overlay.topicId) ?? topicId,
+          projectId: normalizeString(overlay.projectId) ?? projectId ?? scopeId
+        };
+      }
+    } catch {
+    }
+  }
+  return { topicId, projectId };
+}
+async function normalizeProjectGrantRow(ctx, row) {
+  const scope = await resolveGrantScopeIds(ctx, {
+    topicId: row.topicId,
+    projectId: row.projectId
+  });
+  return {
+    ...row,
+    ...scope.topicId ? { topicId: scope.topicId } : {},
+    ...scope.projectId ?? scope.topicId ? { projectId: scope.projectId ?? scope.topicId } : {}
+  };
+}
+async function normalizeProjectGrantRows(ctx, rows) {
+  return await Promise.all(rows.map((row) => normalizeProjectGrantRow(ctx, row)));
+}
+async function listProjectGrantsByPrincipal(ctx, principalId) {
+  const rows = await Promise.all(
+    PROJECT_GRANT_STATUSES.map(
+      (status) => ctx.db.query("projectGrants").withIndex(
+        "by_principal_status",
+        (q) => q.eq("principalId", principalId).eq("status", status)
+      ).collect()
+    )
+  );
+  return await normalizeProjectGrantRows(ctx, rows.flat());
+}
+async function listProjectGrantsByGroup(ctx, groupId) {
+  const rows = await Promise.all(
+    PROJECT_GRANT_STATUSES.map(
+      (status) => ctx.db.query("projectGrants").withIndex(
+        "by_group_status",
+        (q) => q.eq("groupId", groupId).eq("status", status)
+      ).collect()
+    )
+  );
+  return await normalizeProjectGrantRows(ctx, rows.flat());
+}
+function buildScopeMatchers(inputScopeId, resolved) {
+  return new Set(
+    [inputScopeId, resolved.topicId, resolved.projectId].map((value) => normalizeString(value)).filter((value) => Boolean(value))
+  );
+}
+function matchesResolvedScope(row, scopeIds) {
+  const rowTopicId = normalizeString(row.topicId);
+  const rowProjectId = normalizeString(row.projectId);
+  return rowTopicId !== void 0 && scopeIds.has(rowTopicId) || rowProjectId !== void 0 && scopeIds.has(rowProjectId);
+}
+async function bridgeListProjectGrantsByTopicAndPrincipal(ctx, topicId, principalId) {
+  const resolved = await resolveGrantScopeIds(ctx, { topicId });
+  const scopeIds = buildScopeMatchers(topicId, resolved);
+  const rows = await listProjectGrantsByPrincipal(ctx, principalId);
+  return rows.filter((row) => matchesResolvedScope(row, scopeIds));
+}
+async function bridgeListProjectGrantsByTopicAndGroup(ctx, topicId, groupId) {
+  const resolved = await resolveGrantScopeIds(ctx, { topicId });
+  const scopeIds = buildScopeMatchers(topicId, resolved);
+  const rows = await listProjectGrantsByGroup(ctx, groupId);
+  return rows.filter((row) => matchesResolvedScope(row, scopeIds));
+}
+async function bridgeListProjectGrantsByPrincipalStatus(ctx, principalId, status) {
+  const rows = await listProjectGrantsByPrincipal(ctx, principalId);
+  return rows.filter((row) => row.status === status);
+}
+async function bridgeListProjectGrantsByGroupStatus(ctx, groupId, status) {
+  const rows = await listProjectGrantsByGroup(ctx, groupId);
+  return rows.filter((row) => row.status === status);
+}
+async function bridgeInsertProjectGrant(ctx, value) {
+  const resolved = await resolveGrantScopeIds(ctx, value);
+  return await ctx.db.insert("projectGrants", {
+    ...value,
+    ...resolved.topicId ? { topicId: resolved.topicId } : {},
+    ...resolved.projectId ?? resolved.topicId ? { projectId: resolved.projectId ?? resolved.topicId } : {}
+  });
+}
+
+// ../access-control/src/resolvers.ts
+async function findUserByClerkId(ctx, clerkId) {
+  const normalizedClerkId = clerkId.trim();
+  if (!normalizedClerkId) {
+    return null;
+  }
+  if (typeof ctx.runQuery === "function") {
+    try {
+      const bridgedUser = await ctx.runQuery(api.users.getUserByClerkId, {
+        clerkId: normalizedClerkId
+      });
+      if (bridgedUser) {
+        return bridgedUser;
+      }
+    } catch {
+    }
+  }
+  try {
+    const users = await ctx.db.query("users").collect();
+    return users.find((user) => String(user.clerkId ?? "") === normalizedClerkId) ?? null;
+  } catch {
+    return null;
+  }
+}
+async function findUserByPrincipalId(ctx, principalId) {
+  const normalizedPrincipalId = principalId.trim();
+  if (!normalizedPrincipalId) {
+    return null;
+  }
+  try {
+    const users = await ctx.db.query("users").collect();
+    return users.find(
+      (user) => String(user.defaultPrincipalId ?? "") === normalizedPrincipalId
+    ) ?? null;
+  } catch {
+    return null;
+  }
+}
+async function findAgentByPrincipalId(ctx, principalId) {
+  const normalizedPrincipalId = principalId.trim();
+  if (!normalizedPrincipalId) {
+    return null;
+  }
+  if (typeof ctx.runQuery === "function") {
+    try {
+      const bridgedAgent = await ctx.runQuery(
+        api.agents.getAgentByPrincipalId,
+        {
+          principalId: normalizedPrincipalId
+        }
+      );
+      if (bridgedAgent) {
+        return bridgedAgent;
+      }
+    } catch {
+    }
+  }
+  try {
+    const agents = await ctx.db.query("agents").collect();
+    return agents.find(
+      (agent) => String(agent.principalId ?? "") === normalizedPrincipalId
+    ) ?? null;
+  } catch {
+    return null;
+  }
+}
+function defaultResolvers() {
+  return {
+    async getProject(ctx, topicId) {
+      return await resolveTopicProjectOverlay(ctx, topicId, {
+        idMode: "legacy",
+        projectLikeOnly: false
+      });
+    },
+    async listTopics(ctx) {
+      return await listTopicProjectOverlays(ctx, { idMode: "legacy" });
+    },
+    async listTopicsByOwner(ctx, ownerId) {
+      const topics = await listTopicProjectOverlays(ctx, { idMode: "legacy" });
+      return topics.filter((topic) => topic.ownerId === ownerId);
+    },
+    async listTopicsByVisibility(ctx, visibility) {
+      const topics = await listTopicProjectOverlays(ctx, { idMode: "legacy" });
+      return topics.filter((topic) => topic.visibility === visibility);
+    },
+    async listProjectGrantsByProjectAndPrincipal(ctx, topicId, principalId) {
+      return await bridgeListProjectGrantsByTopicAndPrincipal(
+        ctx,
+        topicId,
+        principalId
+      );
+    },
+    async listProjectGrantsByProjectAndGroup(ctx, topicId, groupId) {
+      return await bridgeListProjectGrantsByTopicAndGroup(ctx, topicId, groupId);
+    },
+    async listProjectGrantsByPrincipalStatus(ctx, principalId, status) {
+      return await bridgeListProjectGrantsByPrincipalStatus(
+        ctx,
+        principalId,
+        status
+      );
+    },
+    async listProjectGrantsByGroupStatus(ctx, groupId, status) {
+      return await bridgeListProjectGrantsByGroupStatus(ctx, groupId, status);
+    },
+    async insertProjectGrant(ctx, value) {
+      return await bridgeInsertProjectGrant(ctx, value);
+    },
+    async getAgentByPrincipalId(ctx, principalId) {
+      return await findAgentByPrincipalId(ctx, principalId);
+    },
+    async getUserByClerkId(ctx, clerkId) {
+      return await findUserByClerkId(ctx, clerkId);
+    },
+    async getUserByPrincipalId(ctx, principalId) {
+      return await findUserByPrincipalId(ctx, principalId);
+    }
+  };
+}
+var resolverOverrides = {};
+function resolveAccessControlAppResolvers(_ctx) {
+  return {
+    ...defaultResolvers(),
+    ...resolverOverrides
+  };
+}
+
+// ../access-control/src/principalContext.ts
+function requireCanonicalResolvedUser(user, clerkId) {
+  const resolved = user;
+  if (!resolved) {
+    throw new Error(
+      `[AccessControl] Canonical user identity required for ${clerkId}. Sync users.upsertUser before user-bound access checks.`
+    );
+  }
+  const { mcRole, defaultTenantId, defaultWorkspaceId, defaultPrincipalId } = resolved;
+  if (mcRole !== "platform_admin" && mcRole !== "tenant_admin" && mcRole !== "workspace_admin" && mcRole !== "editor" && mcRole !== "viewer" && mcRole !== "auditor" && mcRole !== "service_agent") {
+    throw new Error(
+      `[AccessControl] Canonical MC role required for ${clerkId}. Re-sync Master Control identity before user-bound access checks.`
+    );
+  }
+  if (typeof defaultTenantId !== "string" || defaultTenantId.trim().length === 0) {
+    throw new Error(
+      `[AccessControl] Canonical home tenant required for ${clerkId}. Re-sync Master Control identity before user-bound access checks.`
+    );
+  }
+  if (typeof defaultWorkspaceId !== "string" || defaultWorkspaceId.trim().length === 0) {
+    throw new Error(
+      `[AccessControl] Canonical home workspace required for ${clerkId}. Re-sync Master Control identity before user-bound access checks.`
+    );
+  }
+  if (typeof defaultPrincipalId !== "string" || defaultPrincipalId.trim().length === 0) {
+    throw new Error(
+      `[AccessControl] Canonical federated principal required for ${clerkId}. Re-sync Master Control identity before user-bound access checks.`
+    );
+  }
+  return {
+    mcRole,
+    defaultTenantId: defaultTenantId.trim(),
+    defaultWorkspaceId: defaultWorkspaceId.trim(),
+    defaultPrincipalId: defaultPrincipalId.trim()
+  };
+}
+function isPrincipalIdInput(value) {
+  return value.startsWith("user:") || value.startsWith("group:") || value.startsWith("service:") || value.startsWith("agent:") || value.startsWith("external_viewer:");
+}
+async function resolveCanonicalUserRecord(ctx, actorId) {
+  const normalizedActorId = actorId.trim();
+  const clerkId = isPrincipalIdInput(normalizedActorId) && normalizedActorId.startsWith("user:") ? normalizedActorId.slice("user:".length) : normalizedActorId;
+  const resolvers = resolveAccessControlAppResolvers();
+  const resolvedByClerkId = await resolvers.getUserByClerkId(ctx, clerkId);
+  if (resolvedByClerkId) {
+    return {
+      resolvedUser: resolvedByClerkId,
+      clerkId,
+      contextClerkId: clerkId
+    };
+  }
+  const resolvedByPrincipalId = await resolvers.getUserByPrincipalId(
+    ctx,
+    normalizedActorId
+  );
+  return {
+    resolvedUser: resolvedByPrincipalId ?? null,
+    clerkId,
+    contextClerkId: normalizedActorId.startsWith("user:") && clerkId.length > 0 ? clerkId : normalizedActorId
+  };
+}
+function uniqRoles(roles) {
+  const roleSet = /* @__PURE__ */ new Set();
+  for (const role of roles) {
+    if (role === "platform_admin" || role === "tenant_admin" || role === "workspace_admin" || role === "editor" || role === "viewer" || role === "auditor" || role === "service_agent") {
+      roleSet.add(role);
+    }
+  }
+  return [...roleSet];
+}
+function normalizeGroupIds(value) {
+  if (!Array.isArray(value)) {
+    return [];
+  }
+  return [...new Set(
+    value.filter((entry) => typeof entry === "string").map((entry) => entry.trim()).filter(Boolean)
+  )];
+}
+function requireServiceAgentUser(user, actorId) {
+  const canonicalUser = requireCanonicalResolvedUser(user, actorId);
+  if (canonicalUser.mcRole !== "service_agent") {
+    throw new Error(
+      `[AccessControl] Canonical service_agent identity required for ${actorId}. Sync users.upsertUser before agent-bound access checks.`
+    );
+  }
+  return canonicalUser;
+}
+function requireCanonicalResolvedAgent(agent, actorId) {
+  const resolved = agent;
+  if (!resolved) {
+    throw new Error(
+      `[AccessControl] Agent "${actorId}" not found in agents or users table.`
+    );
+  }
+  if (typeof resolved.principalId !== "string" || resolved.principalId.trim().length === 0) {
+    throw new Error(
+      `[AccessControl] Canonical agent principalId required for ${actorId}.`
+    );
+  }
+  if (typeof resolved.tenantId !== "string" || resolved.tenantId.trim().length === 0) {
+    throw new Error(
+      `[AccessControl] Canonical home tenant required for ${actorId}.`
+    );
+  }
+  if (typeof resolved.workspaceId !== "string" || resolved.workspaceId.trim().length === 0) {
+    throw new Error(
+      `[AccessControl] Canonical home workspace required for ${actorId}.`
+    );
+  }
+  return {
+    principalId: resolved.principalId.trim(),
+    tenantId: resolved.tenantId.trim(),
+    workspaceId: resolved.workspaceId.trim(),
+    roles: uniqRoles(Array.isArray(resolved.roles) ? resolved.roles : []) ?? ["service_agent"],
+    groupIds: normalizeGroupIds(resolved.groupIds)
+  };
+}
+async function resolvePrincipalContext(ctx, actorId) {
+  if (actorId.startsWith("agent:")) {
+    const resolvers = resolveAccessControlAppResolvers();
+    const resolvedAgent = await resolvers.getAgentByPrincipalId(ctx, actorId);
+    if (resolvedAgent) {
+      const agent = requireCanonicalResolvedAgent(
+        resolvedAgent,
+        actorId
+      );
+      return {
+        principalId: agent.principalId,
+        principalType: "service",
+        clerkId: actorId,
+        tenantId: agent.tenantId,
+        workspaceId: agent.workspaceId,
+        roles: agent.roles.length > 0 ? agent.roles : ["service_agent"],
+        groupIds: agent.groupIds,
+        isPlatformAdmin: false,
+        isTenantAdmin: false,
+        isWorkspaceAdmin: false,
+        isSystemFallback: false
+      };
+    }
+    const resolvedUser2 = await resolvers.getUserByClerkId(
+      ctx,
+      actorId
+    );
+    if (!resolvedUser2) {
+      throw new Error(
+        `[AccessControl] Agent "${actorId}" not found in agents or users table.`
+      );
+    }
+    const user2 = requireServiceAgentUser(
+      resolvedUser2,
+      actorId
+    );
+    console.warn(
+      `[AccessControl] Deprecated legacy service-agent fallback for ${actorId}; migrate this principal into identity.agents.`
+    );
+    return {
+      principalId: user2.defaultPrincipalId,
+      principalType: "service",
+      clerkId: actorId,
+      tenantId: user2.defaultTenantId,
+      workspaceId: user2.defaultWorkspaceId,
+      roles: ["service_agent"],
+      groupIds: normalizeGroupIds(resolvedUser2?.principalGroupIds),
+      isPlatformAdmin: false,
+      isTenantAdmin: false,
+      isWorkspaceAdmin: false,
+      isSystemFallback: false
+    };
+  }
+  const {
+    resolvedUser,
+    contextClerkId
+  } = await resolveCanonicalUserRecord(ctx, actorId);
+  const user = requireCanonicalResolvedUser(
+    resolvedUser,
+    contextClerkId
+  );
+  if (!user.defaultPrincipalId) {
+    throw new Error(
+      `[AccessControl] Canonical federated principal required for ${contextClerkId}. Re-sync Master Control identity before user-bound access checks.`
+    );
+  }
+  if (user.mcRole === "service_agent") {
+    return {
+      principalId: user.defaultPrincipalId,
+      principalType: "service",
+      clerkId: contextClerkId,
+      tenantId: user.defaultTenantId,
+      workspaceId: user.defaultWorkspaceId,
+      roles: ["service_agent"],
+      groupIds: normalizeGroupIds(resolvedUser?.principalGroupIds),
+      isPlatformAdmin: false,
+      isTenantAdmin: false,
+      isWorkspaceAdmin: false,
+      isSystemFallback: false
+    };
+  }
+  const principalId = user.defaultPrincipalId;
+  const effectiveRole = user.mcRole;
+  const roles = effectiveRole === "platform_admin" ? ["platform_admin", "tenant_admin"] : effectiveRole === "tenant_admin" ? ["tenant_admin"] : [effectiveRole];
+  const tenantId = user.defaultTenantId;
+  const workspaceId = user.defaultWorkspaceId;
+  const isPlatformAdmin = effectiveRole === "platform_admin";
+  return {
+    principalId,
+    principalType: "user",
+    clerkId: contextClerkId,
+    tenantId,
+    workspaceId,
+    roles: uniqRoles(roles),
+    groupIds: normalizeGroupIds(resolvedUser?.principalGroupIds),
+    isPlatformAdmin,
+    isTenantAdmin: isPlatformAdmin || effectiveRole === "tenant_admin",
+    isWorkspaceAdmin: isPlatformAdmin || effectiveRole === "tenant_admin" || effectiveRole === "workspace_admin",
+    isSystemFallback: false
+  };
+}
+
+// ../access-control/src/access.ts
+function isTopicInPrincipalTenant(topic, principalTenantId) {
+  if (!topic.tenantId) {
+    return false;
+  }
+  if (!principalTenantId) {
+    return false;
+  }
+  return String(topic.tenantId) === String(principalTenantId);
+}
+function isTopicInPrincipalWorkspace(topic, principalWorkspaceId) {
+  if (!topic.workspaceId) {
+    return false;
+  }
+  if (!principalWorkspaceId) {
+    return false;
+  }
+  return String(topic.workspaceId) === String(principalWorkspaceId);
+}
+function isLegacyUnscopedTopic(topic) {
+  return !topic.tenantId || !topic.workspaceId;
+}
+function isGrantScopeAlignedToTopic(topic, grant) {
+  if (topic.tenantId && grant.tenantId && String(topic.tenantId) !== String(grant.tenantId)) {
+    return false;
+  }
+  if (topic.workspaceId && grant.workspaceId && String(topic.workspaceId) !== String(grant.workspaceId)) {
+    return false;
+  }
+  return true;
+}
+function isGrantSourceAllowedForVisibility(visibility, source) {
+  if (source !== "external_share") {
+    return true;
+  }
+  return visibility === "external" || visibility === "public";
+}
+function isGrantActive(grant) {
+  if (grant.status !== "active") {
+    return false;
+  }
+  if (grant.expiresAt !== void 0 && grant.expiresAt <= Date.now()) {
+    return false;
+  }
+  return true;
+}
+async function hasPrincipalGrant(ctx, args) {
+  const grants = await resolveAccessControlAppResolvers().listProjectGrantsByProjectAndPrincipal(
+    ctx,
+    args.topic._id,
+    args.principalId
+  );
+  if (grants.some(
+    (grant) => isGrantActive(grant) && isGrantScopeAlignedToTopic(args.topic, grant) && isGrantSourceAllowedForVisibility(
+      args.topic.visibility,
+      grant.source
+    ) && (!args.principalIsExternal || args.topic.visibility === "public" || grant.source === "external_share")
+  )) {
+    return true;
+  }
+  return false;
+}
+async function hasGroupGrant(ctx, args) {
+  if (args.groupIds.length === 0) {
+    return false;
+  }
+  for (const groupId of args.groupIds) {
+    const grants = await resolveAccessControlAppResolvers().listProjectGrantsByProjectAndGroup(ctx, args.topic._id, groupId);
+    if (grants.some(
+      (grant) => isGrantActive(grant) && isGrantScopeAlignedToTopic(args.topic, grant) && isGrantSourceAllowedForVisibility(
+        args.topic.visibility,
+        grant.source
+      )
+    )) {
+      return true;
+    }
+  }
+  return false;
+}
+function isExternalPrincipal(_ctx, _args) {
+  return false;
+}
+async function evaluateTopicAccessDetailed(ctx, args) {
+  if (args.legacyUserId) {
+    return {
+      hasAccess: true,
+      isAdmin: false,
+      isOwner: false,
+      isShared: false,
+      hasGrant: true,
+      isFirmVisible: true,
+      isExternalVisible: false,
+      isPublicVisible: false,
+      isTenantScopeMatch: true,
+      isWorkspaceScopeMatch: true,
+      isPrincipalExternal: false
+    };
+  }
+  const topic = await resolveAccessControlAppResolvers().getProject(
+    ctx,
+    args.topicId
+  );
+  if (!topic) {
+    return {
+      hasAccess: false,
+      isAdmin: false,
+      isOwner: false,
+      isShared: false,
+      hasGrant: false,
+      isFirmVisible: false,
+      isExternalVisible: false,
+      isPublicVisible: false,
+      isTenantScopeMatch: false,
+      isWorkspaceScopeMatch: false,
+      isPrincipalExternal: false
+    };
+  }
+  const { principalContext, legacyUserId } = args;
+  const userIsAdmin = principalContext.isPlatformAdmin;
+  const isOwner = topic.ownerId === legacyUserId;
+  const isShared = (topic.sharedWith ?? []).includes(legacyUserId);
+  const principalIsExternal = await isExternalPrincipal(ctx, {
+    groupIds: principalContext.groupIds,
+    topicTenantId: topic.tenantId,
+    topicWorkspaceId: topic.workspaceId
+  });
+  const hasPrincipalGrantResult = await hasPrincipalGrant(ctx, {
+    topic,
+    principalId: principalContext.principalId,
+    principalIsExternal
+  });
+  const hasGroupGrantResult = await hasGroupGrant(ctx, {
+    topic,
+    groupIds: principalContext.groupIds
+  });
+  const hasGrant = isShared || hasPrincipalGrantResult || hasGroupGrantResult;
+  const legacyUnscoped = isLegacyUnscopedTopic(topic);
+  const tenantScopeMatch = isTopicInPrincipalTenant(
+    topic,
+    principalContext.tenantId
+  );
+  const workspaceScopeMatch = isTopicInPrincipalWorkspace(
+    topic,
+    principalContext.workspaceId
+  );
+  const isPublicVisible = topic.visibility === "public";
+  const isFirmVisible = topic.visibility === "firm" && !legacyUnscoped && tenantScopeMatch && workspaceScopeMatch && !principalIsExternal;
+  const hasScopedGrant = hasGrant && (legacyUnscoped || tenantScopeMatch && workspaceScopeMatch);
+  const isExternalVisible = topic.visibility === "external" && hasScopedGrant;
+  const hasAccess = userIsAdmin || isOwner || hasScopedGrant || isPublicVisible || isFirmVisible;
+  return {
+    hasAccess,
+    isAdmin: userIsAdmin,
+    isOwner,
+    isShared,
+    hasGrant,
+    isFirmVisible,
+    isExternalVisible,
+    isPublicVisible,
+    isTenantScopeMatch: tenantScopeMatch,
+    isWorkspaceScopeMatch: workspaceScopeMatch,
+    isPrincipalExternal: principalIsExternal
+  };
+}
+async function checkTopicAccessDetailed(ctx, topicId, userId) {
+  const principalContext = await resolvePrincipalContext(ctx, userId);
+  return evaluateTopicAccessDetailed(ctx, {
+    topicId,
+    legacyUserId: userId,
+    principalContext
+  });
+}
+async function checkTopicAccess(ctx, topicId, userId) {
+  const result = await checkTopicAccessDetailed(ctx, topicId, userId);
+  return result.hasAccess;
+}
+var checkProjectAccess = checkTopicAccess;
+
+// ../access-control/src/auth.ts
+async function getCurrentUserId(ctx) {
+  const identity = await ctx.auth.getUserIdentity();
+  return identity?.subject ?? null;
+}
+var permissiveReturn = v.optional(v.any());
+var looseJsonObject = v.record(v.string(), v.any());
+var looseJsonArray = v.array(v.any());
+v.union(
+  v.string(),
+  v.number(),
+  v.boolean(),
+  v.null(),
+  looseJsonObject,
+  looseJsonArray
+);
+var api2 = anyApi;
+componentsGeneric();
+var internal = anyApi;
+var mutation = mutationGeneric;
+var query = queryGeneric;
+
+// src/entityValidation.ts
+async function getEntityTypeSchema(ctx, nodeType, tenantId) {
+  if (tenantId) {
+    const tenantEntry = 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 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;
+  }
+  return null;
+}
+async function validateEntityMetadata(ctx, nodeType, metadata, tenantId) {
+  const errors = [];
+  const schema = await getEntityTypeSchema(ctx, nodeType, tenantId);
+  if (!schema) {
+    return {
+      valid: false,
+      errors: [
+        `No registered schema for entity type "${nodeType}". Register it in schemaEnumConfig (category="entity_type") before creating entities of this type.`
+      ]
+    };
+  }
+  const meta = metadata || {};
+  for (const [fieldName, fieldDef] of Object.entries(schema)) {
+    if (fieldDef.required) {
+      const value = meta[fieldName];
+      if (value === void 0 || value === null || value === "") {
+        errors.push(`Required field "${fieldName}" is missing or empty`);
+      }
+    }
+  }
+  for (const [fieldName, value] of Object.entries(meta)) {
+    const fieldDef = schema[fieldName];
+    if (!fieldDef) {
+      continue;
+    }
+    if (value === void 0 || value === null) {
+      continue;
+    }
+    const actualType = typeof value;
+    if (actualType !== fieldDef.type) {
+      errors.push(
+        `Field "${fieldName}" expected type "${fieldDef.type}" but got "${actualType}"`
+      );
+    }
+  }
+  return {
+    valid: errors.length === 0,
+    errors
+  };
+}
+
+// src/globalId.ts
+function generateGlobalId() {
+  const bytes = new Uint8Array(16);
+  crypto.getRandomValues(bytes);
+  bytes[6] = bytes[6] & 15 | 64;
+  bytes[8] = bytes[8] & 63 | 128;
+  const hex = Array.from(bytes, (b) => b.toString(16).padStart(2, "0")).join(
+    ""
+  );
+  return `${hex.slice(0, 8)}-${hex.slice(8, 12)}-${hex.slice(12, 16)}-${hex.slice(16, 20)}-${hex.slice(20)}`;
+}
+
+// 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((v4) => v4.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);
+  }
+  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}.`
+  };
+}
+
+// src/topicProjectOverlay.ts
+var LEGACY_SCOPE_FIELD2 = "graphScopeProjectId";
+function readNonEmptyString2(value) {
+  if (typeof value !== "string") {
+    return;
+  }
+  const normalized = value.trim();
+  return normalized.length > 0 ? normalized : void 0;
+}
+function readStringArray2(value) {
+  if (!Array.isArray(value)) {
+    return [];
+  }
+  return value.map((entry) => readNonEmptyString2(entry)).filter((entry) => Boolean(entry));
+}
+function readMetadata2(topic) {
+  return topic.metadata && typeof topic.metadata === "object" ? topic.metadata : {};
+}
+function readLegacyProjectId2(value) {
+  if (!value) {
+    return;
+  }
+  return readNonEmptyString2(value[LEGACY_SCOPE_FIELD2]);
+}
+function coerceVisibility2(value) {
+  return value === "private" || value === "team" || value === "firm" || value === "external" || value === "public" ? value : void 0;
+}
+function coerceStatus2(value) {
+  return value === "active" || value === "archived" || value === "watching" ? value : void 0;
+}
+function mapProjectType2(topic, metadata) {
+  const explicit = readNonEmptyString2(metadata.projectType);
+  if (explicit) {
+    return explicit;
+  }
+  if (topic.type === "theme") {
+    return "thematic";
+  }
+  return readNonEmptyString2(topic.type) || "general";
+}
+function isProjectLikeTopic2(topic) {
+  const metadata = readMetadata2(topic);
+  return topic.type === "theme" || topic.type === "thematic" || topic.type === "deal" || topic.type === "monitoring" || readLegacyProjectId2(topic) !== void 0 || readNonEmptyString2(metadata.projectType) !== void 0;
+}
+function isMissingLucernChildComponentError(error) {
+  const message = error instanceof Error ? error.message : String(error);
+  return message.includes(
+    'Child component ComponentName(Identifier("lucern")) not found'
+  ) || message.includes("Child component") && message.includes("lucern") && message.includes("not found");
+}
+async function resolveTopicDoc2(ctx, scopeId) {
+  if (ctx?.db && typeof ctx.db.get === "function") {
+    try {
+      const directTopic = await ctx.db.get(scopeId);
+      if (directTopic) {
+        return directTopic;
+      }
+    } catch {
+    }
+  }
+  if (typeof ctx.runQuery !== "function") {
+    return null;
+  }
+  try {
+    const topic = await ctx.runQuery(api2.topics.get, {
+      id: String(scopeId)
+    });
+    if (topic?.name !== void 0 && topic?.type !== void 0) {
+      return topic;
+    }
+  } catch {
+  }
+  try {
+    const topic = await ctx.runQuery(api2.topics.getByLegacyScopeId, {
+      projectId: String(scopeId)
+    });
+    if (topic?.name !== void 0 && topic?.type !== void 0) {
+      return topic;
+    }
+  } catch {
+  }
+  return null;
+}
+function materializeTopicProjectOverlay2(topic, idMode = "legacy") {
+  const metadata = readMetadata2(topic);
+  const topicId = String(topic._id);
+  const legacyProjectId = readLegacyProjectId2(topic) || readLegacyProjectId2(metadata) || readNonEmptyString2(metadata.legacyProjectId);
+  const storageProjectId = legacyProjectId || topicId;
+  const outwardId = idMode === "topic" ? topicId : storageProjectId;
+  const visibility = coerceVisibility2(topic.visibility) || coerceVisibility2(metadata.visibility) || "private";
+  const status = coerceStatus2(topic.status) || coerceStatus2(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;
+  return {
+    ...metadata,
+    _id: outwardId,
+    projectId: outwardId,
+    topicId,
+    storageProjectId,
+    legacyProjectId,
+    name: readNonEmptyString2(topic.name) || "Untitled Theme",
+    type: mapProjectType2(topic, metadata),
+    description: readNonEmptyString2(topic.description),
+    ownerId: readNonEmptyString2(metadata.ownerId) || readNonEmptyString2(topic.createdBy) || "system",
+    sharedWith: readStringArray2(metadata.sharedWith),
+    visibility,
+    tenantId: readNonEmptyString2(topic.tenantId) || readNonEmptyString2(metadata.tenantId),
+    workspaceId: readNonEmptyString2(topic.workspaceId) || readNonEmptyString2(metadata.workspaceId),
+    status,
+    tags: readStringArray2(metadata.tags),
+    chatCount: typeof metadata.chatCount === "number" ? metadata.chatCount : 0,
+    artifactCount: typeof metadata.artifactCount === "number" ? metadata.artifactCount : 0,
+    lastActivityAt: typeof metadata.lastActivityAt === "number" ? metadata.lastActivityAt : updatedAt,
+    _creationTime: typeof topic._creationTime === "number" ? topic._creationTime : createdAt,
+    createdAt,
+    updatedAt
+  };
+}
+async function resolveTopicProjectOverlay2(ctx, scopeId, options = {}) {
+  const topic = await resolveTopicDoc2(ctx, scopeId);
+  if (!topic) {
+    return null;
+  }
+  if (options.projectLikeOnly !== false && !isProjectLikeTopic2(topic)) {
+    return null;
+  }
+  return materializeTopicProjectOverlay2(topic, options.idMode);
+}
+async function listTopicProjectOverlays2(ctx, options = {}) {
+  let allTopics = [];
+  if (ctx?.db?.query && typeof ctx.db.query === "function") {
+    try {
+      allTopics = await ctx.db.query("topics").collect();
+    } catch {
+      allTopics = [];
+    }
+  }
+  if (allTopics.length === 0 && typeof ctx.runQuery === "function") {
+    allTopics = (await ctx.runQuery(api2.topics.list, {}) ?? []) || [];
+  }
+  return allTopics.filter(
+    (topic) => options.projectLikeOnly === false || isProjectLikeTopic2(topic)
+  ).map((topic) => materializeTopicProjectOverlay2(topic, options.idMode));
+}
+async function patchTopicProjectOverlay(ctx, scopeId, value) {
+  const topic = await resolveTopicDoc2(ctx, scopeId);
+  if (!topic) {
+    return null;
+  }
+  const nextMetadata = { ...readMetadata2(topic) };
+  const patch = {};
+  const 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 = coerceStatus2(rawValue);
+        if (status) {
+          patch.status = status;
+          topicUpdateArgs.status = status;
+        }
+        break;
+      }
+      case "visibility": {
+        const visibility = coerceVisibility2(rawValue);
+        if (visibility) {
+          patch.visibility = visibility;
+          topicUpdateArgs.visibility = visibility;
+        }
+        break;
+      }
+      case "type": {
+        const projectType = readNonEmptyString2(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;
+        }
+    }
+  }
+  patch.updatedAt = Date.now();
+  patch.metadata = nextMetadata;
+  topicUpdateArgs.metadata = nextMetadata;
+  if (typeof ctx.runMutation === "function") {
+    try {
+      await ctx.runMutation(api2.topics.update, topicUpdateArgs);
+    } catch (error) {
+      if (!isMissingLucernChildComponentError(error) || !ctx?.db || typeof ctx.db.patch !== "function") {
+        throw error;
+      }
+      await ctx.db.patch(String(topic._id), patch);
+    }
+  } else if (ctx?.db && typeof ctx.db.patch === "function") {
+    await ctx.db.patch(String(topic._id), patch);
+  } else {
+    throw new Error(
+      "Cannot patch topic without component adapter (ctx.runMutation unavailable)"
+    );
+  }
+  return materializeTopicProjectOverlay2(
+    {
+      ...topic,
+      ...patch,
+      metadata: nextMetadata
+    }
+  );
+}
+
+// src/resolvers.ts
+function isMissingLucernChildComponentError2(error) {
+  const message = error instanceof Error ? error.message : String(error);
+  return message.includes('Child component ComponentName(Identifier("lucern")) not found') || message.includes("Child component") && message.includes("lucern") && message.includes("not found");
+}
+function isAdvisoryTopicPatch(value) {
+  const advisoryKeys = /* @__PURE__ */ new Set(["lastActivityAt", "updatedAt"]);
+  const keys = Object.keys(value);
+  return keys.length > 0 && keys.every((key) => advisoryKeys.has(key));
+}
+async function patchProjectWithTolerance(ctx, projectId, value) {
+  try {
+    await patchTopicProjectOverlay(ctx, projectId, value);
+  } catch (error) {
+    if (!isAdvisoryTopicPatch(value) || !isMissingLucernChildComponentError2(error)) {
+      throw error;
+    }
+    console.warn("[lucern graph-primitives] Non-fatal advisory topic patch failure", {
+      projectId,
+      keys: Object.keys(value),
+      error: error instanceof Error ? error.message : error
+    });
+  }
+}
+function defaultResolvers2() {
+  return {
+    async getProject(ctx, projectId) {
+      return await resolveTopicProjectOverlay2(ctx, projectId, {
+        idMode: "legacy",
+        projectLikeOnly: false
+      });
+    },
+    async patchProject(ctx, projectId, value) {
+      await patchProjectWithTolerance(ctx, projectId, value);
+    },
+    async listTopics(ctx) {
+      return await listTopicProjectOverlays2(ctx, {
+        idMode: "legacy"
+      });
+    },
+    async getFinalArtifact(ctx, artifactId) {
+      return await ctx.db.get(artifactId);
+    }
+  };
+}
+var resolverOverrides2 = {};
+function resolveGraphPrimitivesAppResolvers(_ctx) {
+  return {
+    ...defaultResolvers2(),
+    ...resolverOverrides2
+  };
+}
+var LEGACY_SCOPE_FIELD3 = "graphScopeProjectId";
+function asMappedProjectId(topic) {
+  if (!topic) {
+    return;
+  }
+  const directLegacyProjectId = normalizeScopeValue(topic[LEGACY_SCOPE_FIELD3]);
+  if (directLegacyProjectId) {
+    return directLegacyProjectId;
+  }
+  const metadata = topic.metadata || {};
+  const candidate = metadata[LEGACY_SCOPE_FIELD3] || metadata.legacyProjectId || metadata.projectId || metadata.scopeProjectId;
+  return candidate ? candidate : void 0;
+}
+function normalizeScopeValue(value) {
+  if (typeof value !== "string") {
+    return;
+  }
+  const normalized = value.trim();
+  return normalized.length > 0 ? normalized : void 0;
+}
+function pickPrimaryTopic(candidates) {
+  return [...candidates].sort((a, b) => {
+    const depthA = a.depth ?? 9999;
+    const depthB = b.depth ?? 9999;
+    if (depthA !== depthB) {
+      return depthA - depthB;
+    }
+    const createdA = a.createdAt ?? Number.MAX_SAFE_INTEGER;
+    const createdB = b.createdAt ?? Number.MAX_SAFE_INTEGER;
+    if (createdA !== createdB) {
+      return createdA - createdB;
+    }
+    return String(a.name || "").localeCompare(String(b.name || ""));
+  })[0];
+}
+async function findTopicsByScopeAlias(ctx, scopeId) {
+  try {
+    return await ctx.db.query("topics").withIndex(
+      "by_graph_scope_project",
+      (q) => q.eq(LEGACY_SCOPE_FIELD3, scopeId)
+    ).collect();
+  } catch {
+    const topics = await ctx.db.query("topics").collect();
+    return topics.filter((topic) => {
+      const normalizedGlobalId = normalizeScopeValue(topic.globalId);
+      const mappedProjectId = asMappedProjectId(topic);
+      return String(topic._id) === scopeId || normalizedGlobalId === scopeId || mappedProjectId === scopeId;
+    });
+  }
+}
+async function tryResolveHostTopicById(ctx, topicId) {
+  if (typeof ctx.runQuery !== "function") {
+    return null;
+  }
+  try {
+    return await ctx.runQuery(api2.topics.get, {
+      id: topicId
+    }) ?? null;
+  } catch {
+    return null;
+  }
+}
+async function tryResolveHostTopicByLegacyScope(ctx, legacyScopeId) {
+  if (typeof ctx.runQuery !== "function") {
+    return null;
+  }
+  try {
+    return await ctx.runQuery(api2.topics.getByLegacyScopeId, {
+      projectId: legacyScopeId
+    }) ?? null;
+  } catch {
+    return null;
+  }
+}
+async function resolveInheritedWorkspaceScope(ctx, topic) {
+  const MAX_DEPTH = 10;
+  let tenantId = normalizeScopeValue(topic.tenantId);
+  let workspaceId = normalizeScopeValue(topic.workspaceId);
+  if (tenantId && workspaceId) {
+    return { tenantId, workspaceId };
+  }
+  let current = topic;
+  for (let i = 0; i < MAX_DEPTH && current?.parentTopicId; i++) {
+    current = await ctx.db.get(current.parentTopicId);
+    if (!current) break;
+    if (!tenantId) {
+      tenantId = normalizeScopeValue(current.tenantId);
+    }
+    if (!workspaceId) {
+      workspaceId = normalizeScopeValue(current.workspaceId);
+    }
+    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 {
+    }
+    if (!topic) {
+      topic = await tryResolveHostTopicById(ctx, String(args.topicId));
+    }
+    if (!topic) {
+      topic = pickPrimaryTopic(
+        await findTopicsByScopeAlias(ctx, String(args.topicId))
+      ) ?? null;
+    }
+    if (!topic) {
+      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"
+    };
+  }
+  if (args.projectId) {
+    let directTopic = null;
+    try {
+      directTopic = await ctx.db.get(
+        args.projectId
+      );
+    } catch {
+    }
+    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"
+      };
+    }
+    throw new Error(
+      `Legacy project scope ${String(args.projectId)} has no mapped topic.`
+    );
+  }
+  throw new Error(
+    "Missing scope: provide topicId (preferred) or legacy projectId alias."
+  );
+}
+var optionalScopeArgs = {
+  projectId: v.optional(v.string()),
+  topicId: v.optional(v.string())
+};
+
+// src/entityLifecycle.ts
+function throwStructuredMutationError(args) {
+  const error = new Error(args.message);
+  error.status = args.status;
+  error.code = args.code;
+  error.invariantCode = args.invariantCode;
+  error.suggestion = args.suggestion;
+  error.details = args.details;
+  throw error;
+}
+async function requireAuthenticatedUserId(ctx) {
+  const userId = await getCurrentUserId(ctx);
+  if (!userId) {
+    throwStructuredMutationError({
+      message: "Authentication required.",
+      status: 401,
+      code: "AUTHENTICATION_REQUIRED",
+      invariantCode: "auth.required",
+      suggestion: "Provide a valid bearer token before invoking entity mutations."
+    });
+  }
+  return userId;
+}
+async function requireProjectWriteAccess(ctx, projectId, userId) {
+  const hasAccess = await checkProjectAccess(ctx, projectId, userId);
+  if (!hasAccess) {
+    throwStructuredMutationError({
+      message: "Project access required.",
+      status: 403,
+      code: "FORBIDDEN",
+      invariantCode: "policy.scope_required",
+      suggestion: "Request write access for the project and retry.",
+      details: { projectId, userId }
+    });
+  }
+}
+function generateContentHash(nodeType, text) {
+  const content = `${nodeType}:${text.trim().toLowerCase().replace(/\s+/g, " ")}`;
+  let hash = 5381;
+  for (let i = 0; i < content.length; i++) {
+    hash = (hash << 5) + hash + content.charCodeAt(i);
+    hash &= hash;
+  }
+  return Math.abs(hash).toString(16).padStart(8, "0");
+}
+var ONTOLOGICAL_NODE_TYPES = [
+  "company",
+  "person",
+  "investor",
+  "function",
+  "value_chain"
+];
+function isOntologicalNodeType(nodeType) {
+  return ONTOLOGICAL_NODE_TYPES.includes(nodeType);
+}
+function normalizeCanonicalEntityText(value) {
+  return value.trim().toLowerCase().replace(/\s+/g, " ");
+}
+function buildEntityTitle(canonicalText) {
+  return canonicalText.slice(0, 100) + (canonicalText.length > 100 ? "..." : "");
+}
+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;
+  return {
+    ...scope,
+    tenantId,
+    topic,
+    project
+  };
+}
+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";
+}
+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();
+  return candidates.find(
+    (node) => matchesCanonicalEntityRecord(node, {
+      nodeType: args.nodeType,
+      tenantId: args.tenantId,
+      contentHash
+    })
+  ) ?? 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();
+  const normalizedSearch = typeof args.searchTerm === "string" && args.searchTerm.trim().length > 0 ? normalizeCanonicalEntityText(args.searchTerm) : void 0;
+  return baseRows.filter(
+    (node) => matchesCanonicalEntityRecord(node, {
+      nodeType: args.nodeType,
+      tenantId: args.tenantId,
+      includeArchived: args.includeArchived
+    })
+  ).filter((node) => {
+    if (!normalizedSearch) {
+      return true;
+    }
+    const text = typeof node.canonicalText === "string" ? node.canonicalText : "";
+    return normalizeCanonicalEntityText(text).includes(normalizedSearch);
+  }).sort(
+    (a, b) => String(a.title ?? a.canonicalText ?? "").localeCompare(
+      String(b.title ?? b.canonicalText ?? "")
+    )
+  ).slice(0, args.limit);
+}
+var entityVerificationStatusValidator = v.union(
+  v.literal("unverified"),
+  v.literal("human_verified"),
+  v.literal("ai_verified"),
+  v.literal("contradicted"),
+  v.literal("outdated")
+);
+var listCanonicalEntities = query({
+  args: {
+    topicId: v.optional(v.string()),
+    scopeProjectId: v.optional(v.string()),
+    nodeType: v.optional(v.string()),
+    searchTerm: v.optional(v.string()),
+    includeArchived: v.optional(v.boolean()),
+    limit: v.optional(v.number())
+  },
+  returns: permissiveReturn,
+  handler: async (ctx, args) => {
+    const scope = await resolveCanonicalEntityScope(ctx, {
+      topicId: args.topicId,
+      projectId: args.scopeProjectId
+    });
+    const limit = Math.max(1, Math.min(Math.floor(args.limit ?? 100), 500));
+    return listCanonicalEntitiesForScope(ctx, {
+      tenantId: scope.tenantId,
+      nodeType: args.nodeType,
+      searchTerm: args.searchTerm,
+      includeArchived: args.includeArchived,
+      limit
+    });
+  }
+});
+var createEntity = mutation({
+  args: {
+    nodeType: v.string(),
+    // "company", "person", "investor", "function", "value_chain"
+    canonicalText: v.string(),
+    // Display name (e.g., "Anthropic", "Dario Amodei")
+    metadata: v.optional(v.any()),
+    // Type-specific attributes validated against schema
+    subtype: v.optional(v.string()),
+    // e.g., "company/private", "investor/vc"
+    ...optionalScopeArgs
+  },
+  returns: permissiveReturn,
+  handler: async (ctx, args) => {
+    const authenticatedUserId = await requireAuthenticatedUserId(ctx);
+    const now = Date.now();
+    const canonicalText = args.canonicalText.trim();
+    if (!canonicalText) {
+      throwStructuredMutationError({
+        message: "canonicalText is required.",
+        status: 400,
+        code: "INVALID_REQUEST",
+        invariantCode: "entity.type_check"
+      });
+    }
+    if (!isOntologicalNodeType(args.nodeType)) {
+      throwStructuredMutationError({
+        message: `"${args.nodeType}" is not an ontological entity type. Use epistemicBeliefs.create for epistemic nodes.`,
+        status: 400,
+        code: "INVALID_NODE_TYPE",
+        invariantCode: "entity.type_check",
+        suggestion: `Valid entity types: ${ONTOLOGICAL_NODE_TYPES.join(", ")}`
+      });
+    }
+    const scope = await resolveCanonicalEntityScope(ctx, {
+      topicId: args.topicId,
+      projectId: args.projectId
+    });
+    if (scope.projectId) {
+      await requireProjectWriteAccess(
+        ctx,
+        scope.projectId,
+        authenticatedUserId
+      );
+    }
+    if (scope.topicId) {
+      const ontologyValidation = await validateEntityTypeForTopic(
+        ctx,
+        scope.topicId,
+        args.nodeType
+      );
+      if (!ontologyValidation.valid) {
+        throwStructuredMutationError({
+          message: `Ontology validation failed: ${ontologyValidation.error}`,
+          status: 400,
+          code: "ONTOLOGY_VALIDATION_ERROR",
+          invariantCode: "entity.ontology_type_check",
+          suggestion: "Use a nodeType that is defined in the ontology bound to this topic, or update the ontology to include this entity type.",
+          details: { nodeType: args.nodeType, topicId: scope.topicId }
+        });
+      }
+    }
+    const metadata = args.metadata || {};
+    const validation = await validateEntityMetadata(
+      ctx,
+      args.nodeType,
+      metadata,
+      scope.tenantId
+    );
+    if (!validation.valid) {
+      throwStructuredMutationError({
+        message: `Entity metadata validation failed: ${validation.errors.join("; ")}`,
+        status: 400,
+        code: "VALIDATION_ERROR",
+        invariantCode: "entity.metadata_schema",
+        suggestion: "Check the registered schema for this entity type in schemaEnumConfig.",
+        details: { errors: validation.errors }
+      });
+    }
+    const existing = await findExistingCanonicalEntity(ctx, {
+      nodeType: args.nodeType,
+      canonicalText,
+      tenantId: scope.tenantId
+    });
+    if (existing) {
+      return {
+        nodeId: existing._id,
+        globalId: existing.globalId,
+        isDuplicate: true
+      };
+    }
+    const entityGlobalId = generateGlobalId();
+    const nodeId = await ctx.db.insert("epistemicNodes", {
+      globalId: entityGlobalId,
+      nodeType: args.nodeType,
+      epistemicLayer: "ontological",
+      subtype: args.subtype,
+      canonicalText,
+      contentHash: generateContentHash(args.nodeType, canonicalText),
+      title: buildEntityTitle(canonicalText),
+      metadata: {
+        ...metadata,
+        ...args.subtype ? { subtype: args.subtype } : {},
+        status: "active"
+      },
+      tenantId: scope.tenantId,
+      sourceType: "human",
+      verificationStatus: "unverified",
+      status: "active",
+      projectId: scope.projectId,
+      createdBy: authenticatedUserId,
+      createdAt: now,
+      updatedAt: now
+    });
+    await ctx.scheduler.runAfter(0, internal.neo4jSync.syncNodeToNeo4j, {
+      nodeId,
+      operation: "upsert"
+    });
+    await ctx.db.insert("epistemicAudit", {
+      entityType: "entity",
+      entityId: nodeId,
+      changeType: "created",
+      changedAt: now,
+      changedBy: authenticatedUserId,
+      isAgent: false,
+      previousState: null,
+      newState: {
+        canonicalText,
+        nodeType: args.nodeType,
+        tenantId: scope.tenantId,
+        workspaceId: null
+      },
+      projectId: scope.projectId
+    });
+    return { nodeId, globalId: entityGlobalId, isDuplicate: false };
+  }
+});
+var updateEntityAttributes = mutation({
+  args: {
+    nodeId: v.id("epistemicNodes"),
+    canonicalText: v.optional(v.string()),
+    title: v.optional(v.string()),
+    metadata: v.optional(v.any()),
+    // Partial metadata to merge
+    subtype: v.optional(v.string()),
+    domain: v.optional(v.string()),
+    tags: v.optional(v.array(v.string())),
+    verificationStatus: v.optional(entityVerificationStatusValidator),
+    externalIds: v.optional(
+      v.object({
+        crunchbase: v.optional(v.string()),
+        linkedin: v.optional(v.string()),
+        pitchbook: v.optional(v.string()),
+        twitter: v.optional(v.string()),
+        website: v.optional(v.string())
+      })
+    )
+  },
+  returns: permissiveReturn,
+  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) {
+      await requireProjectWriteAccess(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;
+    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
+          }
+        });
+      }
+    }
+    const validation = await validateEntityMetadata(
+      ctx,
+      node.nodeType,
+      mergedMetadata,
+      typeof node.tenantId === "string" ? node.tenantId : void 0
+    );
+    if (!validation.valid) {
+      throwStructuredMutationError({
+        message: `Entity metadata validation failed: ${validation.errors.join("; ")}`,
+        status: 400,
+        code: "VALIDATION_ERROR",
+        invariantCode: "entity.metadata_schema",
+        details: { errors: validation.errors }
+      });
+    }
+    const updates = {
+      metadata: mergedMetadata,
+      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,
+      operation: "upsert"
+    });
+    await ctx.db.insert("epistemicAudit", {
+      entityType: "entity",
+      entityId: args.nodeId,
+      changeType: "entity_attributes_updated",
+      changedAt: now,
+      changedBy: authenticatedUserId,
+      isAgent: false,
+      previousState: {
+        canonicalText: node.canonicalText,
+        title: node.title,
+        subtype: node.subtype,
+        domain: node.domain,
+        tags: node.tags,
+        verificationStatus: node.verificationStatus,
+        externalIds: node.externalIds,
+        metadata: existingMetadata
+      },
+      newState: updates,
+      projectId: scopeProjectId
+    });
+    return { nodeId: args.nodeId, updated: true };
+  }
+});
+var mergeEntities = mutation({
+  args: {
+    canonicalNodeId: v.id("epistemicNodes"),
+    duplicateNodeId: v.id("epistemicNodes")
+  },
+  returns: permissiveReturn,
+  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) {
+      throwStructuredMutationError({
+        message: "One or both entity nodes not found.",
+        status: 404,
+        code: "NOT_FOUND",
+        details: {
+          canonicalNodeId: args.canonicalNodeId,
+          duplicateNodeId: args.duplicateNodeId
+        }
+      });
+    }
+    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.",
+        status: 400,
+        code: "SELF_MERGE",
+        invariantCode: "entity.no_self_merge",
+        suggestion: "Provide two different entity IDs to merge.",
+        details: { canonicalNodeId: args.canonicalNodeId }
+      });
+    }
+    if (canonical.nodeType !== duplicate.nodeType) {
+      throwStructuredMutationError({
+        message: `Cannot merge different entity types: ${canonical.nodeType} vs ${duplicate.nodeType}.`,
+        status: 400,
+        code: "TYPE_MISMATCH"
+      });
+    }
+    if (canonical.projectId) {
+      await requireProjectWriteAccess(
+        ctx,
+        canonical.projectId,
+        authenticatedUserId
+      );
+    }
+    const edgeGlobalId = generateGlobalId();
+    await ctx.db.insert("epistemicEdges", {
+      globalId: edgeGlobalId,
+      fromNodeId: args.duplicateNodeId,
+      toNodeId: args.canonicalNodeId,
+      sourceGlobalId: duplicate.globalId,
+      targetGlobalId: canonical.globalId,
+      edgeType: "derived_from",
+      weight: 1,
+      context: `Entity merge: ${duplicate.canonicalText} \u2192 ${canonical.canonicalText}`,
+      createdBy: authenticatedUserId,
+      createdAt: now,
+      updatedAt: now
+    });
+    const outgoingEdges = await ctx.db.query("epistemicEdges").withIndex(
+      "by_from",
+      (q) => q.eq("fromNodeId", args.duplicateNodeId)
+    ).collect();
+    for (const edge of outgoingEdges) {
+      if (edge.toNodeId === args.canonicalNodeId) {
+        continue;
+      }
+      await ctx.db.patch(edge._id, {
+        fromNodeId: args.canonicalNodeId,
+        sourceGlobalId: canonical.globalId,
+        updatedAt: now
+      });
+    }
+    const incomingEdges = await ctx.db.query("epistemicEdges").withIndex("by_to", (q) => q.eq("toNodeId", args.duplicateNodeId)).collect();
+    for (const edge of incomingEdges) {
+      if (edge.fromNodeId === args.canonicalNodeId) {
+        continue;
+      }
+      await ctx.db.patch(edge._id, {
+        toNodeId: args.canonicalNodeId,
+        targetGlobalId: canonical.globalId,
+        updatedAt: now
+      });
+    }
+    const duplicateMetadata = duplicate.metadata || {};
+    await ctx.db.patch(args.duplicateNodeId, {
+      status: "superseded",
+      metadata: {
+        ...duplicateMetadata,
+        status: "superseded",
+        supersededBy: args.canonicalNodeId,
+        mergedAt: now,
+        mergedBy: authenticatedUserId
+      },
+      updatedAt: now
+    });
+    await ctx.scheduler.runAfter(0, internal.neo4jSync.syncNodeToNeo4j, {
+      nodeId: args.canonicalNodeId,
+      operation: "upsert"
+    });
+    await ctx.scheduler.runAfter(0, internal.neo4jSync.syncNodeToNeo4j, {
+      nodeId: args.duplicateNodeId,
+      operation: "upsert"
+    });
+    await ctx.db.insert("epistemicAudit", {
+      entityType: "entity",
+      entityId: args.canonicalNodeId,
+      changeType: "entity_merged",
+      changedAt: now,
+      changedBy: authenticatedUserId,
+      isAgent: false,
+      rationale: `Entity merge: absorbed ${args.duplicateNodeId} (${duplicate.canonicalText}). ${outgoingEdges.length + incomingEdges.length} edges re-pointed.`,
+      previousState: null,
+      newState: {
+        nodeType: canonical.nodeType,
+        canonicalText: canonical.canonicalText
+      },
+      projectId: canonical.projectId
+    });
+    const outgoingRepointed = outgoingEdges.filter(
+      (e) => e.toNodeId !== args.canonicalNodeId
+    ).length;
+    const incomingRepointed = incomingEdges.filter(
+      (e) => e.fromNodeId !== args.canonicalNodeId
+    ).length;
+    await ctx.scheduler.runAfter(
+      0,
+      internal.lucernMcp.triggerEntityChangeReview,
+      {
+        entityNodeId: args.canonicalNodeId,
+        changeDescription: `Merged with duplicate "${duplicate.canonicalText}". ${outgoingRepointed + incomingRepointed} edges re-pointed.`,
+        userId: authenticatedUserId
+      }
+    );
+    return {
+      canonicalNodeId: args.canonicalNodeId,
+      duplicateNodeId: args.duplicateNodeId,
+      edgesRepointed: outgoingRepointed + incomingRepointed
+    };
+  }
+});
+var archiveEntity = mutation({
+  args: {
+    nodeId: v.id("epistemicNodes")
+  },
+  returns: permissiveReturn,
+  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"
+      });
+    }
+    if (node.projectId) {
+      await requireProjectWriteAccess(
+        ctx,
+        node.projectId,
+        authenticatedUserId
+      );
+    }
+    await ctx.db.patch(args.nodeId, {
+      status: "archived",
+      updatedAt: now
+    });
+    await ctx.scheduler.runAfter(0, internal.neo4jSync.syncNodeToNeo4j, {
+      nodeId: args.nodeId,
+      operation: "upsert"
+    });
+    await ctx.db.insert("epistemicAudit", {
+      entityType: "entity",
+      entityId: args.nodeId,
+      changeType: "entity_archived",
+      changedAt: now,
+      changedBy: authenticatedUserId,
+      isAgent: false,
+      previousState: { status: node.status },
+      newState: { status: "archived" },
+      projectId: node.projectId
+    });
+    await ctx.scheduler.runAfter(
+      0,
+      internal.lucernMcp.triggerEntityChangeReview,
+      {
+        entityNodeId: args.nodeId,
+        changeDescription: `Entity "${node.canonicalText}" was archived.`,
+        userId: authenticatedUserId
+      }
+    );
+    return { nodeId: args.nodeId, archived: true };
+  }
+});
+
+export { ONTOLOGICAL_NODE_TYPES, archiveEntity, createEntity, isOntologicalNodeType, listCanonicalEntities, mergeEntities, updateEntityAttributes };
+//# sourceMappingURL=entityLifecycle.js.map
+//# sourceMappingURL=entityLifecycle.js.map