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

package/dist/types/chess-reasoning/existing-analysis-context.d.ts

@@ -0,0 +1,104 @@
+import { type EvidenceLicense } from "./evidence-licenses.js";
+import { type ChessFactAuthority } from "./fact-provider.js";
+import { type ObservationProvider, type ReasoningObservationSet, type ReasoningPositionContext, type ReasoningRunControls } from "./poc-contracts.js";
+import type { SemanticValue } from "./types.js";
+export declare const EXISTING_ANALYSIS_CONTEXT_VERSION: "existing-analysis-context/2";
+export declare const LEGACY_EXISTING_ANALYSIS_CONTEXT_VERSION: "existing-analysis-context/1";
+export declare const CANONICAL_EDGE_ANALYSIS_SNAPSHOT_VERSION: "canonical-edge-analysis-snapshot/1";
+export declare const EXISTING_ANALYSIS_RECORD_VERSION: "existing-analysis-record/1";
+export declare const MATERIAL_OFFER_SET_VERSION: "classifier-material-offer-set/1";
+export declare const EXISTING_ANALYSIS_OBSERVATION_PROVIDER_ID: "knights-eye/existing-analysis-context";
+/**
+ * Development/evaluation views over one identical canonical context snapshot.
+ * These are ablation controls, not user-query kinds or alternative providers.
+ */
+export declare const EXISTING_ANALYSIS_CONTEXT_MODE: Readonly<{
+    readonly HIDDEN: "hidden";
+    readonly LABEL_ONLY: "label-only";
+    readonly DIAGNOSTICS_ONLY: "diagnostics-only";
+    readonly FULL: "full";
+}>;
+export type ExistingAnalysisContextMode = typeof EXISTING_ANALYSIS_CONTEXT_MODE[keyof typeof EXISTING_ANALYSIS_CONTEXT_MODE];
+export declare const ANALYSIS_CONTEXT_PROVENANCE_TIER: Readonly<{
+    readonly RAW_ANALYSIS: "raw-analysis";
+    readonly LEGACY_HEURISTIC: "legacy-heuristic-diagnostic";
+    readonly REVIEWED_SEMANTIC: "reviewed-semantic-state";
+    readonly POLICY_LABEL: "policy-derived-label";
+}>;
+export type AnalysisContextProvenanceTier = typeof ANALYSIS_CONTEXT_PROVENANCE_TIER[keyof typeof ANALYSIS_CONTEXT_PROVENANCE_TIER];
+export type MaterialOfferCandidateSummary = {
+    captureUci: string;
+    offeredSquare: string;
+    offeredPiece: string;
+    nominalOffer: number;
+    voluntaryOfferCap: number;
+    bestImmediateRecoveryNet: number;
+    qualifying: boolean;
+    acceptanceLine: string[];
+    persistent: boolean | null;
+    conversionGain: number | null;
+};
+export type MaterialOfferSet = {
+    version: typeof MATERIAL_OFFER_SET_VERSION;
+    status: "complete" | "unavailable";
+    offers: MaterialOfferCandidateSummary[] | null;
+    screenedCandidates: MaterialOfferCandidateSummary[];
+    classifierVersion: number;
+    detector: "classifier-sacrifice-offer-tracker";
+    policy: string;
+    horizon: {
+        verificationDepth: number | null;
+        materialWindowPlies: number | null;
+        principalVariationPlies: number;
+    };
+    limitations: string[];
+};
+export type ExistingAnalysisRecord = {
+    version: typeof EXISTING_ANALYSIS_RECORD_VERSION;
+    id: string;
+    kind: string;
+    scope: "selected-edge" | "path-window";
+    authority: ChessFactAuthority;
+    licenses: EvidenceLicense[];
+    summary: string;
+    data: Record<string, SemanticValue>;
+    coverage: {
+        complete: boolean;
+        covered: string[];
+        unresolved: string[];
+    };
+    provenance: {
+        tier: AnalysisContextProvenanceTier;
+        provider: string;
+        version: string;
+        derivedFromIds: string[];
+    };
+    replay: Record<string, SemanticValue> | null;
+    limitations: string[];
+};
+export type ExistingAnalysisContext = {
+    version: typeof EXISTING_ANALYSIS_CONTEXT_VERSION;
+    materialOffers: MaterialOfferSet;
+    records: ExistingAnalysisRecord[];
+    coverage: {
+        complete: boolean;
+        includedKinds: string[];
+        omitted: Array<{
+            kind: string;
+            reason: "relevance" | "budget" | "unavailable";
+        }>;
+        unavailableKinds: string[];
+    };
+};
+export declare function normalizeExistingAnalysisContext(value: unknown, context: ReasoningPositionContext, options?: {
+    question?: string;
+    maxRecords?: number;
+}): ExistingAnalysisContext | null;
+export declare class ExistingAnalysisObservationProvider implements ObservationProvider {
+    private readonly existing;
+    private readonly mode;
+    readonly id: "knights-eye/existing-analysis-context";
+    readonly version: "existing-analysis-context/2";
+    constructor(existing: ExistingAnalysisContext | null, mode?: ExistingAnalysisContextMode);
+    observe(context: ReasoningPositionContext, _controls: ReasoningRunControls, signal?: AbortSignal): ReasoningObservationSet;
+}

