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

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

@@ -0,0 +1,68 @@
+import type { ModelMessage, ToolSet, jsonSchema } from 'ai';
+/** A single resumable model turn. No HTTP, account, storage or agent executor assumption. */
+export type AnswerTurnRequest = {
+    system?: string;
+    messages: ModelMessage[];
+    tools: Array<{
+        name: string;
+        description?: string;
+        inputSchema: Parameters<typeof jsonSchema>[0];
+    }>;
+    toolChoice: 'auto' | 'none';
+    maxOutputTokens: number;
+    signal?: AbortSignal;
+    effort: string;
+};
+export type AnswerToolRequest = {
+    toolCallId: string;
+    toolName: string;
+    input: Record<string, unknown>;
+};
+export type AnswerTurnResult = {
+    text: string;
+    toolCalls: AnswerToolRequest[];
+    finishReason: string;
+    usage: {
+        inputTokens?: number;
+        outputTokens?: number;
+    };
+    /** Provider continuation messages; opaque provider metadata must be preserved in memory. */
+    response: {
+        messages: ModelMessage[];
+        headers?: Record<string, string>;
+    };
+    providerMetadata?: unknown;
+};
+export interface AnswerModelConnector {
+    readonly kind: 'model-turn';
+    readonly capabilities?: {
+        toolRequests: boolean;
+        toolFreeComposition: boolean;
+        opaqueContinuation: boolean;
+        outputTokenLimit: 'enforced' | 'requested' | 'unavailable';
+        usageReporting: 'reported' | 'optional' | 'unavailable';
+    };
+    /** Connectors propose calls; only the pipeline executes them. */
+    invoke(request: AnswerTurnRequest): Promise<AnswerTurnResult>;
+}
+export type ExecutableTurn = {
+    system?: string;
+    messages: ModelMessage[];
+    tools?: ToolSet;
+    toolChoice: 'auto' | 'none';
+    maxOutputTokens: number;
+    maxRetries: 0;
+    abortSignal?: AbortSignal;
+    providerOptions: {
+        openai: {
+            store: boolean;
+            include: string[];
+            reasoningEffort: string;
+        };
+    };
+    /** Fixed-evidence evaluation only: validate but discard unsolicited known calls. Never advertised or dispatched. */
+    fixedEvidenceDiscardTools?: ToolSet;
+};
+/** Interface admission ceiling, separate from the inherited search-batch budget. */
+export declare const MAX_ANSWER_TOOL_REQUESTS_PER_TURN = 32;
+export declare function invokeAnswerTurn(connector: AnswerModelConnector, request: ExecutableTurn): Promise<AnswerTurnResult>;

package/dist/types/chess-reasoning/answer-pipeline-exports.d.ts

