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

package/test/owner/move-mechanism-facts.test.mjs

@@ -0,0 +1,105 @@
+import assert from 'node:assert/strict';
+import test from 'node:test';
+import { Chess } from 'chess.js';
+import { moveMechanismFacts } from '../../src/chess-reasoning/move-mechanism-facts.ts';
+import { applyIdentityMove, createIdentityState } from '../../src/chess-reasoning/piece-identities.ts';
+
+function facts(fen, uci, suppliedIdentities = true) {
+  const before = new Chess(fen);
+  const beforeIds = createIdentityState(fen);
+  const { state: afterIds } = applyIdentityMove(beforeIds, {
+    from: uci.slice(0, 2), to: uci.slice(2, 4), promotion: uci.slice(4) || undefined,
+  });
+  const after = new Chess(afterIds.fen);
+  return moveMechanismFacts(before, after, uci.slice(0, 2), uci.slice(2, 4),
+    ...(suppliedIdentities ? [beforeIds, afterIds] : []));
+}
+
+test('KE-REASON-016/021: Rb2+ mover is unattacked while the unmoved rook on d1 is attacked from a4', () => {
+  const observed = facts('1k1r3r/2p5/p2p1p2/2P2B2/b3PB1p/5P2/3R2PP/2KR4 w - - 1 25', 'd2b2');
+  assert.equal(observed.mover.pieceId, 'white-rook:d2:0');
+  assert.deepEqual(observed.mover.attackersBefore, []);
+  assert.deepEqual(observed.mover.attackersAfter, []);
+  assert.deepEqual(observed.attackedUnmovedFriendlyPieces.find((piece) => piece.square === 'd1'), {
+    pieceId: 'white-rook:d1:0', square: 'd1', pieceType: 'r',
+    attackersBefore: ['a4'], attackersAfter: ['a4'],
+  });
+  assert.ok(observed.checksRun.includes('unmoved-friendly-piece-geometric-attackers-before-after'));
+  assert.match(observed.scope, /geometric measurements/i);
+});
+
+test('KE-REASON-016/021: after 7...b6, e5 frees the queen d4 horizontal ray through f4-h4, not a8', () => {
+  // Recorded main-line first 14 plies, exact position before White's eighth move.
+  const observed = facts('r1bqkb1r/p1pp1pp1/1p3n1p/8/2BQP3/2N5/PPP2PPP/R1B1K2R w KQkq - 0 8', 'e4e5');
+  const east = observed.stationarySliderRays.find((item) => item.fromSquare === 'd4' && item.direction === 'E');
+  assert.deepEqual(east?.beforeSquares, ['e4']);
+  assert.deepEqual(east?.afterSquares, ['e4', 'f4', 'g4', 'h4']);
+  assert.deepEqual(east?.gainedSquares, ['f4', 'g4', 'h4']);
+  assert.ok(!observed.stationarySliderRays.some((item) => item.fromSquare === 'd4' && item.gainedSquares.includes('a8')));
+  assert.deepEqual(observed.controlDelta.find((item) => item.square === 'g4' && item.color === 'w')?.attackersAfter, ['d4']);
+});
+
+test('KE-REASON-016/021: control loss occurs at the actual knight move, not the prior pawn push', () => {
+  const rootFen = 'r1bqkb1r/p1pp1pp1/1p3n1p/8/2BQP3/2N5/PPP2PPP/R1B1K2R w KQkq - 0 8';
+  const pawnPush = facts(rootFen, 'e4e5');
+  assert.equal(pawnPush.controlDelta.find((item) => item.square === 'd5' && item.color === 'b'), undefined);
+  const afterPawnPush = new Chess(rootFen);
+  afterPawnPush.move({ from: 'e4', to: 'e5' });
+  const knightMove = facts(afterPawnPush.fen(), 'f6h7');
+  assert.deepEqual(knightMove.controlDelta.find((item) => item.square === 'd5' && item.color === 'b'), {
+    square: 'd5', color: 'b', attackersBefore: ['f6'], attackersAfter: [],
+  });
+  assert.deepEqual(knightMove.mover.attackersBefore, ['e5']);
+});
+
+test('KE-REASON-016/021: moving slider is not reported as stationary opening, even along same file', () => {
+  const rootFen = 'k1B5/1R6/p2B1p2/8/4P2p/5P2/6PP/2K2b2 w - - 7 34';
+  const observed = facts(rootFen, 'b7b2');
+  assert.ok(!observed.stationarySliderRays.some((item) => item.pieceId === observed.mover.pieceId));
+  assert.ok(!observed.stationarySliderRays.some((item) => item.fromSquare === 'b7' || item.fromSquare === 'b2'));
+  const afterRook = new Chess(rootFen);
+  afterRook.move({ from: 'b7', to: 'b2' });
+  const response = facts(afterRook.fen(), 'f1b5');
+  const blocked = response.stationarySliderRays.find((item) => item.fromSquare === 'b2' && item.direction === 'N');
+  assert.deepEqual(blocked?.beforeSquares, ['b3', 'b4', 'b5', 'b6', 'b7', 'b8']);
+  assert.deepEqual(blocked?.afterSquares, ['b3', 'b4', 'b5']);
+  assert.deepEqual(blocked?.lostSquares, ['b6', 'b7', 'b8']);
+});
+
+test('KE-REASON-016/021: Bf7+, queen promotion and bishop underpromotion have exact mover identities and controls', () => {
+  const bishop = facts('8/4P3/1R2B3/6Bk/7P/8/8/2K5 w - - 3 50', 'e6f7');
+  assert.equal(bishop.mover.pieceId, bishop.mover.pieceIdAfter);
+  assert.equal(bishop.mover.pieceTypeBefore, 'b');
+  assert.deepEqual(bishop.controlDelta.find((item) => item.square === 'e8' && item.color === 'w')?.attackersAfter, ['f7']);
+  assert.deepEqual(bishop.controlDelta.find((item) => item.square === 'g4' && item.color === 'w'), {
+    square: 'g4', color: 'w', attackersBefore: ['e6'], attackersAfter: [],
+  });
+  const mateFen = '8/4P3/1R2B3/6Bk/7P/8/8/2K5 w - - 3 50';
+  for (const uci of ['e7e8q', 'e7e8b']) {
+    const promotionMate = new Chess(mateFen);
+    promotionMate.move({ from: 'e7', to: 'e8', promotion: uci.slice(4) });
+    assert.equal(promotionMate.isCheckmate(), true, `${uci} is a legal mate at the observed board`);
+    assert.equal(facts(mateFen, uci).mover.pieceTypeAfter, uci.slice(4));
+  }
+  const promotionFen = '8/4P3/1R2B3/6B1/7P/5k2/8/2K5 w - - 7 52';
+  const queen = facts(promotionFen, 'e7e8q');
+  const underpromotion = facts(promotionFen, 'e7e8b', false);
+  assert.equal(queen.mover.pieceTypeAfter, 'q');
+  assert.equal(underpromotion.mover.pieceTypeAfter, 'b');
+  assert.notEqual(queen.mover.pieceId, queen.mover.pieceIdAfter);
+  assert.match(queen.mover.pieceIdAfter, /promotion:e8/);
+  assert.ok(queen.controlDelta.some((entry) => entry.square === 'e7' && entry.color === 'w'));
+  assert.ok(!underpromotion.controlDelta.some((entry) => entry.square === 'e7' && entry.color === 'w'));
+});
+
+test('KE-REASON-016/021: en passant removes the off-target blocker and castling excludes the moved rook', () => {
+  const ep = facts('7k/8/8/3pP3/8/8/8/K2R4 w - d6 0 1', 'e5d6');
+  assert.deepEqual(ep.controlDelta.find((item) => item.square === 'e4' && item.color === 'b'), {
+    square: 'e4', color: 'b', attackersBefore: ['d5'], attackersAfter: [],
+  });
+  assert.deepEqual(ep.stationarySliderRays.find((item) => item.fromSquare === 'd1' && item.direction === 'N')?.afterSquares,
+    ['d2', 'd3', 'd4', 'd5', 'd6']);
+  const castle = facts('4k3/8/8/8/8/8/8/4K2R w K - 0 1', 'e1g1');
+  assert.ok(!castle.stationarySliderRays.some((item) => item.pieceId === 'white-rook:h1:0'));
+  assert.equal(castle.mover.toSquare, 'g1');
+});

