@lucern/graph-primitives 1.0.28 → 1.0.30

package/dist/epistemicQuestions.tail.js

@@ -1,15 +1,19 @@
-import { v } from 'convex/values';
 import { checkScopeAccess } from '@lucern/access-control/access';
 import { permissiveReturn } from '@lucern/contracts/schema-helpers/validators';
-import { componentsGeneric, anyApi, queryGeneric, mutationGeneric } from 'convex/server';
+import { v } from 'convex/values';
+import { unsafeConvexAnyApi } from '@lucern/contracts/convex/unsafeAnyApi';
+import { componentsGeneric, queryGeneric, mutationGeneric } from 'convex/server';
+import '@lucern/contracts';
 import { generateGlobalId, assertUuidV7Identity } from '@lucern/contracts/ids';
 import '@lucern/contracts/schema-helpers/spine/tables/epistemicNodes';
-import '@lucern/contracts';
 
 // src/epistemicQuestions.tail.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;
 
@@ -43,6 +47,10 @@ function debugGraphPrimitiveFallback(message, context) {
   }
   console.debug(message, context ?? {});
 }
+function insertEpistemicNode(ctx, doc) {
+  assertUuidV7Identity("epistemicNodes", doc.globalId);
+  return ctx.db.insert("epistemicNodes", doc);
+}
 
 // src/topicProjectOverlay.ts
 var LEGACY_SCOPE_FIELD = "graphScopeProjectId";
@@ -62,6 +70,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;
@@ -142,9 +154,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;
     }
@@ -164,8 +179,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,
@@ -234,90 +259,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;
   }
