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

package/dist/types/chess-reasoning/simple-explanation-coverage.d.ts

@@ -0,0 +1,90 @@
+import { type ReasoningEvidenceRecord, type ReasoningPositionContext } from './poc-contracts.js';
+export declare const EXPLANATION_FAMILIES: readonly ["accept-offer", "central-break", "kingside-play", "queenside-play", "exchange-defender", "preserve-piece", "direct-tactics", "quiet-improvement"];
+export declare const EXPLANATION_REVIEW_SCHEMA: Record<string, unknown>;
+export type ExplanationReview = {
+    mode: 'positional' | 'tactical' | 'direct' | 'not-explanation';
+    mechanism: string;
+    challenges: string[];
+    evidenceIds: string[];
+    unresolved: string[];
+    limitations?: string[];
+    shortLineReasons?: string[];
+};
+export declare function validateExplanationReview(input: Record<string, unknown>, context: ReasoningPositionContext, known: Map<string, ReasoningEvidenceRecord>): ExplanationReview;
+export declare function explanationBranches(context: ReasoningPositionContext, records: Iterable<ReasoningEvidenceRecord>): {
+    root: string;
+    id: string;
+    pv: string[];
+    san: string[];
+    depth: number;
+    score: unknown;
+    prefixLength: number;
+    prefixEvidenceId: string | null;
+    pvCompletion: unknown;
+    rawPv: unknown;
+    continuationCovered: boolean;
+    unmetHorizonRequests: {
+        evidenceId: string;
+        requested: number;
+        prefixLength: number;
+    }[];
+}[];
+export declare function legalInvestigationRoots(context: ReasoningPositionContext): {
+    [k: string]: {
+        uci: string;
+        san: string;
+    }[];
+};
+export declare function explanationSummary(context: ReasoningPositionContext, records: Iterable<ReasoningEvidenceRecord>): {
+    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;
+};
+export declare function explanationCoverage(context: ReasoningPositionContext, records: Iterable<ReasoningEvidenceRecord>, review: ExplanationReview | null): {
+    status: string;
+    unresolved: never[];
+    investigated: never[];
+    modelJudgment: null;
+    limitation: string;
+} | {
+    status: string;
+    unresolved: string[];
+    investigated: string[];
+    modelJudgment: ExplanationReview;
+    limitation: string;
+};
+/** Remove only expensive per-ply geometry from planning copies; original evidence stays in known. */
+export declare function planningEvidence(result: {
+    contextHash: string;
+    evidence: ReasoningEvidenceRecord[];
+    limitations: readonly string[];
+}): {
+    evidence: ReasoningEvidenceRecord[];
+    contextHash: string;
+    limitations: readonly string[];
+};

package/dist/types/chess-reasoning/simple-fact-delivery.d.ts

@@ -0,0 +1,43 @@
+import type { ReasoningEvidenceRecord } from "./poc-contracts.js";
+export declare const FACT_DELIVERY_INSTRUCTIONS = "{$priorFact:[toolCallId,evidenceId,variation,ply]} reuses an identical tactical fact from an earlier tool result in this CURRENT_QUESTION only. Locate the native result for toolCallId, then that evidence record's continuationMoveFacts[variation].moves[ply-1]; variation=-1 instead means rootMoveFacts[ply-1]. Expand its same-message encoding/metadata. Position, ordered prefix and the complete fact were checked for equality; this does NOT reuse scores or search provenance. Every current comparison retains its own ranking, settings and coverage. No references point to previous chat exchanges.";
+/** Request-local reuse, valid only while the loop's earlier tool messages remain. */
+export declare class SimpleFactDelivery {
+    private readonly contextHash;
+    private delivered;
+    private pending;
+    /** Called only after complete native response messages have entered context. */
+    commit(): void;
+    constructor(contextHash: string);
+    project(callId: string, result: {
+        contextHash: string;
+        evidence: readonly ReasoningEvidenceRecord[];
+        limitations: readonly string[];
+    }): {
+        evidence: (ReasoningEvidenceRecord | {
+            data: {
+                rootMoveFacts?: unknown[] | undefined;
+                continuationMoveFacts?: (string | number | boolean | import("./types.js").SemanticValue[] | {
+                    [key: string]: import("./types.js").SemanticValue;
+                } | {
+                    moves: unknown[];
+                } | null)[] | undefined;
+            };
+            schemaVersion: typeof import("./poc-contracts.js").REASONING_POC_VERSION;
+            id: string;
+            contextHash: string;
+            kind: import("./poc-contracts.js").ReasoningEvidenceKind;
+            source: string;
+            proofStrength: import("./types.js").ProofStrength | null;
+            licenses?: import("./evidence-licenses.js").EvidenceLicense[];
+            summary: string;
+            coverage: {
+                complete: boolean;
+                covered: string[];
+                unresolved: string[];
+            } | null;
+            replay: Record<string, import("./types.js").SemanticValue> | null;
+        })[];
+        contextHash: string;
+        limitations: readonly string[];
+    };
+}

