@lucern/graph-primitives 1.0.0 → 1.0.1

package/dist/epistemicNodes.internal.js

@@ -0,0 +1,658 @@
+import { v } from 'convex/values';
+import { componentsGeneric, anyApi, internalMutationGeneric, internalQueryGeneric } from 'convex/server';
+import { permissiveReturn } from '@lucern/contracts/schema-helpers/validators';
+
+// src/epistemicNodes.internal.ts
+var api = anyApi;
+componentsGeneric();
+var internal = anyApi;
+var internalMutation = internalMutationGeneric;
+var internalQuery = internalQueryGeneric;
+
+// 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/graphTypes.ts
+function getNodeLayer(nodeType) {
+  const L4_TYPES = ["decision"];
+  const L3_TYPES = ["belief", "question", "theme", "deal"];
+  const L2_TYPES = ["claim", "evidence", "synthesis", "answer"];
+  const L1_TYPES = ["atomic_fact", "excerpt", "source"];
+  const ONTOLOGICAL_TYPES = [
+    "company",
+    "person",
+    "investor",
+    "function",
+    "value_chain"
+  ];
+  const ORGANIZATIONAL_TYPES = ["topic"];
+  if (L4_TYPES.includes(nodeType)) {
+    return "L4";
+  }
+  if (L3_TYPES.includes(nodeType)) {
+    return "L3";
+  }
+  if (L2_TYPES.includes(nodeType)) {
+    return "L2";
+  }
+  if (L1_TYPES.includes(nodeType)) {
+    return "L1";
+  }
+  if (ONTOLOGICAL_TYPES.includes(nodeType)) {
+    return "ontological";
+  }
+  if (ORGANIZATIONAL_TYPES.includes(nodeType)) {
+    return "organizational";
+  }
+  console.warn(`[GraphTypes] Unknown nodeType "${nodeType}", defaulting to L2`);
+  return "L2";
+}
+
+// src/epistemicNodes.helpers.ts
+function buildNodeStatusSuccessResult() {
+  return { success: true };
+}
+function buildNodeNotFoundResult() {
+  const result = {};
+  result.success = false;
+  result.error = "Node not found";
+  return result;
+}
+function buildNodeDeletedResult(deletedEdgeCount) {
+  return {
+    success: true,
+    deletedEdgeCount
+  };
+}
+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")
+);
+var sourceTypeValidator = v.union(
+  v.literal("human"),
+  v.literal("ai_extracted"),
+  v.literal("ai_generated"),
+  v.literal("imported"),
+  v.literal("system")
+  // System-generated (migrations, classifiers)
+);
+v.union(
+  v.literal("active"),
+  v.literal("superseded"),
+  v.literal("archived"),
+  v.literal("deleted")
+);
+var verificationStatusValidator = v.union(
+  v.literal("unverified"),
+  v.literal("human_verified"),
+  v.literal("ai_verified"),
+  v.literal("contradicted"),
+  v.literal("outdated")
+);
+
+// src/invariantEnforcement.ts
+function throwInvariantError(args) {
+  const error = new Error(args.message);
+  error.status = args.status ?? 409;
+  error.code = args.code ?? "INVARIANT_VIOLATION";
+  error.invariantCode = args.invariantCode;
+  error.suggestion = args.suggestion;
+  error.details = args.details;
+  throw error;
+}
+function isBeliefNode(node) {
+  return node?.nodeType === "belief";
+}
+function assertBeliefNodeHardDeleteAllowed(args) {
+  if (!isBeliefNode(args.node)) {
+    return;
+  }
+  if (!args.allowBeliefHardDelete) {
+    throwInvariantError({
+      message: "Belief hard delete is forbidden by default. Beliefs must retain lineage and audit history.",
+      invariantCode: "belief.hard_delete_forbidden",
+      suggestion: "Use epistemicBeliefs.archive() or epistemicBeliefs.forkBelief() instead. Only migration repair flows may opt into hard delete explicitly.",
+      details: { mutationName: args.mutationName, nodeId: args.node._id }
+    });
+  }
+  if (!args.reason.trim().toLowerCase().startsWith("migration:")) {
+    throwInvariantError({
+      message: "Belief hard delete bypasses require a migration-scoped rationale.",
+      invariantCode: "belief.hard_delete_forbidden",
+      suggestion: 'Retry with allowBeliefHardDelete: true and a reason starting with "migration:" only for one-off data repair flows.',
+      details: {
+        mutationName: args.mutationName,
+        nodeId: args.node._id,
+        reason: args.reason
+      }
+    });
+  }
+}
+
+// src/epistemicNodes.internal.ts
+var optionalNodeScopeArgs = optionalScopeArgs;
+var createInternal = internalMutation({
+  args: {
+    ...optionalNodeScopeArgs,
+    globalId: v.string(),
+    nodeType: nodeTypeValidator,
+    subtype: v.optional(v.string()),
+    canonicalText: v.string(),
+    contentHash: v.optional(v.string()),
+    // Optional - will be generated if not provided
+    content: v.optional(v.string()),
+    contentType: v.optional(v.string()),
+    title: v.optional(v.string()),
+    tags: v.optional(v.array(v.string())),
+    domain: v.optional(v.string()),
+    metadata: v.optional(v.any()),
+    externalIds: v.optional(
+      v.object({
+        crunchbase: v.optional(v.string()),
+        linkedin: v.optional(v.string()),
+        pitchbook: v.optional(v.string()),
+        twitter: v.optional(v.string()),
+        website: v.optional(v.string())
+      })
+    ),
+    sourceType: v.optional(sourceTypeValidator),
+    aiProvider: v.optional(v.string()),
+    extractedFromNodeId: v.optional(v.id("epistemicNodes")),
+    confidence: v.optional(v.number()),
+    verificationStatus: v.optional(verificationStatusValidator),
+    createdBy: v.string(),
+    // Neo4j sync status tracking
+    syncStatus: v.optional(
+      v.union(
+        v.literal("synced"),
+        v.literal("pending_edges"),
+        v.literal("edge_creation_failed")
+      )
+    ),
+    epistemicLayer: v.optional(v.string()),
+    status: v.optional(v.string())
+  },
+  returns: permissiveReturn,
+  handler: async (ctx, args) => {
+    const now = Date.now();
+    const resolvedScope = args.topicId || args.projectId ? await (async () => {
+      try {
+        return await resolveTopicProjectScope(ctx, {
+          topicId: args.topicId,
+          projectId: args.projectId
+        });
+      } catch (error) {
+        debugGraphPrimitiveFallback(
+          "[epistemicNodes] Failed to resolve create scope",
+          {
+            error,
+            topicId: args.topicId,
+            projectId: args.projectId
+          }
+        );
+        return void 0;
+      }
+    })() : void 0;
+    const contentHash = args.contentHash || `${args.nodeType}:${args.canonicalText}`.slice(0, 64);
+    const epistemicLayer = args.epistemicLayer || getNodeLayer(args.nodeType);
+    const nodeId = await ctx.db.insert("epistemicNodes", {
+      globalId: args.globalId,
+      nodeType: args.nodeType,
+      epistemicLayer,
+      subtype: args.subtype,
+      canonicalText: args.canonicalText,
+      contentHash,
+      content: args.content,
+      contentType: args.contentType,
+      title: args.title,
+      tags: args.tags,
+      domain: args.domain,
+      metadata: args.metadata,
+      externalIds: args.externalIds,
+      sourceType: args.sourceType ?? "human",
+      aiProvider: args.aiProvider,
+      extractedFromNodeId: args.extractedFromNodeId,
+      confidence: args.confidence,
+      verificationStatus: args.verificationStatus ?? "unverified",
+      status: args.status ?? "active",
+      topicId: resolvedScope?.topicId ?? args.topicId,
+      projectId: resolvedScope?.projectId ?? args.projectId,
+      createdBy: args.createdBy,
+      createdAt: now,
+      updatedAt: now,
+      // Neo4j sync status
+      syncStatus: args.syncStatus
+    });
+    await ctx.scheduler.runAfter(0, internal.neo4jSync.syncNodeToNeo4j, {
+      nodeId,
+      operation: "upsert"
+    });
+    return nodeId;
+  }
+});
+var getInternal = internalQuery({
+  args: {
+    nodeId: v.id("epistemicNodes")
+  },
+  returns: permissiveReturn,
+  handler: async (ctx, args) => {
+    return await ctx.db.get(args.nodeId);
+  }
+});
+var updateSyncStatus = internalMutation({
+  args: {
+    nodeId: v.id("epistemicNodes"),
+    syncStatus: v.union(
+      v.literal("synced"),
+      v.literal("pending_edges"),
+      v.literal("edge_creation_failed")
+    ),
+    syncError: v.optional(v.string())
+  },
+  returns: permissiveReturn,
+  handler: async (ctx, args) => {
+    const updates = {
+      syncStatus: args.syncStatus,
+      updatedAt: Date.now()
+    };
+    if (args.syncError !== void 0) {
+      updates.syncError = args.syncError;
+    }
+    await ctx.db.patch(args.nodeId, updates);
+    return buildNodeStatusSuccessResult();
+  }
+});
+var backfillTopicId = internalMutation({
+  args: {
+    nodeIds: v.array(v.id("epistemicNodes")),
+    newTopicId: v.string()
+  },
+  returns: permissiveReturn,
+  handler: async (ctx, args) => {
+    let patched = 0;
+    for (const nodeId of args.nodeIds) {
+      const node = await ctx.db.get(nodeId);
+      if (!node) {
+        continue;
+      }
+      await ctx.db.patch(nodeId, {
+        topicId: args.newTopicId,
+        updatedAt: Date.now()
+      });
+      patched++;
+    }
+    return { patched, total: args.nodeIds.length };
+  }
+});
+var getNodesPendingEdgeSync = internalQuery({
+  args: {
+    limit: v.optional(v.number())
+  },
+  returns: permissiveReturn,
+  handler: async (ctx, args) => {
+    const limit = args.limit ?? 100;
+    return await ctx.db.query("epistemicNodes").withIndex(
+      "by_syncStatus",
+      (q) => q.eq("syncStatus", "edge_creation_failed")
+    ).take(limit);
+  }
+});
+var hardDelete = internalMutation({
+  args: {
+    nodeId: v.id("epistemicNodes"),
+    reason: v.string(),
+    // Required: document why this is being hard-deleted
+    allowBeliefHardDelete: v.optional(v.boolean())
+  },
+  returns: permissiveReturn,
+  handler: async (ctx, args) => {
+    const node = await ctx.db.get(args.nodeId);
+    if (!node) {
+      return buildNodeNotFoundResult();
+    }
+    assertBeliefNodeHardDeleteAllowed({
+      node,
+      allowBeliefHardDelete: args.allowBeliefHardDelete ?? false,
+      reason: args.reason,
+      mutationName: "epistemicNodes.hardDelete"
+    });
+    await ctx.db.insert("epistemicAudit", {
+      entityType: "node",
+      entityId: args.nodeId,
+      changeType: "deleted",
+      projectId: node.projectId,
+      changedBy: "system:hard_delete",
+      changedAt: Date.now(),
+      isAgent: false,
+      previousState: {
+        nodeType: node.nodeType,
+        title: node.title || node.canonicalText?.slice(0, 100),
+        status: node.status
+      },
+      rationale: args.reason
+    });
+    const fromEdges = await ctx.db.query("epistemicEdges").withIndex("by_from", (q) => q.eq("fromNodeId", args.nodeId)).collect();
+    const toEdges = await ctx.db.query("epistemicEdges").withIndex("by_to", (q) => q.eq("toNodeId", args.nodeId)).collect();
+    const uniqueEdges = /* @__PURE__ */ new Map();
+    for (const edge of [...fromEdges, ...toEdges]) {
+      uniqueEdges.set(edge.globalId, edge);
+    }
+    for (const edge of uniqueEdges.values()) {
+      await ctx.scheduler.runAfter(0, internal.neo4jEdgeAPI.deleteEdge, {
+        globalId: edge.globalId
+      });
+      await ctx.db.delete(edge._id);
+    }
+    await ctx.db.delete(args.nodeId);
+    return buildNodeDeletedResult(uniqueEdges.size);
+  }
+});
+
+export { backfillTopicId, createInternal, getInternal, getNodesPendingEdgeSync, hardDelete, updateSyncStatus };
+//# sourceMappingURL=epistemicNodes.internal.js.map
+//# sourceMappingURL=epistemicNodes.internal.js.map