package/test/owner/pipeline-host-preparation.test.mjs

@@ -0,0 +1,115 @@
+import test from 'node:test';
+import assert from 'node:assert/strict';
+import {Chess} from 'chess.js';
+import {runAnswerPipeline,createProductionObservationProvider,QUESTION_ROUTING_VERSION,simpleSystemPolicy,simpleToolDescription,toPositionAnalysis,toLegacyPositionAnalysis,toPositionAnalysisProvider,toLegacyPositionAnalysisProvider} from '../../src/chess-reasoning/answer-pipeline-exports.ts';
+const fen=new Chess().fen();
+const context={kind:'position',nodeId:'root',historyStartFen:fen,historyUci:[],moveUci:'',moveSan:'',fenBefore:fen,fenAfter:fen};
+function setup(invoke,options={}) {
+ const selected={deliveryId:'answer-test',selectionKey:'root',edgeId:'root',context,existingAnalysis:null};
+ const question='Assess the current position';
+ return {requestId:'portable-test',question,selected,modelName:'deterministic-test',connector:{kind:'model-turn',invoke},
+  policy:{system:simpleSystemPolicy,description:simpleToolDescription},observationProvider:createProductionObservationProvider({context,question}),
+  prepareRouting:async()=>({question,selectionKey:'root',deliveryId:'answer-test',elapsedMs:0,omitSelectedContext:false,
+   decision:{version:QUESTION_ROUTING_VERSION,status:'fallback',omitSelectedContext:false,includeGameRecord:false,reviewGame:false,reason:'explicit-consumer-position',answers:{answer_scope:{choice:'position_analysis',confidence:1}}}}),...options};
+}
+function reply(text='',toolCalls=[]) {return {text,toolCalls,finishReason:toolCalls.length?'tool-calls':'stop',usage:{inputTokens:20,outputTokens:10},response:{messages:[{role:'assistant',content:toolCalls.length?toolCalls.map(c=>({type:'tool-call',...c})):text}]}};}
+function analyzer(log) {return {async analyze(request){log.push(request);const board=new Chess(request.fen);const legal=board.moves({verbose:true});const roots=request.rootMoves.length?request.rootMoves:legal.slice(0,request.multiPv).map(m=>m.from+m.to+(m.promotion??''));return {engine:'deterministic-legal-test',engineBuild:'test-only',command:'test',bestMove:roots[0]??null,lines:roots.map(root=>{const b=new Chess(request.fen);b.move({from:root.slice(0,2),to:root.slice(2,4),promotion:root.slice(4)||undefined});const pv=[root];while(pv.length<(request.minimumPvPlies??1)&&!b.isGameOver()){const m=b.moves({verbose:true})[0];pv.push(m.from+m.to+(m.promotion??''));b.move(m);}return {rootMove:root,pv,depth:request.depth,nodes:1,scoreCp:0,matePly:null};})};}};}
+test('KE-AI-PORT-001: existing preparation, genuine legal tools, resumable evidence and composition',async()=>{
+ let turn=0;const searches=[];const events=[];
+ const result=await runAnswerPipeline(setup(async request=>{
+  turn++;assert.match(request.system,/Knight/);assert.ok(request.tools.every(t=>t.inputSchema&&typeof t.inputSchema==='object'));
+  if(turn===1){assert.ok(searches.length>0);assert.match(JSON.stringify(request.messages),/initial-search/);return reply('',[{toolCallId:'inspect-1',toolName:'inspect_position',input:{phase:'before',squares:['e2']}}]);}
+  if(turn===2){assert.match(JSON.stringify(request.messages),/tool-result/);assert.match(JSON.stringify(request.messages),/inspect-1/);return reply('',[{toolCallId:'line-1',toolName:'test_line',input:{phase:'before',movesUci:['e2e4','e7e5'],analyzeFinal:false}}]);}
+  assert.match(JSON.stringify(request.messages),/line-1/);return reply('Both sides can develop their pieces.');
+ },{analyzer:analyzer(searches),observableTraceSink:e=>events.push(e)}));
+ assert.equal(result.status,'diagnostic');assert.equal(result.answer,'Both sides can develop their pieces.');assert.equal(turn,3);
+ assert.ok(result.initialSearches.some(s=>s.status==='completed'));assert.equal(result.toolRuns.filter(s=>s.status==='completed').length,2);assert.ok(result.presentedEvidence.length>1);assert.ok(events.some(e=>e.stage==='simple-model'));
+});
+test('KE-AI-PORT-001: canonical six-turn reserve forces tool-free composition',async()=>{
+ let turn=0;
+ const result=await runAnswerPipeline(setup(async request=>{turn++;if(request.toolChoice==='none'){assert.equal(turn,6);assert.equal(request.tools.length,0);return reply('The acquired evidence is limited.');}return reply('',[{toolCallId:'inspect-'+turn,toolName:'inspect_position',input:{phase:'before',squares:['e2']}}]);}));
+ assert.equal(turn,6);assert.equal(result.completionReason,'model-calls');assert.equal(result.toolCallsUsed,5);
+});
+test('KE-AI-PORT-001: search batch budget rejects nine requests before host execution',async()=>{
+ let turn=0;
+ const result=await runAnswerPipeline(setup(async request=>{turn++;if(turn===1)return reply('',[{toolCallId:'oversized',toolName:'search_batch',input:{requests:Array.from({length:9},(_,i)=>({queryId:'q'+i,tool:'test_line',input:{phase:'before',movesUci:['e2e4'],analyzeFinal:false}}))}}]);assert.match(JSON.stringify(request.messages),/invalid-tool-array/);return reply('The requested batch was too large.');}));
+ assert.equal(result.toolRuns[0].status,'failed');assert.equal(result.searchesUsed,0);
+});
+test('KE-AI-PORT-001: cancellation after model response prevents tool execution',async()=>{
+ const controller=new AbortController();
+ const result=await runAnswerPipeline(setup(async()=>{controller.abort();return reply('',[{toolCallId:'cancelled',toolName:'inspect_position',input:{phase:'before',squares:['e2']}}]);},{signal:controller.signal}));
+ assert.equal(result.status,'failure');assert.equal(result.toolRuns.length,0);assert.equal(result.answer,'');
+});
+test('KE-AI-PORT-001: unknown usage reserves output allowance without claiming measurement',async()=>{
+ const result=await runAnswerPipeline(setup(async()=>({...reply('A bounded answer.'),usage:{}})));
+ assert.equal(result.status,'diagnostic');assert.equal(result.usage.metering,'partly-unavailable');assert.equal(result.usage.reportedOutputTokens,null);assert.equal(result.usage.reportedInputTokens,null);assert.equal(result.usage.outputBudgetReservation,6000);assert.equal(result.usage.unmeteredCalls,1);
+});
+test('KE-AI-PORT-001: exact recorded history is frozen and retrieved through host port',async()=>{
+ let reads=0,turn=0;
+ const line={startFen:fen,moves:[{uci:'e2e4',san:'e4',edgeId:'e1'},{uci:'e7e5',san:'e5',edgeId:'e2'}],selectedIndex:-1,selectedAtStart:true,totalPlies:2,truncated:false};
+ const result=await runAnswerPipeline(setup(async request=>{turn++;if(turn<3)return reply('',[{toolCallId:'history-'+turn,toolName:'get_main_line',input:{}}]);assert.match(JSON.stringify(request.messages),/e2e4/);assert.match(JSON.stringify(request.messages),/recordedMainLine/);return reply('The recorded game began with central pawn moves.');},{bridge:{getMainLine:async()=>{reads++;return line;}}}));
+ assert.equal(reads,1);assert.equal(result.acquiredMainLines.length,2);assert.equal(result.acquiredMainLines[0].moves[1].san,'e5');
+});
+test('KE-AI-PORT-001: malformed connector batches fail closed before any valid prefix executes',async()=>{
+ const valid={toolCallId:'first',toolName:'inspect_position',input:{phase:'before',squares:['e2']}};
+ for(const invalid of [{...valid},{...valid,toolCallId:''},{...valid,toolCallId:'second',toolName:'unknown'},{...valid,toolCallId:'second',input:[]},{...valid,toolCallId:'second',input:null}]) {
+  const result=await runAnswerPipeline(setup(async()=>reply('',[valid,invalid])));
+  assert.equal(result.status,'failure');assert.equal(result.toolRuns.length,0);assert.equal(result.toolCallsUsed,0);
+ }
+ const result=await runAnswerPipeline(setup(async()=>reply('',Array.from({length:33},(_,i)=>({...valid,toolCallId:'call-'+i})))));
+ assert.equal(result.status,'failure');assert.equal(result.toolRuns.length,0);
+});
+
+test('KE-REASON-034: signed-moves adapters preserve attributed legacy records and conditional segments',async()=>{
+ const provenance={kind:'restored-fallback',engineBuild:'historical-build',originatingDepth:11};
+ const scope={fen,perspective:'white',positiveMeans:'advantage for perspective color',scoreCpUnit:'centipawns',matePlyUnit:'signed mate-in-moves (legacy field name, not plies)'};
+ const legacy={engine:'historical-engine',engineBuild:'historical-build',command:'historical',bestMove:'e2e4',cacheProvenance:'browser-completed-cache',sourceCacheProvenance:'widget-analysis-cache',
+  lines:[{rootMove:'e2e4',pv:['e2e4'],rawPv:['e2e4'],depth:11,nodes:42,scoreCp:null,matePly:-3,scoreScope:scope,scoreProvenance:provenance,
+   pvCompletion:{requestedPlies:10,actualPlies:1,status:'short-budget',conditional:true,segments:[{fen,startPly:1,depth:8,pv:['e7e5'],scoreCp:null,matePly:2,scoreScope:{...scope,perspective:'black'},scoreProvenance:provenance,command:'historical-endpoint',engine:'historical-engine',engineBuild:'historical-build',cacheProvenance:'restored-fallback'}]}}]};
+ const frozen=JSON.stringify(legacy);
+ const preferred=toPositionAnalysis(legacy);
+ assert.equal(preferred.lines[0].mateInMoves,-3);assert.equal('matePly' in preferred.lines[0],false);
+ assert.equal(preferred.lines[0].pvCompletion.segments[0].mateInMoves,2);
+ assert.equal(preferred.lines[0].scoreScope.mateInMovesUnit,'signed mate-in-moves');
+ assert.equal('matePlyUnit' in preferred.lines[0].scoreScope,false);
+ assert.deepEqual(preferred.lines[0].scoreProvenance,provenance);
+ assert.deepEqual(toLegacyPositionAnalysis(preferred),legacy);
+ assert.equal(JSON.stringify(legacy),frozen);
+ for(const mate of [null,0,3,-5]){
+  const result={...legacy,lines:[{...legacy.lines[0],matePly:mate}]};
+  assert.deepEqual(toLegacyPositionAnalysis(toPositionAnalysis(result)),result);
+ }
+});
+
+test('KE-REASON-034: conflicting aliases, invalid distances and units fail closed including segments',async()=>{
+ const result={engine:'test',engineBuild:'test',command:'test',bestMove:null,lines:[{rootMove:'e2e4',pv:['e2e4'],depth:1,nodes:null,scoreCp:null,mateInMoves:2}]};
+ for(const convert of [toPositionAnalysis,toLegacyPositionAnalysis]){
+  for(const value of [{matePly:3},{matePly:null},{mateInMoves:1.5},{mateInMoves:Infinity},{mateInMoves:undefined},{mateInMoves:'2'},{scoreScope:{mateInMovesUnit:'plies'}},{scoreScope:{matePlyUnit:'plies'}}]){
+   assert.throws(()=>convert({...result,lines:[{...result.lines[0],...value}]}),TypeError);
+  }
+  assert.throws(()=>convert({...result,lines:[{...result.lines[0],pvCompletion:{segments:[{matePly:1,mateInMoves:2}]}}]}),/Conflicting/);
+  const {mateInMoves:_,...missing}=result.lines[0];void _;
+  assert.throws(()=>convert({...result,lines:[missing]}),/Missing/);
+  assert.equal(convert({...result,lines:[{...result.lines[0],matePly:2}]}).lines.length,1);
+ }
+});
+
+test('KE-REASON-034: preferred analyzer and explicit legacy analyzer produce identical answer evidence',async()=>{
+ const oldSearches=[],newSearches=[];
+ const old=await runAnswerPipeline(setup(async()=>reply('The evidence is bounded.'),{analyzer:analyzer(oldSearches)}));
+ const modern=await runAnswerPipeline(setup(async()=>reply('The evidence is bounded.'),{analyzer:toPositionAnalysisProvider(analyzer(newSearches))}));
+ assert.equal(modern.answer,old.answer);assert.equal(modern.status,old.status);
+ assert.deepEqual(modern.presentedEvidence,old.presentedEvidence);
+ assert.equal(newSearches.length,oldSearches.length);
+ assert.ok(newSearches.length>0);
+});
+
+test('KE-REASON-034: analyzer adapters forward exact requests and reject pre/post completion cancellation',async()=>{
+ for(const wrap of [toPositionAnalysisProvider,toLegacyPositionAnalysisProvider]){
+  let calls=0;const controller=new AbortController();
+  const request={fen,depth:18,multiPv:3,rootMoves:[],signal:controller.signal};
+  const provider=wrap({async analyze(received){calls++;assert.equal(received,request);controller.abort(new Error('stop-adapter'));return {engine:'test',engineBuild:'test',command:'test',bestMove:null,lines:[]};}});
+  await assert.rejects(provider.analyze(request),/stop-adapter/);assert.equal(calls,1);
+  await assert.rejects(provider.analyze(request),/stop-adapter/);assert.equal(calls,1);
+ }
+});

