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

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

@@ -0,0 +1,625 @@
+// test/owner/position-preparation.test.mjs
+import test from "node:test";
+import assert from "node:assert/strict";
+import { Chess as Chess13 } from "chess.js";
+
+// src/chess-reasoning/initial-search-plan.ts
+import { Chess as Chess12 } from "chess.js";
+
+// src/chess-reasoning/saved-score-presentation.ts
+function savedScorePresentation(a) {
+  const finiteCp = (cp, mate) => mate !== null || cp !== null && Math.abs(cp) >= 1e5 ? null : cp;
+  const beforeCp = finiteCp(a.beforeCp, a.mateBefore), afterCp = finiteCp(a.afterCp, a.mateAfter);
+  return { beforeCp, afterCp, lossCp: a.mateBefore !== null || a.mateAfter !== null || beforeCp === null || afterCp === null || a.lossCp === 9999 ? null : a.lossCp, mateBefore: a.mateBefore, mateAfter: a.mateAfter };
+}
+
+// src/chess-reasoning/recorded-main-line.ts
+import { Chess as Chess6 } from "chess.js";
+
+// src/chess-reasoning/material-accounting.ts
+import { Chess } from "chess.js";
+
+// src/chess-reasoning/poc-contracts.ts
+import { Chess as Chess5 } from "chess.js";
+
+// src/chess-reasoning/poc-piece-refs.ts
+import { Chess as Chess3, SQUARES as SQUARES2 } from "chess.js";
+
+// src/chess-reasoning/piece-identities.ts
+import { Chess as Chess2, SQUARES } from "chess.js";
+
+// src/chess-reasoning/move-mechanism-facts.ts
+import { Chess as Chess4, SQUARES as SQUARES3 } from "chess.js";
+
+// src/chess-reasoning/evidence-licenses.ts
+var EVIDENCE_LICENSE = Object.freeze({
+  CHESS_LEGALITY: "chess.legality",
+  CHESS_IDENTITY: "chess.identity",
+  CHESS_POSITION_FACT: "chess.position-fact",
+  ENGINE_BOUNDED_CONTINUATION: "engine.bounded-continuation",
+  ENGINE_BOUNDED_COMPARISON: "engine.bounded-comparison",
+  ENGINE_BOUNDED_SCORE: "engine.bounded-score",
+  ENGINE_BOUNDED_RESPONSE_COVERAGE: "engine.bounded-response-coverage",
+  COVERAGE_EXHAUSTIVE: "coverage.exhaustive",
+  ATTENTION_AFFORDANCE: "attention.affordance",
+  SEMANTIC_REVIEWED_STATE: "semantic.reviewed-state",
+  WORKFLOW_AUDIT: "workflow.audit"
+});
+var LICENSES = new Set(Object.values(EVIDENCE_LICENSE));
+
+// src/chess-reasoning/stable.ts
+function stableHash(value) {
+  const text = stableJson(value);
+  let hash = 2166136261;
+  for (let index = 0; index < text.length; index += 1) {
+    hash ^= text.charCodeAt(index);
+    hash = Math.imul(hash, 16777619) >>> 0;
+  }
+  return hash.toString(16).padStart(8, "0");
+}
+function stableJson(value) {
+  if (Array.isArray(value)) return `[${value.map(stableJson).join(",")}]`;
+  if (value && typeof value === "object") {
+    const record = value;
+    return `{${Object.keys(record).sort().map((key) => `${JSON.stringify(key)}:${stableJson(record[key])}`).join(",")}}`;
+  }
+  return JSON.stringify(value);
+}
+
+// src/chess-reasoning/poc-contracts.ts
+var REASONING_POC_VERSION = "conceptual-explanation-poc/57";
+var DEFAULT_REASONING_RUN_CONTROLS = Object.freeze({
+  maxModelSteps: 15,
+  maxToolCalls: 16,
+  maxProbeCalls: 5,
+  maxEvidenceRecords: 48,
+  maxObservationRecords: 48,
+  maxObservationsPresented: 16,
+  maxHypotheses: 16,
+  maxOutputChars: 2400,
+  maxProviderOutputChars: 64e3,
+  maxWallTimeMs: 3e4
+});
+var POSITION_CONTEXT_KEYS = /* @__PURE__ */ new Set(["kind", "nodeId", "parentNodeId", "historyStartFen", "fenBefore", "fenAfter", "historyUci", "moveUci", "moveSan"]);
+function validateReasoningPositionContext(value) {
+  if (!value || typeof value !== "object") throw new Error("Reasoning position context must be an object");
+  for (const key of Object.keys(value)) if (!POSITION_CONTEXT_KEYS.has(key)) throw new Error(`Unsupported reasoning position context field: ${key}`);
+  if (!value.nodeId?.trim()) throw new Error("Reasoning position context requires nodeId");
+  if (!Array.isArray(value.historyUci) || value.historyUci.some((move) => !/^[a-h][1-8][a-h][1-8][qrbn]?$/.test(move))) throw new Error("Reasoning position context historyUci must contain UCI moves");
+  if (value.kind !== void 0 && value.kind !== "position") throw new Error("Invalid context kind");
+  if (!value.kind && !/^[a-h][1-8][a-h][1-8][qrbn]?$/.test(value.moveUci)) throw new Error("Reasoning position context moveUci is invalid");
+  if (!value.kind && !value.moveSan?.trim()) throw new Error("Reasoning position context requires moveSan");
+  const history = value.historyStartFen ? new Chess5(value.historyStartFen) : new Chess5();
+  for (const [index, moveUci] of value.historyUci.entries()) {
+    let replayed;
+    try {
+      replayed = history.move({ from: moveUci.slice(0, 2), to: moveUci.slice(2, 4), promotion: moveUci.slice(4) || void 0 });
+    } catch {
+      replayed = null;
+    }
+    if (!replayed) throw new Error(`Reasoning position context historyUci is illegal at index ${index}`);
+  }
+  if (history.fen() !== new Chess5(value.fenBefore).fen()) throw new Error("Reasoning position context historyUci does not replay to fenBefore");
+  if (value.kind === "position") {
+    if (value.moveUci !== "" || value.moveSan !== "" || value.parentNodeId || value.historyUci.length || value.fenBefore !== value.fenAfter || !value.historyStartFen || new Chess5(value.historyStartFen).fen() !== value.fenBefore)
+      throw new Error("Invalid starting-position context");
+    return { ...value, historyUci: [] };
+  }
+  const before = new Chess5(value.fenBefore);
+  let applied;
+  try {
+    applied = before.move({ from: value.moveUci.slice(0, 2), to: value.moveUci.slice(2, 4), promotion: value.moveUci.slice(4) || void 0 });
+  } catch {
+    applied = null;
+  }
+  if (!applied) throw new Error("Reasoning position context target move is illegal in fenBefore");
+  if (applied.san !== value.moveSan) throw new Error("Reasoning position context moveSan does not match the target move");
+  if (before.fen() !== value.fenAfter) throw new Error("Reasoning position context fenAfter does not match the target move");
+  return { ...value, historyUci: [...value.historyUci] };
+}
+function reasoningContextHash(context2) {
+  const checked = validateReasoningPositionContext(context2);
+  return stableHash({ nodeId: checked.nodeId, parentNodeId: checked.parentNodeId || null, historyStartFen: checked.historyStartFen || null, fenBefore: checked.fenBefore, fenAfter: checked.fenAfter, historyUci: checked.historyUci, moveUci: checked.moveUci });
+}
+
+// src/chess-reasoning/recorded-main-line.ts
+function validRecordedAnalysis(value, before, after, uci2) {
+  if (!value || value.version !== "recorded-move-analysis/1" || value.fenBefore !== before || value.fenAfter !== after || value.moveUci !== uci2) return false;
+  const boundedText = (s, max) => typeof s === "string" && s.length > 0 && s.length <= max && /^[a-zA-Z0-9@._/ +:-]+$/.test(s);
+  const depth = (n) => Number.isInteger(n) && n > 0 && n <= 256;
+  const score = (n) => n === null || typeof n === "number" && Number.isFinite(n) && Math.abs(n) <= 1e6;
+  return boundedText(value.engine, 64) && boundedText(value.classification, 40) && depth(value.actualDepth) && depth(value.requestedDepth) && Number.isInteger(value.classifierVersion) && value.classifierVersion > 0 && value.classifierVersion <= 1e5 && [value.beforeCp, value.afterCp, value.lossCp, value.mateBefore, value.mateAfter].every(score);
+}
+function recordedMainLineResult(line, context2) {
+  if (!line || !Array.isArray(line.moves) || line.moves.length > 512 || !Number.isInteger(line.selectedIndex) || line.selectedIndex < -1 || !Number.isInteger(line.totalPlies) || line.totalPlies < line.moves.length || line.selectedIndex >= line.totalPlies || line.truncated !== line.totalPlies > line.moves.length) throw Error("Invalid recorded main line.");
+  const atStart = context2.kind === "position";
+  if (atStart && (line.selectedAtStart !== true || line.selectedIndex !== -1 || line.startFen !== context2.fenAfter)) throw Error("Recorded starting-position scope mismatch.");
+  if (!atStart && line.selectedAtStart) throw Error("Recorded anchor kind mismatch.");
+  const chess = new Chess6(line.startFen);
+  const historyRoot = new Chess6(atStart ? context2.fenAfter : context2.historyStartFen).fen();
+  if (chess.fen() !== historyRoot) throw Error("Recorded main-line root mismatch.");
+  const rows = [];
+  const moves2 = line.moves.map((item, index) => {
+    if (!/^[a-h][1-8][a-h][1-8][qrbn]?$/.test(item.uci)) throw Error("Invalid recorded move.");
+    const before = chess.fen(), move = chess.move({ from: item.uci.slice(0, 2), to: item.uci.slice(2, 4), promotion: item.uci.slice(4) || void 0 });
+    if (move.san !== item.san) throw Error("Recorded SAN mismatch.");
+    if (index === line.selectedIndex && (before !== context2.fenBefore || chess.fen() !== context2.fenAfter || item.uci !== context2.moveUci || index !== context2.historyUci.length || line.moves.slice(0, index).some((m, i) => m.uci !== context2.historyUci[i]))) throw Error("Recorded question scope mismatch.");
+    const a = item.analysis;
+    if (validRecordedAnalysis(a, before, chess.fen(), item.uci)) {
+      const score = savedScorePresentation(a);
+      rows.push([
+        index + 1,
+        a.engine,
+        a.actualDepth,
+        a.requestedDepth,
+        a.classifierVersion,
+        a.classification,
+        score.beforeCp,
+        score.afterCp,
+        score.lossCp,
+        score.mateBefore,
+        score.mateAfter
+      ]);
+    }
+    return { uci: item.uci, san: move.san, moveNumber: Number(before.split(" ")[5]), color: move.color };
+  });
+  const continuation = atStart ? moves2.map((move) => move.uci) : line.selectedIndex >= 0 && line.selectedIndex < moves2.length ? moves2.slice(line.selectedIndex + 1).map((move) => move.uci) : [];
+  const contextHash = reasoningContextHash(context2);
+  const evidence = continuation.length ? [{
+    schemaVersion: REASONING_POC_VERSION,
+    id: `evidence:recorded-main-line:${contextHash}:${continuation.slice(0, 32).join("-")}`,
+    contextHash,
+    kind: "fact",
+    source: "loaded-game-main-line",
+    proofStrength: "observed",
+    licenses: ["chess.legality", "chess.identity"],
+    summary: "Legally replayed recorded main-line continuation; not an engine recommendation or proof of intent.",
+    data: { authority: "legal-exact", scope: "sequence-legality-and-identity", phase: "after" },
+    coverage: { complete: false, covered: [], unresolved: ["No optimality or human-intent claim."] },
+    replay: { fen: context2.fenAfter, movesUci: continuation.slice(0, 32) }
+  }] : [];
+  return {
+    contextHash,
+    evidence,
+    recordedAnalysis: {
+      source: "Current loaded game's stored per-move analysis snapshots",
+      authority: "attributed-existing-analysis",
+      scorePerspective: "mover-at-each-recorded-ply",
+      units: "centipawns; mate separate",
+      coverage: { analyzedPlies: rows.length, totalPlies: line.totalPlies, complete: !line.truncated && rows.length === line.totalPlies },
+      columns: ["ply", "engine", "reportedDepth", "recordedRequestedDepth", "classifierVersion", "classification", "beforeCp", "afterCp", "lossCp", "mateBefore", "mateAfter"],
+      rows,
+      limitations: ["reportedDepth is the stored classification depth, not a verified root-search depth; recordedRequestedDepth is the board setting recorded when classified.", "Matching stored edge analyses are included even when their engine, classifier version or dependency fingerprint is no longer current; missing or invalid plies have no analysis row.", "Scores are from the mover's perspective at each row's ply: positive favors that move's color; lossCp is a saved before/after search delta for that mover, not a controlled regret comparison. Mate-related/sentinel centipawn fields are null; use mateBefore/mateAfter. Best or Forced labels can coexist with search-score changes.", "Classification is a historical decision from the reported classifier version, not necessarily current policy or proof of its explanation. Saved scores may differ from fresh searches.", ...line.truncated ? ["Analysis is limited to the first 512 recorded plies."] : []]
+    },
+    recordedMainLine: {
+      source: "Current loaded game's recorded primary line (may contain user edits)",
+      startFen: line.startFen,
+      moves: moves2,
+      selectedIndex: line.selectedIndex,
+      selectedAtStart: atStart,
+      selectedOnMainLine: atStart || line.selectedIndex >= 0,
+      totalPlies: line.totalPlies,
+      truncated: line.truncated,
+      pgn: chess.pgn()
+    },
+    limitations: ["PGN is reconstructed from recorded moves; original headers, clocks and result metadata are not included.", "Recorded play is not engine evidence of best play, force, safety or human intent.", ...!atStart && line.selectedIndex < 0 ? ["The question is on a branch; this main line is not its continuation."] : [], ...line.truncated ? ["Only the first 512 plies are returned."] : []]
+  };
+}
+
+// src/chess-reasoning/recorded-position-tools.ts
+import { Chess as Chess11 } from "chess.js";
+
+// src/chess-reasoning/branch-expansion.ts
+import { Chess as Chess7 } from "chess.js";
+
+// src/chess-reasoning/poc-tools.ts
+import { Chess as Chess10, SQUARES as SQUARES4 } from "chess.js";
+
+// src/chess-reasoning/concept-registry.ts
+var ENTITY_TYPES = {
+  IDEA: "idea",
+  PLAN: "plan",
+  ROLE: "role-assignment",
+  CONDITION: "condition",
+  TRANSFORMATION: "transformation",
+  OUTCOME: "outcome"
+};
+var PARTICIPANT_ROLES = {
+  ACTOR: "actor",
+  SUBJECT: "subject",
+  TARGET: "target",
+  GOAL: "goal",
+  RESOURCE: "resource",
+  DEFENDER: "defender",
+  DESTINATION: "destination"
+};
+var CONCEPT_KEYS = {
+  OFFER: "material.offer",
+  MATERIAL_CLAIM: "material.claim",
+  FORK: "tactic.fork",
+  TRAPPED_TARGET: "tactic.trapped-target",
+  PROMOTION: "tactic.promotion",
+  MATING_ATTACK: "attack.mating",
+  PERPETUAL_CHECK: "attack.perpetual-check",
+  POSITIONAL_CLAIM: "position.claim",
+  KING_ATTACK_PLAN: "plan.king-attack",
+  PIECE_ROLE: "role.piece-function",
+  CHANGED_CONSTRAINT: "condition.changed-constraint",
+  POSITIONAL_TRANSFORMATION: "position.transformation"
+};
+var COMMON_TERMINAL_STATES = ["converted", "refuted", "abandoned", "expired"];
+function claimLifecycle(capturedBy) {
+  return {
+    initialState: "created",
+    retainedState: "retained",
+    terminalStates: [...COMMON_TERMINAL_STATES],
+    trackedParticipantRole: PARTICIPANT_ROLES.TARGET,
+    expireWhenTrackedUnavailable: true,
+    onTrackedCapture: {
+      capturedBy,
+      matchingState: "converted",
+      matchingAnnotation: "converted",
+      otherState: "refuted",
+      otherAnnotation: "refuted"
+    }
+  };
+}
+function createConceptRegistry(definitions) {
+  const registry = {};
+  for (const definition of definitions) {
+    if (!definition.key.trim()) throw new Error("Concept keys must not be empty");
+    if (registry[definition.key]) throw new Error(`Duplicate concept key: ${definition.key}`);
+    registry[definition.key] = Object.freeze({
+      ...definition,
+      lifecycle: definition.lifecycle ? Object.freeze({
+        ...definition.lifecycle,
+        terminalStates: Object.freeze([...definition.lifecycle.terminalStates]),
+        onTrackedCapture: definition.lifecycle.onTrackedCapture ? Object.freeze({ ...definition.lifecycle.onTrackedCapture }) : void 0
+      }) : void 0
+    });
+  }
+  return Object.freeze(registry);
+}
+var DEFAULT_CONCEPT_REGISTRY = createConceptRegistry([
+  {
+    key: CONCEPT_KEYS.OFFER,
+    label: "Material offer",
+    category: "tactical",
+    description: "A material liability the opponent may choose to accept.",
+    defaultEntityType: ENTITY_TYPES.IDEA,
+    acceptancePolicy: "material-offer-liability/1",
+    lifecycle: claimLifecycle("opponent")
+  },
+  {
+    key: CONCEPT_KEYS.MATERIAL_CLAIM,
+    label: "Material claim",
+    category: "tactical",
+    description: "An evidence-backed entitlement to win material.",
+    defaultEntityType: ENTITY_TYPES.IDEA,
+    lifecycle: claimLifecycle("owner")
+  },
+  {
+    key: CONCEPT_KEYS.FORK,
+    label: "Fork",
+    category: "tactical",
+    description: "One resource attacks multiple targets.",
+    defaultEntityType: ENTITY_TYPES.IDEA,
+    lifecycle: claimLifecycle("owner")
+  },
+  {
+    key: CONCEPT_KEYS.TRAPPED_TARGET,
+    label: "Trapped target",
+    category: "tactical",
+    description: "A target lacks an adequate escape or defensive resource.",
+    defaultEntityType: ENTITY_TYPES.IDEA,
+    lifecycle: claimLifecycle("owner")
+  },
+  {
+    key: CONCEPT_KEYS.PROMOTION,
+    label: "Promotion",
+    category: "tactical",
+    description: "A promotion event or promotion claim.",
+    defaultEntityType: ENTITY_TYPES.IDEA
+  },
+  {
+    key: CONCEPT_KEYS.MATING_ATTACK,
+    label: "Mating attack",
+    category: "tactical",
+    description: "A coordinated plan whose concrete target is mate.",
+    defaultEntityType: ENTITY_TYPES.PLAN
+  },
+  {
+    key: CONCEPT_KEYS.PERPETUAL_CHECK,
+    label: "Perpetual check",
+    category: "tactical",
+    description: "A claim to a repeatable checking sequence.",
+    defaultEntityType: ENTITY_TYPES.IDEA
+  },
+  {
+    key: CONCEPT_KEYS.POSITIONAL_CLAIM,
+    label: "Positional claim",
+    category: "positional",
+    description: "A measured, evidence-bounded positional interpretation.",
+    defaultEntityType: ENTITY_TYPES.IDEA
+  },
+  {
+    key: CONCEPT_KEYS.KING_ATTACK_PLAN,
+    label: "King attack plan",
+    category: "plan",
+    description: "A goal-directed sequence intended to attack the king.",
+    defaultEntityType: ENTITY_TYPES.PLAN
+  },
+  {
+    key: CONCEPT_KEYS.PIECE_ROLE,
+    label: "Piece role",
+    category: "role",
+    description: "A context-dependent function performed by a piece.",
+    defaultEntityType: ENTITY_TYPES.ROLE
+  },
+  {
+    key: CONCEPT_KEYS.CHANGED_CONSTRAINT,
+    label: "Changed constraint",
+    category: "condition",
+    description: "A condition whose importance changed after a move or sequence.",
+    defaultEntityType: ENTITY_TYPES.CONDITION
+  },
+  {
+    key: CONCEPT_KEYS.POSITIONAL_TRANSFORMATION,
+    label: "Positional transformation",
+    category: "transformation",
+    description: "A causal change in the meaning of a positional feature.",
+    defaultEntityType: ENTITY_TYPES.TRANSFORMATION
+  }
+]);
+
+// src/chess-reasoning/poc-move-witnesses.ts
+import { Chess as Chess8 } from "chess.js";
+
+// src/chess-reasoning/poc-hypotheses.ts
+var RECORD_HYPOTHESES_DESCRIPTOR = {
+  name: "record_hypotheses",
+  category: "graph",
+  description: "Record model-originated semantic hypotheses and causal relations in the provisional Hypothesis Ledger. Hypotheses may cite observations or be novel with zero source observations; novel concrete claims still need evidence before acceptance. parentHypothesisIds means refinement lineage only, never causal order: normally use [] and express enables/supports/explains order in relations. A true refinement may name an earlier ledger ID or same-batch localId and must preserve parent owner/concepts/anchors or include explicit refinementReason and removedAnchorReasons attributes.",
+  inputSchema: {
+    type: "object",
+    required: ["hypotheses", "relations"],
+    properties: {
+      hypotheses: {
+        type: "array",
+        minItems: 1,
+        maxItems: 16,
+        items: {
+          type: "object",
+          required: ["localId", "entityType", "concepts", "owner", "participants", "attributes", "proofStrength", "evidenceIds", "sourceObservationIds", "parentHypothesisIds", "anchorRequirements"],
+          properties: {
+            localId: { type: "string", maxLength: 160 },
+            entityType: { type: "string", maxLength: 160 },
+            concepts: { type: "array", minItems: 1, maxItems: 4, items: { type: "string", maxLength: 160 } },
+            owner: { type: ["string", "null"], enum: ["w", "b", null] },
+            participants: participantArraySchema(12),
+            attributes: { type: "object", maxProperties: 24, propertyNames: { type: "string", minLength: 1, maxLength: 80 }, additionalProperties: true },
+            proofStrength: { type: ["string", "null"], enum: ["observed", "supported", "forced", null] },
+            evidenceIds: { type: "array", maxItems: 12, items: { type: "string", maxLength: 200 } },
+            sourceObservationIds: { type: "array", maxItems: 12, items: { type: "string", maxLength: 200 } },
+            parentHypothesisIds: { type: "array", maxItems: 8, description: "Refinement lineage only, not causal order. Usually []. True refinements may use existing hypothesis IDs or same-batch localIds and must satisfy refinement compatibility.", items: { type: "string", maxLength: 200 } },
+            anchorRequirements: {
+              type: "array",
+              maxItems: 12,
+              items: {
+                type: "object",
+                required: ["participant", "disposition"],
+                properties: { participant: participantSchema(), disposition: { type: "string", enum: ["required"] } },
+                additionalProperties: false
+              }
+            }
+          },
+          additionalProperties: false
+        }
+      },
+      relations: {
+        type: "array",
+        maxItems: 24,
+        items: {
+          type: "object",
+          required: ["relationType", "from", "to", "attributes", "evidenceIds", "sourceObservationIds"],
+          properties: {
+            relationType: { type: "string", maxLength: 160 },
+            from: { type: "string", maxLength: 200 },
+            to: { type: "string", maxLength: 200 },
+            attributes: { type: "object", maxProperties: 24, propertyNames: { type: "string", minLength: 1, maxLength: 80 }, additionalProperties: true },
+            evidenceIds: { type: "array", minItems: 1, maxItems: 12, items: { type: "string", maxLength: 200 } },
+            sourceObservationIds: { type: "array", maxItems: 12, items: { type: "string", maxLength: 200 } }
+          },
+          additionalProperties: false
+        }
+      }
+    },
+    additionalProperties: false
+  }
+};
+function participantSchema() {
+  return {
+    type: "object",
+    required: ["role", "ref"],
+    properties: {
+      role: { type: "string", maxLength: 160 },
+      ref: {
+        type: "object",
+        required: ["domain", "id"],
+        properties: { domain: { type: "string", maxLength: 160 }, id: { type: "string", maxLength: 200 } },
+        additionalProperties: false
+      }
+    },
+    additionalProperties: false
+  };
+}
+function participantArraySchema(maxItems) {
+  return { type: "array", maxItems, items: participantSchema() };
+}
+function isRecord(value) {
+  return Boolean(value) && typeof value === "object" && !Array.isArray(value);
+}
+var CONCEPT_ACCEPTANCE_VALIDATORS = Object.freeze({
+  "material-offer-liability/1": (hypothesis, records) => {
+    const contradictedCapture = records.find((record) => {
+      if (record.kind !== "fact" || record.data.kind !== "move.legal_recaptures_after") return false;
+      const data = isRecord(record.data.data) ? record.data.data : null;
+      return data?.targetPieceColor === hypothesis.owner && data.allCapturesLoseAfterImmediateSameSquareRecapture === true;
+    });
+    const contradictedData = contradictedCapture && isRecord(contradictedCapture.data.data) ? contradictedCapture.data.data : null;
+    const captureMoves = Array.isArray(contradictedData?.moves) ? contradictedData.moves.flatMap((move) => isRecord(move) && typeof move.uci === "string" ? [move.uci] : []) : [];
+    const strongerBoundedEvidence = captureMoves.length > 0 && records.some((record) => {
+      if (record.kind !== "probe" || record.proofStrength !== "supported" && record.proofStrength !== "forced") return false;
+      const roots = Array.isArray(record.data.rootMoves) ? record.data.rootMoves.filter((move) => typeof move === "string") : [];
+      return captureMoves.every((move) => roots.includes(move));
+    });
+    return contradictedCapture && !strongerBoundedEvidence ? [`Hypothesis ${hypothesis.id} calls the owner's moved piece a material offer even though cited exhaustive immediate-capture evidence shows every capture can be answered on the same square with a negative nominal balance delta for the capturing side (${contradictedCapture.id})`] : [];
+  }
+});
+
+// src/chess-reasoning/matched-comparison.ts
+import { Chess as Chess9 } from "chess.js";
+
+// src/chess-reasoning/recorded-position-tools.ts
+var moves = { type: "array", maxItems: 32, items: { type: "string", maxLength: 5, pattern: "^[a-h][1-8][a-h][1-8][qrbn]?$" } };
+var common = { ply: { type: "integer", minimum: 0, maximum: 512 }, depth: { type: "integer", minimum: 18, maximum: 18 }, minimumPvPlies: { type: "integer", minimum: 1, maximum: 32 } };
+var RECORDED_POSITION_DESCRIPTORS = [
+  { name: "analyze_game_position", category: "probe", description: "analyze_game_position", inputSchema: { type: "object", additionalProperties: false, required: ["ply"], properties: { ...common, rootMoves: { ...moves, minItems: 1, maxItems: 6 }, multiPv: { type: "integer", minimum: 1, maximum: 3 } } } },
+  { name: "test_game_line", category: "probe", description: "test_game_line", inputSchema: { type: "object", additionalProperties: false, required: ["ply", "movesUci"], properties: { ...common, movesUci: { ...moves, minItems: 1 }, analyzeFinal: { type: "boolean" }, compareFinalMovesUci: { ...moves, minItems: 1, maxItems: 6 }, inspectPlies: { type: "array", maxItems: 8, items: { type: "integer", minimum: 1, maximum: 32 } }, inspectSquares: { type: "array", maxItems: 12, items: { type: "string", maxLength: 2, pattern: "^[a-h][1-8]$" } } } } }
+];
+function recordedPositionContext(line, ply) {
+  if (!Number.isInteger(ply) || ply < 0 || ply > line.moves.length) throw Object.assign(Error(`ply must be between 0 and ${line.moves.length}; 0 is the initial position`), { code: "invalid-recorded-ply", field: "ply", expected: `integer 0..${line.moves.length}` });
+  const chess = new Chess11(line.startFen), prefix = line.moves.slice(0, ply);
+  let before = chess.fen();
+  for (const item of prefix) {
+    before = chess.fen();
+    const m = chess.move({ from: item.uci.slice(0, 2), to: item.uci.slice(2, 4), promotion: item.uci.slice(4) || void 0 });
+    if (m.san !== item.san) throw Error("recorded-SAN-mismatch");
+  }
+  const id = `recorded:${stableHash({ startFen: line.startFen, moves: line.moves.map((m) => m.uci) })}:${ply}`;
+  return ply === 0 ? { kind: "position", nodeId: id, historyStartFen: line.startFen, historyUci: [], fenBefore: chess.fen(), fenAfter: chess.fen(), moveUci: "", moveSan: "" } : { nodeId: id, historyStartFen: line.startFen, historyUci: prefix.slice(0, -1).map((m) => m.uci), fenBefore: before, fenAfter: chess.fen(), moveUci: prefix.at(-1).uci, moveSan: prefix.at(-1).san };
+}
+
+// src/chess-reasoning/initial-search-plan.ts
+var normalize = (san) => san.replace(/[+#?!]+$/, "");
+var uci = (m) => m.from + m.to + (m.promotion ?? "");
+function planInitialSearches(input2) {
+  const { question: q, context: context2, mainLine } = input2;
+  const result = { version: "initial-search-plan/1", requests: [], limitations: [] };
+  const record = mainLine ? recordedMainLineResult(mainLine, context2) : void 0;
+  if (input2.classificationQuestion && !input2.omitSelectedContext && context2.kind !== "position") {
+    result.classificationReassessment = true;
+    result.requests.push({ tool: "explore_continuations", input: { phase: "before", depth: 18, multiPv: 3, minimumPvPlies: 10 }, reason: "Reassess the selected move classification using a depth-18 unrestricted before-position search. Preserve the original decision and refresh the canonical label afterwards." });
+  }
+  const names = [...q.matchAll(/(?<![A-Za-z0-9])(?: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)].map((m) => normalize(m[0]));
+  const alternative = /\b(better|instead|alternative|compare|rather)\b|\bwhat (?:if|about)\b|\b(?:could|should)\b.*\bplay\b/i.test(q);
+  const negated = /\b(?:don't|do not|no need to|without)\b.*\b(?:compare|analy[sz]e|instead|alternative)\b/i.test(q);
+  if (names.length && names.length <= 6 && alternative && !negated) {
+    let fen, phase = "before", ply, played;
+    const numbered = [...q.matchAll(/\b(\d+)\s*(\.{1,3}|…)\s*(?=[KQRBNa-hO])/g)];
+    const unboundNumber = /\b\d+\b/.test(q.replace(/\b(\d+)\s*(\.{1,3}|…)\s*(?=[KQRBNa-hO])/g, ""));
+    if (numbered.length && !unboundNumber && record && mainLine) {
+      const roots = numbered.map((m) => record.recordedMainLine.moves.flatMap((move, i) => move.moveNumber === Number(m[1]) && move.color === (m[2] === "." ? "w" : "b") ? [i] : []));
+      if (roots.every((r) => r.length === 1 && r[0] === roots[0][0])) {
+        ply = roots[0][0];
+        fen = recordedPositionContext(mainLine, ply).fenAfter;
+        played = mainLine.moves[ply]?.uci;
+      }
+    } else if (!numbered.length && !/\b\d+\b/.test(q) && !input2.omitSelectedContext && !/\b(later|earlier|previous|opening|endgame|middlegame|move\s+\d+)\b/i.test(q)) {
+      phase = /\b(next|reply|respond)\b/i.test(q) ? "after" : "before";
+      fen = phase === "after" ? context2.fenAfter : context2.fenBefore;
+      played = phase === "before" && context2.kind !== "position" ? context2.moveUci : void 0;
+      const explicitRole = /\b(instead|alternative|rather|than|next|reply|respond)\b/i.test(q);
+      if (!explicitRole && context2.fenBefore !== context2.fenAfter) {
+        const other = new Chess12(context2.fenAfter).moves().map(normalize);
+        if (names.every((n) => other.includes(n))) fen = void 0;
+      }
+    }
+    if (fen) {
+      const legal = new Chess12(fen).moves({ verbose: true });
+      const resolved = names.map((n) => legal.filter((m) => normalize(m.san) === n));
+      if (resolved.every((ms) => ms.length === 1)) {
+        const roots = [.../* @__PURE__ */ new Set([...resolved.map((ms) => uci(ms[0])), ...played ? [played] : []])];
+        if (roots.length && roots.length <= 6 && (!played || roots.some((r) => r !== played))) {
+          result.requests.push({ tool: ply === void 0 ? "compare_moves" : "analyze_game_position", input: { ...ply === void 0 ? { phase, movesUci: roots } : { ply, rootMoves: roots }, depth: 18, minimumPvPlies: 10 }, reason: "Explicit named legal alternatives at one resolved root; compare with the recorded/selected move when applicable." });
+          return result;
+        }
+      }
+    }
+    result.limitations.push("Named moves were not unambiguously resolved for automatic search; the model may choose the root and query.");
+  }
+  if (input2.positionPreparation !== false && !input2.omitSelectedContext && !input2.reviewGame && (input2.answerScope === "position_analysis" || !input2.answerScope && context2.kind === "position") && !names.length) {
+    try {
+      const phase = context2.kind === "position" ? "before" : "after";
+      const fen = phase === "before" ? context2.fenBefore : context2.fenAfter;
+      if (!new Chess12(fen).isGameOver()) result.requests.push({
+        tool: "explore_continuations",
+        input: { phase, depth: 18, multiPv: 3, minimumPvPlies: 24 },
+        reason: "Initial current-position candidates and continuations. Reuse this evidence and investigate additional relevant plans with the available tools; these returned moves are not exhaustive."
+      });
+    } catch {
+      result.limitations.push("Current-position preparation unavailable: invalid position.");
+    }
+    return result;
+  }
+  if (!record || !mainLine || !input2.reviewGame || !input2.omitSelectedContext) return result;
+  if (names.length || /\b(?:endgame|middlegame|late|last|after|before)\b|\bmove\s+\d+/i.test(q)) {
+    result.limitations.push("Specific move or phase boundary requires model-directed investigation.");
+    return result;
+  }
+  const subject = input2.reviewSubject ?? "unspecified";
+  const relative = subject === "self" || subject === "opponent";
+  const playerSide = input2.playerPerspective?.side;
+  const side = subject === "white" || subject === "black" ? subject : relative && playerSide ? subject === "self" ? playerSide : playerSide === "white" ? "black" : "white" : void 0;
+  result.reviewScope = { subject, resolvedSide: side ?? (relative ? "unknown" : "both") };
+  if (relative && !side) {
+    result.limitations.push("Player side unknown; defer personal/opponent review preparation to the answering model.");
+    return result;
+  }
+  const opening = /\bopening\b/i.test(q);
+  if (opening && mainLine.startFen !== new Chess12().fen()) {
+    result.limitations.push("Opening boundary unknown for a custom starting position.");
+    return result;
+  }
+  if (opening) result.limitations.push("Preparation uses the first 12 full moves as an opening-review heuristic, not a claim that the opening ends there.");
+  const eligible = record.recordedAnalysis.rows.filter((row) => {
+    const move = record.recordedMainLine.moves[row[0] - 1];
+    return (!side || move.color === (side === "white" ? "w" : "b")) && (!opening || move.moveNumber <= 12);
+  });
+  const rank = (row) => row[8] ?? (row[9] !== null && row[10] !== null ? Math.max(0, Math.abs(row[10]) - Math.abs(row[9])) : 0);
+  const ordered = (rows) => rows.sort((a, b) => rank(b) - rank(a) || a[0] - b[0]);
+  const major = ordered(eligible.filter((row) => ["blunder", "mistake", "miss"].includes(row[5])));
+  const optional = major.length < 10 ? ordered(eligible.filter((row) => row[5] === "dubious")).slice(0, Math.min(5, 10 - major.length)) : [];
+  for (const row of [...major, ...optional]) {
+    const score = row[9] !== null || row[10] !== null ? `mate before ${row[9] ?? "not found"}, mate after ${row[10] ?? "not found"}` : row[8] !== null ? `saved search delta ${row[8]}cp` : "no comparable centipawn loss";
+    result.requests.push({ tool: "analyze_game_position", input: { ply: row[0] - 1, multiPv: 3, depth: 18, minimumPvPlies: 10 }, playedMove: mainLine.moves[row[0] - 1].uci, reason: `Review candidate at recorded ply ${row[0]}: saved ${row[5]}, ${score} at depth ${row[2]}. Discover strongest alternatives and ensure a matched comparison with the played move; classification is historical.` });
+  }
+  if (!result.requests.length) result.limitations.push("No matching saved Blunder, Mistake, Miss or Dubious moves; model may investigate other useful moments.");
+  return result;
+}
+
+// test/owner/position-preparation.test.mjs
+var 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;
+var 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 Chess13(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");
+});