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

package/src/chess-reasoning/fact-observation-provider.ts

@@ -0,0 +1,134 @@
+import {
+  CHESS_FACT_REQUEST_VERSION,
+  chessFactRecordLicenses,
+  factProofStrength,
+  type ChessFactProvider,
+  type ChessFactRequest,
+} from "./fact-provider";
+import {
+  REASONING_POC_VERSION,
+  reasoningContextHash,
+  type ObservationProvider,
+  type ReasoningEvidenceRecord,
+  type ReasoningObservation,
+  type ReasoningObservationSet,
+  type ReasoningPositionContext,
+  type ReasoningRunControls,
+} from "./poc-contracts";
+import { stableHash } from "./stable";
+import type { SemanticValue } from "./types";
+
+export const FACT_OBSERVATION_ADAPTER_VERSION = "chess-fact-observation-adapter/1" as const;
+
+export type ChessFactObservationProviderOptions = {
+  maxRecords?: number;
+  maxBytes?: number;
+};
+
+function providerTrust(authority: import("./fact-provider").ChessFactAuthority): "deterministic" | "learned" | "external" {
+  if (authority === "bounded-engine") return "external";
+  return "deterministic";
+}
+
+export class ChessFactObservationProvider implements ObservationProvider {
+  readonly id: string;
+  readonly version: string;
+
+  constructor(
+    private readonly provider: ChessFactProvider,
+    private readonly options: ChessFactObservationProviderOptions = {},
+  ) {
+    this.id = `knights-eye/fact-observation:${provider.id}`;
+    this.version = stableHash({ adapter: FACT_OBSERVATION_ADAPTER_VERSION, provider: provider.id, version: provider.version });
+  }
+
+  async observe(context: ReasoningPositionContext, controls: ReasoningRunControls, signal?: AbortSignal): Promise<ReasoningObservationSet> {
+    const contextHash = reasoningContextHash(context);
+    const request: ChessFactRequest = {
+      schemaVersion: CHESS_FACT_REQUEST_VERSION,
+      requestId: `reasoning-facts:${stableHash({ contextHash, provider: this.provider.id, version: this.provider.version })}`,
+      context,
+      requestedKinds: [],
+      budgets: {
+        maxRecords: Math.max(1, Math.min(controls.maxObservationRecords, this.options.maxRecords ?? controls.maxObservationRecords)),
+        maxBytes: Math.max(1_024, Math.min(controls.maxProviderOutputChars, this.options.maxBytes ?? controls.maxProviderOutputChars)),
+        maxWallTimeMs: Math.max(1, Math.min(300_000, controls.maxWallTimeMs)),
+      },
+    };
+    const result = await this.provider.collect(request, signal);
+    if (result.contextHash !== contextHash) throw new Error("Chess fact provider returned stale context");
+    const observations: ReasoningObservation[] = [];
+    const evidence: ReasoningEvidenceRecord[] = [];
+    for (const record of result.records) {
+      const evidenceId = `evidence:${record.id}`;
+      evidence.push({
+        schemaVersion: REASONING_POC_VERSION,
+        id: evidenceId,
+        contextHash,
+        kind: "fact",
+        source: `${record.provenance.provider}@${record.provenance.version}`,
+        proofStrength: factProofStrength(record.authority, record.coverage),
+        licenses: chessFactRecordLicenses(record),
+        summary: record.summary,
+        data: {
+          factId: record.id,
+          kind: record.kind,
+          phase: record.phase,
+          authority: record.authority,
+          participants: record.participants as unknown as SemanticValue,
+          data: record.data,
+          coverage: record.coverage as unknown as SemanticValue,
+          provenance: record.provenance as unknown as SemanticValue,
+        },
+        coverage: {
+          complete: record.coverage.exhaustive && record.coverage.unresolved.length === 0,
+          covered: [...record.coverage.covered],
+          unresolved: [...record.coverage.unresolved],
+        },
+        replay: record.replay,
+      });
+      observations.push({
+        schemaVersion: REASONING_POC_VERSION,
+        id: `observation:${record.id}`,
+        contextHash,
+        observationType: `chess-fact:${record.kind}`,
+        participants: record.participants.map((participant) => ({ ...participant, ref: { ...participant.ref } })),
+        attributes: {
+          factId: record.id,
+          factKind: record.kind,
+          phase: record.phase,
+          authority: record.authority,
+          data: record.data,
+          coverage: record.coverage as unknown as SemanticValue,
+        },
+        exactness: record.authority === "heuristic-affordance" ? "heuristic" : "exact",
+        provenance: {
+          provider: record.provenance.provider,
+          version: record.provenance.version,
+          trust: providerTrust(record.authority),
+          methods: [record.provenance.method, FACT_OBSERVATION_ADAPTER_VERSION],
+        },
+        factEvidenceIds: [evidenceId],
+        probeRecipes: [],
+      });
+    }
+    const capabilities = result.capabilities.map((capability) => capability.kind).sort();
+    return {
+      schemaVersion: REASONING_POC_VERSION,
+      contextHash,
+      observations,
+      evidence,
+      providers: [
+        { provider: this.id, version: this.version },
+        { provider: this.provider.id, version: this.provider.version },
+      ],
+      limitations: [
+        ...result.limitations,
+        `Chess fact capabilities advertised for model-directed expansion: ${capabilities.join(", ") || "none"}.`,
+        ...(result.omitted.length ? [`${result.omitted.length} fact record(s) were explicitly omitted by request or budget.`] : []),
+        ...(result.unavailableKinds.length ? [`Unavailable fact kinds: ${result.unavailableKinds.map((item) => item.kind).join(", ")}.`] : []),
+        "The adapter preserves fact authority and does not create semantic concepts, plans, roles, or classifications.",
+      ],
+    };
+  }
+}