package/test/owner/position-preparation.test.mjs

@@ -0,0 +1,22 @@
+import test from 'node:test';
+import assert from 'node:assert/strict';
+import {Chess} from 'chess.js';
+import {planInitialSearches} from '../../src/chess-reasoning/initial-search-plan.ts';
+const context={kind:'position',nodeId:'root',historyStartFen:'rnbq1rk1/p1p1bpp1/1p3n1p/3p4/3P3B/2N1PN2/PP3PPP/R2QKB1R w KQ - 0 9',historyUci:[],moveUci:'',moveSan:''};
+context.fenBefore=context.fenAfter=context.historyStartFen;
+const input={context,question:'Assess the current position: what are the main strengths, weaknesses and plans for both sides?',answerScope:'position_analysis',omitSelectedContext:false};
+test('KE-REASON-021: prepare same actual position tool before first answering call',()=>{
+ const plan=planInitialSearches(input);assert.equal(plan.requests.length,1);assert.equal(plan.requests[0].tool,'explore_continuations');
+ assert.deepEqual(plan.requests[0].input,{phase:'before',depth:18,multiPv:3,minimumPvPlies:24});
+});
+test('retrospective, omitted, general, terminal and explicit ablation do not search an unrelated board',()=>{
+ for(const change of [{omitSelectedContext:true},{reviewGame:true},{answerScope:'general'},{positionPreparation:false}])assert.equal(planInitialSearches({...input,...change}).requests.length,0);
+ const terminal='7k/5Q2/6K1/8/8/8/8/8 b - - 0 1';assert.ok(new Chess(terminal).isGameOver());
+ assert.equal(planInitialSearches({...input,context:{...context,fenBefore:terminal,fenAfter:terminal}}).requests.length,0);
+});
+test('explicit current-node comparison takes precedence over broad preparation',()=>{
+ const p=planInitialSearches({...input,question:'Compare Bd3 and Be2 instead.'});assert.equal(p.requests.length,1);assert.equal(p.requests[0].tool,'compare_moves');
+});
+test('retained selected-move context assessment searches the after position',()=>{
+ const c={...context,kind:'move',moveUci:'e6d5',moveSan:'exd5'};assert.equal(planInitialSearches({...input,context:c}).requests[0].input.phase,'after');
+});

