@knights-eye-chess/ai-analysis 0.0.0-stage → 0.1.0-dev.14

package/src/chess-reasoning/answer-pipeline.ts

@@ -0,0 +1,195 @@
+import { classificationTargetAtSelection } from './classification-question-target';
+import { DEFAULT_BRANCH_EXPANSION_MODE, BRANCH_EXPANSION_OPTIONS, withBranchPreparation, selectBranchHost } from './branch-expansion-policy';
+import { planInitialSearches } from './initial-search-plan';
+import { withRecordedPositionTools, memoizeToolResults } from './recorded-position-tools';
+import type { AnswerRoutingPreparation, AnswerSelection, AnswerHistoryPort, AnswerOpeningSession } from './answer-host-contracts';
+import { prepareOpponentThreats } from "./opponent-threat-preparation";
+import { simpleBoardAnalysis } from "./simple-board-analysis";
+import { createContextEvidence, REASONING_POC_VERSION, reasoningContextHash, createQueryContract, DEFAULT_REASONING_RUN_CONTROLS } from "./poc-contracts";
+import type { PriorConversationMessage } from "./conversation-context";
+import type { SimpleAgentConfig } from "./simple-agent-config";
+import { captureAblationOriginalEvidenceBundle } from "./ablation-evidence-capture";
+import { toLegacyPositionAnalysisProvider, type CompatiblePositionAnalysisProvider } from "./position-analysis-contracts";
+import type { ObservationProvider } from "./poc-contracts";
+import type { AnswerModelConnector } from "./answer-model-connector";
+import type { WikibooksIndex } from "./wikibooks-index";
+import { emitObservableTrace, type ObservableLlmTraceSink } from "./ai-sdk-runtime-support";
+import { createDefaultSaliencePolicy } from "./poc-observations";
+import { createPocToolHost } from "./poc-tools";
+import { runPreparedAnswer, SIMPLE_MODELS, SIMPLE_BUDGETS, SIMPLE_EXPANDED_BUDGETS, SIMPLE_RECOVERY_BUDGETS } from "./portable-answer-runtime";
+import type { PlayerPerspective } from "../player-perspective";
+
+export type AnswerPipelineResult = Awaited<ReturnType<typeof runPreparedAnswer>> & { arm: "Simple"; bundleHash: string };
+
+export async function runAnswerPipeline(input: {
+  connector: AnswerModelConnector;
+  policy?: Parameters<typeof runPreparedAnswer>[0]["policy"];
+  modelName?: string;
+  providerRoute?: string;
+  analyzer?: CompatiblePositionAnalysisProvider;
+  /** Optional analyzer for ordinary opponent preparation; later model tools still use analyzer. */
+  preparationAnalyzer?: CompatiblePositionAnalysisProvider;
+  /** Opt in only when the host can safely serve overlapping preparation and classification searches. */
+  parallelPreparation?: boolean;
+  observationProvider: ObservationProvider;
+  prepareRouting: () => Promise<AnswerRoutingPreparation>;
+  openingSession?: AnswerOpeningSession;
+  openingIndex?: () => Promise<WikibooksIndex>;
+  routingPreparation?: AnswerRoutingPreparation;
+  conversationHistory?: readonly PriorConversationMessage[];
+  simpleConfig?: SimpleAgentConfig;
+  simpleAllowance?: "default" | "expanded" | "glm-recovery";
+  requestId: string;
+  question: string;
+  playerPerspective?: PlayerPerspective | null;
+  selected: AnswerSelection;
+  bridge?: AnswerHistoryPort;
+  signal?: AbortSignal;
+  observableTraceSink?: ObservableLlmTraceSink;
+  onProgress?: (message: string) => void;
+}): Promise<AnswerPipelineResult> {
+  const parentSignal = input.signal;
+  const controller = new AbortController();
+  const abort = () => controller.abort(parentSignal?.reason);
+  if (parentSignal?.aborted) abort(); else parentSignal?.addEventListener("abort", abort, { once: true });
+  // Only explicit cancellation aborts; the native loop owns soft completion.
+  input = { ...input, signal: controller.signal };
+  let sourceTimer: ReturnType<typeof setTimeout> | undefined;
+  try {
+    const preparationStarted = performance.now();
+    let phaseSequence = 0;
+    // Paired phase events measure work before the model loop. They do not carry
+    // chess payloads or errors that might contain host transport credentials.
+    const timed = async <T>(stage: string, operation: () => T | Promise<T>, details: Record<string, unknown> = {}, phaseSignal = input.signal): Promise<T> => {
+      const started = performance.now();
+      const invocationId = `${input.requestId}:pipeline-phase:${++phaseSequence}`;
+      const trace = (direction: "input" | "output" | "error", payload: Record<string, unknown>) => emitObservableTrace(input.observableTraceSink, {
+        stage, direction, model: "deterministic", providerRoute: "local-harness", reasoningEffort: "none",
+        payload: { invocationId, ...details, ...payload, elapsedMs: performance.now() - preparationStarted },
+      });
+      trace("input", {});
+      try {
+        const result = await operation();
+        trace("output", { status: "completed", durationMs: performance.now() - started });
+        return result;
+      } catch (error) {
+        trace("error", { status: phaseSignal?.aborted ? "cancelled" : "failed", durationMs: performance.now() - started });
+        throw error;
+      }
+    };
+    const routing = input.routingPreparation ?? await timed("answer-pipeline-routing", input.prepareRouting);
+    if(routing.question!==input.question||routing.selectionKey!==input.selected.selectionKey||routing.deliveryId!==input.selected.deliveryId)throw Error('stale-question-routing');
+    const omitSelectedContext=routing.omitSelectedContext;
+    if(input.signal?.aborted)throw input.signal.reason??Error('cancelled');
+    // Public MediaWiki traffic must never pass through the credentialed model relay.
+    const openingSession = input.openingSession;
+    const allowance = input.simpleAllowance === 'glm-recovery' ? SIMPLE_RECOVERY_BUDGETS
+      : input.simpleAllowance === 'expanded' ? SIMPLE_EXPANDED_BUDGETS : SIMPLE_BUDGETS;
+    const sourceDeadlineMs = Math.max(0, allowance.maxWallTimeMs - 60000);
+    let sourceTimedOut = false;
+    const sourceController = new AbortController();
+    const sourceSignal = AbortSignal.any([controller.signal, sourceController.signal]);
+    const prepareGameOpening = routing.decision.reviewGame && routing.mainLine;
+    const openingLookup = (prepareGameOpening || !omitSelectedContext) && openingSession ? (() => {
+      sourceTimer = setTimeout(() => { sourceTimedOut = true; sourceController.abort(); },
+        Math.max(0, sourceDeadlineMs - (input.routingPreparation?.elapsedMs ?? 0) - (performance.now() - preparationStarted)));
+      return (async () => {
+        const results = await Promise.all([
+          ...(prepareGameOpening ? [openingSession.gameReview(prepareGameOpening, sourceSignal)] : []),
+          ...(!omitSelectedContext ? [openingSession.initial(sourceSignal)] : []),
+        ]);
+        const pages = [...new Map(results.flatMap(result => result.pages).map(page => [`${page.title}@${page.revisionId}`, page])).values()];
+        return {...results[0], status:pages.length ? 'available' as const : results[0].status, pages,
+          requestCount:results.reduce((count, result) => count + result.requestCount, 0),
+          localIndexCandidateCount:results.reduce((count, result) => count + result.localIndexCandidateCount, 0),
+          localIndexPositionCheckCount:results.reduce((count, result) => count + result.localIndexPositionCheckCount, 0),
+          localIndexSelectedTitleCount:results.reduce((count, result) => count + result.localIndexSelectedTitleCount, 0),
+          cacheHitTitleCount:results.reduce((count, result) => count + result.cacheHitTitleCount, 0),
+          networkRequestCount:results.reduce((count, result) => count + result.networkRequestCount, 0),
+          networkRequestedTitles:results.flatMap(result => result.networkRequestedTitles),
+          timingMs:Math.max(...results.map(result => result.timingMs)),
+          limitations:[...new Set(results.flatMap(result => result.limitations))]};
+      })().finally(() => clearTimeout(sourceTimer));
+    })() : undefined;
+    const analyzer = input.analyzer ? toLegacyPositionAnalysisProvider(input.analyzer) : undefined;
+    const preparationAnalyzer = input.preparationAnalyzer ? toLegacyPositionAnalysisProvider(input.preparationAnalyzer) : analyzer;
+    const baseSearchPlan = planInitialSearches({question:input.question,context:input.selected.context,mainLine:routing.mainLine,reviewGame:routing.decision.reviewGame,reviewSubject:routing.decision.reviewSubject,answerScope:routing.decision.answers?.answer_scope?.choice,classificationQuestion:classificationTargetAtSelection(routing.decision,input.question,input.selected.context).applies,omitSelectedContext,playerPerspective:input.playerPerspective});
+    // Capture the selected chess context before refresh can replace host analysis.
+    // Classification refresh changes existingAnalysis, not the selected position.
+    const selectedContext = input.selected.context;
+    const prepare = preparationAnalyzer && !omitSelectedContext && !baseSearchPlan.requests.length
+      ? () => timed("answer-pipeline-preparation", () => prepareOpponentThreats(selectedContext, preparationAnalyzer, input.signal, input.onProgress, { parallel: input.parallelPreparation })) : undefined;
+    const refresh = () => timed("answer-pipeline-classification-refresh", () => input.bridge!.refreshContext!(input.selected, input.signal), { origin: "opponent-threat-preparation" });
+    let preparation: Awaited<ReturnType<typeof prepareOpponentThreats>>;
+    let refreshed: Awaited<ReturnType<NonNullable<AnswerHistoryPort["refreshContext"]>>> | undefined;
+    if (input.parallelPreparation && prepare && selectedContext.kind !== "position" && input.bridge?.refreshContext) {
+      input.onProgress?.("Refreshing move classification and candidate moves");
+      const preparationWork = prepare();
+      const classificationWork = refresh();
+      try {
+        [preparation, refreshed] = await Promise.all([preparationWork, classificationWork]);
+        input.signal?.throwIfAborted();
+      } catch (error) {
+        // Abort and drain the sibling before the host tears down answer resources.
+        // Promise.all observes both rejections; preserve the first operation's error.
+        controller.abort(error);
+        await Promise.allSettled([preparationWork, classificationWork]);
+        throw error;
+      }
+    } else {
+      preparation = prepare ? await prepare() : undefined;
+      input.onProgress?.("Refreshing move classification and candidate moves");
+      refreshed = preparation && input.bridge?.refreshContext ? await refresh() : undefined;
+    }
+    const initialSearchPlan=withBranchPreparation(baseSearchPlan,input.selected.context,omitSelectedContext,DEFAULT_BRANCH_EXPANSION_MODE);
+    // Never reuse a pre-search snapshot when no refresh capability is available.
+    const existingAnalysis = refreshed?.existingAnalysis ?? (preparation ? null : input.selected.existingAnalysis);
+    input.onProgress?.("Collecting compact chess evidence");
+    // Include attributed current board context; never include future recorded play.
+    const { boardAnalysis, observations } = await timed("answer-pipeline-observations", async () => {
+      const boardAnalysis = simpleBoardAnalysis(input.selected.context, existingAnalysis, input.selected.edgeId);
+      const provider = input.observationProvider;
+      const observations = input.selected.context.kind === "position" ? { schemaVersion: REASONING_POC_VERSION, contextHash: reasoningContextHash(input.selected.context), observations: [], evidence: [createContextEvidence(input.selected.context)], providers: [{ provider: "validated-starting-position", version: "1" }], limitations: [] } : await provider.observe(input.selected.context, DEFAULT_REASONING_RUN_CONTROLS, input.signal);
+      return { boardAnalysis, observations };
+    });
+    const { bundle, hostOptions, expandedOptions, host, getMainLine } = await timed("answer-pipeline-evidence-collection", () => {
+      const contract = createQueryContract({ requestId: input.requestId, question: input.question, context: input.selected.context });
+      const rankedObservations = createDefaultSaliencePolicy(DEFAULT_REASONING_RUN_CONTROLS.maxObservationsPresented).rank(observations, contract);
+      const bundle = captureAblationOriginalEvidenceBundle({ context: input.selected.context, question: input.question,
+        observations, rankedObservations, retainAllExactFacts: true });
+      const hostOptions = { ...(analyzer ? { analyzer } : {}), defaultDepth:18, minimumDepth:18, maxDepth:18, maxRootMoves:6, leadingAlternative:boardAnalysis?.leadingAlternative };
+      const baseHost = createPocToolHost(input.selected.context, hostOptions);
+      const expandedOptions={...hostOptions,branchExpansion:BRANCH_EXPANSION_OPTIONS};
+      const expandedHost=createPocToolHost(input.selected.context,expandedOptions);
+      // Freeze one validated record per answer; later navigation cannot replace it.
+      let mainLine = routing.mainLine;
+      const getMainLine = async (signal?:AbortSignal) => mainLine ?? (mainLine = await input.bridge!.getMainLine!(input.selected,signal));
+      const ordinaryHost = (initialSearchPlan && (mainLine || input.bridge?.getMainLine)
+        ? withRecordedPositionTools(input.selected.context,baseHost,hostOptions,getMainLine) : baseHost);
+      const expandedRecordedHost=initialSearchPlan && (mainLine || input.bridge?.getMainLine)
+        ? withRecordedPositionTools(input.selected.context,expandedHost,expandedOptions,getMainLine) : expandedHost;
+      const host=selectBranchHost(memoizeToolResults(ordinaryHost),memoizeToolResults(expandedRecordedHost),DEFAULT_BRANCH_EXPANSION_MODE);
+      return { bundle, hostOptions, expandedOptions, host, getMainLine };
+    });
+    const openingSourceContext = openingLookup ? await timed("answer-pipeline-opening-wait", () => openingLookup) : undefined;
+    const preModelElapsedMs = Math.max(sourceTimedOut ? sourceDeadlineMs : 0, performance.now() - preparationStarted + (input.routingPreparation?.elapsedMs??0));
+    const result = await runPreparedAnswer({ ...input, bundle, host, boardAnalysis, preparation, openingSourceContext, initialSearchPlan,
+      refreshPreparedBoardAnalysis: async signal => {
+        hostOptions.leadingAlternative=undefined;
+        expandedOptions.leadingAlternative=undefined;
+        const fresh=input.bridge?.refreshContext
+          ? await timed("answer-pipeline-classification-refresh", () => input.bridge!.refreshContext!(input.selected,signal), { origin: "initial-search-preparation" }, signal) : undefined;
+        const analysis=simpleBoardAnalysis(input.selected.context,fresh?.existingAnalysis??null,input.selected.edgeId);
+        hostOptions.leadingAlternative=analysis?.leadingAlternative;
+        expandedOptions.leadingAlternative=analysis?.leadingAlternative;
+        return analysis;
+      },
+      omitSelectedContext, initialMainLine:routing.mainLine, routingDecision:routing.decision, openingSourceLookup: openingSession ? (targets, signal, root) => openingSession.lookup(targets, signal, root) : undefined, preModelElapsedMs, analysisDepth: 18,
+      getMainLine: input.bridge?.getMainLine ? signal => getMainLine(signal) : undefined,
+      modelName: input.modelName ?? input.simpleConfig?.modelId ?? SIMPLE_MODELS["Simple-Sol"], effort: input.simpleConfig?.effort ?? "medium" });
+    return { ...result, arm: "Simple", bundleHash: bundle.bundleHash };
+  } finally {
+    clearTimeout(sourceTimer);
+    parentSignal?.removeEventListener("abort", abort);
+  }
+}