package/src/chess-reasoning/fact-provider.ts

@@ -0,0 +1,250 @@
+import type { ReasoningPositionContext } from "./poc-contracts";
+import { effectiveEvidenceLicenses, validateEvidenceLicenseClaims, type EvidenceLicense } from "./evidence-licenses";
+import type { ProofStrength, SemanticParticipant, SemanticValue } from "./types";
+
+export const CHESS_FACT_SCHEMA_VERSION = "chess-facts/1" as const;
+export const CHESS_FACT_REQUEST_VERSION = "chess-fact-request/1" as const;
+export const CHESS_FACT_RESULT_VERSION = "chess-fact-result/1" as const;
+
+export type ChessFactAuthority =
+  | "legal-exact"
+  | "deterministic-derived"
+  | "heuristic-affordance"
+  | "bounded-engine";
+
+const PROOF_RANK: Readonly<Record<ProofStrength, number>> = Object.freeze({
+  observed: 1,
+  supported: 2,
+  forced: 3,
+});
+
+export type ChessFactPhase = "before" | "after" | "transition" | "path";
+
+export type ChessFactCoverage = {
+  domain: string;
+  exhaustive: boolean;
+  covered: string[];
+  unresolved: string[];
+};
+
+export type ChessFactEngineProvenance = {
+  name: string;
+  build: string;
+  network: string | null;
+  depth: number;
+  threads: 1;
+  multiPv: number;
+  rootMoves: string[];
+};
+
+export type ChessFactRecord = {
+  schemaVersion: typeof CHESS_FACT_SCHEMA_VERSION;
+  id: string;
+  contextHash: string;
+  kind: string;
+  phase: ChessFactPhase;
+  authority: ChessFactAuthority;
+  licenses?: EvidenceLicense[];
+  summary: string;
+  participants: SemanticParticipant[];
+  data: Record<string, SemanticValue>;
+  coverage: ChessFactCoverage;
+  provenance: {
+    provider: string;
+    version: string;
+    method: string;
+    derivedFromIds: string[];
+    engine?: ChessFactEngineProvenance;
+  };
+  replay: Record<string, SemanticValue> | null;
+};
+
+export type ChessFactCapability = {
+  kind: string;
+  phases: ChessFactPhase[];
+  authorities: ChessFactAuthority[];
+  coverageDomains: string[];
+  expandable: boolean;
+  limitations: string[];
+};
+
+export type ChessFactRequest = {
+  schemaVersion: typeof CHESS_FACT_REQUEST_VERSION;
+  requestId: string;
+  context: ReasoningPositionContext;
+  requestedKinds: string[];
+  budgets: {
+    maxRecords: number;
+    maxBytes: number;
+    maxWallTimeMs: number;
+  };
+  engineLimits?: {
+    depth: number;
+    threads: 1;
+    multiPv: number;
+    rootMoves: string[];
+  };
+};
+
+export type ChessFactOmission = {
+  kind: string;
+  reason: "budget" | "not-requested";
+  recordId: string | null;
+};
+
+export type ChessFactResult = {
+  schemaVersion: typeof CHESS_FACT_RESULT_VERSION;
+  contextHash: string;
+  records: ChessFactRecord[];
+  capabilities: ChessFactCapability[];
+  omitted: ChessFactOmission[];
+  unavailableKinds: Array<{ kind: string; reason: string }>;
+  limitations: string[];
+};
+
+export interface ChessFactProvider {
+  readonly id: string;
+  readonly version: string;
+  capabilities(): readonly ChessFactCapability[];
+  collect(request: ChessFactRequest, signal?: AbortSignal): Promise<ChessFactResult> | ChessFactResult;
+}
+
+const MECHANICAL_KIND = /^[a-z][a-z0-9]*(?:[._-][a-z0-9]+)+$/;
+const INTERPRETIVE_KIND_TOKEN = /(?:^|[._-])(plan|idea|purpose|brilliant|great|interesting|best|good|okay|dubious|mistake|miss|blunder|decisive|interposition|readiness)(?:$|[._-])/;
+const UCI_MOVE = /^[a-h][1-8][a-h][1-8][qrbn]?$/;
+const SQUARE = /^[a-h][1-8]$/;
+
+function validateMechanicalKind(kind: string): void {
+  if (!MECHANICAL_KIND.test(kind)) throw new Error(`Chess fact kind is not mechanical: ${kind}`);
+  if (INTERPRETIVE_KIND_TOKEN.test(kind)) throw new Error(`Chess fact kind leaks interpretation or policy: ${kind}`);
+}
+
+export function validateChessFactRequest(request: ChessFactRequest): ChessFactRequest {
+  if (request.schemaVersion !== CHESS_FACT_REQUEST_VERSION) throw new Error("Unsupported chess fact request version");
+  if (!request.requestId || request.requestId.length > 200) throw new Error("Chess fact requestId must contain 1..200 characters");
+  if (!Number.isInteger(request.budgets.maxRecords) || request.budgets.maxRecords < 1 || request.budgets.maxRecords > 512) {
+    throw new Error("Chess fact maxRecords must be an integer in 1..512");
+  }
+  if (!Number.isInteger(request.budgets.maxBytes) || request.budgets.maxBytes < 1_024 || request.budgets.maxBytes > 2_000_000) {
+    throw new Error("Chess fact maxBytes must be an integer in 1024..2000000");
+  }
+  if (!Number.isInteger(request.budgets.maxWallTimeMs) || request.budgets.maxWallTimeMs < 1 || request.budgets.maxWallTimeMs > 300_000) {
+    throw new Error("Chess fact maxWallTimeMs must be an integer in 1..300000");
+  }
+  for (const kind of request.requestedKinds) validateMechanicalKind(kind);
+  if (new Set(request.requestedKinds).size !== request.requestedKinds.length) throw new Error("Chess fact requestedKinds must be unique");
+  if (request.engineLimits) {
+    if (request.engineLimits.threads !== 1) throw new Error("Reproducible chess fact engine requests require threads=1");
+    if (!Number.isInteger(request.engineLimits.depth) || request.engineLimits.depth < 1 || request.engineLimits.depth > 64) throw new Error("Chess fact engine depth must be in 1..64");
+    if (!Number.isInteger(request.engineLimits.multiPv) || request.engineLimits.multiPv < 1 || request.engineLimits.multiPv > 16) throw new Error("Chess fact engine multiPv must be in 1..16");
+    if (request.engineLimits.rootMoves.some((move) => !UCI_MOVE.test(move))) throw new Error("Chess fact engine root moves must be UCI moves");
+  }
+  return request;
+}
+
+export function validateChessFactRecord(record: ChessFactRecord): ChessFactRecord {
+  if (record.schemaVersion !== CHESS_FACT_SCHEMA_VERSION) throw new Error("Unsupported chess fact record version");
+  if (!record.id || !record.contextHash) throw new Error("Chess fact record requires stable identity and context hash");
+  validateMechanicalKind(record.kind);
+  if (!new Set<ChessFactAuthority>(["legal-exact", "deterministic-derived", "heuristic-affordance", "bounded-engine"]).has(record.authority)) throw new Error("Unsupported chess fact authority");
+  if (!new Set<ChessFactPhase>(["before", "after", "transition", "path"]).has(record.phase)) throw new Error("Unsupported chess fact phase");
+  if (!record.summary.trim() || record.summary.length > 1_000) throw new Error("Chess fact summary must contain 1..1000 characters");
+  if (!record.coverage.domain) throw new Error("Chess fact coverage domain is required");
+  if (!record.coverage.exhaustive && record.coverage.unresolved.length === 0) throw new Error("Non-exhaustive chess fact coverage must state unresolved domain members");
+  if (record.coverage.covered.some((item) => !item) || record.coverage.unresolved.some((item) => !item)) throw new Error("Chess fact coverage entries must be nonempty");
+  if (!record.provenance.provider || !record.provenance.version || !record.provenance.method) throw new Error("Chess fact provenance is incomplete");
+  if (new Set(record.provenance.derivedFromIds).size !== record.provenance.derivedFromIds.length) throw new Error("Chess fact derivedFromIds must be unique");
+  if (Object.keys(record).some((key) => /^is[A-Z]/.test(key))) throw new Error("Chess fact records cannot add concept-specific boolean flags");
+  const licenseInput = {
+    kind: "fact",
+    source: `${record.provenance.provider}/${record.provenance.method}`,
+    authority: record.authority,
+    proofStrength: factProofStrength(record.authority, record.coverage),
+    data: { ...record.data, authority: record.authority, phase: record.phase, factKind: record.kind },
+    coverage: { complete: record.coverage.exhaustive, covered: record.coverage.covered, unresolved: record.coverage.unresolved },
+    replay: record.replay,
+  };
+  if (record.licenses !== undefined) validateEvidenceLicenseClaims(licenseInput, record.licenses);
+  if (record.authority === "bounded-engine") {
+    const engine = record.provenance.engine;
+    if (!engine) throw new Error("Bounded-engine fact requires engine provenance");
+    if (engine.threads !== 1) throw new Error("Bounded-engine fact provenance requires threads=1");
+    if (!Number.isInteger(engine.depth) || engine.depth < 1 || engine.depth > 64) throw new Error("Bounded-engine fact provenance requires fixed depth");
+    if (!Number.isInteger(engine.multiPv) || engine.multiPv < 1 || engine.multiPv > 16) throw new Error("Bounded-engine fact provenance requires bounded MultiPV");
+    if (!engine.name || !engine.build) throw new Error("Bounded-engine fact provenance requires engine name and build");
+    if (engine.rootMoves.some((move) => !UCI_MOVE.test(move))) throw new Error("Bounded-engine root moves must be UCI moves");
+  } else if (record.provenance.engine) {
+    throw new Error("Only bounded-engine facts may carry engine provenance");
+  }
+  const pieceIds = new Set(record.participants.filter((item) => item.ref.domain === "piece").map((item) => item.ref.id));
+  if (pieceIds.size) {
+    const locations = Array.isArray(record.data.pieceLocations) ? record.data.pieceLocations : [];
+    const located = new Set(locations.flatMap((value) => {
+      if (!value || typeof value !== "object" || Array.isArray(value)) return [];
+      const pieceId = (value as Record<string, SemanticValue>).pieceId;
+      const currentSquare = (value as Record<string, SemanticValue>).currentSquare;
+      return typeof pieceId === "string" && typeof currentSquare === "string" && SQUARE.test(currentSquare) ? [pieceId] : [];
+    }));
+    for (const pieceId of pieceIds) if (!located.has(pieceId)) throw new Error(`Piece participant lacks currentSquare data: ${pieceId}`);
+  }
+  return record;
+}
+
+export function chessFactRecordLicenses(record: ChessFactRecord): EvidenceLicense[] {
+  return effectiveEvidenceLicenses({
+    kind: "fact",
+    source: `${record.provenance.provider}/${record.provenance.method}`,
+    authority: record.authority,
+    proofStrength: factProofStrength(record.authority, record.coverage),
+    data: { ...record.data, authority: record.authority, phase: record.phase, factKind: record.kind },
+    coverage: { complete: record.coverage.exhaustive, covered: record.coverage.covered, unresolved: record.coverage.unresolved },
+    replay: record.replay,
+    licenses: record.licenses,
+  });
+}
+
+/**
+ * Central authority-to-proof policy for every fact-provider boundary.
+ *
+ * `forced` is intentionally absent: fact records cannot establish it. Forced
+ * proof belongs to the rules-complete probe/coverage validators.
+ */
+export function maximumFactProofStrength(
+  authority: ChessFactAuthority,
+  coverage?: Pick<ChessFactCoverage, "exhaustive" | "unresolved"> | null,
+): ProofStrength | null {
+  if (authority === "heuristic-affordance") return null;
+  if (authority === "legal-exact" || authority === "deterministic-derived") return "observed";
+  return coverage?.exhaustive && coverage.unresolved.length === 0 ? "supported" : "observed";
+}
+
+export function factProofStrength(
+  authority: ChessFactAuthority,
+  coverage?: Pick<ChessFactCoverage, "exhaustive" | "unresolved"> | null,
+): ProofStrength | null {
+  return maximumFactProofStrength(authority, coverage);
+}
+
+export function assertFactProofWithinAuthority(input: {
+  authority: ChessFactAuthority;
+  proofStrength: ProofStrength | null;
+  coverage?: Pick<ChessFactCoverage, "exhaustive" | "unresolved"> | null;
+  label?: string;
+}): void {
+  const maximum = maximumFactProofStrength(input.authority, input.coverage);
+  if (input.proofStrength === null) return;
+  if (maximum === null || PROOF_RANK[input.proofStrength] > PROOF_RANK[maximum]) {
+    throw new Error(`${input.label || "Fact evidence"} overstates ${input.authority} authority as ${input.proofStrength}`);
+  }
+}
+
+export function isChessFactAuthority(value: unknown): value is ChessFactAuthority {
+  return value === "legal-exact"
+    || value === "deterministic-derived"
+    || value === "heuristic-affordance"
+    || value === "bounded-engine";
+}
+
+export function factCoverageSupportsAbsence(record: ChessFactRecord, domain: string): boolean {
+  return record.coverage.domain === domain && record.coverage.exhaustive && record.coverage.unresolved.length === 0;
+}

