@lucern/graph-primitives 0.1.0-alpha.2

package/dist/epistemicHelpers-Bd9xbaib.d.ts

@@ -0,0 +1,329 @@
+import { Id, MutationCtx } from './convex.js';
+import { a as getNeo4jLabel, b as getNeo4jRelType, i as isDeprecatedEdgeType } from './graphTypes-CpgIuCdo.js';
+
+/**
+ * Epistemic Spine - Dual-Write Helpers
+ *
+ * These functions handle writing to both legacy tables AND the epistemic spine.
+ * They're called from existing mutations to ensure every new entity gets a spine entry.
+ *
+ * The spine is the canonical identity layer - these helpers ensure consistency.
+ *
+ * @see /docs/architecture/EPISTEMIC_SPINE.md
+ * @see /docs/architecture/UNIFIED_GRAPH_ARCHITECTURE.md
+ */
+
+/**
+ * Epistemic Layer - governs traversal rules
+ * L4 → L3 → L2 → L1 (never skip layers)
+ */
+type EpistemicLayer = "L4" | "L3" | "L2" | "L1" | "ontological" | "organizational";
+/**
+ * Map nodeType to its epistemic layer
+ *
+ * Layer semantics:
+ * - L4: Audit targets (decisions, outcomes) - what we committed to
+ * - L3: Traversal anchors (beliefs, questions, themes) - epistemic structure
+ * - L2: Compression boundary (claims, evidence, synthesis) - minimum reasoning unit
+ * - L1: Terminal leaves (atomic_fact, excerpt, source) - non-traversable grounding
+ * - ontological: Entities in the world (companies, people) - not epistemic
+ * - organizational: Structural containers (topics, lenses, worktrees) - not epistemic
+ */
+declare function getNodeLayer(nodeType: string): EpistemicLayer;
+/**
+ * Layer traversal rules
+ * Key constraint: Cannot skip layers during traversal
+ */
+declare const LAYER_TRAVERSAL_RULES: {
+    readonly L4: {
+        readonly canReach: readonly ["L3", "L4"];
+        readonly mustPassThrough: "L3";
+    };
+    readonly L3: {
+        readonly canReach: readonly ["L2", "L3", "L4"];
+        readonly mustPassThrough: "L2";
+    };
+    readonly L2: {
+        readonly canReach: readonly ["L1", "L2", "L3"];
+        readonly mustPassThrough: null;
+    };
+    readonly L1: {
+        readonly canReach: readonly ["L1"];
+        readonly mustPassThrough: null;
+    };
+    readonly ontological: {
+        readonly canReach: readonly ["L3", "L2", "ontological"];
+        readonly mustPassThrough: null;
+    };
+    readonly organizational: {
+        readonly canReach: readonly ["L3", "L2", "organizational"];
+        readonly mustPassThrough: null;
+    };
+};
+/**
+ * Check if a direct edge between two layers is allowed
+ */
+declare function isValidLayerConnection(fromLayer: EpistemicLayer, toLayer: EpistemicLayer): boolean;
+/**
+ * Get layer hierarchy number (for comparison)
+ * Higher number = higher layer
+ */
+declare function getLayerDepth(layer: EpistemicLayer): number;
+/**
+ * Check if we can traverse from one layer to another
+ * (considering intermediate layers)
+ */
+declare function canTraverseToLayer(fromLayer: EpistemicLayer, toLayer: EpistemicLayer): boolean;
+/**
+ * Traversal mode - determines how to traverse the graph
+ *
+ * anchor_down: Start at L3 belief, traverse to L2 evidence, stop at L1 sources
+ * anchor_up: Start at L2 evidence, traverse to L3 beliefs it supports
+ * same_layer: Traverse within a single layer (e.g., belief → belief)
+ * decision_trace: Start at L4 decision, traverse to L3 beliefs it was based on
+ */
+type TraversalMode = "anchor_down" | "anchor_up" | "same_layer" | "decision_trace";
+/**
+ * Traversal options for layer-aware queries
+ */
+type TraversalOptions = {
+    /** Starting node ID */
+    startNodeId: Id<"epistemicNodes">;
+    /** Traversal mode */
+    mode: TraversalMode;
+    /** Edge types to follow (empty = all valid for mode) */
+    allowedEdgeTypes?: string[];
+    /** Maximum depth */
+    maxDepth?: number;
+    /** Minimum layer to stop at (L1 = 1, L4 = 4) */
+    minLayer?: number;
+    /** Maximum layer to reach */
+    maxLayer?: number;
+};
+/**
+ * Check if traversal should continue based on layer constraints
+ */
+declare function shouldContinueTraversal(currentLayer: EpistemicLayer, targetLayer: EpistemicLayer, options: {
+    mode: TraversalMode;
+    minLayer?: number;
+    maxLayer?: number;
+}): boolean;
+/**
+ * Get default minLayer for a traversal mode
+ */
+declare function getDefaultMinLayer(mode: TraversalMode): number;
+/**
+ * Get allowed edge types for a traversal mode
+ */
+declare function getDefaultEdgeTypesForMode(mode: TraversalMode): string[];
+/**
+ * Edge Layer Rules - defines valid layer combinations for each edge type
+ *
+ * Format: { from: [allowed source layers], to: [allowed target layers] }
+ *
+ * Key rules:
+ * - L4 edges: Decision → L3 (beliefs, questions, themes)
+ * - Cross-layer edges: L2 → L3 (evidence informs beliefs)
+ * - Same-layer edges: L3 → L3, L2 → L2 (beliefs depend on beliefs)
+ * - Downward edges: L2 → L1 (evidence extracted from source)
+ * - Lifecycle edges: same layer only (supersedes)
+ */
+declare const EDGE_LAYER_RULES: Record<string, {
+    from: EpistemicLayer[];
+    to: EpistemicLayer[];
+    description: string;
+}>;
+/**
+ * Validate an edge against layer rules
+ *
+ * Returns { valid: true } or { valid: false, reason: string }
+ */
+declare function validateEdgeLayers(edgeType: string, fromLayer: EpistemicLayer, toLayer: EpistemicLayer): {
+    valid: boolean;
+    reason?: string;
+};
+/**
+ * Create an epistemic node for an insight (evidence)
+ * Called after inserting into the insights table
+ */
+declare function createEpistemicNodeForInsight(ctx: MutationCtx, _insightId: Id<"epistemicNodes">, insight: {
+    projectId: string;
+    text: string;
+    kind: string;
+    tags?: string[];
+    sourceType?: string;
+    aiProvider?: string;
+    verificationStatus?: string;
+    sourceArtifactId?: Id<"finalArtifacts">;
+    sourceQuestionId?: Id<"epistemicNodes">;
+    sourceAnchor?: {
+        artifactId: string;
+        artifactType: string;
+        artifactTitle?: string;
+        sectionHeading?: string;
+        selectedText?: string;
+        startOffset?: number;
+        endOffset?: number;
+        pageNumber?: number;
+    };
+    createdBy: string;
+}): Promise<Id<"epistemicNodes">>;
+/**
+ * Create an epistemic node for a belief
+ * Called after inserting into the beliefs table
+ */
+declare function createEpistemicNodeForBelief(ctx: MutationCtx, beliefId: Id<"epistemicNodes">, belief: {
+    projectId: string;
+    belief: string;
+    rationale?: string;
+    confidence: string;
+    topic?: string;
+    sourceAnchor?: {
+        artifactId: string;
+        artifactType: string;
+        artifactTitle?: string;
+        sectionHeading?: string;
+        selectedText?: string;
+        startOffset?: number;
+        endOffset?: number;
+    };
+    createdBy: string;
+}): Promise<Id<"epistemicNodes">>;
+/**
+ * Create an epistemic node for a question
+ * Called after inserting into the questions table
+ */
+declare function createEpistemicNodeForQuestion(ctx: MutationCtx, _questionId: Id<"epistemicNodes">, question: {
+    projectId: string;
+    question: string;
+    category?: string;
+    priority: string;
+    source: string;
+    sourceAnchor?: {
+        artifactId: string;
+        artifactType: string;
+        artifactTitle?: string;
+        sectionHeading?: string;
+        selectedText?: string;
+        startOffset?: number;
+        endOffset?: number;
+    };
+    createdBy: string;
+}): Promise<Id<"epistemicNodes">>;
+/**
+ * Create an epistemic node for a synthesis artifact (primer or deep research).
+ *
+ * ⚠️ IMPORTANT: This function should NOT be called for primers/deep research
+ * unless the node is being connected to evidence as a source.
+ * Standalone synthesis nodes create orphans in the graph.
+ *
+ * The correct pattern is:
+ * 1. Store the artifact in finalArtifacts (for UI display)
+ * 2. Only create epistemic node when extracting evidence FROM the artifact
+ * 3. Create edge: evidence -> derived_from -> synthesis
+ *
+ * @deprecated Consider removing automatic node creation for primers.
+ * Use the artifact ID reference in evidence metadata instead.
+ */
+declare function createEpistemicNodeForArtifact(ctx: MutationCtx, artifactId: Id<"finalArtifacts">, artifact: {
+    projectId?: string;
+    title: string;
+    content: string;
+    type: string;
+    isDeepResearch?: boolean;
+    aiProvider?: string;
+    createdBy: string;
+}): Promise<Id<"epistemicNodes">>;
+/**
+ * Edge type union for createEpistemicEdge
+ * Phase 2C: Updated to include L4 edges and modern edge types
+ * Phase 3: Added full epistemic impact edges for confidence propagation
+ */
+type EpistemicEdgeType = "derived_from" | "supports" | "contains" | "depends_on" | "informs" | "tests" | "responds_to" | "relates_to_thesis" | "belongs_to" | "plays_theme" | "supersedes" | "counterfactual_of" | "cascade_to" | "mutually_exclusive" | "correlates_with" | "amplifies" | "precondition_for" | "in_tension_with" | "assumes" | "would_predict" | "analogous_to" | "independent_of" | "prerequisite_for" | "parallel_to" | "corroborates" | "extends" | "same_source_as" | "same_theme_as" | "evaluates" | "perspective_on" | "works_at" | "participates_in" | "performs" | "function_in" | "impacts" | "invested_in" | "raised_from" | "mentioned_in" | "founded_by" | "competes_with";
+/**
+ * Normalize confidence to a 0-1 number regardless of input format.
+ *
+ * Handles:
+ * - number (0-1): returned as-is
+ * - number (1-100): divided by 100
+ * - string ("high"/"medium"/"low"): mapped to 0.8/0.5/0.3
+ * - undefined/null/other: returns 0.5 default
+ *
+ * This is the canonical way to read confidence from any source.
+ */
+declare function normalizeConfidence(confidence: unknown): number;
+/**
+ * Epistemic Edge Propagation Semantics
+ *
+ * Each edge type has specific propagation rules for confidence cascades:
+ *
+ * | Edge Type         | Direction    | Propagation Rule                                          |
+ * |-------------------|--------------|-----------------------------------------------------------|
+ * | depends_on        | B → A        | A.conf = min(A.conf, B.conf + 0.2)                       |
+ * | reinforces        | A ↔ B        | Both get boost when either validated                      |
+ * | falsified_by      | B → A        | A.conf = 1 - B.conf (inverse)                            |
+ * | exclusive_with    | A ↔ B        | A.conf + B.conf ≤ 1.0 (redistribute on evidence)         |
+ * | contradicts       | A ↔ B        | Creates tension - neither can be validated without fork   |
+ * | collapses_if      | A → B        | If A.conf < threshold, B.conf → 0                        |
+ * | cascade_from      | A → B        | B.conf_delta = A.conf_delta * damping_factor             |
+ * | strengthened_by   | A → B        | B.conf += A.conf_delta * correlation                     |
+ * | weakened_by       | A → B        | B.conf -= A.conf_delta * correlation                     |
+ * | alternative_to    | A ↔ B        | Evidence for A reduces B, and vice versa                 |
+ * | subsumes          | A → B        | A.conf >= B.conf always                                  |
+ * | validated_by      | A → B        | If A validated, B gains confidence                       |
+ * | required_for      | A → B        | B cannot be validated until A is validated               |
+ * | blocks            | A → B        | B resolution blocked until A resolved                    |
+ */
+/**
+ * Create an epistemic edge between two nodes
+ *
+ * Phase 1 (Graph Architecture): Writes to Neo4j directly - Neo4j is source of truth.
+ * Returns globalId (string) instead of Convex edge ID.
+ *
+ * Phase 2C: Validates layer rules before creation
+ */
+declare function createEpistemicEdge(ctx: MutationCtx, params: {
+    fromNodeId: Id<"epistemicNodes">;
+    toNodeId: Id<"epistemicNodes">;
+    edgeType: EpistemicEdgeType;
+    weight?: number;
+    confidence?: number;
+    context?: string;
+    projectId?: string;
+    createdBy: string;
+    skipLayerValidation?: boolean;
+}): Promise<string>;
+/**
+ * Create an edge when linking an insight to a question
+ * This creates a "derived_from" edge (evidence answers/informs question)
+ */
+declare function createEdgeForInsightQuestionLink(ctx: MutationCtx, questionId: Id<"epistemicNodes">, insightId: Id<"epistemicNodes">, createdBy: string): Promise<string | null>;
+
+declare const epistemicHelpers_EDGE_LAYER_RULES: typeof EDGE_LAYER_RULES;
+type epistemicHelpers_EpistemicLayer = EpistemicLayer;
+declare const epistemicHelpers_LAYER_TRAVERSAL_RULES: typeof LAYER_TRAVERSAL_RULES;
+type epistemicHelpers_TraversalMode = TraversalMode;
+type epistemicHelpers_TraversalOptions = TraversalOptions;
+declare const epistemicHelpers_canTraverseToLayer: typeof canTraverseToLayer;
+declare const epistemicHelpers_createEdgeForInsightQuestionLink: typeof createEdgeForInsightQuestionLink;
+declare const epistemicHelpers_createEpistemicEdge: typeof createEpistemicEdge;
+declare const epistemicHelpers_createEpistemicNodeForArtifact: typeof createEpistemicNodeForArtifact;
+declare const epistemicHelpers_createEpistemicNodeForBelief: typeof createEpistemicNodeForBelief;
+declare const epistemicHelpers_createEpistemicNodeForInsight: typeof createEpistemicNodeForInsight;
+declare const epistemicHelpers_createEpistemicNodeForQuestion: typeof createEpistemicNodeForQuestion;
+declare const epistemicHelpers_getDefaultEdgeTypesForMode: typeof getDefaultEdgeTypesForMode;
+declare const epistemicHelpers_getDefaultMinLayer: typeof getDefaultMinLayer;
+declare const epistemicHelpers_getLayerDepth: typeof getLayerDepth;
+declare const epistemicHelpers_getNeo4jLabel: typeof getNeo4jLabel;
+declare const epistemicHelpers_getNeo4jRelType: typeof getNeo4jRelType;
+declare const epistemicHelpers_getNodeLayer: typeof getNodeLayer;
+declare const epistemicHelpers_isDeprecatedEdgeType: typeof isDeprecatedEdgeType;
+declare const epistemicHelpers_isValidLayerConnection: typeof isValidLayerConnection;
+declare const epistemicHelpers_normalizeConfidence: typeof normalizeConfidence;
+declare const epistemicHelpers_shouldContinueTraversal: typeof shouldContinueTraversal;
+declare const epistemicHelpers_validateEdgeLayers: typeof validateEdgeLayers;
+declare namespace epistemicHelpers {
+  export { epistemicHelpers_EDGE_LAYER_RULES as EDGE_LAYER_RULES, type epistemicHelpers_EpistemicLayer as EpistemicLayer, epistemicHelpers_LAYER_TRAVERSAL_RULES as LAYER_TRAVERSAL_RULES, type epistemicHelpers_TraversalMode as TraversalMode, type epistemicHelpers_TraversalOptions as TraversalOptions, epistemicHelpers_canTraverseToLayer as canTraverseToLayer, epistemicHelpers_createEdgeForInsightQuestionLink as createEdgeForInsightQuestionLink, epistemicHelpers_createEpistemicEdge as createEpistemicEdge, epistemicHelpers_createEpistemicNodeForArtifact as createEpistemicNodeForArtifact, epistemicHelpers_createEpistemicNodeForBelief as createEpistemicNodeForBelief, epistemicHelpers_createEpistemicNodeForInsight as createEpistemicNodeForInsight, epistemicHelpers_createEpistemicNodeForQuestion as createEpistemicNodeForQuestion, epistemicHelpers_getDefaultEdgeTypesForMode as getDefaultEdgeTypesForMode, epistemicHelpers_getDefaultMinLayer as getDefaultMinLayer, epistemicHelpers_getLayerDepth as getLayerDepth, epistemicHelpers_getNeo4jLabel as getNeo4jLabel, epistemicHelpers_getNeo4jRelType as getNeo4jRelType, epistemicHelpers_getNodeLayer as getNodeLayer, epistemicHelpers_isDeprecatedEdgeType as isDeprecatedEdgeType, epistemicHelpers_isValidLayerConnection as isValidLayerConnection, epistemicHelpers_normalizeConfidence as normalizeConfidence, epistemicHelpers_shouldContinueTraversal as shouldContinueTraversal, epistemicHelpers_validateEdgeLayers as validateEdgeLayers };
+}
+
+export { type EpistemicLayer as E, LAYER_TRAVERSAL_RULES as L, type TraversalMode as T, getLayerDepth as a, type TraversalOptions as b, canTraverseToLayer as c, getDefaultMinLayer as d, epistemicHelpers as e, getDefaultEdgeTypesForMode as f, getNodeLayer as g, EDGE_LAYER_RULES as h, isValidLayerConnection as i, createEpistemicNodeForInsight as j, createEpistemicNodeForBelief as k, createEpistemicNodeForQuestion as l, createEpistemicNodeForArtifact as m, normalizeConfidence as n, createEpistemicEdge as o, createEdgeForInsightQuestionLink as p, shouldContinueTraversal as s, validateEdgeLayers as v };

package/dist/epistemicHelpers.d.ts

@@ -0,0 +1,4 @@
+import './convex.js';
+export { a as getNeo4jLabel, b as getNeo4jRelType, i as isDeprecatedEdgeType } from './graphTypes-CpgIuCdo.js';
+export { h as EDGE_LAYER_RULES, E as EpistemicLayer, L as LAYER_TRAVERSAL_RULES, T as TraversalMode, b as TraversalOptions, c as canTraverseToLayer, p as createEdgeForInsightQuestionLink, o as createEpistemicEdge, m as createEpistemicNodeForArtifact, k as createEpistemicNodeForBelief, j as createEpistemicNodeForInsight, l as createEpistemicNodeForQuestion, f as getDefaultEdgeTypesForMode, d as getDefaultMinLayer, a as getLayerDepth, g as getNodeLayer, i as isValidLayerConnection, n as normalizeConfidence, s as shouldContinueTraversal, v as validateEdgeLayers } from './epistemicHelpers-Bd9xbaib.js';
+import 'convex/values';