@lucern/sdk 0.2.0-alpha.5 → 0.2.0-alpha.6

package/dist/lucern/contracts/src/sdk-methods.contract.d.ts

@@ -0,0 +1,358 @@
+/**
+ * SDK Method Contract Definitions
+ *
+ * Canonical method signatures for the Lucern TypeScript SDK.
+ * DERIVED from API contracts — not independently authored.
+ *
+ * These types define the public API of `@lucern/sdk`, covering:
+ *   - client initialization (formerly @lucern/sdk-core)
+ *   - belief, evidence, edge, contradiction operations (formerly @lucern/sdk-graph)
+ *   - branch, worktree, merge, push, pull request lifecycle (formerly @lucern/sdk-workflows)
+ *
+ * Historical note: T7.3.2 (2026-04-18) deleted the three sdk-alpha shim
+ * packages; all surfaces now ship in the single `@lucern/sdk` package.
+ *
+ * CONTRACT SURFACE: Method signatures are semver-bound.
+ * Adding optional parameters is non-breaking.
+ * Changing required parameters or return types is BREAKING.
+ */
+import type { BeliefStatus, BranchStatus, ConfidenceTrigger, ContradictionSeverity, DefeatType, EpistemicLayer, ForkReason, JudgmentType, MergeOutcome, PullRequestStatus, ReasoningMethod } from "./api-enums.contract";
+import type { ContextRankingProfile, PublicCompiledContext } from "./context-pack.contract";
+export type LucernClientConfig = {
+    apiKey: string;
+    environment: "sandbox" | "production";
+    /** Optional base URL override for self-hosted deployments */
+    baseUrl?: string;
+};
+export type LucernClient = {
+    /** The authenticated client instance */
+    readonly config: LucernClientConfig;
+};
+/** Input to createBelief() */
+export type CreateBeliefInput = {
+    canonicalText: string;
+    topicId: string;
+    /** @deprecated Use topicId. */
+    projectId?: string;
+    layer?: EpistemicLayer;
+    domain?: string;
+    nodeType?: string;
+};
+/** Result of createBelief() */
+export type BeliefResult = {
+    nodeId: string;
+    globalId: string;
+    canonicalText: string;
+    status: BeliefStatus;
+    createdAt: number;
+};
+/** Input to refineBelief() */
+export type RefineBeliefInput = {
+    canonicalText: string;
+    rationale?: string;
+};
+/** Input to modulateConfidence() */
+export type ModulateConfidenceInput = {
+    confidence: number;
+    trigger: ConfidenceTrigger;
+    rationale: string;
+};
+/** Result of modulateConfidence() */
+export type ConfidenceResult = {
+    nodeId: string;
+    newConfidence: number;
+    previousConfidence: number | null;
+    trigger: ConfidenceTrigger;
+};
+/** Input to forkBelief() */
+export type ForkBeliefInput = {
+    newFormulation: string;
+    forkReason: ForkReason;
+};
+/** Result of forkBelief() */
+export type ForkResult = {
+    nodeId: string;
+    parentNodeId: string;
+    forkReason: ForkReason;
+    canonicalText: string;
+};
+/** Input to addEvidence() */
+export type AddEvidenceInput = {
+    canonicalText: string;
+    topicId: string;
+    /** @deprecated Use topicId. */
+    projectId?: string;
+    sourceUrl?: string;
+    supports?: {
+        nodeId: string;
+        weight: number;
+        reasoning?: string;
+    };
+};
+/** Result of addEvidence() */
+export type EvidenceResult = {
+    nodeId: string;
+    globalId: string;
+    edgeId?: string;
+};
+/** Input to flagContradiction() */
+export type FlagContradictionInput = {
+    beliefA: string;
+    beliefB: string;
+    description: string;
+    severity: ContradictionSeverity;
+    topicId: string;
+    /** @deprecated Use topicId. */
+    projectId?: string;
+    defeatType?: DefeatType;
+};
+/** Result of flagContradiction() */
+export type ContradictionResult = {
+    contradictionId: string;
+    status: "unresolved";
+    beliefA: string;
+    beliefB: string;
+    defeatType?: DefeatType;
+};
+/** Input to createEdge() */
+export type CreateEdgeInput = {
+    sourceId: string;
+    targetId: string;
+    edgeType: string;
+    weight?: number;
+    reasoning?: string;
+    reasoningMethod?: ReasoningMethod;
+};
+/** Result of createEdge() */
+export type EdgeResult = {
+    globalId: string;
+    edgeType: string;
+    fromLayer: EpistemicLayer;
+    toLayer: EpistemicLayer;
+};
+/** Input to queryLineage() */
+export type QueryLineageInput = {
+    depth?: number;
+};
+/** Result of queryLineage() */
+export type LineageResult = {
+    chain: Array<{
+        nodeId: string;
+        canonicalText: string;
+        confidence: number | null;
+        forkedFrom: string | null;
+        scoredAt: number | null;
+    }>;
+    forkTree: Record<string, string[]>;
+    depth: number;
+};
+/** Input to searchBeliefs() */
+export type SearchBeliefsInput = {
+    query: string;
+    status?: BeliefStatus;
+    minConfidence?: number;
+    topicId?: string;
+    /** @deprecated Use topicId. */
+    projectId?: string;
+    limit?: number;
+};
+/** Input to context.compile() */
+export type CompileContextInput = {
+    query?: string;
+    budget?: number;
+    ranking?: ContextRankingProfile;
+    limit?: number;
+    maxDepth?: number;
+    includeEntities?: boolean;
+};
+/** Result of context.compile() */
+export type CompiledContextResult = PublicCompiledContext;
+/** Input to addWorktree() — like git worktree add <branch> */
+export type AddWorktreeInput = {
+    title: string;
+    topicId: string;
+    /** @deprecated Use topicId. */
+    projectId?: string;
+    branchId?: string;
+    objective?: string;
+    hypothesis?: string;
+    beliefIds?: string[];
+    autoShape?: boolean;
+    domainPackId?: string;
+    executionOrder?: number;
+    dependsOn?: string[];
+    blocks?: string[];
+    gate?: string;
+};
+/** Result of addWorktree() */
+export type WorktreeResult = {
+    worktreeId: string;
+    title: string;
+    status: string;
+    hypothesis?: string;
+    questionCount?: number;
+    taskCount?: number;
+    autoShapeApplied?: boolean;
+};
+/** Input to merge() */
+export type MergeInput = {
+    outcomes: Array<{
+        beliefId: string;
+        confidence: number;
+        rationale: string;
+    }>;
+    summary?: string;
+};
+/** Result of merge() */
+export type MergeResult = {
+    worktreeId: string;
+    status: "merged";
+    outcome: MergeOutcome;
+    beliefsScored: number;
+};
+/** Input to recordJudgment() */
+export type RecordJudgmentInput = {
+    title: string;
+    rationale: string;
+    topicId: string;
+    /** @deprecated Use topicId. */
+    projectId?: string;
+    beliefIds?: string[];
+    confidence?: number;
+    judgmentType?: JudgmentType;
+};
+/** Result of recordJudgment() */
+export type JudgmentResult = {
+    judgmentId: string;
+    title: string;
+    status: "issued";
+};
+/** Input to createBranch() */
+export type CreateBranchInput = {
+    name: string;
+    topicId: string;
+    /** @deprecated Use topicId. */
+    projectId?: string;
+    description?: string;
+};
+/** Result of createBranch() */
+export type BranchResult = {
+    branchId: string;
+    name: string;
+    status: BranchStatus;
+    createdAt: number;
+};
+/** Input to push() */
+export type PushInput = {
+    targetContext: string;
+    beliefIds?: string[];
+};
+/** Result of push() */
+export type PushResult = {
+    pushedCount: number;
+    targetContext: string;
+    pushedAt: number;
+};
+/** Input to openPullRequest() */
+export type OpenPullRequestInput = {
+    reviewers?: string[];
+    summary: string;
+};
+/** Result of openPullRequest() */
+export type PullRequestResult = {
+    pullRequestId: string;
+    worktreeId: string;
+    status: PullRequestStatus;
+};
+/** Input to bisectConfidence() */
+export type BisectConfidenceInput = {
+    expectedDirection: "overconfident" | "underconfident";
+    timeRange?: {
+        start: number;
+        end: number;
+    };
+};
+/** Result of bisectConfidence() */
+export type BisectResult = {
+    inflectionEntry: {
+        confidence: number;
+        trigger: ConfidenceTrigger;
+        rationale: string;
+        timestamp: number;
+    };
+    triggerEvent: string;
+    confidenceBefore: number;
+    confidenceAfter: number;
+};
+/**
+ * @lucern/sdk (graph) method signatures.
+ *
+ * These define the public API. Implementation must match these signatures.
+ * Parameters are the source of truth — generated from API contracts.
+ */
+export type LucernGraphMethods = {
+    createBelief(client: LucernClient, input: CreateBeliefInput): Promise<BeliefResult>;
+    refineBelief(client: LucernClient, nodeId: string, input: RefineBeliefInput): Promise<BeliefResult>;
+    modulateConfidence(client: LucernClient, nodeId: string, input: ModulateConfidenceInput): Promise<ConfidenceResult>;
+    forkBelief(client: LucernClient, nodeId: string, input: ForkBeliefInput): Promise<ForkResult>;
+    archiveBelief(client: LucernClient, nodeId: string, rationale?: string): Promise<{
+        nodeId: string;
+        status: "archived";
+    }>;
+    addEvidence(client: LucernClient, input: AddEvidenceInput): Promise<EvidenceResult>;
+    flagContradiction(client: LucernClient, input: FlagContradictionInput): Promise<ContradictionResult>;
+    createEdge(client: LucernClient, input: CreateEdgeInput): Promise<EdgeResult>;
+    queryLineage(client: LucernClient, nodeId: string, input?: QueryLineageInput): Promise<LineageResult>;
+    getConfidenceHistory(client: LucernClient, nodeId: string): Promise<{
+        entries: Array<{
+            confidence: number;
+            trigger: ConfidenceTrigger;
+            rationale: string;
+            timestamp: number;
+            userId: string;
+        }>;
+    }>;
+    getAuditTrail(client: LucernClient, nodeId: string, limit?: number): Promise<{
+        entries: Array<{
+            action: string;
+            actor: string;
+            timestamp: number;
+            rationale?: string;
+        }>;
+    }>;
+    searchBeliefs(client: LucernClient, input: SearchBeliefsInput): Promise<{
+        results: BeliefResult[];
+    }>;
+    findContradictions(client: LucernClient, input: {
+        topicId?: string;
+        projectId?: string;
+        nodeId?: string;
+        status?: string;
+    }): Promise<{
+        contradictions: ContradictionResult[];
+    }>;
+    traverseGraph(client: LucernClient, input: {
+        startNode: string;
+        direction?: "up" | "down" | "both";
+        maxDepth?: number;
+    }): Promise<{
+        nodes: unknown[];
+        edges: unknown[];
+        depth: number;
+    }>;
+    bisectConfidence(client: LucernClient, nodeId: string, input: BisectConfidenceInput): Promise<BisectResult>;
+    recordJudgment(client: LucernClient, input: RecordJudgmentInput): Promise<JudgmentResult>;
+};
+/**
+ * @lucern/sdk (workflows) method signatures.
+ *
+ * Lifecycle: createBranch (git branch) → addWorktree (git worktree add) →
+ *   openPullRequest (git pull request) → merge (git merge) → push (git push)
+ */
+export type LucernWorkflowMethods = {
+    createBranch(client: LucernClient, input: CreateBranchInput): Promise<BranchResult>;
+    addWorktree(client: LucernClient, input: AddWorktreeInput): Promise<WorktreeResult>;
+    merge(client: LucernClient, worktreeId: string, input: MergeInput): Promise<MergeResult>;
+    openPullRequest(client: LucernClient, worktreeId: string, input: OpenPullRequestInput): Promise<PullRequestResult>;
+    push(client: LucernClient, worktreeId: string, input: PushInput): Promise<PushResult>;
+};