@@ -0,0 +1,98 @@
+export { runAnswerPipeline } from './answer-pipeline.js';
+export type { AnswerPipelineResult } from './answer-pipeline.js';
+export { runPreparedAnswer, SIMPLE_BUDGETS, SIMPLE_MODELS, SIMPLE_EXPANDED_BUDGETS, SIMPLE_RECOVERY_BUDGETS, validateSimpleToolInput } from './portable-answer-runtime.js';
+export type { SimpleModelOption } from './portable-answer-runtime.js';
+export type { AnswerModelConnector, AnswerTurnRequest, AnswerTurnResult, AnswerToolRequest } from './answer-model-connector.js';
+export { createNativeAnswerConnector } from './native-answer-connector.js';
+export { simpleSystemPolicy, simpleToolDescription } from './server-simple-policy.js';
+export { createPocToolHost } from './answer-tool-host.js';
+export type { AnswerToolHostOptions } from './answer-tool-host.js';
+export type { PositionAnalysisProvider, PositionAnalysisRequest, PositionAnalysisResult, PositionAnalysisLine, PositionAnalysisSegment, CompatiblePositionAnalysisProvider, LegacyPositionAnalysisProvider, LegacyPositionAnalysisResult, LegacyPositionAnalysisLine } from './position-analysis-contracts.js';
+export { toPositionAnalysis, toLegacyPositionAnalysis, toPositionAnalysisProvider, toLegacyPositionAnalysisProvider } from './position-analysis-contracts.js';
+export { createProductionObservationProvider } from './production-observation-provider.js';
+export { validateReasoningPositionContext, reasoningContextHash, createContextEvidence, createQueryContract, DEFAULT_REASONING_RUN_CONTROLS, REASONING_POC_VERSION } from './poc-contracts.js';
+export type { ReasoningPositionContext, ReasoningToolSet, ObservationProvider, ReasoningEvidenceRecord } from './poc-contracts.js';
+export { captureAblationOriginalEvidenceBundle } from './ablation-evidence-capture.js';
+export { createDefaultSaliencePolicy } from './poc-observations.js';
+export { planInitialSearches } from './initial-search-plan.js';
+export { QUESTION_ROUTING_VERSION } from './question-routing.js';
+export type { QuestionRoutingDecision } from './question-routing.js';
+export type { RecordedMainLine } from './answer-host-contracts.js';
+export type { AnswerRoutingPreparation, AnswerSelection, AnswerHistoryPort, AnswerOpeningSession } from './answer-host-contracts.js';
+export { MAX_ANSWER_TOOL_REQUESTS_PER_TURN } from './answer-model-connector.js';
+export type { ReasoningToolResult } from './poc-contracts.js';
+export type { ReasoningObservation } from './poc-contracts.js';
+export type { ReasoningObservationSet } from './poc-contracts.js';
+export type { ReasoningRankedObservationSet } from './poc-contracts.js';
+export type { ReasoningToolDescriptor } from './poc-contracts.js';
+export type { ReasoningToolName } from './poc-contracts.js';
+export type { ModelRuntime } from './poc-contracts.js';
+export type { QueryContract } from './poc-contracts.js';
+export type { ReasoningRunControls } from './poc-contracts.js';
+export type { ReasoningToolExecutionContext } from './poc-contracts.js';
+export type { ReasoningProviderObservationSet } from './poc-contracts.js';
+export { SIMPLE_MODEL_CATALOGUE } from './simple-agent-config.js';
+export { simpleEffortsForModel } from './simple-agent-config.js';
+export type { SimpleAgentConfig } from './simple-agent-config.js';
+export { validateSimpleAgentConfig } from './simple-agent-config.js';
+export type { SimpleModelId } from './simple-agent-config.js';
+export type { SimpleEffort } from './simple-agent-config.js';
+export { hasSharedEvidence } from './lossless-evidence-sharing.js';
+export { expandSharedEvidence } from './lossless-evidence-sharing.js';
+export { EVIDENCE_SHARING_VERSION } from './lossless-evidence-sharing.js';
+export { shareEvidence } from './lossless-evidence-sharing.js';
+export { shareEvidenceMessages } from './lossless-evidence-sharing.js';
+export { PRODUCTION_OBSERVATION_PROVIDER_VERSION } from './production-observation-provider.js';
+export type { SimpleToken } from './simple-prose-references.js';
+export { simpleProseReferences } from './simple-prose-references.js';
+export type { SimpleReference } from './simple-prose-references.js';
+export type { SimplePosition } from './simple-prose-references.js';
+export { safeSimpleSourceLink } from './simple-prose-references.js';
+export type { FreshEnginePvWitness } from './simple-prose-references.js';
+export { SIMPLE_REFERENCE_VERSION } from './simple-prose-references.js';
+export { decorateSimpleVariations } from './simple-prose-references.js';
+export { repairFrozenCitationLabels } from './simple-prose-references.js';
+export { stripSimpleMarkdownFences } from './simple-prose-references.js';
+export { stripSimpleCitationLinks } from './simple-prose-references.js';
+export type { AuthoredReferenceResult } from './simple-prose-references.js';
+export type { SimpleProseReferenceOptions } from './simple-prose-references.js';
+export type { SimpleReferenceGapCounts } from './simple-prose-references.js';
+export type { RecordedMoveAnalysis } from './answer-host-contracts.js';
+export { classifyQuestionRoutingAnswers } from './question-routing.js';
+export { classifyReviewSubject } from './question-routing.js';
+export { makeQuestionRoutingRequest } from './question-routing.js';
+export { parseQuestionRoutingAnswers } from './question-routing.js';
+export { hasMoveClassificationQuestion } from './question-routing.js';
+export { moveSectionScope } from './question-routing.js';
+export { REVIEW_SUBJECTS } from './question-routing.js';
+export { openingTitle } from './wikibooks-index.js';
+export { positionKey } from './wikibooks-index.js';
+export { replayWikibooksTitle } from './wikibooks-index.js';
+export { selectIndexedOpening } from './wikibooks-index.js';
+export type { WikibooksIndex } from './wikibooks-index.js';
+export type { IndexedSelection } from './wikibooks-index.js';
+export { decodeWikibooksIndex } from './wikibooks-index.js';
+export type { WikibooksTarget } from './opening-source-contracts.js';
+export type { WikibooksPage } from './opening-source-contracts.js';
+export type { WikibooksContextResult } from './opening-source-contracts.js';
+export type { WikibooksPlan } from './opening-source-contracts.js';
+export { MAX_INTERACTIVE_LINE_PLIES } from './reference-limits.js';
+export { parseOpeningSourceCredits } from './opening-source-credits.js';
+export type { OpeningSourceCredit } from './opening-source-credits.js';
+export { openingSourceLinks } from './opening-source-credits.js';
+export { OPENING_SOURCE_LICENSE_URL } from './opening-source-credits.js';
+export { openingSourcesInMessages } from './opening-source-credits.js';
+export type { RecordedReferenceLine } from './historical-prose.js';
+export { admitFreshEnginePvWitnesses } from './fresh-engine-pv-witnesses.js';
+export type { FreshEnginePvAdmissionAudit } from './fresh-engine-pv-witnesses.js';
+export { MAX_FRESH_ENGINE_WITNESS_ACQUISITIONS } from './fresh-engine-pv-witnesses.js';
+export { SIMPLE_TOOL_AGENT_VERSION } from './simple-runtime-version.js';
+export { recordedMainLineResult } from './recorded-main-line.js';
+export { classificationTargetAtSelection } from './classification-question-target.js';
+export { scopePositionAnalysis } from './position-analysis-scope.js';
+export { priorConversationMessages } from './conversation-context.js';
+export type { PriorConversationMessage } from './conversation-context.js';
+export { emitObservableTrace } from './ai-sdk-runtime-support.js';
+export type { ObservableLlmTraceSink, ObservableLlmTraceEvent, SanitizedHttpAttempt } from './ai-sdk-runtime-support.js';
+export { selectSimpleModel } from './simple-agent-config.js';
+export { recordedNavigation } from './recorded-reference-context.js';

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

