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

package/src/chess-reasoning/mechanical-ray-facts.ts

@@ -0,0 +1,123 @@
+import { Chess, SQUARES, type Color, type PieceSymbol, type Square } from "chess.js";
+import { pieceIdAt } from "./poc-piece-refs";
+import { applyIdentityMove } from "./piece-identities";
+import type { IdentityState } from "./types";
+
+export type OccupiedRayPiece = {
+  pieceId: string;
+  currentSquare: Square;
+  pieceType: PieceSymbol;
+  color: Color;
+};
+
+export type ExchangeRayAlignmentWitness = {
+  movesUci: string[];
+  finalFen: string;
+  slider: OccupiedRayPiece;
+  front: OccupiedRayPiece;
+  rear: OccupiedRayPiece;
+  ray: Square[];
+};
+
+type RayDirection = readonly [number, number];
+
+const NOMINAL_VALUES: Record<PieceSymbol, number> = { p: 1, n: 3, b: 3, r: 5, q: 9, k: 0 };
+const ORTHOGONAL_DIRECTIONS: readonly RayDirection[] = [[1, 0], [-1, 0], [0, 1], [0, -1]];
+const DIAGONAL_DIRECTIONS: readonly RayDirection[] = [[1, 1], [1, -1], [-1, 1], [-1, -1]];
+
+function moveUci(move: { from: string; to: string; promotion?: string }) {
+  return `${move.from}${move.to}${move.promotion || ""}`;
+}
+
+function squareAt(file: number, rank: number): Square | null {
+  if (file < 0 || file > 7 || rank < 0 || rank > 7) return null;
+  return `${String.fromCharCode(97 + file)}${rank + 1}` as Square;
+}
+
+function occupiedOpponentRayAlignments(board: Chess, identities: IdentityState) {
+  const result: Array<Omit<ExchangeRayAlignmentWitness, "movesUci" | "finalFen">> = [];
+  for (const sliderSquare of SQUARES) {
+    const slider = board.get(sliderSquare);
+    if (!slider || !["b", "r", "q"].includes(slider.type)) continue;
+    const directions = slider.type === "b"
+      ? DIAGONAL_DIRECTIONS
+      : slider.type === "r"
+        ? ORTHOGONAL_DIRECTIONS
+        : [...ORTHOGONAL_DIRECTIONS, ...DIAGONAL_DIRECTIONS];
+    const originFile = sliderSquare.charCodeAt(0) - 97;
+    const originRank = Number(sliderSquare[1]) - 1;
+    for (const [fileStep, rankStep] of directions) {
+      const ray: Square[] = [sliderSquare];
+      const occupied: Array<{ square: Square; color: Color; type: PieceSymbol; pieceId: string | null }> = [];
+      for (let distance = 1; distance < 8; distance += 1) {
+        const square = squareAt(originFile + fileStep * distance, originRank + rankStep * distance);
+        if (!square) break;
+        ray.push(square);
+        const piece = board.get(square);
+        if (!piece) continue;
+        occupied.push({ square, color: piece.color, type: piece.type, pieceId: pieceIdAt(identities, square) });
+        if (occupied.length === 2) break;
+      }
+      const front = occupied[0];
+      const rear = occupied[1];
+      const sliderPieceId = pieceIdAt(identities, sliderSquare);
+      if (!front || !rear || !sliderPieceId || !front.pieceId || !rear.pieceId) continue;
+      if (front.color === slider.color || rear.color !== front.color) continue;
+      if (rear.type !== "k" && NOMINAL_VALUES[rear.type] <= NOMINAL_VALUES[front.type]) continue;
+      result.push({
+        slider: { pieceId: sliderPieceId, currentSquare: sliderSquare, pieceType: slider.type, color: slider.color },
+        front: { pieceId: front.pieceId, currentSquare: front.square, pieceType: front.type, color: front.color },
+        rear: { pieceId: rear.pieceId, currentSquare: rear.square, pieceType: rear.type, color: rear.color },
+        ray: ray.slice(0, ray.indexOf(rear.square) + 1),
+      });
+    }
+  }
+  return result;
+}
+
+function alignmentKey(alignment: Omit<ExchangeRayAlignmentWitness, "movesUci" | "finalFen">) {
+  return [
+    alignment.slider.pieceId,
+    alignment.slider.currentSquare,
+    alignment.front.pieceId,
+    alignment.front.currentSquare,
+    alignment.rear.pieceId,
+    alignment.rear.currentSquare,
+    alignment.ray.join("-"),
+  ].join("|");
+}
+
+export function exchangeRayAlignmentWitnesses(
+  fenAfter: string,
+  identityAfter: IdentityState,
+  exchangeLines: readonly (readonly { uci: string }[])[],
+): ExchangeRayAlignmentWitness[] {
+  const baseline = new Chess(fenAfter);
+  const baselineKeys = new Set(occupiedOpponentRayAlignments(baseline, identityAfter).map(alignmentKey));
+  const result = new Map<string, ExchangeRayAlignmentWitness>();
+  for (const line of exchangeLines) {
+    const board = new Chess(fenAfter);
+    let identities = identityAfter;
+    for (const item of line) {
+      const move = board.moves({ verbose: true }).find((candidate) => moveUci(candidate) === item.uci);
+      if (!move) throw new Error(`Same-square witness contains an illegal move: ${item.uci}`);
+      board.move({ from: move.from, to: move.to, promotion: move.promotion });
+      identities = applyIdentityMove(identities, { from: move.from, to: move.to, promotion: move.promotion }).state;
+    }
+    const movesUci = line.map((item) => item.uci);
+    const finalFen = board.fen();
+    for (const alignment of occupiedOpponentRayAlignments(board, identities)) {
+      const key = alignmentKey(alignment);
+      if (baselineKeys.has(key)) continue;
+      const witness = { movesUci, finalFen, ...alignment };
+      const existing = result.get(key);
+      const witnessText = movesUci.join(" ");
+      const existingText = existing?.movesUci.join(" ") || "";
+      if (!existing || movesUci.length < existing.movesUci.length || (movesUci.length === existing.movesUci.length && witnessText < existingText)) {
+        result.set(key, witness);
+      }
+    }
+  }
+  return [...result.values()].sort((left, right) => left.movesUci.join(" ").localeCompare(right.movesUci.join(" "))
+    || alignmentKey(left).localeCompare(alignmentKey(right)));
+}

