@lucern/graph-primitives 0.1.0-alpha.2

package/dist/epistemicBeliefs-DtFVTp-k.d.ts

@@ -0,0 +1,377 @@
+import { VerificationConfidenceTrigger, SLOperator } from '@lucern/confidence';
+import { B as BeliefLifecycleStatus } from './beliefLifecycle-C-AehZgF.js';
+import { Doc, MutationCtx, Id } from './convex.js';
+
+/**
+ * Epistemic Beliefs API
+ *
+ * Clean API for managing beliefs in the epistemic spine (epistemicNodes).
+ * This is the NEW API that replaces beliefs.ts.
+ *
+ * Key differences from beliefs.ts:
+ * - Writes ONLY to epistemicNodes (no dual-write)
+ * - Uses epistemicNodes IDs directly (no runtime ID translation fallback)
+ * - Syncs to Neo4j after mutations
+ * - Follows Lucern invariants strictly
+ *
+ * @see /docs/epistemic-invariants/00-epistemic-invariants.md
+ */
+
+type BeliefConfidenceTrigger = "initial" | "evidence_added" | "evidence_removed" | "contradiction_detected" | "contradiction_resolved" | "manual" | "decay" | "agent_assessment" | "worktree_outcome" | "worktree_completed" | "fusion" | "discount" | "deduction" | "backfill_synthetic" | VerificationConfidenceTrigger;
+declare function resolveBeliefWorktreeId(metadata: Record<string, unknown> | undefined): string | undefined;
+declare function flattenBeliefNode(node: Doc<"epistemicNodes">): {
+    _id: any;
+    _epistemicNodeId: any;
+    _creationTime: any;
+    belief: any;
+    formulation: any;
+    projectId: any;
+    topicId: any;
+    userId: any;
+    confidence: "high" | "medium" | "low";
+    status: any;
+    beliefStatus: BeliefLifecycleStatus;
+    topic: string;
+    pillar: string;
+    category: string;
+    subcategory: string;
+    categoryIcon: string;
+    supportingEvidence: string[];
+    contradictingEvidence: string[];
+    testingQuestions: string[];
+    linkedInsights: string[];
+    createdAt: any;
+    updatedAt: any;
+    tupleContradicted: boolean;
+    sprintId: string | undefined;
+    worktreeId: string | undefined;
+    sourceBeliefIds: string[];
+    criticality: "critical" | "blocking" | "supporting" | "nice_to_have" | "unanalyzed" | "important";
+    rationale: string;
+    audienceLabel: any;
+    policyTags: any;
+    sensitivityTier: any;
+    exportClass: any;
+    anonymizationClass: any;
+};
+declare function applyBeliefConfidenceChange(ctx: MutationCtx, args: {
+    nodeId: Id<"epistemicNodes">;
+    belief: number;
+    disbelief: number;
+    uncertainty: number;
+    baseRate?: number;
+    trigger: BeliefConfidenceTrigger;
+    rationale?: string;
+    authenticatedUserId: string;
+    slOperator?: SLOperator;
+    triggeringEvidenceId?: Id<"epistemicNodes">;
+    triggeringWorktreeId?: string;
+}): Promise<{
+    nodeId: Id<"epistemicNodes">;
+    previousConfidence: number;
+    newConfidence: number;
+    opinion: {
+        b: number;
+        d: number;
+        u: number;
+        a: number;
+    };
+    beliefConfidenceId: Id<"beliefConfidence">;
+}>;
+/**
+ * Propagate a confidence change through graph edges whose specs allow it.
+ *
+ * After a belief is scored, this function:
+ * 1. Reads the graph-primitives edge propagation specs
+ * 2. Traverses matching incoming/outgoing/bidirectional edges hop by hop
+ * 3. Applies the edge operator with per-hop damping and hop limits
+ * 4. Writes propagated opinions as new beliefConfidence entries
+ */
+declare const propagateConfidenceChange: any;
+/**
+ * Create a new belief in the epistemic spine.
+ * Returns the epistemicNodes ID directly (not a beliefs ID).
+ */
+declare const create: any;
+/**
+ * Get a belief by its epistemicNodes ID.
+ */
+declare const getById: any;
+/**
+ * Refine an unscored belief in place.
+ *
+ * Lucern Invariant #1 + #2: Draft beliefs may be refined in place, but scored
+ * beliefs are immutable and must be evolved through forkBelief().
+ */
+declare const refineBelief: any;
+/**
+ * Get all beliefs for a project.
+ */
+declare const getByProject: any;
+/**
+ * Get all beliefs for a topic.
+ */
+declare const getByTopic: any;
+/**
+ * Fork a belief - create a new version while preserving the original.
+ * This is the Lucern-compliant way to "update" a belief.
+ *
+ * Lucern Invariant #1: Beliefs are append-only. Never modify formulation.
+ * Lucern Invariant #3: Lineage is permanent.
+ */
+declare const forkBelief: any;
+/**
+ * Modulate a belief's confidence.
+ *
+ * Lucern Invariant #2: Confidence changes are append-only (tracked in beliefConfidence table).
+ */
+declare const modulateConfidence: any;
+/**
+ * Update a belief's status.
+ */
+declare const updateStatus: any;
+/**
+ * Archive a belief (soft delete).
+ * Lucern invariant: Beliefs are never deleted, only archived.
+ */
+declare const archive: any;
+/**
+ * Update a belief rationale without changing formulation.
+ * Formulation mutability rules are unchanged (use fork/refine paths for wording).
+ */
+declare const updateRationale: any;
+declare const updateStatusInternal: any;
+/**
+ * Get the confidence history for a belief.
+ */
+declare const getConfidenceHistory: any;
+/**
+ * Get the lineage of a belief (all forks and parents).
+ */
+declare const getLineage: any;
+/**
+ * Get multiple beliefs by their IDs.
+ */
+declare const getByIds: any;
+/**
+ * Get all beliefs associated with a worktree via worktreeBeliefCluster.
+ */
+declare const getByWorktree: any;
+/**
+ * Update a belief's pillar/topic categorization.
+ * Uses canonical epistemicNodes IDs.
+ */
+declare const updatePillar: any;
+/**
+ * Get counts of beliefs by status for a project.
+ */
+declare const getCountByStatus: any;
+/**
+ * Create an edge between two beliefs in the epistemic spine.
+ * This works with epistemicNodes IDs directly (no legacy lookup needed).
+ */
+declare const linkBeliefs: any;
+/**
+ * Link an insight (evidence) to a belief.
+ * Creates an edge from evidence → belief with appropriate type.
+ */
+declare const linkEvidence: any;
+/**
+ * Remove the link between an insight and a belief.
+ */
+declare const unlinkEvidence: any;
+/**
+ * Get a belief along with all its linked evidence.
+ */
+declare const getWithEvidence: any;
+/**
+ * Get all relationships (edges) for a belief.
+ */
+declare const getRelationships: any;
+/**
+ * Delete a relationship (edge) between nodes.
+ */
+declare const deleteRelationship: any;
+/**
+ * Update a belief's criticality level.
+ */
+declare const updateCriticality: any;
+/**
+ * Batch update criticality for multiple beliefs.
+ * Uses canonical epistemicNodes IDs.
+ */
+declare const batchUpdateCriticality: any;
+/**
+ * Get beliefs by criticality level.
+ */
+declare const getByCriticality: any;
+/**
+ * Get beliefs that haven't been analyzed yet.
+ * Used by BI agents for batch processing.
+ */
+declare const getUnanalyzed: any;
+/**
+ * Get all beliefs for a project (system level - no auth check).
+ * Used by BI agents and thesis audit agents.
+ */
+declare const getByProjectSystem: any;
+/**
+ * Get beliefs filtered by pillar/topic.
+ */
+declare const getByPillar: any;
+/**
+ * Get the belief cluster for a worktree.
+ * Returns all beliefs linked to the worktree and their relationships.
+ */
+declare const getWorktreeCluster: any;
+/**
+ * Internal query to get beliefs for a project.
+ * Returns epistemicNodes in legacy beliefs format for backward compatibility.
+ *
+ * @internal Use by other Convex functions only
+ */
+declare const internalGetByProject: any;
+/**
+ * Internal query to get beliefs for a topic.
+ *
+ * @internal Use by other Convex functions only
+ */
+declare const internalGetByTopic: any;
+/**
+ * Internal query to get active beliefs for a project.
+ *
+ * @internal Use by other Convex functions only
+ */
+declare const internalGetActive: any;
+/**
+ * Internal query to get a single belief by ID.
+ * Uses canonical epistemicNodes IDs.
+ *
+ * @internal Use by other Convex functions only
+ */
+declare const internalGetById: any;
+/**
+ * Internal mutation to create a belief.
+ * Creates ONLY in epistemicNodes (no dual-write).
+ *
+ * @internal Use by other Convex functions only
+ */
+declare const internalCreate: any;
+/**
+ * Get recent confidence changes for beliefs in a project.
+ * Shows beliefs that have had confidence updates via propagation, decay,
+ * or other users - useful for "Attention Needed" dashboard panel.
+ */
+declare const getRecentConfidenceChanges: any;
+/**
+ * Backfill synthetic t0 opinion-history rows for legacy beliefs that have
+ * node-level opinion/confidence metadata but no beliefConfidence history.
+ *
+ * Run with:
+ *   npx convex run epistemicBeliefs:backfillSyntheticOpinionHistory '{"limit":100}'
+ */
+declare const backfillSyntheticOpinionHistory: any;
+/**
+ * Backfill mandatory priors for legacy beliefs created before LKC-2.
+ *
+ * Run with:
+ *   npx convex run epistemicBeliefs:backfillMandatoryPriors '{"limit":100}'
+ */
+declare const backfillMandatoryPriors: any;
+/**
+ * Backfill valence + certainty on beliefConfidence records and epistemicNodes metadata.
+ * Converts existing single-number confidence to two-axis:
+ *   valence = confidence * 2 - 1  (maps 0→-1, 0.5→0, 1→+1)
+ *   certainty = |confidence - 0.5| * 2  (maps 0.5→0, 0/1→1)
+ *
+ * Run with: npx convex run epistemicBeliefs:backfillTwoAxisConfidence '{}'
+ */
+declare const backfillTwoAxisConfidence: any;
+/**
+ * Backfill: Create relates_to_thesis edges for confidence-bearing beliefs in a project.
+ *
+ * When modulateConfidence was missing the edge-creation step, beliefs got scored
+ * but never linked to the project's theme node. This backfill fixes that.
+ *
+ * Run: npx convex run epistemicBeliefs:backfillScoredBeliefEdges '{"projectId":"<id>"}'
+ * Dry run first: npx convex run epistemicBeliefs:backfillScoredBeliefEdges '{"projectId":"<id>","dryRun":true}'
+ */
+declare const backfillScoredBeliefEdges: any;
+/**
+ * @deprecated Legacy sprint backfill — removed. Sprints are D-tier.
+ * Kept as no-op stub to avoid breaking deployed function references.
+ */
+declare const backfillBeliefSprintIds: any;
+/**
+ * Get belief cluster positions for visualization.
+ * Classifies each belief as "clustered" (in a worktree) or "unprocessed"
+ * based on worktreeBeliefCluster membership.
+ *
+ * Used by PillarDetailPanel, PillarsPanel, BeliefListPanel.
+ */
+declare const getBeliefClusterPositions: any;
+/**
+ * Reassign a batch of belief nodes to a different topic.
+ *
+ * Used by the density-based auto-branching system when beliefs are moved
+ * from a parent topic into newly created subtopics. Patches `topicId`
+ * and `updatedAt` on the target beliefs, and also reassigns any questions
+ * and evidence nodes that are connected to the reassigned beliefs via edges.
+ *
+ * Skips nodes that don't exist or aren't active.
+ */
+declare const reassignBeliefsTopic: any;
+
+type epistemicBeliefs_BeliefConfidenceTrigger = BeliefConfidenceTrigger;
+declare const epistemicBeliefs_applyBeliefConfidenceChange: typeof applyBeliefConfidenceChange;
+declare const epistemicBeliefs_archive: typeof archive;
+declare const epistemicBeliefs_backfillBeliefSprintIds: typeof backfillBeliefSprintIds;
+declare const epistemicBeliefs_backfillMandatoryPriors: typeof backfillMandatoryPriors;
+declare const epistemicBeliefs_backfillScoredBeliefEdges: typeof backfillScoredBeliefEdges;
+declare const epistemicBeliefs_backfillSyntheticOpinionHistory: typeof backfillSyntheticOpinionHistory;
+declare const epistemicBeliefs_backfillTwoAxisConfidence: typeof backfillTwoAxisConfidence;
+declare const epistemicBeliefs_batchUpdateCriticality: typeof batchUpdateCriticality;
+declare const epistemicBeliefs_create: typeof create;
+declare const epistemicBeliefs_deleteRelationship: typeof deleteRelationship;
+declare const epistemicBeliefs_flattenBeliefNode: typeof flattenBeliefNode;
+declare const epistemicBeliefs_forkBelief: typeof forkBelief;
+declare const epistemicBeliefs_getBeliefClusterPositions: typeof getBeliefClusterPositions;
+declare const epistemicBeliefs_getByCriticality: typeof getByCriticality;
+declare const epistemicBeliefs_getById: typeof getById;
+declare const epistemicBeliefs_getByIds: typeof getByIds;
+declare const epistemicBeliefs_getByPillar: typeof getByPillar;
+declare const epistemicBeliefs_getByProject: typeof getByProject;
+declare const epistemicBeliefs_getByProjectSystem: typeof getByProjectSystem;
+declare const epistemicBeliefs_getByTopic: typeof getByTopic;
+declare const epistemicBeliefs_getByWorktree: typeof getByWorktree;
+declare const epistemicBeliefs_getConfidenceHistory: typeof getConfidenceHistory;
+declare const epistemicBeliefs_getCountByStatus: typeof getCountByStatus;
+declare const epistemicBeliefs_getLineage: typeof getLineage;
+declare const epistemicBeliefs_getRecentConfidenceChanges: typeof getRecentConfidenceChanges;
+declare const epistemicBeliefs_getRelationships: typeof getRelationships;
+declare const epistemicBeliefs_getUnanalyzed: typeof getUnanalyzed;
+declare const epistemicBeliefs_getWithEvidence: typeof getWithEvidence;
+declare const epistemicBeliefs_getWorktreeCluster: typeof getWorktreeCluster;
+declare const epistemicBeliefs_internalCreate: typeof internalCreate;
+declare const epistemicBeliefs_internalGetActive: typeof internalGetActive;
+declare const epistemicBeliefs_internalGetById: typeof internalGetById;
+declare const epistemicBeliefs_internalGetByProject: typeof internalGetByProject;
+declare const epistemicBeliefs_internalGetByTopic: typeof internalGetByTopic;
+declare const epistemicBeliefs_linkBeliefs: typeof linkBeliefs;
+declare const epistemicBeliefs_linkEvidence: typeof linkEvidence;
+declare const epistemicBeliefs_modulateConfidence: typeof modulateConfidence;
+declare const epistemicBeliefs_propagateConfidenceChange: typeof propagateConfidenceChange;
+declare const epistemicBeliefs_reassignBeliefsTopic: typeof reassignBeliefsTopic;
+declare const epistemicBeliefs_refineBelief: typeof refineBelief;
+declare const epistemicBeliefs_resolveBeliefWorktreeId: typeof resolveBeliefWorktreeId;
+declare const epistemicBeliefs_unlinkEvidence: typeof unlinkEvidence;
+declare const epistemicBeliefs_updateCriticality: typeof updateCriticality;
+declare const epistemicBeliefs_updatePillar: typeof updatePillar;
+declare const epistemicBeliefs_updateRationale: typeof updateRationale;
+declare const epistemicBeliefs_updateStatus: typeof updateStatus;
+declare const epistemicBeliefs_updateStatusInternal: typeof updateStatusInternal;
+declare namespace epistemicBeliefs {
+  export { type epistemicBeliefs_BeliefConfidenceTrigger as BeliefConfidenceTrigger, epistemicBeliefs_applyBeliefConfidenceChange as applyBeliefConfidenceChange, epistemicBeliefs_archive as archive, epistemicBeliefs_backfillBeliefSprintIds as backfillBeliefSprintIds, epistemicBeliefs_backfillMandatoryPriors as backfillMandatoryPriors, epistemicBeliefs_backfillScoredBeliefEdges as backfillScoredBeliefEdges, epistemicBeliefs_backfillSyntheticOpinionHistory as backfillSyntheticOpinionHistory, epistemicBeliefs_backfillTwoAxisConfidence as backfillTwoAxisConfidence, epistemicBeliefs_batchUpdateCriticality as batchUpdateCriticality, epistemicBeliefs_create as create, epistemicBeliefs_deleteRelationship as deleteRelationship, epistemicBeliefs_flattenBeliefNode as flattenBeliefNode, epistemicBeliefs_forkBelief as forkBelief, epistemicBeliefs_getBeliefClusterPositions as getBeliefClusterPositions, epistemicBeliefs_getByCriticality as getByCriticality, epistemicBeliefs_getById as getById, epistemicBeliefs_getByIds as getByIds, epistemicBeliefs_getByPillar as getByPillar, epistemicBeliefs_getByProject as getByProject, epistemicBeliefs_getByProjectSystem as getByProjectSystem, epistemicBeliefs_getByTopic as getByTopic, epistemicBeliefs_getByWorktree as getByWorktree, epistemicBeliefs_getConfidenceHistory as getConfidenceHistory, epistemicBeliefs_getCountByStatus as getCountByStatus, epistemicBeliefs_getLineage as getLineage, epistemicBeliefs_getRecentConfidenceChanges as getRecentConfidenceChanges, epistemicBeliefs_getRelationships as getRelationships, epistemicBeliefs_getUnanalyzed as getUnanalyzed, epistemicBeliefs_getWithEvidence as getWithEvidence, epistemicBeliefs_getWorktreeCluster as getWorktreeCluster, epistemicBeliefs_internalCreate as internalCreate, epistemicBeliefs_internalGetActive as internalGetActive, epistemicBeliefs_internalGetById as internalGetById, epistemicBeliefs_internalGetByProject as internalGetByProject, epistemicBeliefs_internalGetByTopic as internalGetByTopic, epistemicBeliefs_linkBeliefs as linkBeliefs, epistemicBeliefs_linkEvidence as linkEvidence, epistemicBeliefs_modulateConfidence as modulateConfidence, epistemicBeliefs_propagateConfidenceChange as propagateConfidenceChange, epistemicBeliefs_reassignBeliefsTopic as reassignBeliefsTopic, epistemicBeliefs_refineBelief as refineBelief, epistemicBeliefs_resolveBeliefWorktreeId as resolveBeliefWorktreeId, epistemicBeliefs_unlinkEvidence as unlinkEvidence, epistemicBeliefs_updateCriticality as updateCriticality, epistemicBeliefs_updatePillar as updatePillar, epistemicBeliefs_updateRationale as updateRationale, epistemicBeliefs_updateStatus as updateStatus, epistemicBeliefs_updateStatusInternal as updateStatusInternal };
+}
+
+export { getRelationships as A, type BeliefConfidenceTrigger as B, deleteRelationship as C, updateCriticality as D, batchUpdateCriticality as E, getByCriticality as F, getUnanalyzed as G, getByProjectSystem as H, getByPillar as I, getWorktreeCluster as J, internalGetByProject as K, internalGetByTopic as L, internalGetActive as M, internalGetById as N, internalCreate as O, getRecentConfidenceChanges as P, backfillSyntheticOpinionHistory as Q, backfillMandatoryPriors as R, backfillTwoAxisConfidence as S, backfillScoredBeliefEdges as T, backfillBeliefSprintIds as U, getBeliefClusterPositions as V, reassignBeliefsTopic as W, applyBeliefConfidenceChange as a, refineBelief as b, create as c, getByProject as d, epistemicBeliefs as e, flattenBeliefNode as f, getById as g, getByTopic as h, forkBelief as i, archive as j, updateRationale as k, updateStatusInternal as l, modulateConfidence as m, getConfidenceHistory as n, getLineage as o, propagateConfidenceChange as p, getByIds as q, resolveBeliefWorktreeId as r, getByWorktree as s, updatePillar as t, updateStatus as u, getCountByStatus as v, linkBeliefs as w, linkEvidence as x, unlinkEvidence as y, getWithEvidence as z };