package/test/owner/preparation-consolidation.test.mjs

@@ -0,0 +1,74 @@
+import test from 'node:test';
+import assert from 'node:assert/strict';
+import {consolidatePreparedSearches} from '../../src/chess-reasoning/preparation-consolidation.ts';
+import {compactPreparedSearchResult} from '../../src/chess-reasoning/compact-search-preparation.ts';
+import {scoreComparisonNotices} from '../../src/chess-reasoning/score-comparison-notices.ts';
+const fen='rnbqkbnr/pppppppp/8/8/8/8/PPPPPPPP/RNBQKBNR w KQkq - 0 1';
+const scoreScope={fen,perspective:'white',positiveMeans:'advantage for perspective color',scoreCpUnit:'centipawns',matePlyUnit:'signed mate-in-moves (legacy field name, not plies)'};
+function record(id,restricted=false){
+ const roots=restricted?['d2d4','e2e4','b1c3']:['e2e4','d2d4'];
+ return {id,contextHash:'game',source:'Stockfish/'+(restricted?'compare_moves':'explore-continuations'),
+ data:{recordedPosition:{recordHash:'record',ply:0,startFen:fen,fen,historyUci:[],rootContextHash:'root'},details:{phase:'after',engine:'Stockfish',engineBuild:'test',searchScope:{fen,requestedDepth:18,requestedMultiPv:restricted?null:2,requestedRootMoves:restricted?roots:[],cacheProvenance:'engine'},rootMoveFacts:[],continuationMoveFacts:[],lines:roots.map((rootMove,i)=>({rootMove,pv:[rootMove],depth:18,scoreCp:50-i*10,matePly:null,scoreScope,pvCompletion:{requestedPlies:1,actualPlies:1,status:'complete',conditional:false,segments:[]}}))}},
+ coverage:{complete:restricted,covered:roots,unresolved:[]},licenses:['engine.bounded-comparison'],replay:{fen,linesUci:roots.map(x=>[x])}};
+}
+function entry(callId,record,discoveryCallId){
+ const result=compactPreparedSearchResult({contextHash:'game',evidence:[record],limitations:[]},'b1c3');
+ return {callId,records:[record],playedMove:'b1c3',discoveryCallId,modelRun:{callId,status:'completed',result}};
+}
+const pair=()=>[entry('discovery',record('evidence:discovery')),entry('comparison',record('evidence:comparison',true),'discovery')];
+test('KE-REASON-016/021/026: one primary comparison keeps original scores, order changes, dependency and retrieval identity',()=>{
+ const input=pair(),copy=structuredClone(input),notices=scoreComparisonNotices(input.flatMap(x=>x.records));
+ const out=consolidatePreparedSearches(input);
+ assert.equal(out.results.length,1);assert.deepEqual(out.results[0].result,input[1].modelRun.result);
+ assert.equal(out.results[0].discovery.evidenceId,'evidence:discovery');
+ assert.equal(out.results[0].discovery.retrieveFullEvidenceId,'evidence:discovery');
+ assert.deepEqual(out.results[0].discovery.scores.map(x=>[x.rootMove,x.scoreCp]),[['e2e4',50],['d2d4',40]]);
+ assert.deepEqual(out.results[0].discovery.comparisonOrderForDiscoveredMoves,['d2d4','e2e4']);
+ assert.equal(out.results[0].discovery.reportedOrderChanged,true);
+ assert.equal(out.diagnostics.dependencies[0].relation,'candidate-selection');
+ assert.equal(out.diagnostics.dependencies[0].primaryEvidenceId,'evidence:comparison');
+ assert.deepEqual(scoreComparisonNotices(input.flatMap(x=>x.records)),notices);assert.equal(notices.length,2);
+ assert.deepEqual(input,copy);
+});
+test('KE-REASON-016/021/026: distinct PVs and conditional segments remain explicitly discoverable by original ID',()=>{
+ const input=pair();const line=input[0].records[0].data.details.lines[0];line.pv.push('e7e5');line.pvCompletion.conditional=true;
+ input[0].modelRun.result=compactPreparedSearchResult({contextHash:'game',evidence:input[0].records,limitations:[]},'b1c3');
+ const out=consolidatePreparedSearches(input);assert.deepEqual(out.results[0].discovery.distinctContinuationRootMoves,['e2e4']);
+ assert.deepEqual(input[0].records[0].data.details.lines[0].pv,['e2e4','e7e5']);
+});
+test('KE-REASON-023/026: discovery-only delivered opening commentary survives consolidation',()=>{
+ const input=pair(),source={pages:[{title:'source',prose:'opening',matchedTargets:['original']}]};
+ input[0].modelRun.result={chessResult:input[0].modelRun.result,openingSourceContext:source};
+ assert.deepEqual(consolidatePreparedSearches(input).results[0].discoveryOpeningSourceContext,source);
+});
+test('KE-REASON-016/026: no omission for incomplete, failed, foreign, unrecognized, mixed-depth or unrelated results',()=>{
+ const changes=[
+ a=>a[1].modelRun.status='failed',a=>a[1].records[0].coverage.complete=false,
+ a=>a[1].records[0].coverage.covered.pop(),a=>a[1].records[0].data.details.lines.pop(),
+ a=>a[1].records[0].data.recordedPosition.ply=1,a=>a[1].records[0].contextHash='foreign',
+ a=>a[1].records[0].data.details.lines[0].depth=19,a=>a[1].records[0].data.details.lines[0].scoreScope={...scoreScope,perspective:'black'},
+ a=>a[0].records[0].data.details.newProducerField='retain',a=>a[1].discoveryCallId=undefined,
+ a=>a[1].playedMove=undefined,a=>a[0].records[0].data.details.lines[0].pv.push('a1a8'),
+ ];
+ for(const change of changes){const input=pair();change(input);const out=consolidatePreparedSearches(input);assert.deepEqual(out.results,input.map(e=>e.modelRun));assert.equal(out.diagnostics.summarizedDiscoveryCount,0);}
+ const only=[pair()[0]];assert.deepEqual(consolidatePreparedSearches(only).results,only.map(e=>e.modelRun));
+});
+
+test('KE-REASON-016/021/026: unverified cached comparison depth cannot authorize consolidation',()=>{
+ const input=pair();input[1].records[0].data.details.searchScope.sourceCacheProvenance='widget-analysis-cache';
+ assert.equal(consolidatePreparedSearches(input).results.length,2);
+ for(const line of input[1].records[0].data.details.lines)line.scoreProvenance={kind:'root-search',fen,originatingDepth:18};
+ input[0].records[0].data.details.lines[0].scoreProvenance={kind:'legacy-unknown',originatingDepth:null,reportedDepth:18};
+ assert.equal(consolidatePreparedSearches(input).results.length,2, 'known origins alone do not establish one search');
+ input[1].records[0].data.details.searchScope.sourceCacheProvenance='engine';
+ const out=consolidatePreparedSearches(input);
+ assert.equal(out.results.length,1);
+ assert.equal(out.results[0].discovery.scores[0].scoreProvenance.kind,'legacy-unknown');
+});
+
+test('KE-REASON-026: the original command remains authoritative when origins share a different command',()=>{
+ const input=pair(),details=input[1].records[0].data.details;
+ details.searchScope.command='go depth 18 searchmoves d2d4 e2e4 b1c3';
+ for(const line of details.lines)line.scoreProvenance={kind:'root-search',fen,originatingDepth:18,command:'go depth 26'};
+ assert.equal(consolidatePreparedSearches(input).results.length,2);
+});

