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

package/dist/types/chess-reasoning/poc-hypotheses.d.ts

@@ -0,0 +1,74 @@
+import { type ConceptRegistry } from "./concept-registry.js";
+import { type ReasoningEvidenceRecord, type ReasoningHypothesisDecision, type ReasoningHypothesisProposal, type ReasoningHypothesisRecord, type ReasoningHypothesisProvenance, type ReasoningHypothesisRelationRecord, type ReasoningPositionContext, type ReasoningRankedObservationSet, type ReasoningToolDescriptor } from "./poc-contracts.js";
+import type { SemanticAttributes } from "./types.js";
+export declare const RECORD_HYPOTHESES_DESCRIPTOR: ReasoningToolDescriptor;
+export declare const REVIEW_HYPOTHESES_DESCRIPTOR: ReasoningToolDescriptor;
+export declare const EXPLAIN_PLAN_SELECTION_DESCRIPTOR: ReasoningToolDescriptor;
+/**
+ * Pure policy-only validation shared by every semantic admission boundary.
+ * It does not alter Ledger status, review provenance, or hypothesis meaning.
+ */
+export declare function validateHypothesisAcceptancePolicies(hypothesis: ReasoningHypothesisRecord, evidence: Map<string, ReasoningEvidenceRecord>, registry?: ConceptRegistry): string[];
+export type ExplainPlanSelection = {
+    hypothesisIds: string[];
+    relationIds: string[];
+    startHypothesisId: string;
+    goalHypothesisId: string;
+    requiredHypothesisIds: string[];
+    maxEntities: number;
+};
+export type InternalExplainPlanRequest = {
+    hypothesisLedgerRevision: string;
+    hypotheses: {
+        entities: Array<ReasoningHypothesisProposal & {
+            hypothesisId: string;
+        }>;
+        relations: Array<{
+            relationType: string;
+            from: string;
+            to: string;
+            attributes: SemanticAttributes;
+            evidenceIds: string[];
+            hypothesisRelationId: string;
+        }>;
+    };
+    startEntityId: string;
+    goalEntityId: string;
+    requiredEntityIds: string[];
+    maxEntities: number;
+};
+export declare class HypothesisLedger {
+    private readonly contextHash;
+    private readonly evidence;
+    private readonly maxHypotheses;
+    private readonly context?;
+    private readonly registry;
+    private readonly records;
+    private readonly relations;
+    private readonly observations;
+    constructor(contextHash: string, observations: ReasoningRankedObservationSet, evidence: Map<string, ReasoningEvidenceRecord>, maxHypotheses: number, context?: ReasoningPositionContext | undefined, registry?: ConceptRegistry);
+    allRecords(): ReasoningHypothesisRecord[];
+    allRelations(): ReasoningHypothesisRelationRecord[];
+    proposalRevision(): string;
+    finalRevision(): string;
+    record(value: unknown, provenance?: ReasoningHypothesisProvenance): {
+        records: ReasoningHypothesisRecord[];
+        relations: ReasoningHypothesisRelationRecord[];
+        localToHypothesisIds: Record<string, string>;
+    };
+    review(value: unknown, validateProspective?: (records: ReasoningHypothesisRecord[]) => void, supplementalEvidenceByHypothesisId?: Map<string, string[]>): {
+        decisions: ReasoningHypothesisDecision[];
+        evidence: ReasoningEvidenceRecord;
+    };
+    toInternalPlanRequest(value: unknown): InternalExplainPlanRequest;
+    private parseSelection;
+    private validateRealization;
+    private validateDirectedDestinationAnchors;
+}
+/**
+ * Actor/subject plus destination/goal is an exact typed movement assertion,
+ * even when the surrounding hypothesis remains provisional semantic meaning.
+ * Reject impossible bindings before they enter the Ledger so a later reviewer
+ * cannot accidentally promote a supporting piece into the mover's role.
+ */
+export declare function assertDirectedDestinationAnchors(record: Pick<ReasoningHypothesisRecord, "id" | "localId" | "participants" | "evidenceIds">, evidenceById: Map<string, ReasoningEvidenceRecord>, context: ReasoningPositionContext | undefined): void;

package/dist/types/chess-reasoning/poc-move-witnesses.d.ts

