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

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

@@ -0,0 +1,240 @@
+// test/owner/score-comparison-notices.test.mjs
+import test from "node:test";
+import assert from "node:assert/strict";
+
+// src/chess-reasoning/matched-comparison.ts
+import { Chess } from "chess.js";
+function matchedRootComparison(result, fen2, requiredRoots = []) {
+  const lines = Array.isArray(result.lines) ? result.lines : [];
+  const rootMoves = lines.flatMap((line) => line && typeof line.rootMove === "string" ? [line.rootMove] : []);
+  const unmatched = (reason) => ({ status: "unmatched", actualDepth: null, rootMoves, reason });
+  if ((result.sourceCacheProvenance ?? result.cacheProvenance) !== "engine") return unmatched("Common engine search identity is unavailable.");
+  if (rootMoves.length !== lines.length) return unmatched("A compared root is malformed.");
+  if (lines.length < 2 || new Set(rootMoves).size !== rootMoves.length || requiredRoots.some((root) => !rootMoves.includes(root))) return unmatched("The search does not cover all compared moves.");
+  try {
+    const legal = new Set(new Chess(fen2).moves({ verbose: true }).map((move) => move.from + move.to + (move.promotion || "")));
+    if (rootMoves.some((root) => !legal.has(root))) return unmatched("A compared move is not legal at this root.");
+  } catch {
+    return unmatched("The comparison root is invalid.");
+  }
+  const depth = lines[0].depth, perspective = fen2.split(" ")[1] === "w" ? "white" : fen2.split(" ")[1] === "b" ? "black" : null;
+  if (!perspective || !Number.isSafeInteger(depth) || depth < 1 || lines.some((line) => line.depth !== depth)) return unmatched("The moves have no common achieved depth.");
+  for (const line of lines) {
+    if (line.scoreScope?.fen !== fen2 || line.scoreScope.perspective !== perspective || line.scoreScope.positiveMeans !== "advantage for perspective color") return unmatched("The score roots or perspectives differ.");
+    if (line.matePly == null ? !Number.isFinite(line.scoreCp) || Math.abs(line.scoreCp) >= 1e5 : !Number.isFinite(line.matePly)) return unmatched("A compared score is unavailable.");
+    if (line.matePly == null ? line.scoreScope.scoreCpUnit !== "centipawns" : line.scoreScope.matePlyUnit !== "signed mate-in-moves (legacy field name, not plies)") return unmatched("The score units are unknown.");
+    const origin = line.scoreProvenance;
+    if (origin && (origin.kind !== "root-search" || origin.fen !== fen2 || origin.originatingDepth !== depth)) return unmatched("A score is not a matching root-search measurement.");
+    if (origin?.engineBuild != null && origin.engineBuild !== result.engineBuild) return unmatched("The engine builds differ.");
+    if (origin?.command != null && result.command && origin.command !== result.command) return unmatched("The search commands differ.");
+  }
+  if (new Set(lines.flatMap((line) => typeof line.scoreProvenance?.command === "string" ? [line.scoreProvenance.command] : [])).size > 1) return unmatched("The search commands differ.");
+  return { status: "matched", actualDepth: depth, rootMoves, reason: "These root scores came from one engine search at a common achieved depth." };
+}
+
+// src/chess-reasoning/score-comparison-notices.ts
+var object = (value) => value !== null && typeof value === "object" && !Array.isArray(value) ? value : null;
+var finite = (value) => typeof value === "number" && Number.isFinite(value);
+var strings = (value) => Array.isArray(value) ? value.filter((v) => typeof v === "string") : [];
+function disagreementKind(observations) {
+  const mates = observations.filter((observation) => observation.score.unit === "mate-in-moves").map((observation) => observation.score.value);
+  if (mates.length !== observations.length) return mates.length ? "mate-status-disagreement" : "centipawn-variation";
+  if (mates.some((value) => value > 0) && mates.some((value) => value < 0)) return "opposite-mate-sign";
+  return "mate-distance-variation";
+}
+var sharedInterpretation = "Different search results for the same root move; equal requested depth does not make their search scope, actual depth, cache or search history equivalent. Preserve each scoped score. For relative move comparisons prefer alternatives covered together at the same actual depth in the identified comparison records; this supports a relative claim within that search, not independent confirmation or rejection of a mate result. Do not combine scores from separate searches into a move-loss estimate. This notice alone does not require another search.";
+var interpretationFor = (kind) => {
+  const qualification = kind === "mate-status-disagreement" ? "Mate status differs: a centipawn score in another search does not refute its mating continuation, and mate distances cannot be converted to centipawns. " : kind === "opposite-mate-sign" ? "The mate signs oppose, indicating different reported mating sides; retain each search scope and inspect the underlying continuations. " : kind === "mate-distance-variation" ? "The searches report different mate distances; mate distances are not centipawns. " : "The searches report different centipawn evaluations. ";
+  return qualification + sharedInterpretation;
+};
+function originatingRootDepth(line, search, fen2) {
+  const provenance = object(line.scoreProvenance);
+  if (provenance) return provenance.kind === "root-search" && provenance.fen === fen2 && finite(provenance.originatingDepth) && Number.isInteger(provenance.originatingDepth) && provenance.originatingDepth > 0 && provenance.originatingDepth === line.depth ? provenance.originatingDepth : null;
+  const source = search.sourceCacheProvenance ?? search.cacheProvenance;
+  return source === "engine" && finite(line.depth) && Number.isInteger(line.depth) && line.depth > 0 ? line.depth : null;
+}
+function scoreComparisonNotices(records) {
+  const groups = /* @__PURE__ */ new Map();
+  for (const record of records) {
+    const wrapper = object(record.data);
+    const data = object(wrapper?.details) ?? wrapper;
+    const search = object(data?.searchScope);
+    if (!data || !search || typeof search.fen !== "string" || !Array.isArray(data.lines)) continue;
+    const fen2 = search.fen;
+    const perspective = fen2.split(" ")[1] === "w" ? "white" : fen2.split(" ")[1] === "b" ? "black" : null;
+    if (!perspective) continue;
+    const roots = strings(search.requestedRootMoves);
+    const lines = data.lines.map(object).filter((line) => !!line);
+    const scoped = (line) => {
+      const scope = object(line.scoreScope);
+      return scope?.fen === fen2 && scope.perspective === perspective && scope.positiveMeans === "advantage for perspective color";
+    };
+    const comparedRoots = roots.length ? roots : lines.map((line) => String(line.rootMove));
+    const matched = (!roots.length || record.coverage?.complete === true && roots.every((root) => record.coverage.covered.includes(root))) && matchedRootComparison({ ...data, command: search.command, cacheProvenance: search.cacheProvenance, sourceCacheProvenance: search.sourceCacheProvenance }, fen2, comparedRoots).status === "matched";
+    for (const line of lines) {
+      if (typeof line.rootMove !== "string" || !scoped(line)) continue;
+      const scope = object(line.scoreScope);
+      let score;
+      if (finite(line.matePly) && scope.matePlyUnit === "signed mate-in-moves (legacy field name, not plies)") {
+        score = { unit: "mate-in-moves", value: line.matePly };
+      } else if (line.matePly == null && finite(line.scoreCp) && Math.abs(line.scoreCp) < 1e5 && scope.scoreCpUnit === "centipawns") {
+        score = { unit: "centipawns", value: line.scoreCp };
+      } else continue;
+      const key = JSON.stringify([fen2, line.rootMove, perspective]);
+      let group = groups.get(key);
+      if (!group) {
+        group = { fen: fen2, rootMove: line.rootMove, perspective, observations: [], matched: /* @__PURE__ */ new Set() };
+        groups.set(key, group);
+      }
+      if (group.observations.some((observation) => observation.evidenceId === record.id)) continue;
+      group.observations.push({
+        evidenceId: record.id,
+        source: record.source,
+        score,
+        reportedDepth: finite(line.depth) ? line.depth : null,
+        actualDepth: originatingRootDepth(line, search, fen2),
+        requestedDepth: finite(search.requestedDepth) ? search.requestedDepth : null,
+        requestedMultiPv: finite(search.requestedMultiPv) ? search.requestedMultiPv : null,
+        rootScope: roots.length ? "restricted" : "unrestricted",
+        requestedRootMoves: roots,
+        cacheProvenance: typeof search.cacheProvenance === "string" ? search.cacheProvenance : "unreported",
+        sourceCacheProvenance: typeof search.sourceCacheProvenance === "string" ? search.sourceCacheProvenance : "unreported",
+        engine: typeof data.engine === "string" ? data.engine : null,
+        engineBuild: typeof data.engineBuild === "string" ? data.engineBuild : null,
+        ...object(line.scoreProvenance) ? { scoreProvenance: line.scoreProvenance } : {}
+      });
+      if (matched && comparedRoots.includes(line.rootMove)) group.matched.add(record.id);
+    }
+  }
+  return [...groups.values()].filter((group) => new Set(group.observations.map((observation) => JSON.stringify(observation.score))).size > 1).map((group) => {
+    const kind = disagreementKind(group.observations);
+    return {
+      fen: group.fen,
+      rootMove: group.rootMove,
+      perspective: group.perspective,
+      disagreementKind: kind,
+      observations: group.observations,
+      preferredWithinSearchComparisonEvidenceIds: [...group.matched],
+      interpretation: interpretationFor(kind)
+    };
+  });
+}
+
+// test/owner/score-comparison-notices.test.mjs
+var 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", 1e3)] : []] } };
+}
+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", 1e5, 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", 1e5), b = evidence("b", 1e5, 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/dist/owner-tests/simple-engine-presentation.test.mjs

@@ -0,0 +1,233 @@
+// test/owner/simple-engine-presentation.test.mjs
+import test from "node:test";
+import assert from "node:assert/strict";
+import { Chess as Chess2 } from "chess.js";
+
+// src/chess-reasoning/mechanism-presentation.ts
+var object = (v) => !!v && typeof v === "object" && !Array.isArray(v);
+var 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"]
+};
+function exactKeys(value, columns) {
+  return object(value) && Object.keys(value).length === columns.length && columns.every((column) => Object.hasOwn(value, column));
+}
+function encodeRows(value, columns) {
+  return columns.map((column) => value[column]);
+}
+function compactMechanism(value, targetSquares) {
+  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 = {
+    ...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."
+    }
+  };
+  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, COLUMNS.unmoved)),
+      rays: rays.map((item) => encodeRows(item, COLUMNS.rays)),
+      control: controlDelta.map((item) => encodeRows(item, COLUMNS.control))
+    },
+    checksRun: projected.checksRun,
+    scope: projected.scope,
+    presentation: projected.presentation
+  };
+}
+function presentMoveMechanisms(moves, inspectPlies = [], inspectSquares = []) {
+  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) }];
+  });
+}
+
+// src/chess-reasoning/simple-engine-presentation.ts
+import { Chess } from "chess.js";
+var object2 = (v) => !!v && typeof v === "object" && !Array.isArray(v);
+function projectEnginePresentation(value, fullGeometry = false) {
+  const visit = (v) => {
+    if (Array.isArray(v)) return v.map(visit);
+    if (!object2(v)) return v;
+    if (typeof v.id !== "string" || !object2(v.data)) {
+      return Object.fromEntries(Object.entries(v).map(([k, child]) => [k, visit(child)]));
+    }
+    const nested = object2(v.data.details) && (Array.isArray(v.data.details.lines) || Array.isArray(v.data.details.moveFacts));
+    const d = nested ? v.data.details : v.data;
+    if (Object.hasOwn(d, "modelPresentation")) return v;
+    if (object2(d.selectedMoveMechanism) && Array.isArray(d.selectedMoveMechanism.controlDelta) && !fullGeometry) {
+      const squares = d.selectedMoveMechanism.controlDelta.flatMap((delta) => object2(delta) && typeof delta.square === "string" ? [delta.square] : []);
+      const projected2 = { ...d, selectedMoveMechanism: compactMechanism(d.selectedMoveMechanism, squares) };
+      return { ...v, data: nested ? { ...v.data, details: projected2 } : projected2 };
+    }
+    if (Array.isArray(d.moveFacts) && !fullGeometry) {
+      const inspection = object2(d.mechanismInspection) ? d.mechanismInspection : {};
+      const { moveFacts, ...rest } = d;
+      const projected2 = {
+        ...rest,
+        mechanismFacts: presentMoveMechanisms(
+          moveFacts,
+          Array.isArray(inspection.inspectPlies) ? inspection.inspectPlies : [],
+          Array.isArray(inspection.inspectSquares) ? inspection.inspectSquares : []
+        ),
+        modelPresentation: {
+          mechanismThroughPly: 2,
+          explicitInspection: inspection,
+          retrieveFullEvidenceId: v.id,
+          geometryNotice: "Mechanisms shown for first two plies, explicit inspectPlies and moves landing on inspectSquares. Other plies omitted, not absent; retrieve full evidence for all replayed move facts."
+        }
+      };
+      return { ...v, data: nested ? { ...v.data, details: projected2 } : projected2 };
+    }
+    if (!Array.isArray(d.lines)) return v;
+    const rootFen = object2(d.searchScope) && typeof d.searchScope.fen === "string" ? d.searchScope.fen : void 0;
+    let omittedGeometry = 0, omittedRaw = false, referencedFen = false;
+    const lines = d.lines.map((line) => {
+      if (!object2(line) || !Array.isArray(line.pv)) return line;
+      const next = { ...line };
+      if (!Object.hasOwn(line, "rawPvSameAsPv") && Array.isArray(line.rawPv) && JSON.stringify(line.rawPv) === JSON.stringify(line.pv)) {
+        delete next.rawPv;
+        next.rawPvSameAsPv = true;
+        omittedRaw = true;
+      }
+      if (rootFen && object2(line.pvCompletion) && Array.isArray(line.pvCompletion.segments)) {
+        const fens = [];
+        try {
+          const chess = new Chess(rootFen);
+          fens.push(chess.fen());
+          for (const move of line.pv) {
+            if (typeof move !== "string" || !/^[a-h][1-8][a-h][1-8][qrbn]?$/.test(move)) break;
+            chess.move({ from: move.slice(0, 2), to: move.slice(2, 4), promotion: move.slice(4) || void 0 });
+            fens.push(chess.fen());
+          }
+        } catch {
+        }
+        next.pvCompletion = { ...line.pvCompletion, segments: line.pvCompletion.segments.map((segment) => {
+          if (!object2(segment) || !Number.isInteger(segment.startPly) || segment.startPly < 0 || typeof segment.fen !== "string" || fens[segment.startPly] !== segment.fen || Object.hasOwn(segment, "fenFromLinePvPly")) return segment;
+          const { fen: _fen, ...rest } = segment;
+          void _fen;
+          referencedFen = true;
+          return { ...rest, fenFromLinePvPly: segment.startPly };
+        }) };
+      }
+      return next;
+    });
+    const continuations = !fullGeometry && Array.isArray(d.continuationMoveFacts) ? d.continuationMoveFacts.map((c) => {
+      if (!object2(c) || !Array.isArray(c.moves)) return c;
+      const compact = presentMoveMechanisms(c.moves);
+      return { ...c, moves: c.moves.map((m, i) => {
+        if (!object2(m)) return m;
+        const next = { ...m };
+        if (i >= 2 && Object.hasOwn(next, "captureGeometry")) {
+          delete next.captureGeometry;
+          omittedGeometry++;
+        }
+        if (Object.hasOwn(next, "mechanism")) {
+          const delivered = compact.find((f) => object2(f) && f.ply === i + 1);
+          if (object2(delivered)) next.mechanism = delivered.mechanism;
+          else {
+            delete next.mechanism;
+            omittedGeometry++;
+          }
+        }
+        return next;
+      }) };
+    }) : d.continuationMoveFacts;
+    const roots = !fullGeometry && Array.isArray(d.rootMoveFacts) ? d.rootMoveFacts.map((f) => !object2(f) || !f.mechanism ? f : { ...f, mechanism: compactMechanism(f.mechanism, [String(f.to)]) }) : d.rootMoveFacts;
+    if (!omittedGeometry && !omittedRaw && !referencedFen && !Array.isArray(d.rootMoveFacts)) return v;
+    const projected = {
+      ...d,
+      lines,
+      ...roots !== void 0 ? { rootMoveFacts: roots } : {},
+      ...d.continuationMoveFacts !== void 0 ? { continuationMoveFacts: continuations } : {},
+      modelPresentation: {
+        ...omittedGeometry ? {
+          captureGeometryThroughPly: 2,
+          omittedCaptureGeometry: omittedGeometry,
+          retrieveFullEvidenceId: v.id,
+          geometryNotice: "Deeper capture and mechanism geometry omitted, not absent. Retrieve this evidence ID for full geometry; basic move and capture facts remain complete."
+        } : {},
+        ...referencedFen ? { segmentFenReference: "fenFromLinePvPly=N is the exact position after N moves of this line.pv, legally replayed from this engine result\u2019s searchScope.fen. Segment scores, depth and search provenance still apply only to that segment." } : {}
+      }
+    };
+    return { ...v, data: nested ? { ...v.data, details: projected } : projected };
+  };
+  return visit(value);
+}
+
+// test/owner/simple-engine-presentation.test.mjs
+var pv = ["e2e4", "d7d5", "e4d5", "d8d5"];
+function fixture() {
+  const b = new Chess2(), 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, void 0);
+  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, void 0);
+});
+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, void 0);
+});
+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, void 0);
+  assert.equal(v.data.details.continuationMoveFacts[0].moves[2].captureGeometry, void 0);
+  assert.equal(v.data.details.modelPresentation.retrieveFullEvidenceId, "e1");
+  assert.deepEqual(projectEnginePresentation(raw, true).evidence[0].data.details.continuationMoveFacts, data.continuationMoveFacts);
+});

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