@@ -0,0 +1,41 @@
+import type { AnswerRoutingPreparation, AnswerSelection, AnswerHistoryPort, AnswerOpeningSession } from './answer-host-contracts.js';
+import type { PriorConversationMessage } from "./conversation-context.js";
+import type { SimpleAgentConfig } from "./simple-agent-config.js";
+import { type CompatiblePositionAnalysisProvider } from "./position-analysis-contracts.js";
+import type { ObservationProvider } from "./poc-contracts.js";
+import type { AnswerModelConnector } from "./answer-model-connector.js";
+import type { WikibooksIndex } from "./wikibooks-index.js";
+import { type ObservableLlmTraceSink } from "./ai-sdk-runtime-support.js";
+import { runPreparedAnswer } from "./portable-answer-runtime.js";
+import type { PlayerPerspective } from "../player-perspective.js";
+export type AnswerPipelineResult = Awaited<ReturnType<typeof runPreparedAnswer>> & {
+    arm: "Simple";
+    bundleHash: string;
+};
+export declare function runAnswerPipeline(input: {
+    connector: AnswerModelConnector;
+    policy?: Parameters<typeof runPreparedAnswer>[0]["policy"];
+    modelName?: string;
+    providerRoute?: string;
+    analyzer?: CompatiblePositionAnalysisProvider;
+    /** Optional analyzer for ordinary opponent preparation; later model tools still use analyzer. */
+    preparationAnalyzer?: CompatiblePositionAnalysisProvider;
+    /** Opt in only when the host can safely serve overlapping preparation and classification searches. */
+    parallelPreparation?: boolean;
+    observationProvider: ObservationProvider;
+    prepareRouting: () => Promise<AnswerRoutingPreparation>;
+    openingSession?: AnswerOpeningSession;
+    openingIndex?: () => Promise<WikibooksIndex>;
+    routingPreparation?: AnswerRoutingPreparation;
+    conversationHistory?: readonly PriorConversationMessage[];
+    simpleConfig?: SimpleAgentConfig;
+    simpleAllowance?: "default" | "expanded" | "glm-recovery";
+    requestId: string;
+    question: string;
+    playerPerspective?: PlayerPerspective | null;
+    selected: AnswerSelection;
+    bridge?: AnswerHistoryPort;
+    signal?: AbortSignal;
+    observableTraceSink?: ObservableLlmTraceSink;
+    onProgress?: (message: string) => void;
+}): Promise<AnswerPipelineResult>;