package/src/chess-reasoning/answer-reference-validation.ts

@@ -0,0 +1,124 @@
+import { checkCausalClaims } from './causal-claim-checks';
+import { normalizedEvidenceCitations } from './evidence-citation-normalization';
+import { reasoningContextHash } from './poc-contracts';
+import { Chess } from 'chess.js';
+import { historicalProseRoots } from './historical-prose';
+import { simpleProseReferences, SIMPLE_REFERENCE_VERSION } from './simple-prose-references';
+import { MAX_INTERACTIVE_LINE_PLIES } from './reference-limits';
+import type { RecordedReferenceLine } from './historical-prose';
+import type { AuthoredReferenceResult } from './simple-prose-references';
+import type { ReasoningPositionContext, ReasoningEvidenceRecord } from './poc-contracts';
+
+/** Deterministic presentation repair, never new analytical evidence. */
+export function validateAnswerReferences(answer: string, context: ReasoningPositionContext,
+  records: readonly ReasoningEvidenceRecord[], recordedLine?: RecordedReferenceLine) {
+  const citationResult = normalizedEvidenceCitations(answer, records.filter(record => record.contextHash === reasoningContextHash(context)));
+  answer = citationResult.answer;
+  const historical = historicalProseRoots(context, records, recordedLine);
+  const repairs: Array<{ originalTarget: string; repairedTarget: string; label: string; evidenceIds: string[]; authority: string }> = [];
+  const repairedGaps = new Map<string,number>();
+  const repairedNotationCorrections: string[] = [];
+  const gameReferences: Array<{ target: string; status: 'resolved' | 'repaired' | 'unresolved'; reason?: string }> = [];
+  const admitted = (text: string) => {
+    const view = simpleProseReferences(text, context, records, recordedLine);
+    return { view, valid: view.coverage.resolved === 1 && view.notationCorrections.length === 0 && !view.blocks.some(block => block.tokens.some(token => token.reference?.kind === 'sequence')) && !view.gaps.some(g => !g.startsWith('Unbound text:')) };
+  };
+  const originalReferences = new Map<string,AuthoredReferenceResult>();
+  const originalView = simpleProseReferences(answer, context, records, recordedLine, undefined, r => originalReferences.set(JSON.stringify([r.label,r.target]),r));
+  const targetRepairedAnswer = answer.replace(/\[([^\]\n]+)\]\((game:[^)\n]*)\)/g, (original, label: string, target: string) => {
+    const initial = originalReferences.get(JSON.stringify([label,target]));
+    if (initial?.resolved) { gameReferences.push({target, status:'resolved'}); return original; }
+    try {
+      const parsed = /^game:(\d+):[^:\n]*$/.exec(target);
+      const root = parsed && historical.roots.get(Number(parsed[1]));
+      if (!parsed || !root) throw Error('Unknown recorded position');
+      // A cumulative path may repeat an earlier UCI accidentally. Delete at
+      // most one such occurrence, never insert/reorder moves or change roots.
+      // The complete repaired path must independently pass the same witnessed
+      // replay and SAN-label checks as rendering. Ambiguous repairs stay plain.
+      const authoredPath = target.split(':')[2].split(',');
+      const duplicateCandidates = new Map<string, ReturnType<typeof admitted>>();
+      if (authoredPath.length <= MAX_INTERACTIVE_LINE_PLIES + 1) {
+        for (let i = 1; i < authoredPath.length; i++) {
+          if (!authoredPath.slice(0, i).includes(authoredPath[i])) continue;
+          const path = authoredPath.filter((_, index) => index !== i);
+          const candidateTarget = `game:${parsed[1]}:${path.join(',')}`;
+          const checked = admitted(`[${label}](${candidateTarget})`);
+          const ids = checked.view.blocks.flatMap(b => b.tokens.flatMap(t => t.reference?.evidenceIds ?? []));
+          const actual = historical.recorded?.slice(Number(parsed[1]), Number(parsed[1]) + path.length);
+          const isActual = actual?.length === path.length && actual.every((uci, index) => uci === path[index]);
+          if (checked.valid && (isActual || ids.length)) duplicateCandidates.set(candidateTarget, checked);
+        }
+      }
+      if (duplicateCandidates.size === 1) {
+        const [repairedTarget, checked] = [...duplicateCandidates][0];
+        const evidenceIds = [...new Set(checked.view.blocks.flatMap(b => b.tokens.flatMap(t => t.reference?.evidenceIds ?? [])))];
+        repairs.push({originalTarget:target,repairedTarget,label,evidenceIds,authority:evidenceIds.length?'supplied-evidence':'recorded-play'});
+        if (initial?.reason) repairedGaps.set(initial.reason,(repairedGaps.get(initial.reason) ?? 0)+1);
+        repairedNotationCorrections.push(...checked.view.notationCorrections);
+        gameReferences.push({target,status:'repaired'});
+        return `[${label}](${repairedTarget})`;
+      }
+      if (duplicateCandidates.size > 1) throw Error('Ambiguous witnessed replacement');
+      // Parse the WHOLE label from its stated root; no suffix guessing, skipped
+      // words, root search, or joining independent engine paths.
+      const tokens = [...label.trim().matchAll(/(?:(\d+)(\.{1,3}|…)\s*)?([^\s.]+)/g)];
+      if (!tokens.length || tokens.length > MAX_INTERACTIVE_LINE_PLIES
+        || tokens.map(t => t[0]).join('').replace(/\s/g,'') !== label.replace(/\s/g,'')) throw Error('Incomplete SAN label');
+      const board = new Chess(root.context.fenAfter);
+      const path = tokens.map(t => {
+        const fields = board.fen().split(' ');
+        if (t[1] && (Number(t[1]) !== Number(fields[5]) || (t[2] === '.' ? 'w' : 'b') !== fields[1])) throw Error('Wrong move number');
+        const san = t[3].replace(/[!?]+$/,'');
+        const move = board.move(san, {strict:true});
+        if (move.san !== san) throw Error('Noncanonical SAN label');
+        return move.from + move.to + (move.promotion ?? '');
+      });
+      const repairedTarget = `game:${parsed[1]}:${path.join(',')}`;
+      const candidate = `[${label}](${repairedTarget})`;
+      const checked = admitted(candidate);
+      const evidenceIds = [...new Set(checked.view.blocks.flatMap(b => b.tokens.flatMap(t => t.reference?.evidenceIds ?? [])))];
+      const actual = historical.recorded?.slice(Number(parsed[1]), Number(parsed[1]) + path.length);
+      const isActual = actual?.length === path.length && actual.every((uci,i) => uci === path[i]);
+      if (!checked.valid || (!isActual && !evidenceIds.length)) throw Error('Replacement path is not witnessed');
+      repairs.push({originalTarget:target,repairedTarget,label,evidenceIds,authority:isActual?'recorded-play':'supplied-evidence'});
+      if(initial?.reason) repairedGaps.set(initial.reason,(repairedGaps.get(initial.reason) ?? 0)+1);
+      repairedNotationCorrections.push(...checked.view.notationCorrections);
+      gameReferences.push({target, status:'repaired'});
+      return candidate;
+    } catch {
+      gameReferences.push({target,status:'unresolved',reason:initial?.reason ?? 'Unresolved historical reference'});
+      return original; // Renderer retains its readable noninteractive fallback.
+    }
+  });
+  // Only a fully resolved original link can contribute a canonical label.
+  // Repaired historical targets already require complete strict canonical SAN.
+  // Keep the raw model output in its earlier trace.
+  const labelCorrections: Array<{originalLabel:string;canonicalLabel:string;target:string}> = [];
+  const repairedAnswer = targetRepairedAnswer.replace(/\[([^\]\n]+)\]\(([^)\n]+)\)/g, (original, label: string, target: string) => {
+    const reference = originalReferences.get(JSON.stringify([label,target]));
+    const canonicalLabel = reference?.resolved && reference.canonicalLabel;
+    if (!canonicalLabel || canonicalLabel === label) return original;
+    labelCorrections.push({originalLabel:label,canonicalLabel,target});
+    return `[${canonicalLabel}](${target})`;
+  });
+  // Target and label changes are already validated above. Reuse the full initial
+  // rendering pass instead of replaying every unaffected historical path twice.
+  const gaps = originalView.gaps.filter(gap => {
+    const repaired = repairedGaps.get(gap) ?? 0;
+    if (!repaired) return true;
+    repairedGaps.set(gap,repaired-1); return false;
+  });
+  let causalClaimChecks: ReturnType<typeof checkCausalClaims> = [];
+  let causalClaimCheckStatus: 'completed' | 'unavailable' = 'completed';
+  try { causalClaimChecks = checkCausalClaims(repairedAnswer,context,records,recordedLine); }
+  catch { causalClaimCheckStatus = 'unavailable'; } // A diagnostic failure never discards reference validation or prose.
+  return { answer: repairedAnswer, referenceValidation: {
+    version:SIMPLE_REFERENCE_VERSION, citationRepairs:citationResult.repairs, interactionCoverage:{...originalView.coverage,resolved:originalView.coverage.resolved+repairs.length},
+    unresolvedReferences:gaps.filter(g => !g.startsWith('Unbound text:')),
+    unboundMentions:gaps.filter(g => g.startsWith('Unbound text:')),
+    notationCorrections:[...new Set([...originalView.notationCorrections,...repairedNotationCorrections])], labelCorrections, gameReferences, repairs,
+    causalClaimChecks, causalClaimCheckStatus,
+    causalClaimCheckScope:'Witnessed single moves with explicit piece bindings or a direct move-as-subject escape clause only; ambiguous claims remain unresolved. Ranges are half-open UTF-16 offsets into the final reference-repaired answer; sentenceContext preserves surrounding text. Unlisted claims are not certified. Diagnostic only: no suppression or regeneration.',
+  } };
+}