package/test/owner/prose-reference-admission.test.mjs

@@ -0,0 +1,26 @@
+import test from 'node:test';
+import assert from 'node:assert/strict';
+import {Chess} from 'chess.js';
+import {simpleProseReferences,reasoningContextHash,admitFreshEnginePvWitnesses} from '../../src/chess-reasoning/answer-pipeline-exports.ts';
+
+test('fresh answer witnesses preserve shipped v22 reference geometry and reject foreign engine evidence',()=>{
+  const board=new Chess(),fen=board.fen();
+  const context={kind:'position',nodeId:'start',historyStartFen:fen,historyUci:[],moveUci:'',moveSan:'',fenBefore:fen,fenAfter:fen};
+  const witness={version:'fresh-engine-pv-witness/1',acquisition:'same-answer-engine',acquisitionId:1,
+    evidenceId:'server-engine-acquisition:1',contextHash:reasoningContextHash(context),phase:'before',fen,
+    engineBuild:'test-engine',command:'go depth 18',requestedDepth:18,multiPv:1,rootMoves:[],
+    authority:'bounded-engine',licenses:['engine.bounded-continuation'],
+    lines:[{rootMove:'e2e4',pv:['e2e4','e7e5'],depth:18,scoreCp:20,mateInMoves:null,
+      scoreProvenance:{kind:'root-search',fen,engineBuild:'test-engine',command:'go depth 18',originatingDepth:18,reportedDepth:18}}]};
+  const answer='[e5](move:before:e2e4,e7e5)';
+  const rendered=simpleProseReferences(answer,context,[],undefined,undefined,undefined,{freshEnginePvWitnesses:[witness]});
+  assert.equal(rendered.freshEnginePvAdmission.acceptedLines,1);
+  assert.equal(rendered.blocks[0].tokens[0].reference.position.moves.length,2);
+  assert.equal(rendered.blocks[0].tokens[0].reference.engineEvidence[0].evidenceId,witness.evidenceId);
+  assert.equal(rendered.referenceGapCounts.unresolvedReferences,0);
+  const foreign=structuredClone(witness);foreign.contextHash='foreign';
+  assert.equal(admitFreshEnginePvWitnesses(context,[foreign]).audit.acceptedLines,0);
+  const rejected=simpleProseReferences(answer,context,[],undefined,undefined,undefined,{freshEnginePvWitnesses:[foreign]});
+  assert.equal(rejected.referenceGapCounts.unresolvedReferences,1);
+  assert.equal(rejected.blocks[0].tokens[0].reference,undefined);
+});

package/test/owner/score-comparison-notices.test.mjs