package/dist/epistemicBeliefs.d.ts

@@ -0,0 +1,5 @@
+import '@lucern/confidence';
+import './beliefLifecycle-C-AehZgF.js';
+import './convex.js';
+export { B as BeliefConfidenceTrigger, a as applyBeliefConfidenceChange, j as archive, U as backfillBeliefSprintIds, R as backfillMandatoryPriors, T as backfillScoredBeliefEdges, Q as backfillSyntheticOpinionHistory, S as backfillTwoAxisConfidence, E as batchUpdateCriticality, c as create, C as deleteRelationship, f as flattenBeliefNode, i as forkBelief, V as getBeliefClusterPositions, F as getByCriticality, g as getById, q as getByIds, I as getByPillar, d as getByProject, H as getByProjectSystem, h as getByTopic, s as getByWorktree, n as getConfidenceHistory, v as getCountByStatus, o as getLineage, P as getRecentConfidenceChanges, A as getRelationships, G as getUnanalyzed, z as getWithEvidence, J as getWorktreeCluster, O as internalCreate, M as internalGetActive, N as internalGetById, K as internalGetByProject, L as internalGetByTopic, w as linkBeliefs, x as linkEvidence, m as modulateConfidence, p as propagateConfidenceChange, W as reassignBeliefsTopic, b as refineBelief, r as resolveBeliefWorktreeId, y as unlinkEvidence, D as updateCriticality, t as updatePillar, k as updateRationale, u as updateStatus, l as updateStatusInternal } from './epistemicBeliefs-DtFVTp-k.js';
+import 'convex/values';