@lucern/graph-primitives 0.1.0-alpha.2

package/dist/epistemicHelpers.js

@@ -0,0 +1,999 @@
+import { componentsGeneric, anyApi } from 'convex/server';
+
+// src/convex.ts
+componentsGeneric();
+var internal = anyApi;
+
+// src/globalId.ts
+function generateGlobalId() {
+  const bytes = new Uint8Array(16);
+  crypto.getRandomValues(bytes);
+  bytes[6] = bytes[6] & 15 | 64;
+  bytes[8] = bytes[8] & 63 | 128;
+  const hex = Array.from(bytes, (b) => b.toString(16).padStart(2, "0")).join(
+    ""
+  );
+  return `${hex.slice(0, 8)}-${hex.slice(8, 12)}-${hex.slice(12, 16)}-${hex.slice(16, 20)}-${hex.slice(20)}`;
+}
+
+// src/graphTypes.ts
+var NODE_TYPE_TO_LABEL = {
+  // L4: Audit Targets
+  decision: "Decision",
+  // L3: Traversal Anchors
+  belief: "Belief",
+  question: "Question",
+  theme: "Theme",
+  deal: "Deal",
+  topic: "Topic",
+  // L2: Compression Boundary
+  claim: "Claim",
+  evidence: "Evidence",
+  synthesis: "Synthesis",
+  answer: "Answer",
+  // L1: Terminal Leaves
+  atomic_fact: "AtomicFact",
+  excerpt: "Excerpt",
+  source: "Source",
+  // Ontological (Neo4j is SOT)
+  company: "Company",
+  person: "Person",
+  investor: "Investor",
+  function: "Function",
+  value_chain: "ValueChain"
+};
+var EDGE_TYPE_TO_REL = {
+  // === THE SIX CANONICAL EPISTEMIC EDGE TYPES ===
+  supports: "SUPPORTS",
+  // L3↔L3: belief bears on belief (weight -1 to +1)
+  informs: "INFORMS",
+  // L2→L3: evidence bears on belief
+  depends_on: "DEPENDS_ON",
+  // L3→L3, Q→Q: structural gate
+  derived_from: "DERIVED_FROM",
+  // Any→Any: provenance chain (fork, synthesis, extraction, answer)
+  contains: "CONTAINS",
+  // Any→Any: hierarchy, scoping, membership
+  tests: "TESTS",
+  // Q→L3: question interrogates belief
+  // === L4 DECISION EDGES (derived_from with derivationType=decision) ===
+  // Kept as separate Neo4j relationship types for backward compat with L4 queries.
+  // New code should use derived_from + metadata.
+  based_on_belief: "BASED_ON_BELIEF",
+  based_on_question: "BASED_ON_QUESTION",
+  blocked_by_contradiction: "BLOCKED_BY_CONTRADICTION",
+  informed_by_theme: "INFORMED_BY_THEME",
+  // === ONTOLOGICAL EDGES (tenant-extensible, managed by ontology system) ===
+  works_at: "WORKS_AT",
+  invested_in: "INVESTED_IN",
+  competes_with: "COMPETES_WITH",
+  participates_in: "PARTICIPATES_IN",
+  founded_by: "FOUNDED_BY",
+  evaluates: "EVALUATES",
+  performs: "PERFORMS",
+  function_in: "FUNCTION_IN",
+  impacts: "IMPACTS",
+  raised_from: "RAISED_FROM",
+  mentioned_in: "MENTIONED_IN",
+  perspective_on: "PERSPECTIVE_ON",
+  about_entity: "ABOUT_ENTITY",
+  entity_referenced_in: "ENTITY_REFERENCED_IN"
+};
+function getNeo4jLabel(nodeType) {
+  return NODE_TYPE_TO_LABEL[nodeType] || nodeType.charAt(0).toUpperCase() + nodeType.slice(1);
+}
+function getNeo4jRelType(edgeType) {
+  return EDGE_TYPE_TO_REL[edgeType] || edgeType.toUpperCase();
+}
+var CANONICAL_EPISTEMIC_TYPES = /* @__PURE__ */ new Set([
+  "supports",
+  "informs",
+  "depends_on",
+  "derived_from",
+  "contains",
+  "tests"
+]);
+function isDeprecatedEdgeType(edgeType) {
+  if (CANONICAL_EPISTEMIC_TYPES.has(edgeType)) return false;
+  if (edgeType in EDGE_TYPE_TO_REL) return false;
+  return true;
+}
+
+// src/epistemicHelpers.ts
+function generateContentHash(nodeType, text) {
+  const content = `${nodeType}:${normalizeText(text)}`;
+  let hash = 5381;
+  for (let i = 0; i < content.length; i++) {
+    hash = (hash << 5) + hash + content.charCodeAt(i);
+    hash &= hash;
+  }
+  const hashHex = Math.abs(hash).toString(16).padStart(8, "0");
+  const lengthHex = content.length.toString(16).padStart(4, "0");
+  const checksum = content.split("").reduce((a, c) => a + c.charCodeAt(0), 0).toString(16).padStart(8, "0");
+  return `${hashHex}${lengthHex}${checksum}`;
+}
+function normalizeText(text) {
+  return text.trim().toLowerCase().replace(/\s+/g, " ");
+}
+function getNodeLayer(nodeType) {
+  switch (nodeType) {
+    // L4: Audit targets
+    case "decision":
+      return "L4";
+    // L3: Traversal anchors
+    case "belief":
+    case "question":
+    case "theme":
+    case "deal":
+      return "L3";
+    // L2: Compression boundary
+    case "claim":
+    case "evidence":
+    case "synthesis":
+    case "answer":
+      return "L2";
+    // L1: Terminal leaves
+    case "atomic_fact":
+    case "excerpt":
+    case "source":
+      return "L1";
+    // Ontological entities
+    case "company":
+    case "person":
+    case "investor":
+    case "function":
+    case "value_chain":
+      return "ontological";
+    // Organizational containers
+    case "topic":
+      return "organizational";
+    default:
+      console.warn(
+        `[EpistemicLayer] Unknown nodeType: ${nodeType}, defaulting to L2`
+      );
+      return "L2";
+  }
+}
+var LAYER_TRAVERSAL_RULES = {
+  L4: {
+    canReach: ["L3", "L4"],
+    // Decisions can reach beliefs/questions
+    mustPassThrough: "L3"
+    // Must go through L3 to reach L2
+  },
+  L3: {
+    canReach: ["L2", "L3", "L4"],
+    // Beliefs can reach evidence, other beliefs, or decisions
+    mustPassThrough: "L2"
+    // Must go through L2 to reach L1
+  },
+  L2: {
+    canReach: ["L1", "L2", "L3"],
+    // Evidence can reach sources, other evidence, or beliefs
+    mustPassThrough: null
+    // L2 can reach L1 directly
+  },
+  L1: {
+    canReach: ["L1"],
+    // Sources can only reach other sources
+    mustPassThrough: null
+    // Terminal - no traversal beyond
+  },
+  ontological: {
+    canReach: ["L3", "L2", "ontological"],
+    // Entities can link to epistemic structure
+    mustPassThrough: null
+    // No layer constraints for entities
+  },
+  organizational: {
+    canReach: ["L3", "L2", "organizational"],
+    // Containers scope epistemic structure + nest
+    mustPassThrough: null
+    // No layer constraints for containers
+  }
+};
+function isValidLayerConnection(fromLayer, toLayer) {
+  const rules = LAYER_TRAVERSAL_RULES[fromLayer];
+  return rules.canReach.includes(toLayer);
+}
+function getLayerDepth(layer) {
+  switch (layer) {
+    case "L4":
+      return 4;
+    case "L3":
+      return 3;
+    case "L2":
+      return 2;
+    case "L1":
+      return 1;
+    case "ontological":
+      return 0;
+    // Ontological exists outside the epistemic hierarchy
+    case "organizational":
+      return 0;
+    // Organizational exists outside the epistemic hierarchy
+    default:
+      return 2;
+  }
+}
+function canTraverseToLayer(fromLayer, toLayer) {
+  const fromDepth = getLayerDepth(fromLayer);
+  const toDepth = getLayerDepth(toLayer);
+  if (fromLayer === "ontological" || toLayer === "ontological" || fromLayer === "organizational" || toLayer === "organizational") {
+    return isValidLayerConnection(fromLayer, toLayer);
+  }
+  if (fromDepth === toDepth) {
+    return true;
+  }
+  return isValidLayerConnection(fromLayer, toLayer);
+}
+function shouldContinueTraversal(currentLayer, targetLayer, options) {
+  const currentDepth = getLayerDepth(currentLayer);
+  const targetDepth = getLayerDepth(targetLayer);
+  if (options.minLayer !== void 0 && targetDepth < options.minLayer) {
+    return false;
+  }
+  if (options.maxLayer !== void 0 && targetDepth > options.maxLayer) {
+    return false;
+  }
+  switch (options.mode) {
+    case "anchor_down":
+      return targetDepth < currentDepth || targetDepth === currentDepth;
+    case "anchor_up":
+      return targetDepth > currentDepth || targetDepth === currentDepth;
+    case "same_layer":
+      return targetDepth === currentDepth;
+    case "decision_trace":
+      return currentDepth === 4 ? targetDepth === 3 : targetDepth === currentDepth;
+    default:
+      return true;
+  }
+}
+function getDefaultMinLayer(mode) {
+  switch (mode) {
+    case "anchor_down":
+      return 1;
+    // Can go all the way to L1 sources
+    case "anchor_up":
+      return 2;
+    // Start at L2 evidence minimum
+    case "same_layer":
+      return 1;
+    // No constraint
+    case "decision_trace":
+      return 3;
+    // Stop at L3 beliefs (don't go to L2 evidence)
+    default:
+      return 1;
+  }
+}
+function getDefaultEdgeTypesForMode(mode) {
+  switch (mode) {
+    case "anchor_down":
+      return [
+        "informs",
+        // evidence → belief (traverse backwards)
+        "derived_from"
+        // evidence → source (provenance) + evidence → question
+      ];
+    case "anchor_up":
+      return ["informs", "derived_from"];
+    case "same_layer":
+      return [
+        // L3: Belief ↔ Belief
+        "depends_on",
+        "supports",
+        "contains",
+        // L3: Question ↔ Question
+        "prerequisite_for",
+        "parallel_to",
+        // L2: Evidence ↔ Evidence
+        "corroborates",
+        "extends",
+        "same_source_as",
+        "same_theme_as"
+      ];
+    case "decision_trace":
+      return [
+        "derived_from",
+        "depends_on",
+        "contains"
+      ];
+    default:
+      return [];
+  }
+}
+var EDGE_LAYER_RULES = {
+  // === L4 Decision Edges ===
+  based_on_belief: {
+    from: ["L4"],
+    to: ["L3"],
+    description: "Decision \u2192 Belief (L4 \u2192 L3)"
+  },
+  based_on_question: {
+    from: ["L4"],
+    to: ["L3"],
+    description: "Decision \u2192 Question (L4 \u2192 L3)"
+  },
+  blocked_by_contradiction: {
+    from: ["L4"],
+    to: ["L3"],
+    description: "Decision \u2192 Contradiction (L4 \u2192 L3)"
+  },
+  informed_by_theme: {
+    from: ["L4"],
+    to: ["L3"],
+    description: "Decision \u2192 Theme (L4 \u2192 L3)"
+  },
+  // === Evidence Flow (L2 → L3, L2 → L1) ===
+  derived_from: {
+    from: ["L2", "L3", "L4"],
+    to: ["L1", "L2", "L3"],
+    description: "A was produced from B (provenance chain)"
+  },
+  answers: {
+    from: ["L2"],
+    to: ["L3"],
+    description: "Evidence \u2192 Question (L2 \u2192 L3)"
+  },
+  responds_to: {
+    from: ["L2"],
+    to: ["L3"],
+    description: "Answer \u2192 Question (L2 \u2192 L3)"
+  },
+  informs: {
+    from: ["L2"],
+    to: ["L3"],
+    description: "Evidence \u2192 Belief (L2 \u2192 L3)"
+  },
+  qualifies: {
+    from: ["L2"],
+    to: ["L3"],
+    description: "Evidence \u2192 Belief (L2 \u2192 L3)"
+  },
+  // === Question → Belief (L3 → L3) ===
+  tests: {
+    from: ["L3"],
+    to: ["L3"],
+    description: "Question \u2192 Belief (L3 \u2192 L3)"
+  },
+  explores: {
+    from: ["L3"],
+    to: ["L3"],
+    description: "Question \u2192 Belief assumption (L3 \u2192 L3)"
+  },
+  // === Synthesis (L2 → L2, L2 → L1) ===
+  based_on: {
+    from: ["L2"],
+    to: ["L2", "L1"],
+    description: "Synthesis \u2192 Evidence/Source (L2 \u2192 L2/L1)"
+  },
+  // === Theme Relationships (L3 → L3) ===
+  relates_to_thesis: {
+    from: ["L3"],
+    to: ["L3"],
+    description: "Belief \u2192 Theme (L3 \u2192 L3)"
+  },
+  belongs_to: {
+    from: ["L3", "L2"],
+    // Can belong to theme from L3 or L2
+    to: ["L3"],
+    description: "Any \u2192 Theme (L3/L2 \u2192 L3)"
+  },
+  plays_theme: {
+    from: ["L3"],
+    to: ["L3"],
+    description: "Deal \u2192 Theme (L3 \u2192 L3)"
+  },
+  // === Topic Hierarchy (L3 → organizational) ===
+  scoped_by: {
+    from: ["L3"],
+    to: ["organizational"],
+    description: "Belief/Question \u2192 Topic (L3 \u2192 organizational)"
+  },
+  // === Deal/Company ===
+  evaluates: {
+    from: ["L3"],
+    to: ["ontological"],
+    description: "Deal \u2192 Company (L3 \u2192 ontological)"
+  },
+  // === People (ontological → ontological, ontological → L3) ===
+  perspective_on: {
+    from: ["ontological"],
+    to: ["L3"],
+    description: "Person \u2192 Belief/Theme (ontological \u2192 L3)"
+  },
+  works_at: {
+    from: ["ontological"],
+    to: ["ontological"],
+    description: "Person \u2192 Company (ontological \u2192 ontological)"
+  },
+  // === Value Chain (ontological) ===
+  participates_in: {
+    from: ["ontological"],
+    to: ["ontological"],
+    description: "Company \u2192 ValueChain (ontological \u2192 ontological)"
+  },
+  performs: {
+    from: ["ontological"],
+    to: ["ontological"],
+    description: "Company \u2192 Function (ontological \u2192 ontological)"
+  },
+  function_in: {
+    from: ["ontological"],
+    to: ["ontological"],
+    description: "Function \u2192 ValueChain (ontological \u2192 ontological)"
+  },
+  impacts: {
+    from: ["L3"],
+    to: ["ontological"],
+    description: "Theme \u2192 ValueChain (L3 \u2192 ontological)"
+  },
+  // === Investment (ontological) ===
+  invested_in: {
+    from: ["ontological"],
+    to: ["ontological"],
+    description: "Investor \u2192 Company (ontological \u2192 ontological)"
+  },
+  raised_from: {
+    from: ["ontological"],
+    to: ["ontological"],
+    description: "Company \u2192 Investor (ontological \u2192 ontological)"
+  },
+  // === Entity↔Belief Bridge (OE-B) ===
+  about_entity: {
+    from: ["L3"],
+    to: ["ontological"],
+    description: "Belief/Question/Theme \u2192 Entity (L3 \u2192 ontological)"
+  },
+  entity_referenced_in: {
+    from: ["ontological"],
+    to: ["L2"],
+    description: "Entity \u2192 Evidence (ontological \u2192 L2)"
+  },
+  mentioned_in: {
+    from: ["ontological"],
+    to: ["L1"],
+    description: "Entity \u2192 Source document (ontological \u2192 L1)"
+  },
+  founded_by: {
+    from: ["ontological"],
+    to: ["ontological"],
+    description: "Company \u2192 Person (ontological \u2192 ontological)"
+  },
+  competes_with: {
+    from: ["ontological"],
+    to: ["ontological"],
+    description: "Company \u2192 Company (ontological \u2192 ontological)"
+  },
+  contains: {
+    from: ["ontological"],
+    to: ["ontological"],
+    description: "ValueChain \u2192 Function (ontological \u2192 ontological)"
+  },
+  // === Lifecycle (same layer only) ===
+  supersedes: {
+    from: ["L4", "L3", "L2", "L1", "ontological", "organizational"],
+    to: ["L4", "L3", "L2", "L1", "ontological", "organizational"],
+    description: "NewNode \u2192 OldNode (same layer only - validated separately)"
+  },
+  same_as: {
+    from: ["L4", "L3", "L2", "L1", "ontological", "organizational"],
+    to: ["L4", "L3", "L2", "L1", "ontological", "organizational"],
+    description: "Duplicate detection (same layer only - validated separately)"
+  },
+  // === Same-Type: Belief ↔ Belief (L3 → L3) ===
+  depends_on: {
+    from: ["L3"],
+    to: ["L3"],
+    description: "Belief B requires Belief A (L3 \u2192 L3)"
+  },
+  reinforces: {
+    from: ["L3"],
+    to: ["L3"],
+    description: "Beliefs strengthen each other (L3 \u2192 L3)"
+  },
+  parent_of: {
+    from: ["L3", "organizational"],
+    to: ["L3", "organizational"],
+    description: "A is higher-level than B (L3 \u2192 L3, organizational \u2192 organizational)"
+  },
+  child_of: {
+    from: ["L3"],
+    to: ["L3"],
+    description: "Belief A is more specific (L3 \u2192 L3)"
+  },
+  // === Same-Type: Question ↔ Question (L3 → L3) ===
+  prerequisite_for: {
+    from: ["L3"],
+    to: ["L3"],
+    description: "Question A must be answered first (L3 \u2192 L3)"
+  },
+  parallel_to: {
+    from: ["L3"],
+    to: ["L3"],
+    description: "Same topic, different angles (L3 \u2192 L3)"
+  },
+  // === Same-Type: Evidence ↔ Evidence (L2 → L2) ===
+  corroborates: {
+    from: ["L2"],
+    to: ["L2"],
+    description: "Independent support (L2 \u2192 L2)"
+  },
+  extends: {
+    from: ["L2"],
+    to: ["L2"],
+    description: "Adds depth (L2 \u2192 L2)"
+  },
+  same_source_as: {
+    from: ["L2"],
+    to: ["L2"],
+    description: "Same document/study (L2 \u2192 L2)"
+  },
+  same_theme_as: {
+    from: ["L2"],
+    to: ["L2"],
+    description: "Same topic/entity (L2 \u2192 L2)"
+  },
+  // === NEW: Deep Epistemic Analysis Edges (Phase: Schema Upgrade) ===
+  assumes: {
+    from: ["L3"],
+    to: ["L3"],
+    description: "Hidden dependency - Belief B implicitly assumes Belief A (L3 \u2192 L3)"
+  },
+  would_predict: {
+    from: ["L3"],
+    to: ["L2"],
+    description: "Pre-registered prediction - If Belief true, expect Evidence (L3 \u2192 L2)"
+  },
+  analogous_to: {
+    from: ["L3"],
+    to: ["L3"],
+    description: "Explicit analogy - Belief A is like Belief B (L3 \u2192 L3)"
+  },
+  independent_of: {
+    from: ["L2"],
+    to: ["L2"],
+    description: "True evidence independence - Evidence A independent of B (L2 \u2192 L2)"
+  }
+  // NOTE: Deprecated edge types (supports, contradicts, derived_from, cites,
+  // summarizes, related_to, partially_answers, blocks, refines, branches_from)
+  // have been REMOVED from the system. Use compliant alternatives instead.
+};
+function validateEdgeLayers(edgeType, fromLayer, toLayer) {
+  const rules = EDGE_LAYER_RULES[edgeType];
+  if (!rules) {
+    console.warn(
+      `[EdgeValidation] Unknown edge type: ${edgeType}, allowing by default`
+    );
+    return { valid: true };
+  }
+  if (edgeType === "supersedes") {
+    if (fromLayer !== toLayer) {
+      return {
+        valid: false,
+        reason: `${edgeType} edges must be between nodes of the same layer. Got ${fromLayer} \u2192 ${toLayer}`
+      };
+    }
+    return { valid: true };
+  }
+  if (!rules.from.includes(fromLayer)) {
+    return {
+      valid: false,
+      reason: `Edge type '${edgeType}' does not allow source layer ${fromLayer}. Allowed: ${rules.from.join(", ")}`
+    };
+  }
+  if (!rules.to.includes(toLayer)) {
+    return {
+      valid: false,
+      reason: `Edge type '${edgeType}' does not allow target layer ${toLayer}. Allowed: ${rules.to.join(", ")}`
+    };
+  }
+  return { valid: true };
+}
+function mapInsightSourceType(sourceType) {
+  switch (sourceType) {
+    case "verified":
+    case "proprietary":
+      return "human";
+    case "ai_generated":
+      return "ai_generated";
+    default:
+      return "human";
+  }
+}
+function mapVerificationStatus(status) {
+  switch (status) {
+    case "manually_verified":
+      return "human_verified";
+    case "deep_verified":
+    case "pre_screened":
+      return "ai_verified";
+    default:
+      return "unverified";
+  }
+}
+async function createEpistemicNodeForInsight(ctx, _insightId, insight) {
+  const now = Date.now();
+  const globalId = generateGlobalId();
+  const contentHash = generateContentHash("evidence", insight.text);
+  const existing = await ctx.db.query("epistemicNodes").withIndex("by_contentHash", (q) => q.eq("contentHash", contentHash)).first();
+  if (existing && existing.status === "active") {
+    await ctx.db.patch(existing._id, {
+      updatedAt: now
+    });
+    return existing._id;
+  }
+  const nodeId = await ctx.db.insert("epistemicNodes", {
+    globalId,
+    nodeType: "evidence",
+    epistemicLayer: "L2",
+    // Evidence is at L2 (compression boundary)
+    canonicalText: insight.text,
+    contentHash,
+    title: insight.text.slice(0, 100) + (insight.text.length > 100 ? "..." : ""),
+    tags: insight.tags,
+    metadata: {
+      kind: insight.kind,
+      pillar: insight.tags?.find(
+        (t) => [
+          "market",
+          "competition",
+          "product",
+          "team",
+          "financials",
+          "regulatory",
+          "timing",
+          "customer",
+          "technology",
+          "distribution"
+        ].includes(t)
+      ),
+      // Include sourceArtifactId for source document panel
+      sourceArtifactId: insight.sourceArtifactId,
+      // Include sourceQuestionId if this evidence was created to answer a question
+      sourceQuestionId: insight.sourceQuestionId,
+      // Include sourceAnchor for linking evidence back to source documents
+      sourceAnchor: insight.sourceAnchor
+    },
+    sourceType: mapInsightSourceType(insight.sourceType),
+    aiProvider: insight.aiProvider,
+    confidence: insight.verificationStatus === "manually_verified" ? 0.9 : insight.verificationStatus === "deep_verified" ? 0.7 : insight.verificationStatus === "pre_screened" ? 0.5 : 0.3,
+    verificationStatus: mapVerificationStatus(insight.verificationStatus),
+    status: "active",
+    topicId: insight.projectId,
+    createdBy: insight.createdBy,
+    createdAt: now,
+    updatedAt: now
+  });
+  if (insight.sourceArtifactId) {
+    const sourceNode = await findOrCreateSourceNode(
+      ctx,
+      insight.sourceArtifactId,
+      insight.createdBy,
+      insight.projectId
+    );
+    if (sourceNode) {
+      await createEpistemicEdge(ctx, {
+        fromNodeId: nodeId,
+        toNodeId: sourceNode,
+        edgeType: "derived_from",
+        projectId: insight.projectId,
+        createdBy: insight.createdBy
+      });
+    }
+  }
+  return nodeId;
+}
+async function createEpistemicNodeForBelief(ctx, beliefId, belief) {
+  const now = Date.now();
+  const globalId = generateGlobalId();
+  const contentHash = generateContentHash("belief", belief.belief);
+  const existing = await ctx.db.query("epistemicNodes").withIndex("by_contentHash", (q) => q.eq("contentHash", contentHash)).first();
+  if (existing && existing.status === "active") {
+    await ctx.db.patch(existing._id, {
+      metadata: {
+        ...existing.metadata || {},
+        sourceBeliefId: beliefId
+      },
+      updatedAt: now
+    });
+    return existing._id;
+  }
+  const nodeId = await ctx.db.insert("epistemicNodes", {
+    globalId,
+    nodeType: "belief",
+    epistemicLayer: "L3",
+    // Beliefs are at L3 (traversal anchors)
+    canonicalText: belief.belief,
+    contentHash,
+    content: belief.rationale,
+    title: belief.belief.slice(0, 100) + (belief.belief.length > 100 ? "..." : ""),
+    metadata: {
+      sourceBeliefId: beliefId,
+      beliefStatus: "assumption",
+      topic: belief.topic,
+      // Use 'topic' for consistency with legacy schema
+      pillar: belief.topic,
+      // Keep 'pillar' for backward compat with existing data
+      // No confidence/confidenceLevel — only set after sprint completion
+      rationale: belief.rationale,
+      status: "active",
+      // Include sourceAnchor for linking beliefs back to source documents
+      sourceAnchor: belief.sourceAnchor
+    },
+    beliefStatus: "assumption",
+    epistemicStatus: "assumption",
+    sourceType: "human",
+    confidence: void 0,
+    // No confidence until sprint completion
+    verificationStatus: "unverified",
+    status: "active",
+    topicId: belief.projectId,
+    createdBy: belief.createdBy,
+    createdAt: now,
+    updatedAt: now
+  });
+  return nodeId;
+}
+async function createEpistemicNodeForQuestion(ctx, _questionId, question) {
+  const now = Date.now();
+  const globalId = generateGlobalId();
+  const contentHash = generateContentHash("question", question.question);
+  const existing = await ctx.db.query("epistemicNodes").withIndex("by_contentHash", (q) => q.eq("contentHash", contentHash)).first();
+  if (existing && existing.status === "active") {
+    await ctx.db.patch(existing._id, {
+      updatedAt: now
+    });
+    return existing._id;
+  }
+  const sourceType = question.source === "manual" ? "human" : question.source === "ai_suggested" ? "ai_generated" : "ai_extracted";
+  const nodeId = await ctx.db.insert("epistemicNodes", {
+    globalId,
+    nodeType: "question",
+    epistemicLayer: "L3",
+    // Questions are at L3 (traversal anchors)
+    canonicalText: question.question,
+    contentHash,
+    title: question.question.slice(0, 100) + (question.question.length > 100 ? "..." : ""),
+    metadata: {
+      pillar: question.category,
+      priority: question.priority,
+      source: question.source,
+      // Include sourceAnchor for linking questions back to source documents
+      sourceAnchor: question.sourceAnchor
+    },
+    sourceType,
+    verificationStatus: "unverified",
+    status: "active",
+    topicId: question.projectId,
+    createdBy: question.createdBy,
+    createdAt: now,
+    updatedAt: now
+  });
+  return nodeId;
+}
+async function createEpistemicNodeForArtifact(ctx, artifactId, artifact) {
+  const now = Date.now();
+  const globalId = generateGlobalId();
+  let nodeType = "source";
+  const isSynthesis = artifact.isDeepResearch || artifact.type.includes("deep") || artifact.type.includes("research") || artifact.type.includes("primer");
+  if (isSynthesis) {
+    nodeType = "synthesis";
+    console.log(
+      `[EpistemicHelpers] Skipping synthesis node creation for "${artifact.type}" - will create when evidence is extracted`
+    );
+    const contentHash2 = generateContentHash(
+      nodeType,
+      artifact.title + artifact.content.slice(0, 500)
+    );
+    const existing2 = await ctx.db.query("epistemicNodes").withIndex("by_contentHash", (q) => q.eq("contentHash", contentHash2)).first();
+    if (existing2 && existing2.status === "active") {
+      return existing2._id;
+    }
+    throw new Error("SKIP_SYNTHESIS_NODE_CREATION");
+  }
+  const contentHash = generateContentHash(
+    nodeType,
+    artifact.title + artifact.content.slice(0, 500)
+  );
+  const existing = await ctx.db.query("epistemicNodes").withIndex("by_contentHash", (q) => q.eq("contentHash", contentHash)).first();
+  if (existing && existing.status === "active") {
+    await ctx.db.patch(existing._id, {
+      metadata: {
+        ...existing.metadata || {},
+        legacyArtifactId: artifactId
+      },
+      updatedAt: now
+    });
+    return existing._id;
+  }
+  const epistemicLayer = "L1";
+  const nodeId = await ctx.db.insert("epistemicNodes", {
+    globalId,
+    nodeType,
+    epistemicLayer,
+    // Synthesis is L2, Source is L1
+    canonicalText: artifact.title,
+    contentHash,
+    content: artifact.content,
+    contentType: "markdown",
+    title: artifact.title,
+    metadata: {
+      legacyArtifactId: artifactId,
+      artifactType: artifact.type
+    },
+    sourceType: "ai_generated",
+    aiProvider: artifact.aiProvider || (artifact.isDeepResearch ? "gemini" : "anthropic"),
+    verificationStatus: "unverified",
+    status: "active",
+    topicId: artifact.projectId,
+    createdBy: artifact.createdBy,
+    createdAt: now,
+    updatedAt: now
+  });
+  return nodeId;
+}
+async function findOrCreateSourceNode(ctx, artifactId, createdBy, scopeProjectId) {
+  const artifact = await ctx.db.get(artifactId);
+  const effectiveProjectId = scopeProjectId || artifact?.projectId;
+  const effectiveTopicId = artifact?.topicId;
+  let existingNodes;
+  if (effectiveTopicId) {
+    existingNodes = await ctx.db.query("epistemicNodes").withIndex("by_topic", (q) => q.eq("topicId", effectiveTopicId)).collect();
+  } else if (effectiveProjectId) {
+    existingNodes = await ctx.db.query("epistemicNodes").withIndex("by_project", (q) => q.eq("projectId", effectiveProjectId)).collect();
+  } else {
+    existingNodes = await ctx.db.query("epistemicNodes").withIndex("by_nodeType", (q) => q.eq("nodeType", "source")).collect();
+  }
+  const existing = existingNodes.find((n) => {
+    const metadata = n.metadata;
+    return metadata?.legacyArtifactId === artifactId;
+  });
+  if (existing) {
+    return existing._id;
+  }
+  if (!artifact) {
+    return null;
+  }
+  const now = Date.now();
+  const globalId = generateGlobalId();
+  const artifactType = artifact.metadata?.type || "";
+  const isDeepResearch = artifact.metadata?.isDeepResearch;
+  let nodeType = "source";
+  if (isDeepResearch || artifactType.includes("deep") || artifactType.includes("research")) {
+    nodeType = "synthesis";
+  } else if (artifactType.includes("primer")) {
+    nodeType = "synthesis";
+  }
+  const title = artifact.metadata?.title || artifact.metadata?.theme || "Untitled";
+  const contentHash = generateContentHash(
+    nodeType,
+    title + (artifact.content?.slice(0, 500) || "")
+  );
+  const epistemicLayer = nodeType === "synthesis" ? "L2" : "L1";
+  const nodeId = await ctx.db.insert("epistemicNodes", {
+    globalId,
+    nodeType,
+    epistemicLayer,
+    // Synthesis is L2, Source is L1
+    canonicalText: title,
+    contentHash,
+    content: artifact.content,
+    contentType: "markdown",
+    title,
+    metadata: {
+      legacyArtifactId: artifactId,
+      artifactType,
+      stage: artifact.stage
+    },
+    sourceType: isDeepResearch ? "ai_generated" : "ai_extracted",
+    aiProvider: isDeepResearch ? "gemini" : "anthropic",
+    verificationStatus: "unverified",
+    status: "active",
+    topicId: artifact.projectId,
+    createdBy,
+    createdAt: now,
+    updatedAt: now
+  });
+  return nodeId;
+}
+function normalizeConfidence(confidence) {
+  if (typeof confidence === "number") {
+    return confidence > 1 ? confidence / 100 : confidence;
+  }
+  if (typeof confidence === "string") {
+    switch (confidence) {
+      case "high":
+        return 0.8;
+      case "medium":
+        return 0.5;
+      case "low":
+        return 0.3;
+      default:
+        return 0.5;
+    }
+  }
+  return 0.5;
+}
+async function createEpistemicEdge(ctx, params) {
+  const globalId = generateGlobalId();
+  const fromNode = await ctx.db.get(params.fromNodeId);
+  const toNode = await ctx.db.get(params.toNodeId);
+  if (!fromNode || !toNode) {
+    throw new Error("One or both nodes not found");
+  }
+  const fromLayer = fromNode.epistemicLayer || getNodeLayer(fromNode.nodeType);
+  const toLayer = toNode.epistemicLayer || getNodeLayer(toNode.nodeType);
+  if (!params.skipLayerValidation) {
+    const validation = validateEdgeLayers(params.edgeType, fromLayer, toLayer);
+    if (!validation.valid) {
+      throw new Error(
+        `[EdgeValidation] Invalid edge: ${validation.reason}. Attempted: ${params.edgeType} from ${fromNode.nodeType}(${fromLayer}) \u2192 ${toNode.nodeType}(${toLayer})`
+      );
+    }
+  }
+  await ctx.scheduler.runAfter(0, internal.neo4jEdgeAPI.createEdge, {
+    globalId,
+    fromGlobalId: fromNode.globalId,
+    toGlobalId: toNode.globalId,
+    edgeType: params.edgeType,
+    weight: params.weight,
+    confidence: params.confidence,
+    context: params.context,
+    createdBy: params.createdBy,
+    topicId: params.projectId ? String(params.projectId) : void 0,
+    fromNodeType: fromNode.nodeType,
+    toNodeType: toNode.nodeType,
+    fromLayer,
+    toLayer
+  });
+  return globalId;
+}
+async function createEdgeForInsightQuestionLink(ctx, questionId, insightId, createdBy) {
+  console.log("[EpistemicSpine] Creating edge for insight-question link:", {
+    questionId: String(questionId),
+    insightId: String(insightId)
+  });
+  const questionNode = await findNodeByLegacyId(ctx, "question", questionId);
+  const insightNode = await findNodeByLegacyId(ctx, "insight", insightId);
+  console.log("[EpistemicSpine] Found nodes:", {
+    questionNode: questionNode ? String(questionNode) : null,
+    insightNode: insightNode ? String(insightNode) : null
+  });
+  if (!questionNode || !insightNode) {
+    console.log("[EpistemicSpine] Missing nodes, skipping edge creation");
+    return null;
+  }
+  const question = await ctx.db.get(questionId);
+  const projectId = question?.projectId;
+  return await createEpistemicEdge(ctx, {
+    fromNodeId: insightNode,
+    toNodeId: questionNode,
+    edgeType: "derived_from",
+    projectId,
+    createdBy,
+    context: "Linked from questions workspace"
+  });
+}
+async function findNodeByLegacyId(ctx, legacyType, legacyId) {
+  const nodeType = legacyType === "insight" ? "evidence" : legacyType === "artifact" ? "source" : legacyType;
+  const nodes = await ctx.db.query("epistemicNodes").withIndex("by_nodeType", (q) => q.eq("nodeType", nodeType)).collect();
+  const legacyKey = `legacy${legacyType.charAt(0).toUpperCase() + legacyType.slice(1)}Id`;
+  const legacyIdStr = String(legacyId);
+  const found = nodes.find((n) => {
+    const metadata = n.metadata;
+    const storedId = metadata?.[legacyKey];
+    return storedId && String(storedId) === legacyIdStr;
+  });
+  if (!found) {
+    console.log(
+      `[EpistemicSpine] Node not found for ${legacyType}:${legacyIdStr}, searched ${nodes.length} ${nodeType} nodes`
+    );
+  }
+  return found?._id ?? null;
+}
+
+export { EDGE_LAYER_RULES, LAYER_TRAVERSAL_RULES, canTraverseToLayer, createEdgeForInsightQuestionLink, createEpistemicEdge, createEpistemicNodeForArtifact, createEpistemicNodeForBelief, createEpistemicNodeForInsight, createEpistemicNodeForQuestion, getDefaultEdgeTypesForMode, getDefaultMinLayer, getLayerDepth, getNeo4jLabel, getNeo4jRelType, getNodeLayer, isDeprecatedEdgeType, isValidLayerConnection, normalizeConfidence, shouldContinueTraversal, validateEdgeLayers };
+//# sourceMappingURL=epistemicHelpers.js.map
+//# sourceMappingURL=epistemicHelpers.js.map