@@ -0,0 +1,116 @@
+import test from 'node:test';
+import assert from 'node:assert/strict';
+import { scoreComparisonNotices } from '../../src/chess-reasoning/score-comparison-notices.ts';
+const fen='7k/8/8/8/8/8/8/KR6 w - - 0 1';
+function evidence(id,cp,comparison=false){
+ const roots=comparison?['b1b7','b1b2']:[];
+ const line=(rootMove,scoreCp)=>({rootMove,scoreCp,matePly:null,depth:18,scoreScope:{fen,perspective:'white',positiveMeans:'advantage for perspective color',scoreCpUnit:'centipawns',matePlyUnit:'signed mate-in-moves (legacy field name, not plies)'}});
+ return {id,source:`Stockfish/${comparison?'compare_moves':'explore-continuations'}`,coverage:{complete:comparison,covered:comparison?roots:['b1b7'],unresolved:comparison?[]:['non-enumerated alternatives']},data:{engine:'Stockfish',engineBuild:'18',searchScope:{fen,requestedDepth:18,requestedMultiPv:comparison?2:3,requestedRootMoves:roots,cacheProvenance:comparison?'engine':'browser-completed-cache',sourceCacheProvenance:comparison?'engine':'widget-analysis-cache'},lines:[line('b1b7',cp),...(comparison?[line('b1b2',1000)]:[])]}};
+}
+test('KE-REASON-016/021: qualify cached unrestricted versus matched comparison scores without changing evidence',()=>{
+ const a=evidence('a',1391),b=evidence('b',1256,true),records=[a,b],saved=structuredClone(records);
+ const [notice]=scoreComparisonNotices(records);
+ assert.deepEqual(records,saved);
+ assert.equal(notice.rootMove,'b1b7');assert.equal(notice.perspective,'white');
+ assert.deepEqual(notice.observations.map(o=>o.score),[{unit:'centipawns',value:1391},{unit:'centipawns',value:1256}]);
+ assert.deepEqual(notice.observations.map(o=>o.rootScope),['unrestricted','restricted']);
+ assert.deepEqual(notice.observations.map(o=>[o.reportedDepth,o.actualDepth]),[[18,null],[18,18]]);
+ assert.equal(notice.disagreementKind,'centipawn-variation');
+ assert.deepEqual(notice.preferredWithinSearchComparisonEvidenceIds,['b']);
+ assert.match(notice.interpretation,/does not require another search/);
+});
+test('KE-REASON-021: scope separates root positions and perspectives and excludes unscoped scores',()=>{
+ const a=evidence('a',1391),b=evidence('b',1256,true);
+ b.data.searchScope.fen=fen.replace('0 1','1 1');
+ assert.deepEqual(scoreComparisonNotices([a,b]),[]);
+ b.data.searchScope.fen=fen;b.data.lines[0].scoreScope.perspective='black';
+ assert.deepEqual(scoreComparisonNotices([a,b]),[]);
+ delete b.data.lines[0].scoreScope;
+ assert.deepEqual(scoreComparisonNotices([a,b]),[]);
+});
+test('KE-REASON-021: historical nested results retain scope; duplicates and equal scores create no notice',()=>{
+ const a=evidence('a',1391),b=evidence('b',1256,true);
+ b.data={recordedPosition:{ply:66},details:b.data};
+ assert.equal(scoreComparisonNotices([a,b,a]).length,1);
+ assert.equal(scoreComparisonNotices([a,b,a])[0].observations.length,2);
+ assert.deepEqual(scoreComparisonNotices([a,evidence('equal',1391)]),[]);
+});
+test('KE-REASON-021: mates remain typed distances and missing mate metadata cannot leak sentinel CP',()=>{
+ const a=evidence('a',1391),b=evidence('b',100000,true);
+ b.data.lines[0].matePly=3;
+ const [notice]=scoreComparisonNotices([a,b]);
+ assert.deepEqual(notice.observations[1].score,{unit:'mate-in-moves',value:3});
+ assert.equal(notice.disagreementKind,'mate-status-disagreement');
+ assert.match(notice.interpretation,/centipawn score in another search does not refute its mating continuation/);
+ assert.match(notice.interpretation,/within that search, not independent confirmation or rejection/);
+ assert.deepEqual(notice.preferredWithinSearchComparisonEvidenceIds,['b']);
+ b.data.lines[0].matePly=null;
+ assert.deepEqual(scoreComparisonNotices([a,b]),[]);
+});
+test('KE-REASON-016/021/026: distinguish opposing mate signs from distances while retaining reported scope and provenance',()=>{
+ const a=evidence('a',100000),b=evidence('b',100000,true);
+ a.data.lines[0].matePly=3;b.data.lines[0].matePly=-5;
+ const reported={kind:'root-search',fen,originatingDepth:17,engineBuild:'18'};
+ b.data.lines[0].scoreProvenance=reported;
+ const saved=structuredClone([a,b]);
+ const [opposite]=scoreComparisonNotices([a,b]);
+ assert.equal(opposite.disagreementKind,'opposite-mate-sign');
+ assert.match(opposite.interpretation,/mate signs oppose/);
+ assert.deepEqual(opposite.observations[1].scoreProvenance,reported);
+ assert.equal('scoreProvenance' in opposite.observations[0],false);
+ assert.deepEqual(opposite.observations.map(o=>[o.reportedDepth,o.actualDepth,o.requestedDepth,o.rootScope,o.sourceCacheProvenance]),[[18,null,18,'unrestricted','widget-analysis-cache'],[18,null,18,'restricted','engine']]);
+ assert.deepEqual([a,b],saved);
+ b.data.lines[0].matePly=5;
+ const [distance]=scoreComparisonNotices([a,b]);
+ assert.equal(distance.disagreementKind,'mate-distance-variation');
+ assert.match(distance.interpretation,/different mate distances/);
+ assert.match(distance.interpretation,/does not require another search/);
+});
+test('KE-REASON-021: incomplete or mixed-depth comparisons do not receive comparison preference',()=>{
+ const a=evidence('a',1391),b=evidence('b',1256,true);
+ b.data.lines[1].depth=17;
+ assert.deepEqual(scoreComparisonNotices([a,b])[0].preferredWithinSearchComparisonEvidenceIds,[]);
+ b.data.lines[1].depth=18;b.coverage.complete=false;
+ assert.deepEqual(scoreComparisonNotices([a,b])[0].preferredWithinSearchComparisonEvidenceIds,[]);
+});
+
+test('KE-REASON-026: malformed candidates and inconsistent original commands cannot certify comparison preference',()=>{
+ const a=evidence('a',1391),b=evidence('b',1256,true);
+ b.data.searchScope.command='go depth 18';
+ b.data.lines.forEach(line=>line.scoreProvenance={kind:'root-search',fen,originatingDepth:18,command:'go depth 26'});
+ assert.deepEqual(scoreComparisonNotices([a,b])[0].preferredWithinSearchComparisonEvidenceIds,[]);
+ b.data.lines.push(null);
+ assert.deepEqual(scoreComparisonNotices([a,b])[0].preferredWithinSearchComparisonEvidenceIds,[]);
+});
+test('KE-REASON-016/021/026: cached reported depths and subsequent-position scores cannot certify a matched root comparison',()=>{
+ const a=evidence('a',1391),b=evidence('b',1256,true);
+ b.data.searchScope.cacheProvenance='browser-completed-cache';
+ b.data.searchScope.sourceCacheProvenance='widget-analysis-cache';
+ assert.deepEqual(scoreComparisonNotices([a,b])[0].preferredWithinSearchComparisonEvidenceIds,[]);
+ assert.deepEqual(scoreComparisonNotices([a,b])[0].observations[1].actualDepth,null);
+ const kinds=[
+  {kind:'restored-fallback',originatingDepth:null,reportedDepth:18,fallbackDepth:18},
+  {kind:'legacy-unknown',originatingDepth:null,reportedDepth:18},
+  {kind:'subsequent-position',fen:fen.replace('0 1','1 1'),originatingDepth:18,reportedDepth:18},
+  {kind:'root-search',fen:fen.replace('0 1','1 1'),originatingDepth:18,engineBuild:'18'},
+  {kind:'root-search',fen,originatingDepth:0,engineBuild:'18'},
+ ];
+ for(const provenance of kinds){
+  b.data.lines[0].scoreProvenance=provenance;b.data.lines[1].scoreProvenance=provenance;
+  const [notice]=scoreComparisonNotices([a,b]);
+  assert.equal(notice.observations[1].reportedDepth,18);
+  assert.equal(notice.observations[1].actualDepth,null);
+  assert.deepEqual(notice.preferredWithinSearchComparisonEvidenceIds,[]);
+ }
+ b.data.lines[0].scoreProvenance={kind:'root-search',fen,originatingDepth:17,engineBuild:'18'};
+ b.data.lines[1].scoreProvenance={kind:'root-search',fen,originatingDepth:18,engineBuild:'18'};
+ assert.deepEqual(scoreComparisonNotices([a,b])[0].preferredWithinSearchComparisonEvidenceIds,[]);
+ b.data.lines[1].scoreProvenance={kind:'root-search',fen,originatingDepth:17,engineBuild:'18'};
+ assert.deepEqual(scoreComparisonNotices([a,b])[0].preferredWithinSearchComparisonEvidenceIds,[], 'candidate provenance does not establish shared search identity');
+ b.data.searchScope.sourceCacheProvenance='engine';
+ b.data.lines.forEach(line=>line.depth=17);
+ const [verified]=scoreComparisonNotices([a,b]);
+ assert.deepEqual(verified.preferredWithinSearchComparisonEvidenceIds,['b']);
+ assert.deepEqual(verified.observations[1].scoreProvenance,b.data.lines[0].scoreProvenance);
+ assert.equal(verified.observations[1].actualDepth,17);
+});

