@lucern/contracts 1.0.12 → 1.0.14

package/dist/function-registry/evidence.js

@@ -6,7 +6,7 @@ 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)`; 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",
@@ -92,7 +92,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: {
@@ -1700,10 +1700,11 @@ var LUCERN_ORIENT = {
       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, and noDefaultGlobalScan",
+      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"
     }
   },
@@ -1866,7 +1867,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" },
@@ -1877,7 +1878,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",
@@ -1987,7 +2001,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" },
@@ -1995,9 +2009,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: {
@@ -2825,7 +2848,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"
     }
@@ -4773,6 +4798,12 @@ var internalSystem = {
   mcp: "internal",
   cli: "internal"
 };
+var internalSdkRestOnly = {
+  sdk: "internal",
+  rest: "internal",
+  mcp: "none",
+  cli: "none"
+};
 var publicWithInternalMcp = {
   sdk: "public",
   rest: "public",
@@ -4822,7 +4853,6 @@ var MCP_CORE_OPERATION_NAMES = [
   "get_belief",
   "list_beliefs",
   "refine_belief",
-  "modulate_confidence",
   "fork_belief",
   "archive_belief",
   "search_beliefs",
@@ -5090,6 +5120,13 @@ var LUCERN_OPERATION_MANIFEST = {
     internalSystem,
     "Lucern system/background operation. Available to platform code paths, hidden from public MCP discovery."
   ),
+  modulate_confidence: {
+    name: "modulate_confidence",
+    surfaceClass: "platform_internal",
+    surfaceIntent: "system",
+    surfaces: internalSdkRestOnly,
+    rationale: "Internal SL ledger append primitive. Public callers attach evidence or contradiction relations; confidence is derived algorithmically."
+  },
   ...entries(
     LEGACY_COMPAT_OPERATION_NAMES,
     "legacy_compat",
@@ -5429,6 +5466,23 @@ function defineProjection(def) {
 
 // src/projections/create-evidence.projection.ts
 var jsonRecordSchema = z.record(z.unknown());
+var evidenceRelationSchema = z.enum(["supports", "contradicts"]);
+var evidenceRelationAliasSchema = z.enum([
+  "supports",
+  "contradicts",
+  "supporting",
+  "contradicting"
+]);
+var beliefRelationSchema = z.object({
+  beliefId: z.string().optional(),
+  beliefNodeId: z.string().optional(),
+  targetId: z.string().optional(),
+  relation: evidenceRelationAliasSchema.optional(),
+  evidenceRelation: evidenceRelationSchema.optional(),
+  confidence: z.number().optional(),
+  weight: z.number().optional(),
+  rationale: z.string().optional()
+});
 var createEvidenceInputSchemaBase = z.object({
   projectId: z.string().optional(),
   topicId: z.string().optional(),
@@ -5450,7 +5504,8 @@ var createEvidenceInputSchemaBase = z.object({
   targetId: z.string().optional(),
   targetNodeId: z.string().optional(),
   linkedBeliefNodeId: z.string().optional(),
-  evidenceRelation: z.enum(["supports", "contradicts"]).optional(),
+  evidenceRelation: evidenceRelationSchema.optional(),
+  beliefRelations: z.array(beliefRelationSchema).optional(),
   confidence: z.number().optional(),
   weight: z.number().optional(),
   reasoning: z.string().optional(),
@@ -5458,11 +5513,55 @@ var createEvidenceInputSchemaBase = z.object({
   metadata: jsonRecordSchema.optional(),
   trustedBypassAccessCheck: z.boolean().optional()
 }).passthrough();
-var createEvidenceInputSchema = createEvidenceInputSchemaBase.refine(
-  (input) => Boolean(input.text ?? input.canonicalText),
-  {
-    message: "create_evidence requires text",
-    path: ["text"]
+function hasNonzeroWeight(value) {
+  return typeof value === "number" && Number.isFinite(value) && value !== 0;
+}
+function hasRelationSignal(value, weight) {
+  return Boolean(normalizeRelation(value, weight));
+}
+var createEvidenceInputSchema = createEvidenceInputSchemaBase.superRefine(
+  (input, ctx) => {
+    if (!input.text && !input.canonicalText) {
+      ctx.addIssue({
+        code: z.ZodIssueCode.custom,
+        message: "create_evidence requires text",
+        path: ["text"]
+      });
+    }
+    const target = input.targetId ?? input.targetNodeId;
+    const kind = targetKind(target);
+    const linksPrimaryBelief = Boolean(
+      input.linkedBeliefNodeId || kind === "belief" || kind === "unknown" && target
+    );
+    const weight = typeof input.weight === "number" ? input.weight : void 0;
+    if (linksPrimaryBelief && !hasRelationSignal(input.evidenceRelation, weight)) {
+      ctx.addIssue({
+        code: z.ZodIssueCode.custom,
+        message: "belief-targeted evidence requires evidenceRelation='supports'|'contradicts' or a nonzero signed weight",
+        path: ["evidenceRelation"]
+      });
+    }
+    input.beliefRelations?.forEach((relation, index) => {
+      const beliefNodeId = relation.beliefNodeId ?? relation.beliefId ?? relation.targetId;
+      if (!beliefNodeId) {
+        ctx.addIssue({
+          code: z.ZodIssueCode.custom,
+          message: "beliefRelations entries require beliefId, beliefNodeId, or targetId",
+          path: ["beliefRelations", index, "beliefNodeId"]
+        });
+      }
+      const relationWeight2 = typeof relation.weight === "number" ? relation.weight : void 0;
+      if (beliefNodeId && !hasRelationSignal(
+        relation.evidenceRelation ?? relation.relation,
+        relationWeight2
+      )) {
+        ctx.addIssue({
+          code: z.ZodIssueCode.custom,
+          message: "beliefRelations entries require evidenceRelation='supports'|'contradicts' or a nonzero signed weight",
+          path: ["beliefRelations", index, "evidenceRelation"]
+        });
+      }
+    });
   }
 );
 function compactRecord2(input) {
@@ -5514,6 +5613,47 @@ function targetKind(targetId) {
   }
   return "unknown";
 }
+function normalizeRelation(value, weight) {
+  if (value === "supports" || value === "supporting") {
+    return "supports";
+  }
+  if (value === "contradicts" || value === "contradicting") {
+    return "contradicts";
+  }
+  if (weight === void 0 || !hasNonzeroWeight(weight)) {
+    return void 0;
+  }
+  return weight < 0 ? "contradicts" : "supports";
+}
+function normalizeConfidence(confidence, weight) {
+  if (confidence !== void 0) {
+    return Math.min(1, Math.max(0, confidence));
+  }
+  if (weight === void 0) {
+    return void 0;
+  }
+  return Math.min(1, Math.max(0, Math.abs(weight)));
+}
+function normalizeBeliefRelation(relation) {
+  const beliefNodeId = relation.beliefNodeId ?? relation.beliefId ?? relation.targetId;
+  if (!beliefNodeId) {
+    return void 0;
+  }
+  const weight = typeof relation.weight === "number" ? relation.weight : void 0;
+  const evidenceRelation = normalizeRelation(
+    relation.evidenceRelation ?? relation.relation,
+    weight
+  );
+  if (!evidenceRelation) {
+    return void 0;
+  }
+  return compactRecord2({
+    beliefNodeId,
+    relation: evidenceRelation,
+    confidence: normalizeConfidence(relation.confidence, weight),
+    rationale: relation.rationale
+  });
+}
 var createEvidenceProjection = defineProjection({
   contractName: "create_evidence",
   inputSchema: createEvidenceInputSchema,
@@ -5524,6 +5664,11 @@ var createEvidenceProjection = defineProjection({
     const kind = targetKind(target);
     const linkedWorktreeId = kind === "worktree" ? normalizeWorktreeId(target) : void 0;
     const linkedBeliefNodeId = input.linkedBeliefNodeId ?? (kind === "belief" || kind === "unknown" ? input.targetNodeId ?? input.targetId : void 0);
+    const evidenceRelation = linkedBeliefNodeId ? normalizeRelation(input.evidenceRelation, weight) : void 0;
+    const confidence = evidenceRelation ? normalizeConfidence(input.confidence, weight) : void 0;
+    const beliefRelations = input.beliefRelations?.map(normalizeBeliefRelation).filter(
+      (relation) => relation !== void 0
+    );
     return compactRecord2({
       projectId: input.projectId,
       topicId: normalizeTopicIdForKernel(input.topicId),
@@ -5552,8 +5697,9 @@ var createEvidenceProjection = defineProjection({
         rationale: input.rationale
       }),
       linkedBeliefNodeId,
-      evidenceRelation: input.evidenceRelation ?? (weight === void 0 ? void 0 : weight < 0 ? "contradicts" : "supports"),
-      confidence: input.confidence ?? (weight === void 0 ? void 0 : Math.min(1, Math.max(0, Math.abs(weight)))),
+      evidenceRelation,
+      confidence,
+      beliefRelations: beliefRelations && beliefRelations.length > 0 ? beliefRelations : void 0,
       rationale: input.rationale,
       trustedBypassAccessCheck: input.trustedBypassAccessCheck ?? true
     });
@@ -5582,23 +5728,50 @@ var createEvidenceProjection = defineProjection({
         v.literal("contradicts")
       )
     ),
+    beliefRelations: v.optional(
+      v.array(
+        v.object({
+          beliefNodeId: v.string(),
+          relation: v.union(v.literal("supports"), v.literal("contradicts")),
+          confidence: v.optional(v.number()),
+          rationale: v.optional(v.string())
+        })
+      )
+    ),
     confidence: v.optional(v.number()),
     rationale: v.string(),
     trustedBypassAccessCheck: v.optional(v.boolean())
   })
 });
 var jsonRecordSchema2 = z.record(z.unknown());
-var evidenceRelationSchema = z.enum(["supports", "contradicts"]);
+var evidenceRelationSchema2 = z.enum(["supports", "contradicts"]);
+var beliefRelationSchema2 = z.object({
+  beliefId: z.string().optional().describe("Belief ID this evidence bears on."),
+  beliefNodeId: z.string().optional().describe("Belief node ID this evidence bears on."),
+  targetId: z.string().optional().describe("Belief target ID alias for beliefId/beliefNodeId."),
+  relation: z.enum(["supports", "contradicts", "supporting", "contradicting"]).optional().describe("Relation alias for how the evidence bears on the belief."),
+  evidenceRelation: evidenceRelationSchema2.optional().describe("Canonical relation: supports or contradicts."),
+  confidence: z.number().optional().describe("Confidence in this evidence-to-belief relation."),
+  weight: z.number().optional().describe("Support weight from -1.0 to +1.0 for this belief."),
+  rationale: z.string().optional().describe("Why this relation exists.")
+});
 var createEvidenceArgs = z.object({
   topicId: z.string().optional().describe("Topic scope for the evidence."),
   text: z.string().describe("Canonical evidence text."),
   source: z.string().optional().describe("Source URL or source label."),
   sourceUrl: z.string().optional().describe("Canonical source URL."),
-  targetId: z.string().optional().describe("Belief, question, or worktree identifier to link or preserve on the evidence record."),
+  targetId: z.string().optional().describe(
+    "Belief, question, or worktree identifier to link or preserve on the evidence record. Belief targets require evidenceRelation or a nonzero signed weight."
+  ),
   linkedBeliefNodeId: z.string().optional().describe("Belief node this evidence bears on."),
-  evidenceRelation: evidenceRelationSchema.optional().describe("How the evidence relates to the linked belief."),
+  evidenceRelation: evidenceRelationSchema2.optional().describe(
+    "How the evidence relates to the linked belief. Use supports for proof/fixes; use contradicts for bugs, regressions, or falsifying observations."
+  ),
+  beliefRelations: z.array(beliefRelationSchema2).optional().describe(
+    "Additional belief relations for one evidence record. Use when the same evidence supports or contradicts multiple beliefs."
+  ),
   confidence: z.number().optional().describe("Confidence in the evidence relation."),
-  weight: z.number().optional().describe("Support weight from -1.0 to +1.0."),
+  weight: z.number().optional().describe("Nonzero support weight from -1.0 to +1.0."),
   metadata: jsonRecordSchema2.optional().describe("Metadata merged into the canonical evidence node."),
   rationale: z.string().describe("Why this evidence should enter the reasoning graph."),
   reasoning: z.string().optional().describe("Reasoning note preserved in evidence metadata."),
@@ -5639,6 +5812,35 @@ var createEvidenceInput = (input, context) => {
     context
   );
 };
+function relationWeight(input) {
+  if (typeof input.weight === "number" && Number.isFinite(input.weight) && input.weight !== 0) {
+    return input.weight;
+  }
+  const relation = String(
+    input.evidenceRelation ?? input.relation ?? input.type ?? ""
+  );
+  if (relation !== "supports" && relation !== "supporting" && relation !== "contradicts" && relation !== "contradicting") {
+    throw new Error(
+      "Belief evidence links require evidenceRelation='supports'|'contradicts' or a nonzero signed weight."
+    );
+  }
+  const confidence = typeof input.confidence === "number" ? Math.max(0, Math.min(1, input.confidence)) : 0.7;
+  return relation === "contradicts" || relation === "contradicting" ? -confidence : confidence;
+}
+var linkEvidenceToBeliefInput = (input, context) => {
+  const weight = relationWeight(input);
+  return withUserId(
+    compactRecord({
+      beliefNodeId: input.beliefNodeId ?? input.beliefId ?? input.targetId,
+      insightId: input.insightId ?? input.evidenceNodeId ?? input.evidenceId,
+      type: weight < 0 ? "contradicting" : "supporting",
+      confidence: Math.min(1, Math.abs(weight)),
+      rationale: input.rationale ?? input.context,
+      trustedBypassAccessCheck: input.trustedBypassAccessCheck ?? true
+    }),
+    context
+  );
+};
 var linkEvidenceToBeliefEdgeInput = (input, context) => withCreatedBy(
   compactRecord({
     fromNodeId: input.insightId ?? input.evidenceNodeId ?? input.evidenceId,
@@ -5649,7 +5851,7 @@ var linkEvidenceToBeliefEdgeInput = (input, context) => withCreatedBy(
     )}:${String(
       input.beliefNodeId ?? input.beliefId ?? input.targetId
     )}:informs`,
-    weight: typeof input.weight === "number" ? input.weight : input.type === "contradicting" ? -1 : 1,
+    weight: relationWeight(input),
     context: input.rationale ?? input.context,
     skipLayerValidation: true,
     topicId: input.topicId,
@@ -5781,10 +5983,10 @@ var evidenceContracts = [
     sdkMethod: "linkEvidenceToBelief",
     summary: "Link evidence to a belief.",
     convex: {
-      module: "edges",
-      functionName: "create",
+      module: "beliefs",
+      functionName: "linkEvidence",
       kind: "mutation",
-      inputProjection: linkEvidenceToBeliefEdgeInput
+      inputProjection: linkEvidenceToBeliefInput
     }
   }),
   surfaceContract({