package/src/chess-reasoning/mechanism-presentation.ts

@@ -0,0 +1,94 @@
+type Obj = Record<string, unknown>;
+const object = (v: unknown): v is Obj => !!v && typeof v === 'object' && !Array.isArray(v);
+
+const COLUMNS = {
+  mover: ['pieceId','pieceIdAfter','fromSquare','toSquare','color','pieceTypeBefore','pieceTypeAfter','attackersBefore','attackersAfter'],
+  unmoved: ['pieceId','square','pieceType','attackersBefore','attackersAfter'],
+  rays: ['pieceId','fromSquare','color','pieceType','direction','gainedSquares','lostSquares'],
+  control: ['square','color','attackersBefore','attackersAfter'],
+} as const;
+type ColumnGroup = keyof typeof COLUMNS;
+const GROUPS: ColumnGroup[] = ['mover','unmoved','rays','control'];
+
+function exactKeys(value: unknown, columns: readonly string[]): value is Obj {
+  return object(value) && Object.keys(value).length === columns.length
+    && columns.every(column => Object.hasOwn(value,column));
+}
+
+function encodeRows(value: Obj, columns: readonly string[]): unknown[] {
+  return columns.map(column => value[column]);
+}
+
+function decodeRow(row: unknown, columns: readonly string[]): Obj | null {
+  if (!Array.isArray(row) || row.length !== columns.length) return null;
+  return Object.fromEntries(columns.map((column,index) => [column,row[index]]));
+}
+
+/** Restores the precise bounded projection, including its coverage/omission markers.
+ * Unknown versions or schemas pass through unchanged rather than losing fields. */
+export function expandMechanismPresentation(value: unknown): unknown {
+  if (!object(value) || value.encoding !== 'move-mechanism/1') return value;
+  if (!object(value.columns) || !object(value.rows)
+    || Object.keys(value.columns).length !== GROUPS.length
+    || Object.keys(value.rows).length !== GROUPS.length) return value;
+  for (const group of GROUPS) {
+    if (JSON.stringify(value.columns[group]) !== JSON.stringify(COLUMNS[group])) return value;
+  }
+  const mover = decodeRow(value.rows.mover,COLUMNS.mover);
+  if (!mover || !Array.isArray(value.rows.unmoved) || !Array.isArray(value.rows.rays)
+    || !Array.isArray(value.rows.control)) return value;
+  const unmoved = value.rows.unmoved.map(row => decodeRow(row,COLUMNS.unmoved));
+  const rays = value.rows.rays.map(row => decodeRow(row,COLUMNS.rays));
+  const control = value.rows.control.map(row => decodeRow(row,COLUMNS.control));
+  if ([...unmoved,...rays,...control].some(row => row === null)) return value;
+  const {encoding:_encoding,columns:_columns,rows:_rows,...rest} = value;
+  void _encoding; void _columns; void _rows;
+  return {...rest,mover,attackedUnmovedFriendlyPieces:unmoved,
+    stationarySliderRays:rays,controlDelta:control};
+}
+
+/** A measured but untransmitted square is not a negative result. Full control
+ * deltas stay on the immutable evidence record for retrieval. */
+export function compactMechanism(value: unknown, targetSquares: string[]): unknown {
+  if (!object(value) || !Array.isArray(value.controlDelta)) return value;
+  const targets = [...new Set(targetSquares)].filter(s => /^[a-h][1-8]$/.test(s));
+  const controlDelta = value.controlDelta.filter(d => object(d) && targets.includes(String(d.square)));
+  const rays = Array.isArray(value.stationarySliderRays) ? value.stationarySliderRays.map(ray => {
+    if (!object(ray)) return ray;
+    const {beforeSquares:_before,afterSquares:_after,...changes} = ray;
+    void _before; void _after;
+    return changes;
+  }) : value.stationarySliderRays;
+  const projected: Obj = {...value, stationarySliderRays:rays, controlDelta,
+    presentation:{controlSquares:targets, omittedControlDeltaCount:value.controlDelta.length-controlDelta.length,
+      scope:'All changed stationary rays and mover/unmoved attack measurements retained. Control deltas shown only for controlSquares; an omitted square is not checked-negative in this view. Full ray extents and all control deltas are retrievable.'}};
+  // Additions to the canonical contract must travel verbatim until an explicit
+  // versioned schema can represent them; never silently discard an unknown fact.
+  if (!exactKeys(value,['mover','attackedUnmovedFriendlyPieces','stationarySliderRays','controlDelta','checksRun','scope'])
+    || !exactKeys(projected.mover,COLUMNS.mover)
+    || !Array.isArray(projected.attackedUnmovedFriendlyPieces)
+    || !projected.attackedUnmovedFriendlyPieces.every(item => exactKeys(item,COLUMNS.unmoved))
+    || !Array.isArray(rays) || !rays.every(item => exactKeys(item,COLUMNS.rays))
+    || !controlDelta.every(item => exactKeys(item,COLUMNS.control))) return projected;
+  return {
+    encoding:'move-mechanism/1',columns:COLUMNS,
+    rows:{
+      mover:encodeRows(projected.mover,COLUMNS.mover),
+      unmoved:projected.attackedUnmovedFriendlyPieces.map(item => encodeRows(item as Obj,COLUMNS.unmoved)),
+      rays:rays.map(item => encodeRows(item as Obj,COLUMNS.rays)),
+      control:controlDelta.map(item => encodeRows(item,COLUMNS.control)),
+    },
+    checksRun:projected.checksRun,scope:projected.scope,presentation:projected.presentation,
+  };
+}
+
+/** Root + first reply by default; explicit one-based replay targets, and moves
+ * landing on inspected squares, can expose a deeper mechanism without a search. */
+export function presentMoveMechanisms(moves: unknown[], inspectPlies: number[] = [], inspectSquares: string[] = []): unknown[] {
+  return moves.flatMap((fact,index) => {
+    if (!object(fact) || !object(fact.mechanism)) return [];
+    if (index >= 2 && !inspectPlies.includes(index+1) && !inspectSquares.includes(String(fact.to))) return [];
+    const targets = [...inspectSquares, ...moves.slice(index,index+3).flatMap(m => object(m) && typeof m.to === 'string' ? [m.to] : [])];
+    return [{ply:index+1,uci:fact.uci,san:fact.san,mechanism:compactMechanism(fact.mechanism,targets)}];
+  });
+}