package/src/chess-reasoning/answer-tool-host.ts

@@ -0,0 +1,10 @@
+import { createPocToolHost as createInternalToolHost, type PocToolHostOptions } from './poc-tools';
+import type { ReasoningPositionContext } from './poc-contracts';
+import { toLegacyPositionAnalysisProvider, type CompatiblePositionAnalysisProvider } from './position-analysis-contracts';
+
+export type AnswerToolHostOptions = Omit<PocToolHostOptions, 'analyzer'> & { analyzer?: CompatiblePositionAnalysisProvider };
+/** Public analyzer contract; the existing evidence protocol retains its versioned legacy spelling. */
+export function createPocToolHost(context: ReasoningPositionContext, options: AnswerToolHostOptions = {}) {
+  return createInternalToolHost(context, { ...options,
+    analyzer: options.analyzer ? toLegacyPositionAnalysisProvider(options.analyzer) : undefined });
+}

package/src/chess-reasoning/branch-expansion-policy.ts

@@ -0,0 +1,32 @@
+import type { BranchExpansionConfig } from './branch-expansion';
+import type { InitialSearchPlan } from './initial-search-plan';
+import type { ReasoningPositionContext, ReasoningToolSet } from './poc-contracts';
+
+export type BranchExpansionMode = 'off' | 'preparation' | 'tools' | 'both';
+// Experimental until real-engine cost and answer qualification are complete.
+export const BRANCH_EXPANSION_OPTIONS: BranchExpansionConfig = {maxNodes:8,maxPlies:4,maxLines:2,depthFloor:14,depthMode:'decreasing',maxElapsedMs:20000};
+export const DEFAULT_BRANCH_EXPANSION_MODE: BranchExpansionMode = 'off';
+
+/** Add a registered actual-after search without replacing hypothetical eager leads.
+ * Selected-context retention is the authority; omitted historical questions must
+ * acquire their explicit root through ordinary tools. No natural-language guesses. */
+export function withBranchPreparation(plan: InitialSearchPlan, context: ReasoningPositionContext,
+  omitSelectedContext: boolean, mode: BranchExpansionMode): InitialSearchPlan {
+  if (!(mode === 'both' || mode === 'preparation') || omitSelectedContext || context.kind === 'position' || plan.requests.length) return plan;
+  return {...plan, requests:[{tool:'explore_continuations',input:{phase:'after',depth:18,multiPv:3},
+    reason:'Bounded actual-after continuation and response discovery; distinct from hypothetical skipped-turn leads.'}]};
+}
+
+/** Both hosts keep the same contracts. Only internally generated initial calls
+ * select the preparation arm; user/model tool schemas cannot alter this setting. */
+export function selectBranchHost(ordinary: ReasoningToolSet, expanded: ReasoningToolSet,
+  mode: BranchExpansionMode): ReasoningToolSet {
+  return {reservesSearchAtDispatch:true, seedEvidence:records=>{const all=[...records];ordinary.seedEvidence?.(all);expanded.seedEvidence?.(all);}, descriptors:()=>ordinary.descriptors(), execute:async(name,input,signal,execution)=> {
+    const initial = typeof input.callId === 'string' && /^initial-search-\d+$/.test(input.callId);
+    const enabled = mode === 'both' || (initial ? mode === 'preparation' : mode === 'tools');
+    const selected = enabled ? expanded : ordinary;
+    const result = await selected.execute(name,input,signal,execution);
+    (enabled ? ordinary : expanded).seedEvidence?.(result.evidence);
+    return result;
+  }};
+}