package/dist/types/chess-reasoning/answer-reference-validation.d.ts

@@ -0,0 +1,40 @@
+import type { RecordedReferenceLine } from './historical-prose.js';
+import type { ReasoningPositionContext, ReasoningEvidenceRecord } from './poc-contracts.js';
+/** Deterministic presentation repair, never new analytical evidence. */
+export declare function validateAnswerReferences(answer: string, context: ReasoningPositionContext, records: readonly ReasoningEvidenceRecord[], recordedLine?: RecordedReferenceLine): {
+    answer: 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;
+    };
+};

package/dist/types/chess-reasoning/answer-tool-host.d.ts

@@ -0,0 +1,8 @@
+import { type PocToolHostOptions } from './poc-tools.js';
+import type { ReasoningPositionContext } from './poc-contracts.js';
+import { type CompatiblePositionAnalysisProvider } from './position-analysis-contracts.js';
+export type AnswerToolHostOptions = Omit<PocToolHostOptions, 'analyzer'> & {
+    analyzer?: CompatiblePositionAnalysisProvider;
+};
+/** Public analyzer contract; the existing evidence protocol retains its versioned legacy spelling. */
+export declare function createPocToolHost(context: ReasoningPositionContext, options?: AnswerToolHostOptions): import("./poc-contracts.js").ReasoningToolSet;

package/dist/types/chess-reasoning/branch-expansion-policy.d.ts

@@ -0,0 +1,13 @@
+import type { BranchExpansionConfig } from './branch-expansion.js';
+import type { InitialSearchPlan } from './initial-search-plan.js';
+import type { ReasoningPositionContext, ReasoningToolSet } from './poc-contracts.js';
+export type BranchExpansionMode = 'off' | 'preparation' | 'tools' | 'both';
+export declare const BRANCH_EXPANSION_OPTIONS: BranchExpansionConfig;
+export declare const DEFAULT_BRANCH_EXPANSION_MODE: BranchExpansionMode;
+/** Add a registered actual-after search without replacing hypothetical eager leads.
+ * Selected-context retention is the authority; omitted historical questions must
+ * acquire their explicit root through ordinary tools. No natural-language guesses. */
+export declare function withBranchPreparation(plan: InitialSearchPlan, context: ReasoningPositionContext, omitSelectedContext: boolean, mode: BranchExpansionMode): InitialSearchPlan;
+/** Both hosts keep the same contracts. Only internally generated initial calls
+ * select the preparation arm; user/model tool schemas cannot alter this setting. */
+export declare function selectBranchHost(ordinary: ReasoningToolSet, expanded: ReasoningToolSet, mode: BranchExpansionMode): ReasoningToolSet;

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

@@ -0,0 +1,39 @@
+import type { PositionAnalysisLine } from './poc-tools.js';
+export type BranchExpansionConfig = {
+    maxNodes: number;
+    maxPlies: number;
+    maxLines: number;
+    depthFloor: number;
+    depthMode: 'fixed' | 'decreasing';
+    maxElapsedMs?: number;
+};
+export type BranchNode<T> = {
+    prefix: string[];
+    finalFen: string;
+    analysis: T;
+};
+export type BranchExpansionResult<T> = {
+    nodes: BranchNode<T>[];
+    summary: {
+        requestedNodes: number;
+        searchedNodes: number;
+        returnedNodes: number;
+        skippedDuplicate: number;
+        skippedInvalid: number;
+        failedNodes: number;
+        stopped: 'complete' | 'node-limit' | 'elapsed-limit';
+        scope: string;
+    };
+};
+/** Only the original PVs are traversed. New alternatives are retained, never
+ * recursively scheduled. Each node is an independent FEN-root search. */
+export declare function expandPrincipalBranches<T extends {
+    lines: PositionAnalysisLine[];
+}>(input: {
+    rootFen: string;
+    lines: readonly PositionAnalysisLine[];
+    parentDepth: number;
+    config: BranchExpansionConfig;
+    signal?: AbortSignal;
+    search: (fen: string, depth: number) => Promise<T | null>;
+}): Promise<BranchExpansionResult<T>>;