package/dist/types/chess-reasoning/simple-fallback-premise.d.ts

@@ -0,0 +1,5 @@
+import type { ReasoningEvidenceRecord, ReasoningPositionContext } from './poc-contracts.js';
+/** A deliberately narrow correction for an asserted forced win. The finite
+ * search only limits what this fallback can support; it is no proof that a
+ * different search could never find a forced win. */
+export declare function forcedWinPremiseFallback(question: string, context: ReasoningPositionContext | undefined, records: readonly ReasoningEvidenceRecord[], selectedContextAvailable?: boolean): string | null;

package/dist/types/chess-reasoning/simple-prose-references.d.ts

@@ -0,0 +1,108 @@
+import type { RecordedReferenceLine } from './historical-prose.js';
+export type AuthoredReferenceResult = {
+    label: string;
+    target: string;
+    resolved: boolean;
+    reason?: string;
+    canonicalLabel?: string;
+};
+import { type ReasoningPositionContext, type ReasoningEvidenceRecord } from "./poc-contracts.js";
+import { type FreshEnginePvWitness, type FreshEnginePvReferenceEvidence } from './fresh-engine-pv-witnesses.js';
+export type { FreshEnginePvWitness } from './fresh-engine-pv-witnesses.js';
+export type SimpleProseReferenceOptions = {
+    freshEnginePvWitnesses?: readonly FreshEnginePvWitness[];
+};
+export type SimpleReferenceGapCounts = {
+    version: 'simple-reference-gap-counts/1';
+    unboundProseSpans: number;
+    unboundMentions: number;
+    unresolvedReferences: number;
+    unknownCitations: number;
+    formattingWarnings: number;
+};
+export declare const SIMPLE_REFERENCE_VERSION = "simple-references/22";
+declare const INTERNAL_WITNESS: unique symbol;
+type Phase = "before" | "after";
+export type SimplePosition = {
+    recordedContext?: ReasoningPositionContext;
+    start: Phase;
+    moves: {
+        uci: string;
+        san: string;
+        pieceId: string;
+    }[];
+    fen: string;
+};
+export type SimpleReference = {
+    kind: "move" | "piece" | "square" | "sequence";
+    label: string;
+    displayLabel?: string;
+    position: SimplePosition;
+    evidenceIds: string[];
+    engineEvidence?: FreshEnginePvReferenceEvidence[];
+    square?: string;
+    pieceId?: string;
+    san?: string;
+    uci?: string;
+    copyText?: string;
+    pieceCode?: string;
+};
+export type SimpleToken = {
+    text: string;
+    reference?: SimpleReference;
+    sourceLink?: {
+        href: string;
+    };
+    gap?: string;
+    variationIndex?: number;
+    variationStart?: boolean;
+    variationEnd?: boolean;
+    variationPlayFrom?: number;
+    variationMoveIndices?: number[];
+};
+/** Source attribution links are presentation-only; they never confer chess evidence. */
+export declare function safeSimpleSourceLink(target: string): {
+    href: string;
+} | null;
+/** Preserve the model's prose while removing presentation-only fence markers. */
+export declare function stripSimpleMarkdownFences(value: string): string;
+/** Internal citation labels are not user prose or navigation. Raw output is retained. */
+export declare function stripSimpleCitationLinks(value: string): string;
+/** Repair only trailing legacy labels attested as internal links in the raw answer. */
+export declare function repairFrozenCitationLabels(value: string, rawParagraph: string): string;
+/** Presentation admission only: no claim-entailment or strategic validator. */
+export declare function simpleProseReferences(answer: string, context: ReasoningPositionContext, records: readonly ReasoningEvidenceRecord[], recordedLine?: RecordedReferenceLine, recordedPath?: string[], onReference?: (reference: AuthoredReferenceResult) => void, internalWitness?: typeof INTERNAL_WITNESS | SimpleProseReferenceOptions): {
+    variations: {
+        position: SimplePosition;
+        references: SimpleReference[];
+        start: Phase;
+        ucis: string[];
+        evidenceIds: string[];
+        authority: string;
+        engineEvidence?: FreshEnginePvReferenceEvidence[];
+        recordedContext?: ReasoningPositionContext;
+    }[];
+    freshEnginePvAdmission?: import("./fresh-engine-pv-witnesses.js").FreshEnginePvAdmissionAudit | undefined;
+    referenceGapCounts?: SimpleReferenceGapCounts | undefined;
+    blocks: {
+        tokens: SimpleToken[];
+        evidenceIds: string[];
+        leadingVariationIndex: number | undefined;
+    }[];
+    evidence: ReasoningEvidenceRecord[];
+    gaps: string[];
+    notationCorrections: string[];
+    coverage: {
+        resolved: number;
+        total: number;
+    };
+};
+/** Formatting only: use already validated paths, including persisted answer views. */
+export declare function decorateSimpleVariations(blocks: {
+    tokens: SimpleToken[];
+    leadingVariationIndex?: number;
+}[], variations: readonly {
+    start: Phase;
+    ucis: string[];
+    recordedContext?: ReasoningPositionContext;
+}[]): void;

