@lucern/sdk 0.2.0-alpha.2 → 0.2.0-alpha.3

package/dist/packages/sdk/src/contracts/api-enums.contract.d.ts

@@ -2,57 +2,78 @@
  * API Enum Contract Definitions
  *
  * Canonical enum values for all API-facing enumerations.
- * These are co-equal with MCP contracts as external contracts.
- * SDK types are DERIVED from these — not independently authored.
+ * These MUST match the kernel schema validators exactly.
  *
- * CONTRACT SURFACE: Adding a new enum value is additive (non-breaking).
- * Removing or renaming an existing value is a BREAKING CHANGE.
+ * Source of truth: packages/convex-kernel/src/component/schema/spine/
  */
-/** Fork reasons — why a scored belief was branched */
+/**
+ * Belief epistemic lifecycle — tracks maturity from raw claim to verified fact.
+ *
+ * - assumption: Untested raw claim, lowest epistemic standing
+ * - hypothesis: Under active investigation, being tested against evidence
+ * - belief: Validated through investigation, carries confidence score
+ * - fact: Resolved outcome anchored by strong evidence
+ */
+export declare const BELIEF_STATUSES: readonly ["assumption", "hypothesis", "belief", "fact"];
+export type BeliefStatus = (typeof BELIEF_STATUSES)[number];
+/** Why a scored belief was branched into a new version */
 export declare const FORK_REASONS: readonly ["refinement", "contradiction_response", "scope_change", "confidence_collapse", "manual"];
 export type ForkReason = (typeof FORK_REASONS)[number];
-/** Confidence modulation triggers — what caused a confidence change */
-export declare const CONFIDENCE_TRIGGERS: readonly ["evidence_added", "contradiction_detected", "merge_outcome", "manual", "decay"];
+/** What caused a confidence change — every modulation must declare its trigger */
+export declare const CONFIDENCE_TRIGGERS: readonly ["evidence_added", "contradiction_detected", "merge_outcome", "worktree_outcome", "manual", "decay"];
 export type ConfidenceTrigger = (typeof CONFIDENCE_TRIGGERS)[number];
-/** Belief status — lifecycle state */
-export declare const BELIEF_STATUSES: readonly ["unscored", "scored", "archived"];
-export type BeliefStatus = (typeof BELIEF_STATUSES)[number];
-/** Reasoning methods — how an edge relationship was determined */
+/**
+ * Core epistemic edge types — the grammar of reasoning relationships.
+ *
+ * - supports: Evidence or belief reinforces another belief (weight = strength)
+ * - informs: Evidence bears on a belief (directional, weighted)
+ * - depends_on: Belief B requires belief A to hold
+ * - derived_from: Belief was derived from another (lineage)
+ * - contains: Structural containment (topic contains beliefs)
+ * - tests: Question tests a belief (falsification link)
+ */
+export declare const EPISTEMIC_EDGE_TYPES: readonly ["supports", "informs", "depends_on", "derived_from", "contains", "tests"];
+export type EpistemicEdgeType = (typeof EPISTEMIC_EDGE_TYPES)[number];
+/** Structural and lifecycle edges — required for graph integrity */
+export declare const STRUCTURAL_EDGE_TYPES: readonly ["supersedes", "responds_to", "belongs_to", "relates_to_thesis"];
+export type StructuralEdgeType = (typeof STRUCTURAL_EDGE_TYPES)[number];
+/** All valid edge types (epistemic + structural) */
+export declare const EDGE_TYPES: readonly ["supports", "informs", "depends_on", "derived_from", "contains", "tests", "supersedes", "responds_to", "belongs_to", "relates_to_thesis"];
+export type EdgeType = EpistemicEdgeType | StructuralEdgeType;
+/** How an edge relationship was determined */
 export declare const REASONING_METHODS: readonly ["deductive", "inductive", "abductive", "analogical", "empirical"];
 export type ReasoningMethod = (typeof REASONING_METHODS)[number];
 /** Defeat types (Pollock taxonomy) — how a contradiction operates */
 export declare const DEFEAT_TYPES: readonly ["rebuts", "undercuts", "undermines"];
 export type DefeatType = (typeof DEFEAT_TYPES)[number];