package/src/chess-reasoning/fresh-engine-pv-witnesses.ts

@@ -0,0 +1,128 @@
+import { Chess } from 'chess.js';
+import type { PositionAnalysisLine } from './position-analysis-contracts';
+import { reasoningContextHash, type ReasoningPositionContext } from './poc-contracts';
+
+/** Host-only input, created from this answer's acquired engine results, never a saved snapshot. */
+export type FreshEnginePvWitness = {
+  version: 'fresh-engine-pv-witness/1'; acquisition: 'same-answer-engine'; acquisitionId: number;
+  evidenceId: string; contextHash: string; phase: 'before' | 'after'; fen: string;
+  engineBuild: string; command: string; requestedDepth: number; multiPv: number; rootMoves: string[];
+  authority: 'bounded-engine'; licenses: ['engine.bounded-continuation'];
+  lines: Pick<PositionAnalysisLine, 'rootMove' | 'pv' | 'depth' | 'scoreProvenance' | 'scoreCp' | 'mateInMoves'>[];
+};
+
+export type FreshEnginePvReferenceEvidence = {
+  acquisitionId: number; evidenceId: string; rootFen: string; rootMove: string;
+  depth: number; requestedDepth: number; engineBuild: string; command: string;
+  scoreCp: number | null; mateInMoves: number | null;
+  scoreProvenance: NonNullable<PositionAnalysisLine['scoreProvenance']>;
+  conditional: true;
+  scoreInterpretation: 'Root-search score only; the continuation is conditional, not forced and not a score for a later position.';
+};
+
+export type FreshEnginePvReferenceLine = {
+  start: 'before' | 'after'; ucis: string[]; evidenceIds: string[]; authority: string;
+  engineEvidence: FreshEnginePvReferenceEvidence[];
+};
+
+export const MAX_FRESH_ENGINE_WITNESS_ACQUISITIONS = 64;
+export type FreshEnginePvRejectionReason =
+  | 'invalid-acquisition' | 'missing-authority-license' | 'context-mismatch' | 'root-mismatch'
+  | 'invalid-search-scope' | 'root-set-mismatch' | 'depth-mismatch' | 'provenance-mismatch'
+  | 'score-mismatch' | 'invalid-pv' | 'illegal-pv' | 'audit-capacity-exceeded';
+export type FreshEnginePvAdmissionAudit = {
+  version: 'fresh-engine-pv-admission/1'; inputAcquisitions: number; inspectedAcquisitions: number;
+  acceptedAcquisitions: number; rejectedAcquisitions: number; acceptedLines: number; omittedAcquisitions: number;
+  acceptedAcquisitionIds: number[]; rejectedAcquisitionIds: (number | null)[];
+  rejections: { acquisitionId: number | null; reason: FreshEnginePvRejectionReason }[];
+  rejectionCounts: Partial<Record<FreshEnginePvRejectionReason, number>>;
+};
+
+const UCI = /^[a-h][1-8][a-h][1-8][qrbn]?$/;
+const positiveInteger = (value: unknown): value is number => Number.isSafeInteger(value) && Number(value) > 0;
+
+function rejectionReason(context: ReasoningPositionContext, hash: string, witness: FreshEnginePvWitness): FreshEnginePvRejectionReason | null {
+  if (!witness || witness.version !== 'fresh-engine-pv-witness/1' || witness.acquisition !== 'same-answer-engine'
+    || !positiveInteger(witness.acquisitionId) || typeof witness.evidenceId !== 'string' || !witness.evidenceId
+    || witness.evidenceId.length > 200) return 'invalid-acquisition';
+  if (witness.authority !== 'bounded-engine' || !Array.isArray(witness.licenses)
+    || witness.licenses.length !== 1 || witness.licenses[0] !== 'engine.bounded-continuation') return 'missing-authority-license';
+  if (witness.contextHash !== hash) return 'context-mismatch';
+  if (!['before', 'after'].includes(witness.phase)
+    || witness.fen !== (witness.phase === 'before' ? context.fenBefore : context.fenAfter)) return 'root-mismatch';
+  if (typeof witness.engineBuild !== 'string' || !witness.engineBuild || typeof witness.command !== 'string' || !witness.command
+    || !positiveInteger(witness.requestedDepth) || !positiveInteger(witness.multiPv) || witness.multiPv > 32
+    || !Array.isArray(witness.lines) || witness.lines.length !== witness.multiPv
+    || !Array.isArray(witness.rootMoves) || witness.rootMoves.length > 32
+    || witness.rootMoves.some(root => typeof root !== 'string' || !UCI.test(root))
+    || new Set(witness.rootMoves).size !== witness.rootMoves.length) return 'invalid-search-scope';
+  if (witness.lines.some(line => !line || typeof line.rootMove !== 'string')) return 'invalid-pv';
+  const roots = witness.lines.map(line => line.rootMove);
+  if (new Set(roots).size !== roots.length || witness.rootMoves.some(root => !roots.includes(root))
+    || (witness.rootMoves.length > 0 && roots.some(root => !witness.rootMoves.includes(root)))) return 'root-set-mismatch';
+  // The acquisition is atomic: a malformed sibling or full tail rejects every line.
+  for (const line of witness.lines) {
+    if (!positiveInteger(line.depth) || line.depth < witness.requestedDepth) return 'depth-mismatch';
+    const provenance = line.scoreProvenance;
+    if (!provenance || provenance.kind !== 'root-search' || provenance.fen !== witness.fen
+      || provenance.engineBuild !== witness.engineBuild
+      || (provenance.command !== undefined && provenance.command !== witness.command)
+      || provenance.originatingDepth !== line.depth || provenance.reportedDepth !== line.depth) return 'provenance-mismatch';
+    if (!((Number.isFinite(line.scoreCp) && line.mateInMoves === null)
+      || (line.scoreCp === null && Number.isSafeInteger(line.mateInMoves) && line.mateInMoves !== 0))) return 'score-mismatch';
+    if (!Array.isArray(line.pv) || !line.pv.length || line.pv.length > 256
+      || line.pv.some(uci => typeof uci !== 'string' || !UCI.test(uci)) || line.pv[0] !== line.rootMove) return 'invalid-pv';
+    try {
+      const board = new Chess(witness.fen);
+      for (const uci of line.pv) board.move({ from: uci.slice(0, 2), to: uci.slice(2, 4), promotion: uci.slice(4) || undefined });
+    } catch { return 'illegal-pv'; }
+    try { structuredClone(provenance); } catch { return 'provenance-mismatch'; }
+  }
+  return null;
+}
+
+/** Bounded, safe reason codes; no raw error message, board, path or private source in the audit. */
+export function admitFreshEnginePvWitnesses(context: ReasoningPositionContext, witnesses: readonly FreshEnginePvWitness[]): {
+  lines: FreshEnginePvReferenceLine[]; audit: FreshEnginePvAdmissionAudit;
+} {
+  const lines: FreshEnginePvReferenceLine[] = [];
+  const inspected = witnesses.slice(0, MAX_FRESH_ENGINE_WITNESS_ACQUISITIONS);
+  const audit: FreshEnginePvAdmissionAudit = {
+    version: 'fresh-engine-pv-admission/1', inputAcquisitions: witnesses.length, inspectedAcquisitions: inspected.length,
+    acceptedAcquisitions: 0, rejectedAcquisitions: 0, acceptedLines: 0,
+    omittedAcquisitions: witnesses.length - inspected.length, acceptedAcquisitionIds: [], rejectedAcquisitionIds: [],
+    rejections: [], rejectionCounts: {},
+  };
+  const hash = reasoningContextHash(context);
+  for (const witness of inspected) {
+    const reason = rejectionReason(context, hash, witness);
+    if (reason) {
+      const acquisitionId = positiveInteger(witness?.acquisitionId) ? witness.acquisitionId : null;
+      audit.rejections.push({ acquisitionId, reason });
+      audit.rejectedAcquisitionIds.push(acquisitionId);
+      audit.rejectionCounts[reason] = (audit.rejectionCounts[reason] ?? 0) + 1;
+      continue;
+    }
+    audit.acceptedAcquisitionIds.push(witness.acquisitionId);
+    for (const line of witness.lines) {
+      lines.push({ start: context.kind === 'position' ? 'after' : witness.phase, ucis: [...line.pv],
+        evidenceIds: [witness.evidenceId], authority: 'Bounded engine line', engineEvidence: [{
+          acquisitionId: witness.acquisitionId, evidenceId: witness.evidenceId, rootFen: witness.fen,
+          rootMove: line.rootMove, depth: line.depth, requestedDepth: witness.requestedDepth,
+          engineBuild: witness.engineBuild, command: witness.command,
+          scoreCp: line.scoreCp, mateInMoves: line.mateInMoves, scoreProvenance: structuredClone(line.scoreProvenance!),
+          conditional: true, scoreInterpretation: 'Root-search score only; the continuation is conditional, not forced and not a score for a later position.',
+        }] });
+    }
+  }
+  if (audit.omittedAcquisitions) audit.rejectionCounts['audit-capacity-exceeded'] = audit.omittedAcquisitions;
+  audit.acceptedAcquisitions = audit.acceptedAcquisitionIds.length;
+  audit.rejectedAcquisitions = audit.rejections.length + audit.omittedAcquisitions;
+  audit.acceptedLines = lines.length;
+  return { lines, audit };
+}
+
+/** Presentation witness admission. Scores retain their original root scope, without entailment claims. */
+export function freshEnginePvReferenceLines(context: ReasoningPositionContext, witnesses: readonly FreshEnginePvWitness[]): FreshEnginePvReferenceLine[] {
+  return admitFreshEnginePvWitnesses(context, witnesses).lines;
+}