package/dist/types/chess-reasoning/simple-runtime-version.d.ts

@@ -0,0 +1 @@
+export declare const SIMPLE_TOOL_AGENT_VERSION = "simple-native-tool-agent/40";

package/dist/types/chess-reasoning/stable.d.ts

@@ -0,0 +1,2 @@
+export declare function stableHash(value: unknown): string;
+export declare function stableJson(value: unknown): string;

package/dist/types/chess-reasoning/tool-input-loop-guard.d.ts

@@ -0,0 +1,5 @@
+/** Per answering episode; only pre-dispatch validation errors enter this cache. */
+export declare function createToolInputLoopGuard(): {
+    readonly repeatedFailures: number;
+    validate(name: string, input: Record<string, unknown>, validate: () => void): void;
+};

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

@@ -0,0 +1,180 @@
+import type { Color, PieceSymbol, Square } from "chess.js";
+export declare const CHESS_REASONING_SCHEMA_VERSION: "0.2.0";
+export declare const CHESS_REASONING_POLICY_VERSION: "shadow-2";
+export type BranchId = string;
+export type PieceId = string;
+export type EntityId = string;
+export type EvidenceId = string;
+export type CandidateId = string;
+export type ConceptKey = string;
+export type RegistryKey = string;
+export type ProofStrength = "observed" | "supported" | "forced";
+export type CandidateDisposition = "accepted" | "rejected" | "unsupported";
+export type ConceptCoverage = "evaluated" | "partial" | "unsupported";
+export type SemanticScalar = string | number | boolean | null;
+export type SemanticValue = SemanticScalar | SemanticValue[] | {
+    [key: string]: SemanticValue;
+};
+export type SemanticAttributes = Record<string, SemanticValue>;
+export type SemanticReference = {
+    domain: RegistryKey;
+    id: string;
+};
+export type SemanticParticipant = {
+    role: RegistryKey;
+    ref: SemanticReference;
+};
+export type PieceIdentity = {
+    id: PieceId;
+    color: Color;
+    type: PieceSymbol;
+    originSquare: Square;
+    createdPly: number;
+    promotedFrom: PieceId | null;
+    capturedAtPly: number | null;
+    retiredAtPly: number | null;
+};
+export type IdentityState = {
+    schemaVersion: typeof CHESS_REASONING_SCHEMA_VERSION;
+    branchId: BranchId;
+    fen: string;
+    ply: number;
+    pieces: Record<PieceId, PieceIdentity>;
+    squares: Partial<Record<Square, PieceId>>;
+    promotionSequence: number;
+};
+export type MoveIdentityDelta = {
+    branchId: BranchId;
+    ply: number;
+    uci: string;
+    san: string;
+    mover: PieceId;
+    captured: PieceId | null;
+    promoted: PieceId | null;
+    rookMoved: PieceId | null;
+    beforeFen: string;
+    afterFen: string;
+};
+export type ProposalReason = {
+    code: RegistryKey;
+    detail: string;
+};
+/**
+ * Candidates and persisted entities deliberately share generic semantic
+ * building blocks. Chess concepts are registry values in `concepts`; they do
+ * not add flags, fields, or concept-specific entity subclasses.
+ */
+export type SemanticCandidate = {
+    schemaVersion: typeof CHESS_REASONING_SCHEMA_VERSION;
+    id: CandidateId;
+    branchId: BranchId;
+    ply: number;
+    uci: string;
+    san: string;
+    entityType: RegistryKey;
+    concepts: ConceptKey[];
+    owner: Color | null;
+    participants: SemanticParticipant[];
+    attributes: SemanticAttributes;
+    proposalReasons: ProposalReason[];
+    verification: "not-requested";
+};
+export type CandidateGenerationReport = {
+    schemaVersion: typeof CHESS_REASONING_SCHEMA_VERSION;
+    branchId: BranchId;
+    ply: number;
+    move: MoveIdentityDelta;
+    candidates: SemanticCandidate[];
+    conceptCoverage: Record<ConceptKey, ConceptCoverage>;
+    skipped: Array<{
+        concept: ConceptKey;
+        reason: string;
+    }>;
+};
+export type ProbeBudget = {
+    depth: number | null;
+    nodes: number | null;
+    timeMs: number | null;
+};
+export type EvidenceRecord = {
+    schemaVersion: typeof CHESS_REASONING_SCHEMA_VERSION;
+    id: EvidenceId;
+    candidateId: CandidateId;
+    disposition: CandidateDisposition;
+    proofStrength: ProofStrength | null;
+    summary: string;
+    engine: string;
+    engineBuild: string;
+    budget: ProbeBudget;
+    rootMovesCovered: string[];
+    unresolvedMoves: string[];
+    principalVariations: string[][];
+    scoreCp: number | null;
+    matePly: number | null;
+    replay: {
+        fen: string;
+        command: string;
+    } | null;
+};
+export type SemanticTransition = {
+    ply: number;
+    uci: string;
+    state: RegistryKey;
+    annotation: RegistryKey;
+    evidence: EvidenceId[];
+};
+export type SemanticEntity = {
+    schemaVersion: typeof CHESS_REASONING_SCHEMA_VERSION;
+    id: EntityId;
+    branchId: BranchId;
+    entityType: RegistryKey;
+    concepts: ConceptKey[];
+    owner: Color | null;
+    createdByPly: number;
+    createdByUci: string;
+    participants: SemanticParticipant[];
+    attributes: SemanticAttributes;
+    proofStrength: ProofStrength | null;
+    state: RegistryKey;
+    evidence: EvidenceId[];
+    transitions: SemanticTransition[];
+};
+export type SemanticRelation = {
+    id: string;
+    branchId: BranchId;
+    relationType: RegistryKey;
+    from: EntityId;
+    to: EntityId;
+    createdAtPly: number;
+    attributes: SemanticAttributes;
+    evidence: EvidenceId[];
+};
+export type IdeaGraph = {
+    schemaVersion: typeof CHESS_REASONING_SCHEMA_VERSION;
+    policyVersion: typeof CHESS_REASONING_POLICY_VERSION;
+    branchId: BranchId;
+    ply: number;
+    inputHash: string;
+    entities: SemanticEntity[];
+    relations: SemanticRelation[];
+    candidateOutcomes: Array<{
+        candidateId: CandidateId;
+        disposition: CandidateDisposition;
+        evidence: EvidenceId[];
+    }>;
+};
+export type SemanticMoveRecord = {
+    schemaVersion: typeof CHESS_REASONING_SCHEMA_VERSION;
+    identity: IdentityState;
+    generation: CandidateGenerationReport;
+    evidence: EvidenceRecord[];
+    graph: IdeaGraph;
+};
+export type ToolSupport = "supported" | "insufficient-evidence" | "unsupported-concept";
+export type ReasoningToolResponse<T> = {
+    schemaVersion: typeof CHESS_REASONING_SCHEMA_VERSION;
+    support: ToolSupport;
+    answer: T | null;
+    evidence: EvidenceId[];
+    limitations: string[];
+};

