@lucern/graph-primitives 1.0.0 → 1.0.1

package/dist/epistemicNodes.queries.js

@@ -0,0 +1,619 @@
+import { v } from 'convex/values';
+import { checkScopeAccess } from '@lucern/access-control/access';
+import { permissiveReturn } from '@lucern/contracts/schema-helpers/validators';
+import { componentsGeneric, queryGeneric, anyApi } from 'convex/server';
+
+// src/epistemicNodes.queries.ts
+var api = anyApi;
+componentsGeneric();
+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 debugGraphPrimitiveFallback(message, context) {
+  if (!isGraphPrimitiveDebugEnabled()) {
+    return;
+  }
+  console.debug(message, context ?? {});
+}
+var LEGACY_SCOPE_FIELD = "graphScopeProjectId";
+function asMappedProjectId(topic) {
+  if (!topic) {
+    return;
+  }
+  const directLegacyProjectId = normalizeScopeValue(topic[LEGACY_SCOPE_FIELD]);
+  if (directLegacyProjectId) {
+    return directLegacyProjectId;
+  }
+  const metadata = topic.metadata || {};
+  const candidate = metadata[LEGACY_SCOPE_FIELD] || metadata.legacyProjectId || metadata.projectId || metadata.scopeProjectId;
+  return candidate ? candidate : void 0;
+}
+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_FIELD, 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."
+  );
+}
+var optionalScopeArgs = {
+  projectId: v.optional(v.string()),
+  topicId: v.optional(v.string())
+};
+
+// src/epistemicNodes.helpers.ts
+var DEFAULT_NODE_PAGE_SIZE = 250;
+var MAX_NODE_PAGE_SIZE = 8e3;
+function clampNodeLimit(limit, fallback = DEFAULT_NODE_PAGE_SIZE) {
+  if (!Number.isFinite(limit)) {
+    return fallback;
+  }
+  return Math.max(1, Math.min(Math.floor(limit), MAX_NODE_PAGE_SIZE));
+}
+function dedupeWorkspaceNodes(nodes) {
+  const seen = /* @__PURE__ */ new Set();
+  const deduped = [];
+  for (const node of nodes) {
+    const key = String(node._id);
+    if (seen.has(key)) {
+      continue;
+    }
+    seen.add(key);
+    deduped.push(node);
+  }
+  return deduped;
+}
+function nodeMatchesWorkspaceReasoningScope(node, scope) {
+  return scope.topicId !== void 0 && node.topicId === scope.topicId || scope.projectId !== void 0 && node.projectId === scope.projectId;
+}
+async function collectScopedNodes(ctx, scope, args) {
+  const queries = [];
+  if (scope.topicId) {
+    queries.push(
+      args.nodeType ? ctx.db.query("epistemicNodes").withIndex(
+        "by_topic_type",
+        (q) => q.eq("topicId", scope.topicId).eq("nodeType", args.nodeType)
+      ).order("desc").take(args.scanLimit) : ctx.db.query("epistemicNodes").withIndex("by_topic", (q) => q.eq("topicId", scope.topicId)).order("desc").take(args.scanLimit)
+    );
+  }
+  if (scope.projectId && !scope.topicId) {
+    queries.push(
+      args.nodeType ? ctx.db.query("epistemicNodes").withIndex(
+        "by_topic_type",
+        (q) => q.eq("topicId", scope.projectId).eq("nodeType", args.nodeType)
+      ).order("desc").take(args.scanLimit) : ctx.db.query("epistemicNodes").withIndex("by_topic", (q) => q.eq("topicId", scope.projectId)).order("desc").take(args.scanLimit)
+    );
+  }
+  const combined = dedupeWorkspaceNodes((await Promise.all(queries)).flat());
+  return combined.filter(
+    (node) => nodeMatchesWorkspaceReasoningScope(node, scope)
+  );
+}
+v.union(
+  v.literal("L4"),
+  v.literal("L3"),
+  v.literal("L2"),
+  v.literal("L1"),
+  v.literal("ontological"),
+  v.literal("organizational")
+);
+v.union(v.literal("decision"));
+v.union(
+  v.literal("belief"),
+  v.literal("question"),
+  v.literal("theme"),
+  v.literal("deal")
+);
+v.union(
+  v.literal("claim"),
+  v.literal("evidence"),
+  v.literal("synthesis")
+);
+v.union(
+  v.literal("atomic_fact"),
+  v.literal("excerpt"),
+  v.literal("source")
+);
+v.union(
+  // L4: Audit targets
+  v.literal("decision"),
+  // L3: Traversal anchors
+  v.literal("belief"),
+  v.literal("question"),
+  v.literal("theme"),
+  v.literal("deal"),
+  // L2: Compression boundary
+  v.literal("claim"),
+  v.literal("evidence"),
+  v.literal("synthesis"),
+  v.literal("answer"),
+  // L1: Terminal leaves
+  v.literal("atomic_fact"),
+  v.literal("excerpt"),
+  v.literal("source")
+);
+v.union(
+  v.literal("company"),
+  v.literal("person"),
+  v.literal("investor"),
+  v.literal("function"),
+  v.literal("value_chain")
+);
+v.union(v.literal("topic"));
+var nodeTypeValidator = v.union(
+  // L4: Audit targets
+  v.literal("decision"),
+  // L3: Traversal anchors
+  v.literal("belief"),
+  v.literal("question"),
+  v.literal("theme"),
+  v.literal("deal"),
+  // L2: Compression boundary
+  v.literal("claim"),
+  v.literal("evidence"),
+  v.literal("synthesis"),
+  v.literal("answer"),
+  // L1: Terminal leaves
+  v.literal("atomic_fact"),
+  v.literal("excerpt"),
+  v.literal("source"),
+  // Ontological
+  v.literal("company"),
+  v.literal("person"),
+  v.literal("investor"),
+  v.literal("function"),
+  v.literal("value_chain"),
+  // Organizational
+  v.literal("topic")
+);
+v.union(
+  v.literal("human"),
+  v.literal("ai_extracted"),
+  v.literal("ai_generated"),
+  v.literal("imported"),
+  v.literal("system")
+  // System-generated (migrations, classifiers)
+);
+var statusValidator = v.union(
+  v.literal("active"),
+  v.literal("superseded"),
+  v.literal("archived"),
+  v.literal("deleted")
+);
+v.union(
+  v.literal("unverified"),
+  v.literal("human_verified"),
+  v.literal("ai_verified"),
+  v.literal("contradicted"),
+  v.literal("outdated")
+);
+
+// src/epistemicNodes.queries.ts
+var optionalNodeScopeArgs = optionalScopeArgs;
+var get = query({
+  args: { nodeId: v.id("epistemicNodes") },
+  returns: permissiveReturn,
+  handler: async (ctx, args) => {
+    return await ctx.db.get(args.nodeId);
+  }
+});
+var getByGlobalId = query({
+  args: { globalId: v.string() },
+  returns: permissiveReturn,
+  handler: async (ctx, args) => {
+    return await ctx.db.query("epistemicNodes").withIndex("by_globalId", (q) => q.eq("globalId", args.globalId)).first();
+  }
+});
+var getByContentHash = query({
+  args: { contentHash: v.string() },
+  returns: permissiveReturn,
+  handler: async (ctx, args) => {
+    return await ctx.db.query("epistemicNodes").withIndex("by_contentHash", (q) => q.eq("contentHash", args.contentHash)).collect();
+  }
+});
+var getByProjectAndType = query({
+  args: {
+    ...optionalNodeScopeArgs,
+    nodeType: nodeTypeValidator,
+    status: v.optional(statusValidator),
+    limit: v.optional(v.number())
+  },
+  returns: permissiveReturn,
+  handler: async (ctx, args) => {
+    if (!args.projectId && !args.topicId) {
+      return [];
+    }
+    let scope;
+    try {
+      scope = await resolveTopicProjectScope(ctx, {
+        projectId: args.projectId,
+        topicId: args.topicId
+      });
+    } catch (error) {
+      debugGraphPrimitiveFallback(
+        "[epistemicNodes] Failed to resolve getByProjectAndType scope",
+        {
+          error,
+          projectId: args.projectId,
+          topicId: args.topicId
+        }
+      );
+      return [];
+    }
+    const pageSize = clampNodeLimit(args.limit);
+    const scanLimit = Math.min(pageSize * 3, MAX_NODE_PAGE_SIZE);
+    const nodes = await collectScopedNodes(ctx, scope, {
+      nodeType: args.nodeType,
+      scanLimit
+    });
+    if (args.status) {
+      return nodes.filter(
+        (n) => n.status === args.status && nodeMatchesWorkspaceReasoningScope(n, scope)
+      ).slice(0, pageSize);
+    }
+    return nodes.filter(
+      (n) => n.status === "active" && nodeMatchesWorkspaceReasoningScope(n, scope)
+    ).slice(0, pageSize);
+  }
+});
+var getByProjectAndTypeLite = query({
+  args: {
+    ...optionalNodeScopeArgs,
+    nodeType: nodeTypeValidator,
+    status: v.optional(statusValidator),
+    limit: v.optional(v.number())
+  },
+  returns: permissiveReturn,
+  handler: async (ctx, args) => {
+    if (!args.projectId && !args.topicId) {
+      return [];
+    }
+    let scope;
+    try {
+      scope = await resolveTopicProjectScope(ctx, {
+        projectId: args.projectId,
+        topicId: args.topicId
+      });
+    } catch (error) {
+      debugGraphPrimitiveFallback(
+        "[epistemicNodes] Failed to resolve getByNodeType scope",
+        {
+          error,
+          projectId: args.projectId,
+          topicId: args.topicId
+        }
+      );
+      return [];
+    }
+    const pageSize = clampNodeLimit(args.limit);
+    const scanLimit = Math.min(pageSize * 3, MAX_NODE_PAGE_SIZE);
+    const query2 = ctx.db.query("epistemicNodes").withIndex(
+      "by_topic_type",
+      (q) => q.eq("topicId", scope.topicId).eq("nodeType", args.nodeType)
+    );
+    const nodes = await query2.order("desc").take(scanLimit);
+    const statusFiltered = args.status ? nodes.filter((n) => n.status === args.status) : nodes.filter((n) => n.status === "active");
+    const capped = statusFiltered.slice(0, pageSize);
+    return capped.map((n) => ({
+      _id: n._id,
+      globalId: n.globalId,
+      nodeType: n.nodeType,
+      createdBy: n.createdBy,
+      topicId: n.topicId,
+      projectId: n.projectId,
+      status: n.status,
+      epistemicLayer: n.epistemicLayer
+    }));
+  }
+});
+var getByProject = query({
+  args: {
+    ...optionalNodeScopeArgs,
+    userId: v.optional(v.string()),
+    includeArchived: v.optional(v.boolean()),
+    limit: v.optional(v.number())
+  },
+  returns: permissiveReturn,
+  handler: async (ctx, args) => {
+    if (!args.projectId && !args.topicId) {
+      return [];
+    }
+    const pageSize = clampNodeLimit(args.limit);
+    const scanLimit = Math.min(pageSize * 3, MAX_NODE_PAGE_SIZE);
+    let scope;
+    try {
+      scope = await resolveTopicProjectScope(ctx, {
+        projectId: args.projectId,
+        topicId: args.topicId
+      });
+    } catch (error) {
+      debugGraphPrimitiveFallback("[epistemicNodes] Failed to resolve list scope", {
+        error,
+        projectId: args.projectId,
+        topicId: args.topicId
+      });
+      return [];
+    }
+    if (args.userId) {
+      const hasAccess = await checkScopeAccess(
+        ctx,
+        String(scope.topicId ?? scope.projectId),
+        args.userId
+      );
+      if (!hasAccess) {
+        return [];
+      }
+    }
+    const nodes = await collectScopedNodes(ctx, scope, { scanLimit });
+    if (args.includeArchived) {
+      return nodes.filter(
+        (n) => n.status !== "deleted" && nodeMatchesWorkspaceReasoningScope(n, scope)
+      ).slice(0, pageSize);
+    }
+    return nodes.filter(
+      (n) => n.status === "active" && nodeMatchesWorkspaceReasoningScope(n, scope)
+    ).slice(0, pageSize);
+  }
+});
+var listAll = query({
+  args: {
+    limit: v.optional(v.number())
+  },
+  returns: permissiveReturn,
+  handler: async (ctx, args) => {
+    const pageSize = clampNodeLimit(args.limit ?? 2e3);
+    const scanLimit = Math.min(pageSize * 2, MAX_NODE_PAGE_SIZE * 2);
+    const nodes = await ctx.db.query("epistemicNodes").order("desc").take(scanLimit);
+    return nodes.filter((n) => n.status === "active").slice(0, pageSize);
+  }
+});
+var search = query({
+  args: {
+    searchQuery: v.string(),
+    ...optionalNodeScopeArgs,
+    nodeType: v.optional(nodeTypeValidator),
+    limit: v.optional(v.number())
+  },
+  returns: permissiveReturn,
+  handler: async (ctx, args) => {
+    const pageSize = clampNodeLimit(args.limit, 100);
+    let scope;
+    if (args.projectId || args.topicId) {
+      try {
+        scope = await resolveTopicProjectScope(ctx, {
+          projectId: args.projectId,
+          topicId: args.topicId
+        });
+      } catch (error) {
+        debugGraphPrimitiveFallback(
+          "[epistemicNodes] Failed to resolve search scope",
+          {
+            error,
+            projectId: args.projectId,
+            topicId: args.topicId
+          }
+        );
+        return [];
+      }
+    }
+    const searchResults = ctx.db.query("epistemicNodes").withSearchIndex("search_canonicalText", (q) => {
+      let search2 = q.search("canonicalText", args.searchQuery);
+      if (scope?.topicId) {
+        search2 = search2.eq("topicId", scope.topicId);
+      } else if (scope?.projectId) {
+        search2 = search2.eq("projectId", scope.projectId);
+      }
+      if (args.nodeType) {
+        search2 = search2.eq("nodeType", args.nodeType);
+      }
+      return search2.eq("status", "active");
+    });
+    return await searchResults.take(pageSize);
+  }
+});
+
+export { get, getByContentHash, getByGlobalId, getByProject, getByProjectAndType, getByProjectAndTypeLite, listAll, search };
+//# sourceMappingURL=epistemicNodes.queries.js.map
+//# sourceMappingURL=epistemicNodes.queries.js.map