@@ -0,0 +1,13 @@
+import type { ReasoningEvidenceRecord, ReasoningPositionContext } from "./poc-contracts.js";
+export type ReasoningMoveWitness = {
+    evidenceId: string;
+    uci: string;
+    pieceId: string;
+    san: string;
+};
+export declare function reasoningEvidenceReplayStartPhase(record: ReasoningEvidenceRecord, context: ReasoningPositionContext): "before" | "after" | null;
+/**
+ * Replays only admitted evidence whose starting position is one of the exact
+ * request positions. A malformed or partial replay contributes no witnesses.
+ */
+export declare function collectReasoningMoveWitnesses(records: Iterable<ReasoningEvidenceRecord>, context: ReasoningPositionContext): ReasoningMoveWitness[];

package/dist/types/chess-reasoning/poc-observations.d.ts

@@ -0,0 +1,23 @@
+import { type ObservationProvider, type QueryContract, type ReasoningObservationSet, type ReasoningPositionContext, type ReasoningRankedObservationSet, type ReasoningRunControls, type SaliencePolicy } from "./poc-contracts.js";
+export declare const DETERMINISTIC_OBSERVATION_PROVIDER_VERSION: "deterministic-position-observations/5";
+export declare const QUESTION_SALIENCE_POLICY_VERSION: "question-conditioned-observation-salience/4";
+export declare class DeterministicObservationProvider implements ObservationProvider {
+    readonly id = "knights-eye/deterministic-position-observations";
+    readonly version: "deterministic-position-observations/5";
+    observe(context: ReasoningPositionContext, _controls: ReasoningRunControls, signal?: AbortSignal): ReasoningObservationSet;
+}
+export declare class CompositeObservationProvider implements ObservationProvider {
+    private readonly providers;
+    readonly id = "knights-eye/composite-observation-provider";
+    readonly version: string;
+    constructor(providers: ObservationProvider[]);
+    observe(context: ReasoningPositionContext, controls: ReasoningRunControls, signal?: AbortSignal): Promise<ReasoningObservationSet>;
+}
+export declare class QuestionConditionedSaliencePolicy implements SaliencePolicy {
+    private readonly maxPresented;
+    readonly id: "question-conditioned-observation-salience/4";
+    constructor(maxPresented?: number);
+    rank(observations: ReasoningObservationSet, contract: QueryContract): ReasoningRankedObservationSet;
+}
+export declare function createDefaultObservationProvider(): ObservationProvider;
+export declare function createDefaultSaliencePolicy(maxPresented?: number): SaliencePolicy;

package/dist/types/chess-reasoning/poc-piece-refs.d.ts

@@ -0,0 +1,12 @@
+import { type Square } from "chess.js";
+import type { IdentityState, PieceId, PieceIdentity } from "./types.js";
+import type { ReasoningPositionContext } from "./poc-contracts.js";
+export type PocIdentityTimeline = {
+    before: IdentityState;
+    after: IdentityState;
+};
+export declare function createPocIdentityTimeline(context: ReasoningPositionContext): PocIdentityTimeline;
+export declare function pieceIdAt(state: IdentityState, square: Square): PieceId | null;
+export declare function squareForPiece(state: IdentityState, pieceId: PieceId): Square | null;
+export declare function pieceIdentity(state: IdentityState, pieceId: PieceId): PieceIdentity | null;
+export declare function canonicalPieceLabel(piece: PieceIdentity): string;

package/dist/types/chess-reasoning/poc-plan-model.d.ts

@@ -0,0 +1,45 @@
+import { type ConceptRegistry } from "./concept-registry.js";
+import type { ReasoningEvidenceRecord, ReasoningPositionContext } from "./poc-contracts.js";
+import type { IdeaGraph, ProofStrength, SemanticAttributes, SemanticParticipant } from "./types.js";
+export type PlanEntityHypothesis = {
+    hypothesisId: string;
+    localId: string;
+    entityType: string;
+    concepts: string[];
+    owner: "w" | "b" | null;
+    participants: SemanticParticipant[];
+    attributes: SemanticAttributes;
+    proofStrength: ProofStrength | null;
+    evidenceIds: string[];
+    sourceObservationIds: string[];
+};
+export type PlanRelationHypothesis = {
+    hypothesisRelationId: string;
+    relationType: string;
+    from: string;
+    to: string;
+    attributes: SemanticAttributes;
+    evidenceIds: string[];
+};
+export type PlanHypothesisSet = {
+    entities: PlanEntityHypothesis[];
+    relations: PlanRelationHypothesis[];
+};
+export type ExplainPlanRequest = {
+    hypothesisLedgerRevision: string;
+    hypotheses: PlanHypothesisSet;
+    startEntityId: string;
+    goalEntityId: string;
+    requiredEntityIds: string[];
+    maxEntities: number;
+};
+export type ResolvedPlanExplanation = {
+    hypothesisLedgerRevision: string;
+    graph: IdeaGraph;
+    localToGraphIds: Record<string, string>;
+    selectedEntityIds: string[];
+    selectedRelationIds: string[];
+    evidenceIds: string[];
+};
+export declare function parseExplainPlanRequest(value: unknown): ExplainPlanRequest;
+export declare function resolveAndSelectPlan(rawRequest: unknown, context: ReasoningPositionContext, contextHash: string, availableEvidence: Iterable<ReasoningEvidenceRecord>, registry?: ConceptRegistry): ResolvedPlanExplanation;

