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

package/src/chess-reasoning/recorded-main-line.ts

@@ -0,0 +1,55 @@
+import { savedScorePresentation } from './saved-score-presentation';
+import { Chess } from "chess.js";
+import type { RecordedMainLine, RecordedMoveAnalysis } from "./answer-host-contracts";
+import { REASONING_POC_VERSION, reasoningContextHash, type ReasoningPositionContext, type ReasoningEvidenceRecord } from "./poc-contracts";
+
+/** Recorded moves are legal witnesses, never best-play/score or intent evidence. */
+function validRecordedAnalysis(value: RecordedMoveAnalysis | undefined, before: string, after: string, uci: string): value is RecordedMoveAnalysis {
+  if (!value || value.version !== "recorded-move-analysis/1" || value.fenBefore !== before || value.fenAfter !== after || value.moveUci !== uci) return false;
+  const boundedText = (s: unknown, max: number) => typeof s === "string" && s.length > 0 && s.length <= max && /^[a-zA-Z0-9@._/ +:-]+$/.test(s);
+  const depth = (n: unknown) => Number.isInteger(n) && (n as number) > 0 && (n as number) <= 256;
+  const score = (n: unknown) => n === null || (typeof n === "number" && Number.isFinite(n) && Math.abs(n) <= 1_000_000);
+  return boundedText(value.engine, 64) && boundedText(value.classification, 40) && depth(value.actualDepth)
+    && depth(value.requestedDepth) && Number.isInteger(value.classifierVersion) && value.classifierVersion > 0 && value.classifierVersion <= 100_000
+    && [value.beforeCp, value.afterCp, value.lossCp, value.mateBefore, value.mateAfter].every(score);
+}
+
+export function recordedMainLineResult(line: RecordedMainLine, context: ReasoningPositionContext) {
+  if (!line || !Array.isArray(line.moves) || line.moves.length > 512 || !Number.isInteger(line.selectedIndex) || line.selectedIndex < -1
+    || !Number.isInteger(line.totalPlies) || line.totalPlies < line.moves.length || line.selectedIndex >= line.totalPlies || line.truncated !== (line.totalPlies > line.moves.length)) throw Error("Invalid recorded main line.");
+  const atStart = context.kind === "position";
+  if (atStart && (line.selectedAtStart !== true || line.selectedIndex !== -1 || line.startFen !== context.fenAfter)) throw Error("Recorded starting-position scope mismatch.");
+  if (!atStart && line.selectedAtStart) throw Error("Recorded anchor kind mismatch.");
+  const chess = new Chess(line.startFen);
+  // A branch has no selected main-line index, so its root must be checked directly.
+  // Legacy move contexts omit historyStartFen and replay from the standard start.
+  const historyRoot = new Chess(atStart ? context.fenAfter : context.historyStartFen).fen();
+  if (chess.fen() !== historyRoot) throw Error("Recorded main-line root mismatch.");
+  const rows: Array<[number, string, number, number, number, string, number | null, number | null, number | null, number | null, number | null]> = [];
+  const moves = line.moves.map((item, index) => {
+    if (!/^[a-h][1-8][a-h][1-8][qrbn]?$/.test(item.uci)) throw Error("Invalid recorded move.");
+    const before = chess.fen(), move = chess.move({ from: item.uci.slice(0, 2), to: item.uci.slice(2, 4), promotion: item.uci.slice(4) || undefined });
+    if (move.san !== item.san) throw Error("Recorded SAN mismatch.");
+    if (index === line.selectedIndex && (before !== context.fenBefore || chess.fen() !== context.fenAfter || item.uci !== context.moveUci
+      || index !== context.historyUci.length || line.moves.slice(0, index).some((m, i) => m.uci !== context.historyUci[i]))) throw Error("Recorded question scope mismatch.");
+    const a = item.analysis;
+    if (validRecordedAnalysis(a, before, chess.fen(), item.uci)) { const score=savedScorePresentation(a); rows.push([index + 1, a.engine, a.actualDepth,
+      a.requestedDepth, a.classifierVersion, a.classification, score.beforeCp, score.afterCp, score.lossCp, score.mateBefore, score.mateAfter]); }
+    return { uci: item.uci, san: move.san, moveNumber: Number(before.split(" ")[5]), color: move.color };
+  });
+  const continuation = atStart ? moves.map(move => move.uci) : line.selectedIndex >= 0 && line.selectedIndex < moves.length ? moves.slice(line.selectedIndex + 1).map(move => move.uci) : [];
+  const contextHash = reasoningContextHash(context);
+  const evidence: ReasoningEvidenceRecord[] = continuation.length ? [{ schemaVersion: REASONING_POC_VERSION,
+    id: `evidence:recorded-main-line:${contextHash}:${continuation.slice(0, 32).join("-")}`, contextHash, kind: "fact", source: "loaded-game-main-line", proofStrength: "observed",
+    licenses: ["chess.legality", "chess.identity"], summary: "Legally replayed recorded main-line continuation; not an engine recommendation or proof of intent.",
+    data: { authority: "legal-exact", scope: "sequence-legality-and-identity", phase: "after" },
+    coverage: { complete: false, covered: [], unresolved: ["No optimality or human-intent claim."] },
+    replay: { fen: context.fenAfter, movesUci: continuation.slice(0, 32) } }] : [];
+  return { contextHash, evidence, recordedAnalysis: { source: "Current loaded game's stored per-move analysis snapshots", authority: "attributed-existing-analysis",
+    scorePerspective: "mover-at-each-recorded-ply", units: "centipawns; mate separate", coverage: { analyzedPlies: rows.length, totalPlies: line.totalPlies, complete: !line.truncated && rows.length === line.totalPlies },
+    columns: ["ply", "engine", "reportedDepth", "recordedRequestedDepth", "classifierVersion", "classification", "beforeCp", "afterCp", "lossCp", "mateBefore", "mateAfter"], rows,
+    limitations: ["reportedDepth is the stored classification depth, not a verified root-search depth; recordedRequestedDepth is the board setting recorded when classified.", "Matching stored edge analyses are included even when their engine, classifier version or dependency fingerprint is no longer current; missing or invalid plies have no analysis row.", "Scores are from the mover's perspective at each row's ply: positive favors that move's color; lossCp is a saved before/after search delta for that mover, not a controlled regret comparison. Mate-related/sentinel centipawn fields are null; use mateBefore/mateAfter. Best or Forced labels can coexist with search-score changes.", "Classification is a historical decision from the reported classifier version, not necessarily current policy or proof of its explanation. Saved scores may differ from fresh searches.", ...(line.truncated ? ["Analysis is limited to the first 512 recorded plies."] : [])] },
+    recordedMainLine: { source: "Current loaded game's recorded primary line (may contain user edits)", startFen: line.startFen, moves,
+    selectedIndex: line.selectedIndex, selectedAtStart: atStart, selectedOnMainLine: atStart || line.selectedIndex >= 0, totalPlies: line.totalPlies, truncated: line.truncated, pgn: chess.pgn() },
+    limitations: ["PGN is reconstructed from recorded moves; original headers, clocks and result metadata are not included.", "Recorded play is not engine evidence of best play, force, safety or human intent.", ...(!atStart && line.selectedIndex < 0 ? ["The question is on a branch; this main line is not its continuation."] : []), ...(line.truncated ? ["Only the first 512 plies are returned."] : [])] };
+}