package/dist/lucern/contracts/src/sdk-methods.contract.js

@@ -0,0 +1,19 @@
+/**
+ * SDK Method Contract Definitions
+ *
+ * Canonical method signatures for the Lucern TypeScript SDK.
+ * DERIVED from API contracts — not independently authored.
+ *
+ * These types define the public API of `@lucern/sdk`, covering:
+ *   - client initialization (formerly @lucern/sdk-core)
+ *   - belief, evidence, edge, contradiction operations (formerly @lucern/sdk-graph)
+ *   - branch, worktree, merge, push, pull request lifecycle (formerly @lucern/sdk-workflows)
+ *
+ * Historical note: T7.3.2 (2026-04-18) deleted the three sdk-alpha shim
+ * packages; all surfaces now ship in the single `@lucern/sdk` package.
+ *
+ * CONTRACT SURFACE: Method signatures are semver-bound.
+ * Adding optional parameters is non-breaking.
+ * Changing required parameters or return types is BREAKING.
+ */
+export {};

package/dist/lucern/contracts/src/sdk-tools.contract.d.ts

@@ -0,0 +1,92 @@
+/**
+ * SDK-Only Tool Contract Definitions
+ *
+ * Tools available in @lucern/sdk but NOT in the MCP gateway.
+ * The SDK unfolds deeper capabilities after the MCP gateway shows developers what's possible.
+ *
+ * Total SDK surface = MCP tools (44) + SDK-only tools (44) = 88 tools
+ *
+ * These tools are organized into capability tiers:
+ * - Advanced workflow & phase management (12 tools)
+ * - Deeper graph navigation (6 tools)
+ * - Conviction & analytics (7 tools)
+ * - Extended question & evidence analytics (1 tool; core lifecycle promoted to MCP)
+ * - Task lifecycle (5 tools)
+ * - Domain analytics (8 tools)
+ * - Bias detection suite (5 tools)
+ *
+ * CONTRACT SURFACE: These definitions are the external API for SDK consumers.
+ * Renaming a tool or changing its description is a BREAKING CHANGE.
+ *
+ * Git-native naming rules (same as MCP, enforced by lint):
+ *   1. Workflow tools use git verbs directly
+ *   2. Knowledge tools use epistemic verbs
+ *   3. First sentence of description includes the git analog verb
+ *   4. Description includes "Like `git X`" parenthetical
+ *   5. Parameter names use domain terms (canonicalText, nodeId, confidence)
+ */
+import type { McpToolContract } from "./mcp-tools.contract";
+/** SDK-only tool contract — same shape as MCP but with sdk-only tier marker */
+export interface SdkToolContract extends Omit<McpToolContract, "tier"> {
+    tier: "sdk-only";
+}
+export declare const START_WORKTREE: SdkToolContract;
+export declare const UPDATE_WORKTREE_PHASE: SdkToolContract;
+export declare const ADVANCE_WORKTREE_PHASE: SdkToolContract;
+export declare const ADD_NOTE_TO_WORKTREE: SdkToolContract;
+export declare const LINK_DOCUMENT_TO_WORKTREE: SdkToolContract;
+export declare const LINK_EVIDENCE_TO_WORKTREE: SdkToolContract;
+export declare const LINK_QUESTION_TO_WORKTREE: SdkToolContract;
+export declare const LINK_BELIEF_TO_WORKTREE: SdkToolContract;
+export declare const CREATE_SYNTHESIZED_BELIEF: SdkToolContract;
+export declare const COMPLETE_HYPOTHESIS_FORMATION: SdkToolContract;
+export declare const COMPLETE_EVIDENCE_REVIEW: SdkToolContract;
+export declare const REFINE_WORKTREE_BELIEF: SdkToolContract;
+export declare const TRACE_PROVENANCE: SdkToolContract;
+export declare const GET_BELIEF_RELATIONSHIPS: SdkToolContract;
+export declare const GET_BELIEF_SUPPORT_CHAIN: SdkToolContract;
+export declare const EXPLORE_CONNECTIONS: SdkToolContract;
+export declare const GET_DEEP_LINEAGE: SdkToolContract;
+export declare const GRAPH_AWARE_SEARCH: SdkToolContract;
+export declare const GET_COLLECTION_CONVICTION: SdkToolContract;
+export declare const GET_CONVICTION_TREND: SdkToolContract;
+export declare const ANALYZE_BELIEF_CRITICALITY: SdkToolContract;
+export declare const ANALYZE_BELIEF_CLUSTER_CANDIDATES: SdkToolContract;
+export declare const CREATE_BELIEF_CONDITIONAL: SdkToolContract;
+export declare const GET_NECESSARY_EVIDENCE: SdkToolContract;
+export declare const ANALYZE_REASONING_DEPTH: SdkToolContract;
+export declare const GET_EVIDENCE_BY_METHODOLOGY: SdkToolContract;
+export declare const CREATE_EVIDENCE_TASK: SdkToolContract;
+export declare const LIST_TASKS: SdkToolContract;
+export declare const UPDATE_TASK: SdkToolContract;
+export declare const GET_TASK_COUNTS: SdkToolContract;
+export declare const ADD_RESEARCH_ACTION: SdkToolContract;
+export declare const GET_PREDICTIONS: SdkToolContract;
+export declare const GET_SURPRISE_DETECTION: SdkToolContract;
+export declare const GET_CHALLENGED_BELIEFS: SdkToolContract;
+export declare const GET_CAUSAL_CHAINS: SdkToolContract;
+export declare const GET_NON_CONSENSUS_BELIEFS: SdkToolContract;
+export declare const GET_BELIEFS_BY_EPISTEMIC_STATUS: SdkToolContract;
+export declare const GET_PRIVILEGED_EVIDENCE: SdkToolContract;
+export declare const GET_PRIVILEGED_SIGNALS: SdkToolContract;
+export declare const DETECT_ANCHORING_BIAS: SdkToolContract;
+export declare const DETECT_SOURCE_CONCENTRATION: SdkToolContract;
+export declare const FIND_SOFT_CONTRADICTIONS: SdkToolContract;
+export declare const FIND_SEMANTIC_BRIDGES: SdkToolContract;
+export declare const FIND_SEMANTIC_ORPHANS: SdkToolContract;
+/** All SDK-only tool contracts, indexed by name */
+export declare const SDK_ONLY_TOOL_CONTRACTS: Record<string, SdkToolContract>;
+/** Complete SDK surface: MCP gateway tools + SDK-only advanced tools */
+export declare const ALL_SDK_TOOL_CONTRACTS: Record<string, McpToolContract | SdkToolContract>;
+/** All SDK-only tool names */
+export declare const SDK_ONLY_TOOL_NAMES: string[];
+/** All tool names across the complete SDK surface */
+export declare const ALL_SDK_TOOL_NAMES: string[];
+/**
+ * Lint validation: every SDK tool description must contain "Like `git" reference.
+ * Reuses the same git-semantic validation rule as MCP tools.
+ */
+export declare function validateSdkGitSemantics(tool: SdkToolContract): {
+    valid: boolean;
+    reason?: string;
+};