package/dist/types/chess-reasoning/visible-support-lines.d.ts

@@ -0,0 +1,12 @@
+import { type RecordedReferenceLine } from './historical-prose.js';
+import { type ReasoningPositionContext, type ReasoningEvidenceRecord } from './poc-contracts.js';
+/** Expose only a path the answer already explicitly referenced and admission verified. */
+export declare function visibleSupportLines(answer: string, context: ReasoningPositionContext, records: readonly ReasoningEvidenceRecord[], recordedLine?: RecordedReferenceLine): {
+    answer: string;
+    additions: {
+        target: string;
+        label: string;
+        evidenceIds: string[];
+        authority: string;
+    }[];
+};

package/dist/types/chess-reasoning/wikibooks-index.d.ts

@@ -0,0 +1,30 @@
+export type WikibooksIndexData = {
+    v: number;
+    at: string;
+    run: string;
+    extractor: string;
+    entries: string[][];
+};
+export type IndexedOpening = {
+    title: string;
+    canonicalTitle: string;
+    positionKey: string;
+    plies: number;
+};
+export type WikibooksIndex = {
+    at: string;
+    byPath: Map<string, IndexedOpening[]>;
+    byPosition: Map<string, IndexedOpening[]>;
+};
+export declare function openingTitle(moves: string[]): string;
+export declare function decodeWikibooksIndex(data: WikibooksIndexData): WikibooksIndex;
+export declare function positionKey(fen: string): string;
+/** Normalize only title notation; every move must replay legally with its actual side/number. */
+export declare function replayWikibooksTitle(title: string): string | null;
+export type IndexedSelection = {
+    entry: IndexedOpening;
+    requestedTitle: string;
+    ancestorPlies: number;
+    transposition: boolean;
+};
+export declare function selectIndexedOpening(index: WikibooksIndex, title: string, maxAncestorPlies?: number, minSourcePlies?: number): IndexedSelection | null;

