@lucern/sdk 0.2.0-alpha.9 → 0.3.0-alpha.0

package/dist/beliefs/lifecycle.d.ts

@@ -0,0 +1,24 @@
+type BeliefLifecycleStatus = "assumption" | "hypothesis" | "belief" | "fact";
+declare function isBeliefLifecycleStatus(value: unknown): value is BeliefLifecycleStatus;
+declare function isResolvedByConfidence(confidence: unknown): boolean;
+declare function hasResolvedPredictionOutcome(predictionMeta: unknown): boolean;
+declare function shouldTreatBeliefAsFact(opts: {
+    confidence?: unknown;
+    predictionMeta?: unknown;
+    metadata?: Record<string, unknown>;
+}): boolean;
+declare function resolveBeliefLifecycleStatus(opts: {
+    beliefStatus?: unknown;
+    confidence?: unknown;
+    predictionMeta?: unknown;
+    metadata?: Record<string, unknown>;
+}): BeliefLifecycleStatus;
+declare function isPreValidationBeliefStatus(status: BeliefLifecycleStatus): boolean;
+declare function isPropagationEligibleBeliefStatus(status: BeliefLifecycleStatus): boolean;
+declare function promoteBeliefStatusAfterScoring(status: BeliefLifecycleStatus, opts?: {
+    confidence?: unknown;
+    predictionMeta?: unknown;
+    metadata?: Record<string, unknown>;
+}): BeliefLifecycleStatus;
+
+export { type BeliefLifecycleStatus, hasResolvedPredictionOutcome, isBeliefLifecycleStatus, isPreValidationBeliefStatus, isPropagationEligibleBeliefStatus, isResolvedByConfidence, promoteBeliefStatusAfterScoring, resolveBeliefLifecycleStatus, shouldTreatBeliefAsFact };

package/dist/beliefs/lifecycle.js

@@ -0,0 +1,98 @@
+// src/beliefs/lifecycle.ts
+var BELIEF_STATUS_VALUES = [
+  "assumption",
+  "hypothesis",
+  "belief",
+  "fact"
+];
+var RESOLVED_PREDICTION_OUTCOMES = [
+  "confirmed",
+  "disconfirmed",
+  "partial",
+  "expired"
+];
+function isBeliefLifecycleStatus(value) {
+  return typeof value === "string" && BELIEF_STATUS_VALUES.includes(value);
+}
+function normalizeBeliefConfidence(confidence) {
+  if (typeof confidence !== "number" || !Number.isFinite(confidence)) {
+    return null;
+  }
+  if (confidence >= 0 && confidence <= 1) {
+    return confidence;
+  }
+  if (confidence > 1 && confidence <= 100) {
+    return confidence / 100;
+  }
+  return null;
+}
+function isResolvedByConfidence(confidence) {
+  const normalized = normalizeBeliefConfidence(confidence);
+  if (normalized === null) {
+    return false;
+  }
+  return normalized <= 0 || normalized >= 1;
+}
+function hasResolvedPredictionOutcome(predictionMeta) {
+  if (!predictionMeta || typeof predictionMeta !== "object") {
+    return false;
+  }
+  const outcome = predictionMeta.outcome;
+  return typeof outcome === "string" && RESOLVED_PREDICTION_OUTCOMES.includes(outcome);
+}
+function getPredictionMetaFromMetadata(metadata) {
+  return metadata?.predictionMeta;
+}
+function shouldTreatBeliefAsFact(opts) {
+  if (isResolvedByConfidence(opts.confidence)) {
+    return true;
+  }
+  if (hasResolvedPredictionOutcome(opts.predictionMeta)) {
+    return true;
+  }
+  if (hasResolvedPredictionOutcome(getPredictionMetaFromMetadata(opts.metadata))) {
+    return true;
+  }
+  return false;
+}
+function resolveBeliefLifecycleStatus(opts) {
+  if (shouldTreatBeliefAsFact(opts)) {
+    return "fact";
+  }
+  const direct = opts.beliefStatus;
+  if (isBeliefLifecycleStatus(direct)) {
+    const normalized = normalizeBeliefConfidence(opts.confidence);
+    if (normalized !== null && isPreValidationBeliefStatus(direct)) {
+      return "belief";
+    }
+    return direct;
+  }
+  const metaStatus = opts.metadata?.beliefStatus;
+  if (isBeliefLifecycleStatus(metaStatus)) {
+    const normalized = normalizeBeliefConfidence(opts.confidence);
+    if (normalized !== null && isPreValidationBeliefStatus(metaStatus)) {
+      return "belief";
+    }
+    return metaStatus;
+  }
+  return "assumption";
+}
+function isPreValidationBeliefStatus(status) {
+  return status === "assumption" || status === "hypothesis";
+}
+function isPropagationEligibleBeliefStatus(status) {
+  return status === "belief" || status === "fact";
+}
+function promoteBeliefStatusAfterScoring(status, opts) {
+  if (shouldTreatBeliefAsFact({ ...opts })) {
+    return "fact";
+  }
+  if (isPreValidationBeliefStatus(status)) {
+    return "belief";
+  }
+  return status === "fact" ? "fact" : "belief";
+}
+
+export { hasResolvedPredictionOutcome, isBeliefLifecycleStatus, isPreValidationBeliefStatus, isPropagationEligibleBeliefStatus, isResolvedByConfidence, promoteBeliefStatusAfterScoring, resolveBeliefLifecycleStatus, shouldTreatBeliefAsFact };
+//# sourceMappingURL=lifecycle.js.map
+//# sourceMappingURL=lifecycle.js.map