package/test/owner/simple-engine-presentation.test.mjs

@@ -0,0 +1,50 @@
+import test from 'node:test';
+import assert from 'node:assert/strict';
+import {Chess} from 'chess.js';
+import {projectEnginePresentation} from '../../src/chess-reasoning/simple-engine-presentation.ts';
+
+const pv=['e2e4','d7d5','e4d5','d8d5'];
+function fixture() {
+ const b=new Chess(),fens=[b.fen()];
+ for(const m of pv){b.move({from:m.slice(0,2),to:m.slice(2,4)});fens.push(b.fen());}
+ const segments=[0,2].map(startPly=>({fen:fens[startPly],startPly,depth:18,pv:pv.slice(startPly),scoreCp:15,matePly:null,command:'go depth 18',engine:'Stockfish',engineBuild:'18',cacheProvenance:'engine'}));
+ const moves=pv.map((uci,i)=>({uci,capture:i>1?{pieceType:'p'}:null,givesCheck:false,captureGeometry:{test:i}}));
+ return {evidence:[{id:'e1',source:'Stockfish/compare_moves',data:{searchScope:{fen:fens[0]},lines:[{pv,rawPv:[...pv],depth:18,pvCompletion:{conditional:true,status:'complete',segments}}],continuationMoveFacts:[{rootMove:pv[0],moves}]}}]};
+}
+test('KE-REASON-016/021: default view removes only deep geometry and exact PV duplicates while preserving complete internal records',()=>{
+ const raw=fixture(),copy=structuredClone(raw),v=projectEnginePresentation(raw),d=v.evidence[0].data;
+ assert.deepEqual(raw,copy);
+ assert.deepEqual(d.continuationMoveFacts[0].moves.map(m=>!!m.captureGeometry),[true,true,false,false]);
+ assert.deepEqual(d.continuationMoveFacts[0].moves.map(m=>m.capture),copy.evidence[0].data.continuationMoveFacts[0].moves.map(m=>m.capture));
+ assert.equal(d.lines[0].rawPv,undefined);assert.deepEqual(d.lines[0].pv,pv);
+ assert.equal(d.modelPresentation.retrieveFullEvidenceId,'e1');
+ const segments=d.lines[0].pvCompletion.segments;
+ assert.deepEqual(segments.map(s=>s.fenFromLinePvPly),[0,2]);
+ for(let i=0;i<segments.length;i++){const {fen,...original}=copy.evidence[0].data.lines[0].pvCompletion.segments[i];const {fenFromLinePvPly,...actual}=segments[i];void fen;void fenFromLinePvPly;assert.deepEqual(actual,original);}
+ const full=projectEnginePresentation(raw,true).evidence[0].data;
+ assert.deepEqual(full.continuationMoveFacts,copy.evidence[0].data.continuationMoveFacts);
+ assert.equal(full.modelPresentation.omittedCaptureGeometry,undefined);
+});
+test('KE-REASON-021: unequal original PV and mismatched segment FEN remain explicit',()=>{
+ const raw=fixture(),line=raw.evidence[0].data.lines[0];
+ line.rawPv=pv.slice(0,2);line.pvCompletion.segments[1].fen='unverified';
+ const d=projectEnginePresentation(raw).evidence[0].data;
+ assert.deepEqual(d.lines[0].rawPv,pv.slice(0,2));
+ assert.equal(d.lines[0].pvCompletion.segments[1].fen,'unverified');
+ assert.equal(d.lines[0].pvCompletion.segments[1].fenFromLinePvPly,undefined);
+});
+test('KE-REASON-016: unrelated geometry and unknown record shapes stay intact',()=>{
+ const raw={id:'other',data:{captureGeometry:{detail:'preserve'},continuationMoveFacts:[{moves:[1,2,{captureGeometry:{detail:'preserve'}}]}]}};
+ assert.deepEqual(projectEnginePresentation(raw),raw);
+});
+
+test('KE-REASON-016: recorded-position tools project nested details without losing historical scope',()=>{
+ const raw=fixture(),data=raw.evidence[0].data;
+ raw.evidence[0].data={recordedPosition:{ply:10,fen:data.searchScope.fen},details:data};
+ const v=projectEnginePresentation(raw).evidence[0];
+ assert.deepEqual(v.data.recordedPosition,raw.evidence[0].data.recordedPosition);
+ assert.equal(v.data.details.lines[0].rawPv,undefined);
+ assert.equal(v.data.details.continuationMoveFacts[0].moves[2].captureGeometry,undefined);
+ assert.equal(v.data.details.modelPresentation.retrieveFullEvidenceId,'e1');
+ assert.deepEqual(projectEnginePresentation(raw,true).evidence[0].data.details.continuationMoveFacts,data.continuationMoveFacts);
+});