package/src/chess-reasoning/move-mechanism-facts.ts

@@ -0,0 +1,185 @@
+import { Chess, SQUARES, type Color, type PieceSymbol, type Square } from "chess.js";
+import { applyIdentityMove, createIdentityState } from "./piece-identities";
+import type { IdentityState } from "./types";
+
+type Direction = "N" | "NE" | "E" | "SE" | "S" | "SW" | "W" | "NW";
+type RayStep = readonly [Direction, number, number];
+
+const DIRECTIONS: readonly RayStep[] = [
+  ["N", 0, 1], ["NE", 1, 1], ["E", 1, 0], ["SE", 1, -1],
+  ["S", 0, -1], ["SW", -1, -1], ["W", -1, 0], ["NW", -1, 1],
+];
+
+export type MoveMechanismFacts = {
+  mover: {
+    pieceId: string;
+    pieceIdAfter: string;
+    fromSquare: Square;
+    toSquare: Square;
+    color: Color;
+    pieceTypeBefore: PieceSymbol;
+    pieceTypeAfter: PieceSymbol;
+    attackersBefore: Square[];
+    attackersAfter: Square[];
+  };
+  attackedUnmovedFriendlyPieces: Array<{
+    pieceId: string;
+    square: Square;
+    pieceType: PieceSymbol;
+    attackersBefore: Square[];
+    attackersAfter: Square[];
+  }>;
+  stationarySliderRays: Array<{
+    pieceId: string;
+    fromSquare: Square;
+    color: Color;
+    pieceType: PieceSymbol;
+    direction: Direction;
+    beforeSquares: Square[];
+    afterSquares: Square[];
+    gainedSquares: Square[];
+    lostSquares: Square[];
+  }>;
+  controlDelta: Array<{
+    square: Square;
+    color: Color;
+    attackersBefore: Square[];
+    attackersAfter: Square[];
+  }>;
+  checksRun: string[];
+  scope: string;
+};
+
+function enemy(color: Color): Color {
+  return color === "w" ? "b" : "w";
+}
+
+function attackers(board: Chess, square: Square, color: Color): Square[] {
+  return board.attackers(square, color).sort((a, b) => SQUARES.indexOf(a) - SQUARES.indexOf(b));
+}
+
+function ray(board: Chess, origin: Square, fileStep: number, rankStep: number): Square[] {
+  const squares: Square[] = [];
+  const file = origin.charCodeAt(0) - 97;
+  const rank = Number(origin[1]) - 1;
+  for (let distance = 1; distance < 8; distance += 1) {
+    const f = file + fileStep * distance;
+    const r = rank + rankStep * distance;
+    if (f < 0 || f > 7 || r < 0 || r > 7) break;
+    const square = `${String.fromCharCode(97 + f)}${r + 1}` as Square;
+    squares.push(square);
+    // The first blocker is controlled, but nothing behind it is visible.
+    if (board.get(square)) break;
+  }
+  return squares;
+}
+
+function sliderDirections(type: PieceSymbol): readonly RayStep[] {
+  if (type === "q") return DIRECTIONS;
+  return DIRECTIONS.filter(([, dx, dy]) => type === "r" ? !dx || !dy : !!dx && !!dy);
+}
+
+/** Complete board-local geometric measurements for one already-admitted legal move. */
+export function moveMechanismFacts(
+  before: Chess,
+  after: Chess,
+  from: Square,
+  to: Square,
+  beforeIds?: IdentityState,
+  afterIds?: IdentityState,
+): MoveMechanismFacts {
+  const moverBefore = before.get(from);
+  const moverAfter = after.get(to);
+  if (!moverBefore || !moverAfter || moverBefore.color !== moverAfter.color) {
+    throw new Error(`Move mechanism has no corresponding mover at ${from}-${to}`);
+  }
+  const beforeState = beforeIds || createIdentityState(before.fen());
+  if (beforeState.fen !== before.fen() || (afterIds && afterIds.fen !== after.fen())) {
+    throw new Error("Move mechanism identity position does not match the board");
+  }
+  // Resolve promotion by the resulting board, since from/to alone can name four
+  // distinct legal moves. This also rejects an unrelated after-position.
+  const actualMove = before.moves({ verbose: true }).find((move) => {
+    if (move.from !== from || move.to !== to) return false;
+    const replay = new Chess(before.fen());
+    replay.move({ from, to, promotion: move.promotion });
+    return replay.fen() === after.fen();
+  });
+  if (!actualMove) throw new Error(`Move mechanism after-position is not a legal ${from}-${to} result`);
+  const afterState = afterIds || applyIdentityMove(beforeState, {
+    from, to, promotion: actualMove.promotion,
+  }).state;
+  const pieceId = beforeState.squares[from];
+  const pieceIdAfter = afterState.squares[to];
+  if (!pieceId || !pieceIdAfter || (actualMove.promotion
+    ? afterState.pieces[pieceIdAfter]?.promotedFrom !== pieceId
+    : pieceIdAfter !== pieceId)) {
+    throw new Error("Move mechanism mover identities do not match");
+  }
+
+  const attackedUnmovedFriendlyPieces: MoveMechanismFacts["attackedUnmovedFriendlyPieces"] = [];
+  const stationarySliderRays: MoveMechanismFacts["stationarySliderRays"] = [];
+  const color = moverBefore.color;
+  for (const square of SQUARES) {
+    const piece = before.get(square);
+    const samePiece = after.get(square);
+    const id = beforeState.squares[square];
+    if (!piece || !samePiece || !id || afterState.squares[square] !== id
+      || piece.color !== samePiece.color || piece.type !== samePiece.type) continue;
+    if (piece.color === color) {
+      const beforeAttackers = attackers(before, square, enemy(color));
+      const afterAttackers = attackers(after, square, enemy(color));
+      if (beforeAttackers.length || afterAttackers.length) {
+        attackedUnmovedFriendlyPieces.push({
+          pieceId: id, square, pieceType: piece.type,
+          attackersBefore: beforeAttackers, attackersAfter: afterAttackers,
+        });
+      }
+    }
+    if (piece.type !== "r" && piece.type !== "b" && piece.type !== "q") continue;
+    for (const [direction, dx, dy] of sliderDirections(piece.type)) {
+      const beforeSquares = ray(before, square, dx, dy);
+      const afterSquares = ray(after, square, dx, dy);
+      const beforeSet = new Set(beforeSquares);
+      const afterSet = new Set(afterSquares);
+      const gainedSquares = afterSquares.filter((target) => !beforeSet.has(target));
+      const lostSquares = beforeSquares.filter((target) => !afterSet.has(target));
+      if (gainedSquares.length || lostSquares.length) {
+        stationarySliderRays.push({
+          pieceId: id, fromSquare: square, color: piece.color, pieceType: piece.type,
+          direction, beforeSquares, afterSquares, gainedSquares, lostSquares,
+        });
+      }
+    }
+  }
+
+  const controlDelta: MoveMechanismFacts["controlDelta"] = [];
+  for (const square of SQUARES) {
+    for (const attackingColor of ["w", "b"] as const) {
+      const attackersBefore = attackers(before, square, attackingColor);
+      const attackersAfter = attackers(after, square, attackingColor);
+      if (attackersBefore.length !== attackersAfter.length
+        || attackersBefore.some((origin, index) => origin !== attackersAfter[index])) {
+        controlDelta.push({ square, color: attackingColor, attackersBefore, attackersAfter });
+      }
+    }
+  }
+  return {
+    mover: {
+      pieceId, pieceIdAfter, fromSquare: from, toSquare: to, color,
+      pieceTypeBefore: moverBefore.type, pieceTypeAfter: moverAfter.type,
+      attackersBefore: attackers(before, from, enemy(color)),
+      attackersAfter: attackers(after, to, enemy(color)),
+    },
+    attackedUnmovedFriendlyPieces,
+    stationarySliderRays,
+    controlDelta,
+    checksRun: [
+      "mover-geometric-attackers-before-after",
+      "unmoved-friendly-piece-geometric-attackers-before-after",
+      "stationary-slider-visible-rays-before-after",
+      "all-square-both-color-geometric-control-delta",
+    ],
+    scope: "Complete board-local geometric measurements at this move. Attackers include pinned pieces; visible slider rays include the first occupied square. Empty lists mean measured none or no change. No claim of legal captures, safe retreat, exchange profit, forced purpose, or strategic importance.",
+  };
+}