package/dist/beliefs/lifecycle.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/beliefs/lifecycle.ts"],"names":[],"mappings":"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","file":"lifecycle.js","sourcesContent":["export type BeliefLifecycleStatus =\n  | \"assumption\"\n  | \"hypothesis\"\n  | \"belief\"\n  | \"fact\";\n\ntype PredictionOutcome =\n  | \"pending\"\n  | \"confirmed\"\n  | \"disconfirmed\"\n  | \"partial\"\n  | \"expired\";\n\nconst BELIEF_STATUS_VALUES: readonly BeliefLifecycleStatus[] = [\n  \"assumption\",\n  \"hypothesis\",\n  \"belief\",\n  \"fact\",\n];\n\nconst RESOLVED_PREDICTION_OUTCOMES: readonly PredictionOutcome[] = [\n  \"confirmed\",\n  \"disconfirmed\",\n  \"partial\",\n  \"expired\",\n];\n\nexport function isBeliefLifecycleStatus(\n  value: unknown\n): value is BeliefLifecycleStatus {\n  return (\n    typeof value === \"string\" &&\n    BELIEF_STATUS_VALUES.includes(value as BeliefLifecycleStatus)\n  );\n}\n\nfunction normalizeBeliefConfidence(confidence: unknown): number | null {\n  if (typeof confidence !== \"number\" || !Number.isFinite(confidence)) {\n    return null;\n  }\n  if (confidence >= 0 && confidence <= 1) {\n    return confidence;\n  }\n  if (confidence > 1 && confidence <= 100) {\n    return confidence / 100;\n  }\n  return null;\n}\n\nexport function isResolvedByConfidence(confidence: unknown): boolean {\n  const normalized = normalizeBeliefConfidence(confidence);\n  if (normalized === null) {\n    return false;\n  }\n  return normalized <= 0 || normalized >= 1;\n}\n\nexport function hasResolvedPredictionOutcome(predictionMeta: unknown): boolean {\n  if (!predictionMeta || typeof predictionMeta !== \"object\") {\n    return false;\n  }\n  const outcome = (predictionMeta as { outcome?: unknown }).outcome;\n  return (\n    typeof outcome === \"string\" &&\n    RESOLVED_PREDICTION_OUTCOMES.includes(outcome as PredictionOutcome)\n  );\n}\n\nfunction getPredictionMetaFromMetadata(\n  metadata: Record<string, unknown> | undefined\n): unknown {\n  return metadata?.predictionMeta;\n}\n\nexport function shouldTreatBeliefAsFact(opts: {\n  confidence?: unknown;\n  predictionMeta?: unknown;\n  metadata?: Record<string, unknown>;\n}): boolean {\n  if (isResolvedByConfidence(opts.confidence)) {\n    return true;\n  }\n  if (hasResolvedPredictionOutcome(opts.predictionMeta)) {\n    return true;\n  }\n  if (\n    hasResolvedPredictionOutcome(getPredictionMetaFromMetadata(opts.metadata))\n  ) {\n    return true;\n  }\n  return false;\n}\n\nexport function resolveBeliefLifecycleStatus(opts: {\n  beliefStatus?: unknown;\n  confidence?: unknown;\n  predictionMeta?: unknown;\n  metadata?: Record<string, unknown>;\n}): BeliefLifecycleStatus {\n  if (shouldTreatBeliefAsFact(opts)) {\n    return \"fact\";\n  }\n\n  const direct = opts.beliefStatus;\n  if (isBeliefLifecycleStatus(direct)) {\n    const normalized = normalizeBeliefConfidence(opts.confidence);\n    if (normalized !== null && isPreValidationBeliefStatus(direct)) {\n      return \"belief\";\n    }\n    return direct;\n  }\n\n  const metaStatus = opts.metadata?.beliefStatus;\n  if (isBeliefLifecycleStatus(metaStatus)) {\n    const normalized = normalizeBeliefConfidence(opts.confidence);\n    if (normalized !== null && isPreValidationBeliefStatus(metaStatus)) {\n      return \"belief\";\n    }\n    return metaStatus;\n  }\n\n  return \"assumption\";\n}\n\nexport function isPreValidationBeliefStatus(\n  status: BeliefLifecycleStatus\n): boolean {\n  return status === \"assumption\" || status === \"hypothesis\";\n}\n\nexport function isPropagationEligibleBeliefStatus(\n  status: BeliefLifecycleStatus\n): boolean {\n  return status === \"belief\" || status === \"fact\";\n}\n\nexport function promoteBeliefStatusAfterScoring(\n  status: BeliefLifecycleStatus,\n  opts?: {\n    confidence?: unknown;\n    predictionMeta?: unknown;\n    metadata?: Record<string, unknown>;\n  }\n): BeliefLifecycleStatus {\n  if (shouldTreatBeliefAsFact({ ...opts })) {\n    return \"fact\";\n  }\n  if (isPreValidationBeliefStatus(status)) {\n    return \"belief\";\n  }\n  return status === \"fact\" ? \"fact\" : \"belief\";\n}\n"]}