package/dist/types/chess-reasoning/causal-claim-checks.d.ts

@@ -0,0 +1,21 @@
+import { type RecordedReferenceLine } from './historical-prose.js';
+import type { ReasoningEvidenceRecord, ReasoningPositionContext } from './poc-contracts.js';
+export type CausalClaimCheck = {
+    claim: string;
+    /** Half-open UTF-16 offsets into the final reference-repaired answer. */
+    claimRange: {
+        start: number;
+        end: number;
+    };
+    sentenceContext: {
+        text: string;
+        start: number;
+        end: number;
+    };
+    reference: string;
+    predicate: 'moving-piece-escape' | 'stationary-slider-ray' | 'square-control-release';
+    verdict: 'supported' | 'contradicted' | 'unresolved';
+    reason: string;
+};
+/** Bounded geometry diagnostics only. No answer modification, strategic judgment or intent inference. */
+export declare function checkCausalClaims(answer: string, context: ReasoningPositionContext, records: readonly ReasoningEvidenceRecord[], recordedLine?: RecordedReferenceLine): CausalClaimCheck[];

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

@@ -0,0 +1,13 @@
+/** Stable, position-independent geometry. a1 is dark, regardless of orientation. */
+export type SquareColor = 'light' | 'dark';
+export declare function chessSquareColor(square: string): SquareColor | null;
+/** Grouping is a complete square->colour dictionary without 64 repeated keys. */
+export declare const CHESS_REFERENCE_DICTIONARY: Readonly<{
+    version: "square-colors-v1";
+    scope: "Position-independent square colors; not piece ownership or a position assessment.";
+    squareColors: Readonly<{
+        light: readonly string[];
+        dark: readonly string[];
+    }>;
+    use: "A bishop occupies squares of its color complex. Identify the bishop and the relevant position before applying this reference; do not infer which bishop a move frees from square colors alone.";
+}>;

package/dist/types/chess-reasoning/classification-question-target.d.ts

@@ -0,0 +1,22 @@
+import type { ReasoningPositionContext } from './poc-contracts.js';
+import { type QuestionRoutingDecision } from './question-routing.js';
+/** Question-only notation extraction; these are references, not verified moves. */
+export declare function classificationQuestionMoveReferences(question: string): {
+    san: string;
+    moveNumber: number | null;
+    color: string | null;
+}[];
+/** Resolve wording against frozen context AFTER Jev; never change board selection. */
+export declare function classificationTargetAtSelection(decision: QuestionRoutingDecision, question: string, context: ReasoningPositionContext): {
+    applies: boolean;
+    resolution: string;
+    references?: undefined;
+} | {
+    applies: boolean;
+    resolution: string;
+    references: {
+        san: string;
+        moveNumber: number | null;
+        color: string | null;
+    }[];
+};

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