package/src/chess-reasoning/branch-expansion.ts

@@ -0,0 +1,80 @@
+import { Chess } from 'chess.js';
+import type { PositionAnalysisLine } from './poc-tools';
+
+export type BranchExpansionConfig = {
+  maxNodes: number;
+  maxPlies: number;
+  maxLines: number;
+  depthFloor: number;
+  depthMode: 'fixed' | 'decreasing';
+  maxElapsedMs?: number;
+};
+
+export type BranchNode<T> = { prefix: string[]; finalFen: string; analysis: T };
+export type BranchExpansionResult<T> = {
+  nodes: BranchNode<T>[];
+  summary: { requestedNodes: number; searchedNodes: number; returnedNodes: number; skippedDuplicate: number;
+    skippedInvalid: number; failedNodes: number; stopped: 'complete' | 'node-limit' | 'elapsed-limit';
+    scope: string };
+};
+
+/** Only the original PVs are traversed. New alternatives are retained, never
+ * recursively scheduled. Each node is an independent FEN-root search. */
+export async function expandPrincipalBranches<T extends {lines: PositionAnalysisLine[]}>(input: {
+  rootFen: string;
+  lines: readonly PositionAnalysisLine[];
+  parentDepth: number;
+  config: BranchExpansionConfig;
+  signal?: AbortSignal;
+  search: (fen: string, depth: number) => Promise<T | null>;
+}): Promise<BranchExpansionResult<T>> {
+  const started = performance.now();
+  const config = input.config;
+  const roots = input.lines.slice(0, Math.max(0,config.maxLines)).map(line => {
+    if (!Array.isArray(line.pv) || line.pv[0] !== line.rootMove) return [];
+    // Completed PV suffixes are independently searched from another root. They
+    // must not become the parent search's own branch-selection evidence.
+    return Array.isArray(line.rawPv) ? line.rawPv : line.pv;
+  });
+  const seen = new Set<string>();
+  const nodes: BranchNode<T>[] = [];
+  let requestedNodes = 0, searchedNodes = 0, skippedDuplicate = 0, skippedInvalid = 0, failedNodes = 0;
+  let stopped: BranchExpansionResult<T>['summary']['stopped'] = 'complete';
+  outer: for (let ply = 1; ply <= config.maxPlies; ply++) {
+    for (const pv of roots) {
+      if (pv.length < ply) continue;
+      input.signal?.throwIfAborted();
+      if (searchedNodes >= config.maxNodes) { stopped = 'node-limit'; break outer; }
+      if (config.maxElapsedMs != null && performance.now() - started >= config.maxElapsedMs) { stopped = 'elapsed-limit'; break outer; }
+      requestedNodes++;
+      const prefix = pv.slice(0,ply);
+      let finalFen: string;
+      try {
+        const chess = new Chess(input.rootFen);
+        for (const uci of prefix) {
+          if (!/^[a-h][1-8][a-h][1-8][qrbn]?$/.test(uci)
+            || !chess.move({from:uci.slice(0,2),to:uci.slice(2,4),promotion:uci.slice(4)||undefined})) throw Error('invalid-parent-pv');
+        }
+        if (chess.isGameOver()) continue;
+        finalFen = chess.fen();
+      } catch { skippedInvalid++; continue; }
+      if (seen.has(finalFen)) { skippedDuplicate++; continue; }
+      seen.add(finalFen);
+      const depth = config.depthMode === 'fixed' ? input.parentDepth
+        : Math.max(config.depthFloor,input.parentDepth-ply);
+      searchedNodes++;
+      try {
+        const analysis = await input.search(finalFen,depth);
+        input.signal?.throwIfAborted();
+        if (analysis?.lines.length) nodes.push({prefix,finalFen,analysis});
+        else failedNodes++;
+      } catch (error) {
+        input.signal?.throwIfAborted();
+        if ((error as {code?:string})?.code === 'search-budget-exhausted') { stopped='node-limit'; break outer; }
+        failedNodes++;
+      }
+    }
+  }
+  return {nodes,summary:{requestedNodes,searchedNodes,returnedNodes:nodes.length,skippedDuplicate,skippedInvalid,failedNodes,stopped,
+    scope:'Independent searches at exact legal PV-prefix positions. Child scores compare moves only within the same child search; no child score validates the parent move. No new branches recursively expanded.'}};
+}