@lucern/sdk 0.2.0-alpha.1 → 0.2.0-alpha.10

package/dist/beliefsClient.d.ts

@@ -0,0 +1,242 @@
+import { JsonObject, PlatformBeliefRecord, ModulateConfidenceResponse, ForkBeliefResponse } from './types.js';
+export { CreateBeliefResponse } from './types.js';
+import { GatewayClientConfig, PlatformGatewaySuccess } from './coreClient.js';
+export { LucernApiError } from './coreClient.js';
+import { Opinion } from '@lucern/confidence';
+export { Opinion } from '@lucern/confidence';
+import './contracts/workflow-runtime.contract.js';
+import './contracts/lens-workflow.contract.js';
+import './contracts/lens-filter.contract.js';
+
+/** Configuration for the beliefs client. Inherits gateway transport settings. */
+type BeliefsClientConfig = GatewayClientConfig;
+type OpinionHistoryEntry = {
+    t: number;
+    b: number;
+    d: number;
+    u: number;
+    a: number;
+    P: number;
+    trigger: string;
+    triggeringRef?: {
+        kind: "evidence" | "worktree";
+        id: string;
+    };
+    rationale?: string;
+    userId?: string;
+    slOperator?: string;
+};
+type GatewayRecord = Record<string, unknown>;
+declare function mapOpinionHistoryEntriesFromGatewayData(payload: GatewayRecord): OpinionHistoryEntry[];
+/**
+ * Input for creating a new belief within a topic scope.
+ *
+ * Use `text` as the canonical belief statement.
+ * `canonicalText` remains available as a legacy alias for backwards compatibility.
+ * Beliefs start as drafts but must carry a prior via `baseRate`, which is
+ * stored as the vacuous opinion `(0, 0, 1, a)` at creation time.
+ */
+type CreateBeliefInput = {
+    topicId?: string;
+    /** Preferred belief statement alias. */
+    text?: string;
+    /** @deprecated Use text. */
+    canonicalText?: string;
+    layer?: "L1" | "L2" | "L3" | "L4";
+    domain?: string;
+    sourceType?: "human" | "ai" | "agent" | "imported";
+    content?: string;
+    contentHash?: string;
+    globalId?: string;
+    title?: string;
+    subtype?: string;
+    confidence?: number;
+    baseRate: number;
+    tags?: string[];
+    metadata?: JsonObject;
+    verificationStatus?: "unverified" | "verified" | "rejected";
+};
+/**
+ * Input for refining an existing draft belief.
+ *
+ * Use `text` as the canonical belief statement.
+ * `canonicalText` remains available as a legacy alias for backwards compatibility.
+ */
+type RefineBeliefInput = {
+    /** Preferred belief statement alias. */
+    text?: string;
+    /** @deprecated Use text. */
+    canonicalText?: string;
+    rationale?: string;
+    title?: string;
+};
+type BeliefConfidenceTrigger = "evidence_added" | "evidence_removed" | "contradiction_detected" | "contradiction_resolved" | "manual" | "decay" | "agent_assessment" | "worktree_outcome" | "worktree_completed" | "fusion" | "discount" | "deduction";
+type ModulateConfidenceInputBase = {
+    trigger?: BeliefConfidenceTrigger;
+    rationale: string;
+    maxInlinePropagationTargets?: number;
+};
+/**
+ * Record an append-only confidence change using an explicit subjective-logic
+ * opinion tuple.
+ */
+type ModulateConfidenceOpinionInput = ModulateConfidenceInputBase & {
+    opinion: Opinion;
+};
+/**
+ * @deprecated Prefer passing `opinion` directly or call an `opinionFrom*`
+ * helper before invoking `modulateConfidence`.
+ */
+type ModulateConfidenceScalarInput = (ModulateConfidenceInputBase & {
+    confidence: number;
+    interpretation: "base_rate";
+}) | (ModulateConfidenceInputBase & {
+    confidence: number;
+    interpretation: "dogmatic";
+    baseRate?: number;
+}) | (ModulateConfidenceInputBase & {
+    confidence: number;
+    interpretation: "projected";
+    uncertainty: number;
+    baseRate?: number;
+});
+type ModulateConfidenceInput = ModulateConfidenceOpinionInput | ModulateConfidenceScalarInput;
+/**
+ * Input for forking a scored belief into a new formulation.
+ * Scored beliefs are immutable — fork to evolve understanding.
+ */
+type ForkBeliefInput = {
+    newFormulation: string;
+    forkReason?: "refinement" | "contradiction_response" | "scope_change" | "confidence_collapse" | "manual";
+    rationale?: string;
+};
+/** Input for changing a belief's lifecycle status. */
+type UpdateBeliefStatusInput = {
+    id?: string;
+    nodeId?: string;
+    beliefId?: string;
+    status: "active" | "superseded" | "archived";
+    reason?: string;
+};
+/** Input for updating a belief's rationale without refining its text. */
+type UpdateBeliefRationaleInput = {
+    id?: string;
+    nodeId?: string;
+    beliefId?: string;
+    rationale?: string;
+};
+/** Input for creating a belief-to-belief reasoning edge. */
+type LinkBeliefsInput = {
+    fromNodeId: string;
+    toNodeId: string;
+    edgeType: string;
+    weight?: number;
+    context?: string;
+};
+/** Input for unlinking a belief from an attached evidence item. */
+type UnlinkBeliefEvidenceInput = {
+    beliefNodeId?: string;
+    beliefId?: string;
+    nodeId?: string;
+    insightId?: string;
+    evidenceId?: string;
+};
+/** Input for updating a belief's criticality classification. */
+type UpdateBeliefCriticalityInput = {
+    id?: string;
+    nodeId?: string;
+    beliefId?: string;
+    criticality: "blocking" | "important" | "supporting" | "essential" | "nice_to_have";
+};
+/** Input for bulk-updating multiple beliefs' criticality. */
+type BatchUpdateBeliefCriticalityInput = {
+    updates: Array<{
+        beliefId: string;
+        criticality: "blocking" | "important" | "supporting" | "essential" | "nice_to_have";
+        ifFalseImpact?: string;
+        triagePriority?: number;
+        reasoning?: string;
+        dependentBeliefIds?: string[];
+        blockedByBeliefIds?: string[];
+    }>;
+};
+/** Input for moving beliefs into a different topic scope. */
+type ReassignBeliefsTopicInput = {
+    beliefNodeIds?: string[];
+    beliefIds?: string[];
+    targetTopicId: string;
+    reason?: string;
+};
+/**
+ * Create the beliefs client for belief lifecycle operations.
+ *
+ * @param config - Gateway transport configuration.
+ * @returns An object with `createBelief`, `refineBelief`, `modulateConfidence`, and `forkBelief` methods.
+ */
+declare function createBeliefsClient(config?: BeliefsClientConfig): {
+    /**
+     * Create a belief within a topic scope.
+     */
+    createBelief(input: CreateBeliefInput, idempotencyKey?: string): Promise<PlatformGatewaySuccess<PlatformBeliefRecord>>;
+    /**
+     * Refine a draft belief in place.
+     */
+    refineBelief(beliefId: string, input: RefineBeliefInput, idempotencyKey?: string): Promise<PlatformGatewaySuccess<PlatformBeliefRecord>>;
+    /**
+     * Record a confidence change for an existing belief.
+     */
+    modulateConfidence: {
+        (beliefId: string, input: ModulateConfidenceOpinionInput, idempotencyKey?: string): Promise<PlatformGatewaySuccess<ModulateConfidenceResponse>>;
+        (beliefId: string, input: ModulateConfidenceScalarInput, idempotencyKey?: string): Promise<PlatformGatewaySuccess<ModulateConfidenceResponse>>;
+    };
+    /**
+     * Returns the belief's confidence trajectory as a chronological array.
+     *
+     * Canonical UI trend shape (what every trend component consumes):
+     *   { t: number, b: number, d: number, u: number, a: number, P: number, trigger: string, triggeringRef?: { kind: "evidence" | "worktree"; id: string } }[]
+     *
+     * Where:
+     *   t = assessedAt (epoch ms)
+     *   b, d, u, a = Opinion 4-tuple components
+     *   P = projected probability = b + a*u  (precomputed for UI convenience)
+     *   trigger = cause of the score change
+     *   triggeringRef = optional pointer to the evidence or worktree that drove the change
+     */
+    getOpinionHistory(beliefId: string): Promise<OpinionHistoryEntry[]>;
+    /** @deprecated Use getOpinionHistory(). */
+    getConfidenceHistory(beliefId: string): Promise<OpinionHistoryEntry[]>;
+    /**
+     * Fork a scored belief into a new formulation.
+     */
+    forkBelief(beliefId: string, input: ForkBeliefInput, idempotencyKey?: string): Promise<PlatformGatewaySuccess<ForkBeliefResponse>>;
+    /**
+     * Update a belief's lifecycle status.
+     */
+    updateBeliefStatus(input: UpdateBeliefStatusInput, idempotencyKey?: string): Promise<PlatformGatewaySuccess<Record<string, unknown>>>;
+    /**
+     * Update a belief's rationale without changing its text.
+     */
+    updateBeliefRationale(input: UpdateBeliefRationaleInput, idempotencyKey?: string): Promise<PlatformGatewaySuccess<Record<string, unknown>>>;
+    /**
+     * Create a typed relationship between two beliefs.
+     */
+    linkBeliefs(input: LinkBeliefsInput, idempotencyKey?: string): Promise<PlatformGatewaySuccess<Record<string, unknown>>>;
+    /**
+     * Remove an evidence attachment from a belief.
+     */
+    unlinkBeliefEvidence(input: UnlinkBeliefEvidenceInput, idempotencyKey?: string): Promise<PlatformGatewaySuccess<Record<string, unknown>>>;
+    /**
+     * Update a belief's criticality metadata.
+     */
+    updateBeliefCriticality(input: UpdateBeliefCriticalityInput, idempotencyKey?: string): Promise<PlatformGatewaySuccess<Record<string, unknown>>>;
+    /**
+     * Update multiple beliefs' criticality in one mutation.
+     */
+    batchUpdateBeliefCriticality(input: BatchUpdateBeliefCriticalityInput, idempotencyKey?: string): Promise<PlatformGatewaySuccess<Record<string, unknown>>>;
+    /**
+     * Reassign beliefs to a different topic scope.
+     */
+    reassignBeliefsTopic(input: ReassignBeliefsTopicInput, idempotencyKey?: string): Promise<PlatformGatewaySuccess<Record<string, unknown>>>;
+};
+
+export { type BatchUpdateBeliefCriticalityInput, type BeliefsClientConfig, type CreateBeliefInput, type ForkBeliefInput, ForkBeliefResponse, type LinkBeliefsInput, type ModulateConfidenceInput, type ModulateConfidenceOpinionInput, ModulateConfidenceResponse, type ModulateConfidenceScalarInput, type OpinionHistoryEntry, PlatformGatewaySuccess, type ReassignBeliefsTopicInput, type RefineBeliefInput, type UnlinkBeliefEvidenceInput, type UpdateBeliefCriticalityInput, type UpdateBeliefRationaleInput, type UpdateBeliefStatusInput, createBeliefsClient, mapOpinionHistoryEntriesFromGatewayData };