@@ -0,0 +1,31 @@
+import type { SimpleBoardAnalysis } from './simple-board-analysis.js';
+/** Preserve decision provenance without repeating the full board-analysis snapshots. */
+export declare function classificationReassessment(previous: SimpleBoardAnalysis | undefined, current: SimpleBoardAnalysis | undefined): {
+    limitation: string;
+    current?: {
+        role: "previous-analysis" | "current-analysis";
+        evidenceId: string;
+        classification: string | null;
+        lossCp: number | null;
+        recordedRequestedDepth: number | null;
+        beforeDepth: number | null;
+        afterDepth: number | null;
+    } | undefined;
+    previous?: {
+        recordedReason?: {} | null | undefined;
+        superseded?: boolean | undefined;
+        supersededBy?: string | undefined;
+        role: "previous-analysis" | "current-analysis";
+        evidenceId: string;
+        classification: string | null;
+        lossCp: number | null;
+        recordedRequestedDepth: number | null;
+        beforeDepth: number | null;
+        afterDepth: number | null;
+    } | undefined;
+    version: string;
+    status: string;
+    labelChanged: boolean;
+    preparationRequestedDepth: number;
+};
+export declare const CLASSIFICATION_REASSESSMENT_GUIDANCE = "For questions that include the selected move's classification, Knight's Eye may prepare a deeper before-position search and refresh the board's canonical classification before answering. classificationReassessment contains compact decision summaries: the current full analysis is in boardAnalysis; previous is an attributed historical summary, superseded only for a matching current context. retrieve_evidence with the previous evidenceId restores omitted historical details when needed. preparationRequestedDepth names the preparation request, not the recorded depth of either decision. When classificationReassessment.status is changed and labelChanged is true, acknowledge the change explicitly in first-person Knight's Eye language, for example: \u201CI had a better look at this move and changed its classification from Great to Best because \u2026\u201D. Use the previous recordedReason and the current boardAnalysis decision details to explain the supported reason. Distinguish why we originally assigned the old label from why the refreshed decision differs; do not defend an outdated label as the current one. A changed score with an unchanged label is not a classification change. If the original or current decision, its reason, or the search is unavailable, state the material uncertainty and never invent a change or explanation. A recorded candidate-gap flag is a bounded policy signal, not proof that only one move preserves a favorable position.";

package/dist/types/chess-reasoning/compact-search-preparation.d.ts

@@ -0,0 +1,7 @@
+import type { MaterialFormat } from './material-format.js';
+import type { ReasoningEvidenceRecord, ReasoningToolResult } from './poc-contracts.js';
+/** The initial projection must not silently discard a new engine field. */
+export declare function compactSearchRecord(record: ReasoningEvidenceRecord, playedMove?: string): ReasoningEvidenceRecord | null;
+/** Only automatic preparation is thinned. The caller keeps the original tool
+ * result in its evidence ledger and observable trace for retrieval/replay. */
+export declare function compactPreparedSearchResult(result: ReasoningToolResult, playedMove?: string, format?: MaterialFormat): unknown;

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