package/src/chess-reasoning/recorded-position-tools.ts

@@ -0,0 +1,78 @@
+import { Chess } from 'chess.js';
+import type { RecordedMainLine } from './answer-host-contracts';
+import { recordedMainLineResult } from './recorded-main-line';
+import { createPocToolHost, type PocToolHostOptions } from './poc-tools';
+import { reasoningContextHash, type ReasoningPositionContext, type ReasoningToolDescriptor, type ReasoningToolSet, type ReasoningToolResult } from './poc-contracts';
+import { stableHash } from './stable';
+
+export const RECORDED_POSITION_TOOLS = ['analyze_game_position', 'test_game_line'] as const;
+export const isRecordedPositionTool = (name: string) => (RECORDED_POSITION_TOOLS as readonly string[]).includes(name);
+const moves = { type:'array', maxItems:32, items:{type:'string',maxLength:5,pattern:'^[a-h][1-8][a-h][1-8][qrbn]?$'} };
+const common = { ply:{type:'integer',minimum:0,maximum:512}, depth:{type:'integer',minimum:18,maximum:18}, minimumPvPlies:{type:'integer',minimum:1,maximum:32} };
+export const RECORDED_POSITION_DESCRIPTORS: ReasoningToolDescriptor[] = [
+  {name:'analyze_game_position',category:'probe',description:'analyze_game_position',inputSchema:{type:'object',additionalProperties:false,required:['ply'],properties:{...common,rootMoves:{...moves,minItems:1,maxItems:6},multiPv:{type:'integer',minimum:1,maximum:3}}}},
+  {name:'test_game_line',category:'probe',description:'test_game_line',inputSchema:{type:'object',additionalProperties:false,required:['ply','movesUci'],properties:{...common,movesUci:{...moves,minItems:1},analyzeFinal:{type:'boolean'},compareFinalMovesUci:{...moves,minItems:1,maxItems:6},inspectPlies:{type:'array',maxItems:8,items:{type:'integer',minimum:1,maximum:32}},inspectSquares:{type:'array',maxItems:12,items:{type:'string',maxLength:2,pattern:'^[a-h][1-8]$'}}}}},
+];
+
+/** No caller supplied FEN. Every root is an exact occurrence in the frozen record. */
+export function recordedPositionContext(line: RecordedMainLine, ply: number): ReasoningPositionContext {
+  if (!Number.isInteger(ply) || ply < 0 || ply > line.moves.length) throw Object.assign(Error(`ply must be between 0 and ${line.moves.length}; 0 is the initial position`),{code:'invalid-recorded-ply',field:'ply',expected:`integer 0..${line.moves.length}`});
+  const chess=new Chess(line.startFen), prefix=line.moves.slice(0,ply);
+  let before=chess.fen();
+  for(const item of prefix){before=chess.fen(); const m=chess.move({from:item.uci.slice(0,2),to:item.uci.slice(2,4),promotion:item.uci.slice(4)||undefined}); if(m.san!==item.san)throw Error('recorded-SAN-mismatch');}
+  const id=`recorded:${stableHash({startFen:line.startFen,moves:line.moves.map(m=>m.uci)})}:${ply}`;
+  return ply===0 ? {kind:'position',nodeId:id,historyStartFen:line.startFen,historyUci:[],fenBefore:chess.fen(),fenAfter:chess.fen(),moveUci:'',moveSan:''}
+    : {nodeId:id,historyStartFen:line.startFen,historyUci:prefix.slice(0,-1).map(m=>m.uci),fenBefore:before,fenAfter:chess.fen(),moveUci:prefix.at(-1)!.uci,moveSan:prefix.at(-1)!.san};
+}
+
+export function withRecordedPositionTools(selected: ReasoningPositionContext, base: ReasoningToolSet, options: PocToolHostOptions, getLine: (signal?:AbortSignal)=>Promise<RecordedMainLine>): ReasoningToolSet {
+  const hash=reasoningContextHash(selected);
+  let frozen: RecordedMainLine | undefined;
+  return {
+    reservesSearchAtDispatch:true,
+    descriptors:()=>[...base.descriptors(),...RECORDED_POSITION_DESCRIPTORS],
+    seedEvidence:records=>base.seedEvidence?.(records),
+    async execute(name,args,signal,execution){
+      if(!isRecordedPositionTool(name))return base.execute(name,args,signal,execution);
+      signal?.throwIfAborted();
+      if(args.contextHash!==hash || typeof args.callId!=='string')throw Error('stale-recorded-tool-envelope');
+      if(!frozen){const line=structuredClone(await getLine(signal));recordedMainLineResult(line,selected);frozen=line;}
+      signal?.throwIfAborted();
+      const root=recordedPositionContext(frozen,Number(args.ply)), rootHash=reasoningContextHash(root);
+      // Never carry a selected-edge leading alternative into another root.
+      const host=createPocToolHost(root,{...options,leadingAlternative:undefined});
+      const board=new Chess(root.fenAfter);
+      const tool=name==='test_game_line'?'test_line':args.rootMoves?'compare_moves':board.isCheckmate()||board.isStalemate()?'inspect_position':'explore_continuations';
+      const request={contextHash:rootHash,callId:args.callId,phase:'after',depth:args.depth??18,minimumPvPlies:args.minimumPvPlies??10,
+        ...(tool==='test_line'?{movesUci:args.movesUci,analyzeFinal:args.analyzeFinal,compareFinalMovesUci:args.compareFinalMovesUci,inspectSquares:args.inspectSquares,inspectPlies:args.inspectPlies}:tool==='compare_moves'?{movesUci:args.rootMoves}:{multiPv:args.multiPv??3})};
+      const result=await host.execute(tool,request,signal,execution);
+      const recordedPosition={recordHash:stableHash({startFen:frozen.startFen,moves:frozen.moves.map(m=>m.uci)}),ply:Number(args.ply),startFen:frozen.startFen,fen:root.fenAfter,historyUci:frozen.moves.slice(0,Number(args.ply)).map(m=>m.uci),rootContextHash:rootHash,
+        nextRecordedMove:frozen.moves[Number(args.ply)]?.san??null,scope:'position after exactly ply recorded half-moves; independent of board selection'};
+      return {...result,tool:name,contextHash:hash,data:{recordedPosition,details:result.data},
+        evidence:result.evidence.map(e=>({...e,id:`evidence:game:${hash}:${rootHash}:${e.id.replaceAll(':','-')}`,contextHash:hash,data:{recordedPosition,details:e.data}})),
+        limitations:[...result.limitations,'Historical root: phases and piece identities inside details refer only to recordedPosition. Use game:PLY:uci,uci links for this exact recorded ply and witnessed local path; selected before/after links cannot address this root.']} satisfies ReasoningToolResult;
+    },
+  };
+}
+
+/** Request-local exact successful result reuse, including automatically prepared searches. */
+export function memoizeToolResults(host: ReasoningToolSet): ReasoningToolSet {
+  const cache=new Map<string,ReasoningToolResult>();
+  return {...host,async execute(name,args,signal,execution){
+    signal?.throwIfAborted();
+    const {callId,...input}=args;
+    const key=JSON.stringify([name,Object.keys(input).sort().map(k=>[k,input[k]])]);
+    const old=cache.get(key);
+    if(old)return {...structuredClone(old),callId:String(callId),durationMs:0,limitations:[...old.limitations,'Reused the exact successful request-local result; no new engine search.']};
+    const result=await host.execute(name,args,signal,execution);
+    signal?.throwIfAborted();
+    const short=result.evidence.some(e=>{
+      const d=(e.data.recordedPosition?e.data.details:e.data) as Record<string,unknown>;
+      const minimum=Number((d.searchScope as Record<string,unknown>|undefined)?.minimumPvPlies??1);
+      return Array.isArray(d.lines)&&d.lines.some(line=>line.pv.length<minimum&&line.pvCompletion?.status!=='terminal');
+    });
+    // A short legal line is valid evidence, but not coverage for a longer request.
+    if(result.support==='supported' && result.evidence.length && !short)cache.set(key,structuredClone(result));
+    return result;
+  }};
+}