package/dist/types/chess-reasoning/fact-observation-provider.d.ts

@@ -0,0 +1,15 @@
+import { type ChessFactProvider } from "./fact-provider.js";
+import { type ObservationProvider, type ReasoningObservationSet, type ReasoningPositionContext, type ReasoningRunControls } from "./poc-contracts.js";
+export declare const FACT_OBSERVATION_ADAPTER_VERSION: "chess-fact-observation-adapter/1";
+export type ChessFactObservationProviderOptions = {
+    maxRecords?: number;
+    maxBytes?: number;
+};
+export declare class ChessFactObservationProvider implements ObservationProvider {
+    private readonly provider;
+    private readonly options;
+    readonly id: string;
+    readonly version: string;
+    constructor(provider: ChessFactProvider, options?: ChessFactObservationProviderOptions);
+    observe(context: ReasoningPositionContext, controls: ReasoningRunControls, signal?: AbortSignal): Promise<ReasoningObservationSet>;
+}

package/dist/types/chess-reasoning/fact-provider.d.ts

@@ -0,0 +1,111 @@
+import type { ReasoningPositionContext } from "./poc-contracts.js";
+import { type EvidenceLicense } from "./evidence-licenses.js";
+import type { ProofStrength, SemanticParticipant, SemanticValue } from "./types.js";
+export declare const CHESS_FACT_SCHEMA_VERSION: "chess-facts/1";
+export declare const CHESS_FACT_REQUEST_VERSION: "chess-fact-request/1";
+export declare const CHESS_FACT_RESULT_VERSION: "chess-fact-result/1";
+export type ChessFactAuthority = "legal-exact" | "deterministic-derived" | "heuristic-affordance" | "bounded-engine";
+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;
+}
+export declare function validateChessFactRequest(request: ChessFactRequest): ChessFactRequest;
+export declare function validateChessFactRecord(record: ChessFactRecord): ChessFactRecord;
+export declare function chessFactRecordLicenses(record: ChessFactRecord): EvidenceLicense[];
+/**
+ * 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 declare function maximumFactProofStrength(authority: ChessFactAuthority, coverage?: Pick<ChessFactCoverage, "exhaustive" | "unresolved"> | null): ProofStrength | null;
+export declare function factProofStrength(authority: ChessFactAuthority, coverage?: Pick<ChessFactCoverage, "exhaustive" | "unresolved"> | null): ProofStrength | null;
+export declare function assertFactProofWithinAuthority(input: {
+    authority: ChessFactAuthority;
+    proofStrength: ProofStrength | null;
+    coverage?: Pick<ChessFactCoverage, "exhaustive" | "unresolved"> | null;
+    label?: string;
+}): void;
+export declare function isChessFactAuthority(value: unknown): value is ChessFactAuthority;
+export declare function factCoverageSupportsAbsence(record: ChessFactRecord, domain: string): boolean;

package/dist/types/chess-reasoning/fresh-engine-pv-witnesses.d.ts

@@ -0,0 +1,67 @@
+import type { PositionAnalysisLine } from './position-analysis-contracts.js';
+import { type ReasoningPositionContext } from './poc-contracts.js';
+/** 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 declare 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>>;
+};
+/** Bounded, safe reason codes; no raw error message, board, path or private source in the audit. */
+export declare function admitFreshEnginePvWitnesses(context: ReasoningPositionContext, witnesses: readonly FreshEnginePvWitness[]): {
+    lines: FreshEnginePvReferenceLine[];
+    audit: FreshEnginePvAdmissionAudit;
+};
+/** Presentation witness admission. Scores retain their original root scope, without entailment claims. */
+export declare function freshEnginePvReferenceLines(context: ReasoningPositionContext, witnesses: readonly FreshEnginePvWitness[]): FreshEnginePvReferenceLine[];

