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

package/src/chess-reasoning/idea-graph.ts

@@ -0,0 +1,224 @@
+import {
+  DEFAULT_CONCEPT_REGISTRY,
+  conceptDefinition,
+  type ConceptRegistry,
+} from "./concept-registry";
+import { stableHash } from "./stable";
+import {
+  CHESS_REASONING_POLICY_VERSION,
+  CHESS_REASONING_SCHEMA_VERSION,
+  type IdeaGraph,
+  type IdentityState,
+  type ProofStrength,
+  type SemanticAttributes,
+  type SemanticEntity,
+  type SemanticParticipant,
+  type SemanticRelation,
+  type SemanticValue,
+} from "./types";
+
+const FALLBACK_TERMINAL_STATES = new Set(["converted", "completed", "refuted", "abandoned", "expired"]);
+
+function cloneValue(value: SemanticValue): SemanticValue {
+  if (Array.isArray(value)) return value.map(cloneValue);
+  if (value && typeof value === "object") {
+    return Object.fromEntries(Object.entries(value).map(([key, item]) => [key, cloneValue(item)]));
+  }
+  return value;
+}
+
+function cloneAttributes(attributes: SemanticAttributes): SemanticAttributes {
+  return Object.fromEntries(Object.entries(attributes).map(([key, value]) => [key, cloneValue(value)]));
+}
+
+function cloneParticipants(participants: SemanticParticipant[]): SemanticParticipant[] {
+  return participants.map((item) => ({ role: item.role, ref: { ...item.ref } }));
+}
+
+export type CreateSemanticEntityInput = {
+  id?: string;
+  branchId: string;
+  entityType: string;
+  concepts: string[];
+  owner?: SemanticEntity["owner"];
+  createdByPly: number;
+  createdByUci: string;
+  participants?: SemanticParticipant[];
+  attributes?: SemanticAttributes;
+  proofStrength?: ProofStrength | null;
+  state?: string;
+  evidence?: string[];
+};
+
+export function createSemanticEntity(
+  input: CreateSemanticEntityInput,
+  registry: ConceptRegistry = DEFAULT_CONCEPT_REGISTRY,
+): SemanticEntity {
+  if (!input.concepts.length) throw new Error("A semantic entity must reference at least one registered concept");
+  for (const concept of input.concepts) {
+    if (!conceptDefinition(registry, concept)) throw new Error(`Unknown concept key: ${concept}`);
+  }
+  const concepts = [...new Set(input.concepts)].sort();
+  const participants = cloneParticipants(input.participants || []).sort((left, right) =>
+    `${left.role}:${left.ref.domain}:${left.ref.id}`.localeCompare(`${right.role}:${right.ref.domain}:${right.ref.id}`));
+  const attributes = cloneAttributes(input.attributes || {});
+  const evidence = [...new Set(input.evidence || [])].sort();
+  const primary = conceptDefinition(registry, concepts[0]);
+  const state = input.state || primary?.lifecycle?.initialState || "proposed";
+  const identity = {
+    branchId: input.branchId,
+    entityType: input.entityType,
+    concepts,
+    owner: input.owner ?? null,
+    createdByPly: input.createdByPly,
+    createdByUci: input.createdByUci,
+    participants,
+    attributes,
+  };
+  const id = input.id || `entity:${input.branchId}:${input.createdByPly}:${stableHash(identity)}`;
+  return {
+    schemaVersion: CHESS_REASONING_SCHEMA_VERSION,
+    id,
+    ...identity,
+    proofStrength: input.proofStrength ?? null,
+    state,
+    evidence,
+    transitions: [{
+      ply: input.createdByPly,
+      uci: input.createdByUci,
+      state,
+      annotation: state,
+      evidence,
+    }],
+  };
+}
+
+export type CreateSemanticRelationInput = {
+  id?: string;
+  branchId: string;
+  relationType: string;
+  from: string;
+  to: string;
+  createdAtPly: number;
+  attributes?: SemanticAttributes;
+  evidence?: string[];
+};
+
+export function createSemanticRelation(input: CreateSemanticRelationInput): SemanticRelation {
+  const attributes = cloneAttributes(input.attributes || {});
+  const evidence = [...new Set(input.evidence || [])].sort();
+  const identity = {
+    branchId: input.branchId,
+    relationType: input.relationType,
+    from: input.from,
+    to: input.to,
+    createdAtPly: input.createdAtPly,
+    attributes,
+  };
+  return {
+    id: input.id || `relation:${input.branchId}:${stableHash(identity)}`,
+    ...identity,
+    evidence,
+  };
+}
+
+export function createIdeaGraph(branchId = "main", ply = 0): IdeaGraph {
+  const seed = { branchId, ply, entities: [], relations: [], candidateOutcomes: [] };
+  return {
+    schemaVersion: CHESS_REASONING_SCHEMA_VERSION,
+    policyVersion: CHESS_REASONING_POLICY_VERSION,
+    branchId,
+    ply,
+    inputHash: stableHash(seed),
+    entities: [],
+    relations: [],
+    candidateOutcomes: [],
+  };
+}
+
+export function extendIdeaGraph(
+  graph: IdeaGraph,
+  entities: SemanticEntity[],
+  relations: SemanticRelation[] = [],
+  ply = graph.ply,
+): IdeaGraph {
+  const entityMap = new Map(graph.entities.map((entity) => [entity.id, entity]));
+  for (const entity of entities) {
+    if (entity.branchId !== graph.branchId) throw new Error(`Entity ${entity.id} belongs to another branch`);
+    const existing = entityMap.get(entity.id);
+    if (existing && stableHash(existing) !== stableHash(entity)) throw new Error(`Conflicting semantic entity ID: ${entity.id}`);
+    entityMap.set(entity.id, entity);
+  }
+  const allEntities = [...entityMap.values()].sort((left, right) => left.id.localeCompare(right.id));
+  const ids = new Set(allEntities.map((entity) => entity.id));
+  const relationMap = new Map(graph.relations.map((relation) => [relation.id, relation]));
+  for (const relation of relations) {
+    if (relation.branchId !== graph.branchId) throw new Error(`Relation ${relation.id} belongs to another branch`);
+    if (!ids.has(relation.from) || !ids.has(relation.to)) {
+      throw new Error(`Relation ${relation.id} references an unknown semantic entity`);
+    }
+    const existing = relationMap.get(relation.id);
+    if (existing && stableHash(existing) !== stableHash(relation)) throw new Error(`Conflicting semantic relation ID: ${relation.id}`);
+    relationMap.set(relation.id, relation);
+  }
+  const allRelations = [...relationMap.values()].sort((left, right) => left.id.localeCompare(right.id));
+  const copy = {
+    ...graph,
+    ply,
+    entities: allEntities,
+    relations: allRelations,
+    candidateOutcomes: graph.candidateOutcomes.map((outcome) => ({ ...outcome, evidence: [...outcome.evidence] })),
+  };
+  return { ...copy, inputHash: stableHash({ previous: graph.inputHash, ...copy, inputHash: undefined }) };
+}
+
+export function forkIdeaGraph(graph: IdeaGraph, branchId: string): IdeaGraph {
+  const idMap = new Map(graph.entities.map((entity) => [
+    entity.id,
+    `entity:${branchId}:${entity.createdByPly}:${stableHash({ source: entity.id, branchId })}`,
+  ]));
+  const entities = graph.entities.map((entity) => ({
+    ...entity,
+    id: idMap.get(entity.id) as string,
+    branchId,
+    concepts: [...entity.concepts],
+    participants: cloneParticipants(entity.participants),
+    attributes: cloneAttributes(entity.attributes),
+    evidence: [...entity.evidence],
+    transitions: entity.transitions.map((transition) => ({ ...transition, evidence: [...transition.evidence] })),
+  }));
+  const relations = graph.relations.map((relation) => createSemanticRelation({
+    branchId,
+    relationType: relation.relationType,
+    from: idMap.get(relation.from) as string,
+    to: idMap.get(relation.to) as string,
+    createdAtPly: relation.createdAtPly,
+    attributes: relation.attributes,
+    evidence: relation.evidence,
+  }));
+  const copy = {
+    ...graph,
+    branchId,
+    entities,
+    relations,
+    candidateOutcomes: graph.candidateOutcomes.map((outcome) => ({ ...outcome, evidence: [...outcome.evidence] })),
+  };
+  return { ...copy, inputHash: stableHash({ source: graph.inputHash, branchId, entities, relations }) };
+}
+
+export function graphIdentityCompatible(identity: IdentityState, graph: IdeaGraph): boolean {
+  return identity.branchId === graph.branchId && identity.ply === graph.ply;
+}
+
+export function isTerminalEntity(
+  entity: SemanticEntity,
+  registry: ConceptRegistry = DEFAULT_CONCEPT_REGISTRY,
+): boolean {
+  const registeredTerminal = entity.concepts.some((concept) =>
+    conceptDefinition(registry, concept)?.lifecycle?.terminalStates.includes(entity.state));
+  return registeredTerminal || FALLBACK_TERMINAL_STATES.has(entity.state);
+}
+
+export function openEntityCount(graph: IdeaGraph, registry: ConceptRegistry = DEFAULT_CONCEPT_REGISTRY): number {
+  return graph.entities.filter((entity) => !isTerminalEntity(entity, registry)).length;
+}