@@ -0,0 +1,99 @@
+import type { ConceptKey, RegistryKey, SemanticCandidate, SemanticEntity, SemanticParticipant, SemanticValue } from "./types.js";
+export declare const ENTITY_TYPES: {
+    readonly IDEA: "idea";
+    readonly PLAN: "plan";
+    readonly ROLE: "role-assignment";
+    readonly CONDITION: "condition";
+    readonly TRANSFORMATION: "transformation";
+    readonly OUTCOME: "outcome";
+};
+export declare const REFERENCE_DOMAINS: {
+    readonly PIECE: "piece";
+    readonly SQUARE: "square";
+    readonly MOVE: "move";
+    readonly POSITION: "position";
+    readonly OUTCOME: "outcome";
+    readonly ENTITY: "entity";
+};
+export declare const PARTICIPANT_ROLES: {
+    readonly ACTOR: "actor";
+    readonly SUBJECT: "subject";
+    readonly TARGET: "target";
+    readonly GOAL: "goal";
+    readonly RESOURCE: "resource";
+    readonly DEFENDER: "defender";
+    readonly DESTINATION: "destination";
+};
+export declare const ATTRIBUTE_KEYS: {
+    readonly ACCEPTING_MOVES: "acceptingMoves";
+    readonly PROPOSAL_REASONS: "proposalReasons";
+    readonly DESCRIPTION: "description";
+    readonly CONFIDENCE_NOTE: "confidenceNote";
+};
+export declare const RELATION_TYPES: {
+    readonly SUPPORTS: "supports";
+    readonly COMPETES: "competes";
+    readonly DERIVES: "derives";
+    readonly SPLITS: "splits";
+    readonly CONVERGES: "converges";
+    readonly ENABLES: "enables";
+    readonly REQUIRES: "requires";
+    readonly REFUTES: "refutes";
+    readonly EXPLAINS: "explains";
+    readonly TRANSFORMS: "transforms";
+};
+/**
+ * These are registry values, not members of the entity schema. New concepts
+ * may be registered without changing `SemanticCandidate` or `SemanticEntity`.
+ */
+export declare const CONCEPT_KEYS: {
+    readonly OFFER: "material.offer";
+    readonly MATERIAL_CLAIM: "material.claim";
+    readonly FORK: "tactic.fork";
+    readonly TRAPPED_TARGET: "tactic.trapped-target";
+    readonly PROMOTION: "tactic.promotion";
+    readonly MATING_ATTACK: "attack.mating";
+    readonly PERPETUAL_CHECK: "attack.perpetual-check";
+    readonly POSITIONAL_CLAIM: "position.claim";
+    readonly KING_ATTACK_PLAN: "plan.king-attack";
+    readonly PIECE_ROLE: "role.piece-function";
+    readonly CHANGED_CONSTRAINT: "condition.changed-constraint";
+    readonly POSITIONAL_TRANSFORMATION: "position.transformation";
+};
+export type CaptureActor = "owner" | "opponent" | "either";
+export type ConceptLifecycle = {
+    initialState: RegistryKey;
+    retainedState: RegistryKey;
+    terminalStates: RegistryKey[];
+    trackedParticipantRole?: RegistryKey;
+    expireWhenTrackedUnavailable?: boolean;
+    onTrackedCapture?: {
+        capturedBy: CaptureActor;
+        matchingState: RegistryKey;
+        matchingAnnotation: RegistryKey;
+        otherState: RegistryKey;
+        otherAnnotation: RegistryKey;
+    };
+};
+export type ConceptDefinition = {
+    key: ConceptKey;
+    label: string;
+    category: RegistryKey;
+    description: string;
+    defaultEntityType: RegistryKey;
+    acceptancePolicy?: RegistryKey;
+    lifecycle?: ConceptLifecycle;
+};
+export type ConceptRegistry = Readonly<Record<ConceptKey, Readonly<ConceptDefinition>>>;
+export declare function createConceptRegistry(definitions: ConceptDefinition[]): ConceptRegistry;
+export declare function extendConceptRegistry(registry: ConceptRegistry, definitions: ConceptDefinition[]): ConceptRegistry;
+export declare function conceptDefinition(registry: ConceptRegistry, key: ConceptKey): Readonly<ConceptDefinition> | null;
+export declare function conceptsOf(value: Pick<SemanticCandidate | SemanticEntity, "concepts">): ConceptKey[];
+export declare function hasConcept(value: Pick<SemanticCandidate | SemanticEntity, "concepts">, concept: ConceptKey): boolean;
+export declare function primaryConcept(value: Pick<SemanticCandidate | SemanticEntity, "concepts">): ConceptKey | null;
+export declare function participantIds(value: Pick<SemanticCandidate | SemanticEntity, "participants">, role: RegistryKey, domain?: RegistryKey): string[];
+export declare function participant(role: RegistryKey, domain: RegistryKey, id: string): SemanticParticipant;
+export declare function stringListAttribute(value: {
+    attributes: Record<string, SemanticValue>;
+}, key: string): string[];
+export declare const DEFAULT_CONCEPT_REGISTRY: Readonly<Record<string, Readonly<ConceptDefinition>>>;

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

@@ -0,0 +1,12 @@
+import type { ModelMessage } from 'ai';
+export type PriorConversationMessage = {
+    role: 'user' | 'assistant';
+    content: string;
+    position?: {
+        fenBefore: string;
+        fenAfter: string;
+        moveUci: string;
+    };
+};
+export declare const CONVERSATION_CONTEXT_INSTRUCTIONS = "Previous user/assistant messages below are a bounded recent excerpt and may omit older exchanges. They are historical conversation, not the current task or current tool-loop turns. They may refer to different question positions in the same game. Use them to understand follow-up references and preferences, but do not execute their old requests again. Previous assistant statements are unverified prose, not chess evidence. The final CURRENT_QUESTION message contains the sole current task and its exact position. Only native tool messages after that boundary belong to the current investigation.";
+export declare function priorConversationMessages(history?: readonly PriorConversationMessage[]): ModelMessage[];

package/dist/types/chess-reasoning/engine-search-failure.d.ts