package/src/chess-reasoning/recorded-reference-context.ts

@@ -0,0 +1,44 @@
+import { Chess } from 'chess.js';
+import { reasoningContextHash, type ReasoningPositionContext } from './poc-contracts';
+
+/** Reconstruct an occurrence from its ordered history, never from a FEN guess. */
+export function historyPositionContext(startFen: string, history: string[]): ReasoningPositionContext {
+  if (!Array.isArray(history) || history.length > 512) throw Error('Invalid recorded history');
+  const board = new Chess(startFen); let before = board.fen(), san = '';
+  for (const uci of history) {
+    if (typeof uci !== 'string' || !/^[a-h][1-8][a-h][1-8][qrbn]?$/.test(uci)) throw Error('Invalid recorded move');
+    before = board.fen(); san = board.move({from:uci.slice(0,2),to:uci.slice(2,4),promotion:uci[4]}).san;
+  }
+  return history.length ? {nodeId:'recorded-reference',historyStartFen:startFen,historyUci:history.slice(0,-1),fenBefore:before,fenAfter:board.fen(),moveUci:history.at(-1)!,moveSan:san}
+    : {kind:'position',nodeId:'recorded-reference',historyStartFen:startFen,historyUci:[],fenBefore:board.fen(),fenAfter:board.fen(),moveUci:'',moveSan:''};
+}
+export function recordedEvidenceContext(selected: ReasoningPositionContext, value: unknown): ReasoningPositionContext {
+  const p=value as {startFen:string;historyUci:string[];ply:number;fen:string;rootContextHash:string;recordHash:string};
+  if (!p || p.startFen !== (selected.historyStartFen ?? new Chess().fen()) || !Array.isArray(p.historyUci) || p.ply !== p.historyUci.length) throw Error('Invalid recorded scope');
+  const root=historyPositionContext(p.startFen,p.historyUci);
+  if (typeof p.recordHash !== 'string' || reasoningContextHash({...root,nodeId:`recorded:${p.recordHash}:${p.ply}`}) !== p.rootContextHash) throw Error('Recorded identity mismatch');
+  if (root.fenAfter !== p.fen) throw Error('Recorded root mismatch');
+  return root;
+}
+export function recordedNavigation(context: ReasoningPositionContext, recorded?: ReasoningPositionContext) {
+  return recorded ? {anchorEdgeId:`recorded-reference:${reasoningContextHash(recorded)}`,context:recorded} : {context};
+}
+
+/** Reject contradictory engine scope before promoting its paths to navigation/theory. */
+export function recordedDetailsMatch(root: ReasoningPositionContext, value: unknown): boolean {
+  try {
+    const d=value as {phase?:string;played?:{uci:string;san?:string}[];finalFen?:string;searchScope?:{fen?:string};lines?:{pv:string[];rootMove:string;scoreScope?:{fen?:string}}[]};
+    if (!d || (d.phase !== undefined && d.phase !== 'after')) return false;
+    const board=new Chess(root.fenAfter);
+    if(d.played)for(const move of d.played) {
+      const m=board.move({from:move.uci.slice(0,2),to:move.uci.slice(2,4),promotion:move.uci[4]});
+      if(move.san!==undefined && move.san!==m.san)return false;
+    }
+    if(d.finalFen!==undefined && board.fen()!==d.finalFen)return false;
+    if(d.searchScope?.fen!==undefined && d.searchScope.fen!==board.fen())return false;
+    if(d.lines)for(const line of d.lines) {
+      if(!Array.isArray(line.pv) || line.rootMove!==line.pv[0] || (line.scoreScope?.fen!==undefined && line.scoreScope.fen!==board.fen()))return false;
+    }
+    return true;
+  } catch { return false; }
+}

package/src/chess-reasoning/recorded-selected-classification.ts

@@ -0,0 +1,54 @@
+import { Chess } from 'chess.js';
+import type { RecordedMainLine } from './answer-host-contracts';
+import { recordedMainLineResult } from './recorded-main-line';
+import { REASONING_POC_VERSION, reasoningContextHash, validateReasoningPositionContext, type ReasoningPositionContext, type ReasoningEvidenceRecord } from './poc-contracts';
+import { EVIDENCE_LICENSE } from './evidence-licenses';
+import { stableHash } from './stable';
+
+/** A historical badge is not a refreshed board analysis or a new classification. */
+export function recordedSelectedClassification(context: ReasoningPositionContext, line: RecordedMainLine | undefined) {
+  if (context.kind === 'position' || !line || line.selectedAtStart || !Array.isArray(line.moves)
+    || !Number.isInteger(line.selectedIndex) || line.selectedIndex < 0 || line.selectedIndex >= line.moves.length
+    || line.selectedIndex !== context.historyUci.length || line.moves.length > 512
+    || line.startFen !== (context.historyStartFen ?? new Chess().fen())) return undefined;
+  try {
+    validateReasoningPositionContext(context);
+    const selected = line.moves[line.selectedIndex];
+    if (selected.san !== context.moveSan || selected.uci !== context.moveUci) return undefined;
+    // Replay only the observed prefix. Neither validation nor output requires future play.
+    const prefix = line.moves.slice(0, line.selectedIndex + 1);
+    const validated = recordedMainLineResult({...line, moves: prefix, totalPlies: prefix.length, truncated: false}, context);
+    const row = validated.recordedAnalysis.rows.find(item => item[0] === line.selectedIndex + 1);
+    if (!row) return undefined;
+    const [ply, engine, recordedDepth, requestedDepth, classifierVersion, classification,
+      beforeCp, afterCp, lossCp, mateBefore, mateAfter] = row;
+    const snapshot = {
+      version: 'recorded-selected-classification/1' as const,
+      authority: 'historical-reported-label-only',
+      source: 'loaded-game-stored-selected-move-analysis',
+      position: { fenBefore: context.fenBefore, fenAfter: context.fenAfter, moveUci: context.moveUci, moveSan: context.moveSan, ply },
+      classification, classifierVersion, engine, reportedDepth: recordedDepth, recordedRequestedDepth: requestedDepth,
+      freshlyRecomputed: false,
+      savedEvaluation: { perspective: 'selected-mover', units: 'centipawns; mate separate', beforeCp, afterCp, lossCp, mateBefore, mateAfter },
+      limitations: [
+        'This is the recorded classification under the supplied historical classifier version, not necessarily the current app badge or current policy.',
+        'Preparation and subsequent engine searches do not recompute this stored label. Prefer a separately supplied refreshed board classification when available.',
+        'The label is not proof of its chess explanation. Saved scores may differ from fresh searches; lossCp is a saved search delta, not a matched comparison.',
+        'No future recorded moves, alternative candidates or other moves\' classifications are included.',
+      ],
+    };
+    const contextHash = reasoningContextHash(context);
+    const record: ReasoningEvidenceRecord = {
+      schemaVersion: REASONING_POC_VERSION, id: `evidence:recorded-selected-classification:${stableHash({contextHash,snapshot})}`,
+      contextHash, kind: 'context', source: snapshot.source, proofStrength: null,
+      summary: `The stored analysis labelled ${context.moveSan} ${classification} under classifier version ${classifierVersion}; this is historical reported context, not a new classification.`,
+      data: snapshot, coverage: {complete:false, covered:['historical-selected-classification'], unresolved:['current-policy-classification','causal-explanation']},
+      replay: {fen:context.fenBefore,moveUci:context.moveUci}, licenses:[EVIDENCE_LICENSE.ATTENTION_AFFORDANCE],
+    };
+    return { record, snapshot: {...snapshot, evidenceId:record.id} };
+  } catch {
+    return undefined;
+  }
+}
+
+export type RecordedSelectedClassification = ReturnType<typeof recordedSelectedClassification>;