package/src/chess-reasoning/native-answer-connector.ts

@@ -0,0 +1,13 @@
+import { generateText, jsonSchema, tool, type LanguageModel } from 'ai';
+import type { AnswerModelConnector } from './answer-model-connector';
+/** Native SDK performs exactly one model turn; pipeline owns tool dispatch. */
+export function createNativeAnswerConnector(model:LanguageModel):AnswerModelConnector {
+  return {kind:'model-turn',capabilities:{toolRequests:true,toolFreeComposition:true,opaqueContinuation:true,outputTokenLimit:'requested',usageReporting:'optional'},async invoke(request) {
+    const result=await generateText({model,system:request.system,messages:request.messages,
+      tools:request.tools.length ? Object.fromEntries(request.tools.map(d=>[d.name,tool({description:d.description,inputSchema:jsonSchema<Record<string,unknown>>(d.inputSchema as Parameters<typeof jsonSchema>[0])})])) : undefined,
+      toolChoice:request.toolChoice,maxOutputTokens:request.maxOutputTokens,maxRetries:0,abortSignal:request.signal,
+      providerOptions:{openai:{store:false,include:['reasoning.encrypted_content'],reasoningEffort:request.effort}}});
+    return {text:result.text,toolCalls:result.toolCalls.map(c=>({toolCallId:c.toolCallId,toolName:c.toolName,input:c.input as Record<string,unknown>})),
+      finishReason:result.finishReason,usage:result.usage,response:result.response,providerMetadata:result.providerMetadata};
+  }};
+}