package/dist/types/chess-reasoning/historical-prose.d.ts

@@ -0,0 +1,23 @@
+import { type ReasoningPositionContext, type ReasoningEvidenceRecord } from './poc-contracts.js';
+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 declare function historicalProseRoots(selected: ReasoningPositionContext, records: readonly ReasoningEvidenceRecord[], line?: RecordedReferenceLine): {
+    roots: Map<number, Root>;
+    annotate: (text: string) => string;
+    recorded: string[] | undefined;
+    witnessedSuffixes: (ply: number, path: string[]) => {
+        root: Root;
+        path: string[];
+    }[];
+};
+export {};

package/dist/types/chess-reasoning/idea-graph.d.ts

@@ -0,0 +1,34 @@
+import { type ConceptRegistry } from "./concept-registry.js";
+import { type IdeaGraph, type IdentityState, type ProofStrength, type SemanticAttributes, type SemanticEntity, type SemanticParticipant, type SemanticRelation } from "./types.js";
+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 declare function createSemanticEntity(input: CreateSemanticEntityInput, registry?: ConceptRegistry): SemanticEntity;
+export type CreateSemanticRelationInput = {
+    id?: string;
+    branchId: string;
+    relationType: string;
+    from: string;
+    to: string;
+    createdAtPly: number;
+    attributes?: SemanticAttributes;
+    evidence?: string[];
+};
+export declare function createSemanticRelation(input: CreateSemanticRelationInput): SemanticRelation;
+export declare function createIdeaGraph(branchId?: string, ply?: number): IdeaGraph;
+export declare function extendIdeaGraph(graph: IdeaGraph, entities: SemanticEntity[], relations?: SemanticRelation[], ply?: number): IdeaGraph;
+export declare function forkIdeaGraph(graph: IdeaGraph, branchId: string): IdeaGraph;
+export declare function graphIdentityCompatible(identity: IdentityState, graph: IdeaGraph): boolean;
+export declare function isTerminalEntity(entity: SemanticEntity, registry?: ConceptRegistry): boolean;
+export declare function openEntityCount(graph: IdeaGraph, registry?: ConceptRegistry): number;

package/dist/types/chess-reasoning/initial-search-plan.d.ts

@@ -0,0 +1,37 @@
+import type { AnswerScope, ReviewSubject } from './question-routing.js';
+import type { ReasoningEvidenceRecord } from './poc-contracts.js';
+import type { RecordedMainLine } from './answer-host-contracts.js';
+import type { PlayerPerspective } from '../player-perspective.js';
+import type { ReasoningPositionContext, ReasoningToolName } from './poc-contracts.js';
+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';
+    };
+};
+/** Recognition is deliberately narrow: unresolved language stays with the answering model. */
+export declare 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;
+/** Use the same recorded-position comparison tool the model uses. Discovery may
+ * already include played+best at the same depth; otherwise compare explicitly. */
+export declare function preparedMoveComparison(request: InitialSearch, evidence: ReasoningEvidenceRecord[]): InitialSearch | undefined;

package/dist/types/chess-reasoning/lossless-evidence-sharing.d.ts

@@ -0,0 +1,18 @@
+import type { ModelMessage } from 'ai';
+export declare const EVIDENCE_SHARING_VERSION = "evidence-sharing/1";
+export declare 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.";
+export declare const EVIDENCE_SHARING_GUIDANCE_CHARS = 490;
+/** 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 declare function shareEvidence(value: unknown): unknown;
+/** 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 declare function hasSharedEvidence(value: unknown): boolean;
+/** Strict verifier; malformed/dangling/cyclic dictionaries never decode silently. */
+export declare function expandSharedEvidence(value: unknown): unknown;
+/** Serialize a copy at the model boundary, retaining native tool identity and
+ * opaque assistant/provider continuation objects without modification. */
+export declare function shareEvidenceMessages(messages: ModelMessage[]): ModelMessage[];

package/dist/types/chess-reasoning/matched-comparison.d.ts

@@ -0,0 +1,10 @@
+import type { PositionAnalysisResult } from './poc-tools.js';
+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 declare function matchedRootComparison(result: PositionAnalysisResult, fen: string, requiredRoots?: readonly string[]): MatchedComparison;
+export declare 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/dist/types/chess-reasoning/material-accounting.d.ts