package/dist/types/chess-reasoning/poc-semantic-text.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Board objects must travel as typed narrative segments. This pattern catches
+ * piece names, coordinates, UCI, common SAN (including captures and
+ * disambiguation), and castling when they leak into opaque text.
+ */
+export declare const RAW_CHESS_TEXT_PATTERN_SOURCE: string;
+export declare const RAW_CHESS_TEXT: RegExp;
+export declare const SEMANTIC_TEXT_JSON_PATTERN: string;

package/dist/types/chess-reasoning/poc-tools.d.ts

@@ -0,0 +1,81 @@
+import { type BranchExpansionConfig } from './branch-expansion.js';
+import type { ConceptRegistry } from "./concept-registry.js";
+import { type ReasoningPositionContext, type ReasoningToolSet } from "./poc-contracts.js";
+import type { IdeaGraph, SemanticValue } from "./types.js";
+export type PositionAnalysisLine = {
+    rootMove: string;
+    pv: string[];
+    depth: number;
+    nodes: number | null;
+    scoreCp: number | null;
+    /** @deprecated Legacy name: signed mate distance in moves, NOT plies. Rename before public release. */
+    matePly: number | null;
+    /** Added at the adapter/tool boundary; old saved records remain unchanged. */
+    scoreScope?: Record<string, string>;
+    scoreProvenance?: Record<string, SemanticValue>;
+    /** The unmodified engine line from the original search root. */
+    rawPv?: string[];
+    /** Joined endpoint searches are conditional, each with its own score/search scope. */
+    pvCompletion?: {
+        requestedPlies: number;
+        actualPlies: number;
+        status: "complete" | "terminal" | "short-budget" | "short-attempt-limit" | "short-no-progress" | "short-error" | "invalid";
+        conditional: boolean;
+        segments: Array<{
+            fen: string;
+            startPly: number;
+            depth: number;
+            pv: string[];
+            scoreCp: number | null;
+            matePly: number | null;
+            scoreScope?: Record<string, string>;
+            scoreProvenance?: Record<string, SemanticValue>;
+            command: string;
+            engine: string;
+            engineBuild: string;
+            cacheProvenance: string;
+        }>;
+    };
+};
+export type PositionAnalysisRequest = {
+    fen: string;
+    depth: number;
+    multiPv: number;
+    rootMoves: string[];
+    minimumPvPlies?: number;
+    /** Defaults to `default`; `bypass` is reserved for independently sampled probes. */
+    cachePolicy?: "default" | "bypass";
+    signal?: AbortSignal;
+};
+/** Identifies the exact local source that supplied a browser analysis result. */
+export type PositionAnalysisCacheProvenance = "engine" | "widget-analysis-cache" | "browser-completed-cache";
+export type PositionAnalysisResult = {
+    engine: string;
+    engineBuild: string;
+    command: string;
+    bestMove: string | null;
+    lines: PositionAnalysisLine[];
+    /** Present for browser-backed analyses so callers can distinguish local reuse from a search. */
+    cacheProvenance?: PositionAnalysisCacheProvenance;
+    sourceCacheProvenance?: PositionAnalysisCacheProvenance;
+};
+export interface PositionAnalysisProvider {
+    analyze(request: PositionAnalysisRequest): Promise<PositionAnalysisResult>;
+}
+export type PocToolHostOptions = {
+    analyzer?: PositionAnalysisProvider;
+    graph?: IdeaGraph;
+    registry?: ConceptRegistry;
+    defaultDepth?: number;
+    minimumDepth?: number;
+    maxDepth?: number;
+    maxRootMoves?: number;
+    leadingAlternative?: {
+        fen: string;
+        uci: string;
+        evidenceId: string;
+    };
+    /** Explicit, bounded option; omitted for ordinary hosts. */
+    branchExpansion?: BranchExpansionConfig;
+};
+export declare function createPocToolHost(contextInput: ReasoningPositionContext, options?: PocToolHostOptions): ReasoningToolSet;