package/dist/types/chess-reasoning/wikibooks-tool-context.d.ts

@@ -0,0 +1,10 @@
+import { type WikibooksIndex } from './wikibooks-index.js';
+import { type ReasoningPositionContext, type ReasoningToolResult } from './poc-contracts.js';
+import { type WikibooksTarget } from './opening-source-contracts.js';
+/** Legacy unfiltered planner; production uses the indexed entrypoint below. */
+export declare function wikibooksTargetsForTool(context: ReasoningPositionContext, name: string, args: Record<string, unknown>, result: ReasoningToolResult): WikibooksTarget[];
+export declare function wikibooksTargetsForToolIndexed(context: ReasoningPositionContext, name: string, args: Record<string, unknown>, result: ReasoningToolResult, catalog: WikibooksIndex): {
+    targets: WikibooksTarget[];
+    positionChecks: number;
+    candidateCount: number;
+};

package/dist/types/player-perspective.d.ts

@@ -0,0 +1,16 @@
+export type PlayerPerspective = Readonly<{
+    side: "white" | "black";
+    basis: "linked-lichess-identity" | "chesscom-lookup-handle";
+}>;
+export type PlayerPerspectiveIdentity = Readonly<{
+    provider: string;
+    providerUserId: string;
+    displayName: string;
+}>;
+/** Resolve the current viewer's side without using board orientation or stored game data. */
+export declare function resolvePlayerPerspective(input: {
+    white: string;
+    black: string;
+    providerIdentities?: readonly PlayerPerspectiveIdentity[];
+    chessComLookupHandle?: string;
+}): PlayerPerspective | null;