@@ -0,0 +1,80 @@
+import { Chess } from 'chess.js';
+declare const pieces: {
+    readonly p: "pawn";
+    readonly n: "knight";
+    readonly b: "bishop";
+    readonly r: "rook";
+    readonly q: "queen";
+};
+type Counts = Record<typeof pieces[keyof typeof pieces], number>;
+/** Absolute counts, independent of turn, engine evaluation or starting inventory. */
+export declare function materialAtPosition(board: Chess): {
+    white: Counts;
+    black: Counts;
+    whiteMinusBlack: Counts;
+    balance: string;
+};
+/** Count by legal replay; never report a partial replay as a complete endpoint. */
+export declare function materialAlongLine(startFen: string, movesUci: readonly string[]): {
+    authority: string;
+    startFen: string;
+    plies: number;
+    start: {
+        white: Counts;
+        black: Counts;
+        whiteMinusBlack: Counts;
+        balance: string;
+    };
+    changes: {
+        ply: number;
+        san: string;
+        whiteMinusBlack: Counts;
+        balance: string;
+    }[];
+    endFen: string;
+    end: {
+        white: Counts;
+        black: Counts;
+        whiteMinusBlack: Counts;
+        balance: string;
+    };
+    balanceChangeFromStart: Counts;
+    scope: string;
+};
+export declare function materialForVariations<T extends {
+    rootMove: string;
+    pv: string[];
+}>(startFen: string, lines: readonly T[]): ((T & {
+    material: {
+        authority: string;
+        startFen: string;
+        plies: number;
+        start: {
+            white: Counts;
+            black: Counts;
+            whiteMinusBlack: Counts;
+            balance: string;
+        };
+        changes: {
+            ply: number;
+            san: string;
+            whiteMinusBlack: Counts;
+            balance: string;
+        }[];
+        endFen: string;
+        end: {
+            white: Counts;
+            black: Counts;
+            whiteMinusBlack: Counts;
+            balance: string;
+        };
+        balanceChangeFromStart: Counts;
+        scope: string;
+    };
+}) | (T & {
+    material: {
+        status: string;
+        reason: string;
+    };
+}))[];
+export {};

package/dist/types/chess-reasoning/material-format.d.ts

@@ -0,0 +1,4 @@
+/** Presentation only: the legally computed canonical material record is immutable. */
+export type MaterialFormat = 'raw' | 'hybrid' | 'text';
+export declare const DEFAULT_MATERIAL_FORMAT: MaterialFormat;
+export declare function projectMaterial(value: unknown, format?: MaterialFormat): unknown;

package/dist/types/chess-reasoning/mechanical-fact-provider.d.ts

@@ -0,0 +1,33 @@
+import { type Square } from "chess.js";
+import { type ChessFactCapability, type ChessFactProvider, type ChessFactRecord, type ChessFactRequest, type ChessFactResult } from "./fact-provider.js";
+import { type ReasoningPositionContext } from "./poc-contracts.js";
+export declare const MECHANICAL_CHESS_FACT_PROVIDER_ID: "knights-eye/mechanical-chess-facts";
+export declare const MECHANICAL_CHESS_FACT_PROVIDER_VERSION: "mechanical-chess-facts/18";
+/** A replayable immediate-capture response fact in the ordinary fact contract. */
+export type AdmittedCaptureResponseAvailabilityFact = ChessFactRecord;
+export type AdmittedCaptureResponseAvailabilityInput = {
+    /** The target-move context that owns stable identities and the record hash. */
+    context: ReasoningPositionContext;
+    /** Must be the hash of `context`; callers cannot attach a path fact elsewhere. */
+    contextHash: string;
+    /** Which exact target-context phase the supplied line starts from. */
+    start: "before" | "after";
+    /** An admitted, fully declared line whose final move must be a legal capture. */
+    movesUci: readonly string[];
+};
+export declare function squaresBetween(from: Square, to: Square): Square[];
+/**
+ * Derive the immediate legal recapture availability after a capture already
+ * admitted by a replayable line.  This never discovers a continuation: the
+ * caller supplies every UCI move, and the result is rooted at the declared
+ * target-context phase.  Stable identities are replayed along that exact
+ * prefix so a later capture can still name the original piece accurately.
+ */
+export declare function deriveAdmittedCaptureResponseAvailabilityFact(input: AdmittedCaptureResponseAvailabilityInput): AdmittedCaptureResponseAvailabilityFact;
+export declare class MechanicalChessFactProvider implements ChessFactProvider {
+    readonly id: "knights-eye/mechanical-chess-facts";
+    readonly version: "mechanical-chess-facts/18";
+    capabilities(): readonly ChessFactCapability[];
+    collect(requestInput: ChessFactRequest, signal?: AbortSignal): ChessFactResult;
+}
+export declare function createMechanicalFactRequest(context: ReasoningPositionContext, overrides?: Partial<ChessFactRequest["budgets"]>): ChessFactRequest;