package/test/owner/tool-input-loop-guard.test.mjs

@@ -0,0 +1,25 @@
+import test from 'node:test';
+import assert from 'node:assert/strict';
+import {createToolInputLoopGuard} from '../../src/chess-reasoning/tool-input-loop-guard.ts';
+test('KE-REASON-026: Nc8 repeated final comparison is blocked before dispatch; corrected request stays eligible',()=>{
+ const guard=createToolInputLoopGuard(); let validations=0;
+ const input={phase:'after',movesUci:['h2h3','e8e4','f1e1','f8e8','a2a4','c8b6','a4a5','b6c4'],inspectSquares:['c4','e4','d3','f5'],inspectPlies:[6,8],analyzeFinal:false,compareFinalMovesUci:['d3c4'],minimumPvPlies:10,depth:18};
+ assert.throws(()=>guard.validate('test_line',input,()=>validations++),/requires analyzeFinal=true/);
+ for(let n=0;n<3;n++)assert.throws(()=>guard.validate('test_line',{...input},()=>validations++),e=>e.code==='repeated-invalid-tool-input'&&e.repeatedInvalidInput===true);
+ assert.equal(validations,1); assert.equal(guard.repeatedFailures,3);
+ guard.validate('test_line',{...input,analyzeFinal:true},()=>validations++);
+ guard.validate('test_line',{phase:'after',movesUci:input.movesUci,analyzeFinal:false},()=>validations++);
+ assert.equal(validations,3);
+});
+test('KE-REASON-026: canonical keys ignore property order but preserve array order, names and episode boundaries',()=>{
+ const guard=createToolInputLoopGuard(); const invalid=()=>{throw Object.assign(new Error('array of 1..6 items'),{code:'invalid-tool-array',field:'compareFinalMovesUci',expected:'array of 1..6 items'});};
+ assert.throws(()=>guard.validate('test_line',{analyzeFinal:false,compareFinalMovesUci:[]},invalid));
+ assert.throws(()=>guard.validate('test_line',{compareFinalMovesUci:[],analyzeFinal:false},invalid),e=>e.code==='repeated-invalid-tool-input');
+ assert.throws(()=>createToolInputLoopGuard().validate('test_line',{compareFinalMovesUci:[],analyzeFinal:false},invalid),e=>e.code==='invalid-tool-array');
+ assert.throws(()=>guard.validate('test_game_line',{compareFinalMovesUci:[],analyzeFinal:false},invalid),e=>e.code==='invalid-tool-array');
+});
+test('KE-REASON-026: unstructured and transient failures are never remembered',()=>{
+ const guard=createToolInputLoopGuard(); let attempts=0;
+ for(let n=0;n<2;n++)assert.throws(()=>guard.validate('analyze_position',{},()=>{attempts++;throw Error('network failed');}),/network failed/);
+ assert.equal(attempts,2);assert.equal(guard.repeatedFailures,0);
+});

package/test-types.mts

@@ -0,0 +1,23 @@
+import {runAnswerPipeline,createProductionObservationProvider,QUESTION_ROUTING_VERSION,type AnswerModelConnector,type AnswerSelection,type AnswerHistoryPort} from '@knights-eye-chess/ai-analysis';
+const connector:AnswerModelConnector={kind:'model-turn',async invoke(request){return {text:request.toolChoice,toolCalls:[],finishReason:'stop',usage:{},response:{messages:[]}};}};
+const selection:AnswerSelection={deliveryId:'x',selectionKey:'x',edgeId:'root',existingAnalysis:null,context:{kind:'position',nodeId:'root',fenBefore:'x',fenAfter:'x',historyUci:[],moveUci:'',moveSan:''}};
+const history:AnswerHistoryPort={};
+void runAnswerPipeline({connector,requestId:'x',question:'x',selected:selection,bridge:history,observationProvider:createProductionObservationProvider({context:selection.context}),prepareRouting:async()=>({question:'x',selectionKey:'x',deliveryId:'x',elapsedMs:0,omitSelectedContext:false,decision:{version:QUESTION_ROUTING_VERSION,status:'fallback',omitSelectedContext:false,includeGameRecord:false,reviewGame:false,reason:'explicit'}})});
+// @ts-expect-error model turn cannot be replaced by an unrelated delegated agent executor
+const wrong:AnswerModelConnector={kind:'agent',execute:async()=>''};
+// @ts-expect-error exact history is required in a selected position context
+const noHistory:AnswerSelection={...selection,context:{nodeId:'x',fenBefore:'x',fenAfter:'x',moveUci:'',moveSan:''}};
+void wrong;void noHistory;
+
+// The public analyzer distance is signed mate-in-moves; legacy reads are explicit.
+import {toPositionAnalysis,toLegacyPositionAnalysis,type PositionAnalysisResult,type LegacyPositionAnalysisResult,type PositionAnalysisProvider} from '@knights-eye-chess/ai-analysis';
+const modern:PositionAnalysisResult={engine:'synthetic',engineBuild:'test',command:'test',bestMove:'e2e4',lines:[{rootMove:'e2e4',pv:['e2e4'],depth:18,nodes:null,scoreCp:null,mateInMoves:-3}]};
+const old:LegacyPositionAnalysisResult=toLegacyPositionAnalysis(modern);
+const current:PositionAnalysisResult=toPositionAnalysis(old);
+const analyzer:PositionAnalysisProvider={analyze:async()=>current};
+// @ts-expect-error matePly alone is not the preferred public result contract
+const oldAsCurrent:PositionAnalysisResult=old;
+// @ts-expect-error mate distance is numeric, never a UCI or SAN string
+const badMate:PositionAnalysisResult={...modern,lines:[{...modern.lines[0],mateInMoves:'3'}]};
+void runAnswerPipeline({connector,requestId:'parallel',question:'x',selected:selection,bridge:history,analyzer,preparationAnalyzer:analyzer,parallelPreparation:true,observationProvider:createProductionObservationProvider({context:selection.context}),prepareRouting:async()=>({question:'x',selectionKey:'x',deliveryId:'x',elapsedMs:0,omitSelectedContext:false,decision:{version:QUESTION_ROUTING_VERSION,status:'fallback',omitSelectedContext:false,includeGameRecord:false,reviewGame:false,reason:'explicit'}})});
+void analyzer;void oldAsCurrent;void badMate;

package/tsconfig.json

@@ -0,0 +1,22 @@
+{
+  "compilerOptions": {
+    "strict": true,
+    "target": "ES2022",
+    "module": "ESNext",
+    "moduleResolution": "Bundler",
+    "lib": [
+      "ES2022",
+      "DOM",
+      "DOM.Iterable"
+    ],
+    "types": [],
+    "skipLibCheck": true,
+    "declaration": true,
+    "emitDeclarationOnly": true,
+    "rootDir": "src",
+    "outDir": "dist/types"
+  },
+  "include": [
+    "src/**/*.ts"
+  ]
+}