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

package/dist/lib/platform/sdk/beliefsClient.d.ts

@@ -0,0 +1,157 @@
+import { type GatewayClientConfig, LucernApiError } from "./coreClient";
+import type { ForkBeliefResponse, JsonObject, ModulateConfidenceResponse } from "./types";
+export { LucernApiError };
+export type { PlatformGatewaySuccess } from "./coreClient";
+export type { CreateBeliefResponse, ForkBeliefResponse, ModulateConfidenceResponse, } from "./types";
+/** Configuration for the beliefs client. Inherits gateway transport settings. */
+export type BeliefsClientConfig = GatewayClientConfig;
+/**
+ * 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 unscored drafts and can be scored via confidence modulation.
+ */
+export 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;
+    tags?: string[];
+    metadata?: JsonObject;
+    verificationStatus?: "unverified" | "verified" | "rejected";
+};
+/**
+ * Input for recording a confidence change on a belief.
+ * Confidence modulation is append-only — each call adds a new credence history entry.
+ */
+export type ModulateConfidenceInput = {
+    confidence: number;
+    trigger?: "evidence_added" | "evidence_removed" | "contradiction_detected" | "contradiction_resolved" | "manual" | "decay" | "agent_assessment" | "merge_outcome" | "worktree_outcome" | "worktree_completed";
+    rationale: string;
+    certainty?: number;
+};
+/**
+ * Input for forking a scored belief into a new formulation.
+ * Scored beliefs are immutable — fork to evolve understanding.
+ */
+export type ForkBeliefInput = {
+    newFormulation: string;
+    forkReason?: "refinement" | "contradiction_response" | "scope_change" | "confidence_collapse" | "manual";
+    rationale?: string;
+};
+/** Input for changing a belief's lifecycle status. */
+export 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. */
+export type UpdateBeliefRationaleInput = {
+    id?: string;
+    nodeId?: string;
+    beliefId?: string;
+    rationale?: string;
+};
+/** Input for creating a belief-to-belief reasoning edge. */
+export type LinkBeliefsInput = {
+    fromNodeId: string;
+    toNodeId: string;
+    edgeType: string;
+    weight?: number;
+    context?: string;
+};
+/** Input for unlinking a belief from an attached evidence item. */
+export type UnlinkBeliefEvidenceInput = {
+    beliefNodeId?: string;
+    beliefId?: string;
+    nodeId?: string;
+    insightId?: string;
+    evidenceId?: string;
+};
+/** Input for updating a belief's criticality classification. */
+export type UpdateBeliefCriticalityInput = {
+    id?: string;
+    nodeId?: string;
+    beliefId?: string;
+    criticality: "blocking" | "important" | "supporting" | "essential" | "nice_to_have";
+};
+/** Input for bulk-updating multiple beliefs' criticality. */
+export 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. */
+export 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`, `modulateConfidence`, and `forkBelief` methods.
+ */
+export declare function createBeliefsClient(config?: BeliefsClientConfig): {
+    /**
+     * Create a belief within a topic scope.
+     */
+    createBelief(input: CreateBeliefInput, idempotencyKey?: string): Promise<import("./coreClient").PlatformGatewaySuccess<import("./types").PlatformBeliefRecord>>;
+    /**
+     * Record a confidence change for an existing belief.
+     */
+    modulateConfidence(beliefId: string, input: ModulateConfidenceInput, idempotencyKey?: string): Promise<import("./coreClient").PlatformGatewaySuccess<ModulateConfidenceResponse>>;
+    /**
+     * Fork a scored belief into a new formulation.
+     */
+    forkBelief(beliefId: string, input: ForkBeliefInput, idempotencyKey?: string): Promise<import("./coreClient").PlatformGatewaySuccess<ForkBeliefResponse>>;
+    /**
+     * Update a belief's lifecycle status.
+     */
+    updateBeliefStatus(input: UpdateBeliefStatusInput, idempotencyKey?: string): Promise<import("./coreClient").PlatformGatewaySuccess<Record<string, unknown>>>;
+    /**
+     * Update a belief's rationale without changing its text.
+     */
+    updateBeliefRationale(input: UpdateBeliefRationaleInput, idempotencyKey?: string): Promise<import("./coreClient").PlatformGatewaySuccess<Record<string, unknown>>>;
+    /**
+     * Create a typed relationship between two beliefs.
+     */
+    linkBeliefs(input: LinkBeliefsInput, idempotencyKey?: string): Promise<import("./coreClient").PlatformGatewaySuccess<Record<string, unknown>>>;
+    /**
+     * Remove an evidence attachment from a belief.
+     */
+    unlinkBeliefEvidence(input: UnlinkBeliefEvidenceInput, idempotencyKey?: string): Promise<import("./coreClient").PlatformGatewaySuccess<Record<string, unknown>>>;
+    /**
+     * Update a belief's criticality metadata.
+     */
+    updateBeliefCriticality(input: UpdateBeliefCriticalityInput, idempotencyKey?: string): Promise<import("./coreClient").PlatformGatewaySuccess<Record<string, unknown>>>;
+    /**
+     * Update multiple beliefs' criticality in one mutation.
+     */
+    batchUpdateBeliefCriticality(input: BatchUpdateBeliefCriticalityInput, idempotencyKey?: string): Promise<import("./coreClient").PlatformGatewaySuccess<Record<string, unknown>>>;
+    /**
+     * Reassign beliefs to a different topic scope.
+     */
+    reassignBeliefsTopic(input: ReassignBeliefsTopicInput, idempotencyKey?: string): Promise<import("./coreClient").PlatformGatewaySuccess<Record<string, unknown>>>;
+};

package/dist/lib/platform/sdk/beliefsClient.js

@@ -0,0 +1,124 @@
+import { createGatewayRequestClient, LucernApiError, randomIdempotencyKey, } from "./coreClient.js";
+import { normalizeNodeWriteInput } from "./sdkSurface.js";
+export { LucernApiError };
+/**
+ * Create the beliefs client for belief lifecycle operations.
+ *
+ * @param config - Gateway transport configuration.
+ * @returns An object with `createBelief`, `modulateConfidence`, and `forkBelief` methods.
+ */
+export function createBeliefsClient(config = {}) {
+    const gateway = createGatewayRequestClient(config);
+    return {
+        /**
+         * Create a belief within a topic scope.
+         */
+        async createBelief(input, idempotencyKey) {
+            return gateway.request({
+                path: "/api/platform/v1/beliefs",
+                method: "POST",
+                body: normalizeNodeWriteInput(input),
+                idempotencyKey: idempotencyKey ?? randomIdempotencyKey(),
+            });
+        },
+        /**
+         * Record a confidence change for an existing belief.
+         */
+        async modulateConfidence(beliefId, input, idempotencyKey) {
+            return gateway.request({
+                path: `/api/platform/v1/beliefs/${encodeURIComponent(beliefId)}/confidence`,
+                method: "POST",
+                body: input,
+                idempotencyKey: idempotencyKey ?? randomIdempotencyKey(),
+            });
+        },
+        /**
+         * Fork a scored belief into a new formulation.
+         */
+        async forkBelief(beliefId, input, idempotencyKey) {
+            return gateway.request({
+                path: `/api/platform/v1/beliefs/${encodeURIComponent(beliefId)}/fork`,
+                method: "POST",
+                body: input,
+                idempotencyKey: idempotencyKey ?? randomIdempotencyKey(),
+            });
+        },
+        /**
+         * Update a belief's lifecycle status.
+         */
+        async updateBeliefStatus(input, idempotencyKey) {
+            return gateway.request({
+                path: "/api/platform/v1/beliefs/update-status",
+                method: "POST",
+                body: input,
+                idempotencyKey: idempotencyKey ?? randomIdempotencyKey(),
+            });
+        },
+        /**
+         * Update a belief's rationale without changing its text.
+         */
+        async updateBeliefRationale(input, idempotencyKey) {
+            return gateway.request({
+                path: "/api/platform/v1/beliefs/update-rationale",
+                method: "POST",
+                body: input,
+                idempotencyKey: idempotencyKey ?? randomIdempotencyKey(),
+            });
+        },
+        /**
+         * Create a typed relationship between two beliefs.
+         */
+        async linkBeliefs(input, idempotencyKey) {
+            return gateway.request({
+                path: "/api/platform/v1/beliefs/link",
+                method: "POST",
+                body: input,
+                idempotencyKey: idempotencyKey ?? randomIdempotencyKey(),
+            });
+        },
+        /**
+         * Remove an evidence attachment from a belief.
+         */
+        async unlinkBeliefEvidence(input, idempotencyKey) {
+            return gateway.request({
+                path: "/api/platform/v1/beliefs/unlink-evidence",
+                method: "POST",
+                body: input,
+                idempotencyKey: idempotencyKey ?? randomIdempotencyKey(),
+            });
+        },
+        /**
+         * Update a belief's criticality metadata.
+         */
+        async updateBeliefCriticality(input, idempotencyKey) {
+            return gateway.request({
+                path: "/api/platform/v1/beliefs/update-criticality",
+                method: "POST",
+                body: input,
+                idempotencyKey: idempotencyKey ?? randomIdempotencyKey(),
+            });
+        },
+        /**
+         * Update multiple beliefs' criticality in one mutation.
+         */
+        async batchUpdateBeliefCriticality(input, idempotencyKey) {
+            return gateway.request({
+                path: "/api/platform/v1/beliefs/batch-update-criticality",
+                method: "POST",
+                body: input,
+                idempotencyKey: idempotencyKey ?? randomIdempotencyKey(),
+            });
+        },
+        /**
+         * Reassign beliefs to a different topic scope.
+         */
+        async reassignBeliefsTopic(input, idempotencyKey) {
+            return gateway.request({
+                path: "/api/platform/v1/beliefs/reassign-topic",
+                method: "POST",
+                body: input,
+                idempotencyKey: idempotencyKey ?? randomIdempotencyKey(),
+            });
+        },
+    };
+}