package/dist/types/chess-reasoning/mechanical-ray-facts.d.ts

@@ -0,0 +1,19 @@
+import { type Color, type PieceSymbol, type Square } from "chess.js";
+import type { IdentityState } from "./types.js";
+export type OccupiedRayPiece = {
+    pieceId: string;
+    currentSquare: Square;
+    pieceType: PieceSymbol;
+    color: Color;
+};
+export type ExchangeRayAlignmentWitness = {
+    movesUci: string[];
+    finalFen: string;
+    slider: OccupiedRayPiece;
+    front: OccupiedRayPiece;
+    rear: OccupiedRayPiece;
+    ray: Square[];
+};
+export declare function exchangeRayAlignmentWitnesses(fenAfter: string, identityAfter: IdentityState, exchangeLines: readonly (readonly {
+    uci: string;
+}[])[]): ExchangeRayAlignmentWitness[];

package/dist/types/chess-reasoning/mechanism-presentation.d.ts

@@ -0,0 +1,9 @@
+/** Restores the precise bounded projection, including its coverage/omission markers.
+ * Unknown versions or schemas pass through unchanged rather than losing fields. */
+export declare function expandMechanismPresentation(value: unknown): unknown;
+/** A measured but untransmitted square is not a negative result. Full control
+ * deltas stay on the immutable evidence record for retrieval. */
+export declare function compactMechanism(value: unknown, targetSquares: string[]): unknown;
+/** Root + first reply by default; explicit one-based replay targets, and moves
+ * landing on inspected squares, can expose a deeper mechanism without a search. */
+export declare function presentMoveMechanisms(moves: unknown[], inspectPlies?: number[], inspectSquares?: string[]): unknown[];

package/dist/types/chess-reasoning/move-mechanism-facts.d.ts

@@ -0,0 +1,45 @@
+import { Chess, type Color, type PieceSymbol, type Square } from "chess.js";
+import type { IdentityState } from "./types.js";
+type Direction = "N" | "NE" | "E" | "SE" | "S" | "SW" | "W" | "NW";
+export type MoveMechanismFacts = {
+    mover: {
+        pieceId: string;
+        pieceIdAfter: string;
+        fromSquare: Square;
+        toSquare: Square;
+        color: Color;
+        pieceTypeBefore: PieceSymbol;
+        pieceTypeAfter: PieceSymbol;
+        attackersBefore: Square[];
+        attackersAfter: Square[];
+    };
+    attackedUnmovedFriendlyPieces: Array<{
+        pieceId: string;
+        square: Square;
+        pieceType: PieceSymbol;
+        attackersBefore: Square[];
+        attackersAfter: Square[];
+    }>;
+    stationarySliderRays: Array<{
+        pieceId: string;
+        fromSquare: Square;
+        color: Color;
+        pieceType: PieceSymbol;
+        direction: Direction;
+        beforeSquares: Square[];
+        afterSquares: Square[];
+        gainedSquares: Square[];
+        lostSquares: Square[];
+    }>;
+    controlDelta: Array<{
+        square: Square;
+        color: Color;
+        attackersBefore: Square[];
+        attackersAfter: Square[];
+    }>;
+    checksRun: string[];
+    scope: string;
+};
+/** Complete board-local geometric measurements for one already-admitted legal move. */
+export declare function moveMechanismFacts(before: Chess, after: Chess, from: Square, to: Square, beforeIds?: IdentityState, afterIds?: IdentityState): MoveMechanismFacts;
+export {};

package/dist/types/chess-reasoning/native-answer-connector.d.ts

@@ -0,0 +1,4 @@
+import { type LanguageModel } from 'ai';
+import type { AnswerModelConnector } from './answer-model-connector.js';
+/** Native SDK performs exactly one model turn; pipeline owns tool dispatch. */
+export declare function createNativeAnswerConnector(model: LanguageModel): AnswerModelConnector;