package/src/chess-reasoning/opening-source-contracts.ts

@@ -0,0 +1,47 @@
+export type WikibooksTarget = { title: string; relation: 'current' | 'before' | 'continuation' };
+export type WikibooksPage = {
+  title: string;
+  relation: WikibooksTarget['relation'] | 'ancestor';
+  matchedTargets?: Array<{ requestedTitle: string; relation: WikibooksTarget['relation']; ancestorPlies: number; transposition: boolean }>;
+  requestedTitle?: string;
+  ancestorPlies?: number;
+  transposition?: boolean;
+  positionFen: string;
+  revisionId: number;
+  revisionTimestamp: string;
+  url: string;
+  authorHistoryUrl: string;
+  attribution: string;
+  license: 'CC BY-SA 4.0';
+  licenseUrl: string;
+  prose: string;
+};
+export type WikibooksContextResult = {
+  status: 'available' | 'outside-scope' | 'unavailable' | 'invalid-context' | 'aborted';
+  contextHash: string | null;
+  scope?: 'game-review';
+  pages: WikibooksPage[];
+  /** Local usable-prose catalog title candidates checked during this lookup. */
+  localIndexCandidateCount: number;
+  /** Recorded-game positions checked against the local catalog before title selection. */
+  localIndexPositionCheckCount: number;
+  /** Distinct catalog titles selected for possible live revision retrieval. */
+  localIndexSelectedTitleCount: number;
+  /** Selected titles already present in this answer's transport cache. */
+  cacheHitTitleCount: number;
+  /** Actual MediaWiki fetch attempts, retained alongside requestCount for clarity. */
+  networkRequestCount: number;
+  /** Exact titles sent in those fetch attempts, including redirects and continuations. */
+  networkRequestedTitles: string[];
+  requestCount: number;
+  timingMs: number;
+  limitations: string[];
+};
+export type WikibooksPlan = {
+  status: 'in-scope' | 'outside-scope' | 'invalid-context';
+  rootTitle: string;
+  beforeTitle: string | null;
+  currentTitle: string | null;
+  currentFen: string | null;
+};
+