package/src/chess-reasoning/reference-limits.ts

@@ -0,0 +1,2 @@
+/** Shared producer, reference-admission and saved-answer path bound. */
+export const MAX_INTERACTIVE_LINE_PLIES = 32;

package/src/chess-reasoning/research-exports.ts

@@ -0,0 +1,197 @@
+/** Experimental evidence and replay surface. See docs/RESEARCH-API.md. */
+export {SIMPLE_SYSTEM,SIMPLE_REFERENCE_INSTRUCTIONS,SIMPLE_STOPPING_GUIDANCE,SIMPLE_PURPOSE_GUIDANCE,SIMPLE_SEARCH_BREADTH_GUIDANCE,SIMPLE_SECTION_GUIDANCE,SIMPLE_CONTENT_SELECTION_GUIDANCE,SIMPLE_EXAMPLE_GUIDANCE,COMPACT_ENGINE_INSTRUCTIONS,FACT_DELIVERY_INSTRUCTIONS,OPENING_SOURCE_INSTRUCTIONS,SIMPLE_BOARD_ANALYSIS_GUIDANCE,SIMPLE_EXPLANATION_GUIDANCE,stabilizeSimplePolicy,MECHANISM_FACT_INSTRUCTIONS,CONVERSATION_CONTEXT_INSTRUCTIONS} from './server-simple-policy';
+export type {SimplePolicyOptions} from './server-simple-policy';
+export {enrichAblationEvidenceBundleWithAdmittedCaptureResponses,CAPTURE_RESPONSE_FACT_KIND,COMPLETED_TOOL_REPLAY_ADMISSION_KEY} from './ablation-evidence-capture';
+export {ABLATION_EVIDENCE_BUNDLE_VERSION,validateAblationEvidenceClosureBundle,PRECOMMITTED_PROBE_ATTRIBUTION_CATEGORIES,validateAblationProbeTelemetry,createAblationEvidenceClosureBundle,enrichAblationEvidenceClosureBundle,ABLATION_PROBE_TELEMETRY_VERSION,createAblationProbeTelemetry,ablationHistoryThroughTargetHash,precommittedProbeAttributionCategories} from './ablation-evidence-bundle';
+export type {AblationEvidenceClosureBundle,ProbeAttributionCategory,AblationProbeTelemetry,AblationEvidenceClosureCoverage,AblationProbeEffect} from './ablation-evidence-bundle';
+export {createDefaultObservationProvider,DETERMINISTIC_OBSERVATION_PROVIDER_VERSION,QUESTION_SALIENCE_POLICY_VERSION,DeterministicObservationProvider,CompositeObservationProvider,QuestionConditionedSaliencePolicy} from './poc-observations';
+export {stableHash,stableJson} from './stable';
+export {ABLATION_DIRECT_SYNTHESIS_VERSION,DIRECT_SYNTHESIS_PROPOSAL_JSON_SCHEMA,materializeDirectSynthesis,parseDirectSynthesisProposal} from './ablation-direct-synthesis';
+export type {DirectSynthesisArtifact,DirectSynthesisIssue} from './ablation-direct-synthesis';
+export {projectAblationEvidenceForModel,compactLeanEvidencePacket} from './ablation-model-facing-evidence';
+export {bytes,emitObservableTrace,numericUsage,AI_SDK_ANSWER_OBLIGATION_RUNTIME,reasoningMetrics,requestId,AI_SDK_CRITIC_RUNTIME,classifyReasoningCriticHarnessRejection,AI_SDK_DISCOURSE_RUNTIME,abortSource,classifyRuntimeFailure,deepestError,AI_SDK_GRAPH_PLANNING_RUNTIME,GraphSelectionHarnessRejection,classifyGraphSelectionHarnessRejection,AI_SDK_GRAPH_SELECTION_RUNTIME,AI_SDK_HYPOTHESIS_RUNTIME,HypothesisProviderRuntimeFailure,classifyProviderHypothesisRejection,AI_SDK_RENDER_RUNTIME,AI_SDK_REPAIR_RUNTIME,AI_SDK_PURPOSE_PROBE_RUNTIME,AI_SDK_RESOLUTION_AUDIT_RUNTIME,AI_SDK_REASONING_RUNTIME,AI_SDK_TERMINAL_REVIEW_RUNTIME,DETERMINISTIC_DISCOURSE_RUNTIME,CriticResolutionAuditHarnessRejection,HypothesisHarnessRejection,HypothesisReviewHarnessRejection,TerminalReviewHarnessRejection,ReasoningCriticHarnessRejection,ReasoningWorkflowFailure,classifyGraphSelectionRuntimeFailure,classifyHypothesisHarnessRejection,observableTraceMessages} from './ai-sdk-runtime-support';
+export type {ObservableLlmTraceSink,SanitizedHttpAttempt,ObservableLlmTraceEvent} from './ai-sdk-runtime-support';
+export {AblationTransportCorrectionError,assertTransportOnlyDirectCorrection,isTransportCorrectableDirectSynthesisIssues} from './ablation-transport-correction';
+export {effectiveLicensesForRecord,EVIDENCE_LICENSE,licensesSemanticChessGrounding,withEvidenceLicenses,evidenceLicenseInput,maximumEvidenceLicenses,validateEvidenceLicenseClaims,effectiveEvidenceLicenses,licensesBoundedRouteRelevance} from './evidence-licenses';
+export type {EvidenceLicense,EvidenceLicenseInput,LicensableEvidenceRecord} from './evidence-licenses';
+export {REFERENCE_DOMAINS,PARTICIPANT_ROLES,hasConcept,participantIds,DEFAULT_CONCEPT_REGISTRY,ENTITY_TYPES,RELATION_TYPES,ATTRIBUTE_KEYS,CONCEPT_KEYS,participant,conceptDefinition,createConceptRegistry,extendConceptRegistry,conceptsOf,primaryConcept,stringListAttribute} from './concept-registry';
+export type {CaptureActor,ConceptLifecycle,ConceptRegistry,ConceptDefinition} from './concept-registry';
+export {collectReasoningMoveWitnesses,reasoningEvidenceReplayStartPhase} from './poc-move-witnesses';
+export type {ReasoningMoveWitness} from './poc-move-witnesses';
+export {createPocIdentityTimeline,canonicalPieceLabel,pieceIdentity,squareForPiece,pieceIdAt} from './poc-piece-refs';
+export type {PocIdentityTimeline} from './poc-piece-refs';
+export {ABLATION_B_PRIME_TRIGGER_VALUES,runAblationAdaptiveDirect,ABLATION_ADAPTIVE_RUNTIME_VERSION,ABLATION_B_SYSTEM,prepareAblationAdaptiveEvidenceForStagedReference,AdaptiveAblationPreconditionError,deriveAblationBPrimeTriggers} from './ablation-adaptive-runtime';
+export type {AblationBPrimeTrigger,AblationAdaptiveArm,AblationAdaptiveResult,AblationAdaptiveRuntimeOptions,AdaptiveEvidenceLoopResult,AblationAdaptiveCallDiagnostic,AdaptiveEvidenceLoop} from './ablation-adaptive-runtime';
+export {ABLATION_ADAPTIVE_EVIDENCE_LOOP_VERSION,ModelOwnedAdaptiveEvidenceLoop,retainedEvidenceCatalogue} from './ablation-adaptive-evidence-loop';
+export type {AdaptiveEvidenceToolExecutor} from './ablation-adaptive-evidence-loop';
+export {ABLATION_LEAN_DIRECT_RUNTIME_VERSION,projectLeanDirectEvidence,projectLeanEpisodeEvidence,runLeanDirect,ABLATION_LEAN_DIRECT_PROPOSAL_VERSION,LEAN_DIRECT_PROPOSAL_JSON_SCHEMA,ablationLeanDirectSystem,materializeLeanDirectProposal} from './ablation-lean-direct-runtime';
+export type {LeanDirectCallDiagnostic,LeanDirectResult,LeanDirectRuntimeOptions} from './ablation-lean-direct-runtime';
+export type {LeanDirectEvidenceSelector} from './evidence-selector-contract';
+export type {PositionAnalysisCacheProvenance,PocToolHostOptions} from './poc-tools';
+export {isTerminalEntity,createSemanticEntity,createSemanticRelation,createIdeaGraph,extendIdeaGraph,forkIdeaGraph,graphIdentityCompatible,openEntityCount} from './idea-graph';
+export type {CreateSemanticEntityInput,CreateSemanticRelationInput} from './idea-graph';
+export {CHESS_REASONING_SCHEMA_VERSION,CHESS_REASONING_POLICY_VERSION} from './types';
+export type {ConceptKey,EntityId,ReasoningToolResponse,SemanticMoveRecord,CandidateGenerationReport,IdentityState,PieceId,SemanticCandidate,ProofStrength,SemanticParticipant,SemanticValue,SemanticEntity,SemanticRelation,CandidateDisposition,EvidenceRecord,ProbeBudget,IdeaGraph,BranchId,EvidenceId,CandidateId,RegistryKey,ConceptCoverage,SemanticScalar,SemanticAttributes,SemanticReference,PieceIdentity,MoveIdentityDelta,ProposalReason,SemanticTransition,ToolSupport} from './types';
+export {EXPLAIN_PLAN_SELECTION_DESCRIPTOR,RECORD_HYPOTHESES_DESCRIPTOR,HypothesisLedger,REVIEW_HYPOTHESES_DESCRIPTOR,validateHypothesisAcceptancePolicies,assertDirectedDestinationAnchors} from './poc-hypotheses';
+export type {ExplainPlanSelection,InternalExplainPlanRequest} from './poc-hypotheses';
+export {RAW_CHESS_TEXT,SEMANTIC_TEXT_JSON_PATTERN,RAW_CHESS_TEXT_PATTERN_SOURCE} from './poc-semantic-text';
+export {priorConversationMessages} from './conversation-context';
+export type {PriorConversationMessage} from './conversation-context';
+export {chessSquareColor,CHESS_REFERENCE_DICTIONARY} from './chess-reference-dictionary';
+export {EXISTING_ANALYSIS_CONTEXT_MODE,normalizeExistingAnalysisContext,EXISTING_ANALYSIS_CONTEXT_VERSION,LEGACY_EXISTING_ANALYSIS_CONTEXT_VERSION,CANONICAL_EDGE_ANALYSIS_SNAPSHOT_VERSION,EXISTING_ANALYSIS_RECORD_VERSION,MATERIAL_OFFER_SET_VERSION,EXISTING_ANALYSIS_OBSERVATION_PROVIDER_ID,ANALYSIS_CONTEXT_PROVENANCE_TIER,ExistingAnalysisObservationProvider} from './existing-analysis-context';
+export type {ExistingAnalysisContextMode,AnalysisContextProvenanceTier,MaterialOfferCandidateSummary,MaterialOfferSet,ExistingAnalysisRecord,ExistingAnalysisContext} from './existing-analysis-context';
+export {scopePositionAnalysis} from './position-analysis-scope';
+export {classificationTargetAtSelection} from './classification-question-target';
+export {recordedMainLineResult} from './recorded-main-line';
+export {applyIdentityMove,createIdentityState,forkIdentityState} from './piece-identities';
+export {CLASSIFICATION_REASSESSMENT_GUIDANCE,classificationReassessment} from './classification-reassessment';
+export {MATCHED_COMPARISON_GUIDANCE,matchedRootComparison} from './matched-comparison';
+export {CHESS_FACT_REQUEST_VERSION,CHESS_FACT_RESULT_VERSION,CHESS_FACT_SCHEMA_VERSION,validateChessFactRecord,validateChessFactRequest,assertFactProofWithinAuthority,isChessFactAuthority,chessFactRecordLicenses,maximumFactProofStrength,factProofStrength,factCoverageSupportsAbsence} from './fact-provider';
+export type {ChessFactCapability,ChessFactRecord,ChessFactResult,ChessFactAuthority,ChessFactCoverage,ChessFactPhase,ChessFactProvider,ChessFactRequest,ChessFactEngineProvenance,ChessFactOmission} from './fact-provider';
+export {createMechanicalFactRequest,MechanicalChessFactProvider,squaresBetween,deriveAdmittedCaptureResponseAvailabilityFact,MECHANICAL_CHESS_FACT_PROVIDER_ID,MECHANICAL_CHESS_FACT_PROVIDER_VERSION} from './mechanical-fact-provider';
+export type {AdmittedCaptureResponseAvailabilityFact,AdmittedCaptureResponseAvailabilityInput} from './mechanical-fact-provider';
+export {moveMechanismFacts} from './move-mechanism-facts';
+export {simpleUsageForTrace,SIMPLE_TOOL_AGENT_VERSION,SIMPLE_DISCLOSURE} from './portable-answer-runtime';
+export type {SimpleAgentDiagnostic} from './portable-answer-runtime';
+export {withRecordedPositionTools,memoizeToolResults,RECORDED_POSITION_DESCRIPTORS,recordedPositionContext} from './recorded-position-tools';
+export {EXPLANATION_REVIEW_SCHEMA,validateExplanationReview,explanationCoverage,explanationSummary,planningEvidence,explanationBranches} from './simple-explanation-coverage';
+export {compactSimpleEngineResult,compactSimpleToolResult,simplePastHistory,compactSimpleInitialPacket,SIMPLE_EVIDENCE_VIEW_VERSION,simpleInitialEvidenceView} from './simple-evidence-view';
+export {recordedNavigation,historyPositionContext} from './recorded-reference-context';
+export {validateAnswerReferences} from './answer-reference-validation';
+export {withBranchPreparation,selectBranchHost,BRANCH_EXPANSION_OPTIONS} from './branch-expansion-policy';
+export {expandPrincipalBranches} from './branch-expansion';
+export {checkCausalClaims} from './causal-claim-checks';
+export {ChessFactObservationProvider,FACT_OBSERVATION_ADAPTER_VERSION} from './fact-observation-provider';
+export type {ChessFactObservationProviderOptions} from './fact-observation-provider';
+export {projectCompactEngineEvidence,expandCompactEngineEvidence} from './simple-compact-evidence';
+export {compactPreparedSearchResult,compactSearchRecord} from './compact-search-preparation';
+export {evidenceFallback} from './simple-completion';
+export {projectEnginePresentation} from './simple-engine-presentation';
+export {materialAtPosition,materialAlongLine,materialForVariations} from './material-accounting';
+export {resolveAndSelectPlan,parseExplainPlanRequest} from './poc-plan-model';
+export type {PlanEntityHypothesis,PlanRelationHypothesis,PlanHypothesisSet,ExplainPlanRequest,ResolvedPlanExplanation} from './poc-plan-model';
+export {prepareSimpleEvidence} from './simple-evidence-preparation';
+export {forcedWinPremiseFallback} from './simple-fallback-premise';
+export {simpleBoardAnalysis} from './simple-board-analysis';
+export {preparedMoveComparison} from './initial-search-plan';
+export {normalizedEvidenceCitations} from './evidence-citation-normalization';
+export {savedScorePresentation} from './saved-score-presentation';
+export {scoreComparisonNotices} from './score-comparison-notices';
+export {projectMaterial,DEFAULT_MATERIAL_FORMAT} from './material-format';
+export type {MaterialFormat} from './material-format';
+export {expandMechanismPresentation,compactMechanism} from './mechanism-presentation';
+export {SimpleFactDelivery} from './simple-fact-delivery';
+export {consolidatePreparedSearches} from './preparation-consolidation';
+export {recordedSelectedClassification} from './recorded-selected-classification';
+export {createToolInputLoopGuard} from './tool-input-loop-guard';
+export {visibleSupportLines} from './visible-support-lines';
+export {wikibooksTargetsForTool} from './wikibooks-tool-context';
+export {prepareOpponentThreats} from './opponent-threat-preparation';
+export type {SaliencePolicy} from './poc-contracts';
+export type {ValidatedReasoningAnswer} from './poc-contracts';
+export type {ReasoningRuntimeDiagnostic} from './poc-contracts';
+export type {ReasoningSemanticPreservationSignal} from './poc-contracts';
+export {REASONING_POC_MAX_CRITIC_OUTPUT_TOKENS} from './poc-contracts';
+export type {ReasoningHypothesisRecord} from './poc-contracts';
+export type {ReasoningObservationCoverage} from './poc-contracts';
+export {ModelRuntimeFailure} from './poc-contracts';
+export {REASONING_POC_MAX_DISCOURSE_OUTPUT_TOKENS} from './poc-contracts';
+export type {ModelDiscoursePlanRequest} from './poc-contracts';
+export type {ModelDiscoursePlanResult} from './poc-contracts';
+export type {ReasoningHarnessPhase} from './poc-contracts';
+export {REASONING_POC_MAX_HYPOTHESIS_OUTPUT_TOKENS} from './poc-contracts';
+export {REASONING_POC_MAX_OUTPUT_TOKENS} from './poc-contracts';
+export {REASONING_POC_RESERVED_MANDATORY_STEPS} from './poc-contracts';
+export type {HypothesisProviderInput} from './poc-contracts';
+export type {ModelRunRequest} from './poc-contracts';
+export type {ReasoningChallengeDecision} from './poc-contracts';
+export {REASONING_POC_MAX_GRAPH_SELECTION_OUTPUT_TOKENS} from './poc-contracts';
+export type {HypothesisProvider} from './poc-contracts';
+export type {HypothesisProviderResult} from './poc-contracts';
+export {REASONING_POC_MAX_RENDER_OUTPUT_TOKENS} from './poc-contracts';
+export type {ModelDraftRepairRequest} from './poc-contracts';
+export type {ModelDraftRepairResult} from './poc-contracts';
+export type {ModelRenderRequest} from './poc-contracts';
+export type {ModelRenderResult} from './poc-contracts';
+export type {ReasoningDraft} from './poc-contracts';
+export type {ReasoningModelNarrativeSegment} from './poc-contracts';
+export type {ReasoningNarrativeSegment} from './poc-contracts';
+export type {ReasoningReferenceScope} from './poc-contracts';
+export type {ReasoningRenderDraft} from './poc-contracts';
+export {REASONING_POC_MAX_PURPOSE_PROBE_OUTPUT_TOKENS} from './poc-contracts';
+export {REASONING_POC_MAX_RESOLUTION_AUDIT_OUTPUT_TOKENS} from './poc-contracts';
+export {REASONING_POC_MAX_TERMINAL_REVIEW_OUTPUT_TOKENS} from './poc-contracts';
+export {REASONING_POC_CRITIC_CORRECTION_ALLOWANCE} from './poc-contracts';
+export {REASONING_POC_PURPOSE_PROBE_ALLOWANCE} from './poc-contracts';
+export {REASONING_POC_REVISION_EVIDENCE_ALLOWANCE} from './poc-contracts';
+export type {ModelRunResult} from './poc-contracts';
+export type {ModelSemanticStageReplayRequest} from './poc-contracts';
+export type {ModelSemanticStageReplayResult} from './poc-contracts';
+export type {BoardAnnotation} from './poc-contracts';
+export type {ReasoningClaim} from './poc-contracts';
+export type {ReasoningCheckpointReferenceBindings} from './poc-contracts';
+export type {ReasoningDemonstration} from './poc-contracts';
+export type {ReasoningDefenseCoverage} from './poc-contracts';
+export type {ReasoningDraftDemonstration} from './poc-contracts';
+export type {ReasoningGraphReference} from './poc-contracts';
+export type {ReasoningPieceReferenceForm} from './poc-contracts';
+export type {ReasoningValidationIssue} from './poc-contracts';
+export type {ResolvedReasoningNarrativeSegment} from './poc-contracts';
+export type {ValidatedReasoningClaim} from './poc-contracts';
+export type {ReasoningCheckpoint} from './poc-contracts';
+export {REASONING_DISCOURSE_PLAN_VERSION} from './poc-contracts';
+export type {ReasoningDiscourseDemonstrationIntent} from './poc-contracts';
+export type {ReasoningDiscourseParagraph} from './poc-contracts';
+export type {ReasoningDiscoursePlan} from './poc-contracts';
+export type {ReasoningDiscoursePlanDraft} from './poc-contracts';
+export type {ReasoningHypothesisRelationRecord} from './poc-contracts';
+export {REASONING_POC_MAX_HYPOTHESIS_BATCHES} from './poc-contracts';
+export type {ReasoningCompletionStage} from './poc-contracts';
+export type {ReasoningAudience} from './poc-contracts';
+export type {ReasoningGraphRequirements} from './poc-contracts';
+export type {ReasoningRenderMetrics} from './poc-contracts';
+export type {ReasoningToolTrace} from './poc-contracts';
+export type {ReasoningPieceKind} from './poc-contracts';
+export type {ReasoningObservationDecision} from './poc-contracts';
+export type {ReasoningInteractionCoverage} from './poc-contracts';
+export type {ReasoningNarrativeOutcome} from './poc-contracts';
+export type {ReasoningCriticFinding} from './poc-contracts';
+export type {ReasoningCriticFindingResolution} from './poc-contracts';
+export type {ReasoningCriticResolutionAudit} from './poc-contracts';
+export type {ReasoningCheckpointEvidenceSummary} from './poc-contracts';
+export type {ReasoningModelDraft} from './poc-contracts';
+export type {ReasoningSemanticReplayStage} from './poc-contracts';
+export type {ReasoningEvidenceKind} from './poc-contracts';
+export type {ReasoningToolSupport} from './poc-contracts';
+export type {ReasoningHypothesisProvenance} from './poc-contracts';
+export type {ReasoningProbeRecipe} from './poc-contracts';
+export type {ReasoningRankedObservation} from './poc-contracts';
+export type {ReasoningHypothesisRelationProposal} from './poc-contracts';
+export type {ReasoningAnchorRequirement} from './poc-contracts';
+export type {ReasoningHypothesisProposal} from './poc-contracts';
+export type {ReasoningHypothesisStatus} from './poc-contracts';
+export type {ReasoningHypothesisDecision} from './poc-contracts';
+export type {ReasoningObservationDispositionState} from './poc-contracts';
+export type {ReasoningChallengeObservationAudit} from './poc-contracts';
+export type {ReasoningCriticFindingKind} from './poc-contracts';
+export type {ReasoningCriticFindingResolutionDisposition} from './poc-contracts';
+export type {ReasoningCriticResolutionAuditDecision} from './poc-contracts';
+export type {ReasoningClaimKind} from './poc-contracts';
+export type {ReasoningMoveInput} from './poc-contracts';
+export type {ResolvedReasoningMove} from './poc-contracts';
+export type {ReasoningClaimScope} from './poc-contracts';
+export type {ReasoningModelDraftClaim} from './poc-contracts';
+export type {ReasoningModelDraftDemonstration} from './poc-contracts';
+export type {ReasoningRenderNarrativeSegment} from './poc-contracts';
+export type {ReasoningRenderDraftClaim} from './poc-contracts';
+export type {ReasoningRenderDraftDemonstration} from './poc-contracts';
+export type {ReasoningDiscourseRole} from './poc-contracts';
+export type {ReasoningDiscourseRelationAction} from './poc-contracts';
+export type {ReasoningStructuralOutcome} from './poc-contracts';
+export {selectSimpleModel} from './simple-agent-config';
+export {SIMPLE_EXTENSION_CONFIGS} from './simple-agent-config';
+export {SIMPLE_VENDOR_CONFIGS} from './simple-agent-config';
+export {EVALUATED_ASTRA_CONFIG} from './simple-agent-config';
+export {EVIDENCE_SHARING_INSTRUCTIONS} from './lossless-evidence-sharing';
+export {EVIDENCE_SHARING_GUIDANCE_CHARS} from './lossless-evidence-sharing';
+export * from './answer-pipeline-exports';