package/dist/types/chess-reasoning/portable-answer-runtime.d.ts

@@ -0,0 +1,291 @@
+import type { RecordedSelectedClassification } from './recorded-selected-classification.js';
+import { visibleSupportLines } from './visible-support-lines.js';
+import type { WikibooksIndex } from './wikibooks-index.js';
+import { type OpeningSourceCredit } from './opening-source-credits.js';
+import type { MaterialFormat } from './material-format.js';
+import { type InitialSearchPlan } from './initial-search-plan.js';
+import type { WikibooksContextResult, WikibooksTarget } from "./opening-source-contracts.js";
+import { type ExplanationReview } from './simple-explanation-coverage.js';
+import { type AiFailureDetails } from "../ai-request-failure.js";
+import type { SimpleBoardAnalysis } from "./simple-board-analysis.js";
+import { type PriorConversationMessage } from "./conversation-context.js";
+import type { RecordedMainLine } from "./answer-host-contracts.js";
+import type { SimpleEffort } from "./simple-agent-config.js";
+import { type AnswerModelConnector } from "./answer-model-connector.js";
+import { type AblationEvidenceClosureBundle } from "./ablation-evidence-bundle.js";
+import { type ObservableLlmTraceSink } from "./ai-sdk-runtime-support.js";
+import { type ReasoningEvidenceRecord, type ReasoningToolSet } from "./poc-contracts.js";
+import type { PlayerPerspective } from "../player-perspective.js";
+export { SIMPLE_TOOL_AGENT_VERSION } from "./simple-runtime-version.js";
+export declare const SIMPLE_MODELS: {
+    readonly "Simple-Sol": "openai/gpt-5.6-sol";
+    readonly "Simple-Opus": "anthropic/claude-opus-5";
+};
+export type SimpleModelOption = keyof typeof SIMPLE_MODELS;
+export declare const SIMPLE_BUDGETS: Readonly<{
+    maxModelCalls: 6;
+    maxOutputTokensPerCall: 6000;
+    maxSearchesPerBatch: 8;
+    maxOutputTokens: 18000;
+    maxWallTimeMs: 180000;
+    maxRequestBytes: 1000000;
+    maxDepth: 14;
+    maxRootMoves: 6;
+}>;
+export declare const SIMPLE_EXPANDED_BUDGETS: Readonly<{
+    maxOutputTokensPerCall: 12000;
+    maxOutputTokens: 36000;
+    maxWallTimeMs: 300000;
+    maxModelCalls: 6;
+    maxSearchesPerBatch: 8;
+    maxRequestBytes: 1000000;
+    maxDepth: 14;
+    maxRootMoves: 6;
+}>;
+export declare const SIMPLE_RECOVERY_BUDGETS: Readonly<{
+    maxOutputTokensPerCall: 24000;
+    maxOutputTokens: 72000;
+    maxWallTimeMs: 600000;
+    maxModelCalls: 6;
+    maxSearchesPerBatch: 8;
+    maxRequestBytes: 1000000;
+    maxDepth: 14;
+    maxRootMoves: 6;
+}>;
+export declare const SIMPLE_DISCLOSURE = "Experimental answer. Tool inputs, legality, evidence scope and interactive references are checked at completion and reported in referenceValidation; prose correctness and claim entailment are not validated. Unresolved references remain plain text.";
+/** Keep only billing and bounded routing metadata; provider reasoning stays private in continuation memory. */
+export declare function simpleUsageForTrace(usage: unknown, metadata: unknown, headers?: Record<string, string>): {
+    providerMetadata?: {
+        openrouter: {
+            usage: {
+                cost: number;
+            };
+        };
+    } | undefined;
+    serviceRouting?: import("../ai-routing-diagnostics.js").AiRoutingDiagnostics | undefined;
+    usage: unknown;
+};
+export declare function validateSimpleToolInput(name: string, input: Record<string, unknown>, schema: Record<string, unknown>): void;
+export type SimpleAgentDiagnostic = {
+    stage: string;
+    inputTokens: number;
+    outputTokens: number;
+    latencyMs: number;
+    finishReason: string;
+};
+export declare function runPreparedAnswer(input: {
+    policy?: {
+        system: (flags: {
+            encoded: boolean;
+            reusedFacts: boolean;
+            sharedEvidence?: boolean;
+            final: boolean;
+            purposeGuidance?: boolean;
+            searchBreadthGuidance?: boolean;
+            boardAnalysisGuidance?: boolean;
+            explanationCoverage?: boolean;
+            answerComposition?: 'move-explanation' | 'none';
+        }) => string;
+        description: (name: string) => string;
+    };
+    connector: AnswerModelConnector;
+    openingIndex?: () => Promise<WikibooksIndex>;
+    modelName: string;
+    requestId: string;
+    /** Offline evaluation only; callers supply a condition-specific bundle without withheld evidence. */
+    evaluation?: {
+        fixedEvidence: true;
+        requiredEvidenceIds: string[];
+    };
+    /** Node evaluation only: provider metering is unavailable; no browser caller sets this. */
+    evaluationTransport?: {
+        kind: "subagent-files" | "openrouter-direct";
+        wallTimeMs: number;
+    };
+    /** Baseline switch for controlled serializer evaluation only. */
+    evidenceCompaction?: "baseline" | "lossless";
+    /** Node comparison override; browser uses the qualified default. */
+    materialFormat?: MaterialFormat;
+    question?: string;
+    /** Diagnostic ablation only; live Simple enables bounded explanation review. */
+    explanationCoverage?: boolean;
+    boardAnalysis?: SimpleBoardAnalysis;
+    recordedSelectedClassification?: RecordedSelectedClassification;
+    /** Research ablation; normal evidence always includes the standard reference. */
+    squareReference?: boolean;
+    openingSourceContext?: WikibooksContextResult;
+    openingSourceLookup?: (targets: WikibooksTarget[], signal: AbortSignal, root?: import("./poc-contracts.js").ReasoningPositionContext) => Promise<WikibooksContextResult>;
+    /** Total overlapping browser preparation time, including optional source wait. */
+    preModelElapsedMs?: number;
+    playerPerspective?: PlayerPerspective | null;
+    conversationHistory?: readonly PriorConversationMessage[];
+    getMainLine?: (signal: AbortSignal) => Promise<RecordedMainLine>;
+    initialMainLine?: RecordedMainLine;
+    initialSearchPlan?: InitialSearchPlan;
+    refreshPreparedBoardAnalysis?: (signal: AbortSignal) => Promise<SimpleBoardAnalysis | undefined>;
+    omitSelectedContext?: boolean;
+    routingDecision?: import('./question-routing.js').QuestionRoutingDecision;
+    effort?: SimpleEffort;
+    providerRoute?: string;
+    /** Explicit browser analysis policy; frozen diagnostic defaults remain unchanged. */
+    analysisDepth?: 18;
+    preparation?: import("./simple-evidence-preparation.js").SimpleEvidencePreparation;
+    purposeGuidance?: boolean;
+    searchBreadthGuidance?: boolean;
+    boardAnalysisGuidance?: boolean;
+    simpleAllowance?: "default" | "expanded" | "glm-recovery";
+    bundle: Readonly<AblationEvidenceClosureBundle>;
+    host: ReasoningToolSet;
+    signal?: AbortSignal;
+    observableTraceSink?: ObservableLlmTraceSink;
+    onProgress?: (message: string) => void;
+}): Promise<{
+    usage: {
+        inputTokens: number;
+        outputTokens: number;
+        metering: "reported" | "partly-unavailable";
+        reportedOutputTokens: number | null;
+        outputBudgetReservation: number;
+        unmeteredCalls: number;
+        reportedInputTokens: number | null;
+        unmeteredInputCalls: number;
+    };
+    limitations: string[];
+    evaluationTransport?: {
+        metering: string;
+        outputBudgetReserved: number;
+        kind: "subagent-files" | "openrouter-direct";
+        wallTimeMs: number;
+    } | undefined;
+    acquiredMainLines: {
+        source: string;
+        startFen: string;
+        moves: {
+            uci: string;
+            san: string;
+            moveNumber: number;
+            color: import("chess.js").Color;
+        }[];
+        selectedIndex: number;
+        selectedAtStart: boolean;
+        selectedOnMainLine: boolean;
+        totalPlies: number;
+        truncated: boolean;
+        pgn: string;
+    }[];
+    status: "failure" | "diagnostic";
+    answer: string;
+    failure: string | null;
+    failureDetails: AiFailureDetails | undefined;
+    diagnostics: SimpleAgentDiagnostic[];
+    toolRuns: Record<string, unknown>[];
+    elapsedMs: number;
+    initialEvidenceIds: string[];
+    presentedEvidenceIds: string[];
+    presentedEvidence: ReasoningEvidenceRecord[];
+    openingSources: OpeningSourceCredit[];
+    searchesUsed: 0 | 1 | 2 | 3;
+    searchesSucceeded: number;
+    searchesFailed: number;
+    engineEvidenceStatus: "unavailable" | "not-requested" | "unknown" | "available";
+    preparation: import("./simple-evidence-preparation.js").SimpleEvidencePreparation | undefined;
+    explanationCoverage?: {
+        stopRepairs: number;
+        reviewCount: number;
+        qualificationRequested: boolean;
+        status: string;
+        unresolved: never[];
+        investigated: never[];
+        modelJudgment: null;
+        limitation: string;
+    } | {
+        stopRepairs: number;
+        reviewCount: number;
+        qualificationRequested: boolean;
+        status: string;
+        unresolved: string[];
+        investigated: string[];
+        modelJudgment: ExplanationReview;
+        limitation: string;
+    } | undefined;
+    recurringMotifs?: {
+        authority: string;
+        branches: {
+            root: string;
+            evidenceId: string;
+            plies: number;
+            depth: number;
+            continuationCoverage: string;
+            unmetHorizonRequests: {
+                evidenceId: string;
+                requested: number;
+                prefixLength: number;
+            }[];
+            prefixLength: number;
+            prefixEvidenceId: string | null;
+            pvCompletion: unknown;
+            rawPv: unknown;
+            san: string;
+            score: unknown;
+            structuralEvents: unknown[];
+        }[];
+        observedRoutes: {
+            piece: string;
+            start: string;
+            destination: string;
+            roots: string[];
+            witnesses: unknown[];
+        }[];
+        distinctOpponentRoots: number;
+    } | undefined;
+    preparationConsolidation: {
+        version: string;
+        searchCount: number;
+        primaryEntryCount: number;
+        summarizedDiscoveryCount: number;
+        dependencies: Record<string, unknown>[];
+        interpretation: string;
+    };
+    referenceValidation: ({
+        version: string;
+        citationRepairs: {
+            originalId: string;
+            canonicalId: string;
+        }[];
+        interactionCoverage: {
+            resolved: number;
+            total: number;
+        };
+        unresolvedReferences: string[];
+        unboundMentions: string[];
+        notationCorrections: string[];
+        labelCorrections: {
+            originalLabel: string;
+            canonicalLabel: string;
+            target: string;
+        }[];
+        gameReferences: {
+            target: string;
+            status: "resolved" | "repaired" | "unresolved";
+            reason?: string;
+        }[];
+        repairs: {
+            originalTarget: string;
+            repairedTarget: string;
+            label: string;
+            evidenceIds: string[];
+            authority: string;
+        }[];
+        causalClaimChecks: import("./causal-claim-checks.js").CausalClaimCheck[];
+        causalClaimCheckStatus: "unavailable" | "completed";
+        causalClaimCheckScope: string;
+    } & {
+        supportingContinuations?: ReturnType<typeof visibleSupportLines>["additions"];
+    }) | {
+        status: "unavailable";
+        reason: string;
+    };
+    completionReason: string | null;
+    toolCallsUsed: number;
+    initialSearches: Record<string, unknown>[];
+}>;