package/dist/types/shared-exports.d.ts

@@ -0,0 +1,22 @@
+/** Pure host protocol, presentation and error helpers; no model connector or answer loop. */
+export * from './ai-request-failure.js';
+export * from './ai-request-limits.js';
+export * from './ai-routing-diagnostics.js';
+export * from './player-perspective.js';
+export { validateReasoningPositionContext, reasoningContextHash, createContextEvidence, createQueryContract, DEFAULT_REASONING_RUN_CONTROLS, REASONING_POC_VERSION } from './chess-reasoning/poc-contracts.js';
+export { toPositionAnalysis, toLegacyPositionAnalysis, toPositionAnalysisProvider, toLegacyPositionAnalysisProvider } from './chess-reasoning/position-analysis-contracts.js';
+export { simpleProseReferences, SIMPLE_REFERENCE_VERSION, safeSimpleSourceLink, decorateSimpleVariations, repairFrozenCitationLabels, stripSimpleMarkdownFences, stripSimpleCitationLinks } from './chess-reasoning/simple-prose-references.js';
+export { admitFreshEnginePvWitnesses, MAX_FRESH_ENGINE_WITNESS_ACQUISITIONS } from './chess-reasoning/fresh-engine-pv-witnesses.js';
+export { MAX_INTERACTIVE_LINE_PLIES } from './chess-reasoning/reference-limits.js';
+export { recordedMainLineResult } from './chess-reasoning/recorded-main-line.js';
+export { recordedNavigation, historyPositionContext } from './chess-reasoning/recorded-reference-context.js';
+export { classificationTargetAtSelection } from './chess-reasoning/classification-question-target.js';
+export { scopePositionAnalysis } from './chess-reasoning/position-analysis-scope.js';
+export { priorConversationMessages } from './chess-reasoning/conversation-context.js';
+export { parseOpeningSourceCredits, openingSourceLinks, OPENING_SOURCE_LICENSE_URL, openingSourcesInMessages } from './chess-reasoning/opening-source-credits.js';
+export { openingTitle, positionKey, replayWikibooksTitle, selectIndexedOpening, decodeWikibooksIndex } from './chess-reasoning/wikibooks-index.js';
+export { QUESTION_ROUTING_VERSION, classifyQuestionRoutingAnswers, classifyReviewSubject, makeQuestionRoutingRequest, parseQuestionRoutingAnswers, hasMoveClassificationQuestion, moveSectionScope, REVIEW_SUBJECTS } from './chess-reasoning/question-routing.js';
+export { SIMPLE_TOOL_AGENT_VERSION } from './chess-reasoning/simple-runtime-version.js';
+export { SIMPLE_MODEL_CATALOGUE, simpleEffortsForModel, validateSimpleAgentConfig, selectSimpleModel, SIMPLE_EXTENSION_CONFIGS, SIMPLE_VENDOR_CONFIGS, EVALUATED_ASTRA_CONFIG } from './chess-reasoning/simple-agent-config.js';
+export { hasSharedEvidence, expandSharedEvidence, EVIDENCE_SHARING_VERSION, shareEvidence, shareEvidenceMessages } from './chess-reasoning/lossless-evidence-sharing.js';
+export type * from './chess-reasoning/answer-pipeline-exports.js';

