@lucern/graph-primitives 1.0.0 → 1.0.1

package/dist/epistemicQuestions.conviction.js

@@ -0,0 +1,1389 @@
+import { v } from 'convex/values';
+import { checkScopeAccess } from '@lucern/access-control/access';
+import { permissiveReturn } from '@lucern/contracts/schema-helpers/validators';
+import { componentsGeneric, anyApi, mutationGeneric, queryGeneric } from 'convex/server';
+
+// src/epistemicQuestions.conviction.ts
+var api = anyApi;
+componentsGeneric();
+var internal = anyApi;
+var mutation = mutationGeneric;
+var query = queryGeneric;
+
+// src/debug.ts
+function isGraphPrimitiveDebugEnabled() {
+  const env = globalThis.process?.env;
+  return env?.LUCERN_COMPAT_FALLBACK_DEBUG === "1" || env?.LUCERN_GRAPH_DEBUG === "1";
+}
+function formatGraphPrimitiveError(error) {
+  if (error instanceof Error) {
+    return `${error.name}: ${error.message}`;
+  }
+  if (typeof error === "string") {
+    return error;
+  }
+  if (error === null) {
+    return "null";
+  }
+  if (error === void 0) {
+    return "undefined";
+  }
+  try {
+    return JSON.stringify(error);
+  } catch {
+    return Object.prototype.toString.call(error);
+  }
+}
+function debugGraphPrimitiveFallback(message, context) {
+  if (!isGraphPrimitiveDebugEnabled()) {
+    return;
+  }
+  console.debug(message, context ?? {});
+}
+
+// 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;
+}
+function isMissingLucernChildComponentError(error) {
+  const message = getErrorMessage(error);
+  return message.includes(
+    'Child component ComponentName(Identifier("lucern")) not found'
+  ) || message.includes("Child component") && message.includes("lucern") && message.includes("not found");
+}
+function getErrorMessage(error) {
+  if (error instanceof Error) {
+    return error.message;
+  }
+  if (typeof error === "object" && error !== null && "message" in error && typeof error.message === "string") {
+    return error.message;
+  }
+  return "unknown error";
+}
+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 (error) {
+      debugGraphPrimitiveFallback(
+        "[topicProjectOverlay] Failed to resolve topic by direct ID",
+        {
+          error,
+          scopeId
+        }
+      );
+    }
+  }
+  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 (error) {
+    debugGraphPrimitiveFallback(
+      "[topicProjectOverlay] Failed to resolve topic by ID query",
+      {
+        error,
+        scopeId
+      }
+    );
+  }
+  try {
+    const topic = await ctx.runQuery(api.topics.getByLegacyScopeId, {
+      projectId: String(scopeId)
+    });
+    if (topic?.name !== void 0 && topic?.type !== void 0) {
+      return topic;
+    }
+  } catch (error) {
+    debugGraphPrimitiveFallback(
+      "[topicProjectOverlay] Failed to resolve topic by legacy scope ID",
+      { error, scopeId }
+    );
+  }
+  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 (error) {
+      debugGraphPrimitiveFallback(
+        "[topicProjectOverlay] Failed to read topics table; falling back to API",
+        { error }
+      );
+      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));
+}
+async function patchTopicProjectOverlay(ctx, scopeId, value) {
+  const topic = await resolveTopicDoc(ctx, scopeId);
+  if (!topic) {
+    return null;
+  }
+  const nextMetadata = { ...readMetadata(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 = 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;
+        }
+    }
+  }
+  patch.updatedAt = Date.now();
+  patch.metadata = nextMetadata;
+  topicUpdateArgs.metadata = nextMetadata;
+  if (typeof ctx.runMutation === "function") {
+    try {
+      await ctx.runMutation(api.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 materializeTopicProjectOverlay({
+    ...topic,
+    ...patch,
+    metadata: nextMetadata
+  });
+}
+
+// src/resolvers.ts
+function isMissingLucernChildComponentError2(error) {
+  const message = getErrorMessage2(error);
+  return message.includes(
+    'Child component ComponentName(Identifier("lucern")) not found'
+  ) || message.includes("Child component") && message.includes("lucern") && message.includes("not found");
+}
+function getErrorMessage2(error) {
+  if (error instanceof Error) {
+    return error.message;
+  }
+  if (typeof error === "object" && error !== null && "message" in error && typeof error.message === "string") {
+    return error.message;
+  }
+  return "unknown error";
+}
+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: getErrorMessage2(error)
+      }
+    );
+  }
+}
+function defaultResolvers() {
+  return {
+    getProject: (ctx, projectId) => resolveTopicProjectOverlay(ctx, projectId, {
+      idMode: "legacy",
+      projectLikeOnly: false
+    }),
+    patchProject: (ctx, projectId, value) => patchProjectWithTolerance(ctx, projectId, value),
+    listTopics: (ctx) => listTopicProjectOverlays(ctx, {
+      idMode: "legacy"
+    }),
+    getFinalArtifact: (ctx, artifactId) => ctx.db.get(artifactId)
+  };
+}
+var resolverOverrides = {};
+function resolveGraphPrimitivesAppResolvers(_ctx) {
+  return {
+    ...defaultResolvers(),
+    ...resolverOverrides
+  };
+}
+var LEGACY_SCOPE_FIELD2 = "graphScopeProjectId";
+function asMappedProjectId(topic) {
+  if (!topic) {
+    return;
+  }
+  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;
+}
+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_FIELD2, scopeId)
+    ).collect();
+  } catch (error) {
+    debugGraphPrimitiveFallback(
+      "[topicScope] Failed to resolve scope alias via index",
+      {
+        error,
+        scopeId
+      }
+    );
+    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(api.topics.get, {
+      id: topicId
+    }) ?? null;
+  } catch (error) {
+    debugGraphPrimitiveFallback(
+      "[topicScope] Failed to resolve topic by host query",
+      {
+        error,
+        topicId
+      }
+    );
+    return null;
+  }
+}
+async function tryResolveHostTopicByLegacyScope(ctx, legacyScopeId) {
+  if (typeof ctx.runQuery !== "function") {
+    return null;
+  }
+  try {
+    return await ctx.runQuery(api.topics.getByLegacyScopeId, {
+      projectId: legacyScopeId
+    }) ?? null;
+  } catch (error) {
+    debugGraphPrimitiveFallback(
+      "[topicScope] Failed to resolve topic by legacy scope",
+      {
+        error,
+        legacyScopeId
+      }
+    );
+    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 (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) {
+      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 (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"
+      };
+    }
+    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."
+  );
+}
+({
+  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;
+  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");
+}
+function buildTestsEdgeGlobalId(fromGlobalId, toGlobalId) {
+  return `edge-${fromGlobalId}-tests-${toGlobalId}`;
+}
+async function markProjectGraphDirty(ctx, projectId, topicId) {
+  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) {
+    return;
+  }
+  if (normalizedProjectId) {
+    await ctx.scheduler.runAfter(
+      0,
+      internal.graphAnalysisCache.markCacheStaleInternal,
+      {
+        projectId: normalizedProjectId
+      }
+    );
+  }
+  if (normalizedTopicId) {
+    await ctx.scheduler.runAfter(
+      0,
+      internal.graphAnalysisCache.markCacheStaleByTopic,
+      {
+        topicId: normalizedTopicId
+      }
+    );
+  }
+  await resolveGraphPrimitivesAppResolvers().patchProject(
+    ctx,
+    normalizedTopicId ?? normalizedProjectId,
+    {
+      lastActivityAt: Date.now()
+    }
+  );
+}
+function dedupeQuestionNodes(nodes) {
+  const seen = /* @__PURE__ */ new Set();
+  const deduped = [];
+  for (const node of nodes) {
+    const id = String(node._id);
+    if (seen.has(id)) {
+      continue;
+    }
+    seen.add(id);
+    deduped.push(node);
+  }
+  return deduped;
+}
+function normalizeQuestionTopicId(topicId) {
+  return typeof topicId === "string" && topicId.trim().length > 0 ? topicId : void 0;
+}
+function resolveQuestionScopeId(scope) {
+  return normalizeQuestionTopicId(scope.topicId) ?? scope.projectId ?? void 0;
+}
+function logQuestionFallback(message, error, context) {
+  debugGraphPrimitiveFallback(message, {
+    error: formatGraphPrimitiveError(error),
+    ...context ?? {}
+  });
+}
+async function resolveQuestionScopeOrNull(ctx, args) {
+  if (!args.projectId && !args.topicId) {
+    return null;
+  }
+  try {
+    return await resolveTopicProjectScope(ctx, {
+      projectId: args.projectId ?? void 0,
+      topicId: args.topicId ?? void 0
+    });
+  } catch (error) {
+    debugGraphPrimitiveFallback(
+      "[epistemicQuestions] Failed to resolve question scope",
+      {
+        error: formatGraphPrimitiveError(error),
+        projectId: args.projectId,
+        topicId: args.topicId
+      }
+    );
+    return null;
+  }
+}
+async function getQuestionNodesForScope(ctx, scope, args) {
+  const fetchNodes = (query2) => query2.collect();
+  const topicNodes = await fetchNodes(
+    ctx.db.query("epistemicNodes").withIndex(
+      "by_topic_type",
+      (q) => q.eq("topicId", scope.topicId).eq("nodeType", "question")
+    )
+  );
+  return dedupeQuestionNodes(topicNodes).filter(
+    (node) => questionMatchesScope(node, scope)
+  );
+}
+function questionMatchesScope(node, scope) {
+  return scope.topicId !== void 0 && node.topicId === scope.topicId || scope.projectId !== void 0 && node.projectId === scope.projectId;
+}
+function buildLinkedWorktreeMetadata(linkedWorktreeId) {
+  return linkedWorktreeId ? {
+    linkedWorktreeId
+  } : {};
+}
+
+// src/epistemicQuestions.conviction.ts
+var advanceToConviction = mutation({
+  args: {
+    questionId: v.id("epistemicNodes"),
+    userId: v.string(),
+    sprintId: v.optional(v.string()),
+    worktreeId: v.optional(v.string())
+  },
+  returns: permissiveReturn,
+  handler: async (ctx, args) => {
+    const node = await ctx.db.get(args.questionId);
+    if (!node || node.nodeType !== "question") {
+      throw new Error("Question not found");
+    }
+    const meta = node.metadata || {};
+    if (meta.convictionStage === "in_conviction" || meta.convictionStage === "scored") {
+      throw new Error("Question is already in conviction stage");
+    }
+    const now = Date.now();
+    await ctx.db.patch(args.questionId, {
+      updatedAt: now,
+      metadata: {
+        ...meta,
+        convictionStage: "in_conviction",
+        convictionAdvancedAt: now,
+        convictionAdvancedBy: args.userId,
+        ...buildLinkedWorktreeMetadata(args.worktreeId ?? args.sprintId)
+      }
+    });
+    try {
+      await ctx.db.insert("epistemicAudit", {
+        entityType: "question",
+        entityId: args.questionId,
+        changeType: "status_changed",
+        changedAt: now,
+        changedBy: args.userId,
+        isAgent: false,
+        projectId: node.projectId,
+        previousState: {
+          convictionStage: meta.convictionStage || "researching"
+        },
+        newState: { convictionStage: "in_conviction" },
+        triggeringAction: "question_advanced_to_conviction"
+      });
+    } catch (e) {
+      logQuestionFallback(
+        "[epistemicQuestions] Failed to log advanceToConviction audit",
+        e,
+        {
+          questionId: args.questionId,
+          projectId: node.projectId
+        }
+      );
+      console.error("[EpistemicAudit] Failed to log advanceToConviction:", e);
+    }
+    await markProjectGraphDirty(ctx, node.projectId, node.topicId);
+    return {
+      questionId: args.questionId,
+      convictionStage: "in_conviction",
+      advancedAt: now
+    };
+  }
+});
+var updateConviction = mutation({
+  args: {
+    questionId: v.id("epistemicNodes"),
+    conviction: v.optional(v.number()),
+    answerCompleteness: v.optional(
+      v.union(
+        v.literal("unanswered"),
+        v.literal("partial"),
+        v.literal("sufficient"),
+        v.literal("comprehensive")
+      )
+    ),
+    convictionRationale: v.optional(v.string()),
+    userId: v.string()
+  },
+  returns: permissiveReturn,
+  handler: async (ctx, args) => {
+    const node = await ctx.db.get(args.questionId);
+    if (!node || node.nodeType !== "question") {
+      throw new Error("Question not found");
+    }
+    const now = Date.now();
+    const meta = node.metadata || {};
+    const updates = { ...meta };
+    if (args.conviction !== void 0) {
+      updates.conviction = Math.max(0, Math.min(1, args.conviction));
+    }
+    if (args.answerCompleteness !== void 0) {
+      updates.answerCompleteness = args.answerCompleteness;
+    }
+    if (args.convictionRationale !== void 0) {
+      updates.convictionRationale = args.convictionRationale;
+    }
+    updates.convictionUpdatedAt = now;
+    updates.convictionUpdatedBy = args.userId;
+    await ctx.db.patch(args.questionId, {
+      updatedAt: now,
+      metadata: updates
+    });
+    await markProjectGraphDirty(ctx, node.projectId, node.topicId);
+    return {
+      questionId: args.questionId,
+      conviction: updates.conviction ?? meta.conviction,
+      answerCompleteness: updates.answerCompleteness ?? meta.answerCompleteness
+    };
+  }
+});
+var finalizeConviction = mutation({
+  args: {
+    questionId: v.id("epistemicNodes"),
+    conviction: v.number(),
+    answer: v.string(),
+    convictionRationale: v.optional(v.string()),
+    userId: v.string(),
+    answerCompleteness: v.optional(
+      v.union(
+        v.literal("unanswered"),
+        v.literal("partial"),
+        v.literal("sufficient"),
+        v.literal("comprehensive"),
+        v.literal("unanswerable")
+      )
+    ),
+    whatWeNeed: v.optional(v.string())
+  },
+  returns: permissiveReturn,
+  handler: async (ctx, args) => {
+    const node = await ctx.db.get(args.questionId);
+    if (!node || node.nodeType !== "question") {
+      throw new Error("Question not found");
+    }
+    const now = Date.now();
+    const clampedConviction = Math.max(0, Math.min(1, args.conviction));
+    const isUnanswerable = args.answerCompleteness === "unanswerable";
+    const meta = node.metadata || {};
+    let completeness = args.answerCompleteness;
+    if (!completeness) {
+      completeness = clampedConviction >= 0.8 ? "comprehensive" : clampedConviction >= 0.6 ? "sufficient" : clampedConviction >= 0.3 ? "partial" : "unanswered";
+    }
+    await ctx.db.patch(args.questionId, {
+      updatedAt: now,
+      metadata: {
+        ...meta,
+        convictionStage: "scored",
+        conviction: clampedConviction,
+        convictionRationale: args.convictionRationale,
+        convictionUpdatedAt: now,
+        convictionUpdatedBy: args.userId,
+        answer: args.answer,
+        answerStatus: "final",
+        questionStatus: isUnanswerable ? "blocked" : "answered",
+        answeredAt: now,
+        answeredBy: args.userId,
+        answerCompleteness: completeness,
+        whatWeNeed: args.whatWeNeed
+      }
+    });
+    try {
+      await ctx.db.insert("epistemicAudit", {
+        entityType: "question",
+        entityId: args.questionId,
+        changeType: "status_changed",
+        changedAt: now,
+        changedBy: args.userId,
+        isAgent: false,
+        projectId: node.projectId,
+        previousState: {
+          convictionStage: meta.convictionStage || "in_conviction"
+        },
+        newState: {
+          convictionStage: "scored",
+          conviction: clampedConviction
+        },
+        triggeringAction: "question_conviction_finalized"
+      });
+    } catch (e) {
+      logQuestionFallback(
+        "[epistemicQuestions] Failed to log finalizeConviction audit",
+        e,
+        {
+          questionId: args.questionId,
+          projectId: node.projectId
+        }
+      );
+      console.error("[EpistemicAudit] Failed to log finalizeConviction:", e);
+    }
+    if (node.projectId || node.topicId) {
+      const beliefId = meta.linkedBeliefNodeId || meta.linkedBeliefId || meta.beliefId;
+      if (beliefId) {
+        try {
+          await ctx.scheduler.runAfter(
+            0,
+            internal.epistemicQuestions.createEvidenceFromScoredQuestion,
+            {
+              questionNodeId: args.questionId,
+              questionText: node.canonicalText || "",
+              answerText: args.answer,
+              beliefId,
+              relatedBeliefIds: meta.relatedBeliefIds || [],
+              conviction: clampedConviction,
+              rationale: args.convictionRationale || "",
+              projectId: node.projectId,
+              topicId: normalizeQuestionTopicId(node.topicId),
+              userId: args.userId
+            }
+          );
+        } catch (e) {
+          logQuestionFallback(
+            "[epistemicQuestions] Failed to schedule evidence creation from scored question",
+            e,
+            {
+              questionId: args.questionId,
+              beliefId,
+              projectId: node.projectId
+            }
+          );
+          console.error(
+            "[finalizeConviction] Failed to schedule evidence creation:",
+            e
+          );
+        }
+      }
+    }
+    await ctx.scheduler.runAfter(0, internal.neo4jSync.syncNodeToNeo4j, {
+      nodeId: args.questionId,
+      operation: "upsert"
+    });
+    await markProjectGraphDirty(ctx, node.projectId, node.topicId);
+    return {
+      questionId: args.questionId,
+      convictionStage: "scored",
+      conviction: clampedConviction
+    };
+  }
+});
+var getByBeliefWithAccess = query({
+  args: {
+    beliefId: v.string(),
+    userId: v.string()
+  },
+  returns: permissiveReturn,
+  handler: async (ctx, args) => {
+    let beliefNode = null;
+    try {
+      beliefNode = await ctx.db.get(args.beliefId);
+    } catch (error) {
+      debugGraphPrimitiveFallback(
+        "[epistemicQuestions] Failed to resolve belief node directly",
+        {
+          error: formatGraphPrimitiveError(error),
+          beliefId: args.beliefId
+        }
+      );
+      try {
+        beliefNode = await ctx.db.get(args.beliefId);
+      } catch (legacyError) {
+        debugGraphPrimitiveFallback(
+          "[epistemicQuestions] Failed to resolve legacy belief node",
+          {
+            error: formatGraphPrimitiveError(legacyError),
+            beliefId: args.beliefId
+          }
+        );
+        return [];
+      }
+    }
+    if (!beliefNode) {
+      return [];
+    }
+    const scope = await resolveQuestionScopeOrNull(ctx, {
+      projectId: beliefNode.projectId,
+      topicId: normalizeQuestionTopicId(beliefNode.topicId)
+    });
+    const scopeId = scope ? resolveQuestionScopeId(scope) : void 0;
+    if (!scope || !scopeId) {
+      return [];
+    }
+    const hasAccess = await checkScopeAccess(ctx, scopeId, args.userId);
+    if (!hasAccess) {
+      return [];
+    }
+    const questionNodes = await getQuestionNodesForScope(ctx, scope);
+    const beliefIdStr = String(args.beliefId);
+    return questionNodes.filter((q) => {
+      const meta = q.metadata || {};
+      if (String(meta.linkedBeliefNodeId || "") === beliefIdStr) {
+        return true;
+      }
+      if (String(meta.linkedBeliefId || "") === beliefIdStr) {
+        return true;
+      }
+      if (String(meta.beliefId || "") === beliefIdStr) {
+        return true;
+      }
+      const relatedIds = meta.relatedBeliefIds || [];
+      if (relatedIds.some((id) => String(id) === beliefIdStr)) {
+        return true;
+      }
+      return false;
+    });
+  }
+});
+var updateQuestion = mutation({
+  args: {
+    questionId: v.id("epistemicNodes"),
+    question: v.optional(v.string()),
+    category: v.optional(
+      v.union(
+        v.literal("market"),
+        v.literal("competition"),
+        v.literal("product"),
+        v.literal("team"),
+        v.literal("financials"),
+        v.literal("financial"),
+        v.literal("regulatory"),
+        v.literal("timing"),
+        v.literal("customer"),
+        v.literal("technology"),
+        v.literal("distribution"),
+        v.literal("strategic"),
+        v.literal("other")
+      )
+    ),
+    priority: v.optional(
+      v.union(v.literal("high"), v.literal("medium"), v.literal("low"))
+    )
+  },
+  returns: permissiveReturn,
+  handler: async (ctx, args) => {
+    const node = await ctx.db.get(args.questionId);
+    if (!node || node.nodeType !== "question") {
+      throw new Error("Question not found");
+    }
+    const now = Date.now();
+    const meta = node.metadata || {};
+    const metaUpdates = { ...meta };
+    if (args.category) {
+      const category = args.category === "financial" ? "financials" : args.category;
+      metaUpdates.category = category;
+    }
+    if (args.priority) {
+      metaUpdates.priority = args.priority;
+    }
+    const patchData = {
+      updatedAt: now,
+      metadata: metaUpdates
+    };
+    if (args.question !== void 0) {
+      patchData.canonicalText = args.question;
+      patchData.contentHash = generateContentHash(args.question);
+      if (node.sourceType === "ai_generated") {
+        patchData.sourceType = "human";
+      }
+    }
+    await ctx.db.patch(args.questionId, patchData);
+    await ctx.scheduler.runAfter(0, internal.neo4jSync.syncNodeToNeo4j, {
+      nodeId: args.questionId,
+      operation: "upsert"
+    });
+    await markProjectGraphDirty(ctx, node.projectId, node.topicId);
+  }
+});
+var linkToBelief = mutation({
+  args: {
+    questionId: v.id("epistemicNodes"),
+    beliefId: v.string(),
+    // Accept string for backward compat
+    userId: v.string(),
+    testType: v.optional(
+      v.union(
+        v.literal("validates"),
+        v.literal("invalidates"),
+        v.literal("clarifies")
+      )
+    ),
+    answerImpact: v.optional(
+      v.object({
+        ifYes: v.string(),
+        ifNo: v.string()
+      })
+    ),
+    isPrimaryBelief: v.optional(v.boolean())
+  },
+  returns: permissiveReturn,
+  handler: async (ctx, args) => {
+    const questionNode = await ctx.db.get(args.questionId);
+    if (!questionNode || questionNode.nodeType !== "question") {
+      throw new Error("Question not found");
+    }
+    const questionScopeId = resolveQuestionScopeId({
+      projectId: questionNode.projectId,
+      topicId: normalizeQuestionTopicId(questionNode.topicId)
+    });
+    if (questionScopeId) {
+      const hasAccess = await checkScopeAccess(
+        ctx,
+        questionScopeId,
+        args.userId
+      );
+      if (!hasAccess) {
+        throw new Error("Access denied");
+      }
+    }
+    let beliefNode = null;
+    try {
+      beliefNode = await ctx.db.get(args.beliefId);
+    } catch (error) {
+      debugGraphPrimitiveFallback(
+        "[epistemicQuestions] Failed to resolve belief node directly",
+        {
+          error: formatGraphPrimitiveError(error),
+          beliefId: args.beliefId
+        }
+      );
+      try {
+        beliefNode = await ctx.db.get(args.beliefId);
+      } catch (legacyError) {
+        debugGraphPrimitiveFallback(
+          "[epistemicQuestions] Failed to resolve legacy belief node",
+          {
+            error: formatGraphPrimitiveError(legacyError),
+            beliefId: args.beliefId
+          }
+        );
+        throw new Error("Belief not found");
+      }
+    }
+    if (!beliefNode) {
+      throw new Error("Belief not found");
+    }
+    const now = Date.now();
+    const meta = questionNode.metadata || {};
+    const currentBeliefs = meta.relatedBeliefIds || [];
+    const beliefIdStr = String(args.beliefId);
+    const newRelated = currentBeliefs.includes(beliefIdStr) ? currentBeliefs : [...currentBeliefs, beliefIdStr];
+    const metaUpdates = {
+      ...meta,
+      relatedBeliefIds: newRelated
+    };
+    if (args.isPrimaryBelief || args.testType) {
+      metaUpdates.linkedBeliefNodeId = args.beliefId;
+      metaUpdates.linkedBeliefId = args.beliefId;
+      metaUpdates.questionType = "belief_test";
+      if (args.testType) {
+        metaUpdates.testType = args.testType;
+      }
+      if (args.answerImpact) {
+        metaUpdates.answerImpact = args.answerImpact;
+      }
+    }
+    await ctx.db.patch(args.questionId, {
+      updatedAt: now,
+      metadata: metaUpdates
+    });
+    try {
+      const beliefGlobalId = beliefNode.globalId;
+      if (beliefGlobalId && questionNode.globalId) {
+        await ctx.scheduler.runAfter(0, internal.neo4jSync.syncNodeToNeo4j, {
+          nodeId: args.questionId,
+          operation: "upsert"
+        });
+        await ctx.scheduler.runAfter(100, internal.neo4jSync.syncNodeToNeo4j, {
+          nodeId: args.beliefId,
+          operation: "upsert"
+        });
+        const edgeGlobalId = buildTestsEdgeGlobalId(
+          questionNode.globalId,
+          beliefGlobalId
+        );
+        await ctx.scheduler.runAfter(250, internal.neo4jEdgeAPI.createEdge, {
+          globalId: edgeGlobalId,
+          fromGlobalId: questionNode.globalId,
+          toGlobalId: beliefGlobalId,
+          edgeType: "tests",
+          context: args.testType || "tests",
+          topicId: questionNode.projectId ? String(questionNode.projectId) : void 0,
+          createdBy: args.userId,
+          fromNodeType: "question",
+          toNodeType: "belief",
+          fromLayer: "L3",
+          toLayer: "L3"
+        });
+      }
+    } catch (e) {
+      logQuestionFallback(
+        "[epistemicQuestions] Failed to create tests edge",
+        e,
+        {
+          questionId: args.questionId,
+          beliefId: args.beliefId
+        }
+      );
+      console.error("[linkToBelief] Failed to create tests edge:", e);
+    }
+    await markProjectGraphDirty(
+      ctx,
+      questionNode.projectId,
+      questionNode.topicId
+    );
+  }
+});
+var linkToInsight = mutation({
+  args: {
+    questionId: v.id("epistemicNodes"),
+    insightId: v.id("epistemicNodes"),
+    userId: v.string(),
+    sprintId: v.optional(v.string()),
+    worktreeId: v.optional(v.string()),
+    relevance: v.optional(v.number()),
+    rationale: v.optional(v.string())
+  },
+  returns: permissiveReturn,
+  handler: async (ctx, args) => {
+    const questionNode = await ctx.db.get(args.questionId);
+    if (!questionNode || questionNode.nodeType !== "question") {
+      throw new Error("Question not found");
+    }
+    const insight = await ctx.db.get(args.insightId);
+    if (!insight) {
+      throw new Error("Insight not found");
+    }
+    const questionScopeId = resolveQuestionScopeId({
+      projectId: questionNode.projectId,
+      topicId: normalizeQuestionTopicId(questionNode.topicId)
+    });
+    if (questionScopeId) {
+      const hasAccess = await checkScopeAccess(
+        ctx,
+        questionScopeId,
+        args.userId
+      );
+      if (!hasAccess) {
+        throw new Error("Access denied");
+      }
+    }
+    const now = Date.now();
+    const meta = questionNode.metadata || {};
+    const currentInsights = meta.relatedInsightIds || [];
+    const insightIdStr = String(args.insightId);
+    if (!currentInsights.includes(insightIdStr)) {
+      await ctx.db.patch(args.questionId, {
+        updatedAt: now,
+        metadata: {
+          ...meta,
+          relatedInsightIds: [...currentInsights, insightIdStr]
+        }
+      });
+      try {
+        const existingLinks = await ctx.db.query("questionEvidenceLinks").withIndex(
+          "by_questionId",
+          (q) => q.eq("questionId", args.questionId)
+        ).collect();
+        const duplicate = existingLinks.find(
+          (link) => String(link.insightId) === String(args.insightId)
+        );
+        if (!duplicate) {
+          await ctx.db.insert("questionEvidenceLinks", {
+            questionId: args.questionId,
+            insightId: args.insightId,
+            helpsAnswer: true,
+            relevance: args.relevance ?? 0.7,
+            rationale: args.rationale || "Linked from research results",
+            createdBy: args.userId,
+            createdAt: now
+          });
+        }
+      } catch (e) {
+        console.error(
+          "[linkToInsight] Failed to create questionEvidenceLink:",
+          e
+        );
+      }
+    }
+    await markProjectGraphDirty(
+      ctx,
+      questionNode.projectId,
+      questionNode.topicId
+    );
+  }
+});
+var unlinkInsight = mutation({
+  args: {
+    questionId: v.id("epistemicNodes"),
+    insightId: v.id("epistemicNodes"),
+    userId: v.string()
+  },
+  returns: permissiveReturn,
+  handler: async (ctx, args) => {
+    const questionNode = await ctx.db.get(args.questionId);
+    if (!questionNode || questionNode.nodeType !== "question") {
+      throw new Error("Question not found");
+    }
+    const questionScopeId = resolveQuestionScopeId({
+      projectId: questionNode.projectId,
+      topicId: normalizeQuestionTopicId(questionNode.topicId)
+    });
+    if (questionScopeId) {
+      const hasAccess = await checkScopeAccess(
+        ctx,
+        questionScopeId,
+        args.userId
+      );
+      if (!hasAccess) {
+        throw new Error("Access denied");
+      }
+    }
+    const now = Date.now();
+    const meta = questionNode.metadata || {};
+    const currentInsights = meta.relatedInsightIds || [];
+    const newInsights = currentInsights.filter(
+      (id) => String(id) !== String(args.insightId)
+    );
+    await ctx.db.patch(args.questionId, {
+      updatedAt: now,
+      metadata: {
+        ...meta,
+        relatedInsightIds: newInsights
+      }
+    });
+    try {
+      const links = await ctx.db.query("questionEvidenceLinks").withIndex(
+        "by_questionId",
+        (q) => q.eq("questionId", args.questionId)
+      ).collect();
+      for (const link of links) {
+        if (String(link.insightId) === String(args.insightId)) {
+          await ctx.db.delete(link._id);
+        }
+      }
+    } catch (e) {
+      logQuestionFallback(
+        "[epistemicQuestions] Failed to remove questionEvidenceLink",
+        e,
+        {
+          questionId: args.questionId,
+          insightId: args.insightId
+        }
+      );
+      console.error(
+        "[unlinkInsight] Failed to remove questionEvidenceLink:",
+        e
+      );
+    }
+    try {
+      const evidenceNode = await ctx.db.get(args.insightId);
+      if (evidenceNode && evidenceNode.nodeType === "evidence") {
+        const edges = await ctx.db.query("epistemicEdges").withIndex(
+          "by_from_to",
+          (q) => q.eq("fromNodeId", evidenceNode._id).eq("toNodeId", args.questionId)
+        ).collect();
+        for (const edge of edges) {
+          if (edge.edgeType === "derived_from") {
+            await ctx.scheduler.runAfter(0, internal.neo4jEdgeAPI.deleteEdge, {
+              globalId: edge.globalId
+            });
+            await ctx.db.delete(edge._id);
+          }
+        }
+      }
+    } catch (e) {
+      logQuestionFallback(
+        "[epistemicQuestions] Failed to remove derived edge",
+        e,
+        {
+          questionId: args.questionId,
+          insightId: args.insightId
+        }
+      );
+      console.error("[unlinkInsight] Failed to remove edge:", e);
+    }
+    await markProjectGraphDirty(
+      ctx,
+      questionNode.projectId,
+      questionNode.topicId
+    );
+  }
+});
+
+export { advanceToConviction, finalizeConviction, getByBeliefWithAccess, linkToBelief, linkToInsight, unlinkInsight, updateConviction, updateQuestion };
+//# sourceMappingURL=epistemicQuestions.conviction.js.map
+//# sourceMappingURL=epistemicQuestions.conviction.js.map