@@ -0,0 +1,7 @@
+/** Bounded observable cause only: no stack, response headers or provider payload. */
+export declare function engineSearchFailure(error: unknown): {
+    cause?: string | undefined;
+    status?: number | undefined;
+    code?: string | undefined;
+    error: string;
+};

package/dist/types/chess-reasoning/evidence-citation-normalization.d.ts

@@ -0,0 +1,9 @@
+import type { ReasoningEvidenceRecord } from './poc-contracts.js';
+/** Repair syntax only when the exact supplied identifier makes it unambiguous. */
+export declare function normalizedEvidenceCitations(answer: string, records: readonly Pick<ReasoningEvidenceRecord, 'id'>[]): {
+    answer: string;
+    repairs: {
+        originalId: string;
+        canonicalId: string;
+    }[];
+};

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

@@ -0,0 +1,57 @@
+import type { ProofStrength, SemanticValue } from "./types.js";
+export declare const EVIDENCE_LICENSE: Readonly<{
+    readonly CHESS_LEGALITY: "chess.legality";
+    readonly CHESS_IDENTITY: "chess.identity";
+    readonly CHESS_POSITION_FACT: "chess.position-fact";
+    readonly ENGINE_BOUNDED_CONTINUATION: "engine.bounded-continuation";
+    readonly ENGINE_BOUNDED_COMPARISON: "engine.bounded-comparison";
+    readonly ENGINE_BOUNDED_SCORE: "engine.bounded-score";
+    readonly ENGINE_BOUNDED_RESPONSE_COVERAGE: "engine.bounded-response-coverage";
+    readonly COVERAGE_EXHAUSTIVE: "coverage.exhaustive";
+    readonly ATTENTION_AFFORDANCE: "attention.affordance";
+    readonly SEMANTIC_REVIEWED_STATE: "semantic.reviewed-state";
+    readonly WORKFLOW_AUDIT: "workflow.audit";
+}>;
+export type EvidenceLicense = typeof EVIDENCE_LICENSE[keyof typeof EVIDENCE_LICENSE];
+export type EvidenceLicenseInput = {
+    kind: string;
+    source: string;
+    authority: string | null;
+    proofStrength: ProofStrength | null;
+    data: Record<string, SemanticValue>;
+    coverage: {
+        complete: boolean;
+        covered: string[];
+        unresolved: string[];
+    } | null;
+    replay: Record<string, SemanticValue> | null;
+};
+export type LicensableEvidenceRecord = {
+    kind: string;
+    source: string;
+    proofStrength: ProofStrength | null;
+    licenses?: EvidenceLicense[];
+    data: Record<string, SemanticValue>;
+    coverage: {
+        complete: boolean;
+        covered: string[];
+        unresolved: string[];
+    } | null;
+    replay: Record<string, SemanticValue> | null;
+};
+export declare function evidenceLicenseInput(record: LicensableEvidenceRecord): EvidenceLicenseInput;
+/**
+ * Central maximum-license policy. A producer may claim any subset of these
+ * values, but no producer can broaden its source by adding a license.
+ */
+export declare function maximumEvidenceLicenses(input: EvidenceLicenseInput): EvidenceLicense[];
+export declare function validateEvidenceLicenseClaims(input: EvidenceLicenseInput, claimed: readonly unknown[]): EvidenceLicense[];
+export declare function effectiveEvidenceLicenses(input: EvidenceLicenseInput & {
+    licenses?: readonly unknown[];
+}): EvidenceLicense[];
+export declare function effectiveLicensesForRecord(record: LicensableEvidenceRecord): EvidenceLicense[];
+export declare function withEvidenceLicenses<T extends LicensableEvidenceRecord>(record: T): T & {
+    licenses: EvidenceLicense[];
+};
+export declare function licensesSemanticChessGrounding(licenses: readonly EvidenceLicense[]): boolean;
+export declare function licensesBoundedRouteRelevance(licenses: readonly EvidenceLicense[]): boolean;

package/dist/types/chess-reasoning/evidence-selector-contract.d.ts

@@ -0,0 +1,5 @@
+export type LeanDirectEvidenceSelector = Readonly<{
+    id: string;
+    factKinds?: readonly string[];
+    observationTypes?: readonly string[];
+}>;