package/docs/API.md

@@ -0,0 +1,82 @@
+# Answer pipeline contracts
+
+Connectors return assistant continuation messages with their proposed tool calls.
+Preserve opaque provider continuation metadata in memory. Do not execute proposed
+tools in connectors: the pipeline performs validation, dispatch and result append.
+Cancellation is checked before invocation, after response and around each tool.
+`simpleSystemPolicy` and `simpleToolDescription` expose the existing base policy
+builder. Hosts must deliberately supply their chosen policy; this base builder
+is not a claim of equivalence to the website's currently selected conversational
+policy. Website relay adapters continue injecting the existing server-owned prompt.
+
+Preferred public analyzer lines and conditional segments use `mateInMoves`: signed
+mate distance in moves. Explicit `toPositionAnalysis` / `toLegacyPositionAnalysis`
+adapters retain legacy provider compatibility and reject contradictory aliases.
+Existing versioned trace/evidence outputs keep their historical `matePly` spelling;
+this is not a trace-schema migration. See the publication contract documentation.
+
+All observations and diagnostic events may contain user chess data. Hosts choose
+storage and retention. Published package files contain no recorded study fixtures,
+credentials or private traces. Network and engine work requires an injected port.
+
+Budget behavior is inherited: at most six normal model turns, at most eight
+searches per batch, reserved final composition, plus the existing one-slot
+recovery rules. There is no new aggregate engine-search quota. Connector output
+limits may be requested rather than guaranteed. `usage.outputTokens` retains
+legacy budget accounting; check `reportedOutputTokens` and `metering` before
+reporting measured usage. Missing usage reserves the call allowance and has an
+explicit `outputBudgetReservation`; it is not measured usage or billing.
+
+Requirement KE-AI-PORT-002: `searchesUsed` retains attempted engine dispatch
+accounting, including failures. `searchesSucceeded` and `searchesFailed` report
+completed search outcomes separately. Preparation retains bounded error message,
+code and HTTP status, without stacks or headers. When every completed attempted
+search fails, `engineEvidenceStatus` is `unavailable` and the saved answer plainly
+discloses that engine analysis could not be completed. A successful later search
+clears that all-failed condition. The disclosure precedes final reference validation;
+causal claim and sentence-context ranges remain half-open UTF-16 offsets into
+the returned final answer. Cancellation remains a failure, and answers
+that request no searches are not labelled engine outages. Hosts can mark such
+unavailable answers degraded while retaining the pipeline's `diagnostic` status.
+
+Requirement KE-AI-PORT-003: optional observable traces pair input and output/error
+phase events for routing performed here, opponent preparation, classification
+refresh, observations, evidence construction, and the residual opening wait.
+These events use `deterministic`/`local-harness` identity so model-attempt and
+billing summaries exclude them. `invocationId` joins each pair; terminal
+`durationMs` measures that operation and
+`elapsedMs` is relative to pipeline entry. Opening lookup runs concurrently;
+its wait duration is only the remaining wait after chess evidence collection.
+No event is emitted for an operation that is skipped or routing already supplied
+by the host. Existing preparation/result diagnostics remain unchanged. Failed or
+cancelled operations emit a terminal timing event and preserve the original error
+and cancellation behavior. Phase events never include host error messages,
+credentials or chess payloads. Model/tool intervals remain separately measured;
+do not sum overlapping source lookup and engine intervals.
+
+Requirement KE-AI-PORT-004: hosts can explicitly set `parallelPreparation: true`
+to overlap the two independent ordinary opponent probes and classification refresh
+after routing. The probes retain their original evidence order when they finish
+out of order. At most three upfront searches can overlap with this opt-in.
+The default remains serial, and prepared-board initial searches retain their existing
+refresh order. Both ordinary operations complete before observation collection or
+model invocation. On failure the sibling is cancelled and drained before the
+original failure is propagated; explicit cancellation prevents model dispatch.
+Hosts must provide analyzers that safely support the overlap. `preparationAnalyzer`
+can select a separate provider for ordinary opponent probes only; evidence tools
+and prepared-board initial searches still use `analyzer`. Classification remains
+owned by the history bridge. No search, freshness, score or classification semantics
+are relaxed, and engine outages continue to use the inherited degraded-answer path.
+Overlapping phase durations must not be summed as sequential wall time.
+
+Connector capability metadata declares `toolRequests`, `toolFreeComposition`,
+`opaqueContinuation` booleans; `outputTokenLimit` is `enforced`, `requested` or
+`unavailable`; `usageReporting` is `reported`, `optional` or `unavailable`.
+The interface rejects an entire proposed batch before dispatch if a call ID is
+empty or repeated, a tool is unknown, arguments are not objects, or the batch
+exceeds 32 calls. This is an interface admission ceiling, separate from the
+inherited eight-search batch limit. Detailed chess schema and legality checks
+remain in the canonical tool wrappers and host.
+
+
+See the [pipeline source](../src/chess-reasoning/answer-pipeline.ts) and [connector contract](../src/chess-reasoning/answer-model-connector.ts).

