@lucern/contracts 1.0.11 → 1.0.13

package/dist/tool-contracts.values.js

@@ -527,7 +527,7 @@ 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.",
+  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.",
   parameters: {
     topicId: { type: "string", description: "Topic scope" },
     text: { type: "string", description: "Canonical evidence text" },
@@ -538,7 +538,20 @@ var CREATE_EVIDENCE = {
     },
     weight: {
       type: "number",
-      description: "Support weight: -1.0 (contradicts) to +1.0 (supports)"
+      description: "Optional support weight: -1.0 (contradicts) to +1.0 (supports). If omitted, evidenceRelation + confidence determine the weight."
+    },
+    evidenceRelation: {
+      type: "string",
+      enum: ["supports", "contradicts"],
+      description: "Canonical relation to targetId/linkedBeliefNodeId. Prefer this over relying on signed weight inference."
+    },
+    confidence: {
+      type: "number",
+      description: "Confidence in the evidence relation, 0.0 to 1.0"
+    },
+    beliefRelations: {
+      type: "array",
+      description: "Optional additional belief relations: [{ beliefId|beliefNodeId|targetId, evidenceRelation|relation, confidence?, weight?, rationale? }]. Use one evidence node with multiple relations when the same fact supports or contradicts several beliefs."
     },
     metadata: {
       type: "object",
@@ -648,7 +661,7 @@ var LINK_EVIDENCE = {
 };
 var LINK_EVIDENCE_TO_BELIEF = {
   name: "link_evidence_to_belief",
-  description: "Link evidence to a belief with a support weight. Like `git add` \u2014 stages evidence in support of (or against) a belief. The weight ranges from -1.0 (strongly contradicts) to +1.0 (strongly supports).",
+  description: "Link evidence to a belief with a support weight. Like `git add` \u2014 stages evidence in support of (or against) a belief. The weight ranges from -1.0 (strongly contradicts) to +1.0 (strongly supports). This relation appends to the SL confidence ledger; do not hand-write confidence separately.",
   parameters: {
     evidenceId: { type: "string", description: "The evidence node ID" },
     beliefId: { type: "string", description: "The belief node ID" },
@@ -656,9 +669,18 @@ var LINK_EVIDENCE_TO_BELIEF = {
       type: "number",
       description: "Support weight: -1.0 (contradicts) to +1.0 (supports)"
     },
+    evidenceRelation: {
+      type: "string",
+      enum: ["supports", "contradicts"],
+      description: "Canonical semantic relation. If omitted, the sign of weight is used."
+    },
+    confidence: {
+      type: "number",
+      description: "Confidence in this evidence-to-belief relation, 0.0 to 1.0"
+    },
     rationale: { type: "string", description: "Why this evidence is relevant" }
   },
-  required: ["evidenceId", "beliefId", "weight"],
+  required: ["evidenceId", "beliefId"],
   response: {
     description: "The created edge linking evidence to belief",
     fields: {
@@ -676,7 +698,7 @@ var LINK_EVIDENCE_TO_BELIEF = {
 // 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)`; use modulate_confidence to record the first evidential update.",
+  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.",
   parameters: {
     canonicalText: {
       type: "string",
@@ -762,7 +784,7 @@ 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. 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. Every modulation must cite a truth-bearing artifact: triggeringEvidenceId, triggeringQuestionId, triggeringAnswerId, triggeringContradictionId, or triggeringWorktreeId. Triggers: evidence_added, evidence_removed, contradiction_detected, contradiction_resolved, agent_assessment, worktree_outcome, worktree_completed, fusion, discount, deduction.",
+  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.",
   parameters: {
     nodeId: { type: "string", description: "The belief to score" },
     belief: {
@@ -1411,6 +1433,60 @@ var REMOVE_LENS_FROM_TOPIC = {
   tier: "workhorse"
 };
 
+// src/tool-contracts.context-orientation.ts
+var LUCERN_ORIENT = {
+  name: "lucern_orient",
+  description: "Load the Lucern reasoning grammar before operating. Like `git help` plus a repository CONTRIBUTING guide for reasoning state - teaches the git-shaped model of topics, campaigns, lanes, worktrees, beliefs, questions, evidence, receipts, gates, and merges.",
+  parameters: {
+    audience: {
+      type: "string",
+      description: "Audience for the primer: agent, human, operator, or developer.",
+      enum: ["agent", "human", "operator", "developer"]
+    },
+    depth: {
+      type: "string",
+      description: "Orientation depth: quick, standard, or deep.",
+      enum: ["quick", "standard", "deep"]
+    },
+    situation: {
+      type: "string",
+      description: "Optional task or query context used to tailor suggested next calls."
+    },
+    includeExamples: {
+      type: "boolean",
+      description: "Whether to include concrete tool-call examples."
+    },
+    includeToolMap: {
+      type: "boolean",
+      description: "Whether to include situation-to-tool routing guidance."
+    },
+    includeFuture: {
+      type: "boolean",
+      description: "Whether to include future exemplar, gauntlet, and training-data capabilities."
+    }
+  },
+  required: [],
+  response: {
+    description: "Canonical operator primer for Lucern's git-shaped reasoning substrate.",
+    fields: {
+      schemaVersion: "string - lucern_orientation.v1",
+      canonicalMentalModel: "object - concise model of Lucern as git-shaped reasoning state",
+      workflow: "array - recommended branch -> investigate -> prove gate -> merge workflow",
+      grammarMap: "array - primitive-to-git-analogy map for topics, campaigns, worktrees, beliefs, questions, evidence, edges, contradictions, and gates",
+      firstMoves: "array - recommended first tools for a cold-start agent",
+      receiptRules: "array - how to interpret candidateCounts, broadening, coverageWarning, narrativeCoverage, synthesisLints, and noDefaultGlobalScan",
+      safetyRules: "array - mutation and completion rules that preserve reasoning lineage",
+      toolMap: "array | undefined - situation-to-tool routing map when requested",
+      examples: "array | undefined - concrete tool-call examples when requested",
+      futureCapabilities: "array | undefined - exemplar, gauntlet, trace-corpus, and native-model-training capabilities when requested",
+      suggestedNextCalls: "array - safe next tool calls for the current situation"
+    }
+  },
+  ownerModule: "reasoning-kernel",
+  ontologyPrimitive: "graph",
+  tier: "showcase"
+};
+
 // src/tool-contracts.ontology.ts
 var MANAGE_WRITE_POLICY = {
   name: "manage_write_policy",
@@ -3920,10 +3996,34 @@ var COMPILE_CONTEXT = {
       type: "string",
       description: "Optional source kind used as a resolver signal, such as cli, worktree, commit, or docs."
     },
+    campaign: {
+      type: "number",
+      description: "Optional campaign dimension seed. When supplied without topicId, the compiler fans out across all carrier topics for that campaign instead of resolving a single topic."
+    },
+    lane: {
+      type: "string",
+      description: "Optional lane dimension seed. When supplied without topicId, the compiler reads all matching worktrees and their carrier topics."
+    },
+    status: {
+      type: "string",
+      description: "Optional state/status dimension seed for worktrees and graph rows."
+    },
+    principalId: {
+      type: "string",
+      description: "Optional principal seed for work authored, touched, or owned by a human, agent, group, or service principal."
+    },
+    workspaceId: {
+      type: "string",
+      description: "Optional workspace seed used by hosted MCP and SDK clients when compiling tenant-scoped context."
+    },
     budget: {
       type: "number",
       description: "Token budget for prompt injection planning"
     },
+    tokenBudget: {
+      type: "number",
+      description: "Compatibility alias for budget. External MCP clients may send tokenBudget when requesting prompt injection planning."
+    },
     ranking: {
       type: "string",
       description: "Ranking profile for context ordering",
@@ -3959,7 +4059,9 @@ var COMPILE_CONTEXT = {
       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 guidance for prompt assembly",
+      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, and blocksEmitted for the narrative",
       injectionPolicy: "object \u2014 token-budgeted section selections",
       diagnostics: "object \u2014 scoring and utilization telemetry"
     }
@@ -4614,6 +4716,7 @@ var MCP_TOOL_CONTRACTS = {
   update_worktree_metadata: UPDATE_WORKTREE_METADATA,
   identity_whoami: IDENTITY_WHOAMI,
   resolve_interactive_principal: RESOLVE_INTERACTIVE_PRINCIPAL,
+  lucern_orient: LUCERN_ORIENT,
   compile_context: COMPILE_CONTEXT,
   record_scope_learning: RECORD_SCOPE_LEARNING,
   pipeline_snapshot: PIPELINE_SNAPSHOT,
@@ -4689,6 +4792,6 @@ function validateGitSemantics(tool) {
   return { valid: true };
 }
 
-export { ACTIVATE_WORKTREE, ADD_EVIDENCE, ADD_WORKTREE, ANALYZE_TOPIC_DENSITY, ANSWER_QUESTION, APPLY_AUTO_BRANCHING, APPLY_LENS_TO_TOPIC, APPLY_ONTOLOGY, ARCHIVE_BELIEF, ARCHIVE_EPISTEMIC_NODE, ARCHIVE_ONTOLOGY, ARCHIVE_QUESTION, BATCH_CREATE_EDGES, BATCH_CREATE_EPISTEMIC_NODES, BEGIN_BUILD_SESSION, BISECT_CONFIDENCE, BROADCAST_MESSAGE, CHECK_PERMISSION, CLAIM_FILES, COMPILE_CONTEXT, COMPLETE_TASK, CREATE_ANSWER, CREATE_BELIEF, CREATE_EDGE, CREATE_EPISTEMIC_CONTRACT, CREATE_EPISTEMIC_NODE, CREATE_EVIDENCE, CREATE_LENS, CREATE_ONTOLOGY, CREATE_ONTOLOGY_VERSION, CREATE_QUESTION, CREATE_TASK, CREATE_TOPIC, DEPRECATE_ONTOLOGY_VERSION, DETECT_CONFIRMATION_BIAS, DISCOVER, DISCOVER_ENTITY_CONNECTIONS, END_SESSION, EVALUATE_CONTRACT, FILTER_BY_PERMISSION, FIND_CONTRADICTIONS, FIND_MISSING_QUESTIONS, FLAG_CONTRADICTION, FORK_BELIEF, GENERATE_SESSION_HANDOFF, GET_AGENT_INBOX, GET_ANSWER, GET_AUDIT_TRAIL, GET_BELIEF, GET_CHANGE_HISTORY, GET_CODE_CONTEXT, GET_CONFIDENCE_HISTORY, GET_CONTRACT_STATUS, GET_EPISTEMIC_NODE, GET_EVIDENCE, GET_FAILURE_LOG, GET_FALSIFICATION_QUESTIONS, GET_GRAPH_GAPS, GET_GRAPH_NEIGHBORHOOD, GET_GRAPH_STRUCTURE_ANALYSIS, GET_HIGH_PRIORITY_QUESTIONS, GET_LATTICE_COVERAGE, GET_OBSERVATION_CONTEXT, GET_ONTOLOGY, GET_QUESTION, GET_TOPIC, GET_TOPIC_COVERAGE, GET_TOPIC_GRAPH_SPINE, GET_TOPIC_TREE, GET_WORKTREE, GIT_SEMANTIC_REQUIRED_TOOLS, HEARTBEAT_SESSION, IDENTITY_WHOAMI, INGEST_OBSERVATION, LINK_EVIDENCE, LINK_EVIDENCE_TO_BELIEF, LINK_EVIDENCE_TO_QUESTION, LIST_ACTIVE_SESSIONS, LIST_ALL_WORKTREES, LIST_BELIEFS, LIST_CAMPAIGNS, LIST_EPISTEMIC_NODES, LIST_EVIDENCE, LIST_GRAPH_INTELLIGENCE_QUERIES, LIST_LENSES, LIST_ONTOLOGIES, LIST_QUESTIONS, LIST_TASKS, LIST_TOPICS, LIST_WORKTREES, MANAGE_WRITE_POLICY, MATCH_ENTITY_TYPE, MATERIALIZE_TOPIC_GRAPH, MCP_TOOL_CONTRACTS, MERGE, MODULATE_CONFIDENCE, OPEN_PULL_REQUEST, PIPELINE_SNAPSHOT, PUBLISH_ONTOLOGY_VERSION, PUSH, QUERY_LINEAGE, RECORD_ATTEMPT, RECORD_JUDGMENT, RECORD_SCOPE_LEARNING, REFINE_BELIEF, REFINE_QUESTION, REGISTER_SESSION, REMOVE_EDGE, REMOVE_EDGES_BETWEEN, REMOVE_LENS_FROM_TOPIC, RESOLVE_EFFECTIVE_ONTOLOGY, RESOLVE_INTERACTIVE_PRINCIPAL, RUN_GRAPH_INTELLIGENCE_QUERY, SEARCH_BELIEFS, SEARCH_EVIDENCE, SEED_BELIEF_LATTICE, SEND_AGENT_MESSAGE, SUPERSEDE_EPISTEMIC_NODE, TRACE_ENTITY_IMPACT, TRAVERSE_GRAPH, TRIGGER_BELIEF_REVIEW, UPDATE_EDGE, UPDATE_EPISTEMIC_NODE, UPDATE_ONTOLOGY, UPDATE_QUESTION_STATUS, UPDATE_TASK, UPDATE_TOPIC, UPDATE_WORKTREE_METADATA, UPDATE_WORKTREE_TARGETS, VERIFY_EPISTEMIC_NODE, validateGitSemantics };
+export { ACTIVATE_WORKTREE, ADD_EVIDENCE, ADD_WORKTREE, ANALYZE_TOPIC_DENSITY, ANSWER_QUESTION, APPLY_AUTO_BRANCHING, APPLY_LENS_TO_TOPIC, APPLY_ONTOLOGY, ARCHIVE_BELIEF, ARCHIVE_EPISTEMIC_NODE, ARCHIVE_ONTOLOGY, ARCHIVE_QUESTION, BATCH_CREATE_EDGES, BATCH_CREATE_EPISTEMIC_NODES, BEGIN_BUILD_SESSION, BISECT_CONFIDENCE, BROADCAST_MESSAGE, CHECK_PERMISSION, CLAIM_FILES, COMPILE_CONTEXT, COMPLETE_TASK, CREATE_ANSWER, CREATE_BELIEF, CREATE_EDGE, CREATE_EPISTEMIC_CONTRACT, CREATE_EPISTEMIC_NODE, CREATE_EVIDENCE, CREATE_LENS, CREATE_ONTOLOGY, CREATE_ONTOLOGY_VERSION, CREATE_QUESTION, CREATE_TASK, CREATE_TOPIC, DEPRECATE_ONTOLOGY_VERSION, DETECT_CONFIRMATION_BIAS, DISCOVER, DISCOVER_ENTITY_CONNECTIONS, END_SESSION, EVALUATE_CONTRACT, FILTER_BY_PERMISSION, FIND_CONTRADICTIONS, FIND_MISSING_QUESTIONS, FLAG_CONTRADICTION, FORK_BELIEF, GENERATE_SESSION_HANDOFF, GET_AGENT_INBOX, GET_ANSWER, GET_AUDIT_TRAIL, GET_BELIEF, GET_CHANGE_HISTORY, GET_CODE_CONTEXT, GET_CONFIDENCE_HISTORY, GET_CONTRACT_STATUS, GET_EPISTEMIC_NODE, GET_EVIDENCE, GET_FAILURE_LOG, GET_FALSIFICATION_QUESTIONS, GET_GRAPH_GAPS, GET_GRAPH_NEIGHBORHOOD, GET_GRAPH_STRUCTURE_ANALYSIS, GET_HIGH_PRIORITY_QUESTIONS, GET_LATTICE_COVERAGE, GET_OBSERVATION_CONTEXT, GET_ONTOLOGY, GET_QUESTION, GET_TOPIC, GET_TOPIC_COVERAGE, GET_TOPIC_GRAPH_SPINE, GET_TOPIC_TREE, GET_WORKTREE, GIT_SEMANTIC_REQUIRED_TOOLS, HEARTBEAT_SESSION, IDENTITY_WHOAMI, INGEST_OBSERVATION, LINK_EVIDENCE, LINK_EVIDENCE_TO_BELIEF, LINK_EVIDENCE_TO_QUESTION, LIST_ACTIVE_SESSIONS, LIST_ALL_WORKTREES, LIST_BELIEFS, LIST_CAMPAIGNS, LIST_EPISTEMIC_NODES, LIST_EVIDENCE, LIST_GRAPH_INTELLIGENCE_QUERIES, LIST_LENSES, LIST_ONTOLOGIES, LIST_QUESTIONS, LIST_TASKS, LIST_TOPICS, LIST_WORKTREES, LUCERN_ORIENT, MANAGE_WRITE_POLICY, MATCH_ENTITY_TYPE, MATERIALIZE_TOPIC_GRAPH, MCP_TOOL_CONTRACTS, MERGE, MODULATE_CONFIDENCE, OPEN_PULL_REQUEST, PIPELINE_SNAPSHOT, PUBLISH_ONTOLOGY_VERSION, PUSH, QUERY_LINEAGE, RECORD_ATTEMPT, RECORD_JUDGMENT, RECORD_SCOPE_LEARNING, REFINE_BELIEF, REFINE_QUESTION, REGISTER_SESSION, REMOVE_EDGE, REMOVE_EDGES_BETWEEN, REMOVE_LENS_FROM_TOPIC, RESOLVE_EFFECTIVE_ONTOLOGY, RESOLVE_INTERACTIVE_PRINCIPAL, RUN_GRAPH_INTELLIGENCE_QUERY, SEARCH_BELIEFS, SEARCH_EVIDENCE, SEED_BELIEF_LATTICE, SEND_AGENT_MESSAGE, SUPERSEDE_EPISTEMIC_NODE, TRACE_ENTITY_IMPACT, TRAVERSE_GRAPH, TRIGGER_BELIEF_REVIEW, UPDATE_EDGE, UPDATE_EPISTEMIC_NODE, UPDATE_ONTOLOGY, UPDATE_QUESTION_STATUS, UPDATE_TASK, UPDATE_TOPIC, UPDATE_WORKTREE_METADATA, UPDATE_WORKTREE_TARGETS, VERIFY_EPISTEMIC_NODE, validateGitSemantics };
 //# sourceMappingURL=tool-contracts.values.js.map
 //# sourceMappingURL=tool-contracts.values.js.map