package/dist/beliefsClient.d.ts

@@ -1,19 +1,39 @@
-import { GatewayClientConfig, PlatformGatewaySuccess } from './coreClient.js';
-export { LucernApiError } from './coreClient.js';
 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 './opinion.js';
 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 unscored drafts and can be scored via confidence modulation.
+ * 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;
@@ -30,20 +50,56 @@ type CreateBeliefInput = {
     title?: string;
     subtype?: string;
     confidence?: number;
+    baseRate: 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.
+ * 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 ModulateConfidenceInput = {
-    confidence: number;
-    trigger?: "evidence_added" | "evidence_removed" | "contradiction_detected" | "contradiction_resolved" | "manual" | "decay" | "agent_assessment" | "merge_outcome" | "worktree_outcome" | "worktree_completed";
+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;
-    certainty?: number;
+    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.
@@ -114,17 +170,40 @@ type ReassignBeliefsTopicInput = {
  * Create the beliefs client for belief lifecycle operations.
  *
  * @param config - Gateway transport configuration.
- * @returns An object with `createBelief`, `modulateConfidence`, and `forkBelief` methods.
+ * @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: ModulateConfidenceInput, idempotencyKey?: string): Promise<PlatformGatewaySuccess<ModulateConfidenceResponse>>;
+    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.
      */
@@ -159,4 +238,4 @@ declare function createBeliefsClient(config?: BeliefsClientConfig): {
     reassignBeliefsTopic(input: ReassignBeliefsTopicInput, idempotencyKey?: string): Promise<PlatformGatewaySuccess<Record<string, unknown>>>;
 };
 
-export { type BatchUpdateBeliefCriticalityInput, type BeliefsClientConfig, type CreateBeliefInput, type ForkBeliefInput, ForkBeliefResponse, type LinkBeliefsInput, type ModulateConfidenceInput, ModulateConfidenceResponse, PlatformGatewaySuccess, type ReassignBeliefsTopicInput, type UnlinkBeliefEvidenceInput, type UpdateBeliefCriticalityInput, type UpdateBeliefRationaleInput, type UpdateBeliefStatusInput, createBeliefsClient };
+export { type BatchUpdateBeliefCriticalityInput, type BeliefsClientConfig, type CreateBeliefInput, type ForkBeliefInput, ForkBeliefResponse, type LinkBeliefsInput, type ModulateConfidenceInput, type ModulateConfidenceOpinionInput, ModulateConfidenceResponse, type ModulateConfidenceScalarInput, Opinion, type OpinionHistoryEntry, PlatformGatewaySuccess, type ReassignBeliefsTopicInput, type RefineBeliefInput, type UnlinkBeliefEvidenceInput, type UpdateBeliefCriticalityInput, type UpdateBeliefRationaleInput, type UpdateBeliefStatusInput, createBeliefsClient, mapOpinionHistoryEntriesFromGatewayData };

package/dist/beliefsClient.js

@@ -314,6 +314,38 @@ function createGatewayRequestClient(config = {}) {
   };
 }
 
+// src/opinion.ts
+function clamp01(value) {
+  if (!Number.isFinite(value)) {
+    return 0;
+  }
+  return Math.max(0, Math.min(1, value));
+}
+function vacuous(baseRate = 0.5) {
+  return { b: 0, d: 0, u: 1, a: clamp01(baseRate) };
+}
+function dogmatic(probability, baseRate = 0.5) {
+  const p = clamp01(probability);
+  return { b: p, d: 1 - p, u: 0, a: clamp01(baseRate) };
+}
+function opinionFromBaseRate(probability) {
+  return vacuous(clamp01(probability));
+}
+function opinionFromDogmatic(probability, baseRate = 0.5) {
+  return dogmatic(clamp01(probability), clamp01(baseRate));
+}
+function opinionFromProjected(probability, uncertainty, baseRate = 0.5) {
+  const p = clamp01(probability);
+  const u = clamp01(uncertainty);
+  const remainingMass = 1 - u;
+  return {
+    b: p * remainingMass,
+    d: (1 - p) * remainingMass,
+    u,
+    a: clamp01(baseRate)
+  };
+}
+
 // src/sdkSurface.ts
 function cleanString(value) {
   return typeof value === "string" && value.trim().length > 0 ? value.trim() : void 0;
@@ -356,31 +388,168 @@ function normalizeNodeWriteInput(value) {
 }
 
 // src/beliefsClient.ts
+function asRecord(value) {
+  return value && typeof value === "object" && !Array.isArray(value) ? value : {};
+}
+function readString(value) {
+  if (typeof value !== "string") {
+    return void 0;
+  }
+  const normalized = value.trim();
+  return normalized.length > 0 ? normalized : void 0;
+}
+function readNumber(value) {
+  return typeof value === "number" && Number.isFinite(value) ? value : void 0;
+}
+function clamp012(value) {
+  return Math.max(0, Math.min(1, value));
+}
+function normalizeOpinionTuple(record) {
+  const opinion = asRecord(record.opinion);
+  const rawBelief = readNumber(opinion.b) ?? readNumber(record.belief);
+  const rawDisbelief = readNumber(opinion.d) ?? readNumber(record.disbelief);
+  const rawUncertainty = readNumber(opinion.u) ?? readNumber(record.uncertainty);
+  const rawBaseRate = readNumber(opinion.a) ?? readNumber(record.baseRate);
+  if (rawBelief === void 0 && rawDisbelief === void 0 && rawUncertainty === void 0) {
+    const projected = clamp012(readNumber(record.confidence) ?? 0);
+    return {
+      b: projected,
+      d: 1 - projected,
+      u: 0,
+      a: 0.5
+    };
+  }
+  return {
+    b: clamp012(rawBelief ?? 0),
+    d: clamp012(rawDisbelief ?? 0),
+    u: clamp012(rawUncertainty ?? 0),
+    a: clamp012(rawBaseRate ?? 0.5)
+  };
+}
+function mapOpinionHistoryEntriesFromGatewayData(payload) {
+  const entries = Array.isArray(payload.entries) ? payload.entries : [];
+  return entries.map((value) => {
+    const record = asRecord(value);
+    const tuple = normalizeOpinionTuple(record);
+    const projected = readNumber(record.confidence) ?? clamp012(tuple.b + tuple.a * tuple.u);
+    const triggeringEvidenceId = readString(record.triggeringEvidenceId);
+    const triggeringWorktreeId = readString(record.triggeringWorktreeId);
+    return {
+      t: readNumber(record.timestamp) ?? readNumber(record.assessedAt) ?? 0,
+      b: tuple.b,
+      d: tuple.d,
+      u: tuple.u,
+      a: tuple.a,
+      P: clamp012(projected),
+      trigger: readString(record.trigger) ?? "manual",
+      ...triggeringEvidenceId ? {
+        triggeringRef: {
+          kind: "evidence",
+          id: triggeringEvidenceId
+        }
+      } : triggeringWorktreeId ? {
+        triggeringRef: {
+          kind: "worktree",
+          id: triggeringWorktreeId
+        }
+      } : {},
+      ...readString(record.rationale) ? { rationale: readString(record.rationale) } : {},
+      ...readString(record.userId) ? { userId: readString(record.userId) } : {},
+      ...readString(record.slOperator) ? { slOperator: readString(record.slOperator) } : {}
+    };
+  }).sort((left, right) => left.t - right.t);
+}
+function normalizeModulateConfidenceInput(input) {
+  const opinion = "opinion" in input ? input.opinion : input.interpretation === "base_rate" ? opinionFromBaseRate(input.confidence) : input.interpretation === "dogmatic" ? opinionFromDogmatic(input.confidence, input.baseRate) : opinionFromProjected(
+    input.confidence,
+    input.uncertainty,
+    input.baseRate
+  );
+  return {
+    belief: opinion.b,
+    disbelief: opinion.d,
+    uncertainty: opinion.u,
+    baseRate: opinion.a,
+    trigger: input.trigger,
+    rationale: input.rationale,
+    maxInlinePropagationTargets: input.maxInlinePropagationTargets
+  };
+}
 function createBeliefsClient(config = {}) {
   const gateway = createGatewayRequestClient(config);
+  function requireBaseRate(value) {
+    const baseRate = readNumber(value);
+    if (baseRate === void 0) {
+      throw new Error("baseRate is required for belief creation.");
+    }
+    if (baseRate < 0 || baseRate > 1) {
+      throw new Error("baseRate must be within [0, 1].");
+    }
+    return baseRate;
+  }
+  const modulateConfidence = async (beliefId, input, idempotencyKey) => gateway.request({
+    path: `/api/platform/v1/beliefs/${encodeURIComponent(beliefId)}/confidence`,
+    method: "POST",
+    body: normalizeModulateConfidenceInput(input),
+    idempotencyKey: idempotencyKey ?? randomIdempotencyKey()
+  });
+  async function getOpinionHistory(beliefId) {
+    const response = await gateway.request({
+      path: `/api/platform/v1/beliefs/${encodeURIComponent(beliefId)}/confidence-history`
+    });
+    return mapOpinionHistoryEntriesFromGatewayData(response.data);
+  }
   return {
     /**
      * Create a belief within a topic scope.
      */
     async createBelief(input, idempotencyKey) {
+      const baseRate = requireBaseRate(input.baseRate);
       return gateway.request({
         path: "/api/platform/v1/beliefs",
         method: "POST",
-        body: normalizeNodeWriteInput(input),
+        body: {
+          ...normalizeNodeWriteInput(input),
+          baseRate
+        },
         idempotencyKey: idempotencyKey ?? randomIdempotencyKey()
       });
     },
     /**
-     * Record a confidence change for an existing belief.
+     * Refine a draft belief in place.
      */
-    async modulateConfidence(beliefId, input, idempotencyKey) {
+    async refineBelief(beliefId, input, idempotencyKey) {
       return gateway.request({
-        path: `/api/platform/v1/beliefs/${encodeURIComponent(beliefId)}/confidence`,
-        method: "POST",
-        body: input,
+        path: `/api/platform/v1/beliefs/${encodeURIComponent(beliefId)}`,
+        method: "PATCH",
+        body: normalizeNodeWriteInput(input),
         idempotencyKey: idempotencyKey ?? randomIdempotencyKey()
       });
     },
+    /**
+     * Record a confidence change for an existing belief.
+     */
+    modulateConfidence,
+    /**
+     * 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
+     */
+    async getOpinionHistory(beliefId) {
+      return getOpinionHistory(beliefId);
+    },
+    /** @deprecated Use getOpinionHistory(). */
+    async getConfidenceHistory(beliefId) {
+      return getOpinionHistory(beliefId);
+    },
     /**
      * Fork a scored belief into a new formulation.
      */
@@ -472,6 +641,6 @@ function createBeliefsClient(config = {}) {
   };
 }
 
-export { LucernApiError, createBeliefsClient };
+export { LucernApiError, createBeliefsClient, mapOpinionHistoryEntriesFromGatewayData };
 //# sourceMappingURL=beliefsClient.js.map
 //# sourceMappingURL=beliefsClient.js.map