@@ -0,0 +1,78 @@
+// test/owner/tool-input-loop-guard.test.mjs
+import test from "node:test";
+import assert from "node:assert/strict";
+
+// src/chess-reasoning/tool-input-loop-guard.ts
+function createToolInputLoopGuard() {
+  const failures = /* @__PURE__ */ new Map();
+  const stable = (value) => Array.isArray(value) ? value.map(stable) : value && typeof value === "object" ? Object.fromEntries(Object.entries(value).sort(([a], [b]) => a.localeCompare(b)).map(([key, item]) => [key, stable(item)])) : value;
+  let repeatedFailures = 0;
+  return {
+    get repeatedFailures() {
+      return repeatedFailures;
+    },
+    validate(name, input, validate) {
+      const key = JSON.stringify([name, stable(input)]);
+      const previous = failures.get(key);
+      if (previous) {
+        repeatedFailures++;
+        throw Object.assign(new Error(`Repeated invalid request was not executed. ${previous.message} Correct the named field; do not repeat unchanged arguments. If unnecessary, summarize the acquired evidence.`), {
+          code: "repeated-invalid-tool-input",
+          field: previous.field,
+          expected: previous.expected,
+          originalCode: previous.code,
+          repeatedInvalidInput: true
+        });
+      }
+      try {
+        validate();
+        if (["test_line", "test_game_line"].includes(name) && input.compareFinalMovesUci !== void 0) {
+          if (input.analyzeFinal !== true) throw Object.assign(new Error("compareFinalMovesUci requires analyzeFinal=true. Set analyzeFinal=true to compare the final position, or omit compareFinalMovesUci for replay only."), { code: "invalid-final-comparison", field: "analyzeFinal", expected: "true when compareFinalMovesUci is supplied" });
+        }
+      } catch (error) {
+        const detail = error;
+        if (typeof detail.code === "string" && typeof detail.field === "string") failures.set(key, {
+          message: typeof detail.message === "string" ? detail.message.slice(0, 600) : "Invalid tool input.",
+          code: detail.code,
+          field: detail.field,
+          expected: typeof detail.expected === "string" ? detail.expected : void 0
+        });
+        throw error;
+      }
+    }
+  };
+}
+
+// test/owner/tool-input-loop-guard.test.mjs
+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);
+});