docs(FN-4223): complete Step 3 — clarify research confidence and run semantics in JSDoc

Fusion-Task-Id: FN-4223
Fusion-Task-Lineage: bc114ff2-ee0f-4e96-b1d2-6ba3112a48e4

packages/core/src/research-types.ts

@@ -126,6 +126,10 @@ export interface ResearchFinding {
   heading: string;
   content: string;
   sources: string[];
+  /**
+   * Synthesis-emitted confidence in [0,1] from the LLM response.
+   * NOT a statistical MAD confidence score.
+   */
   confidence?: number;
 }
 
@@ -143,6 +147,11 @@ export interface ResearchTokenUsage {
   totalTokens?: number;
 }
 
+/**
+ * A cited-search/synthesis run persisted by Fusion Research.
+ * Not an upstream pi-autoresearch experiment session.
+ * See docs/research/naming-decision-2026-05.md.
+ */
 export interface ResearchRun {
   id: string;
   query: string;
@@ -305,7 +314,15 @@ export interface ResearchModelSettings {
 
 export interface ResearchOrchestrationConfig {
   providers: ResearchOrchestrationProvider[];
+  /**
+   * Bounds source fan-out within a single cited-research run.
+   * NOT an experiment-iteration cap.
+   */
   maxSources: number;
+  /**
+   * Bounds synthesis passes within a single cited-research run.
+   * NOT an experiment-iteration cap.
+   */
   maxSynthesisRounds: number;
   phaseTimeoutMs?: number;
   stepTimeoutMs?: number;

packages/engine/src/research/providers/llm-synthesis-provider.ts

@@ -200,6 +200,11 @@ function extractCitations(text: string, sources: ResearchSource[]): string[] {
   return [...refs];
 }
 
+/**
+ * Extracts synthesis-emitted confidence (0-1) from model output.
+ * This is an LLM-provided signal for cited-research synthesis,
+ * not a statistical MAD confidence metric.
+ */
 function extractConfidence(text: string): number | undefined {
   const jsonBlock = text.match(/```(?:json)?\s*([\s\S]*?)```/i)?.[1] ?? text;
   try {