package/src/chess-reasoning/opening-source-credits.ts

@@ -0,0 +1,53 @@
+import type { WikibooksPage } from './opening-source-contracts';
+import { EVIDENCE_SHARING_VERSION, expandSharedEvidence } from './lossless-evidence-sharing';
+export type OpeningSourceCredit = { title: string; revisionId: number };
+export const OPENING_SOURCE_LICENSE_URL = 'https://creativecommons.org/licenses/by-sa/4.0/';
+export function openingSourceLinks(source: OpeningSourceCredit) {
+ const title=encodeURIComponent(source.title.replaceAll(' ','_'));
+ return {revision:`https://en.wikibooks.org/w/index.php?title=${title}&oldid=${source.revisionId}`,
+  history:`https://en.wikibooks.org/w/index.php?title=${title}&action=history`};
+}
+/** Persist only bounded attribution metadata, never fetched prose or model data. */
+export function parseOpeningSourceCredits(value: unknown): OpeningSourceCredit[] {
+ if(!Array.isArray(value)||value.length>512)throw Error('Invalid opening sources.');
+ const result:OpeningSourceCredit[]=[],seen=new Set<string>();
+ for(const item of value) {
+  if(!item||typeof item!=='object'||typeof item.title!=='string'||!item.title.startsWith('Chess Opening Theory/')
+   ||item.title.length>2000||/[\u0000-\u001f\u007f]/.test(item.title)||!Number.isSafeInteger(item.revisionId)||item.revisionId<=0)throw Error('Invalid opening source.');
+  const key=item.title+'@'+item.revisionId;
+  if(!seen.has(key)){seen.add(key);result.push({title:item.title,revisionId:item.revisionId});}
+ }
+ return result;
+}
+const key=(page:OpeningSourceCredit)=>page.title+'@'+page.revisionId;
+/** Match actual prompt packets against accepted fetched prose. Never credit a
+ * lookup merely because it completed: tools may run on the last allowed call. */
+export function openingSourcesInMessages(messages:unknown,known:ReadonlyMap<string,WikibooksPage>):OpeningSourceCredit[] {
+ const found=new Map<string,OpeningSourceCredit>();
+ function visit(value:unknown,depth:number) {
+  if(depth>30||value==null)return;
+  if(typeof value==='string') {
+   if(!/^[\s]*[\[{]/.test(value))return;
+   try {visit(JSON.parse(value),depth+1);} catch { /* Ordinary prose. */ }
+   return;
+  }
+  if(Array.isArray(value)){for(const item of value)visit(item,depth+1);return;}
+  if(typeof value!=='object')return;
+  const record=value as Record<string,unknown>;
+  if(record.encoding===EVIDENCE_SHARING_VERSION) {
+   // Each self-contained packet owns its dictionary. An invalid packet must not
+   // leak credits from definitions that were never delivered as content.
+   try { visit(expandSharedEvidence(record),depth+1); } catch { /* Invalid shared packet. */ }
+   return;
+  }
+  if(record.authority==='untrusted-opening-commentary'&&Array.isArray(record.pages))for(const page of record.pages) {
+   const original=page&&known.get(key(page));
+   if(original&&typeof page.prose==='string'&&page.prose.trim()&&page.prose===original.prose) {
+    try {const [credit]=parseOpeningSourceCredits([original]);found.set(key(credit),credit);} catch { /* Never persist malformed source metadata. */ }
+   }
+  }
+  for(const item of Object.values(record))visit(item,depth+1);
+ }
+ visit(messages,0);return [...found.values()];
+}
+export const openingSourceKey=key;

package/src/chess-reasoning/opponent-threat-preparation.ts

@@ -0,0 +1,98 @@
+import { Chess } from "chess.js";
+import type { ReasoningPositionContext } from "./poc-contracts";
+import type { PositionAnalysisProvider, PositionAnalysisRequest, PositionAnalysisResult } from "./poc-tools";
+import { SIMPLE_EVIDENCE_PREPARATION_VERSION, type SimpleEvidencePreparation } from "./simple-evidence-preparation";
+import { engineSearchFailure } from './engine-search-failure';
+
+type Scope = "hypothetical-opponent-turn-before" | "actual-after";
+type LeadLine = { root: string; uci: string; san: string; depth: number; scoreCp: number | null; matePly: number | null; shorterThanRequested: boolean };
+
+/** Cheap engine acquisition only. These leads do not register evidence or UI witnesses. */
+export async function prepareOpponentThreats(context: ReasoningPositionContext, engine: PositionAnalysisProvider,
+  signal?: AbortSignal, onProgress?: (message: string) => void, options: { parallel?: boolean } = {}): Promise<SimpleEvidencePreparation | undefined> {
+  if (context.kind === "position") return undefined;
+  const started = performance.now();
+  const rawRecords: { scope: Scope; fen: string; request: Omit<PositionAnalysisRequest, "signal">; result: PositionAnalysisResult }[] = [];
+  const probes: Record<string, unknown>[] = [];
+  const unavailable: ({ scope: Scope; reason: string } & Partial<ReturnType<typeof engineSearchFailure>>)[] = [];
+  let searchCount: 0 | 1 | 2 = 0;
+  let searchesSucceeded = 0, searchesFailed = 0;
+  const targets: { scope: Scope; fen: string; depth: number }[] = [];
+  try {
+    const before = new Chess(context.fenBefore);
+    if (before.isCheck()) unavailable.push({ scope: "hypothetical-opponent-turn-before", reason: "cannot-skip-check" });
+    else {
+      const fields = context.fenBefore.split(" ");
+      fields[1] = before.turn() === "w" ? "b" : "w";
+      fields[3] = "-";
+      targets.push({ scope: "hypothetical-opponent-turn-before", fen: fields.join(" "), depth: 18 });
+    }
+  } catch { unavailable.push({ scope: "hypothetical-opponent-turn-before", reason: "invalid-position" }); }
+  targets.push({ scope: "actual-after", fen: context.fenAfter, depth: 20 });
+  const probeController = options.parallel ? new AbortController() : undefined;
+  const workSignal = probeController ? (signal ? AbortSignal.any([signal, probeController.signal]) : probeController.signal) : signal;
+  const examine = async (target: typeof targets[number]) => {
+    const records: typeof rawRecords = [], targetProbes: typeof probes = [], issues: typeof unavailable = [];
+    workSignal?.throwIfAborted();
+    let dispatched = false, completed = false;
+    try {
+      if (new Chess(target.fen).isGameOver()) {
+        issues.push({ scope: target.scope, reason: "terminal-position" });
+        return { records, targetProbes, issues };
+      }
+      const request = { fen: target.fen, rootMoves: [], depth: target.depth, multiPv: 3, minimumPvPlies: 10 };
+      dispatched = true;
+      searchCount = (searchCount + 1) as 1 | 2;
+      onProgress?.(`Examining ${target.scope === "actual-after" ? "opponent responses" : "potential opponent plans"} · depth ${target.depth}`);
+      const result = await engine.analyze({ ...request, signal: workSignal });
+      workSignal?.throwIfAborted();
+      searchesSucceeded++;
+      completed = true;
+      records.push({ scope: target.scope, fen: target.fen, request, result });
+      const lines: LeadLine[] = [];
+      for (const line of result.lines) {
+        try {
+          const board = new Chess(target.fen);
+          const san = line.pv.map(move => board.move({ from: move.slice(0, 2), to: move.slice(2, 4), promotion: move.slice(4) || undefined }).san);
+          if (!line.pv.length || line.pv[0] !== line.rootMove) throw Error("invalid-root");
+          lines.push({ root: line.rootMove, uci: line.pv.join(" "), san: san.join(" "), depth: line.depth,
+            scoreCp: line.scoreCp, matePly: line.matePly, shorterThanRequested: line.pv.length < 10 });
+        } catch { issues.push({ scope: target.scope, reason: "invalid-continuation-omitted" }); }
+      }
+      targetProbes.push({ scope: target.scope, fen: target.fen,
+        requested: { depth: request.depth, multiPv: request.multiPv, minimumPvPlies: request.minimumPvPlies },
+        engine: result.engine, engineBuild: result.engineBuild, provenance: result.cacheProvenance,
+        sourceProvenance: result.sourceCacheProvenance, command: result.command,
+        perspective: target.fen.split(" ")[1] === "w" ? "white" : "black",
+        units: "centipawns; positive favors perspective; matePly is signed mate-in-moves (legacy name)",
+        coveredRoots: lines.map(line => line.root), lines });
+    } catch (error) {
+      workSignal?.throwIfAborted();
+      if (dispatched && !completed) searchesFailed++;
+      issues.push({ scope: target.scope, reason: "probe-unavailable", ...engineSearchFailure(error) });
+    }
+    return { records, targetProbes, issues };
+  };
+  let acquired: Awaited<ReturnType<typeof examine>>[];
+  if (options.parallel) {
+    const work = targets.map(examine);
+    try { acquired = await Promise.all(work); }
+    catch (error) {
+      probeController!.abort(error);
+      await Promise.allSettled(work);
+      throw error;
+    }
+  } else {
+    acquired = [];
+    for (const target of targets) acquired.push(await examine(target));
+  }
+  // Completion order must not change the preparation evidence's target order.
+  for (const result of acquired) {
+    rawRecords.push(...result.records);
+    probes.push(...result.targetProbes);
+    unavailable.push(...result.issues);
+  }
+  return { version: SIMPLE_EVIDENCE_PREPARATION_VERSION, searchCount, searchesSucceeded, searchesFailed, elapsedMs: performance.now() - started,
+    rawRecords, investigationLeads: { version: "opponent-threat-leads/2", fenBefore: context.fenBefore, fenAfter: context.fenAfter, probes, unavailable,
+      limitation: "Investigation leads, NOT registered/citable evidence. Hypothetical before flips only turn and clears en-passant: skipping is not a legal move. FEN-root searches omit prior repetition history. These scores are not a measured value of the selected move. Top 3 roots only, not exhaustive defense coverage. Raw engine records retained in diagnostic; tactical geometry omitted here. Use ordinary tools to validate relevant actual lines, captures, checks and recaptures and register interactive references. Do not turn an incidental opponent blunder into the purpose of the move." } };
+}