-/** Contradiction severity levels */
+/** Contradiction severity */
 export declare const CONTRADICTION_SEVERITIES: readonly ["low", "medium", "high", "critical"];
 export type ContradictionSeverity = (typeof CONTRADICTION_SEVERITIES)[number];
 /** Contradiction resolution status */
 export declare const CONTRADICTION_STATUSES: readonly ["unresolved", "resolved", "accepted"];
 export type ContradictionStatus = (typeof CONTRADICTION_STATUSES)[number];
-/** Merge outcome types — how a worktree merge resolved */
+/** How a worktree investigation concluded */
 export declare const MERGE_OUTCOMES: readonly ["validated", "invalidated", "forked", "inconclusive"];
 export type MergeOutcome = (typeof MERGE_OUTCOMES)[number];
-/** Worktree phases — investigation lifecycle within a checked-out worktree */
+/** Investigation phases within a worktree */
 export declare const WORKTREE_PHASES: readonly ["hypothesis", "investigation", "evaluation", "resolution"];
 export type WorktreePhase = (typeof WORKTREE_PHASES)[number];
-/** Branch status — thematic branch lifecycle */
-export declare const BRANCH_STATUSES: readonly ["dormant", "active", "archived"];
-export type BranchStatus = (typeof BRANCH_STATUSES)[number];
-/** Pull request status — review lifecycle before merge */
-export declare const PULL_REQUEST_STATUSES: readonly ["pending_review", "changes_requested", "approved", "blocked"];
-export type PullRequestStatus = (typeof PULL_REQUEST_STATUSES)[number];
-/** Epistemic layers — the hierarchy of knowledge */
+/**
+ * The knowledge hierarchy — each layer builds on the one below it.
+ *
+ * - L1: Sources — raw inputs (documents, APIs, observations)
+ * - L2: Evidence — interpreted facts with context and weight
+ * - L3: Beliefs — structural claims that carry confidence
+ * - L4: Judgments — irreversible commitments based on the epistemic state
+ */
 export declare const EPISTEMIC_LAYERS: readonly ["L1", "L2", "L3", "L4"];
 export type EpistemicLayer = (typeof EPISTEMIC_LAYERS)[number];
 /**
- * Judgment type — classification of the determination.
+ * Classification of L4 judgments — irreversible determinations.
  *
- * Phase 1: These are new enum values for the Judgment (L4) vocabulary.
- * The existing code uses "Decision" — these are the forward-looking terms
- * that will eventually replace the Decision vocabulary (Phase 2-3).
+ * Judgments are evaluated against the knowledge horizon that existed
+ * when they were made. They cannot be retroactively invalidated —
+ * only new judgments can supersede old ones.
  */
-export declare const JUDGMENT_TYPES: readonly ["investment_thesis", "thesis_maturity", "contradiction_ruling", "scope_determination", "confidence_ruling"];
+export declare const JUDGMENT_TYPES: readonly ["thesis", "thesis_maturity", "contradiction_ruling", "scope_determination", "confidence_ruling"];
 export type JudgmentType = (typeof JUDGMENT_TYPES)[number];
-/** Core edge types used in the Integration Surfaces */
-export declare const INTEGRATION_EDGE_TYPES: readonly ["informs", "grounds", "answers", "contradicts", "weakened_by", "undermined_by", "depends_on", "cascades_to", "supersedes", "in_tension_with", "implies", "tests"];
-export type IntegrationEdgeType = (typeof INTEGRATION_EDGE_TYPES)[number];

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lucern/sdk",
-  "version": "0.2.0-alpha.2",
+  "version": "0.2.0-alpha.3",
   "description": "Lucern reasoning platform SDK. Install this one package, provide your API key, and start building in 10 minutes.",
   "license": "UNLICENSED",
   "type": "module",