-  patch.updatedAt = Date.now();
-  patch.metadata = nextMetadata;
-  topicUpdateArgs.metadata = nextMetadata;
+}
+function applyTopicVisibilityPatch(plan, rawValue) {
+  const visibility = coerceVisibility(rawValue);
+  if (visibility) {
+    plan.patch.visibility = visibility;
+    plan.topicUpdateArgs.visibility = visibility;
+  }
+}
+function applyTopicProjectTypePatch(plan, rawValue) {
+  const projectType = readNonEmptyString(rawValue);
+  if (projectType) {
+    plan.nextMetadata.projectType = projectType;
+    return;
+  }
+  plan.nextMetadata = omitMetadataKey(plan.nextMetadata, "projectType");
+}
+function applyTopicMetadataPatch(plan, key, rawValue) {
+  if (rawValue === void 0) {
+    plan.nextMetadata = omitMetadataKey(plan.nextMetadata, key);
+    return;
+  }
+  plan.nextMetadata[key] = rawValue;
+}
+async function applyTopicProjectOverlayPatch(ctx, topic, plan) {
   if (typeof ctx.runMutation === "function") {
     try {
-      await ctx.runMutation(api.topics.update, topicUpdateArgs);
+      await ctx.runMutation(api.topics.update, plan.topicUpdateArgs);
     } catch (error) {
-      if (!isMissingLucernChildComponentError(error) || !ctx?.db || typeof ctx.db.patch !== "function") {
+      if (!canPatchTopicViaLocalDb(ctx, error)) {
         throw error;
       }
-      await ctx.db.patch(String(topic._id), patch);
+      await ctx.db.patch(topic._id, plan.patch);
     }
   } else if (ctx?.db && typeof ctx.db.patch === "function") {
-    await ctx.db.patch(String(topic._id), patch);
+    await ctx.db.patch(topic._id, plan.patch);
   } else {
     throw new Error(
       "Cannot patch topic without component adapter (ctx.runMutation unavailable)"
     );
   }
-  return materializeTopicProjectOverlay({
-    ...topic,
-    ...patch,
-    metadata: nextMetadata
-  });
+}
+function canPatchTopicViaLocalDb(ctx, error) {
+  return isMissingLucernChildComponentError(error) && Boolean(ctx?.db) && typeof ctx.db?.patch === "function";
 }
 
 // src/resolvers.ts
@@ -345,7 +393,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(
@@ -412,13 +460,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") {
@@ -443,8 +493,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();
@@ -456,7 +507,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);
@@ -512,244 +563,140 @@ 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())
-};
-function normalizeScopeValue2(value) {
-  if (typeof value !== "string") {
-    return;
+async function resolveScopeFromTopicId(ctx, topicId) {
+  const topic = await resolveTopicDocFromTopicId(ctx, topicId);
+  if (topic) {
+    return await buildTopicScope(ctx, topic, "topic");
   }
-  const normalized = value.trim();
-  return normalized.length > 0 ? normalized : void 0;
-}
-function throwWorkspaceIsolationError(args) {
-  const error = new Error(args.message);
-  error.status = 409;
-  error.code = "INVARIANT_VIOLATION";
-  error.invariantCode = args.invariantCode;
-  error.suggestion = args.suggestion;
-  error.details = args.details;
-  throw error;
-}
-async function resolveNodeScopeForWorkspaceIsolation(ctx, node) {
-  const epistemicLayer = typeof node?.epistemicLayer === "string" ? node.epistemicLayer : void 0;
-  const resolved = {
-    tenantId: normalizeScopeValue2(node?.tenantId),
-    workspaceId: normalizeScopeValue2(node?.workspaceId),
-    epistemicLayer,
-    nodeType: typeof node?.nodeType === "string" ? node.nodeType : void 0
-  };
-  if (!node) {
-    return resolved;
+  const nodeScope = await resolveTopicNodeScopeOrNull(ctx, String(topicId));
+  if (nodeScope) {
+    return nodeScope;
   }
-  if (resolved.epistemicLayer === "ontological") {
-    return resolved;
+  throw new Error(`Topic not found: ${String(topicId)}`);
+}
+async function resolveTopicDocFromTopicId(ctx, topicId) {
+  const direct = await tryReadTopicDoc(ctx, topicId, {
+    failureLog: "[topicScope] Failed to load topic by direct id",
+    idLogKey: "topicId"
+  });
+  if (direct) {
+    return direct;
   }
-  if (resolved.tenantId || resolved.workspaceId) {
-    return resolved;
+  const hostTopic = await tryResolveHostTopicById(ctx, String(topicId));
+  if (hostTopic) {
+    return hostTopic;
   }
-  if (node.topicId) {
-    const topicScope = await resolveTopicProjectScope(ctx, {
-      topicId: node.topicId
+  return pickPrimaryTopic(await findTopicsByScopeAlias(ctx, String(topicId))) ?? null;
+}
+async function resolveScopeFromLegacyProjectId(ctx, legacyProjectId) {
+  const directTopic = await resolveDirectLegacyProjectTopic(
+    ctx,
+    legacyProjectId
+  );
+  if (directTopic) {
+    return await buildTopicScope(ctx, directTopic, "topic_inferred", {
+      fallbackProjectId: legacyProjectId
     });
-    return {
-      ...resolved,
-      tenantId: topicScope.tenantId,
-      workspaceId: topicScope.workspaceId
-    };
   }
-  if (node.projectId) {
-    const topicScope = await resolveTopicProjectScope(ctx, {
-      projectId: String(node.projectId)
+  const primary = pickPrimaryTopic(
+    await findTopicsByScopeAlias(ctx, legacyProjectId)
+  );
+  if (primary) {
+    return await buildTopicScope(ctx, primary, "project_mapped_topic", {
+      fallbackProjectId: legacyProjectId
     });
+  }
+  const nodeScope = await resolveTopicNodeScopeOrNull(ctx, legacyProjectId);
+  if (nodeScope) {
     return {
-      ...resolved,
-      tenantId: topicScope.tenantId,
-      workspaceId: topicScope.workspaceId
+      ...nodeScope,
+      projectId: nodeScope.projectId ?? legacyProjectId
     };
   }
-  return resolved;
+  throw new Error(
+    `Legacy project scope ${legacyProjectId} has no mapped topic.`
+  );
 }
-function resolveRuntimePackMutationContext(args) {
-  if (!args.runtimeToolName && !args.runtimePackKey && !args.runtimePackInstallScope) {
-    return;
+async function resolveDirectLegacyProjectTopic(ctx, legacyProjectId) {
+  const directTopic = await tryReadTopicDoc(ctx, legacyProjectId, {
+    failureLog: "[topicScope] Failed to load direct project topic",
+    idLogKey: "projectId"
+  });
+  return directTopic ?? tryResolveHostTopicByLegacyScope(ctx, legacyProjectId);
+}
+async function tryReadTopicDoc(ctx, id, log) {
+  try {
+    return await ctx.db.get(id);
+  } catch (error) {
+    debugGraphPrimitiveFallback(log.failureLog, {
+      error,
+      [log.idLogKey]: id
+    });
+    return null;
   }
+}
+async function buildTopicScope(ctx, topic, source, options = {}) {
+  const inherited = await resolveInheritedWorkspaceScope(ctx, topic);
+  const mapped = asMappedProjectId(topic);
   return {
-    toolName: args.runtimeToolName,
-    packKey: args.runtimePackKey,
-    packInstallScope: args.runtimePackInstallScope
+    topicId: topic._id,
+    ...mapped || options.fallbackProjectId ? { projectId: mapped ?? options.fallbackProjectId } : {},
+    tenantId: inherited.tenantId,
+    workspaceId: inherited.workspaceId,
+    source
   };
 }
-function assertTenantPackWorkspaceMutationAllowed(args) {
-  if (!args.runtime?.packKey || args.runtime.packInstallScope !== "tenant") {
-    return;
-  }
-  const targetWorkspaceId = normalizeScopeValue2(args.target.workspaceId);
-  const targetLayer = typeof args.target.epistemicLayer === "string" ? args.target.epistemicLayer : void 0;
-  if (!targetWorkspaceId || targetLayer === "ontological") {
-    return;
-  }
-  throwWorkspaceIsolationError({
-    message: `Tenant-scoped pack "${args.runtime.packKey}" cannot mutate workspace-scoped reasoning state.`,
-    invariantCode: "workspace.tenant_pack_reasoning_write_forbidden",
-    suggestion: "Use a workspace-scoped pack for workspace-local graph mutations, or route the change through tenant-global canonical entity flows.",
-    details: {
-      mutationName: args.mutationName,
-      toolName: args.runtime.toolName,
-      packKey: args.runtime.packKey,
-      targetWorkspaceId,
-      targetNodeType: args.target.nodeType,
-      targetLayer
-    }
-  });
-}
+var optionalScopeArgs = {
+  projectId: v.optional(v.string()),
+  topicId: v.optional(v.string())
+};
 
 // src/epistemicQuestions.helpers.ts
 function generateContentHash(text) {
   const content = `question:${text.trim().toLowerCase().replace(/\s+/g, " ")}`;
   let hash = 5381;
+  const maxSigned32Bit = 2147483647;
+  const uint32Size = 4294967296;
   for (let i = 0; i < content.length; i++) {
-    hash = (hash << 5) + hash + content.charCodeAt(i);
-    hash &= hash;
+    hash = Math.imul(hash, 33) + content.charCodeAt(i);
+    hash %= uint32Size;
+    if (hash > maxSigned32Bit) {
+      hash -= uint32Size;
+    }
   }
   return Math.abs(hash).toString(16).padStart(8, "0");
 }
 async function markProjectGraphDirty(ctx, projectId, topicId) {
+  const markCacheStaleByTopic = internal.graphAnalysisCache.markCacheStaleByTopic;
   const normalizedProjectId = typeof projectId === "string" && projectId.trim().length > 0 ? projectId : void 0;
   const normalizedTopicId = typeof topicId === "string" && topicId.trim().length > 0 ? topicId : void 0;
-  if (!normalizedProjectId && !normalizedTopicId) {
+  if (!(normalizedProjectId || normalizedTopicId)) {
     return;
   }
   if (normalizedProjectId) {
@@ -762,17 +709,17 @@ async function markProjectGraphDirty(ctx, projectId, topicId) {
     );
   }
   if (normalizedTopicId) {
-    await ctx.scheduler.runAfter(
-      0,
-      internal.graphAnalysisCache.markCacheStaleByTopic,
-      {
-        topicId: normalizedTopicId
-      }
-    );
+    await ctx.scheduler.runAfter(0, markCacheStaleByTopic, {
+      topicId: normalizedTopicId
+    });
+  }
+  const resolvedProjectId = normalizedTopicId ?? normalizedProjectId;
+  if (!resolvedProjectId) {
+    return;
   }
   await resolveGraphPrimitivesAppResolvers().patchProject(
     ctx,
-    normalizedTopicId ?? normalizedProjectId,
+    resolvedProjectId,
     {
       lastActivityAt: Date.now()
     }
@@ -798,7 +745,7 @@ function resolveQuestionScopeId(scope) {
   return normalizeQuestionTopicId(scope.topicId) ?? scope.projectId ?? void 0;
 }
 async function resolveQuestionScopeOrNull(ctx, args) {
-  if (!args.projectId && !args.topicId) {
+  if (!(args.projectId || args.topicId)) {
     return null;
   }
   try {
@@ -854,7 +801,7 @@ function flattenQuestionNode(n) {
     linkedBeliefId: meta.linkedBeliefNodeId || null,
     testType: meta.testType || "validates",
     importance: meta.importance || 5,
-    isKeyQuestion: meta.isKeyQuestion || false,
+    isKeyQuestion: Boolean(meta.isKeyQuestion),
     answer: meta.answer || null,
     convictionStage: meta.convictionStage || null,
     conviction: meta.conviction ?? null,
@@ -889,7 +836,7 @@ function getQuestionStatusCandidates(node) {
   );
 }
 function isActiveQuestionNode(node) {
-  if (INACTIVE_NODE_STATUSES.has(node.status)) {
+  if (typeof node.status === "string" && INACTIVE_NODE_STATUSES.has(node.status)) {
     return false;
   }
   return !getQuestionStatusCandidates(node).some(
@@ -902,12 +849,288 @@ function matchesRequestedQuestionStatus(node, requestedStatus) {
     (status) => status.toLowerCase() === normalizedStatus
   );
 }
-async function insertEpistemicNode(ctx, doc) {
-  assertUuidV7Identity("epistemicNodes", doc.globalId);
-  return ctx.db.insert("epistemicNodes", doc);
+function normalizeScopeValue2(value) {
+  if (typeof value !== "string") {
+    return;
+  }
+  const normalized = value.trim();
+  return normalized.length > 0 ? normalized : void 0;
+}
+function throwWorkspaceIsolationError(args) {
+  const error = new Error(args.message);
+  error.status = 409;
+  error.code = "INVARIANT_VIOLATION";
+  error.invariantCode = args.invariantCode;
+  error.suggestion = args.suggestion;
+  error.details = args.details;
+  throw error;
+}
+async function resolveNodeScopeForWorkspaceIsolation(ctx, node) {
+  const epistemicLayer = typeof node?.epistemicLayer === "string" ? node.epistemicLayer : void 0;
+  const resolved = {
+    tenantId: normalizeScopeValue2(node?.tenantId),
+    workspaceId: normalizeScopeValue2(node?.workspaceId),
+    epistemicLayer,
+    nodeType: typeof node?.nodeType === "string" ? node.nodeType : void 0
+  };
+  if (!node) {
+    return resolved;
+  }
+  if (resolved.epistemicLayer === "ontological") {
+    return resolved;
+  }
+  if (resolved.tenantId || resolved.workspaceId) {
+    return resolved;
+  }
+  const topicId = normalizeScopeValue2(node.topicId);
+  if (topicId) {
+    const topicScope = await resolveTopicProjectScope(ctx, {
+      topicId
+    });
+    return {
+      ...resolved,
+      tenantId: topicScope.tenantId,
+      workspaceId: topicScope.workspaceId
+    };
+  }
+  if (node.projectId) {
+    const topicScope = await resolveTopicProjectScope(ctx, {
+      projectId: String(node.projectId)
+    });
+    return {
+      ...resolved,
+      tenantId: topicScope.tenantId,
+      workspaceId: topicScope.workspaceId
+    };
+  }
+  return resolved;
+}
+function resolveRuntimePackMutationContext(args) {
+  if (!(args.runtimeToolName || args.runtimePackKey || args.runtimePackInstallScope)) {
+    return;
+  }
+  return {
+    toolName: args.runtimeToolName,
+    packKey: args.runtimePackKey,
+    packInstallScope: args.runtimePackInstallScope
+  };
+}
+function assertTenantPackWorkspaceMutationAllowed(args) {
+  if (!args.runtime?.packKey || args.runtime.packInstallScope !== "tenant") {
+    return;
+  }
+  const targetWorkspaceId = normalizeScopeValue2(args.target.workspaceId);
+  const targetLayer = typeof args.target.epistemicLayer === "string" ? args.target.epistemicLayer : void 0;
+  if (!targetWorkspaceId || targetLayer === "ontological") {
+    return;
+  }
+  throwWorkspaceIsolationError({
+    message: `Tenant-scoped pack "${args.runtime.packKey}" cannot mutate workspace-scoped reasoning state.`,
+    invariantCode: "workspace.tenant_pack_reasoning_write_forbidden",
+    suggestion: "Use a workspace-scoped pack for workspace-local graph mutations, or route the change through tenant-global canonical entity flows.",
+    details: {
+      mutationName: args.mutationName,
+      toolName: args.runtime.toolName,
+      packKey: args.runtime.packKey,
+      targetWorkspaceId,
+      targetNodeType: args.target.nodeType,
+      targetLayer
+    }
+  });
 }
 
 // src/epistemicQuestions.tail.ts
+var QUESTION_PRIORITY_ORDER = {
+  high: 0,
+  low: 2,
+  medium: 1
+};
+function readQuestionType(question, metadata) {
+  if (typeof question.questionType === "string") {
+    return question.questionType;
+  }
+  if (typeof metadata.questionType === "string") {
+    return metadata.questionType;
+  }
+  return;
+}
+function toRecord(value) {
+  if (typeof value === "object" && value !== null && !Array.isArray(value)) {
+    return value;
+  }
+  return {};
+}
+function readOptionalString(value) {
+  return typeof value === "string" && value.trim().length > 0 ? value : void 0;
+}
+function readStringValue(source, key) {
+  return readOptionalString(source[key]);
+}
+function readConvexId(value) {
+  const normalized = readOptionalString(value);
+  return normalized ? normalized : null;
+}
+function readStringArray2(value) {
+  return Array.isArray(value) ? value.filter((item) => typeof item === "string") : [];
+}
+function isEpistemicNodeDoc(value) {
+  return readConvexId(toRecord(value)._id) !== null;
+}
+function isQuestionNodeDoc(value) {
+  return isEpistemicNodeDoc(value) && readStringValue(toRecord(value), "nodeType") === "question";
+}
+function isBeliefNodeDoc(value) {
+  return isEpistemicNodeDoc(value) && readStringValue(toRecord(value), "nodeType") === "belief";
+}
+function readFinalArtifactRow(value) {
+  const record = toRecord(value);
+  const id = readConvexId(record._id);
+  if (!id) {
+    return null;
+  }
+  const row = { _id: id };
+  const projectId = readOptionalString(record.projectId);
+  if (projectId !== void 0) {
+    row.projectId = projectId;
+  }
+  const topicId = readOptionalString(record.topicId);
+  if (topicId !== void 0) {
+    row.topicId = topicId;
+  }
+  return row;
+}
+function readQuestionPriority(metadata) {
+  const value = metadata.priority;
+  return value === "high" || value === "medium" || value === "low" ? value : "medium";
+}
+function loadQuestionNodes(ctx, questionIds) {
+  return Promise.all(
+    questionIds.map(async (questionId) => {
+      try {
+        const nodeId = readConvexId(questionId);
+        return nodeId ? await ctx.db.get(nodeId) : null;
+      } catch (error) {
+        debugGraphPrimitiveFallback(
+          "[epistemicQuestions] Failed to load original question",
+          {
+            error: formatGraphPrimitiveError(error),
+            questionId
+          }
+        );
+        return null;
+      }
+    })
+  );
+}
+function questionBelongsToScope(question, scope) {
+  if (scope.topicId) {
+    return String(question.topicId) === String(scope.topicId) || !question.topicId && scope.projectId !== void 0 && String(question.projectId) === String(scope.projectId);
+  }
+  return String(question.projectId) === String(scope.projectId);
+}
+function consolidatedQuestionNodes(questions, scope, expectedCount) {
+  const validQuestions = questions.filter(
+    (question) => isQuestionNodeDoc(question) && questionBelongsToScope(question, scope)
+  );
+  if (validQuestions.length !== expectedCount) {
+    throw new Error(
+      "Some questions not found or do not belong to this topic scope"
+    );
+  }
+  return validQuestions;
+}
+function chooseConsolidatedPriority(explicitPriority, questions) {
+  if (explicitPriority) {
+    return explicitPriority;
+  }
+  let bestPriority = "medium";
+  let bestScore = QUESTION_PRIORITY_ORDER.low;
+  for (const question of questions) {
+    const priority = readQuestionPriority(toRecord(question.metadata));
+    const score = QUESTION_PRIORITY_ORDER[priority];
+    if (score < bestScore) {
+      bestPriority = priority;
+      bestScore = score;
+    }
+  }
+  return bestPriority;
+}
+function collectLinkedBeliefIds(questions, explicitBeliefIds) {
+  const linkedBeliefSet = /* @__PURE__ */ new Set();
+  if (explicitBeliefIds) {
+    for (const beliefId of explicitBeliefIds) {
+      linkedBeliefSet.add(String(beliefId));
+    }
+    return linkedBeliefSet;
+  }
+  for (const question of questions) {
+    const metadata = toRecord(question.metadata);
+    const linkedBeliefNodeId = metadata.linkedBeliefNodeId;
+    const linkedBeliefId = metadata.linkedBeliefId;
+    if (linkedBeliefNodeId) {
+      linkedBeliefSet.add(String(linkedBeliefNodeId));
+    }
+    if (linkedBeliefId) {
+      linkedBeliefSet.add(String(linkedBeliefId));
+    }
+  }
+  return linkedBeliefSet;
+}
+async function readConsolidatedQuestionCategory(ctx, linkedBeliefSet) {
+  const firstBeliefId = Array.from(linkedBeliefSet)[0];
+  if (!firstBeliefId) {
+    return "other";
+  }
+  try {
+    const beliefId = readConvexId(firstBeliefId);
+    const belief = beliefId ? await ctx.db.get(beliefId) : null;
+    const metadata = toRecord(belief?.metadata);
+    return readStringValue(metadata, "category") ?? readStringValue(metadata, "pillar") ?? "other";
+  } catch (error) {
+    debugGraphPrimitiveFallback(
+      "[epistemicQuestions] Failed to read first linked belief metadata",
+      {
+        beliefId: firstBeliefId,
+        error: formatGraphPrimitiveError(error)
+      }
+    );
+    return "other";
+  }
+}
+async function archiveConsolidatedQuestions(ctx, questionIds, newNodeId, now) {
+  for (const questionId of questionIds) {
+    try {
+      const nodeId = readConvexId(questionId);
+      if (!nodeId) {
+        continue;
+      }
+      const node = await ctx.db.get(nodeId);
+      if (!node) {
+        continue;
+      }
+      const metadata = toRecord(node.metadata);
+      await ctx.db.patch(nodeId, {
+        metadata: {
+          ...metadata,
+          archivedAt: now,
+          archivedReason: `Consolidated into question ${newNodeId}`,
+          consolidatedIntoId: newNodeId,
+          questionStatus: "archived"
+        },
+        status: "archived",
+        updatedAt: now
+      });
+    } catch (error) {
+      debugGraphPrimitiveFallback(
+        "[epistemicQuestions] Failed to archive linked question",
+        {
+          error: formatGraphPrimitiveError(error),
+          questionId
+        }
+      );
+    }
+  }
+}
 var list = query({
   args: {
     ...optionalScopeArgs,
@@ -929,8 +1152,9 @@ var list = query({
       return [];
     }
     const nodes = await getQuestionNodesForScope(ctx, scope);
-    const filtered = args.status ? nodes.filter(
-      (node) => matchesRequestedQuestionStatus(node, args.status)
+    const requestedStatus = args.status;
+    const filtered = requestedStatus ? nodes.filter(
+      (node) => matchesRequestedQuestionStatus(node, requestedStatus)
     ) : nodes.filter(isActiveQuestionNode);
     return filtered.map(flattenInternalQuestionNode);
   }
@@ -961,7 +1185,10 @@ var getByPillar = query({
       (q) => q.eq("topicId", scope.topicId).eq("nodeType", "belief")
     ).collect();
     const beliefs = allBeliefNodes.filter((n) => {
-      const meta = n.metadata || {};
+      if (!isBeliefNodeDoc(n)) {
+        return false;
+      }
+      const meta = toRecord(n.metadata);
       return (meta.category === args.pillar || meta.topic === args.pillar || meta.pillar === args.pillar) && n.status !== "archived";
     });
     if (beliefs.length === 0) {
@@ -973,37 +1200,34 @@ var getByPillar = query({
     );
     const questionNodes = await getQuestionNodesForScope(ctx, scope);
     const pillarQuestions = questionNodes.filter((q) => {
-      const meta = q.metadata || {};
-      const linkedId = String(
-        meta.linkedBeliefNodeId || meta.linkedBeliefId || meta.beliefId || ""
-      );
+      const meta = toRecord(q.metadata);
+      const linkedId = readOptionalString(meta.linkedBeliefNodeId) ?? readOptionalString(meta.linkedBeliefId) ?? readOptionalString(meta.beliefId);
       if (linkedId && beliefIds.has(linkedId)) {
         return true;
       }
-      const relatedIds = meta.relatedBeliefIds || [];
-      return relatedIds.some((id) => beliefIds.has(String(id)));
+      return readStringArray2(meta.relatedBeliefIds).some(
+        (id) => beliefIds.has(id)
+      );
     });
     const includeAnswered = args.includeAnswered ?? true;
     const filteredQuestions = includeAnswered ? pillarQuestions : pillarQuestions.filter((q) => {
-      const meta = q.metadata || {};
+      const meta = toRecord(q.metadata);
       return meta.questionStatus !== "answered";
     });
     const enrichedQuestions = filteredQuestions.map((q) => {
-      const meta = q.metadata || {};
-      const linkedId = String(
-        meta.linkedBeliefNodeId || meta.linkedBeliefId || meta.beliefId || ""
-      );
+      const meta = toRecord(q.metadata);
+      const linkedId = readOptionalString(meta.linkedBeliefNodeId) ?? readOptionalString(meta.linkedBeliefId) ?? readOptionalString(meta.beliefId);
       return {
         _id: q._id,
         _creationTime: q._creationTime,
         projectId: q.projectId,
         question: q.canonicalText,
         canonicalText: q.canonicalText,
-        category: meta.category || "other",
-        priority: meta.priority || "medium",
-        status: meta.questionStatus || q.status,
-        questionType: q.questionType || meta.questionType || "general",
-        beliefId: linkedId || void 0,
+        category: readOptionalString(meta.category) ?? "other",
+        priority: readQuestionPriority(meta),
+        status: readOptionalString(meta.questionStatus) ?? q.status ?? "open",
+        questionType: q.questionType ?? readOptionalString(meta.questionType) ?? "general",
+        beliefId: linkedId,
         beliefText: linkedId ? beliefMap.get(linkedId) : void 0,
         createdAt: q.createdAt,
         createdBy: q.createdBy,
@@ -1021,15 +1245,15 @@ var getByPillar = query({
       if (aPriority !== bPriority) {
         return aPriority - bPriority;
       }
-      return (b.createdAt || 0) - (a.createdAt || 0);
+      return (b.createdAt ?? 0) - (a.createdAt ?? 0);
     });
     return {
       questions: enrichedQuestions,
       beliefs: beliefs.map((b) => ({
         _id: b._id,
         belief: b.canonicalText,
-        pillar: b.metadata?.category || b.metadata?.pillar,
-        confidence: b.metadata?.confidence
+        pillar: readStringValue(toRecord(b.metadata), "category") || readStringValue(toRecord(b.metadata), "pillar"),
+        confidence: toRecord(b.metadata).confidence
       }))
     };
   }
@@ -1065,88 +1289,23 @@ var consolidate = mutation({
     if (args.questionIds.length < 2) {
       throw new Error("At least 2 questions required for consolidation");
     }
-    const originalQuestions = await Promise.all(
-      args.questionIds.map(async (qid) => {
-        try {
-          return await ctx.db.get(qid);
-        } catch (error) {
-          debugGraphPrimitiveFallback(
-            "[epistemicQuestions] Failed to load original question",
-            {
-              error: formatGraphPrimitiveError(error),
-              questionId: qid
-            }
-          );
-          return null;
-        }
-      })
+    const validQuestions = consolidatedQuestionNodes(
+      await loadQuestionNodes(ctx, args.questionIds),
+      scope,
+      args.questionIds.length
+    );
+    const bestPriority = chooseConsolidatedPriority(
+      args.priority,
+      validQuestions
+    );
+    const linkedBeliefSet = collectLinkedBeliefIds(
+      validQuestions,
+      args.linkedBeliefIds
+    );
+    const category = await readConsolidatedQuestionCategory(
+      ctx,
+      linkedBeliefSet
     );
-    const validQuestions = originalQuestions.filter((q) => {
-      if (!q || q.nodeType !== "question") {
-        return false;
-      }
-      if (scope.topicId) {
-        return String(q.topicId) === String(scope.topicId) || !q.topicId && scope.projectId !== void 0 && String(q.projectId) === String(scope.projectId);
-      }
-      return String(q.projectId) === String(scope.projectId);
-    });
-    if (validQuestions.length !== args.questionIds.length) {
-      throw new Error(
-        "Some questions not found or do not belong to this topic scope"
-      );
-    }
-    const priorityOrder = {
-      high: 0,
-      medium: 1,
-      low: 2
-    };
-    let bestPriority = args.priority;
-    if (!bestPriority) {
-      let bestScore = 2;
-      for (const q of validQuestions) {
-        const meta = q?.metadata || {};
-        const score = priorityOrder[meta.priority || "medium"] ?? 1;
-        if (score < bestScore) {
-          bestScore = score;
-          bestPriority = meta.priority || "medium";
-        }
-      }
-    }
-    const linkedBeliefSet = /* @__PURE__ */ new Set();
-    if (args.linkedBeliefIds) {
-      for (const bid of args.linkedBeliefIds) {
-        linkedBeliefSet.add(String(bid));
-      }
-    } else {
-      for (const q of validQuestions) {
-        const meta = q?.metadata || {};
-        if (meta.linkedBeliefNodeId) {
-          linkedBeliefSet.add(String(meta.linkedBeliefNodeId));
-        }
-        if (meta.linkedBeliefId) {
-          linkedBeliefSet.add(String(meta.linkedBeliefId));
-        }
-      }
-    }
-    let category = "other";
-    if (linkedBeliefSet.size > 0) {
-      const firstBeliefId = Array.from(linkedBeliefSet)[0];
-      try {
-        const belief = await ctx.db.get(firstBeliefId);
-        if (belief) {
-          const bMeta = belief.metadata || {};
-          category = bMeta.category || bMeta.pillar || "other";
-        }
-      } catch (error) {
-        debugGraphPrimitiveFallback(
-          "[epistemicQuestions] Failed to read first linked belief metadata",
-          {
-            error: formatGraphPrimitiveError(error),
-            beliefId: firstBeliefId
-          }
-        );
-      }
-    }
     const now = Date.now();
     const globalId = generateGlobalId();
     const contentHash = generateContentHash(args.consolidatedQuestion);
@@ -1165,7 +1324,7 @@ var consolidate = mutation({
       createdBy: args.consolidatedBy,
       metadata: {
         category,
-        priority: bestPriority || "medium",
+        priority: bestPriority,
         source: "consolidated",
         questionStatus: "open",
         linkedBeliefNodeId: linkedBeliefSet.size > 0 ? Array.from(linkedBeliefSet)[0] : void 0,
@@ -1177,33 +1336,7 @@ var consolidate = mutation({
         }
       }
     });
-    for (const qid of args.questionIds) {
-      try {
-        const node = await ctx.db.get(qid);
-        if (node) {
-          const meta = node.metadata || {};
-          await ctx.db.patch(qid, {
-            status: "archived",
-            updatedAt: now,
-            metadata: {
-              ...meta,
-              questionStatus: "archived",
-              archivedAt: now,
-              archivedReason: `Consolidated into question ${newNodeId}`,
-              consolidatedIntoId: newNodeId
-            }
-          });
-        }
-      } catch (error) {
-        debugGraphPrimitiveFallback(
-          "[epistemicQuestions] Failed to archive linked question",
-          {
-            error: formatGraphPrimitiveError(error),
-            questionId: qid
-          }
-        );
-      }
-    }
+    await archiveConsolidatedQuestions(ctx, args.questionIds, newNodeId, now);
     await ctx.scheduler.runAfter(0, internal.neo4jSync.syncNodeToNeo4j, {
       nodeId: newNodeId,
       operation: "upsert"
@@ -1233,7 +1366,7 @@ var deleteQuestion = mutation({
   returns: permissiveReturn,
   handler: async (ctx, args) => {
     const node = await ctx.db.get(args.questionId);
-    if (!node || node.nodeType !== "question") {
+    if (!isQuestionNodeDoc(node)) {
       throw new Error("Question not found");
     }
     assertTenantPackWorkspaceMutationAllowed({
@@ -1242,7 +1375,7 @@ var deleteQuestion = mutation({
       mutationName: "epistemicQuestions.deleteQuestion"
     });
     const now = Date.now();
-    const meta = node.metadata || {};
+    const meta = toRecord(node.metadata);
     await ctx.db.patch(args.questionId, {
       status: "archived",
       updatedAt: now,
@@ -1283,16 +1416,22 @@ var markAnsweredWithArtifact = mutation({
   returns: permissiveReturn,
   handler: async (ctx, args) => {
     const node = await ctx.db.get(args.questionId);
-    if (!node || node.nodeType !== "question") {
+    if (!isQuestionNodeDoc(node)) {
       throw new Error("Question not found");
     }
-    const artifact = await resolveGraphPrimitivesAppResolvers().getFinalArtifact(ctx, args.artifactId);
+    const artifact = readFinalArtifactRow(
+      await resolveGraphPrimitivesAppResolvers().getFinalArtifact(
+        ctx,
+        args.artifactId
+      )
+    );
     if (!artifact) {
       throw new Error("Artifact not found");
     }
+    const nodeTopicId = normalizeQuestionTopicId(node.topicId);
     const scopeId = resolveQuestionScopeId({
-      projectId: node.projectId,
-      topicId: normalizeQuestionTopicId(node.topicId)
+      ...node.projectId ? { projectId: node.projectId } : {},
+      ...nodeTopicId ? { topicId: nodeTopicId } : {}
     });
     if (scopeId) {
       const hasAccess = await checkScopeAccess(ctx, scopeId, args.userId);
@@ -1301,7 +1440,7 @@ var markAnsweredWithArtifact = mutation({
       }
     }
     const now = Date.now();
-    const meta = node.metadata || {};
+    const meta = toRecord(node.metadata);
     await ctx.db.patch(args.questionId, {
       updatedAt: now,
       metadata: {
@@ -1352,10 +1491,10 @@ var getQuestionClusterPositions = query({
         }
       };
     }
-    const questionNodes = await ctx.db.query("epistemicNodes").withIndex(
+    const questionNodes = (await ctx.db.query("epistemicNodes").withIndex(
       "by_topic_type",
       (q) => q.eq("topicId", scope.topicId).eq("nodeType", "question")
-    ).collect();
+    ).collect()).filter(isQuestionNodeDoc);
     const activeQuestionNodes = questionNodes.filter(isActiveQuestionNode);
     const positions = {};
     let clusterCount = 0;
@@ -1363,8 +1502,8 @@ var getQuestionClusterPositions = query({
     let baselineCount = 0;
     for (const question of activeQuestionNodes) {
       const id = question._id.toString();
-      const meta = question.metadata || {};
-      const questionType = typeof question.questionType === "string" ? question.questionType : typeof meta.questionType === "string" ? meta.questionType : void 0;
+      const meta = toRecord(question.metadata);
+      const questionType = readQuestionType(question, meta);
       if (questionType === "belief_test" || meta.testType) {
         positions[id] = "cluster";
         clusterCount++;