package/docs/OWNERSHIP-ADOPTION.md

@@ -0,0 +1,35 @@
+# AI owner consolidation, 10 October 2026
+
+`OWNERSHIP-DRIFT.json` records SHA-256 hashes before deletion for all eight
+non-identical app/component modules. The app installed `0.1.0-dev.9`; every one
+of those eight installed source files equals component source `0.1.0-dev.11`.
+Thus source dev11's newer behavior was already the application's shipped
+controlled answer pipeline. It is retained deliberately:
+
+| Module | Adoption |
+| --- | --- |
+| answer-pipeline | Intentional ed04bb0 phase timing and be9eedd cancellation-safe opt-in parallel preparation retained; both already shipped in installed dev9. |
+| opponent-threat-preparation | Intentional fea48a8 search outcome accounting and be9eedd opt-in concurrency retained. |
+| poc-contracts | Intentional fea48a8 actual analyzer-outcome callback retained. |
+| poc-tools | Intentional fea48a8 completed search-outcome accounting retained. |
+| portable-answer-runtime | Intentional fea48a8 outage disclosure and 610a27d preserved final reference ranges retained. |
+| simple-evidence-preparation | Intentional fea48a8 failure causes and outcome counts retained. |
+| server-simple-policy | Adopt intentional 610a27d issue #7 correction: both descriptions explicitly require analyzeFinal=true for compareFinalMovesUci. The app retained source missed that migration; no old-wording override remains. System text is unchanged. |
+| simple-prose-references | Upstream intentional app ed87585 / 347f478 / 89cce23 v22 changes: fresh same-answer PV admission and structured gap counts. Their legality/provenance gates and stored-answer version remain intact. |
+
+The fresh-engine-pv-witnesses validator now belongs here with prose references.
+The app's 91 maintained copies (87 reasoning modules and four identical pure top-level helpers) were removed after replacing consumers with
+installed root/research exports. Host adapters, deployment policy variants,
+node/browser providers and active historical research runners remain in the app.
+Their versioned evidence and archived source snapshots were not rewritten.
+
+Classifier version and scoped decision validation are imported from the
+classifier's public `/contracts` entry; this repository no longer owns a second
+classifier-rules or classifier-decision runtime. The dependency is a hash-pinned
+local source-build archive and the packed release names its exact public version.
+
+No widget source fragment or fingerprint, real model run, registry publication,
+commit or push is part of this consolidation. Package checks validate offline
+protocol and evidence behavior, not model answer quality.
+
+The four identical helpers ai-request-failure, ai-request-limits, ai-routing-diagnostics and player-perspective were extracted in bc8f5f2. Their maintained component source now serves all hosts via `/shared`. This entry also provides pure context, reference, recorded-view and routing helpers. Its runtime closure imports only chess.js; the build rejects model SDK or classifier runtime imports. Workspace browser presentation/protocol/client entries use `/shared`, while website browser execution intentionally loads the root pipeline in its execution adapter outside those entries.