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

package/src/chess-reasoning/causal-claim-checks.ts

@@ -0,0 +1,256 @@
+import { Chess, type Square } from 'chess.js';
+import { historicalProseRoots, type RecordedReferenceLine } from './historical-prose';
+import { simpleProseReferences } from './simple-prose-references';
+import type { ReasoningEvidenceRecord, ReasoningPositionContext } from './poc-contracts';
+
+export type CausalClaimCheck = {
+  claim: string;
+  /** Half-open UTF-16 offsets into the final reference-repaired answer. */
+  claimRange: { start: number; end: number };
+  sentenceContext: { text: string; start: number; end: number };
+  reference: string;
+  predicate: 'moving-piece-escape' | 'stationary-slider-ray' | 'square-control-release';
+  verdict: 'supported' | 'contradicted' | 'unresolved';
+  reason: string;
+};
+
+const names: Record<string, string> = { rook: 'r', bishop: 'b', queen: 'q', knight: 'n', pawn: 'p', king: 'k' };
+const uci = /^[a-h][1-8][a-h][1-8][qrbn]?$/;
+const pieceBinding = /\b(the|a|white(?:'s|’s)?|black(?:'s|’s)?|your)\s+(rook|bishop|queen|knight|pawn|king)\s+(?:on|at)\s+([a-h][1-8])\b/i;
+const compactBinding = /\b([RBQNKP])([a-h][1-8])\b/;
+
+/** Mask markup punctuation without changing string offsets (including surrogate pairs). */
+function sentenceRanges(answer: string) {
+  const masked = answer.replace(/\[[^\]\n]+\]\([^\n)]*\)/g, text => ' '.repeat(text.length))
+    .replace(/\b\d+\.(?:\.\.)?/g, text => ' '.repeat(text.length));
+  const ranges: Array<{start:number;end:number}> = [];
+  let start = 0;
+  for (const boundary of masked.matchAll(/[.!?](?:[”"’']?)(?=\s|$)|\n+/g)) {
+    const end = boundary.index + boundary[0].length;
+    ranges.push({start,end});
+    start = end;
+  }
+  ranges.push({start,end:answer.length});
+  return ranges;
+}
+
+function trimRange(answer:string, start:number, end:number) {
+  while(start<end && /\s/.test(answer[start])) start++;
+  while(end>start && /\s/.test(answer[end-1])) end--;
+  return {start,end};
+}
+
+function binding(clause: string): {type:string;at:Square;color?:'w'|'b'}|null {
+  const all=[...clause.matchAll(new RegExp(pieceBinding.source,'gi'))];
+  const compact=[...clause.matchAll(new RegExp(compactBinding.source,'g'))];
+  const identities=[...all.map(match=>`${names[match[2].toLowerCase()]}:${match[3]}`),
+    ...compact.map(match=>`${match[1].toLowerCase()}:${match[2]}`)];
+  if(new Set(identities).size>1)return null;
+  const named=clause.match(pieceBinding);
+  if(named) return {type:names[named[2].toLowerCase()],at:named[3] as Square,
+    color:/^white/i.test(named[1])?'w':/^black/i.test(named[1])?'b':undefined};
+  return compact[0] ? {type:compact[0][1].toLowerCase(),at:compact[0][2] as Square} : null;
+}
+
+function direction(from:Square,to:Square):[number,number]|null {
+  const dx=to.charCodeAt(0)-from.charCodeAt(0),dy=Number(to[1])-Number(from[1]);
+  if(!dx && !dy || dx && dy && Math.abs(dx)!==Math.abs(dy))return null;
+  return [Math.sign(dx),Math.sign(dy)];
+}
+
+function ray(board:Chess,from:Square,to:Square):boolean {
+  const d=direction(from,to);
+  if(!d)return false;
+  let file=from.charCodeAt(0)+d[0],rank=Number(from[1])+d[1];
+  while(file!==to.charCodeAt(0)||rank!==Number(to[1])) {
+    if(board.get(`${String.fromCharCode(file)}${rank}` as Square))return false;
+    file+=d[0];rank+=d[1];
+  }
+  return true;
+}
+
+function parseTarget(target:string, historical:ReturnType<typeof historicalProseRoots>, label:string,
+  context:ReasoningPositionContext, records:readonly ReasoningEvidenceRecord[],recordedLine?:RecordedReferenceLine) {
+  const match=/^game:(0|[1-9]\d*):([a-h1-8qrbn,]+)$/.exec(target);
+  if(!match)return null;
+  const root=historical.roots.get(Number(match[1]));
+  if(!root)return null;
+  const path=match[2].split(',');
+  if(!path.length||path.length>32||path.some(move=>!uci.test(move)))return null;
+  try {
+    const before=new Chess(root.context.fenAfter);
+    const start=new Chess(before.fen());
+    let san='';
+    for(const move of path) {
+      const actual=before.move({from:move.slice(0,2),to:move.slice(2,4),promotion:move[4]});
+      if(actual.from+actual.to+(actual.promotion??'')!==move) return null;
+      san=actual.san;
+    }
+    const last=path.at(-1)!;
+    // A recorded path must reproduce the frozen record, not merely be legal.
+    const recorded=historical.recorded?.slice(Number(match[1]),Number(match[1])+path.length);
+    if(recorded?.length===path.length && recorded.every((move,i)=>move===path[i])) {
+      // witnessed recorded path
+    } else if(!root.records.length || simpleProseReferences(`[${label}](${target})`,context,records,recordedLine).coverage.resolved!==1) return null;
+    // Only single-move links have unambiguous move-local prose binding here.
+    if(path.length!==1)return { ambiguous:true as const };
+    const fields=start.fen().split(' ');
+    const notation=label.trim().match(/^(?:(\d+)\s*(\.{1,3}|…)\s*)?([^\s]+)$/);
+    if(!notation||notation[3].replace(/[!?]+$/,'')!==san
+      || notation[1] && (Number(notation[1])!==Number(fields[5])||(notation[2]==='.'?'w':'b')!==fields[1])) return null;
+    return {ambiguous:false as const,before:start,after:before,from:last.slice(0,2) as Square,to:last.slice(2,4) as Square};
+  }catch{return null;}
+}
+
+/** Bounded geometry diagnostics only. No answer modification, strategic judgment or intent inference. */
+export function checkCausalClaims(answer:string,context:ReasoningPositionContext,
+  records:readonly ReasoningEvidenceRecord[],recordedLine?:RecordedReferenceLine):CausalClaimCheck[] {
+  const historical=historicalProseRoots(context,records,recordedLine);
+  const output:CausalClaimCheck[]=[];
+  const sentences=sentenceRanges(answer);
+  const links=[...answer.matchAll(/\[([^\]\n]+)\]\(([^)\n]+)\)/g)];
+  let sentenceIndex=0;
+  for(const [linkIndex,match] of links.entries()) {
+    const [full,label,reference]=match;
+    if(!reference.startsWith('game:'))continue;
+    const index=match.index;
+    while(sentences[sentenceIndex].end<=index && sentenceIndex<sentences.length-1)sentenceIndex++;
+    const sentence=trimRange(answer,sentences[sentenceIndex].start,sentences[sentenceIndex].end);
+    const previous=links[linkIndex-1],next=links[linkIndex+1];
+    // Neighbouring links cannot lend their piece binding to this move.
+    const claimRange=trimRange(answer,Math.max(sentence.start,previous?previous.index+previous[0].length:0),
+      Math.min(sentence.end,next?.index??answer.length));
+    const left=answer.slice(claimRange.start,index).replace(/[*_`]/g,'');
+    const right=answer.slice(index+full.length,claimRange.end).replace(/[*_`]/g,'');
+    // The SAN label names the move, not a second piece in the explanatory prose.
+    const clause=`${left} ${right}`.trim();
+    // Readable context is complete, but predicate recognition stays local.
+    // Longer sentences must not attach a later subject's action to this move.
+    const local=right.slice(0,90);
+    const escape=/\b(?:escap(?:e|ed|es|ing)|fle(?:e|d)|evad(?:e|ed|es|ing))\b/i.test(local)
+      || /\bmoved?\s+out\s+of\s+attack\b/i.test(local)
+      || /\b(?:escap(?:e|ed|es|ing)|fle(?:e|d)|evad(?:e|ed|es|ing))\s+(?:with|by|on)\s*$/i.test(left);
+    const presentAttack=/\b(?:escap(?:e|ed|es|ing)|fle(?:e|d)|evad(?:e|ed|es|ing))\s+(?:from\s+)?(?:(?:the|an?)\s+)?(?:(?:rook|bishop|queen|knight|pawn|king)['’]s\s+)?attack\b/i.test(local)
+      || /\bmoved?\s+out\s+of\s+attack\b/i.test(local);
+    const targets=[...local.matchAll(/\b(?:toward(?:s)?|to|along)\s+([a-h][1-8])\b/gi)];
+    const slider=/\b(?:open(?:s|ed|ing)?|clear(?:s|ed|ing)?|block(?:s|ed|ing)?|clos(?:e|es|ed|ing))\b/i.exec(local);
+    const competingSliderVerbs=[...local.matchAll(/\b(?:open(?:s|ed|ing)?|clear(?:s|ed|ing)?|block(?:s|ed|ing)?|clos(?:e|es|ed|ing))\b/gi)];
+    const release=/\b(?:releas(?:e|es|ed|ing)|los(?:e|es|t|ing)|no longer controls?)\s+(?:control\s+(?:of|over)\s+)?([a-h][1-8])\b/i.exec(local);
+    if(!escape&&!slider&& !release)continue;
+    let parsedReady=false,parsedValue:ReturnType<typeof parseTarget>;
+    const parsed=()=>{
+      if(!parsedReady){parsedValue=parseTarget(reference,historical,label,context,records,recordedLine);parsedReady=true;}
+      return parsedValue;
+    };
+    const negated=/\b(?:not|never|didn't|did not|doesn't|does not)\b/i.test(clause);
+    const strategicConclusion=/\b(?:force(?:d|s)?|mate|tempo|wins?|winning)\b/i.test(clause);
+    const result=(predicate:CausalClaimCheck['predicate'],verdict:CausalClaimCheck['verdict'],reason:string)=>
+      output.push({claim:answer.slice(claimRange.start,claimRange.end),claimRange,
+        sentenceContext:{...sentence,text:answer.slice(sentence.start,sentence.end)},reference,predicate,
+        verdict:negated||strategicConclusion?'unresolved':verdict,
+        reason:negated?'Negated mechanism wording is outside this narrow check.'
+          :strategicConclusion?'This clause mixes geometry with a forcing, mating, winning or tempo claim.':reason});
+    if(escape) {
+      let bound=binding(clause);
+      const directEscape=/^\s*[,;:]?\s*(?:both\s+)?(?:escapes?|escaped|evades?|evaded|flees?|fled|moves?\s+out\s+of\s+attack)\b/i.test(local);
+      // Only a direct finite verb with a neutral lead-in licenses the move as
+      // grammatical subject. This is not general pronoun or noun resolution.
+      const moveSubject=/^\s*(?:(?:instead|however|then|here|but|and|now)[,:]?\s*)?$/i.test(left)
+        && directEscape;
+      if(!bound && moveSubject && !pieceBinding.test(clause) && !compactBinding.test(clause)) {
+        const move=parsed();
+        if(move && !move.ambiguous) {
+          const mover=move.before.get(move.from);
+          if(mover)bound={type:mover.type,at:move.from,color:mover.color};
+        }
+      }
+      // A condition before another link can still qualify this whole sentence.
+      const futureOrConditional=/\b(?:if|unless|future|potential|possible|could|might|may|would|will|later|threat|threatened|threatening|preemptive|anticipat(?:e|ed|ing))\b/i
+        .test(answer.slice(sentence.start,sentence.end));
+      if(!directEscape||!presentAttack||futureOrConditional)result('moving-piece-escape','unresolved','Escape wording does not unambiguously assert a present attack on the moving piece.');
+      else if(!bound)result('moving-piece-escape','unresolved','Move or moving piece is not uniquely bound to a witnessed single move and square.');
+      else {
+        const move=parsed();
+        if(!move||move.ambiguous)result('moving-piece-escape','unresolved','Move is not uniquely bound to a witnessed single ply.');
+        else {
+        const mover=move.before.get(move.from);
+        if(!mover||bound.at!==move.from||bound.type!==mover.type||bound.color&&bound.color!==mover.color)result('moving-piece-escape','unresolved','Named piece does not identify the moving piece at the referenced ply.');
+        else {
+          const attacked=move.before.attackers(move.from,mover.color==='w'?'b':'w').length>0;
+          const stillAttacked=move.after.attackers(move.to,mover.color==='w'?'b':'w').length>0;
+          const attackerType=/\b(rook|bishop|queen|knight|pawn|king)['’]s\s+attack\b/i.exec(local)?.[1]?.toLowerCase();
+          if(attackerType && !move.before.attackers(move.from,mover.color==='w'?'b':'w')
+            .some(square=>move.before.get(square)?.type===names[attackerType])) {
+            result('moving-piece-escape','unresolved','The named kind of attacker is not established on the starting square.');
+            continue;
+          }
+          result('moving-piece-escape',!attacked?'contradicted':stillAttacked?'unresolved':'supported',!attacked
+            ?'The moving piece was not geometrically attacked on its starting square.'
+            :stillAttacked?'The piece was attacked on both squares; whether this was an escape is not established.'
+              :'The moving piece left an attacked square for a geometrically unattacked square; safety or necessity is not established.');
+        }
+        }
+      }
+    }
+    // Opening a file or keeping the center closed describes a wider structure,
+    // not necessarily a ray from a stationary slider. Enter this predicate only
+    // when prose explicitly names both the piece and a target square.
+    const explicitSliderRay=slider && targets.length>0 &&
+      (pieceBinding.test(clause)||compactBinding.test(clause));
+    if(explicitSliderRay) {
+      const bound=binding(clause),wantOpen=/^(?:open|clear)/i.test(slider[0]);
+      if(!bound||targets.length!==1||competingSliderVerbs.length!==1)
+        result('stationary-slider-ray','unresolved','Slider, target ray, causal clause or referenced move is ambiguous.');
+      else {
+        const move=parsed();
+        if(!move||move.ambiguous) {
+          result('stationary-slider-ray','unresolved','Referenced move is not a witnessed single ply.');
+          continue;
+        }
+        const target=targets[0];
+        const piece=move.before.get(bound.at),same=move.after.get(bound.at);
+        const d=direction(bound.at,target[1] as Square);
+        const namedAxis=new RegExp(`\\b(diagonal|rank|file)\\s+(?:toward(?:s)?|to|along)\\s+${target[1]}\\b`,'i').exec(local)?.[1]?.toLowerCase();
+        const axis=d ? d[0]&&d[1]?'diagonal':d[0]?'rank':'file' : null;
+        const valid=piece&&same&&piece.type===bound.type&&same.type===piece.type&&same.color===piece.color&&(!bound.color||bound.color===piece.color)
+          && (piece.type==='q'||piece.type==='r'&&d&&(!d[0]||!d[1])||piece.type==='b'&&d&&!!d[0]&&!!d[1]);
+        if(piece&&same&&piece.type===bound.type&&same.type===piece.type&&same.color===piece.color&&(!bound.color||bound.color===piece.color)&&(!d||namedAxis&&namedAxis!==axis))
+          result('stationary-slider-ray','contradicted','The named target is not on the claimed ray from the stationary piece.');
+        else if(!valid)result('stationary-slider-ray','unresolved','The named stationary slider or its geometric ray is not established at this ply.');
+        else {
+          const previous=ray(move.before,bound.at,target[1] as Square),next=ray(move.after,bound.at,target[1] as Square);
+          const changed=wantOpen?!previous&&next:previous&&!next;
+          result('stationary-slider-ray',changed?'supported':'contradicted',
+            `The named ray was ${previous?'clear':'blocked'} before and ${next?'clear':'blocked'} after the move; this checks geometry only.`);
+        }
+      }
+    }
+    // Explicit source piece and target square only. A bare 'releases g4' has no controller.
+    if(release) {
+      const bound=binding(clause),target=release[1] as Square;
+      if(!bound)result('square-control-release','unresolved','Controlling piece or referenced ply is ambiguous.');
+      else {
+        const move=parsed();
+        if(!move||move.ambiguous) {
+          result('square-control-release','unresolved','Referenced move is not a witnessed single ply.');
+          continue;
+        }
+        const piece=move.before.get(bound.at);
+        if(!piece||piece.type!==bound.type||bound.color&&bound.color!==piece.color)result('square-control-release','unresolved','Named controller is not on its stated square before the move.');
+        else {
+          const prior=move.before.attackers(target,piece.color).includes(bound.at);
+          const finalSquare=bound.at===move.from?move.to:bound.at;
+          const nextPiece=move.after.get(finalSquare);
+          if(!nextPiece||nextPiece.color!==piece.color||nextPiece.type!==piece.type)
+            result('square-control-release','unresolved','The named controller cannot be tracked across this move.');
+          else {
+            const current=move.after.attackers(target,piece.color).includes(finalSquare);
+            result('square-control-release',prior&&!current?'supported':'contradicted',
+              `The named piece ${prior?'controlled':'did not control'} ${target} before and ${current?'controls':'does not control'} it after the move.`);
+          }
+        }
+      }
+    }
+  }
+  return output;
+}

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

@@ -0,0 +1,21 @@
+/** Stable, position-independent geometry. a1 is dark, regardless of orientation. */
+export type SquareColor = 'light' | 'dark';
+
+export function chessSquareColor(square: string): SquareColor | null {
+  if (!/^[a-h][1-8]$/.test(square)) return null;
+  return (square.charCodeAt(0) - 97 + Number(square[1]) - 1) % 2 === 0 ? 'dark' : 'light';
+}
+
+const squares = Array.from({ length: 64 }, (_, i) =>
+  `${String.fromCharCode(97 + i % 8)}${1 + Math.floor(i / 8)}`);
+
+/** Grouping is a complete square->colour dictionary without 64 repeated keys. */
+export const CHESS_REFERENCE_DICTIONARY = Object.freeze({
+  version: 'square-colors-v1',
+  scope: 'Position-independent square colors; not piece ownership or a position assessment.',
+  squareColors: Object.freeze({
+    light: Object.freeze(squares.filter(square => chessSquareColor(square) === 'light')),
+    dark: Object.freeze(squares.filter(square => chessSquareColor(square) === 'dark')),
+  }),
+  use: 'A bishop occupies squares of its color complex. Identify the bishop and the relevant position before applying this reference; do not infer which bishop a move frees from square colors alone.',
+});

package/src/chess-reasoning/classification-question-target.ts

@@ -0,0 +1,30 @@
+import type { ReasoningPositionContext } from './poc-contracts';
+import {hasMoveClassificationQuestion,type QuestionRoutingDecision} from './question-routing';
+
+const normalizedSan=(san:string)=>san.replace(/[+#?!]+$/,'');
+/** Question-only notation extraction; these are references, not verified moves. */
+export function classificationQuestionMoveReferences(question:string) {
+  const pattern=/(?<![A-Za-z0-9])(?:(\d+)\s*(\.{1,3}|…)\s*)?(O-O(?:-O)?|[KQRBN][a-h]?[1-8]?x?[a-h][1-8](?:=[QRBN])?|[a-h]x?[a-h]?[1-8](?:=[QRBN])?)[+#]?(?![A-Za-z0-9])/g;
+  return [...question.matchAll(pattern)].map(match=>({san:normalizedSan(match[3]),moveNumber:match[1]?Number(match[1]):null,color:match[2]?(match[2]==='.'?'w':'b'):null}));
+}
+/** Resolve wording against frozen context AFTER Jev; never change board selection. */
+export function classificationTargetAtSelection(decision:QuestionRoutingDecision,question:string,context:ReasoningPositionContext) {
+  if(!hasMoveClassificationQuestion(decision))return {applies:false,resolution:'no-classification'};
+  if(context.kind==='position'||!context.moveUci)return {applies:false,resolution:'no-played-selection'};
+  const reference=decision.answers?.classification_reference?.choice;
+  if(reference==='selection_relative')return {applies:true,resolution:'selection-relative'};
+  // An affirmative classification intent plus the existing local-reference head
+  // can resolve a contradictory/missing secondary head, only without named moves.
+  const localReference=decision.answers?.local_reference;
+  if((!reference||reference==='none')&&localReference?.type==='choice'&&localReference.choice==='yes'&&classificationQuestionMoveReferences(question).length===0)
+    return {applies:true,resolution:'unnamed-local-classification'};
+  if(reference!=='named_move')return {applies:false,resolution:reference==='other_relative'?'other-relative':'unresolved-reference'};
+  const references=classificationQuestionMoveReferences(question);
+  const unique=[...new Map(references.map(ref=>[JSON.stringify(ref),ref])).values()];
+  // Multiple distinct named moves require model-directed disambiguation. Never
+  // silently make an alternative or quoted/other named move the selected target.
+  if(unique.length!==1)return {applies:false,resolution:'ambiguous-named-reference',references};
+  const ref=unique[0],fields=context.fenBefore.split(' ');
+  const matches=ref.san===normalizedSan(context.moveSan)&&(!ref.moveNumber||ref.moveNumber===Number(fields[5]))&&(!ref.color||ref.color===fields[1]);
+  return {applies:matches,resolution:matches?'named-selected-move':'named-other-move',references};
+}

package/src/chess-reasoning/classification-reassessment.ts

@@ -0,0 +1,34 @@
+import type { SimpleBoardAnalysis } from './simple-board-analysis';
+
+/** Preserve decision provenance without repeating the full board-analysis snapshots. */
+export function classificationReassessment(previous: SimpleBoardAnalysis | undefined, current: SimpleBoardAnalysis | undefined) {
+  const previousLabel = previous?.snapshot.classification;
+  const currentLabel = current?.snapshot.classification;
+  const sameContext = Boolean(previous && current && previous.record.contextHash === current.record.contextHash);
+  const labelChanged = sameContext && Boolean(previousLabel && currentLabel && previousLabel !== currentLabel);
+  const superseded = Boolean(sameContext && currentLabel && previous!.snapshot.evidenceId !== current!.snapshot.evidenceId);
+  const summary = (analysis: NonNullable<SimpleBoardAnalysis>, role: 'previous-analysis' | 'current-analysis') => ({
+    role,
+    evidenceId: analysis.snapshot.evidenceId,
+    classification: analysis.snapshot.classification,
+    lossCp: analysis.snapshot.evaluation.lossCp,
+    recordedRequestedDepth: analysis.snapshot.recordedRequestedDepth,
+    beforeDepth: analysis.snapshot.beforeDepth,
+    afterDepth: analysis.snapshot.afterDepth,
+  });
+  return {
+    version: 'classification-reassessment/1',
+    status: !currentLabel ? 'current-decision-unavailable' : !previousLabel ? 'original-decision-unavailable' : !sameContext ? 'context-mismatch' : labelChanged ? 'changed' : 'unchanged',
+    labelChanged,
+    preparationRequestedDepth: 18,
+    ...(previous ? {previous: {
+      ...summary(previous, 'previous-analysis'),
+      ...(superseded ? {superseded: true, supersededBy: current!.snapshot.evidenceId} : {}),
+      ...(labelChanged ? {recordedReason: previous.snapshot.recordedReason} : {}),
+    }} : {}),
+    ...(current && (sameContext || !previous) ? {current: summary(current, 'current-analysis')} : {}),
+    limitation: 'These are attributed canonical decisions before and after preparation, not causal proof. preparationRequestedDepth is the preparation search request, not the recorded depth of every classification dependency. The full current analysis is in boardAnalysis; retrieve the previous evidenceId for omitted historical detail. A missing or mismatched decision does not establish a classification change.',
+  };
+}
+
+export const CLASSIFICATION_REASSESSMENT_GUIDANCE = `For questions that include the selected move's classification, Knight's Eye may prepare a deeper before-position search and refresh the board's canonical classification before answering. classificationReassessment contains compact decision summaries: the current full analysis is in boardAnalysis; previous is an attributed historical summary, superseded only for a matching current context. retrieve_evidence with the previous evidenceId restores omitted historical details when needed. preparationRequestedDepth names the preparation request, not the recorded depth of either decision. When classificationReassessment.status is changed and labelChanged is true, acknowledge the change explicitly in first-person Knight's Eye language, for example: “I had a better look at this move and changed its classification from Great to Best because …”. Use the previous recordedReason and the current boardAnalysis decision details to explain the supported reason. Distinguish why we originally assigned the old label from why the refreshed decision differs; do not defend an outdated label as the current one. A changed score with an unchanged label is not a classification change. If the original or current decision, its reason, or the search is unavailable, state the material uncertainty and never invent a change or explanation. A recorded candidate-gap flag is a bounded policy signal, not proof that only one move preserves a favorable position.`;

package/src/chess-reasoning/compact-search-preparation.ts

@@ -0,0 +1,125 @@
+import { presentMoveMechanisms } from './mechanism-presentation';
+import { Chess } from 'chess.js';
+import type { MaterialFormat } from './material-format';
+import type { ReasoningEvidenceRecord, ReasoningToolResult } from './poc-contracts';
+import { compactSimpleEngineResult } from './simple-evidence-view';
+
+type Obj = Record<string, unknown>;
+const object = (value: unknown): value is Obj => value !== null && typeof value === 'object' && !Array.isArray(value);
+const known = (value: Obj, keys: readonly string[]) => Object.keys(value).every(key => keys.includes(key));
+const detailsKeys = [
+  'phase', 'rootMoves', 'rootSelection', 'bestMove', 'engine', 'engineBuild', 'searchScope',
+  'rootMoveFacts', 'continuationMoveFacts', 'lines', 'minimumPvPlies',
+  'requestedPvCoverage', 'authority', 'branchExpansion',
+] as const;
+const lineKeys = [
+  'multipv', 'rootMove', 'pv', 'depth', 'nodes', 'scoreCp', 'matePly', 'scoreScope', 'scoreProvenance',
+  'rawPv', 'pvCompletion', 'material',
+] as const;
+const completionKeys = ['requestedPlies', 'actualPlies', 'status', 'conditional', 'segments'] as const;
+const segmentKeys = [
+  'fen', 'startPly', 'depth', 'pv', 'scoreCp', 'matePly', 'scoreScope', 'scoreProvenance',
+  'command', 'engine', 'engineBuild', 'cacheProvenance',
+] as const;
+
+/** The initial projection must not silently discard a new engine field. */
+export function compactSearchRecord(record: ReasoningEvidenceRecord, playedMove?: string): ReasoningEvidenceRecord | null {
+  const data = record.data as Obj;
+  if (!known(data, ['recordedPosition', 'details']) || !object(data.recordedPosition) || !object(data.details)) return null;
+  const recordedPosition = data.recordedPosition;
+  const details = data.details;
+  if (!known(details, detailsKeys) || !object(details.searchScope) || typeof details.searchScope.fen !== 'string'
+    || !Array.isArray(details.lines) || !details.lines.length || !Array.isArray(details.continuationMoveFacts)) return null;
+  const positionKeys = ['recordHash', 'ply', 'startFen', 'fen', 'historyUci', 'rootContextHash', 'nextRecordedMove', 'scope'];
+  if (!known(recordedPosition, positionKeys) || !Number.isInteger(recordedPosition.ply)
+    || typeof recordedPosition.fen !== 'string') return null;
+
+  const strongestOther = details.lines.find(line => object(line) && line.rootMove !== playedMove);
+  const mechanismAlternative = details.bestMove && details.bestMove !== playedMove ? details.bestMove
+    : object(strongestOther) ? strongestOther.rootMove : details.bestMove;
+  const lines: Obj[] = [];
+  for (const line of details.lines) {
+    if (!object(line) || !known(line, lineKeys) || !Array.isArray(line.pv)
+      || !line.pv.every(move => typeof move === 'string')
+      || typeof line.rootMove !== 'string' || !object(line.pvCompletion)
+      || !known(line.pvCompletion, completionKeys) || !Array.isArray(line.pvCompletion.segments)) return null;
+    // SAN is useful to the answering model; derive it from the exact rooted PV,
+    // never from move-number strings that may belong to another position.
+    let pvSan: string[];
+    try {
+      const board = new Chess(details.searchScope.fen);
+      pvSan = line.pv.map(move => {
+        if (!/^[a-h][1-8][a-h][1-8][qrbn]?$/.test(move)) throw Error('invalid PV move');
+        const replayed = board.move({from:move.slice(0,2),to:move.slice(2,4),promotion:move.slice(4)||undefined});
+        if (!replayed) throw Error('illegal PV move');
+        return replayed.san;
+      });
+    } catch { return null; }
+    const segments: Obj[] = [];
+    for (const segment of line.pvCompletion.segments) {
+      if (!object(segment) || !known(segment,segmentKeys)
+        || !Array.isArray(segment.pv) || !Number.isInteger(segment.startPly)) return null;
+      const start = segment.startPly as number;
+      const same = start >= 0 && JSON.stringify(line.pv.slice(start,start+segment.pv.length)) === JSON.stringify(segment.pv);
+      const {pv: _pv, ...remaining} = segment;
+      void _pv;
+      segments.push(same ? {...remaining,pvFromLinePly:start,pvLength:segment.pv.length} : {...remaining,pv:segment.pv});
+    }
+    const {segments:_segments, ...completion} = line.pvCompletion;
+    void _segments;
+    const material = object(line.material) && object(line.material.start) && object(line.material.end)
+      ? {authority:line.material.authority,
+          startBalance:line.material.start.balance,
+          endBalance:line.material.end.balance,
+          balanceChangeFromStart:line.material.balanceChangeFromStart,
+          scope:line.material.scope}
+      : undefined;
+    // rawPv is sometimes different from the displayed continuation. Retain it
+    // in that case; only equal bytes may be omitted.
+    const separateRawPv = Array.isArray(line.rawPv)
+      && JSON.stringify(line.rawPv) !== JSON.stringify(line.pv) ? {rawPv:line.rawPv} : {};
+    const continuation = details.continuationMoveFacts.find(f => object(f) && f.rootMove === line.rootMove);
+    const mechanismRelevant = line.rootMove === playedMove || line.rootMove === mechanismAlternative
+      || (!mechanismAlternative && lines.length === 0);
+    const mechanismFacts = mechanismRelevant && object(continuation) && Array.isArray(continuation.moves) ? presentMoveMechanisms(continuation.moves) : [];
+    lines.push({
+      ...(object(continuation) && Array.isArray(continuation.moves) ? {mechanismAvailablePlies:continuation.moves.length} : {}),
+      ...(mechanismFacts.length ? {mechanismFacts} : {}),
+      ...(line.multipv !== undefined ? {multipv:line.multipv} : {}), rootMove:line.rootMove,
+      ...(playedMove ? {playedMove:playedMove === line.rootMove} : {}), pv:line.pv, pvSan,
+      depth:line.depth, scoreCp:line.scoreCp, matePly:line.matePly,
+      scoreScope:line.scoreScope, ...(line.scoreProvenance ? {scoreProvenance:line.scoreProvenance} : {}), pvCompletion:{...completion,segments},
+      ...(material ? {materialSummary:material} : {}), ...separateRawPv,
+    });
+  }
+  const {historyUci:_historyUci, ...root} = recordedPosition;
+  void _historyUci;
+  const {rootMoveFacts:_rootMoveFacts,continuationMoveFacts:_continuationMoveFacts,lines:_lines,...search} = details;
+  void _rootMoveFacts; void _continuationMoveFacts; void _lines;
+  const projection = {
+    ...record,
+    data:{recordedPosition:root,details:{...search,lines,
+      modelPresentation:{scope:'compact initial preparation only; supplied PVs are complete, mechanismFacts cover first two plies for played and strongest roots with scoped control targets; deeper geometry remains retrievable',
+        mechanismRoots:lines.filter(line=>Array.isArray(line.mechanismFacts)).map(line=>line.rootMove),
+        omitted:['otherRootMechanisms','rootMoveFacts','continuationMoveFacts','captureGeometry','materialCheckpoints','duplicatePvSegmentMoves'],
+        retrieveFullEvidenceId:record.id,
+        segmentPvReference:'A segment with pvFromLinePly=N and pvLength=L repeats exactly L moves of that line.pv starting at zero-based index N; its own depth, score, FEN, command and cache provenance remain specific to that segment.',
+        instruction:'For deeper or omitted geometry, other control squares, piece identities or material checkpoints, call retrieve_evidence with this evidence ID. This reuses the acquired record without another engine search. mechanismAvailablePlies states the retained geometry horizon; inspect later moves with test_game_line/inspectPlies.'}}},
+    // replay duplicates the full PV arrays. The PVs above remain available for
+    // game links, while the immutable replay stays in the authoritative record.
+    replay:null,
+  };
+  return projection as ReasoningEvidenceRecord;
+}
+
+/** Only automatic preparation is thinned. The caller keeps the original tool
+ * result in its evidence ledger and observable trace for retrieval/replay. */
+export function compactPreparedSearchResult(result: ReasoningToolResult, playedMove?: string, format?: MaterialFormat): unknown {
+  const packet = {
+    contextHash:result.contextHash,
+    evidence:result.evidence.map(record => compactSearchRecord(record,playedMove) ?? record),
+    limitations:[...result.limitations,
+      'Initial preparation shows complete supplied PV moves and bounded scores, with first-two-ply mechanism measurements for played/strongest roots, but omits deeper geometry and material checkpoints. retrieve_evidence(evidenceIds) returns the already acquired full records without a new search.'],
+  };
+  return compactSimpleEngineResult(packet,format);
+}