package/src/chess-reasoning/historical-prose.ts

@@ -0,0 +1,116 @@
+import { effectiveLicensesForRecord } from './evidence-licenses';
+import { Chess } from 'chess.js';
+import { historyPositionContext, recordedEvidenceContext, recordedDetailsMatch } from './recorded-reference-context';
+import { reasoningContextHash, type ReasoningPositionContext, type ReasoningEvidenceRecord } from './poc-contracts';
+export type RecordedReferenceLine = {startFen:string; moves:readonly {uci:string;san:string}[]};
+
+type Root = {context:ReasoningPositionContext; records:ReasoningEvidenceRecord[]};
+/** Exact frozen witnesses for game:<recorded ply>:<local UCI path> links. */
+export function historicalProseRoots(selected:ReasoningPositionContext, records:readonly ReasoningEvidenceRecord[], line?:RecordedReferenceLine) {
+  const roots = new Map<number,Root>();
+  const paths: Array<{ply:number;path:string[];sans:string[];numbers:string[]}> = [];
+  const addPath = (ply:number,context:ReasoningPositionContext,path:string[]) => {
+    if (!path.length || path.length > 256) return;
+    const board = new Chess(context.fenAfter), sans:string[]=[], numbers:string[]=[];
+    try { for (const uci of path) {
+      const f=board.fen().split(' '); numbers.push(`${f[5]}${f[1]==='w'?'.':'...'}`);
+      sans.push(board.move({from:uci.slice(0,2),to:uci.slice(2,4),promotion:uci[4]}).san);
+    } paths.push({ply,path,sans,numbers}); } catch { /* Invalid whole path is not evidence. */ }
+  };
+  let recorded:string[]|undefined;
+  const recordedNumbers:string[]=[];
+  if (line && line.startFen === (selected.historyStartFen ?? new Chess().fen()) && line.moves.length <= 512) {
+    try {
+      const board = new Chess(line.startFen);
+      recorded=line.moves.map(m=>m.uci);
+      let before=board.fen();
+      for(let ply=0;ply<recorded.length;ply++) {
+        const f=board.fen().split(' '); recordedNumbers.push(`${f[5]}${f[1]==='w'?'.':'...'}`);
+        const context:ReasoningPositionContext=ply===0 ? historyPositionContext(line.startFen,[]) : {
+          nodeId:'recorded-reference',historyStartFen:line.startFen,historyUci:recorded.slice(0,ply-1),
+          fenBefore:before,fenAfter:board.fen(),moveUci:recorded[ply-1],moveSan:line.moves[ply-1].san};
+        roots.set(ply,{context,records:[]});
+        before=board.fen();
+        const uci=recorded[ply];
+        if(board.move({from:uci.slice(0,2),to:uci.slice(2,4),promotion:uci[4]}).san!==line.moves[ply].san)throw Error('Invalid recorded SAN');
+      }
+    } catch { recorded=undefined; roots.clear(); paths.length=0; }
+  }
+  for (const e of records) {
+    if (e.contextHash !== reasoningContextHash(selected) || !e.data.recordedPosition) continue;
+    try {
+      const p=e.data.recordedPosition as {ply:number;historyUci:string[]};
+      const context=recordedEvidenceContext(selected,p);
+      if (recorded && p.historyUci.some((uci,i)=>recorded![i]!==uci)) continue;
+      const root=roots.get(p.ply) ?? {context,records:[]};
+      if(root.context.fenAfter!==context.fenAfter || JSON.stringify(root.context.historyUci)!==JSON.stringify(context.historyUci))continue;
+      effectiveLicensesForRecord(e);
+      const data=e.data.details as ReasoningEvidenceRecord['data'];
+      if(!recordedDetailsMatch(context,data))continue;
+      const unwrapped={...e,contextHash:reasoningContextHash(root.context),data};
+      root.records.push(unwrapped); roots.set(p.ply,root);
+      if(Array.isArray(data.lines))for(const candidate of data.lines) {
+        const prefix=Array.isArray(data.played)?data.played.map(m=>(m as {uci:string}).uci):[];
+        const pv=(candidate as {pv?:string[]})?.pv;
+        if(Array.isArray(pv))addPath(p.ply,context,[...prefix,...pv]);
+      }
+      if(Array.isArray(data.played))addPath(p.ply,context,data.played.map(m=>(m as {uci:string}).uci));
+    } catch { /* Malformed scope never becomes a link. */ }
+  }
+  // Only numbered notation starts a procedural match. Unnumbered/square prose
+  // is never guessed. A complete contiguous sequence must have one exact path.
+  const san='(?:O-O(?:-O)?|[KQRBN](?:[a-h1-8])?x?[a-h][1-8]|[a-h](?:x[a-h])?[1-8](?:=[QRBN])?)[+#]?[!?]*';
+  const sequence=new RegExp(`(?<![\\w])\\d+\\s*(?:\\.{3}|\\.|…)\\s*${san}(?:\\s+(?:\\d+\\s*(?:\\.{3}|\\.|…)\\s*)?${san})*`,'g');
+  const token=new RegExp(`(?:(\\d+)\\s*(\\.{3}|\\.|…)\\s*)?(${san})`,'g');
+  const annotate=(text:string)=>text.replace(sequence,(match,offset)=>{
+    // Leave authored Markdown links untouched.
+    const left=text.slice(0,offset), right=text.slice(offset+match.length);
+    if(left.lastIndexOf('[')>left.lastIndexOf(']') || /^\]\(/.test(right))return match;
+    const moves=[...match.matchAll(token)];
+    const candidates=new Map<string,{ply:number;path:string[]}>();
+    for(const witness of paths) for(let from=0;from<witness.path.length;from++) {
+      if(from+moves.length>witness.path.length)continue;
+      if(!moves.every((m,i)=>m[3].replace(/[!?]/g,'')===witness.sans[from+i]
+        && (!m[1] || `${Number(m[1])}${m[2]==='.'?'.':'...'}`===witness.numbers[from+i])))continue;
+      const path=witness.path.slice(0,from+moves.length),root=roots.get(witness.ply)!;
+      const history=[...root.context.historyUci,...(root.context.kind==='position'?[]:[root.context.moveUci]),...path];
+      candidates.set(history.join(','),{ply:witness.ply,path});
+    }
+    // Consecutive recorded moves may span the one-move witnesses above.
+    if(recorded)for(let ply=0;ply<recorded.length;ply++) {
+      const root=roots.get(ply);if(!root || ply+moves.length>recorded.length)continue;
+      const path=recorded.slice(ply,ply+moves.length);
+      if(moves.every((m,i)=>m[3].replace(/[!?]/g,'')===line!.moves[ply+i].san && (!m[1]||`${Number(m[1])}${m[2]==='.'?'.':'...'}`===recordedNumbers[ply+i])))candidates.set(recorded.slice(0,ply+moves.length).join(','),{ply,path});
+    }
+    if(candidates.size!==1)return match;
+    const c=[...candidates.values()][0];
+    return `[${match}](game:${c.ply}:${c.path.join(',')})`;
+  });
+  const witnessedSuffixes=(ply:number,path:string[]) => {
+    const target=roots.get(ply);
+    if(!recorded || !target || !path.length) return [];
+    const suffixes: Array<{root:Root;path:string[]}> = [];
+    const seen=new Set<string>();
+    for(const witness of paths) {
+      if(witness.ply>=ply)continue;
+      const omitted=recorded.slice(witness.ply,ply);
+      if(omitted.length!==ply-witness.ply || witness.path.length<omitted.length+path.length
+        || !omitted.every((uci,i)=>witness.path[i]===uci)
+        || !path.every((uci,i)=>witness.path[omitted.length+i]===uci))continue;
+      const root=roots.get(witness.ply);
+      if(!root?.records.length)continue;
+      // The ordered record, not a repeated FEN elsewhere in the game, fixes
+      // the omitted prefix and the later root. A source line only proposes a
+      // candidate; the caller must still admit its complete evidence witness.
+      const board=new Chess(root.context.fenAfter);
+      try {
+        for(const uci of omitted)board.move({from:uci.slice(0,2),to:uci.slice(2,4),promotion:uci[4]});
+        if(board.fen()!==target.context.fenAfter)continue;
+      } catch {continue;}
+      const fullPath=[...omitted,...path],key=`${witness.ply}:${fullPath.join(',')}`;
+      if(!seen.has(key)){seen.add(key);suffixes.push({root,path:fullPath});}
+    }
+    return suffixes.sort((a,b)=>a.path.length-b.path.length);
+  };
+  return {roots,annotate,recorded,witnessedSuffixes};
+}