@lucern/contracts 1.0.16 → 1.0.17

package/dist/sdk-tools.contract.registry.js

@@ -1,15 +1,23 @@
 // 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",
@@ -24,7 +32,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: {
@@ -33,7 +41,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"
     }
   },
@@ -56,7 +64,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"
     }
   },
@@ -85,34 +93,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",
@@ -123,64 +121,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"
@@ -192,12 +165,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: {
@@ -699,7 +680,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: {
@@ -898,7 +879,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: {
@@ -917,7 +898,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",
@@ -1862,18 +1843,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",
@@ -1882,7 +1863,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",
@@ -1904,7 +1885,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: {
@@ -1979,7 +1960,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: {
@@ -2015,7 +1996,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: {
@@ -2834,6 +2815,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",
@@ -2841,15 +2827,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"
     }
@@ -4268,7 +4245,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: {
@@ -4624,7 +4601,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,