@lucern/sdk 0.3.0-alpha.0 → 0.3.0-alpha.10

package/dist/beliefsClient.d.ts

@@ -6,6 +6,8 @@ import { Opinion } from './opinion.js';
 import './contracts/workflow-runtime.contract.js';
 import './contracts/lens-workflow.contract.js';
 import './contracts/lens-filter.contract.js';
+import './authContext.js';
+import './contracts/auth-session.contract.js';
 
 /** Configuration for the beliefs client. Inherits gateway transport settings. */
 type BeliefsClientConfig = GatewayClientConfig;
@@ -18,7 +20,7 @@ type OpinionHistoryEntry = {
     P: number;
     trigger: string;
     triggeringRef?: {
-        kind: "evidence" | "worktree";
+        kind: "evidence" | "question" | "answer" | "contradiction" | "worktree";
         id: string;
     };
     rationale?: string;
@@ -32,8 +34,8 @@ declare function mapOpinionHistoryEntriesFromGatewayData(payload: GatewayRecord)
  *
  * 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.
+ * Beliefs start as drafts with a vacuous prior `(0, 0, 1, a)`. When omitted,
+ * `baseRate` defaults to the canonical neutral prior `0.5`.
  */
 type CreateBeliefInput = {
     topicId?: string;
@@ -50,7 +52,7 @@ type CreateBeliefInput = {
     title?: string;
     subtype?: string;
     confidence?: number;
-    baseRate: number;
+    baseRate?: number;
     tags?: string[];
     metadata?: JsonObject;
     verificationStatus?: "unverified" | "verified" | "rejected";
@@ -69,10 +71,15 @@ type RefineBeliefInput = {
     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 BeliefConfidenceTrigger = "evidence_added" | "evidence_removed" | "contradiction_detected" | "contradiction_resolved" | "agent_assessment" | "worktree_outcome" | "worktree_completed" | "fusion" | "discount" | "deduction";
 type ModulateConfidenceInputBase = {
-    trigger?: BeliefConfidenceTrigger;
+    trigger: BeliefConfidenceTrigger;
     rationale: string;
+    triggeringEvidenceId?: string;
+    triggeringQuestionId?: string;
+    triggeringAnswerId?: string;
+    triggeringContradictionId?: string;
+    triggeringWorktreeId?: string;
     maxInlinePropagationTargets?: number;
 };
 /**
@@ -82,24 +89,7 @@ type ModulateConfidenceInputBase = {
 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;
+type ModulateConfidenceInput = ModulateConfidenceOpinionInput;
 /**
  * Input for forking a scored belief into a new formulation.
  * Scored beliefs are immutable — fork to evolve understanding.
@@ -184,10 +174,7 @@ declare function createBeliefsClient(config?: BeliefsClientConfig): {
     /**
      * 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>>;
-    };
+    modulateConfidence: (beliefId: string, input: ModulateConfidenceOpinionInput, idempotencyKey?: string) => Promise<PlatformGatewaySuccess<ModulateConfidenceResponse>>;
     /**
      * Returns the belief's confidence trajectory as a chronological array.
      *
@@ -201,9 +188,9 @@ declare function createBeliefsClient(config?: BeliefsClientConfig): {
      *   trigger = cause of the score change
      *   triggeringRef = optional pointer to the evidence or worktree that drove the change
      */
-    getOpinionHistory(beliefId: string): Promise<OpinionHistoryEntry[]>;
+    getOpinionHistory: (beliefId: string) => Promise<OpinionHistoryEntry[]>;
     /** @deprecated Use getOpinionHistory(). */
-    getConfidenceHistory(beliefId: string): Promise<OpinionHistoryEntry[]>;
+    getConfidenceHistory: (beliefId: string) => Promise<OpinionHistoryEntry[]>;
     /**
      * Fork a scored belief into a new formulation.
      */
@@ -238,4 +225,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, type ModulateConfidenceOpinionInput, ModulateConfidenceResponse, type ModulateConfidenceScalarInput, Opinion, type OpinionHistoryEntry, PlatformGatewaySuccess, type ReassignBeliefsTopicInput, type RefineBeliefInput, type UnlinkBeliefEvidenceInput, type UpdateBeliefCriticalityInput, type UpdateBeliefRationaleInput, type UpdateBeliefStatusInput, createBeliefsClient, mapOpinionHistoryEntriesFromGatewayData };
+export { type BatchUpdateBeliefCriticalityInput, type BeliefsClientConfig, type CreateBeliefInput, type ForkBeliefInput, ForkBeliefResponse, type LinkBeliefsInput, type ModulateConfidenceInput, type ModulateConfidenceOpinionInput, ModulateConfidenceResponse, Opinion, type OpinionHistoryEntry, PlatformGatewaySuccess, type ReassignBeliefsTopicInput, type RefineBeliefInput, type UnlinkBeliefEvidenceInput, type UpdateBeliefCriticalityInput, type UpdateBeliefRationaleInput, type UpdateBeliefStatusInput, createBeliefsClient, mapOpinionHistoryEntriesFromGatewayData };

package/dist/beliefsClient.js

@@ -1,3 +1,170 @@
+// src/authContext.ts
+var LucernSdkAuthContextError = class extends Error {
+  reason;
+  constructor(reason, message) {
+    super(message);
+    this.name = "LucernSdkAuthContextError";
+    this.reason = reason;
+  }
+};
+function cleanString(value) {
+  const normalized = value?.trim();
+  return normalized ? normalized : void 0;
+}
+function cleanStringList(values) {
+  if (!values) {
+    return [];
+  }
+  return values.map((value) => value.trim()).filter(
+    (value, index, list) => value.length > 0 && list.indexOf(value) === index
+  );
+}
+function requireString(value, reason, label) {
+  const normalized = cleanString(value);
+  if (!normalized) {
+    throw new LucernSdkAuthContextError(
+      reason,
+      `Canonical Lucern SDK auth context is missing ${label}.`
+    );
+  }
+  return normalized;
+}
+function requirePrincipalType(principalType) {
+  if (!principalType) {
+    throw new LucernSdkAuthContextError(
+      "principal_missing",
+      "Canonical Lucern SDK auth context is missing principalType."
+    );
+  }
+  return principalType;
+}
+function requireAuthMode(authMode) {
+  if (!authMode) {
+    throw new LucernSdkAuthContextError(
+      "principal_missing",
+      "Canonical Lucern SDK auth context is missing authMode."
+    );
+  }
+  return authMode;
+}
+function ensurePermitMatch(args) {
+  const actual = cleanString(args.actual);
+  if (actual && actual !== args.expected) {
+    throw new LucernSdkAuthContextError(
+      "policy_denied",
+      `Canonical Lucern SDK auth context has conflicting Permit ${args.field}.`
+    );
+  }
+}
+function normalizeCanonicalLucernAuthContext(input) {
+  if (!input) {
+    throw new LucernSdkAuthContextError(
+      "principal_missing",
+      "Canonical Lucern SDK auth context is required."
+    );
+  }
+  if (input.policyDecision === "deny") {
+    throw new LucernSdkAuthContextError(
+      "policy_denied",
+      "Canonical Lucern SDK auth context carries a denied policy decision."
+    );
+  }
+  const principalId = requireString(
+    input.principalId,
+    "principal_missing",
+    "principalId"
+  );
+  const tenantId = requireString(input.tenantId, "tenant_missing", "tenantId");
+  const workspaceId = requireString(
+    input.workspaceId,
+    "workspace_missing",
+    "workspaceId"
+  );
+  const roles = cleanStringList(input.roles);
+  const scopes = cleanStringList(input.scopes);
+  const principalType = requirePrincipalType(input.principalType);
+  const authMode = requireAuthMode(input.authMode);
+  const roleBasedInteractiveAuth = authMode === "interactive_user" && roles.length > 0;
+  if (roles.length === 0 || scopes.length === 0 && !roleBasedInteractiveAuth) {
+    throw new LucernSdkAuthContextError(
+      "membership_missing",
+      "Canonical Lucern SDK auth context requires non-empty roles and scopes."
+    );
+  }
+  const subject = cleanString(input.permit?.subject) ?? principalId;
+  const tenant = cleanString(input.permit?.tenant) ?? tenantId;
+  const workspace = cleanString(input.permit?.workspace) ?? workspaceId;
+  ensurePermitMatch({
+    field: "subject",
+    expected: principalId,
+    actual: subject
+  });
+  ensurePermitMatch({ field: "tenant", expected: tenantId, actual: tenant });
+  ensurePermitMatch({
+    field: "workspace",
+    expected: workspaceId,
+    actual: workspace
+  });
+  const context = input.permit?.context ? { ...input.permit.context } : void 0;
+  return {
+    clerkId: cleanString(input.clerkId),
+    principalId,
+    tenantId,
+    workspaceId,
+    principalType,
+    authMode,
+    roles,
+    scopes,
+    delegationChain: input.delegationChain ? [...input.delegationChain] : [],
+    policyTraceId: cleanString(input.policyTraceId),
+    correlationId: cleanString(input.correlationId),
+    membershipId: cleanString(input.membershipId),
+    permit: {
+      subject,
+      tenant,
+      workspace,
+      resource: cleanString(input.permit?.resource),
+      action: cleanString(input.permit?.action),
+      relation: cleanString(input.permit?.relation),
+      context
+    }
+  };
+}
+function createCanonicalAuthHeaders(authContext) {
+  const headers = {
+    "x-lucern-principal-id": authContext.principalId,
+    "x-lucern-principal-type": authContext.principalType,
+    "x-lucern-tenant": authContext.tenantId,
+    "x-lucern-tenant-id": authContext.tenantId,
+    "x-lucern-workspace": authContext.workspaceId,
+    "x-lucern-workspace-id": authContext.workspaceId,
+    "x-lucern-auth-mode": authContext.authMode,
+    "x-lucern-roles": authContext.roles.join(","),
+    "x-lucern-scopes": authContext.scopes.join(","),
+    "x-lucern-permit-context": JSON.stringify(authContext.permit)
+  };
+  if (authContext.clerkId) {
+    headers["x-lucern-clerk-id"] = authContext.clerkId;
+    headers["x-lucern-user-id"] = authContext.clerkId;
+  }
+  if (authContext.delegationChain.length > 0) {
+    headers["x-lucern-delegation-chain"] = JSON.stringify(
+      authContext.delegationChain
+    );
+  }
+  if (authContext.policyTraceId) {
+    headers["x-lucern-policy-trace-id"] = authContext.policyTraceId;
+  }
+  if (authContext.correlationId) {
+    headers["x-correlation-id"] = authContext.correlationId;
+    headers["x-lucern-correlation-id"] = authContext.correlationId;
+  }
+  if (authContext.membershipId) {
+    headers["x-lucern-membership-id"] = authContext.membershipId;
+  }
+  return headers;
+}
+
 // src/coreClient.ts
 var LucernApiError = class extends Error {
   code;
@@ -45,9 +212,7 @@ function generatePortableRequestId() {
     8
   ).join("")}-${hex.slice(8, 10).join("")}-${hex.slice(10).join("")}`;
 }
-function randomIdempotencyKey() {
-  return generatePortableRequestId();
-}
+var randomIdempotencyKey = generatePortableRequestId;
 function isRetryableStatus(status) {
   return status >= 500 || status === 408 || status === 429;
 }
@@ -112,8 +277,11 @@ function timeoutError(timeoutMs) {
   error.name = "AbortError";
   return error;
 }
+function isRecord(value) {
+  return value !== null && typeof value === "object" && !Array.isArray(value);
+}
 function readPolicySummaryFromDetails(details) {
-  if (!details || typeof details !== "object" || Array.isArray(details)) {
+  if (!isRecord(details)) {
     return null;
   }
   const directSummary = details.summary;
@@ -121,11 +289,11 @@ function readPolicySummaryFromDetails(details) {
     return directSummary.trim();
   }
   const policy = details.policy;
-  if (!policy || typeof policy !== "object" || Array.isArray(policy)) {
+  if (!isRecord(policy)) {
     return null;
   }
   const explanation = policy.explanation;
-  if (!explanation || typeof explanation !== "object" || Array.isArray(explanation)) {
+  if (!isRecord(explanation)) {
     return null;
   }
   const nestedSummary = explanation.summary;
@@ -134,16 +302,41 @@ function readPolicySummaryFromDetails(details) {
   }
   return null;
 }
+async function resolveConfiguredAuthContext(authContext) {
+  if (typeof authContext === "function") {
+    return await authContext();
+  }
+  return authContext;
+}
+function mergeHeaderRecord(base, addition) {
+  const headers = new Headers(base);
+  for (const [key, value] of Object.entries(addition)) {
+    const existing = headers.get(key);
+    if (existing !== null && existing !== value) {
+      throw new LucernSdkAuthContextError(
+        "policy_denied",
+        `Canonical Lucern SDK auth context conflicts with existing ${key} header.`
+      );
+    }
+    headers.set(key, value);
+  }
+  return Object.fromEntries(headers.entries());
+}
 function createGatewayRequestClient(config = {}) {
   const fetchImpl = config.fetchImpl ?? fetch;
   const baseUrl = config.baseUrl?.replace(/\/+$/, "") ?? "";
   const maxRetries = config.maxRetries ?? 2;
   const requestIdFactory = config.requestIdFactory ?? (() => generatePortableRequestId());
   async function resolveAuthHeaders() {
-    if (!config.getAuthHeaders) {
-      return {};
+    const base = config.getAuthHeaders ? await config.getAuthHeaders() : {};
+    const authContextInput = await resolveConfiguredAuthContext(
+      config.authContext
+    );
+    if (!authContextInput && !config.requireCanonicalAuthContext) {
+      return base;
     }
-    return await config.getAuthHeaders();
+    const authContext = normalizeCanonicalLucernAuthContext(authContextInput);
+    return mergeHeaderRecord(base, createCanonicalAuthHeaders(authContext));
   }
   async function fetchWithTimeout(url, init, timeoutMs) {
     const controller = new AbortController();
@@ -164,11 +357,11 @@ function createGatewayRequestClient(config = {}) {
     if (!text) {
       return null;
     }
-    try {
-      return JSON.parse(text);
-    } catch {
+    const parsed = tryParseGatewayEnvelopeJson(text);
+    if (!parsed.ok) {
       return null;
     }
+    return isRecord(parsed.value) ? parsed.value : null;
   }
   function resolveTimeoutMs(method, requestTimeoutMs) {
     if (typeof requestTimeoutMs === "number") {
@@ -180,16 +373,31 @@ function createGatewayRequestClient(config = {}) {
     }
     return config.timeoutMs ?? 15e3;
   }
+  function tryParseGatewayEnvelopeJson(text) {
+    const trimmed = text.trim();
+    if (!trimmed.startsWith("{") && !trimmed.startsWith("[")) {
+      return { ok: false, reason: "non-json" };
+    }
+    try {
+      return { ok: true, value: JSON.parse(trimmed) };
+    } catch (error) {
+      if (error instanceof SyntaxError) {
+        return { ok: false, reason: "invalid-json", error };
+      }
+      throw error;
+    }
+  }
   function buildApiError(args) {
     const failure = args.failure;
-    const legacyError = failure && typeof failure.error === "object" && failure.error !== null ? failure.error : failure?.legacyError;
+    const legacyError = failure && isRecord(failure.error) ? failure.error : failure?.legacyError;
     const correlationId = failure?.correlationId ?? args.response.headers.get("x-lucern-correlation-id")?.trim() ?? args.requestId;
     const policyTraceId = failure?.policyTraceId ?? args.response.headers.get("x-lucern-policy-trace-id")?.trim() ?? null;
     const details = failure?.details ?? legacyError?.details;
     const policySummary = readPolicySummaryFromDetails(details);
+    const failureMessage = typeof failure?.error === "string" ? failure.error : legacyError?.message;
     return new LucernApiError({
       code: failure?.code ?? legacyError?.code ?? fallbackErrorCode(args.response.status),
-      message: policySummary ?? (typeof failure?.error === "string" ? failure.error : legacyError?.message ?? (args.response.ok ? "Platform API returned an invalid success payload." : "Platform API request failed.")),
+      message: policySummary ?? failureMessage ?? (args.response.ok ? "Platform API returned an invalid success payload." : "Platform API request failed."),
       status: args.response.status,
       invariant: failure?.invariant,
       suggestion: failure?.suggestion,
@@ -314,44 +522,12 @@ 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) {
+function cleanString2(value) {
   return typeof value === "string" && value.trim().length > 0 ? value.trim() : void 0;
 }
 function normalizeVerificationStatus(value) {
-  const status = cleanString(value);
+  const status = cleanString2(value);
   if (!status) {
     return void 0;
   }
@@ -364,10 +540,10 @@ function normalizeVerificationStatus(value) {
   return status;
 }
 function resolveTopicId(value) {
-  return cleanString(value.topicId);
+  return cleanString2(value.topicId);
 }
 function resolveText(value) {
-  return cleanString(value.text) ?? cleanString(value.canonicalText);
+  return cleanString2(value.text) ?? cleanString2(value.canonicalText);
 }
 function normalizeNodeWriteInput(value) {
   const topicId = resolveTopicId(value);
@@ -401,7 +577,7 @@ function readString(value) {
 function readNumber(value) {
   return typeof value === "number" && Number.isFinite(value) ? value : void 0;
 }
-function clamp012(value) {
+function clamp01(value) {
   return Math.max(0, Math.min(1, value));
 }
 function normalizeOpinionTuple(record) {
@@ -410,20 +586,16 @@ function normalizeOpinionTuple(record) {
   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
-    };
+  if (rawBelief === void 0 || rawDisbelief === void 0 || rawUncertainty === void 0 || rawBaseRate === void 0) {
+    throw new Error(
+      "Gateway opinion history entries must include belief, disbelief, uncertainty, and baseRate."
+    );
   }
   return {
-    b: clamp012(rawBelief ?? 0),
-    d: clamp012(rawDisbelief ?? 0),
-    u: clamp012(rawUncertainty ?? 0),
-    a: clamp012(rawBaseRate ?? 0.5)
+    b: clamp01(rawBelief),
+    d: clamp01(rawDisbelief),
+    u: clamp01(rawUncertainty),
+    a: clamp01(rawBaseRate)
   };
 }
 function mapOpinionHistoryEntriesFromGatewayData(payload) {
@@ -431,28 +603,28 @@ function mapOpinionHistoryEntriesFromGatewayData(payload) {
   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 projected = readNumber(record.confidence) ?? clamp01(tuple.b + tuple.a * tuple.u);
     const triggeringEvidenceId = readString(record.triggeringEvidenceId);
+    const triggeringQuestionId = readString(record.triggeringQuestionId);
+    const triggeringAnswerId = readString(record.triggeringAnswerId);
+    const triggeringContradictionId = readString(
+      record.triggeringContradictionId
+    );
     const triggeringWorktreeId = readString(record.triggeringWorktreeId);
+    const triggeringRef = triggeringEvidenceId ? { kind: "evidence", id: triggeringEvidenceId } : triggeringQuestionId ? { kind: "question", id: triggeringQuestionId } : triggeringAnswerId ? { kind: "answer", id: triggeringAnswerId } : triggeringContradictionId ? { kind: "contradiction", id: triggeringContradictionId } : triggeringWorktreeId ? { kind: "worktree", id: triggeringWorktreeId } : void 0;
+    const trigger = readString(record.trigger);
+    if (!trigger) {
+      throw new Error("Gateway opinion history entries must include trigger.");
+    }
     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
-        }
-      } : {},
+      P: clamp01(projected),
+      trigger,
+      ...triggeringRef ? { triggeringRef } : {},
       ...readString(record.rationale) ? { rationale: readString(record.rationale) } : {},
       ...readString(record.userId) ? { userId: readString(record.userId) } : {},
       ...readString(record.slOperator) ? { slOperator: readString(record.slOperator) } : {}
@@ -460,11 +632,7 @@ function mapOpinionHistoryEntriesFromGatewayData(payload) {
   }).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
-  );
+  const opinion = input.opinion;
   return {
     belief: opinion.b,
     disbelief: opinion.d,
@@ -472,20 +640,23 @@ function normalizeModulateConfidenceInput(input) {
     baseRate: opinion.a,
     trigger: input.trigger,
     rationale: input.rationale,
+    triggeringEvidenceId: input.triggeringEvidenceId,
+    triggeringQuestionId: input.triggeringQuestionId,
+    triggeringAnswerId: input.triggeringAnswerId,
+    triggeringContradictionId: input.triggeringContradictionId,
+    triggeringWorktreeId: input.triggeringWorktreeId,
     maxInlinePropagationTargets: input.maxInlinePropagationTargets
   };
 }
 function createBeliefsClient(config = {}) {
   const gateway = createGatewayRequestClient(config);
-  function requireBaseRate(value) {
+  function normalizeBaseRate(value) {
     const baseRate = readNumber(value);
-    if (baseRate === void 0) {
-      throw new Error("baseRate is required for belief creation.");
-    }
-    if (baseRate < 0 || baseRate > 1) {
+    const normalized = baseRate ?? 0.5;
+    if (normalized < 0 || normalized > 1) {
       throw new Error("baseRate must be within [0, 1].");
     }
-    return baseRate;
+    return normalized;
   }
   const modulateConfidence = async (beliefId, input, idempotencyKey) => gateway.request({
     path: `/api/platform/v1/beliefs/${encodeURIComponent(beliefId)}/confidence`,
@@ -493,18 +664,18 @@ function createBeliefsClient(config = {}) {
     body: normalizeModulateConfidenceInput(input),
     idempotencyKey: idempotencyKey ?? randomIdempotencyKey()
   });
-  async function getOpinionHistory(beliefId) {
+  const getOpinionHistory = async (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);
+      const baseRate = normalizeBaseRate(input.baseRate);
       return gateway.request({
         path: "/api/platform/v1/beliefs",
         method: "POST",
@@ -543,13 +714,9 @@ function createBeliefsClient(config = {}) {
      *   trigger = cause of the score change
      *   triggeringRef = optional pointer to the evidence or worktree that drove the change
      */
-    async getOpinionHistory(beliefId) {
-      return getOpinionHistory(beliefId);
-    },
+    getOpinionHistory,
     /** @deprecated Use getOpinionHistory(). */
-    async getConfidenceHistory(beliefId) {
-      return getOpinionHistory(beliefId);
-    },
+    getConfidenceHistory: getOpinionHistory,
     /**
      * Fork a scored belief into a new formulation.
      */