@lucern/contracts 1.0.16 → 1.0.17

package/dist/function-registry/beliefs.js

@@ -6,15 +6,23 @@ import { v } from 'convex/values';
 // src/tool-contracts.lifecycle.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 with a prior. Creation stores the vacuous opinion `(0, 0, 1, a)`; attach supporting or contradicting evidence with create_evidence or link_evidence_to_belief to record evidential updates.",
+  description: "Commit a new belief (knowledge unit) to the reasoning graph. Like `git commit` \u2014 creates an atomic, traceable knowledge object with a prior. Creation requires a topic epistemic-node anchor and writes a `scoped_by` edge directly from belief node to topic node; orphan beliefs are invalid. Creation stores the vacuous opinion `(0, 0, 1, a)`; attach supporting or contradicting evidence with create_evidence or link_evidence_to_belief to record evidential updates.",
   parameters: {
     canonicalText: {
       type: "string",
       description: "The belief statement \u2014 what the agent holds to be true"
     },
+    topicGlobalId: {
+      type: "string",
+      description: "Required globalId (UUID) of the topic node in epistemicNodes that anchors the belief"
+    },
+    topicNodeId: {
+      type: "string",
+      description: "Optional internal epistemicNodes _id for the topic anchor. Prefer topicGlobalId for public callers."
+    },
     topicId: {
       type: "string",
-      description: "Optional topic scope hint for the belief"
+      description: "Deprecated compatibility alias for topicGlobalId. Must identify a topic epistemicNode, not a legacy topics-table row."
     },
     baseRate: {
       type: "number",
@@ -29,7 +37,7 @@ var CREATE_BELIEF = {
       description: "Optional extra metadata merged into the node (e.g., { codeAnchors: ['path/to/file.ts'] } for coding intelligence)"
     }
   },
-  required: ["canonicalText"],
+  required: ["canonicalText", "topicGlobalId"],
   response: {
     description: "The created canonical belief record",
     fields: {
@@ -38,7 +46,7 @@ var CREATE_BELIEF = {
       beliefId: "string \u2014 canonical belief ID",
       text: "string \u2014 canonical belief formulation",
       topicId: "string",
-      status: "string \u2014 active | superseded | archived",
+      beliefStatus: "string \u2014 assumption | hypothesis | active | superseded | resolved_true | resolved_false",
       scoringState: "string \u2014 unscored | scored"
     }
   },
@@ -61,7 +69,7 @@ var GET_BELIEF = {
       beliefId: "string \u2014 canonical belief ID",
       text: "string \u2014 canonical belief formulation",
       topicId: "string",
-      status: "string \u2014 active | superseded | archived",
+      beliefStatus: "string \u2014 assumption | hypothesis | active | superseded | resolved_true | resolved_false",
       scoringState: "string \u2014 unscored | scored"
     }
   },
@@ -90,34 +98,24 @@ var REFINE_BELIEF = {
   ontologyPrimitive: "belief",
   tier: "showcase"
 };
-var MODULATE_CONFIDENCE = {
-  name: "modulate_confidence",
-  description: "Internal-only subjective-logic ledger append. Like `git commit` to the credence log for the scoring engine \u2014 never an operator-facing way to assert confidence. Agents, SDK callers, CLI users, and MCP clients must instead create or link evidence with `evidenceRelation: supports|contradicts`; the kernel derives the next opinion from that evidence. This compatibility primitive is reserved for governed system scoring paths that already hold a full subjective-logic tuple and truth-bearing provenance.",
+var APPEND_SL_SCORING = {
+  name: "append_sl_scoring",
+  description: "Internal evidence-backed Subjective Logic scoring append. This is not a public MCP tool: callers should attach supporting or contradicting evidence, and governed system paths append the derived SL tuple.",
   parameters: {
-    nodeId: { type: "string", description: "The belief to score" },
-    belief: {
-      type: "number",
-      description: "Subjective-logic belief mass `b` in [0, 1]"
-    },
+    nodeId: { type: "string", description: "The belief receiving the SL score" },
+    belief: { type: "number", description: "Subjective Logic belief mass b" },
     disbelief: {
       type: "number",
-      description: "Subjective-logic disbelief mass `d` in [0, 1]"
+      description: "Subjective Logic disbelief mass d"
     },
     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."
-    },
-    worktreeId: {
-      type: "string",
-      description: "Completed worktree that tested this belief when confidence policy requires merge-backed scoring."
+      description: "Subjective Logic uncertainty mass u"
     },
+    baseRate: { type: "number", description: "Subjective Logic base rate a" },
     trigger: {
       type: "string",
-      description: "What caused this confidence change",
+      description: "Evidence-bearing cause of the scoring event",
       enum: [
         "evidence_added",
         "evidence_removed",
@@ -128,64 +126,39 @@ var MODULATE_CONFIDENCE = {
         "worktree_completed",
         "fusion",
         "discount",
-        "deduction"
+        "deduction",
+        "backfill_synthetic"
       ]
     },
-    triggeringEvidenceId: {
-      type: "string",
-      description: "Evidence node that caused an evidence-triggered modulation"
-    },
-    triggeringQuestionId: {
-      type: "string",
-      description: "Answered question whose resolution supports this modulation"
-    },
-    triggeringAnswerId: {
-      type: "string",
-      description: "Answer node whose content supports this modulation"
-    },
-    triggeringContradictionId: {
-      type: "string",
-      description: "Contradiction record that caused a contradiction-triggered modulation"
-    },
-    triggeringWorktreeId: {
-      type: "string",
-      description: "Completed worktree whose outcome caused a worktree-triggered modulation"
+    provenance: {
+      type: "object",
+      description: "At least one of evidence, question, answer, contradiction, or worktree."
     },
     rationale: {
       type: "string",
-      description: "Human-readable explanation of why confidence changed"
+      description: "Why this evidence-bearing event moved the SL tuple"
     }
   },
-  required: [
-    "nodeId",
-    "belief",
-    "disbelief",
-    "uncertainty",
-    "baseRate",
-    "trigger",
-    "rationale"
-  ],
+  required: ["nodeId", "belief", "disbelief", "uncertainty", "baseRate", "trigger", "rationale"],
   response: {
-    description: "Confidence modulation result",
+    description: "Internal SL scoring append receipt",
     fields: {
-      beliefId: "string \u2014 canonical belief ID",
-      nodeId: "string \u2014 canonical belief ID",
-      newConfidence: "number",
+      nodeId: "string",
       previousConfidence: "number",
-      trigger: "string",
-      requestId: "string \u2014 request identifier for the scheduled cascade",
-      propagationSummary: "object \u2014 bounded inline cascade summary with totalCandidateTargets, inlineTargets, and remainingTargetCount"
+      newConfidence: "number",
+      beliefConfidenceId: "string"
     }
   },
   ownerModule: "graph-primitives",
   ontologyPrimitive: "belief",
-  tier: "showcase"
+  tier: "workhorse",
+  internal: true
 };
 var FORK_BELIEF = {
   name: "fork_belief",
-  description: "Branch off a scored belief to create a new version with a different formulation. Like `git fork` \u2014 the parent remains immutable with full history. The new belief gets a `supersedes` edge to the parent. Fork reasons: refinement, contradiction_response, scope_change, confidence_collapse, manual.",
+  description: "Branch off an evidence-bearing belief to create a new formulation. Like `git fork` \u2014 the parent remains immutable with full history, and every fork must cite evidence already attached to the parent through SL scoring. `forkMode=supersede` marks the parent superseded and requires contradicting evidence; `forkMode=branch` preserves the parent and creates a derived child.",
   parameters: {
-    nodeId: { type: "string", description: "The scored belief to fork from" },
+    nodeId: { type: "string", description: "The belief to fork from" },
     newFormulation: {
       type: "string",
       description: "The evolved belief statement"
@@ -197,12 +170,20 @@ var FORK_BELIEF = {
         "refinement",
         "contradiction_response",
         "scope_change",
-        "confidence_collapse",
-        "manual"
+        "confidence_collapse"
       ]
+    },
+    forkMode: {
+      type: "string",
+      description: "supersede replaces the parent; branch creates a child while preserving the parent.",
+      enum: ["supersede", "branch"]
+    },
+    triggeringEvidenceId: {
+      type: "string",
+      description: "Evidence already attached to the parent belief that caused the fork."
     }
   },
-  required: ["nodeId", "newFormulation", "forkReason"],
+  required: ["nodeId", "newFormulation", "forkReason", "triggeringEvidenceId"],
   response: {
     description: "The forked canonical belief record",
     fields: {
@@ -704,7 +685,7 @@ var REASONING_METHODS = [
 // src/tool-contracts.graph.ts
 var QUERY_LINEAGE = {
   name: "query_lineage",
-  description: "Trace a belief's full ancestry \u2014 every fork, score, and confidence modulation. Like `git log --graph`. Returns the complete evolution chain showing how understanding developed over time. Lineage is permanent and can never be erased (Invariant #3).",
+  description: "Trace a belief's full ancestry \u2014 every fork, score, and SL scoring event. Like `git log --graph`. Returns the complete evolution chain showing how understanding developed over time. Lineage is permanent and can never be erased (Invariant #3).",
   parameters: {
     nodeId: { type: "string", description: "Starting node to trace from" },
     depth: {
@@ -903,7 +884,7 @@ var FIND_CONTRADICTIONS = {
 };
 var BISECT_CONFIDENCE = {
   name: "bisect_confidence",
-  description: "Find when a belief's confidence diverged from reality. Like `git bisect` \u2014 binary search through the credence history to find the inflection point. Given a belief that is now known to be wrong (or right), traces back through confidence modulations to identify which evidence or event caused the divergence.",
+  description: "Find when a belief's confidence diverged from reality. Like `git bisect` \u2014 binary search through the credence history to find the inflection point. Given a belief that is now known to be wrong (or right), traces back through SL scoring events to identify which evidence or event caused the divergence.",
   parameters: {
     nodeId: { type: "string", description: "The belief to bisect" },
     expectedDirection: {
@@ -922,7 +903,7 @@ var BISECT_CONFIDENCE = {
     fields: {
       beliefId: "string \u2014 canonical belief ID",
       expectedDirection: "string \u2014 overconfident | underconfident",
-      inflectionEntry: "object \u2014 the confidence modulation where divergence began",
+      inflectionEntry: "object \u2014 the scoring event where divergence began",
       triggerEvent: "string | null \u2014 what caused the divergence",
       confidenceBefore: "number | null",
       confidenceAfter: "number | null",
@@ -1867,18 +1848,18 @@ var SEARCH_EVIDENCE = {
 };
 var CREATE_EVIDENCE = {
   name: "create_evidence",
-  description: "Commit evidence to the reasoning graph. Like `git commit` \u2014 creates a traceable evidence record with canonical public IDs. Optionally links the evidence to a belief or question in the same operation. When evidence bears on beliefs, state whether it supports or contradicts; SL confidence is derived from these evidence relations.",
+  description: "Commit evidence to the reasoning graph. Like `git commit` \u2014 creates a traceable evidence record with canonical public IDs. Evidence creation must link to at least one belief and must include a signed impact score. Positive scores support the belief; negative scores contradict it. SL confidence is derived from these weighted evidence relations.",
   parameters: {
     topicId: { type: "string", description: "Topic scope" },
     text: { type: "string", description: "Canonical evidence text" },
     source: { type: "string", description: "Source URL or source label" },
     targetId: {
       type: "string",
-      description: "Optional belief or question identifier to link immediately"
+      description: "Belief identifier to link immediately"
     },
     weight: {
       type: "number",
-      description: "Optional support weight: -1.0 (contradicts) to +1.0 (supports). If omitted, evidenceRelation + confidence determine the weight."
+      description: "Required nonzero signed impact score: -1.0 (contradicts) to +1.0 (supports)."
     },
     evidenceRelation: {
       type: "string",
@@ -1887,7 +1868,7 @@ var CREATE_EVIDENCE = {
     },
     confidence: {
       type: "number",
-      description: "Confidence in the evidence relation, 0.0 to 1.0"
+      description: "Deprecated hint. Runtime confidence is derived from the signed impact score."
     },
     beliefRelations: {
       type: "array",
@@ -1909,7 +1890,7 @@ var CREATE_EVIDENCE = {
     },
     kind: { type: "string", description: "Optional evidence kind" }
   },
-  required: ["text", "rationale"],
+  required: ["text", "rationale", "weight"],
   response: {
     description: "The created canonical evidence record",
     fields: {
@@ -1984,7 +1965,7 @@ var LINK_EVIDENCE = {
     },
     rationale: { type: "string", description: "Why this link exists" }
   },
-  required: ["evidenceId", "targetId"],
+  required: ["evidenceId", "targetId", "weight"],
   response: {
     description: "The created canonical evidence edge summary",
     fields: {
@@ -2020,7 +2001,7 @@ var LINK_EVIDENCE_TO_BELIEF = {
     },
     rationale: { type: "string", description: "Why this evidence is relevant" }
   },
-  required: ["evidenceId", "beliefId"],
+  required: ["evidenceId", "beliefId", "weight"],
   response: {
     description: "The created edge linking evidence to belief",
     fields: {
@@ -2839,6 +2820,11 @@ var COMPILE_CONTEXT = {
   response: {
     description: "Compiled context pack for the requested topic",
     fields: {
+      contextNarrative: "array \u2014 first field; ordered synthesis blocks with kind/text, starting with executive_summary and canonical narrative blocks before raw objects",
+      narrativeCoverage: "object \u2014 recordsSynthesized, recordsNamed, recordsOmitted, topicsSynthesized, topicsEnriched, topicContentOmitted, enrichmentMode, and blocksEmitted for the narrative",
+      synthesisLints: "array \u2014 inline quality warnings for degenerate synthesis blocks or weak narrative coverage",
+      retrievalReceipt: "object \u2014 candidateCounts, coverageWarning, narrativeCoverage, synthesisLints, and suggestedNextActions",
+      supportingObjects: "object \u2014 raw graph records grouped behind the synthesis: invariants, activeBeliefs, openQuestions, recentEvidence, worktrees, lanes, entities, and contradictions",
       schemaVersion: "string",
       topicId: "string",
       topicName: "string",
@@ -2846,15 +2832,6 @@ var COMPILE_CONTEXT = {
       generatedAt: "number \u2014 deterministic graph-backed reference timestamp for this compilation",
       ranking: "string \u2014 baseline_v1 | weighted_v1",
       summary: "object \u2014 counts and scoped health signals",
-      invariants: "array \u2014 high-confidence invariant beliefs",
-      activeBeliefs: "array \u2014 current high-signal beliefs",
-      openQuestions: "array \u2014 unresolved questions ranked for this query",
-      recentEvidence: "array \u2014 recent evidence ranked for this query",
-      contradictions: "array \u2014 unresolved contradiction records",
-      relatedEntities: "array | undefined \u2014 ranked ontological entities in scope",
-      contextNarrative: "array \u2014 ordered synthesis blocks with kind/text, starting with executive_summary and canonical narrative blocks before raw objects",
-      retrievalReceipt: "object \u2014 candidateCounts, coverageWarning, narrativeCoverage, synthesisLints, and suggestedNextActions",
-      narrativeCoverage: "object \u2014 recordsSynthesized, recordsNamed, recordsOmitted, topicsSynthesized, topicsEnriched, topicContentOmitted, enrichmentMode, and blocksEmitted for the narrative",
       injectionPolicy: "object \u2014 token-budgeted section selections",
       diagnostics: "object \u2014 scoring and utilization telemetry"
     }
@@ -4273,7 +4250,7 @@ var TRIGGER_BELIEF_REVIEW = {
 };
 var EVALUATE_CONTRACT = {
   name: "evaluate_contract",
-  description: "Run a contract evaluation and record the append-only result. Like `git test` for a belief binding \u2014 executes the evaluator, logs the result, and applies any allowed confidence modulation.",
+  description: "Run a contract evaluation and record the append-only result. Like `git test` for a belief binding \u2014 executes the evaluator, logs the result, and applies any allowed SL scoring action.",
   parameters: {
     contractId: { type: "string", description: "Which contract to evaluate" },
     trigger: {
@@ -4629,7 +4606,7 @@ var MCP_TOOL_CONTRACTS = {
   create_belief: CREATE_BELIEF,
   get_belief: GET_BELIEF,
   refine_belief: REFINE_BELIEF,
-  modulate_confidence: MODULATE_CONFIDENCE,
+  append_sl_scoring: APPEND_SL_SCORING,
   fork_belief: FORK_BELIEF,
   archive_belief: ARCHIVE_BELIEF,
   create_epistemic_contract: CREATE_EPISTEMIC_CONTRACT,
@@ -5124,12 +5101,12 @@ var LUCERN_OPERATION_MANIFEST = {
     internalSystem,
     "Lucern system/background operation. Available to platform code paths, hidden from public MCP discovery."
   ),
-  modulate_confidence: {
-    name: "modulate_confidence",
+  append_sl_scoring: {
+    name: "append_sl_scoring",
     surfaceClass: "platform_internal",
     surfaceIntent: "system",
     surfaces: internalSdkRestOnly,
-    rationale: "Internal SL ledger append primitive. Public callers attach evidence or contradiction relations; confidence is derived algorithmically."
+    rationale: "Internal SL scoring append primitive. Public callers attach evidence or contradiction relations; confidence is derived algorithmically."
   },
   ...entries(
     LEGACY_COMPAT_OPERATION_NAMES,
@@ -5512,7 +5489,7 @@ var slOpinionProjectionSchema = z.object({
   uncertainty: z.number(),
   baseRate: z.number()
 });
-var modulateConfidenceInputObjectSchema = z.object({
+var appendSlScoringInputObjectSchema = z.object({
   nodeId: z.string().optional(),
   beliefNodeId: z.string().optional(),
   worktreeId: z.string().optional(),
@@ -5531,23 +5508,23 @@ var modulateConfidenceInputObjectSchema = z.object({
   rationale: z.string(),
   trustedBypassAccessCheck: z.boolean().optional()
 });
-var modulateConfidenceInputSchema = modulateConfidenceInputObjectSchema.superRefine((input, ctx) => {
+var appendSlScoringInputSchema = appendSlScoringInputObjectSchema.superRefine((input, ctx) => {
   if (hasProvenance(input)) {
     return;
   }
   ctx.addIssue({
     code: z.ZodIssueCode.custom,
-    message: "modulate_confidence requires evidence, question, answer, contradiction, or worktree provenance",
+    message: "append_sl_scoring requires evidence, question, answer, contradiction, or worktree provenance",
     path: ["provenance"]
   });
 });
-var modulateConfidenceProjection = defineProjection({
-  contractName: "modulate_confidence",
-  inputSchema: modulateConfidenceInputSchema,
+var appendSlScoringProjection = defineProjection({
+  contractName: "append_sl_scoring",
+  inputSchema: appendSlScoringInputSchema,
   project: (input) => {
     const nodeId = input.beliefNodeId ?? input.nodeId;
     if (!nodeId) {
-      throw new Error("modulate_confidence requires beliefNodeId or nodeId");
+      throw new Error("append_sl_scoring requires beliefNodeId or nodeId");
     }
     const opinion = input.opinion ?? {
       belief: requireNumber(input.belief, "belief"),
@@ -5604,14 +5581,14 @@ var modulateConfidenceProjection = defineProjection({
 });
 function requireNumber(value, field) {
   if (value === void 0) {
-    throw new Error(`modulate_confidence requires ${field}`);
+    throw new Error(`append_sl_scoring requires ${field}`);
   }
   return value;
 }
 function assertProvenance(input) {
   if (!hasProvenance(input)) {
     throw new Error(
-      "modulate_confidence requires evidence, question, answer, contradiction, or worktree provenance"
+      "append_sl_scoring requires evidence, question, answer, contradiction, or worktree provenance"
     );
   }
 }
@@ -5635,7 +5612,15 @@ var predictionMetaSchema = z.object({
 });
 var createBeliefArgs = z.object({
   canonicalText: z.string().describe("The belief statement the agent holds to be true."),
-  topicId: z.string().optional().describe("Topic scope hint for the belief."),
+  topicGlobalId: z.string().describe(
+    "Required globalId of the topic epistemicNode that anchors this belief. Belief creation creates a scoped_by edge directly to that topic node."
+  ),
+  topicNodeId: z.string().optional().describe(
+    "Optional internal epistemicNodes _id for the topic anchor. Prefer topicGlobalId for public callers."
+  ),
+  topicId: z.string().optional().describe(
+    "Deprecated compatibility alias for topicGlobalId. Must identify a topic epistemicNode, not a legacy topics-table row."
+  ),
   baseRate: z.number().optional().describe("Prior base rate used to seed the vacuous opinion."),
   beliefType: z.string().optional().describe("Schema belief type."),
   metadata: jsonRecordSchema.optional().describe("Extra metadata merged into the belief node."),
@@ -5654,9 +5639,14 @@ var forkBeliefArgs = z.object({
     "refinement",
     "contradiction_response",
     "scope_change",
-    "confidence_collapse",
-    "manual"
+    "confidence_collapse"
   ]).describe("Why this fork was created."),
+  forkMode: z.enum(["supersede", "branch"]).optional().describe(
+    "supersede marks the parent belief superseded; branch preserves the parent and creates a derived child."
+  ),
+  triggeringEvidenceId: z.string().describe(
+    "Evidence already attached to the parent belief through SL scoring; required for every fork."
+  ),
   rationale: z.string().optional().describe("Why the fork is warranted.")
 });
 var beliefLookupInput = (input) => compactRecord({
@@ -5670,7 +5660,9 @@ var createBeliefInput = (input, context) => {
   return withUserId(
     compactRecord({
       projectId: input.projectId,
-      topicId: input.topicId,
+      topicId: input.topicGlobalId ?? input.topicNodeId ?? input.topicId,
+      topicGlobalId: input.topicGlobalId,
+      topicNodeId: input.topicNodeId,
       formulation: input.formulation ?? input.canonicalText,
       beliefType: input.beliefType,
       rationale: input.rationale,
@@ -5692,20 +5684,22 @@ var forkBeliefInput = (input, context) => withUserId(
     parentNodeId: input.parentNodeId ?? input.nodeId ?? input.id,
     newFormulation: input.newFormulation,
     forkReason: input.forkReason,
+    forkMode: input.forkMode,
+    triggeringEvidenceId: input.triggeringEvidenceId,
     rationale: input.rationale,
     trustedBypassAccessCheck: input.trustedBypassAccessCheck ?? true
   }),
   context
 );
-var confidenceInput = (input, context) => {
-  const parsed = modulateConfidenceProjection.inputSchema.safeParse(input);
+var appendSlScoringInput = (input, context) => {
+  const parsed = appendSlScoringProjection.inputSchema.safeParse(input);
   if (!parsed.success) {
     throw new Error(
-      `modulate_confidence projection input rejected: ${parsed.error.message}`
+      `append_sl_scoring projection input rejected: ${parsed.error.message}`
     );
   }
   return withUserId(
-    compactRecord(modulateConfidenceProjection.project(parsed.data)),
+    compactRecord(appendSlScoringProjection.project(parsed.data)),
     context
   );
 };
@@ -5783,21 +5777,21 @@ var beliefsContracts = [
     }
   }),
   surfaceContract({
-    name: "modulate_confidence",
+    name: "append_sl_scoring",
     kind: "mutation",
     domain: "beliefs",
     surfaceClass: "platform_internal",
-    path: "/beliefs/confidence",
+    path: "/beliefs/sl-scoring",
     sdkNamespace: "beliefs",
-    sdkMethod: "modulateConfidence",
-    summary: "Internal SL ledger append. Public callers should attach evidence or contradiction relations instead.",
+    sdkMethod: "appendSlScoring",
+    summary: "Internal SL scoring append. Public callers attach evidence or contradiction relations instead.",
     convex: {
       module: "beliefs",
-      functionName: "modulateConfidence",
+      functionName: "appendSlScoring",
       kind: "mutation",
-      inputProjection: confidenceInput
+      inputProjection: appendSlScoringInput
     },
-    args: modulateConfidenceInputSchema
+    args: appendSlScoringInputSchema
   }),
   surfaceContract({
     name: "fork_belief",