@lucern/mcp 0.2.0-alpha.6 → 0.2.0-alpha.8

package/dist/index.js

@@ -263,6 +263,38 @@ function scoreObservation(record, terms) {
   return score;
 }
 
+// ../sdk/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)
+  };
+}
+
 // ../sdk/src/coreClient.ts
 var LucernApiError = class extends Error {
   code;
@@ -1261,31 +1293,168 @@ function createAuditClient(config = {}) {
 }
 
 // ../sdk/src/beliefsClient.ts
+function asRecord2(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 = asRecord2(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 = asRecord2(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 requireBaseRate2(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 = requireBaseRate2(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.
      */
@@ -1376,6 +1545,57 @@ function createBeliefsClient(config = {}) {
     }
   };
 }
+
+// ../sdk/src/sourcesClient.ts
+function createSourcesClient(config = {}) {
+  const gateway = createGatewayRequestClient(config);
+  return {
+    async upsert(spec, idempotencyKey = randomIdempotencyKey()) {
+      return gateway.request({
+        path: "/api/platform/v1/sources/upsert",
+        method: "POST",
+        body: spec,
+        idempotencyKey
+      });
+    },
+    async get(sourceId) {
+      return gateway.request({
+        path: `/api/platform/v1/sources/${encodeURIComponent(sourceId)}`
+      });
+    }
+  };
+}
+
+// ../sdk/src/evidenceClient.ts
+function createEvidenceClient(config = {}) {
+  const gateway = createGatewayRequestClient(config);
+  return {
+    async classifyEvidence(beliefId, evidenceId, classificationConfig, idempotencyKey) {
+      return gateway.request({
+        path: "/api/platform/v1/evidence/classify",
+        method: "POST",
+        body: {
+          beliefId,
+          evidenceId,
+          config: classificationConfig
+        },
+        idempotencyKey: idempotencyKey ?? randomIdempotencyKey()
+      });
+    },
+    async classifyEvidenceBatch(beliefId, evidence, classificationConfig, idempotencyKey) {
+      return gateway.request({
+        path: "/api/platform/v1/evidence/classify-batch",
+        method: "POST",
+        body: {
+          beliefId,
+          evidence,
+          config: classificationConfig
+        },
+        idempotencyKey: idempotencyKey ?? randomIdempotencyKey()
+      });
+    }
+  };
+}
 var DEFAULT_CUSTOM_NAMESPACE = "custom";
 var RESERVED_NAMESPACES = /* @__PURE__ */ new Set(["lucern"]);
 var CustomToolRegistryError = class extends Error {
@@ -2165,14 +2385,14 @@ function createIdentityClient(config = {}) {
 }
 
 // ../sdk/src/topicsClient.ts
-function asRecord2(value) {
+function asRecord3(value) {
   return value && typeof value === "object" ? value : {};
 }
 function cleanString2(value) {
   return typeof value === "string" && value.trim().length > 0 ? value.trim() : void 0;
 }
 function normalizeTopicRecord(value) {
-  const record = asRecord2(value);
+  const record = asRecord3(value);
   const topicId = cleanString2(record.topicId) ?? cleanString2(record.id) ?? cleanString2(record._id);
   return withTopicAlias({
     ...record,
@@ -2197,7 +2417,7 @@ function createTopicsClient(config = {}) {
         })}`
       }).then(
         (response) => mapGatewayData(response, (data) => {
-          const record = asRecord2(data);
+          const record = asRecord3(data);
           const items = Array.isArray(record.topics) ? record.topics.map(normalizeTopicRecord) : [];
           return {
             ...createListResult(items, "topics"),
@@ -2214,7 +2434,7 @@ function createTopicsClient(config = {}) {
       }).then(
         (response) => mapGatewayData(
           response,
-          (data) => normalizeTopicRecord(asRecord2(data).topic ?? data)
+          (data) => normalizeTopicRecord(asRecord3(data).topic ?? data)
         )
       );
     },
@@ -2250,7 +2470,7 @@ function createTopicsClient(config = {}) {
         )}`
       }).then(
         (response) => mapGatewayData(response, (data) => {
-          const record = asRecord2(data);
+          const record = asRecord3(data);
           return {
             tree: Array.isArray(record.tree) ? record.tree.map(normalizeTopicTreeNode) : []
           };
@@ -2284,6 +2504,22 @@ function createTopicsClient(config = {}) {
 }
 
 // ../sdk/src/gatewayFacades.ts
+function normalizeBeliefConfidenceInput(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 serializeTypes(types) {
   return Array.isArray(types) && types.length > 0 ? types.join(",") : void 0;
 }
@@ -2335,7 +2571,7 @@ function createBeliefsFacade(config = {}) {
       return gateway.request({
         path: `/api/platform/v1/beliefs/${encodeURIComponent(id)}/confidence`,
         method: "POST",
-        body: input,
+        body: normalizeBeliefConfidenceInput(input),
         idempotencyKey
       });
     },
@@ -2413,6 +2649,11 @@ function createBeliefsFacade(config = {}) {
         path: `/api/platform/v1/beliefs/${encodeURIComponent(id)}/confidence-history`
       });
     },
+    async opinionHistory(id) {
+      return gateway.request({
+        path: `/api/platform/v1/beliefs/${encodeURIComponent(id)}/confidence-history`
+      });
+    },
     async createContract(id, input, idempotencyKey = randomIdempotencyKey()) {
       return gateway.request({
         path: `/api/platform/v1/beliefs/${encodeURIComponent(id)}/contracts`,
@@ -4892,13 +5133,24 @@ function requireText(args) {
   }
   return text;
 }
+function requireBaseRate(args) {
+  if (typeof args.baseRate !== "number" || !Number.isFinite(args.baseRate)) {
+    throw new Error("baseRate is required.");
+  }
+  if (args.baseRate < 0 || args.baseRate > 1) {
+    throw new Error("baseRate must be within [0, 1].");
+  }
+  return args.baseRate;
+}
 function exposeGatewayData(response) {
   return Object.assign({}, response, response.data);
 }
 function createLucernClient(config = {}) {
   const gatewayConfig = toGatewayConfig(config);
   const beliefsClient = createBeliefsClient(gatewayConfig);
+  const sourcesClient = createSourcesClient(gatewayConfig);
   const beliefsFacade = createBeliefsFacade(gatewayConfig);
+  const evidenceClient = createEvidenceClient(gatewayConfig);
   const graphClient = createGraphClient(gatewayConfig);
   const graphFacade = createGraphFacade(gatewayConfig);
   const decisionsClient = createDecisionsClient(gatewayConfig);
@@ -5139,6 +5391,10 @@ function createLucernClient(config = {}) {
   async function getConfidenceHistory(nodeId) {
     return beliefsFacade.confidenceHistory(nodeId).then(exposeGatewayData);
   }
+  async function getOpinionHistory(nodeId) {
+    const response = await beliefsFacade.opinionHistory(nodeId);
+    return mapOpinionHistoryEntriesFromGatewayData(response.data);
+  }
   async function getAuditTrail(nodeId, limit = 50) {
     const events = await auditClient.listEvents({ limit });
     const entries = asListItems(events.data, "events").filter((event) => matchesAuditNodeReference(event, nodeId)).slice(0, limit).map((event) => {
@@ -5324,6 +5580,7 @@ function createLucernClient(config = {}) {
           rationale: input.rationale,
           worktreeId: input.worktreeId,
           pillar: input.pillar,
+          baseRate: requireBaseRate(input),
           sourceBeliefIds: input.sourceBeliefIds,
           sourceType: input.sourceType,
           beliefType: input.beliefType,
@@ -5397,6 +5654,9 @@ function createLucernClient(config = {}) {
       confidenceHistory(nodeId) {
         return beliefsFacade.confidenceHistory(nodeId).then(exposeGatewayData);
       },
+      opinionHistory(nodeId) {
+        return getOpinionHistory(nodeId);
+      },
       createContract(nodeId, input) {
         return beliefsFacade.createContract(nodeId, input).then(exposeGatewayData);
       },
@@ -5528,6 +5788,12 @@ function createLucernClient(config = {}) {
           beliefId: args.beliefId
         }));
       },
+      classifyEvidence(beliefId, evidenceId, config2, idempotencyKey) {
+        return evidenceClient.classifyEvidence(beliefId, evidenceId, config2, idempotencyKey).then(exposeGatewayData);
+      },
+      classifyEvidenceBatch(beliefId, evidence, config2, idempotencyKey) {
+        return evidenceClient.classifyEvidenceBatch(beliefId, evidence, config2, idempotencyKey).then(exposeGatewayData);
+      },
       updateStatus(input, idempotencyKey) {
         return evidenceFacade.updateStatus(input, idempotencyKey).then(exposeGatewayData);
       },
@@ -5544,6 +5810,14 @@ function createLucernClient(config = {}) {
         return evidenceFacade.updateVerificationStatus(input, idempotencyKey).then(exposeGatewayData);
       }
     },
+    sources: {
+      upsert(input, idempotencyKey) {
+        return sourcesClient.upsert(input, idempotencyKey).then(exposeGatewayData);
+      },
+      get(sourceId) {
+        return sourcesClient.get(sourceId).then(exposeGatewayData);
+      }
+    },
     questions: {
       create(args) {
         return questionsFacade.create({
@@ -5669,6 +5943,7 @@ function createLucernClient(config = {}) {
       },
       queryLineage,
       getConfidenceHistory,
+      getOpinionHistory,
       getAuditTrail,
       traverse(args) {
         return graphFacade.traverse({
@@ -6371,6 +6646,8 @@ function createLucernClient(config = {}) {
     extensions: extensionNamespaces,
     raw: {
       beliefs: beliefsClient,
+      sources: sourcesClient,
+      evidence: evidenceClient,
       graph: graphClient,
       decisions: decisionsClient,
       workflow: workflowClient,
@@ -6569,13 +6846,17 @@ var LENS_PERSPECTIVE_TYPES = [
 // ../sdk/src/contracts/mcp-tools.contract.ts
 var CREATE_BELIEF = {
   name: "create_belief",
-  description: "Commit a new belief (knowledge unit) to the reasoning graph. Like `git commit` \u2014 creates an atomic, traceable knowledge object. The belief starts as unscored (draft). Score it with modulate_confidence to freeze the formulation.",
+  description: "Commit a new belief (knowledge unit) to the reasoning graph. Like `git commit` \u2014 creates an atomic, traceable knowledge object with a mandatory prior. Creation stores the vacuous opinion `(0, 0, 1, a)`; use modulate_confidence to record the first evidential update.",
   parameters: {
     canonicalText: {
       type: "string",
       description: "The belief statement \u2014 what the agent holds to be true"
     },
     topicId: { type: "string", description: "Topic scope for the belief" },
+    baseRate: {
+      type: "number",
+      description: "Required prior probability used to seed the vacuous opinion `(0, 0, 1, a)` at creation time."
+    },
     beliefType: {
       type: "string",
       description: "Belief type (e.g., hypothesis, belief, principle, invariant, tenet, forecast). Validated against schemaEnumConfig."
@@ -6585,7 +6866,7 @@ var CREATE_BELIEF = {
       description: "Optional extra metadata merged into the node (e.g., { codeAnchors: ['path/to/file.ts'] } for coding intelligence)"
     }
   },
-  required: ["canonicalText", "topicId"],
+  required: ["canonicalText", "topicId", "baseRate"],
   response: {
     description: "The created canonical belief record",
     fields: {
@@ -6648,17 +6929,43 @@ var REFINE_BELIEF = {
 };
 var MODULATE_CONFIDENCE = {
   name: "modulate_confidence",
-  description: "Record a confidence change for a belief. Like `git commit` to the credence log \u2014 an atomic, append-only write. Each modulation is a new entry in the history, not an overwrite. Scoring happens via merge; this tool records the individual data points. Triggers: evidence_added, contradiction_detected, merge_outcome, manual, decay.",
+  description: "Record a confidence change for a belief. Like `git commit` to the credence log \u2014 an atomic, append-only write. Each modulation is a new entry in the history, not an overwrite. Scoring happens via merge; this tool records the individual data points. Pass the full subjective-logic tuple (`belief`, `disbelief`, `uncertainty`, `baseRate`) directly. If a caller only has a scalar probability, use `@lucern/sdk` helpers `opinionFromBaseRate`, `opinionFromDogmatic`, or `opinionFromProjected` to name the intended interpretation before calling this tool. Triggers: evidence_added, evidence_removed, contradiction_detected, contradiction_resolved, agent_assessment, worktree_outcome, worktree_completed, fusion, discount, deduction, manual, decay.",
   parameters: {
     nodeId: { type: "string", description: "The belief to score" },
-    confidence: { type: "number", description: "Confidence level in [0, 1]" },
+    belief: {
+      type: "number",
+      description: "Subjective-logic belief mass `b` in [0, 1]"
+    },
+    disbelief: {
+      type: "number",
+      description: "Subjective-logic disbelief mass `d` in [0, 1]"
+    },
+    uncertainty: {
+      type: "number",
+      description: "Subjective-logic uncertainty mass `u` in [0, 1]"
+    },
+    baseRate: {
+      type: "number",
+      description: "Subjective-logic base rate `a` in [0, 1]. Required for tuple payloads."
+    },
+    confidence: {
+      type: "number",
+      description: "Deprecated scalar confidence value in [0, 1]. Scalar-only payloads are rejected as AMBIGUOUS_SCALAR."
+    },
     trigger: {
       type: "string",
       description: "What caused this confidence change",
       enum: [
         "evidence_added",
+        "evidence_removed",
         "contradiction_detected",
-        "merge_outcome",
+        "contradiction_resolved",
+        "agent_assessment",
+        "worktree_outcome",
+        "worktree_completed",
+        "fusion",
+        "discount",
+        "deduction",
         "manual",
         "decay"
       ]
@@ -6668,7 +6975,7 @@ var MODULATE_CONFIDENCE = {
       description: "Human-readable explanation of why confidence changed"
     }
   },
-  required: ["nodeId", "confidence", "trigger", "rationale"],
+  required: ["nodeId", "trigger", "rationale"],
   response: {
     description: "Confidence modulation result",
     fields: {
@@ -7310,7 +7617,7 @@ var RECORD_JUDGMENT = {
       status: "string \u2014 'issued'"
     }
   },
-  ownerModule: "decision-state",
+  ownerModule: "decisions",
   ontologyPrimitive: "judgment",
   tier: "showcase"
 };
@@ -8579,7 +8886,7 @@ var INGEST_OBSERVATION = {
       contextResourceUri: "string"
     }
   },
-  ownerModule: "agent-harness",
+  ownerModule: "agent-frameworks",
   ontologyPrimitive: "graph",
   tier: "workhorse"
 };
@@ -8609,7 +8916,7 @@ var GET_OBSERVATION_CONTEXT = {
       generatedAt: "number"
     }
   },
-  ownerModule: "agent-harness",
+  ownerModule: "agent-frameworks",
   ontologyPrimitive: "graph",
   tier: "workhorse"
 };
@@ -9527,6 +9834,7 @@ var MCP_TOOL_CONTRACTS = {
   deprecate_ontology_version: DEPRECATE_ONTOLOGY_VERSION,
   resolve_effective_ontology: RESOLVE_EFFECTIVE_ONTOLOGY
 };
+globalThis.process?.env;
 
 // ../sdk/src/mcpParitySurface.ts
 var SDK_MCP_PARITY_METHODS = [
@@ -9594,11 +9902,13 @@ SDK_MCP_PARITY_METHODS.map(
 var McpHandlerError = class extends Error {
   code;
   status;
-  constructor(message, code = "INVALID_REQUEST", status = 400) {
+  suggestion;
+  constructor(message, code = "INVALID_REQUEST", status = 400, suggestion) {
     super(message);
     this.name = "McpHandlerError";
     this.code = code;
     this.status = status;
+    this.suggestion = suggestion;
   }
 };
 
@@ -9615,7 +9925,7 @@ function isMissing(value) {
   }
   return false;
 }
-function readString(params, key, options = {}) {
+function readString2(params, key, options = {}) {
   const value = params[key];
   if (value === void 0 || value === null) {
     if (options.required) {
@@ -9632,7 +9942,7 @@ function readString(params, key, options = {}) {
   }
   return trimmed || void 0;
 }
-function readNumber(params, key, options = {}) {
+function readNumber2(params, key, options = {}) {
   const value = params[key];
   if (value === void 0 || value === null) {
     if (options.required) {
@@ -9701,7 +10011,8 @@ function toMcpError(error) {
           text: JSON.stringify({
             code: error.code,
             status: error.status,
-            message: error.message
+            message: error.message,
+            suggestion: error.suggestion ?? null
           })
         }
       ]
@@ -9770,6 +10081,45 @@ function contractToHandler(contract, executor) {
 }
 
 // src/handlers/beliefs.ts
+var AMBIGUOUS_SCALAR_SUGGESTION = "Use opinion tuple (b, d, u, a) or an @lucern/sdk opinionFromBaseRate/opinionFromDogmatic/opinionFromProjected helper.";
+function readOpinionTuple(params) {
+  const belief = readNumber2(params, "belief");
+  const disbelief = readNumber2(params, "disbelief");
+  const uncertainty = readNumber2(params, "uncertainty");
+  const baseRate = readNumber2(params, "baseRate");
+  const tupleValues = [belief, disbelief, uncertainty, baseRate];
+  const providedCount = tupleValues.filter(
+    (value) => value !== void 0
+  ).length;
+  if (providedCount === 0) {
+    if (readNumber2(params, "confidence") !== void 0) {
+      throw new McpHandlerError(
+        "Scalar confidence input is ambiguous without an explicit subjective-logic interpretation.",
+        "AMBIGUOUS_SCALAR",
+        400,
+        AMBIGUOUS_SCALAR_SUGGESTION
+      );
+    }
+    throw new McpHandlerError(
+      "Missing required opinion tuple: belief, disbelief, uncertainty, and baseRate are required.",
+      "INVALID_REQUEST",
+      400
+    );
+  }
+  if (providedCount !== tupleValues.length) {
+    throw new McpHandlerError(
+      "Incomplete opinion tuple: belief, disbelief, uncertainty, and baseRate must all be provided together.",
+      "INVALID_REQUEST",
+      400
+    );
+  }
+  return {
+    b: belief,
+    d: disbelief,
+    u: uncertainty,
+    a: baseRate
+  };
+}
 function createBeliefHandlers(context) {
   const beliefs = createBeliefsClient(context.sdkConfig);
   const graph = createGraphClient(context.sdkConfig);
@@ -9778,13 +10128,14 @@ function createBeliefHandlers(context) {
       MCP_TOOL_CONTRACTS.create_belief,
       async (params) => {
         const result = await beliefs.createBelief({
-          canonicalText: readString(params, "canonicalText", {
+          canonicalText: readString2(params, "canonicalText", {
             required: true
           }),
           topicId: readTopicId(params, { required: true }),
-          layer: readString(params, "layer"),
-          domain: readString(params, "domain"),
-          subtype: readString(params, "nodeType")
+          layer: readString2(params, "layer"),
+          domain: readString2(params, "domain"),
+          subtype: readString2(params, "nodeType"),
+          baseRate: readNumber2(params, "baseRate", { required: true })
         });
         return {
           nodeId: result.data.nodeId,
@@ -9796,51 +10147,49 @@ function createBeliefHandlers(context) {
     refine_belief: contractToHandler(
       MCP_TOOL_CONTRACTS.refine_belief,
       async (params) => {
-        const nodeId = readString(params, "nodeId", { required: true });
-        const canonicalText = readString(params, "canonicalText", {
+        const nodeId = readString2(params, "nodeId", { required: true });
+        const canonicalText = readString2(params, "canonicalText", {
           required: true
         });
-        const rationale = readString(params, "rationale");
-        const result = await graph.updateNode({
-          nodeId,
+        const rationale = readString2(params, "rationale");
+        const result = await beliefs.refineBelief(nodeId, {
           canonicalText,
-          metadata: rationale ? {
-            lastRefinementRationale: rationale
-          } : void 0
+          rationale
         });
         return {
           nodeId: result.data.nodeId ?? nodeId,
           canonicalText: result.data.canonicalText ?? canonicalText,
-          updatedAt: Date.now()
+          updatedAt: result.data.updatedAt ?? Date.now()
         };
       }
     ),
     modulate_confidence: contractToHandler(
       MCP_TOOL_CONTRACTS.modulate_confidence,
       async (params) => {
-        const nodeId = readString(params, "nodeId", { required: true });
+        const nodeId = readString2(params, "nodeId", { required: true });
+        const opinion = readOpinionTuple(params);
         const result = await beliefs.modulateConfidence(nodeId, {
-          confidence: readNumber(params, "confidence", { required: true }),
-          trigger: readString(params, "trigger", { required: true }),
-          rationale: readString(params, "rationale", { required: true })
+          opinion,
+          trigger: readString2(params, "trigger", { required: true }),
+          rationale: readString2(params, "rationale", { required: true })
         });
         return {
           nodeId,
-          newConfidence: result.data.newConfidence ?? result.data.confidence ?? readNumber(params, "confidence", { required: true }),
+          newConfidence: result.data.newConfidence ?? result.data.confidence ?? opinion.b + opinion.a * opinion.u,
           previousConfidence: result.data.previousConfidence ?? null,
-          trigger: readString(params, "trigger", { required: true })
+          trigger: readString2(params, "trigger", { required: true })
         };
       }
     ),
     fork_belief: contractToHandler(
       MCP_TOOL_CONTRACTS.fork_belief,
       async (params) => {
-        const nodeId = readString(params, "nodeId", { required: true });
-        const forkReason = readString(params, "forkReason", {
+        const nodeId = readString2(params, "nodeId", { required: true });
+        const forkReason = readString2(params, "forkReason", {
           required: true
         });
         const result = await beliefs.forkBelief(nodeId, {
-          newFormulation: readString(params, "newFormulation", {
+          newFormulation: readString2(params, "newFormulation", {
             required: true
           }),
           forkReason
@@ -9855,8 +10204,8 @@ function createBeliefHandlers(context) {
     archive_belief: contractToHandler(
       MCP_TOOL_CONTRACTS.archive_belief,
       async (params) => {
-        const nodeId = readString(params, "nodeId", { required: true });
-        const rationale = readString(params, "rationale");
+        const nodeId = readString2(params, "nodeId", { required: true });
+        const rationale = readString2(params, "rationale");
         const result = await graph.updateNode({
           nodeId,
           status: "archived",
@@ -9883,13 +10232,13 @@ function createContextHandlers(context) {
         const response = await compiler.compile(
           readTopicId(params, { required: true }),
           {
-            ...readString(params, "query") ? { query: readString(params, "query") } : {},
-            ...readNumber(params, "budget") !== void 0 ? { budget: readNumber(params, "budget") } : {},
-            ...readString(params, "ranking") ? {
-              ranking: readString(params, "ranking")
+            ...readString2(params, "query") ? { query: readString2(params, "query") } : {},
+            ...readNumber2(params, "budget") !== void 0 ? { budget: readNumber2(params, "budget") } : {},
+            ...readString2(params, "ranking") ? {
+              ranking: readString2(params, "ranking")
             } : {},
-            ...readNumber(params, "limit") !== void 0 ? { limit: readNumber(params, "limit") } : {},
-            ...readNumber(params, "maxDepth") !== void 0 ? { maxDepth: readNumber(params, "maxDepth") } : {},
+            ...readNumber2(params, "limit") !== void 0 ? { limit: readNumber2(params, "limit") } : {},
+            ...readNumber2(params, "maxDepth") !== void 0 ? { maxDepth: readNumber2(params, "maxDepth") } : {},
             ...readBoolean(params, "includeEntities") !== void 0 ? { includeEntities: readBoolean(params, "includeEntities") } : {}
           }
         );
@@ -9906,14 +10255,14 @@ function createContradictionHandlers(context) {
     flag_contradiction: contractToHandler(
       MCP_TOOL_CONTRACTS.flag_contradiction,
       async (params) => {
-        const beliefA = readString(params, "beliefA", { required: true });
-        const beliefB = readString(params, "beliefB", { required: true });
-        const description = readString(params, "description", {
+        const beliefA = readString2(params, "beliefA", { required: true });
+        const beliefB = readString2(params, "beliefB", { required: true });
+        const description = readString2(params, "description", {
           required: true
         });
         const topicId = readTopicId(params, { required: true });
-        const severity = readString(params, "severity") ?? "medium";
-        const defeatType = readString(params, "defeatType") ?? "rebuts";
+        const severity = readString2(params, "severity") ?? "medium";
+        const defeatType = readString2(params, "defeatType") ?? "rebuts";
         const contradiction = await lucern.contradictions.flag({
           beliefA,
           beliefB,
@@ -9940,12 +10289,12 @@ function createEdgeHandlers(context) {
     create_edge: contractToHandler(
       MCP_TOOL_CONTRACTS.create_edge,
       async (params) => {
-        const sourceId = readString(params, "sourceId", { required: true });
-        const targetId = readString(params, "targetId", { required: true });
-        const edgeType = readString(params, "edgeType", { required: true });
-        const confidence = readNumber(params, "confidence");
-        const weight = readNumber(params, "weight");
-        const contextText = readString(params, "context") ?? readString(params, "reasoning");
+        const sourceId = readString2(params, "sourceId", { required: true });
+        const targetId = readString2(params, "targetId", { required: true });
+        const edgeType = readString2(params, "edgeType", { required: true });
+        const confidence = readNumber2(params, "confidence");
+        const weight = readNumber2(params, "weight");
+        const contextText = readString2(params, "context") ?? readString2(params, "reasoning");
         const edge = await lucern.edges.create({
           sourceId,
           targetId,
@@ -9978,15 +10327,15 @@ function createEvidenceHandlers(context) {
       async (params) => {
         const response = await lucern.evidence.create({
           topicId: readTopicId(params, { required: true }),
-          text: readString(params, "text", { required: true }),
-          source: readString(params, "source"),
-          targetId: readString(params, "targetId"),
-          weight: readNumber(params, "weight"),
+          text: readString2(params, "text", { required: true }),
+          source: readString2(params, "source"),
+          targetId: readString2(params, "targetId"),
+          weight: readNumber2(params, "weight"),
           metadata: readMetadata(params),
-          title: readString(params, "title"),
-          content: readString(params, "content"),
-          contentType: readString(params, "contentType"),
-          kind: readString(params, "kind")
+          title: readString2(params, "title"),
+          content: readString2(params, "content"),
+          contentType: readString2(params, "contentType"),
+          kind: readString2(params, "kind")
         });
         return response.data;
       }
@@ -9995,7 +10344,7 @@ function createEvidenceHandlers(context) {
       MCP_TOOL_CONTRACTS.get_evidence,
       async (params) => {
         const response = await lucern.evidence.get(
-          readString(params, "id", { required: true })
+          readString2(params, "id", { required: true })
         );
         return response.data;
       }
@@ -10005,9 +10354,9 @@ function createEvidenceHandlers(context) {
       async (params) => {
         const response = await lucern.evidence.list({
           topicId: readTopicId(params),
-          targetId: readString(params, "targetId"),
-          limit: readNumber(params, "limit"),
-          cursor: readString(params, "cursor")
+          targetId: readString2(params, "targetId"),
+          limit: readNumber2(params, "limit"),
+          cursor: readString2(params, "cursor")
         });
         return response.data;
       }
@@ -10016,10 +10365,10 @@ function createEvidenceHandlers(context) {
       MCP_TOOL_CONTRACTS.link_evidence,
       async (params) => {
         const response = await lucern.evidence.link({
-          evidenceId: readString(params, "evidenceId", { required: true }),
-          targetId: readString(params, "targetId", { required: true }),
-          weight: readNumber(params, "weight"),
-          rationale: readString(params, "rationale")
+          evidenceId: readString2(params, "evidenceId", { required: true }),
+          targetId: readString2(params, "targetId", { required: true }),
+          weight: readNumber2(params, "weight"),
+          rationale: readString2(params, "rationale")
         });
         return response.data;
       }
@@ -10028,11 +10377,11 @@ function createEvidenceHandlers(context) {
       MCP_TOOL_CONTRACTS.search_evidence,
       async (params) => {
         const response = await lucern.evidence.search({
-          q: readString(params, "q") ?? readString(params, "query", { required: true }),
+          q: readString2(params, "q") ?? readString2(params, "query", { required: true }),
           topicId: readTopicId(params),
-          targetId: readString(params, "targetId"),
-          limit: readNumber(params, "limit"),
-          cursor: readString(params, "cursor")
+          targetId: readString2(params, "targetId"),
+          limit: readNumber2(params, "limit"),
+          cursor: readString2(params, "cursor")
         });
         return response.data;
       }
@@ -10041,17 +10390,17 @@ function createEvidenceHandlers(context) {
       MCP_TOOL_CONTRACTS.add_evidence,
       async (params) => {
         return lucern.evidence.add({
-          canonicalText: readString(params, "canonicalText", { required: true }),
+          canonicalText: readString2(params, "canonicalText", { required: true }),
           topicId: readTopicId(params, { required: true }),
-          sourceUrl: readString(params, "sourceUrl"),
+          sourceUrl: readString2(params, "sourceUrl"),
           supports: {
-            nodeId: readString(params, "targetNodeId", { required: true }),
-            weight: readNumber(params, "weight") ?? 1,
-            reasoning: readString(params, "reasoning")
+            nodeId: readString2(params, "targetNodeId", { required: true }),
+            weight: readNumber2(params, "weight") ?? 1,
+            reasoning: readString2(params, "reasoning")
           },
-          title: readString(params, "title"),
-          content: readString(params, "content"),
-          contentType: readString(params, "contentType"),
+          title: readString2(params, "title"),
+          content: readString2(params, "content"),
+          contentType: readString2(params, "contentType"),
           metadata: readMetadata(params)
         });
       }
@@ -10060,10 +10409,10 @@ function createEvidenceHandlers(context) {
       MCP_TOOL_CONTRACTS.link_evidence_to_belief,
       async (params) => {
         return lucern.evidence.linkToBelief({
-          evidenceId: readString(params, "evidenceId", { required: true }),
-          beliefId: readString(params, "beliefId", { required: true }),
-          weight: readNumber(params, "weight", { required: true }),
-          rationale: readString(params, "rationale")
+          evidenceId: readString2(params, "evidenceId", { required: true }),
+          beliefId: readString2(params, "beliefId", { required: true }),
+          weight: readNumber2(params, "weight", { required: true }),
+          rationale: readString2(params, "rationale")
         });
       }
     )
@@ -10178,8 +10527,8 @@ function createGraphHandlers(context) {
     query_lineage: contractToHandler(
       MCP_TOOL_CONTRACTS.query_lineage,
       async (params) => {
-        const nodeId = readString(params, "nodeId", { required: true });
-        const depth = readNumber(params, "depth") ?? 5;
+        const nodeId = readString2(params, "nodeId", { required: true });
+        const depth = readNumber2(params, "depth") ?? 5;
         const [parentEdgesResponse, childEdgesResponse] = await Promise.all([
           graph.queryEdges({
             toNodeId: nodeId,
@@ -10216,7 +10565,7 @@ function createGraphHandlers(context) {
     get_confidence_history: contractToHandler(
       MCP_TOOL_CONTRACTS.get_confidence_history,
       async (params) => {
-        const nodeId = readString(params, "nodeId", { required: true });
+        const nodeId = readString2(params, "nodeId", { required: true });
         const entries = await getConfidenceEntries(nodeId);
         return { entries };
       }
@@ -10224,8 +10573,8 @@ function createGraphHandlers(context) {
     get_audit_trail: contractToHandler(
       MCP_TOOL_CONTRACTS.get_audit_trail,
       async (params) => {
-        const nodeId = readString(params, "nodeId", { required: true });
-        const limit = readNumber(params, "limit") ?? 50;
+        const nodeId = readString2(params, "nodeId", { required: true });
+        const limit = readNumber2(params, "limit") ?? 50;
         const events = await audit.listEvents({ limit: Math.max(1, limit) });
         const entries = asAuditArray(events.data).filter((entry) => matchesAuditNodeReference2(entry, nodeId)).slice(0, limit).map((entry) => ({
           action: entry.action ?? "unknown",
@@ -10242,9 +10591,9 @@ function createGraphHandlers(context) {
       MCP_TOOL_CONTRACTS.traverse_graph,
       async (params) => {
         const response = await graph.traverse({
-          startNode: readString(params, "startNode", { required: true }),
-          direction: readString(params, "direction"),
-          maxDepth: readNumber(params, "maxDepth"),
+          startNode: readString2(params, "startNode", { required: true }),
+          direction: readString2(params, "direction"),
+          maxDepth: readNumber2(params, "maxDepth"),
           topicId: readTopicId(params)
         });
         return response.data;
@@ -10255,9 +10604,9 @@ function createGraphHandlers(context) {
       async (params) => {
         const globalIds = readStringArray(params, "globalIds");
         const response = await graph.neighborhood({
-          globalId: readString(params, "globalId"),
+          globalId: readString2(params, "globalId"),
           globalIds: globalIds ? globalIds.join(",") : void 0,
-          maxDepth: readNumber(params, "maxDepth")
+          maxDepth: readNumber2(params, "maxDepth")
         });
         return response.data;
       }
@@ -10265,11 +10614,11 @@ function createGraphHandlers(context) {
     search_beliefs: contractToHandler(
       MCP_TOOL_CONTRACTS.search_beliefs,
       async (params) => {
-        const query = readString(params, "query", { required: true });
+        const query = readString2(params, "query", { required: true });
         const topicId = readTopicId(params);
-        const status = readString(params, "status");
-        const minConfidence = readNumber(params, "minConfidence");
-        const limit = readNumber(params, "limit") ?? 10;
+        const status = readString2(params, "status");
+        const minConfidence = readNumber2(params, "minConfidence");
+        const limit = readNumber2(params, "limit") ?? 10;
         if (!topicId) {
           return { results: [] };
         }
@@ -10295,8 +10644,8 @@ function createGraphHandlers(context) {
       MCP_TOOL_CONTRACTS.find_contradictions,
       async (params) => {
         const topicId = readTopicId(params);
-        const nodeId = readString(params, "nodeId");
-        const status = readString(params, "status");
+        const nodeId = readString2(params, "nodeId");
+        const status = readString2(params, "status");
         if (!topicId && !nodeId) {
           return { contradictions: [] };
         }
@@ -10328,8 +10677,8 @@ function createGraphHandlers(context) {
     bisect_confidence: contractToHandler(
       MCP_TOOL_CONTRACTS.bisect_confidence,
       async (params) => {
-        const nodeId = readString(params, "nodeId", { required: true });
-        const expectedDirection = readString(params, "expectedDirection", {
+        const nodeId = readString2(params, "nodeId", { required: true });
+        const expectedDirection = readString2(params, "expectedDirection", {
           required: true
         });
         const entries = await getConfidenceEntries(nodeId);
@@ -10352,7 +10701,7 @@ function createGraphHandlers(context) {
         if (!await isTopicReadable(topicId)) {
           return { topicId, beliefs: [] };
         }
-        const threshold = readNumber(params, "threshold") ?? 0.7;
+        const threshold = readNumber2(params, "threshold") ?? 0.7;
         const analytics = await graph.bias({
           topicId,
           threshold,
@@ -10426,7 +10775,7 @@ function createGraphHandlers(context) {
         }
         return lucern.graph.gaps({
           topicId,
-          minConfidence: readNumber(params, "minConfidence")
+          minConfidence: readNumber2(params, "minConfidence")
         });
       }
     ),
@@ -10437,9 +10786,9 @@ function createGraphHandlers(context) {
         if (!await isTopicReadable(topicId)) {
           return { beliefs: [] };
         }
-        const status = readString(params, "status");
-        const minConfidence = readNumber(params, "minConfidence");
-        const worktreeId = readString(params, "worktreeId");
+        const status = readString2(params, "status");
+        const minConfidence = readNumber2(params, "minConfidence");
+        const worktreeId = readString2(params, "worktreeId");
         const response = await graph.queryNodes({
           topicId,
           nodeType: "belief",
@@ -10486,10 +10835,10 @@ function createJudgmentHandlers(context) {
     record_judgment: contractToHandler(
       MCP_TOOL_CONTRACTS.record_judgment,
       async (params) => {
-        const title = readString(params, "title", { required: true });
-        const rationale = readString(params, "rationale", { required: true });
+        const title = readString2(params, "title", { required: true });
+        const rationale = readString2(params, "rationale", { required: true });
         const topicId = readTopicId(params, { required: true });
-        const confidence = readNumber(params, "confidence");
+        const confidence = readNumber2(params, "confidence");
         const beliefIds = readStringArray(params, "beliefIds");
         const result = await decisions.recordJudgment({
           title,
@@ -10536,14 +10885,14 @@ function createObservationHandlers(context) {
         const topicId = readTopicId(params, {
           required: true
         });
-        const observationType = readString(params, "observationType", {
+        const observationType = readString2(params, "observationType", {
           required: true
         });
-        const summary = readString(params, "summary", {
+        const summary = readString2(params, "summary", {
           required: true
         });
-        const source = readString(params, "source");
-        const confidence = readNumber(params, "confidence");
+        const source = readString2(params, "source");
+        const confidence = readNumber2(params, "confidence");
         const tags = readStringArray(params, "tags");
         const metadata = readObject(params, "metadata");
         const allowedTypes = [
@@ -10602,8 +10951,8 @@ function createObservationHandlers(context) {
         const topicId = readTopicId(params, {
           required: true
         });
-        const query = readString(params, "query");
-        const limit = readNumber(params, "limit");
+        const query = readString2(params, "query");
+        const limit = readNumber2(params, "limit");
         return observationStore.getContext({
           topicId,
           query,
@@ -10622,9 +10971,9 @@ function createPolicyHandlers(context) {
       MCP_TOOL_CONTRACTS.check_permission,
       async (params) => {
         const topicId = readTopicId(params, { required: true });
-        const permission = readString(params, "permission", { required: true }) ?? "read";
-        const principal = readString(params, "principal");
-        const beliefClusterId = readString(params, "beliefClusterId");
+        const permission = readString2(params, "permission", { required: true }) ?? "read";
+        const principal = readString2(params, "principal");
+        const beliefClusterId = readString2(params, "beliefClusterId");
         const result = await policy.checkPermission({
           topicId,
           permission,
@@ -10646,10 +10995,10 @@ function createPolicyHandlers(context) {
       MCP_TOOL_CONTRACTS.filter_by_permission,
       async (params) => {
         const topicIds = readStringArray(params, "topicIds") ?? [];
-        const permission = readString(params, "permission", {
+        const permission = readString2(params, "permission", {
           required: true
         }) ?? "read";
-        const principal = readString(params, "principal");
+        const principal = readString2(params, "principal");
         const result = await policy.filterByPermission({
           topicIds,
           permission,
@@ -10680,10 +11029,10 @@ function createQuestionHandlers(context) {
       MCP_TOOL_CONTRACTS.create_question,
       async (params) => {
         const response = await lucern.questions.create({
-          text: readString(params, "text", { required: true }),
+          text: readString2(params, "text", { required: true }),
           topicId: readTopicId(params, { required: true }),
-          priority: readString(params, "priority"),
-          linkedBeliefId: readString(params, "linkedBeliefId"),
+          priority: readString2(params, "priority"),
+          linkedBeliefId: readString2(params, "linkedBeliefId"),
           metadata: readMetadata2(params)
         });
         return response.data;
@@ -10693,7 +11042,7 @@ function createQuestionHandlers(context) {
       MCP_TOOL_CONTRACTS.get_question,
       async (params) => {
         const response = await lucern.questions.get(
-          readString(params, "id", { required: true })
+          readString2(params, "id", { required: true })
         );
         return response.data;
       }
@@ -10703,11 +11052,11 @@ function createQuestionHandlers(context) {
       async (params) => {
         const response = await lucern.questions.list({
           topicId: readTopicId(params, { required: true }),
-          status: readString(params, "status"),
-          priority: readString(params, "priority"),
-          worktreeId: readString(params, "worktreeId"),
-          limit: readNumber(params, "limit"),
-          cursor: readString(params, "cursor")
+          status: readString2(params, "status"),
+          priority: readString2(params, "priority"),
+          worktreeId: readString2(params, "worktreeId"),
+          limit: readNumber2(params, "limit"),
+          cursor: readString2(params, "cursor")
         });
         return response.data;
       }
@@ -10716,12 +11065,12 @@ function createQuestionHandlers(context) {
       MCP_TOOL_CONTRACTS.answer_question,
       async (params) => {
         const response = await lucern.questions.answer(
-          readString(params, "id", { required: true }),
+          readString2(params, "id", { required: true }),
           {
-            text: readString(params, "text", { required: true }),
-            confidence: readString(params, "confidence"),
+            text: readString2(params, "text", { required: true }),
+            confidence: readString2(params, "confidence"),
             evidenceIds: readStringArray(params, "evidenceIds"),
-            rationale: readString(params, "rationale")
+            rationale: readString2(params, "rationale")
           }
         );
         return response.data;
@@ -10731,9 +11080,9 @@ function createQuestionHandlers(context) {
       MCP_TOOL_CONTRACTS.refine_question,
       async (params) => {
         const response = await lucern.questions.refine(
-          readString(params, "id") ?? readString(params, "questionId", { required: true }),
-          readString(params, "text", { required: true }),
-          readString(params, "rationale") ?? readString(params, "refinementReason")
+          readString2(params, "id") ?? readString2(params, "questionId", { required: true }),
+          readString2(params, "text", { required: true }),
+          readString2(params, "rationale") ?? readString2(params, "refinementReason")
         );
         return response.data;
       }
@@ -10742,9 +11091,9 @@ function createQuestionHandlers(context) {
       MCP_TOOL_CONTRACTS.update_question_status,
       async (params) => {
         const response = await lucern.questions.updateStatus(
-          readString(params, "id") ?? readString(params, "questionId", { required: true }),
-          readString(params, "status", { required: true }),
-          readString(params, "rationale")
+          readString2(params, "id") ?? readString2(params, "questionId", { required: true }),
+          readString2(params, "status", { required: true }),
+          readString2(params, "rationale")
         );
         return response.data;
       }
@@ -10753,8 +11102,8 @@ function createQuestionHandlers(context) {
       MCP_TOOL_CONTRACTS.archive_question,
       async (params) => {
         return lucern.questions.archive(
-          readString(params, "questionId", { required: true }),
-          readString(params, "reason")
+          readString2(params, "questionId", { required: true }),
+          readString2(params, "reason")
         );
       }
     ),
@@ -10762,10 +11111,10 @@ function createQuestionHandlers(context) {
       MCP_TOOL_CONTRACTS.link_evidence_to_question,
       async (params) => {
         return lucern.questions.linkEvidence({
-          evidenceId: readString(params, "evidenceId", { required: true }),
-          questionId: readString(params, "questionId", { required: true }),
-          relevance: readNumber(params, "relevance") ?? 1,
-          rationale: readString(params, "rationale")
+          evidenceId: readString2(params, "evidenceId", { required: true }),
+          questionId: readString2(params, "questionId", { required: true }),
+          relevance: readNumber2(params, "relevance") ?? 1,
+          rationale: readString2(params, "rationale")
         });
       }
     ),
@@ -10774,7 +11123,7 @@ function createQuestionHandlers(context) {
       async (params) => {
         return lucern.questions.getHighPriority({
           topicId: readTopicId(params, { required: true }),
-          limit: readNumber(params, "limit"),
+          limit: readNumber2(params, "limit"),
           includeAnswered: readBoolean(params, "includeAnswered")
         });
       }
@@ -10784,7 +11133,7 @@ function createQuestionHandlers(context) {
       async (params) => {
         return lucern.questions.findMissing({
           topicId: readTopicId(params, { required: true }),
-          minConfidence: readNumber(params, "minConfidence")
+          minConfidence: readNumber2(params, "minConfidence")
         });
       }
     )
@@ -10806,7 +11155,7 @@ function asSourceArray(data) {
 function createResearchHandlers(context) {
   const graph = createGraphClient(context.sdkConfig);
   const searchSources = async (params) => {
-    const query = readString(params, "query", { required: true });
+    const query = readString2(params, "query", { required: true });
     const topicId = readTopicId(params);
     const sourceTypes = readStringArray(params, "sources") ?? [];
     if (!topicId) {
@@ -10845,9 +11194,9 @@ function createResearchHandlers(context) {
     execute_deep_research: contractToHandler(
       MCP_TOOL_CONTRACTS.execute_deep_research,
       async (params) => {
-        const query = readString(params, "query", { required: true });
+        const query = readString2(params, "query", { required: true });
         const topicId = readTopicId(params, { required: true });
-        const depth = readString(params, "depth") ?? "standard";
+        const depth = readString2(params, "depth") ?? "standard";
         const sources = await searchSources({
           query,
           topicId,
@@ -10883,13 +11232,13 @@ function createSearchHandlers(context) {
     search_resources: contractToHandler(
       MCP_TOOL_CONTRACTS.search_resources,
       async (params) => {
-        return lucern.search(readString(params, "q", { required: true }), {
+        return lucern.search(readString2(params, "q", { required: true }), {
           topicId: readTopicId(params, { required: true }),
           types: readStringArray(params, "types"),
-          status: readString(params, "status"),
-          minConfidence: readNumber(params, "minConfidence"),
-          limit: readNumber(params, "limit"),
-          cursor: readString(params, "cursor")
+          status: readString2(params, "status"),
+          minConfidence: readNumber2(params, "minConfidence"),
+          limit: readNumber2(params, "limit"),
+          cursor: readString2(params, "cursor")
         });
       }
     )
@@ -10903,11 +11252,11 @@ function createTaskHandlers(context) {
     create_task: contractToHandler(
       MCP_TOOL_CONTRACTS.create_task,
       async (params) => {
-        const title = readString(params, "title", { required: true });
+        const title = readString2(params, "title", { required: true });
         const topicId = readTopicId(params, { required: true });
-        const taskType = readString(params, "taskType");
-        const linkedQuestionId = readString(params, "linkedQuestionId");
-        const linkedWorktreeId = readString(params, "linkedWorktreeId");
+        const taskType = readString2(params, "taskType");
+        const linkedQuestionId = readString2(params, "linkedQuestionId");
+        const linkedWorktreeId = readString2(params, "linkedWorktreeId");
         const result = await workflow.createTask({
           title,
           topicId,
@@ -10925,8 +11274,8 @@ function createTaskHandlers(context) {
     complete_task: contractToHandler(
       MCP_TOOL_CONTRACTS.complete_task,
       async (params) => {
-        const taskId = readString(params, "taskId", { required: true });
-        const outputSummary = readString(params, "outputSummary", {
+        const taskId = readString2(params, "taskId", { required: true });
+        const outputSummary = readString2(params, "outputSummary", {
           required: true
         });
         const evidenceCreated = readBoolean(params, "evidenceCreated");
@@ -10944,15 +11293,15 @@ function createTaskHandlers(context) {
     update_task: contractToHandler(
       MCP_TOOL_CONTRACTS.update_task,
       async (params) => {
-        const taskId = readString(params, "taskId", { required: true });
-        const title = readString(params, "title");
-        const description = readString(params, "description");
-        const linkedBeliefId = readString(params, "linkedBeliefId");
-        const linkedQuestionId = readString(params, "linkedQuestionId");
-        const linkedWorktreeId = readString(params, "linkedWorktreeId");
-        const rawPriority = readString(params, "priority");
+        const taskId = readString2(params, "taskId", { required: true });
+        const title = readString2(params, "title");
+        const description = readString2(params, "description");
+        const linkedBeliefId = readString2(params, "linkedBeliefId");
+        const linkedQuestionId = readString2(params, "linkedQuestionId");
+        const linkedWorktreeId = readString2(params, "linkedWorktreeId");
+        const rawPriority = readString2(params, "priority");
         const priority = rawPriority === "critical" || rawPriority === "high" || rawPriority === "medium" || rawPriority === "low" ? rawPriority : void 0;
-        const rawStatus = readString(params, "status");
+        const rawStatus = readString2(params, "status");
         const status = rawStatus === "todo" || rawStatus === "in_progress" || rawStatus === "blocked" || rawStatus === "done" ? rawStatus : void 0;
         const result = await workflow.updateTask(taskId, {
           title,
@@ -10990,11 +11339,11 @@ function createWorktreeHandlers(context) {
   return {
     create_lens: contractToHandler(MCP_TOOL_CONTRACTS.create_lens, async (params) => {
       const result = await workflow.createLens({
-        name: readString(params, "name", { required: true }),
-        workspaceId: readString(params, "workspaceId"),
+        name: readString2(params, "name", { required: true }),
+        workspaceId: readString2(params, "workspaceId"),
         topicId: readTopicId(params),
-        description: readString(params, "description"),
-        perspectiveType: readString(params, "perspectiveType", {
+        description: readString2(params, "description"),
+        perspectiveType: readString2(params, "perspectiveType", {
           required: true
         }),
         promptTemplates: Array.isArray(params.promptTemplates) ? params.promptTemplates : void 0,
@@ -11004,17 +11353,17 @@ function createWorktreeHandlers(context) {
       });
       return {
         lensId: result.data.lensId ?? "",
-        name: result.data.name ?? readString(params, "name", { required: true }),
-        workspaceId: result.data.workspaceId ?? readString(params, "workspaceId") ?? null,
+        name: result.data.name ?? readString2(params, "name", { required: true }),
+        workspaceId: result.data.workspaceId ?? readString2(params, "workspaceId") ?? null,
         status: result.data.status ?? "active"
       };
     }),
     list_lenses: contractToHandler(MCP_TOOL_CONTRACTS.list_lenses, async (params) => {
       const result = await workflow.listLenses({
-        workspaceId: readString(params, "workspaceId"),
+        workspaceId: readString2(params, "workspaceId"),
         topicId: readTopicId(params),
-        status: readString(params, "status"),
-        perspectiveType: readString(params, "perspectiveType")
+        status: readString2(params, "status"),
+        perspectiveType: readString2(params, "perspectiveType")
       });
       return {
         lenses: result.data.items ?? ("lenses" in result.data && Array.isArray(result.data.lenses) ? result.data.lenses : [])
@@ -11024,7 +11373,7 @@ function createWorktreeHandlers(context) {
       MCP_TOOL_CONTRACTS.apply_lens_to_topic,
       async (params) => {
         const topicId = readTopicId(params, { required: true });
-        const lensId = readString(params, "lensId", { required: true });
+        const lensId = readString2(params, "lensId", { required: true });
         const result = await workflow.applyLensToTopic({
           lensId,
           topicId,
@@ -11042,7 +11391,7 @@ function createWorktreeHandlers(context) {
       MCP_TOOL_CONTRACTS.remove_lens_from_topic,
       async (params) => {
         const topicId = readTopicId(params, { required: true });
-        const lensId = readString(params, "lensId", { required: true });
+        const lensId = readString2(params, "lensId", { required: true });
         const result = await workflow.removeLensFromTopic({
           lensId,
           topicId
@@ -11063,18 +11412,18 @@ function createWorktreeHandlers(context) {
           throw new Error("add_worktree requires topicId");
         }
         const result = await workflow.addWorktree({
-          title: readString(params, "title", { required: true }),
+          title: readString2(params, "title", { required: true }),
           topicId,
-          branchId: readString(params, "branchId"),
-          objective: readString(params, "objective"),
-          hypothesis: readString(params, "hypothesis"),
+          branchId: readString2(params, "branchId"),
+          objective: readString2(params, "objective"),
+          hypothesis: readString2(params, "hypothesis"),
           beliefIds: readStringArray(params, "beliefIds"),
           autoShape: readBoolean(params, "autoShape"),
-          domainPackId: readString(params, "domainPackId"),
+          domainPackId: readString2(params, "domainPackId"),
           executionOrder: typeof params.executionOrder === "number" ? params.executionOrder : void 0,
           dependsOn: readStringArray(params, "dependsOn"),
           blocks: readStringArray(params, "blocks"),
-          gate: readString(params, "gate")
+          gate: readString2(params, "gate")
         });
         return {
           worktreeId: result.data.worktreeId,
@@ -11091,11 +11440,11 @@ function createWorktreeHandlers(context) {
       }
     ),
     merge: contractToHandler(MCP_TOOL_CONTRACTS.merge, async (params) => {
-      const worktreeId = readString(params, "worktreeId", { required: true });
+      const worktreeId = readString2(params, "worktreeId", { required: true });
       const outcomes = Array.isArray(params.outcomes) ? params.outcomes : [];
       const result = await workflow.merge(worktreeId, {
         outcomes,
-        summary: readString(params, "summary")
+        summary: readString2(params, "summary")
       });
       return {
         worktreeId: result.data.worktreeId ?? worktreeId,
@@ -11104,8 +11453,8 @@ function createWorktreeHandlers(context) {
       };
     }),
     push: contractToHandler(MCP_TOOL_CONTRACTS.push, async (params) => {
-      const worktreeId = readString(params, "worktreeId", { required: true });
-      const targetContext = readString(params, "targetContext", {
+      const worktreeId = readString2(params, "worktreeId", { required: true });
+      const targetContext = readString2(params, "targetContext", {
         required: true
       });
       const result = await workflow.push(worktreeId, {
@@ -11121,10 +11470,10 @@ function createWorktreeHandlers(context) {
     open_pull_request: contractToHandler(
       MCP_TOOL_CONTRACTS.open_pull_request,
       async (params) => {
-        const worktreeId = readString(params, "worktreeId", {
+        const worktreeId = readString2(params, "worktreeId", {
           required: true
         });
-        const summary = readString(params, "summary", { required: true });
+        const summary = readString2(params, "summary", { required: true });
         const reviewers = readStringArray(params, "reviewers");
         const result = await workflow.openPullRequest(worktreeId, {
           summary,
@@ -11141,7 +11490,7 @@ function createWorktreeHandlers(context) {
       MCP_TOOL_CONTRACTS.list_worktrees,
       async (params) => {
         const topicId = readTopicId(params, { required: true });
-        const status = mapWorktreeStatus(readString(params, "status"));
+        const status = mapWorktreeStatus(readString2(params, "status"));
         const result = await workflow.listWorktrees({
           topicId,
           status
@@ -12181,7 +12530,7 @@ async function runLucernMcpCli(argv = process.argv.slice(2)) {
   }
 }
 
-// src/legacyToolContracts.ts
+// src/toolContracts.ts
 function pickToolContracts(names) {
   return Object.fromEntries(
     names.flatMap((name) => {
@@ -12224,16 +12573,16 @@ var SCOPE_MCP_TOOLS = pickToolContracts([
   "trigger_belief_review"
 ]);
 
-// src/legacyAuthenticatedHandlers.ts
-var LEGACY_HANDLER_TOOL_NAMES = [
+// src/authenticatedHandlers.ts
+var GATEWAY_HANDLER_TOOL_NAMES = [
   ...Object.keys(SCOPE_MCP_TOOLS),
   ...Object.keys(COORDINATION_MCP_TOOLS),
   ...Object.keys(EPISTEMIC_CONTRACT_MCP_TOOLS),
   ...Object.keys(BOOTSTRAP_MCP_TOOLS)
 ];
-function buildLegacyGatewayClient(ctx) {
+function buildGatewayClient(ctx) {
   if (!ctx.gatewayBaseUrl || !ctx.getAuthHeaders) {
-    throw new Error("Legacy MCP bridge requires gateway auth headers.");
+    throw new Error("MCP gateway bridge requires auth headers.");
   }
   return createGatewayRequestClient({
     baseUrl: ctx.gatewayBaseUrl,
@@ -12246,12 +12595,12 @@ function withSessionId(args, ctx) {
     __sdkSessionId: ctx.sessionId
   };
 }
-async function buildLegacyAuthenticatedHandlerMap() {
+async function buildAuthenticatedHandlerMap() {
   return Object.fromEntries(
-    LEGACY_HANDLER_TOOL_NAMES.map((toolName) => [
+    GATEWAY_HANDLER_TOOL_NAMES.map((toolName) => [
       toolName,
       async (args, ctx) => {
-        const gateway = buildLegacyGatewayClient(ctx);
+        const gateway = buildGatewayClient(ctx);
         const response = await gateway.request({
           path: `/api/platform/v1/mcp-tools/${encodeURIComponent(toolName)}`,
           method: "POST",
@@ -12320,7 +12669,7 @@ function parseCredentialsFile(filePath) {
   }
   return result;
 }
-function resolveCredentials() {
+function resolveMcpCredentials() {
   if (process.env.LUCERN_CONVEX_URL && process.env.LUCERN_DEPLOY_KEY) {
     return {
       lucernResolved: true,
@@ -12438,7 +12787,7 @@ function initializeLucernScriptEnv() {
       }
     }
   }
-  resolveCredentials();
+  resolveMcpCredentials();
   lucernScriptEnvInitialized = true;
 }
 function readArg(name, fallback) {
@@ -12485,7 +12834,7 @@ async function createLucernMcpClient() {
   const deployKey = requireEnv("LUCERN_DEPLOY_KEY");
   const transport = new StdioClientTransport({
     command: "npx",
-    args: ["tsx", "lucern/apps/mcp-server/src/index.ts"],
+    args: ["tsx", "apps/mcp-server/src/index.ts"],
     env: {
       ...process.env,
       LUCERN_CONVEX_URL: convexUrl,
@@ -12509,7 +12858,7 @@ function createLucernAdminClient() {
 }
 async function resolveMcpSessionTenantId() {
   initializeLucernScriptEnv();
-  const apiKey = resolveCredentials().rawLucernApiKey;
+  const apiKey = resolveMcpCredentials().rawLucernApiKey;
   if (!apiKey) {
     return void 0;
   }
@@ -12538,8 +12887,8 @@ async function closeMcpClient(client) {
   await client.close();
 }
 
-// src/legacyDiscovery.ts
-async function loadLegacyDiscoveryHandlers() {
+// src/discovery.ts
+async function loadDiscoveryHandlers() {
   return {
     async discover(args, ctx) {
       const query = typeof args.query === "string" ? args.query : "";
@@ -12862,6 +13211,6 @@ function validateContextPackSchema2(payload) {
   };
 }
 
-export { BOOTSTRAP_MCP_TOOLS, COORDINATION_MCP_TOOLS, EPISTEMIC_CONTRACT_MCP_TOOLS, LUCERN_AGENT_MD, LUCERN_MCP_RESOURCE_URIS, LUCERN_MCP_TOOL_NAMES, LUCERN_OBSERVER_PROMPT_NAME, McpObservationStore, SCOPE_MCP_TOOLS, buildLegacyAuthenticatedHandlerMap, buildLucernObserverPrompt, callMcpTool, classifyTransportParityDrift, closeMcpClient, createLucernAdminClient, createLucernMcpClient, createLucernMcpHttpRequestHandler, createLucernMcpServer, createLucernStandaloneMcpServer, createMcpHandlerRegistry, createToolExecutionEnvelope, executeToolWithEnvelope, initializeLucernScriptEnv, loadLegacyDiscoveryHandlers, parseToolExecutionMetadata, readArg, resolveCredentials as resolveLegacyMcpCredentials, resolveMcpSessionTenantId, runLucernMcpCli, startLucernMcpHttpServer, startLucernMcpStdioServer, validateContextPackSchema2 as validateContextPackSchema };
+export { BOOTSTRAP_MCP_TOOLS, COORDINATION_MCP_TOOLS, EPISTEMIC_CONTRACT_MCP_TOOLS, LUCERN_AGENT_MD, LUCERN_MCP_RESOURCE_URIS, LUCERN_MCP_TOOL_NAMES, LUCERN_OBSERVER_PROMPT_NAME, McpObservationStore, SCOPE_MCP_TOOLS, buildAuthenticatedHandlerMap, buildLucernObserverPrompt, callMcpTool, classifyTransportParityDrift, closeMcpClient, createLucernAdminClient, createLucernMcpClient, createLucernMcpHttpRequestHandler, createLucernMcpServer, createLucernStandaloneMcpServer, createMcpHandlerRegistry, createToolExecutionEnvelope, executeToolWithEnvelope, initializeLucernScriptEnv, loadDiscoveryHandlers, parseToolExecutionMetadata, readArg, resolveMcpCredentials, resolveMcpSessionTenantId, runLucernMcpCli, startLucernMcpHttpServer, startLucernMcpStdioServer, validateContextPackSchema2 as validateContextPackSchema };
 //# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map