package/dist/types/chess-reasoning/position-analysis-contracts.d.ts

@@ -0,0 +1,31 @@
+import type { PositionAnalysisLine as LegacyPositionAnalysisLine, PositionAnalysisResult as LegacyPositionAnalysisResult, PositionAnalysisProvider as LegacyPositionAnalysisProvider, PositionAnalysisRequest } from './poc-tools.js';
+export type { PositionAnalysisRequest } from './poc-tools.js';
+/** Historical evidence uses matePly, whose values have always been signed moves. */
+export type { LegacyPositionAnalysisLine, LegacyPositionAnalysisResult, LegacyPositionAnalysisProvider };
+type LegacyCompletion = NonNullable<LegacyPositionAnalysisLine['pvCompletion']>;
+type LegacySegment = LegacyCompletion['segments'][number];
+/** Signed mate-in-moves relative to the declared score perspective; null is no mate score. */
+export type PositionAnalysisSegment = Omit<LegacySegment, 'matePly'> & {
+    mateInMoves: number | null;
+};
+export type PositionAnalysisLine = Omit<LegacyPositionAnalysisLine, 'matePly' | 'pvCompletion'> & {
+    mateInMoves: number | null;
+    pvCompletion?: Omit<LegacyCompletion, 'segments'> & {
+        segments: PositionAnalysisSegment[];
+    };
+};
+export type PositionAnalysisResult = Omit<LegacyPositionAnalysisResult, 'lines'> & {
+    lines: PositionAnalysisLine[];
+};
+export interface PositionAnalysisProvider {
+    analyze(request: PositionAnalysisRequest): Promise<PositionAnalysisResult>;
+}
+export type CompatiblePositionAnalysisProvider = PositionAnalysisProvider | LegacyPositionAnalysisProvider;
+/** Rename only: no search, score reinterpretation, schema migration or evidence admission. */
+export declare function toPositionAnalysis(result: PositionAnalysisResult | LegacyPositionAnalysisResult): PositionAnalysisResult;
+/** Explicit compatibility conversion for current internal tool/trace wire schemas. */
+export declare function toLegacyPositionAnalysis(result: PositionAnalysisResult | LegacyPositionAnalysisResult): LegacyPositionAnalysisResult;
+/** Public/legacy input normalization; delegates the original request and cancellation signal. */
+export declare function toLegacyPositionAnalysisProvider(provider: CompatiblePositionAnalysisProvider): LegacyPositionAnalysisProvider;
+/** Adapt an existing legacy provider to the preferred public signed-moves contract. */
+export declare function toPositionAnalysisProvider(provider: CompatiblePositionAnalysisProvider): PositionAnalysisProvider;