package/src/chess-reasoning/initial-search-plan.ts

@@ -0,0 +1,115 @@
+import type { AnswerScope, ReviewSubject } from './question-routing';
+import type { ReasoningEvidenceRecord } from './poc-contracts';
+import { Chess } from 'chess.js';
+import type { RecordedMainLine } from './answer-host-contracts';
+import type { PlayerPerspective } from '../player-perspective';
+import type { ReasoningPositionContext, ReasoningToolName } from './poc-contracts';
+import { recordedMainLineResult } from './recorded-main-line';
+import { recordedPositionContext } from './recorded-position-tools';
+import { matchedRootComparison } from './matched-comparison';
+import type { PositionAnalysisResult } from './poc-tools';
+
+export type InitialSearch = {tool:ReasoningToolName;input:Record<string,unknown>;reason:string;playedMove?:string};
+export type InitialSearchPlan = {version:'initial-search-plan/1';requests:InitialSearch[];limitations:string[];classificationReassessment?:boolean;reviewScope?:{subject:ReviewSubject;resolvedSide:'white'|'black'|'both'|'unknown'}};
+const normalize=(san:string)=>san.replace(/[+#?!]+$/,'');
+const uci=(m:{from:string;to:string;promotion?:string})=>m.from+m.to+(m.promotion??'');
+/** Recognition is deliberately narrow: unresolved language stays with the answering model. */
+export function planInitialSearches(input:{question:string;context:ReasoningPositionContext;mainLine?:RecordedMainLine;reviewGame?:boolean;reviewSubject?:ReviewSubject;omitSelectedContext?:boolean;playerPerspective?:PlayerPerspective|null;answerScope?:AnswerScope;positionPreparation?:boolean;classificationQuestion?:boolean}):InitialSearchPlan {
+  const {question:q,context,mainLine}=input;
+  const result:InitialSearchPlan={version:'initial-search-plan/1',requests:[],limitations:[]};
+  const record=mainLine?recordedMainLineResult(mainLine,context):undefined;
+  if(input.classificationQuestion && !input.omitSelectedContext && context.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:string|undefined,phase:'before'|'after'='before',ply:number|undefined,played:string|undefined;
+    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) && !input.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'?context.fenAfter:context.fenBefore;
+      played=phase==='before'&&context.kind!=='position'?context.moveUci:undefined;
+      // Without an explicit role cue, legal in both roots is genuinely ambiguous.
+      const explicitRole=/\b(instead|alternative|rather|than|next|reply|respond)\b/i.test(q);
+      if(!explicitRole && context.fenBefore!==context.fenAfter){const other=new Chess(context.fenAfter).moves().map(normalize);if(names.every(n=>other.includes(n)))fen=undefined;}
+    }
+    if(fen){
+      const legal=new Chess(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=[...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===undefined?'compare_moves':'analyze_game_position',input:{...(ply===undefined?{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.');
+  }
+  // The actual current-position assessment starts with the same unrestricted
+  // search available to the answering model. Do not search unrelated board
+  // state for general theory, omitted selections or retrospective reviews.
+  if(input.positionPreparation!==false && !input.omitSelectedContext && !input.reviewGame
+    && (input.answerScope==='position_analysis' || (!input.answerScope && context.kind==='position'))
+    && !names.length) {
+    try {
+      const phase=context.kind==='position'?'before':'after';
+      const fen=phase==='before'?context.fenBefore:context.fenAfter;
+      if(!new Chess(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 || !input.reviewGame || !input.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=input.reviewSubject??'unspecified';
+  const relative=subject==='self'||subject==='opponent';
+  const playerSide=input.playerPerspective?.side;
+  const side=subject==='white'||subject==='black'?subject:relative&&playerSide
+    ?subject==='self'?playerSide:playerSide==='white'?'black':'white':undefined;
+  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 Chess().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);
+  });
+  // All major classifications qualify, including missed faster mates with zero cp loss.
+  const rank=(row:typeof eligible[number])=>row[8]??(row[9]!==null&&row[10]!==null?Math.max(0,Math.abs(row[10])-Math.abs(row[9])):0);
+  const ordered=(rows:typeof eligible)=>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;
+}
+
+/** Use the same recorded-position comparison tool the model uses. Discovery may
+ * already include played+best at the same depth; otherwise compare explicitly. */
+export function preparedMoveComparison(request:InitialSearch,evidence:ReasoningEvidenceRecord[]):InitialSearch|undefined {
+  if(!request.playedMove || request.input.rootMoves) return;
+  for(const record of evidence) {
+    const data=record.data as Record<string,unknown>,details=data?.details as Record<string,unknown>|undefined;
+    const lines=details?.lines as Array<{rootMove?:string;depth?:number}>|undefined;
+    if(!Array.isArray(lines)||!lines.length)continue;
+    const roots=lines.flatMap(l=>typeof l.rootMove==='string'?[l.rootMove]:[]);
+    if(!roots.length)continue;
+    const scope=details?.searchScope as Record<string,unknown>|undefined;
+    if(roots.includes(request.playedMove)&&scope&&typeof scope.fen==='string'&&matchedRootComparison({...details,command:scope.command,cacheProvenance:scope.cacheProvenance,sourceCacheProvenance:scope.sourceCacheProvenance} as unknown as PositionAnalysisResult,scope.fen,roots).status==='matched')return;
+    const rootMoves=[...new Set([roots[0],...roots.slice(1,3),request.playedMove])];
+    return {tool:'analyze_game_position',input:{ply:request.input.ply,rootMoves,depth:18,minimumPvPlies:10},reason:`Matched comparison of played ${request.playedMove} and discovered strongest alternatives at recorded root ${request.input.ply}. Use these within-search differences for relative move claims.`};
+  }
+}

package/src/chess-reasoning/lossless-evidence-sharing.ts

@@ -0,0 +1,135 @@
+import type { ModelMessage } from 'ai';
+
+export const EVIDENCE_SHARING_VERSION = 'evidence-sharing/1';
+export const EVIDENCE_SHARING_INSTRUCTIONS = `Evidence encoding evidence-sharing/1 is lossless and self-contained. Read content with each {"$shared":"sN"} replaced by values.sN in the SAME envelope; dictionary values can themselves contain these references. Then interpret existing engine/metadata encodings normally. All values are already supplied: no tool is needed to expand them. References share identical values only, never authority, position scope, scores or search provenance. Dictionary IDs are not evidence IDs or citations.`;
+// Keep the server-only prose tree-shakeable from the browser serializer. A test
+// binds this sizing allowance to the server instruction's current length.
+export const EVIDENCE_SHARING_GUIDANCE_CHARS = 490;
+type Obj = Record<string, unknown>;
+const object = (x: unknown): x is Obj => x !== null && typeof x === 'object' && !Array.isArray(x);
+
+/** Exact JSON-value DAG. Unlike the older metadata pass, definitions are also
+ * interned recursively, so repeated children of different shared parents survive
+ * only once. Literal strings are counted after object sharing, since repeated
+ * object subtrees otherwise exaggerate their actual delivered frequency. No
+ * cross-message state or chess inference is involved. */
+export function shareEvidence(value: unknown): unknown {
+  // A caller-owned envelope is already encoded; never nest/reinterpret it.
+  if (object(value) && value.encoding === EVIDENCE_SHARING_VERSION) return value;
+  const counts = new Map<string, number>();
+  const keys = new WeakMap<object, string>();
+  let collision = false;
+  const count = (x: unknown) => {
+    if (!x || typeof x !== 'object') return;
+    if (Object.hasOwn(x, '$shared')) collision = true;
+    const key = JSON.stringify(x);
+    keys.set(x, key);
+    if (key.length >= 96) counts.set(key, (counts.get(key) ?? 0) + 1);
+    for (const child of Object.values(x)) count(child);
+  };
+  count(value);
+  if (collision) return value;
+  const values: Obj = {}, ids = new Map<string, string>();
+  const children = (x: unknown): unknown => Array.isArray(x) ? x.map(visit)
+    : object(x) ? Object.fromEntries(Object.entries(x).map(([k, v]) => [k, visit(v)])) : x;
+  const visit = (x: unknown): unknown => {
+    if (!x || typeof x !== 'object') return x;
+    const key = keys.get(x)!;
+    if ((counts.get(key) ?? 0) < 2) return children(x);
+    let id = ids.get(key);
+    if (!id) {
+      id = `s${ids.size}`; ids.set(key, id);
+      values[id] = children(x);
+    }
+    return { $shared: id };
+  };
+  let content = children(value);
+  const stringCounts = new Map<string, number>();
+  const objectDefinitions = Object.entries(values);
+  const countStrings = (x: unknown): void => {
+    if (typeof x === 'string') { stringCounts.set(x, (stringCounts.get(x) ?? 0) + 1); return; }
+    if (Array.isArray(x)) { x.forEach(countStrings); return; }
+    if (object(x) && !Object.hasOwn(x, '$shared')) Object.values(x).forEach(countStrings);
+  };
+  countStrings(content);
+  for (const [, definition] of objectDefinitions) countStrings(definition);
+
+  const stringIds = new Map<string, string>();
+  const shareStrings = (x: unknown): unknown => {
+    if (typeof x === 'string') {
+      const count = stringCounts.get(x) ?? 0;
+      let id = stringIds.get(x);
+      if (!id && count >= 2) {
+        const nextId = `s${ids.size + stringIds.size}`;
+        const literalLength = JSON.stringify(x).length;
+        const pointerLength = JSON.stringify({ $shared: nextId }).length;
+        const definitionLength = JSON.stringify(nextId).length + 1 + literalLength + 1;
+        if (count * literalLength > count * pointerLength + definitionLength) {
+          id = nextId; stringIds.set(x, id);
+          values[id] = x;
+        }
+      }
+      return id ? { $shared: id } : x;
+    }
+    if (Array.isArray(x)) return x.map(shareStrings);
+    if (object(x) && !Object.hasOwn(x, '$shared')) return Object.fromEntries(Object.entries(x).map(([k, v]) => [k, shareStrings(v)]));
+    return x;
+  };
+  content = shareStrings(content);
+  // Iterate a snapshot: new string definitions must remain literal values.
+  for (const [id, definition] of objectDefinitions) values[id] = shareStrings(definition);
+  const result = { encoding: EVIDENCE_SHARING_VERSION, values, content };
+  // Pay for the decoding guidance too; small packets stay unchanged.
+  return (ids.size || stringIds.size) && JSON.stringify(result).length + EVIDENCE_SHARING_GUIDANCE_CHARS + 128 < JSON.stringify(value).length ? result : value;
+}
+
+/** Both SDK and hosted-provider message shapes contain JSON strings. Detect an
+ * actual envelope, never an incidental mention of the codec in ordinary prose. */
+export function hasSharedEvidence(value: unknown): boolean {
+  if (typeof value === 'string') {
+    if (!value.startsWith('{') || !value.includes(EVIDENCE_SHARING_VERSION)) return false;
+    try { return hasSharedEvidence(JSON.parse(value)); } catch { return false; }
+  }
+  if (Array.isArray(value)) return value.some(hasSharedEvidence);
+  if (!object(value)) return false;
+  if (value.encoding === EVIDENCE_SHARING_VERSION && object(value.values) && Object.hasOwn(value, 'content')) return true;
+  return Object.values(value).some(hasSharedEvidence);
+}
+
+/** Strict verifier; malformed/dangling/cyclic dictionaries never decode silently. */
+export function expandSharedEvidence(value: unknown): unknown {
+  if (!object(value) || value.encoding !== EVIDENCE_SHARING_VERSION) return value;
+  if (!object(value.values) || !Object.hasOwn(value, 'content')) throw Error('invalid-evidence-sharing');
+  const values = value.values, active = new Set<string>(), expanded = new Map<string, unknown>();
+  const visit = (x: unknown): unknown => {
+    if (Array.isArray(x)) return x.map(visit);
+    if (!object(x)) return x;
+    if (Object.hasOwn(x, '$shared')) {
+      const id = x.$shared;
+      if (Object.keys(x).length !== 1 || typeof id !== 'string' || !Object.hasOwn(values, id) || active.has(id)) throw Error('invalid-evidence-sharing-reference');
+      if (!expanded.has(id)) { active.add(id); expanded.set(id, visit(values[id])); active.delete(id); }
+      return expanded.get(id);
+    }
+    return Object.fromEntries(Object.entries(x).map(([k, v]) => [k, visit(v)]));
+  };
+  return visit(value.content);
+}
+
+/** Serialize a copy at the model boundary, retaining native tool identity and
+ * opaque assistant/provider continuation objects without modification. */
+export function shareEvidenceMessages(messages: ModelMessage[]): ModelMessage[] {
+  return messages.map(message => {
+    if (message.role === 'user' && typeof message.content === 'string') {
+      let data: unknown;
+      try { data = JSON.parse(message.content); } catch { return message; }
+      if (!object(data) || data.scope !== 'CURRENT_QUESTION') return message;
+      const shared = shareEvidence(data);
+      return shared === data ? message : { ...message, content: JSON.stringify(shared) };
+    }
+    if (message.role === 'tool') return { ...message, content: message.content.map(part => {
+      if (part.type !== 'tool-result' || part.output.type !== 'json') return part;
+      return { ...part, output: { ...part.output, value: shareEvidence(part.output.value) as typeof part.output.value } };
+    }) };
+    return message;
+  });
+}

package/src/chess-reasoning/matched-comparison.ts

@@ -0,0 +1,40 @@
+import { Chess } from 'chess.js';
+import type { PositionAnalysisResult } from './poc-tools';
+
+export type MatchedComparison = {
+  status: 'matched' | 'unmatched';
+  actualDepth: number | null;
+  rootMoves: string[];
+  reason: string;
+};
+
+/** One retained engine response establishes search identity; candidate caches do not. */
+export function matchedRootComparison(result: PositionAnalysisResult, fen: string, requiredRoots: readonly string[] = []): MatchedComparison {
+  const lines = Array.isArray(result.lines) ? result.lines : [];
+  const rootMoves = lines.flatMap(line => line && typeof line.rootMove === 'string' ? [line.rootMove] : []);
+  const unmatched = (reason: string): MatchedComparison => ({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(fen).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 = fen.split(' ')[1] === 'w' ? 'white' : fen.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 !== fen || 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!) >= 100000 : !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 !== fen || origin.originatingDepth !== depth)) return unmatched('A score is not a matching root-search measurement.');
+    // Old direct engine responses have known single-dispatch identity even when
+    // they predate per-line origin metadata. A cache of saved candidates does not.
+    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.'};
+}
+
+export const MATCHED_COMPARISON_GUIDANCE = `For an explicit claim that one move is better than another, use and cite a matched comparison covering both moves at the same exact root, from one engine search at a common achieved depth. searchScope.comparison identifies matched or unmatched results. A completed engine comparison can be reused. Stored board alternatives are historical observations; their greater reported depth does not supersede a matched comparison or establish a precise relative advantage. Reuse initial preparation when its matched search already covers both choices. Otherwise request compare_moves (or the appropriate recorded-position comparison) while investigation is open. Never subtract separately cached candidate scores to support a better-than claim. If a matched comparison is unavailable or searches disagree, explain the supported chess mechanism and qualify the ranking; do not claim an absolute ordering or search again merely to resolve small cross-depth differences.`;

package/src/chess-reasoning/material-accounting.ts

@@ -0,0 +1,55 @@
+import { Chess } from 'chess.js';
+
+const pieces = { p: 'pawn', n: 'knight', b: 'bishop', r: 'rook', q: 'queen' } as const;
+type Counts = Record<typeof pieces[keyof typeof pieces], number>;
+const empty = (): Counts => ({ pawn: 0, knight: 0, bishop: 0, rook: 0, queen: 0 });
+const difference = (a: Counts, b: Counts): Counts => Object.fromEntries(
+  Object.values(pieces).map(name => [name, a[name] - b[name]]),
+) as Counts;
+
+/** Absolute counts, independent of turn, engine evaluation or starting inventory. */
+export function materialAtPosition(board: Chess) {
+  const white = empty(), black = empty();
+  for (const piece of board.board().flat()) {
+    if (piece && piece.type !== 'k') (piece.color === 'w' ? white : black)[pieces[piece.type]]++;
+  }
+  const whiteMinusBlack = difference(white, black);
+  const extras = (sign: number) => Object.entries(whiteMinusBlack)
+    .filter(([, n]) => n * sign > 0)
+    .map(([name, n]) => `${Math.abs(n)} ${name}${Math.abs(n) === 1 ? '' : 's'}`);
+  const w = extras(1), b = extras(-1);
+  return { white, black, whiteMinusBlack, balance: !w.length && !b.length
+    ? 'Equal piece counts.'
+    : [w.length ? `White has ${w.join(' and ')} more than Black` : '',
+      b.length ? `Black has ${b.join(' and ')} more than White` : ''].filter(Boolean).join('; ') + '.' };
+}
+
+/** Count by legal replay; never report a partial replay as a complete endpoint. */
+export function materialAlongLine(startFen: string, movesUci: readonly string[]) {
+  const board = new Chess(startFen), start = materialAtPosition(board);
+  const changes: { ply: number; san: string; whiteMinusBlack: Counts; balance: string }[] = [];
+  for (const [index, uci] of movesUci.entries()) {
+    if (!/^[a-h][1-8][a-h][1-8][qrbn]?$/.test(uci)) throw Error('Invalid material replay move');
+    const move = board.move({ from: uci.slice(0, 2), to: uci.slice(2, 4), promotion: uci.slice(4) || undefined });
+    if (move.captured || move.promotion) {
+      const { whiteMinusBlack, balance } = materialAtPosition(board);
+      changes.push({ ply: index + 1, san: move.san, whiteMinusBlack, balance });
+    }
+  }
+  const end = materialAtPosition(board);
+  return { authority: 'legal-replay-piece-counts', startFen, plies: movesUci.length,
+    start, changes, endFen: board.fen(), end,
+    balanceChangeFromStart: difference(end.whiteMinusBlack, start.whiteMinusBlack),
+    scope: 'Absolute piece counts at the stated positions; balanceChangeFromStart is only a change, not the final balance. Conditional line, not proof of force, safety or compensation.' };
+}
+
+export function materialForVariations<T extends { rootMove: string; pv: string[] }>(startFen: string, lines: readonly T[]) {
+  return lines.map(line => {
+    try {
+      if (!line.pv.length || line.rootMove !== line.pv[0]) throw Error('Missing root');
+      return { ...line, material: materialAlongLine(startFen, line.pv) };
+    } catch {
+      return { ...line, material: { status: 'unavailable', reason: 'The complete variation could not be legally replayed from its stated root.' } };
+    }
+  });
+}

package/src/chess-reasoning/material-format.ts

@@ -0,0 +1,47 @@
+/** Presentation only: the legally computed canonical material record is immutable. */
+export type MaterialFormat = 'raw' | 'hybrid' | 'text';
+export const DEFAULT_MATERIAL_FORMAT: MaterialFormat = 'hybrid';
+const order = ['pawn', 'knight', 'bishop', 'rook', 'queen'] as const;
+type PieceCounts = Record<typeof order[number], number>;
+interface MaterialSnapshot { white: PieceCounts; black: PieceCounts; whiteMinusBlack: PieceCounts; balance: string }
+const obj = (v: unknown): v is Record<string, unknown> => !!v && typeof v === 'object' && !Array.isArray(v);
+const keys = (v: Record<string, unknown>, expected: string[]) => Object.keys(v).every(k => expected.includes(k));
+const counts = (v: unknown): v is Record<typeof order[number], number> => obj(v)
+  && keys(v, [...order]) && order.every(k => Number.isInteger(v[k]));
+const snapshot = (v: unknown): v is MaterialSnapshot => obj(v)
+  && keys(v, ['white','black','whiteMinusBlack','balance'])
+  && counts(v.white) && counts(v.black) && counts(v.whiteMinusBlack) && typeof v.balance === 'string';
+const row = (v: Record<string, number>) => order.map(k => v[k]);
+const inventory = (v: Record<string, number>) => order.map(k => `${v[k]} ${k}${v[k] === 1 ? '' : 's'}`).join(', ');
+const textSnapshot = (v: MaterialSnapshot) => `White: ${inventory(v.white)}. Black: ${inventory(v.black)}. ${v.balance}`;
+const hybridSnapshot = (v: MaterialSnapshot) => ({white:row(v.white),black:row(v.black),balance:v.balance});
+
+function formattedMaterial(v: unknown, format: Exclude<MaterialFormat,'raw'>): unknown {
+  if (snapshot(v)) return format === 'text' ? {encoding:'material-text/1',position:textSnapshot(v)}
+    : {encoding:'material-table/1',pieceOrder:order.join(' '),...hybridSnapshot(v)};
+  if (!obj(v) || v.authority !== 'legal-replay-piece-counts'
+    || !keys(v,['authority','startFen','plies','start','changes','endFen','end','balanceChangeFromStart','scope'])
+    || typeof v.startFen !== 'string' || typeof v.endFen !== 'string' || !Number.isInteger(v.plies)
+    || !snapshot(v.start) || !snapshot(v.end) || !counts(v.balanceChangeFromStart) || typeof v.scope !== 'string'
+    || !Array.isArray(v.changes) || v.changes.some(c => !obj(c) || !keys(c,['ply','san','whiteMinusBlack','balance'])
+      || !Number.isInteger(c.ply) || typeof c.san !== 'string' || !counts(c.whiteMinusBlack) || typeof c.balance !== 'string')) return v;
+  const balanceChangeFromStart = v.balanceChangeFromStart;
+  const shared = {authority:v.authority,startFen:v.startFen,plies:v.plies,endFen:v.endFen,scope:v.scope};
+  if (format === 'hybrid') return {encoding:'material-table/1',...shared,pieceOrder:order.join(' '),
+    start:hybridSnapshot(v.start),
+    checkpointColumns:'ply san pawn knight bishop rook queen; absolute White minus Black',
+    checkpoints:v.changes.map(c => [c.ply,c.san,...row(c.whiteMinusBlack)]),
+    end:hybridSnapshot(v.end),balanceChangeFromStart:row(v.balanceChangeFromStart)};
+  return {encoding:'material-text/1',...shared,convention:'Balances list all differences; unmentioned piece types have equal counts.',start:textSnapshot(v.start),
+    checkpoints:Object.fromEntries(v.changes.map(c => [`After ply ${c.ply} (${c.san})`,c.balance])),
+    end:textSnapshot(v.end),
+    balanceChangeFromStart:`Change only, White minus Black: ${order.map(k=>`${k} ${balanceChangeFromStart[k] >= 0 ? '+' : ''}${balanceChangeFromStart[k]}`).join(', ')}.`};
+}
+
+export function projectMaterial(value: unknown, format: MaterialFormat = DEFAULT_MATERIAL_FORMAT): unknown {
+  if (!['raw','hybrid','text'].includes(format)) throw Error('invalid-material-format');
+  if (format === 'raw') return value;
+  const visit = (v: unknown): unknown => Array.isArray(v) ? v.map(visit) : obj(v)
+    ? Object.fromEntries(Object.entries(v).map(([k,x]) => [k,k === 'material' ? formattedMaterial(x,format) : visit(x)])) : v;
+  return visit(value);
+}