package/src/chess-reasoning/saved-score-presentation.ts

@@ -0,0 +1,6 @@
+/** Stored numeric mate sentinels are bookkeeping, never centipawn evidence. */
+export function savedScorePresentation(a: {beforeCp:number|null;afterCp:number|null;lossCp:number|null;mateBefore:number|null;mateAfter:number|null}) {
+  const finiteCp=(cp:number|null,mate:number|null)=>mate!==null || cp!==null&&Math.abs(cp)>=100000 ? null : cp;
+  const beforeCp=finiteCp(a.beforeCp,a.mateBefore),afterCp=finiteCp(a.afterCp,a.mateAfter);
+  return {beforeCp,afterCp,lossCp:a.mateBefore!==null||a.mateAfter!==null||beforeCp===null||afterCp===null||a.lossCp===9999?null:a.lossCp,mateBefore:a.mateBefore,mateAfter:a.mateAfter};
+}

package/src/chess-reasoning/score-comparison-notices.ts

@@ -0,0 +1,115 @@
+import type { ReasoningEvidenceRecord } from './poc-contracts';
+import { matchedRootComparison } from './matched-comparison';
+import type { PositionAnalysisResult } from './poc-tools';
+
+const object = (value: unknown): Record<string, unknown> | null =>
+  value !== null && typeof value === 'object' && !Array.isArray(value) ? value as Record<string, unknown> : null;
+const finite = (value: unknown): value is number => typeof value === 'number' && Number.isFinite(value);
+const strings = (value: unknown): string[] => Array.isArray(value) ? value.filter((v): v is string => typeof v === 'string') : [];
+type Score = { unit: 'centipawns' | 'mate-in-moves'; value: number };
+type Observation = {
+  evidenceId: string; source: string; score: Score; reportedDepth: number | null; actualDepth: number | null;
+  requestedDepth: number | null; requestedMultiPv: number | null;
+  rootScope: 'restricted' | 'unrestricted'; requestedRootMoves: string[];
+  cacheProvenance: string; sourceCacheProvenance: string;
+  engine: string | null; engineBuild: string | null;
+  scoreProvenance?: Record<string, unknown>;
+};
+export type ScoreComparisonNotice = {
+  fen: string; rootMove: string; perspective: 'white' | 'black';
+  disagreementKind: 'centipawn-variation' | 'mate-status-disagreement' | 'opposite-mate-sign' | 'mate-distance-variation';
+  observations: Observation[]; preferredWithinSearchComparisonEvidenceIds: string[];
+  interpretation: string;
+};
+
+function disagreementKind(observations: Observation[]): ScoreComparisonNotice['disagreementKind'] {
+  const mates = observations.filter(observation => observation.score.unit === 'mate-in-moves').map(observation => observation.score.value);
+  if (mates.length !== observations.length) return mates.length ? 'mate-status-disagreement' : 'centipawn-variation';
+  if (mates.some(value => value > 0) && mates.some(value => value < 0)) return 'opposite-mate-sign';
+  return 'mate-distance-variation';
+}
+
+const sharedInterpretation = 'Different search results for the same root move; equal requested depth does not make their search scope, actual depth, cache or search history equivalent. Preserve each scoped score. For relative move comparisons prefer alternatives covered together at the same actual depth in the identified comparison records; this supports a relative claim within that search, not independent confirmation or rejection of a mate result. Do not combine scores from separate searches into a move-loss estimate. This notice alone does not require another search.';
+const interpretationFor = (kind: ScoreComparisonNotice['disagreementKind']): string => {
+  const qualification = kind === 'mate-status-disagreement'
+    ? 'Mate status differs: a centipawn score in another search does not refute its mating continuation, and mate distances cannot be converted to centipawns. '
+    : kind === 'opposite-mate-sign'
+      ? 'The mate signs oppose, indicating different reported mating sides; retain each search scope and inspect the underlying continuations. '
+      : kind === 'mate-distance-variation'
+        ? 'The searches report different mate distances; mate distances are not centipawns. '
+        : 'The searches report different centipawn evaluations. ';
+  return qualification + sharedInterpretation;
+};
+
+function originatingRootDepth(line: Record<string, unknown>, search: Record<string, unknown>, fen: string): number | null {
+  const provenance = object(line.scoreProvenance);
+  if (provenance) return provenance.kind === 'root-search' && provenance.fen === fen &&
+    finite(provenance.originatingDepth) && Number.isInteger(provenance.originatingDepth) && provenance.originatingDepth > 0
+    && provenance.originatingDepth === line.depth ? provenance.originatingDepth : null;
+  // Old direct engine records predate scoreProvenance. Widget display-cache
+  // depths may instead describe a later position and cannot be promoted here.
+  const source = search.sourceCacheProvenance ?? search.cacheProvenance;
+  return source === 'engine' && finite(line.depth) && Number.isInteger(line.depth) && line.depth > 0 ? line.depth : null;
+}
+
+/** Presentation-only qualification. Does not reconcile numeric truth or initiate searches. */
+export function scoreComparisonNotices(records: readonly ReasoningEvidenceRecord[]): ScoreComparisonNotice[] {
+  const groups = new Map<string, { fen: string; rootMove: string; perspective: 'white' | 'black'; observations: Observation[]; matched: Set<string> }>();
+  for (const record of records) {
+    const wrapper = object(record.data);
+    const data = object(wrapper?.details) ?? wrapper;
+    const search = object(data?.searchScope);
+    if (!data || !search || typeof search.fen !== 'string' || !Array.isArray(data.lines)) continue;
+    const fen = search.fen;
+    const perspective = fen.split(' ')[1] === 'w' ? 'white' : fen.split(' ')[1] === 'b' ? 'black' : null;
+    if (!perspective) continue;
+    const roots = strings(search.requestedRootMoves);
+    const lines = data.lines.map(object).filter((line): line is Record<string, unknown> => !!line);
+    const scoped = (line: Record<string, unknown>) => {
+      const scope = object(line.scoreScope);
+      return scope?.fen === fen && scope.perspective === perspective && scope.positiveMeans === 'advantage for perspective color';
+    };
+    // A restricted probe is useful for relative comparisons only if all requested
+    // alternatives were returned with a common actual depth and explicit root scope.
+    const comparedRoots = roots.length ? roots : lines.map(line => String(line.rootMove));
+    const matched = (!roots.length || record.coverage?.complete === true && roots.every(root => record.coverage!.covered.includes(root))) &&
+      matchedRootComparison({...data,command:search.command,cacheProvenance:search.cacheProvenance,sourceCacheProvenance:search.sourceCacheProvenance} as unknown as PositionAnalysisResult,fen,comparedRoots).status === 'matched';
+    for (const line of lines) {
+      if (typeof line.rootMove !== 'string' || !scoped(line)) continue;
+      const scope = object(line.scoreScope)!;
+      let score: Score;
+      if (finite(line.matePly) && scope.matePlyUnit === 'signed mate-in-moves (legacy field name, not plies)') {
+        score = { unit: 'mate-in-moves', value: line.matePly };
+      } else if (line.matePly == null && finite(line.scoreCp) && Math.abs(line.scoreCp) < 100000 && scope.scoreCpUnit === 'centipawns') {
+        score = { unit: 'centipawns', value: line.scoreCp };
+      } else continue;
+      const key = JSON.stringify([fen, line.rootMove, perspective]);
+      let group = groups.get(key);
+      if (!group) { group = { fen, rootMove: line.rootMove, perspective, observations: [], matched: new Set() }; groups.set(key, group); }
+      // Reusing an evidence record is not a second independent evaluation.
+      if (group.observations.some(observation => observation.evidenceId === record.id)) continue;
+      group.observations.push({ evidenceId: record.id, source: record.source, score,
+        reportedDepth: finite(line.depth) ? line.depth : null,
+        actualDepth: originatingRootDepth(line, search, fen),
+        requestedDepth: finite(search.requestedDepth) ? search.requestedDepth : null,
+        requestedMultiPv: finite(search.requestedMultiPv) ? search.requestedMultiPv : null,
+        rootScope: roots.length ? 'restricted' : 'unrestricted', requestedRootMoves: roots,
+        cacheProvenance: typeof search.cacheProvenance === 'string' ? search.cacheProvenance : 'unreported',
+        sourceCacheProvenance: typeof search.sourceCacheProvenance === 'string' ? search.sourceCacheProvenance : 'unreported',
+        engine: typeof data.engine === 'string' ? data.engine : null,
+        engineBuild: typeof data.engineBuild === 'string' ? data.engineBuild : null,
+        ...(object(line.scoreProvenance) ? { scoreProvenance: line.scoreProvenance as Record<string, unknown> } : {}),
+      });
+      if (matched && comparedRoots.includes(line.rootMove)) group.matched.add(record.id);
+    }
+  }
+  return [...groups.values()].filter(group => new Set(group.observations.map(observation => JSON.stringify(observation.score))).size > 1)
+    .map(group => {
+      const kind = disagreementKind(group.observations);
+      return { fen: group.fen, rootMove: group.rootMove, perspective: group.perspective,
+        disagreementKind: kind,
+        observations: group.observations, preferredWithinSearchComparisonEvidenceIds: [...group.matched],
+        interpretation: interpretationFor(kind),
+      };
+    });
+}