package/dist/types/chess-reasoning/position-analysis-scope.d.ts

@@ -0,0 +1,3 @@
+import type { PositionAnalysisRequest, PositionAnalysisResult } from "./poc-tools.js";
+/** Both Stockfish adapters retain UCI scores relative to the search root's turn. */
+export declare function scopePositionAnalysis(result: PositionAnalysisResult, request: PositionAnalysisRequest): PositionAnalysisResult;

package/dist/types/chess-reasoning/preparation-consolidation.d.ts

@@ -0,0 +1,21 @@
+import type { ReasoningEvidenceRecord } from './poc-contracts.js';
+export type PreparedPresentation = {
+    callId: string;
+    modelRun: Record<string, unknown>;
+    records: ReasoningEvidenceRecord[];
+    playedMove?: string;
+    discoveryCallId?: string;
+    limitations?: string[];
+};
+/** Consolidates presentation only. Raw searches, evidence and numeric scores are never merged. */
+export declare function consolidatePreparedSearches(entries: readonly PreparedPresentation[]): {
+    results: Record<string, unknown>[];
+    diagnostics: {
+        version: string;
+        searchCount: number;
+        primaryEntryCount: number;
+        summarizedDiscoveryCount: number;
+        dependencies: Record<string, unknown>[];
+        interpretation: string;
+    };
+};

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

@@ -0,0 +1,16 @@
+import { type ExistingAnalysisContextMode } from "./existing-analysis-context.js";
+import { CompositeObservationProvider } from "./poc-observations.js";
+import type { ReasoningPositionContext } from "./poc-contracts.js";
+/**
+ * The production pre-semantic observation composition.  It is deliberately
+ * environment-neutral: browser and evaluation callers share exactly the same
+ * deterministic, mechanical-fact, and attributed-existing-analysis inputs.
+ */
+export declare const PRODUCTION_OBSERVATION_PROVIDER_VERSION: "production-observation-provider/1";
+export type ProductionObservationProviderInput = {
+    existingAnalysis?: unknown;
+    context?: ReasoningPositionContext;
+    question?: string;
+    existingAnalysisContextMode?: ExistingAnalysisContextMode;
+};
+export declare function createProductionObservationProvider(input?: ProductionObservationProviderInput): CompositeObservationProvider;