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

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

@@ -0,0 +1,1026 @@
+import { type EvidenceLicense } from "./evidence-licenses.js";
+import type { ProofStrength, SemanticAttributes, SemanticEntity, SemanticParticipant, SemanticRelation, SemanticValue } from "./types.js";
+export declare const REASONING_POC_VERSION: "conceptual-explanation-poc/57";
+export declare const REASONING_POC_MAX_OUTPUT_TOKENS = 2000;
+export declare const REASONING_POC_MAX_HYPOTHESIS_OUTPUT_TOKENS = 4000;
+export declare const REASONING_POC_MAX_CRITIC_OUTPUT_TOKENS = 7000;
+export declare const REASONING_POC_MAX_TERMINAL_REVIEW_OUTPUT_TOKENS = 4000;
+export declare const REASONING_POC_MAX_RESOLUTION_AUDIT_OUTPUT_TOKENS = 3000;
+/**
+ * The optional future-purpose planner may choose one already-supported,
+ * bounded probe. It never writes semantic hypotheses, so it gets a smaller
+ * transport budget than the hypothesis and critic stages.
+ */
+export declare const REASONING_POC_MAX_PURPOSE_PROBE_OUTPUT_TOKENS = 1500;
+export declare const REASONING_POC_MAX_GRAPH_SELECTION_OUTPUT_TOKENS = 2000;
+export declare const REASONING_POC_MAX_DISCOURSE_OUTPUT_TOKENS = 2500;
+export declare const REASONING_POC_MAX_RENDER_OUTPUT_TOKENS = 4000;
+export declare const REASONING_POC_MAX_HYPOTHESIS_BATCHES = 2;
+export declare const REASONING_POC_RESERVED_MANDATORY_STEPS = 11;
+export declare const REASONING_POC_REVISION_EVIDENCE_ALLOWANCE = 1;
+/** One opt-in slot for the bounded future-purpose planner; base profiles stay unchanged. */
+export declare const REASONING_POC_PURPOSE_PROBE_ALLOWANCE = 1;
+/** One opt-in slot for a complete replacement of structurally invalid critic output. */
+export declare const REASONING_POC_CRITIC_CORRECTION_ALLOWANCE = 1;
+export type ReasoningPositionContext = {
+    kind?: "position";
+    nodeId: string;
+    parentNodeId?: string;
+    historyStartFen?: string;
+    fenBefore: string;
+    fenAfter: string;
+    historyUci: string[];
+    moveUci: string;
+    moveSan: string;
+};
+export type ReasoningAudience = "beginner" | "intermediate" | "advanced";
+export type ReasoningGraphRequirements = {
+    minimumEntities: number;
+    minimumRelations: number;
+};
+export type QueryContract = {
+    schemaVersion: typeof REASONING_POC_VERSION;
+    requestId: string;
+    question: string;
+    requestedConclusion: "move-idea" | "position-question";
+    responseCoverageRequirement: "none" | "bounded-class";
+    continuationCoverageRequirement: "none" | "principal-variation";
+    minimumContinuationLines: number;
+    graphRequirements: ReasoningGraphRequirements;
+    audience: ReasoningAudience;
+    concise: boolean;
+    nodeId: string;
+};
+export type ReasoningRunControls = {
+    maxModelSteps: number;
+    maxToolCalls: number;
+    maxProbeCalls: number;
+    maxEvidenceRecords: number;
+    maxObservationRecords: number;
+    maxObservationsPresented: number;
+    maxHypotheses: number;
+    maxOutputChars: number;
+    maxProviderOutputChars: number;
+    maxWallTimeMs: number;
+};
+export declare const DEFAULT_REASONING_RUN_CONTROLS: Readonly<ReasoningRunControls>;
+export type ReasoningEvidenceKind = "context" | "fact" | "probe" | "graph" | "observation-review" | "reasoning-challenge" | "hypothesis-review" | "critic-resolution-audit";
+export type ReasoningEvidenceRecord = {
+    schemaVersion: typeof REASONING_POC_VERSION;
+    id: string;
+    contextHash: string;
+    kind: ReasoningEvidenceKind;
+    source: string;
+    proofStrength: ProofStrength | null;
+    licenses?: EvidenceLicense[];
+    summary: string;
+    data: Record<string, SemanticValue>;
+    coverage: {
+        complete: boolean;
+        covered: string[];
+        unresolved: string[];
+    } | null;
+    replay: Record<string, SemanticValue> | null;
+};
+export type ReasoningToolName = "finish_evidence_collection" | "review_observations" | "challenge_reasoning" | "record_hypotheses" | "review_hypotheses" | "finalize_reasoning_review" | "audit_critic_resolutions" | "analyze_game_position" | "test_game_line" | "inspect_position" | "analyze_move" | "explore_continuations" | "compare_moves" | "enumerate_defenses" | "test_line" | "trace_idea" | "explain_plan";
+export type ReasoningToolSupport = "supported" | "insufficient-evidence" | "unsupported";
+export type ReasoningToolResult = {
+    schemaVersion: typeof REASONING_POC_VERSION;
+    callId: string;
+    tool: ReasoningToolName;
+    contextHash: string;
+    support: ReasoningToolSupport;
+    data: Record<string, SemanticValue>;
+    evidence: ReasoningEvidenceRecord[];
+    limitations: string[];
+    durationMs: number;
+};
+export type ReasoningToolDescriptor = {
+    name: ReasoningToolName;
+    description: string;
+    category: "fact" | "probe" | "graph";
+    inputSchema: Record<string, unknown>;
+};
+export interface ReasoningToolSet {
+    /** Native hosts reserve engine slots after legality checks, at dispatch. */
+    reservesSearchAtDispatch?: boolean;
+    descriptors(): ReasoningToolDescriptor[];
+    execute(name: ReasoningToolName, input: Record<string, unknown>, signal?: AbortSignal, execution?: ReasoningToolExecutionContext): Promise<ReasoningToolResult>;
+    seedEvidence?(records: Iterable<ReasoningEvidenceRecord>): void;
+}
+export type ReasoningHypothesisProvenance = {
+    provider: string;
+    version: string;
+    origin: "model" | "learned-provider" | "reviewed-annotation" | "user";
+};
+export type ReasoningToolExecutionContext = {
+    hypothesisProvenance?: ReasoningHypothesisProvenance;
+    /** Reserve an answer-budgeted engine search after input/legality validation. */
+    reserveSearch?: () => boolean;
+    /** Reserve one answer-budgeted engine search before a PV endpoint continuation. */
+    reserveAdditionalSearch?: () => boolean;
+    /** Actual completed analyzer outcome; failed dispatches still consume attempts. */
+    recordSearchOutcome?: (outcome: 'succeeded' | 'failed') => void;
+};
+export type ReasoningProbeRecipe = {
+    tool: "inspect_position" | "analyze_move" | "enumerate_defenses" | "test_line";
+    input: Record<string, SemanticValue>;
+    purpose: string;
+};
+export type ReasoningObservation = {
+    schemaVersion: typeof REASONING_POC_VERSION;
+    id: string;
+    contextHash: string;
+    observationType: string;
+    participants: SemanticParticipant[];
+    attributes: Record<string, SemanticValue>;
+    exactness: "exact" | "heuristic";
+    provenance: {
+        provider: string;
+        version: string;
+        trust: "deterministic" | "learned" | "external";
+        methods: string[];
+    };
+    factEvidenceIds: string[];
+    probeRecipes: ReasoningProbeRecipe[];
+};
+export type ReasoningObservationSet = {
+    schemaVersion: typeof REASONING_POC_VERSION;
+    contextHash: string;
+    observations: ReasoningObservation[];
+    evidence: ReasoningEvidenceRecord[];
+    providers: Array<{
+        provider: string;
+        version: string;
+    }>;
+    limitations: string[];
+};
+export type ReasoningRankedObservation = ReasoningObservation & {
+    salience: number;
+    salienceReasons: string[];
+    presentedToModel: boolean;
+};
+export type ReasoningRankedObservationSet = Omit<ReasoningObservationSet, "observations"> & {
+    observations: ReasoningRankedObservation[];
+    saliencePolicy: string;
+};
+/**
+ * The model-facing observation catalogue deliberately excludes the embedded
+ * evidence array. Evidence is transmitted once, through the separately
+ * licensed `evidence` field on HypothesisProviderInput. Keeping this shape
+ * explicit prevents an omitted observation or a duplicate evidence payload
+ * from leaking back into an isolated semantic stage.
+ */
+export type ReasoningProviderObservationSet = Omit<ReasoningRankedObservationSet, "observations" | "evidence"> & {
+    observations: Array<Pick<ReasoningRankedObservation, "id" | "observationType" | "participants" | "attributes" | "exactness" | "provenance" | "factEvidenceIds" | "probeRecipes" | "salience" | "salienceReasons" | "presentedToModel">>;
+};
+export interface ObservationProvider {
+    readonly id: string;
+    readonly version: string;
+    observe(context: ReasoningPositionContext, controls: ReasoningRunControls, signal?: AbortSignal): Promise<ReasoningObservationSet> | ReasoningObservationSet;
+}
+export interface SaliencePolicy {
+    readonly id: string;
+    rank(observations: ReasoningObservationSet, contract: QueryContract, graphContext?: Record<string, SemanticValue>): ReasoningRankedObservationSet;
+}
+export type ReasoningHypothesisRelationProposal = {
+    relationType: string;
+    from: string;
+    to: string;
+    attributes: SemanticAttributes;
+    evidenceIds: string[];
+    sourceObservationIds: string[];
+};
+export type HypothesisProviderInput = {
+    mode: "initial" | "revision";
+    correction?: {
+        attempt: 1;
+        rejectionStage: string;
+        rejectionCode: string;
+        rejectionDetails: string;
+        previousInvalidBatch: {
+            hypotheses: ReasoningHypothesisProposal[];
+            relations: ReasoningHypothesisRelationProposal[];
+        };
+        instruction: string;
+    };
+    revisionObligations: {
+        minimumNewHypotheses: 1;
+        reopenedGaps: Array<Pick<ReasoningChallengeDecision["observationAudits"][number], "observationId" | "missingLink" | "omissionImpact" | "representedHypothesisIds">>;
+        novelHypothesisNeeded: boolean;
+        questionCoverageRationale: string;
+        hypothesisFindings: ReasoningCriticFinding[];
+    } | null;
+    contract: QueryContract;
+    context: ReasoningPositionContext;
+    observations: ReasoningProviderObservationSet;
+    evidence: Array<Pick<ReasoningEvidenceRecord, "id" | "kind" | "source" | "proofStrength" | "licenses" | "summary" | "data" | "coverage" | "replay">>;
+    existingHypotheses: Array<Pick<ReasoningHypothesisRecord, "id" | "localId" | "entityType" | "concepts" | "owner" | "participants" | "attributes" | "proofStrength" | "evidenceIds" | "sourceObservationIds" | "parentHypothesisIds" | "anchorRequirements" | "origin" | "provenance" | "status">>;
+    existingRelations: Array<Pick<ReasoningHypothesisRelationRecord, "id" | "relationType" | "fromHypothesisId" | "toHypothesisId" | "attributes" | "evidenceIds" | "sourceObservationIds">>;
+    challenge: ReasoningChallengeDecision | null;
+    inspectionLenses: {
+        version: string;
+        authority: "non-evidentiary";
+        items: Array<{
+            id: string;
+            families: string[];
+            text: string;
+        }>;
+    };
+    allowedVocabulary: {
+        entityTypes: string[];
+        concepts: string[];
+        relationTypes: string[];
+        participantRoles: string[];
+    };
+    allowedEvidenceIds: string[];
+    allowedReferences: Array<{
+        domain: string;
+        id: string;
+    }>;
+    maxOutputTokens: number;
+};
+export type HypothesisProviderResult = {
+    batch: {
+        hypotheses: ReasoningHypothesisProposal[];
+        relations: ReasoningHypothesisRelationProposal[];
+    };
+    provenance: ReasoningHypothesisProvenance;
+    steps?: number;
+    usage?: {
+        inputTokens: number | null;
+        outputTokens: number | null;
+    };
+    diagnostics?: ReasoningRuntimeDiagnostic[];
+};
+export interface HypothesisProvider {
+    readonly id: string;
+    readonly version: string;
+    propose(input: HypothesisProviderInput, signal?: AbortSignal): Promise<HypothesisProviderResult>;
+}
+export type ReasoningAnchorRequirement = {
+    participant: SemanticParticipant;
+    disposition: "required";
+};
+export type ReasoningHypothesisProposal = {
+    localId: string;
+    entityType: string;
+    concepts: string[];
+    owner: "w" | "b" | null;
+    participants: SemanticParticipant[];
+    attributes: SemanticAttributes;
+    proofStrength: ProofStrength | null;
+    evidenceIds: string[];
+    sourceObservationIds: string[];
+    parentHypothesisIds: string[];
+    anchorRequirements: ReasoningAnchorRequirement[];
+};
+export type ReasoningHypothesisStatus = "proposed" | "needs-probe" | "accepted" | "rejected" | "superseded";
+export type ReasoningHypothesisRecord = ReasoningHypothesisProposal & {
+    schemaVersion: typeof REASONING_POC_VERSION;
+    id: string;
+    contextHash: string;
+    origin: "model" | "learned-provider" | "reviewed-annotation" | "user";
+    provenance: {
+        provider: string;
+        version: string;
+    };
+    status: ReasoningHypothesisStatus;
+    review: {
+        rationale: string;
+        supersededBy: string[];
+    } | null;
+};
+export type ReasoningHypothesisRelationRecord = {
+    schemaVersion: typeof REASONING_POC_VERSION;
+    id: string;
+    contextHash: string;
+    relationType: string;
+    fromHypothesisId: string;
+    toHypothesisId: string;
+    attributes: SemanticAttributes;
+    evidenceIds: string[];
+    sourceObservationIds: string[];
+};
+export type ReasoningHypothesisDecision = {
+    hypothesisId: string;
+    disposition: "accept" | "reject" | "needs-probe" | "supersede";
+    rationale: string;
+    supersededBy: string[];
+};
+export type ReasoningObservationDispositionState = "used" | "irrelevant" | "duplicate" | "needs-probe" | "unaddressed" | "deferred-by-harness-budget" | "not-presented-to-model";
+export type ReasoningObservationDecision = {
+    observationId: string;
+    disposition: "used" | "irrelevant" | "duplicate" | "needs-probe";
+    rationale: string;
+    hypothesisIds: string[];
+    duplicateOfObservationId: string | null;
+    probeCallIds: string[];
+};
+export type ReasoningObservationCoverage = {
+    observationId: string;
+    state: ReasoningObservationDispositionState;
+    rationale: string | null;
+    hypothesisIds: string[];
+    duplicateOfObservationId: string | null;
+    probeCallIds: string[];
+};
+export type ReasoningChallengeObservationAudit = {
+    observationId: string;
+    action: "retain" | "reopen";
+    rationale: string;
+    missingLink: string | null;
+    omissionImpact: "preserves-conclusion" | "weakens-conclusion" | "uncertain";
+    representedHypothesisIds: string[];
+};
+export type ReasoningCriticFindingKind = "missing-link" | "evidence-mismatch" | "question-irrelevant" | "overstated" | "redundant";
+export type ReasoningCriticFinding = {
+    id: string;
+    hypothesisId: string;
+    kind: ReasoningCriticFindingKind;
+    issue: string;
+};
+export type ReasoningCriticFindingResolutionDisposition = "rejected" | "superseded" | "retained-with-new-evidence" | "retained-safe-to-omit" | "resolved-by-associated-hypotheses" | "resolved-existing-evidence";
+export type ReasoningCriticFindingResolution = {
+    findingId: string;
+    hypothesisId: string;
+    disposition: ReasoningCriticFindingResolutionDisposition;
+    rationale: string;
+    evidenceIds: string[];
+    supersededBy: string[];
+    resolvedByHypothesisIds: string[];
+};
+export type ReasoningCriticResolutionAuditDecision = {
+    findingId: string;
+    hypothesisId: string;
+    outcome: "resolved" | "unresolved";
+    rationale: string;
+};
+export type ReasoningCriticResolutionAudit = {
+    decisions: ReasoningCriticResolutionAuditDecision[];
+    batchRationale: string;
+};
+/**
+ * Compact provenance that a completed critic audit found an already accepted
+ * hypothesis to represent a bounded causal or continuation meaning. It is an
+ * omission-audit signal only: it adds neither chess proof nor evidence
+ * authority, and is deliberately not a retained copy of the raw critic row.
+ */
+export type ReasoningSemanticPreservationSignal = {
+    hypothesisId: string;
+    auditKind: "causal-evidence" | "continuation-activity";
+    evidenceId: string;
+    rootMove: string | null;
+    routeMoves: string[];
+    contact: {
+        attackedSquare: string;
+        targetMoverPieceId: string | null;
+        targetMoveUci: string | null;
+        continuationPieceId: string;
+        contactMoveUci: string;
+    } | null;
+    rationale: string;
+};
+export type ReasoningChallengeDecision = {
+    hypothesisIds: string[];
+    observationAudits: ReasoningChallengeObservationAudit[];
+    hypothesisFindings: ReasoningCriticFinding[];
+    semanticPreservationSignals: ReasoningSemanticPreservationSignal[];
+    novelHypothesisNeeded: boolean;
+    questionCoverageRationale: string;
+};
+export type ReasoningClaimKind = "fact" | "interpretation" | "consequence" | "defense" | "uncertainty";
+export type ReasoningPieceKind = "bishop" | "king" | "knight" | "pawn" | "queen" | "rook";
+export type ReasoningPieceReferenceForm = "definite" | "color-qualified" | "square-qualified" | "canonical" | "bare" | "bare-square-qualified";
+export type ReasoningNarrativeSegment = {
+    type: "text";
+    text: string;
+} | {
+    type: "piece";
+    pieceId: string;
+    form?: ReasoningPieceReferenceForm;
+    capitalize?: boolean;
+    label?: string;
+} | {
+    type: "piece-kind";
+    pieceKind: ReasoningPieceKind;
+    color: "w" | "b" | null;
+    label?: string;
+} | {
+    type: "square";
+    square: string;
+    label?: string;
+} | {
+    type: "move";
+    uci: string;
+    pieceId: string;
+    san?: string;
+    label?: string;
+} | {
+    type: "entity";
+    entityId: string;
+    label?: string;
+} | {
+    type: "relation";
+    relationId: string;
+    fromEntityId: string;
+    toEntityId: string;
+    label?: string;
+};
+export type ResolvedReasoningNarrativeSegment = {
+    type: "text";
+    text: string;
+} | {
+    type: "piece";
+    pieceId: string;
+    square: string | null;
+    label: string;
+} | {
+    type: "piece-kind";
+    pieceKind: ReasoningPieceKind;
+    color: "w" | "b" | null;
+    label: string;
+} | {
+    type: "square";
+    square: string;
+    label: string;
+} | {
+    type: "move";
+    uci: string;
+    pieceId: string;
+    from: string;
+    to: string;
+    san: string;
+    label: string;
+} | {
+    type: "entity";
+    entityId: string;
+    label: string;
+} | {
+    type: "relation";
+    relationId: string;
+    fromEntityId: string;
+    toEntityId: string;
+    relationType: string;
+    label: string;
+};
+export type ReasoningGraphReference = {
+    type: "entity";
+    entityId: string;
+} | {
+    type: "relation";
+    relationId: string;
+    fromEntityId: string;
+    toEntityId: string;
+};
+export type ReasoningClaim = {
+    id: string;
+    kind: ReasoningClaimKind;
+    content: ReasoningNarrativeSegment[];
+    proofStrength: ProofStrength | null;
+    evidenceIds: string[];
+    graphRefs: ReasoningGraphReference[];
+};
+export type ValidatedReasoningClaim = Omit<ReasoningClaim, "content"> & {
+    content: ResolvedReasoningNarrativeSegment[];
+    text: string;
+    graphEvidenceId: string | null;
+};
+export type ReasoningMoveInput = {
+    uci: string;
+    pieceId: string;
+};
+type ReasoningDraftGraphCoverage = {
+    graphRefs: ReasoningGraphReference[];
+    intentId?: string;
+};
+export type ReasoningDraftDemonstration = ({
+    id: string;
+    type: "legal-variation";
+    start: "before" | "after";
+    moves: ReasoningMoveInput[];
+    label: string;
+    evidenceIds: string[];
+} & ReasoningDraftGraphCoverage) | ({
+    id: string;
+    type: "conditional-route";
+    pieceId: string;
+    waypoints: string[];
+    prerequisiteRefs: ReasoningNarrativeSegment[];
+    label: string;
+    evidenceIds: string[];
+} & ReasoningDraftGraphCoverage) | ({
+    id: string;
+    type: "static-relationship";
+    from: ReasoningNarrativeSegment;
+    to: ReasoningNarrativeSegment;
+    relationType: string;
+    label: string;
+    evidenceIds: string[];
+} & ReasoningDraftGraphCoverage);
+export type ResolvedReasoningMove = ReasoningMoveInput & {
+    from: string;
+    to: string;
+    san: string;
+    resultingFen: string;
+};
+export type ReasoningDemonstration = ((Omit<Extract<ReasoningDraftDemonstration, {
+    type: "legal-variation";
+}>, "moves"> & {
+    moves: ResolvedReasoningMove[];
+}) | (Omit<Extract<ReasoningDraftDemonstration, {
+    type: "conditional-route";
+}>, "prerequisiteRefs"> & {
+    prerequisiteRefs: ResolvedReasoningNarrativeSegment[];
+}) | (Omit<Extract<ReasoningDraftDemonstration, {
+    type: "static-relationship";
+}>, "from" | "to"> & {
+    from: ResolvedReasoningNarrativeSegment;
+    to: ResolvedReasoningNarrativeSegment;
+})) & {
+    graphEvidenceId: string | null;
+};
+export type BoardAnnotation = {
+    kind: "arrow" | "highlight";
+    from?: string;
+    to: string;
+    sourceRefType: "move" | "piece" | "square" | "route";
+};
+export type ReasoningClaimScope = "conditional-plan" | "bounded-consequence" | "position-fact";
+export type ReasoningDefenseCoverage = {
+    completeWithinClass: boolean;
+    completeForAllResponses: boolean;
+    coveredClasses: string[];
+    unresolvedClasses: string[];
+    evidenceIds: string[];
+};
+export type ReasoningValidationIssue = {
+    path: string;
+    code: string;
+    message: string;
+    permittedReferences: string[];
+};
+export type ReasoningDraft = {
+    claimScope: ReasoningClaimScope;
+    defenseCoverage: ReasoningDefenseCoverage;
+    claims: ReasoningClaim[];
+    demonstrations: ReasoningDraftDemonstration[];
+    limitations: string[];
+};
+export type ReasoningModelNarrativeSegment = Extract<ReasoningNarrativeSegment, {
+    type: "text";
+}> | Omit<Extract<ReasoningNarrativeSegment, {
+    type: "piece";
+}>, "label"> | Omit<Extract<ReasoningNarrativeSegment, {
+    type: "piece-kind";
+}>, "label"> | Omit<Extract<ReasoningNarrativeSegment, {
+    type: "square";
+}>, "label"> | Omit<Extract<ReasoningNarrativeSegment, {
+    type: "move";
+}>, "label"> | Omit<Extract<ReasoningNarrativeSegment, {
+    type: "entity";
+}>, "label"> | Omit<Extract<ReasoningNarrativeSegment, {
+    type: "relation";
+}>, "label">;
+export type ReasoningModelDraftClaim = Omit<ReasoningClaim, "content" | "graphRefs"> & {
+    content: ReasoningModelNarrativeSegment[];
+};
+export type ReasoningModelDraftDemonstration = Omit<Extract<ReasoningDraftDemonstration, {
+    type: "legal-variation";
+}>, "graphRefs"> | (Omit<Extract<ReasoningDraftDemonstration, {
+    type: "conditional-route";
+}>, "graphRefs" | "prerequisiteRefs"> & {
+    prerequisiteRefs: ReasoningModelNarrativeSegment[];
+}) | {
+    id: string;
+    type: "static-relationship";
+    relation: Extract<ReasoningModelNarrativeSegment, {
+        type: "relation";
+    }>;
+    label: string;
+    evidenceIds: string[];
+};
+export type ReasoningModelDraft = {
+    claimScope: ReasoningClaimScope;
+    defenseCoverage: ReasoningDefenseCoverage;
+    claims: ReasoningModelDraftClaim[];
+    demonstrations: ReasoningModelDraftDemonstration[];
+    limitations: string[];
+};
+export type ReasoningRenderNarrativeSegment = Exclude<ReasoningModelNarrativeSegment, {
+    type: "relation" | "entity";
+}> | {
+    type: "entity";
+    entityId: string;
+    label?: string;
+};
+export type ReasoningRenderDraftClaim = Omit<ReasoningModelDraftClaim, "content"> & {
+    content: ReasoningRenderNarrativeSegment[];
+    entityIds: string[];
+};
+export type ReasoningRenderDraftDemonstration = {
+    type: "legal-variation";
+    intentId: string;
+} | (Omit<Extract<ReasoningModelDraftDemonstration, {
+    type: "conditional-route";
+}>, "prerequisiteRefs"> & {
+    intentId?: string;
+    prerequisiteRefs: ReasoningRenderNarrativeSegment[];
+});
+export type ReasoningRenderDraft = {
+    claims: ReasoningRenderDraftClaim[];
+    demonstrations: ReasoningRenderDraftDemonstration[];
+};
+export declare const REASONING_DISCOURSE_PLAN_VERSION: "reasoning-discourse-plan/2";
+export type ReasoningDiscourseRole = "main-idea" | "mechanism" | "practical-consequence" | "qualification";
+export type ReasoningDiscourseParagraph = {
+    id: string;
+    role: ReasoningDiscourseRole;
+    claimKind: ReasoningClaimKind;
+    objective: string;
+    entityIds: string[];
+    relationIds: string[];
+    evidenceIds: string[];
+};
+export type ReasoningDiscourseRelationAction = {
+    relationId: string;
+    label: string;
+};
+export type ReasoningDiscourseDemonstrationIntent = {
+    id: string;
+    paragraphId: string;
+    type: "legal-variation" | "conditional-route";
+    evidenceIds: string[];
+    objective: string;
+};
+export type ReasoningDiscoursePlan = {
+    schemaVersion: typeof REASONING_POC_VERSION;
+    planVersion: typeof REASONING_DISCOURSE_PLAN_VERSION;
+    id: string;
+    checkpointId: string;
+    paragraphs: ReasoningDiscourseParagraph[];
+    relationActions: ReasoningDiscourseRelationAction[];
+    demonstrationIntents: ReasoningDiscourseDemonstrationIntent[];
+};
+export type ReasoningDiscoursePlanDraft = Pick<ReasoningDiscoursePlan, "paragraphs" | "relationActions" | "demonstrationIntents">;
+export type ReasoningCheckpointEvidenceSummary = {
+    id: string;
+    kind: ReasoningEvidenceKind;
+    source: string;
+    proofStrength: ProofStrength | null;
+    licenses: EvidenceLicense[];
+    summary: string;
+    details: Record<string, SemanticValue>;
+    coverage: ReasoningEvidenceRecord["coverage"];
+};
+export type ReasoningReferenceScope = {
+    pieceIds: string[];
+    squares: string[];
+    moves: Array<ReasoningMoveInput & {
+        san: string;
+    }>;
+};
+export type ReasoningCheckpointReferenceBindings = {
+    target: ReasoningReferenceScope;
+    evidence: Array<{
+        evidenceId: string;
+    } & ReasoningReferenceScope>;
+    entities: Array<{
+        entityId: string;
+    } & ReasoningReferenceScope>;
+    relations: Array<{
+        relationId: string;
+    } & ReasoningReferenceScope>;
+};
+export type ReasoningCheckpoint = {
+    schemaVersion: typeof REASONING_POC_VERSION;
+    checkpointVersion: "reasoning-checkpoint/5";
+    id: string;
+    requestId: string;
+    contextHash: string;
+    question: string;
+    audience: ReasoningAudience;
+    concise: boolean;
+    requestedConclusion: QueryContract["requestedConclusion"];
+    hypothesisLedgerRevision: string;
+    observationCoverage: ReasoningObservationCoverage[];
+    reviewedHypotheses: ReasoningHypothesisRecord[];
+    selectedGraph: {
+        evidenceId: string;
+        graphHash: string;
+        entities: SemanticEntity[];
+        relations: SemanticRelation[];
+    };
+    presentation: {
+        entities: Array<{
+            entityId: string;
+            label: string;
+        }>;
+        relations: Array<{
+            relationId: string;
+            fromEntityId: string;
+            toEntityId: string;
+            label: string;
+        }>;
+    };
+    approvedEvidence: ReasoningCheckpointEvidenceSummary[];
+    claimScope: ReasoningClaimScope;
+    defenseCoverage: ReasoningDefenseCoverage;
+    limitations: string[];
+    referenceBindings: ReasoningCheckpointReferenceBindings;
+    allowlists: {
+        evidenceIds: string[];
+        pieceIds: string[];
+        squares: string[];
+        moves: Array<ReasoningMoveInput & {
+            san: string;
+        }>;
+        entityIds: string[];
+        relations: Array<{
+            relationId: string;
+            fromEntityId: string;
+            toEntityId: string;
+        }>;
+    };
+    obligations: {
+        requestedConclusion: QueryContract["requestedConclusion"];
+        responseCoverageRequirement: QueryContract["responseCoverageRequirement"];
+        continuationCoverageRequirement: QueryContract["continuationCoverageRequirement"];
+        minimumContinuationLines: number;
+        graphRequirements: ReasoningGraphRequirements;
+        entityIds: string[];
+        relations: Array<{
+            relationId: string;
+            fromEntityId: string;
+            toEntityId: string;
+        }>;
+        requireInterpretationClaim: boolean;
+        requireConditionalQualification: boolean;
+    };
+};
+export type ReasoningCompletionStage = "semantic-incomplete" | "reasoned-unrendered" | "render-invalid" | "complete";
+export type ReasoningStructuralOutcome = "incomplete" | "complete";
+export type ReasoningNarrativeOutcome = "not-attempted" | "unrendered" | "invalid" | "valid";
+export type ReasoningInteractionCoverage = {
+    status: "not-assessed" | "partial" | "complete";
+    semanticReferenceCount: number;
+    interactiveReferenceCount: number;
+    genericReferenceCount: number;
+    coverageRatio: number | null;
+    gaps: Array<{
+        path: string;
+        type: "piece-kind" | "off-board-piece" | "unbound-entity" | "unbound-relation" | "indistinguishable-entity-label";
+        label: string;
+    }>;
+};
+export type ReasoningRenderMetrics = {
+    inputBytes: number | null;
+    generatedJsonBytes: number;
+    inputTokens: number | null;
+    outputTokens: number | null;
+    finishReason: string | null;
+    validationResult: "not-attempted" | "unparseable" | "invalid" | "valid";
+};
+export type ReasoningToolTrace = {
+    callId: string;
+    tool: ReasoningToolName;
+    input: Record<string, unknown>;
+    support: ReasoningToolSupport;
+    evidenceIds: string[];
+    durationMs: number;
+    error?: string;
+};
+export type ReasoningHarnessPhase = "observations-presented" | "hypothesis-submission-required" | "hypotheses-recorded" | "observations-reviewed" | "future-purpose-planning" | "reasoning-challenged" | "hypotheses-revised" | "hypotheses-reviewed" | "critic-resolutions-audited" | "graph-materialized" | "checkpoint-frozen" | "discourse-planning" | "discourse-planning-repair" | "discourse-planned" | "draft-render" | "draft-generated" | "draft-repair";
+export type ReasoningRuntimeDiagnostic = {
+    step: number;
+    provider: string;
+    model: string;
+    route: string;
+    sdkRuntime: string;
+    reasoningEffort: string;
+    outcome: "succeeded" | "failed" | "aborted";
+    httpStatus: number | null;
+    providerRequestId: string | null;
+    latencyMs: number | null;
+    retryCount: number | null;
+    finishReason: string | null;
+    contentPartCount: number;
+    textBytes: number;
+    toolCallCount: number;
+    toolCallBytes: number;
+    structuredOutputBytes: number;
+    reasoningPartCount: number;
+    reasoningBytes: number;
+    reasoningDetailsPresent: boolean;
+    inputTokens: number | null;
+    outputTokens: number | null;
+    outputTokenLimit: number;
+    requestContextBytes: number | null;
+    requestMessageCount: number | null;
+    contextCompacted: boolean;
+    lastHarnessPhase: ReasoningHarnessPhase;
+    errorCategory: string | null;
+    structuredOutputRecovery?: "locally-validated-json" | null;
+    /** Transport-only structured-output retry metadata for bounded stage recovery. */
+    recoveryAttempt?: number | null;
+    recoveryTrigger?: "output-truncated" | "output-missing" | null;
+    hypothesisRejectionStage?: "provider-structured-output" | "schema-validation" | "harness-validation" | null;
+    hypothesisRejectionCode?: "no-output" | "parse" | "schema" | "unknown-reference-or-evidence" | "unsupported-concept" | "anchor-incompatibility" | "supersession-lineage" | "critic-resolution-evidence" | "critic-resolution-incompatibility" | "used-observation-orphaned" | "empty-batch" | "evidence-license" | "proof-overstatement" | "malformed-structure" | "relation-or-budget" | "harness-validation" | null;
+    abortSource: "external" | "wall-time" | "provider" | null;
+};
+export declare class ModelRuntimeFailure extends Error {
+    readonly runtime: string;
+    readonly model: string;
+    readonly diagnostics: ReasoningRuntimeDiagnostic[];
+    readonly usage: {
+        inputTokens: number | null;
+        outputTokens: number | null;
+    };
+    constructor(input: {
+        runtime: string;
+        model: string;
+        diagnostics: ReasoningRuntimeDiagnostic[];
+        usage: {
+            inputTokens: number | null;
+            outputTokens: number | null;
+        };
+    });
+}
+export type ModelRunRequest = {
+    schemaVersion: typeof REASONING_POC_VERSION;
+    contract: QueryContract;
+    context: ReasoningPositionContext;
+    contextHash: string;
+    observations: ReasoningRankedObservationSet;
+    controls: ReasoningRunControls;
+};
+export type ModelRunResult = {
+    runtime: string;
+    model: string;
+    draft?: ReasoningDraft;
+    trace: ReasoningToolTrace[];
+    steps: number;
+    usage: {
+        inputTokens: number | null;
+        outputTokens: number | null;
+    };
+    diagnostics?: ReasoningRuntimeDiagnostic[];
+};
+export interface ModelRuntime {
+    run(request: ModelRunRequest, tools: ReasoningToolSet, signal?: AbortSignal): Promise<ModelRunResult>;
+    replaySemanticStage?(request: ModelSemanticStageReplayRequest, signal?: AbortSignal): Promise<ModelSemanticStageReplayResult>;
+    planDiscourse?(request: ModelDiscoursePlanRequest, signal?: AbortSignal): Promise<ModelDiscoursePlanResult>;
+    renderCheckpoint?(request: ModelRenderRequest, signal?: AbortSignal): Promise<ModelRenderResult>;
+    repairDraft?(request: ModelDraftRepairRequest, signal?: AbortSignal): Promise<ModelDraftRepairResult>;
+}
+export type ReasoningSemanticReplayStage = "hypothesis-initial" | "hypothesis-revision" | "future-purpose-probe" | "reasoning-critic" | "critic-resolution-audit" | "answer-obligation-and-graph-selection" | "graph-selection";
+export type ModelSemanticStageReplayRequest = {
+    schemaVersion: typeof REASONING_POC_VERSION;
+    stage: ReasoningSemanticReplayStage;
+    input: Record<string, unknown>;
+};
+export type ModelSemanticStageReplayResult = {
+    runtime: string;
+    model: string;
+    stage: ReasoningSemanticReplayStage;
+    output: Record<string, unknown>;
+    usage: {
+        inputTokens: number | null;
+        outputTokens: number | null;
+    };
+    diagnostics?: ReasoningRuntimeDiagnostic[];
+};
+export type ModelDiscoursePlanRequest = {
+    schemaVersion: typeof REASONING_POC_VERSION;
+    contract: QueryContract;
+    context: ReasoningPositionContext;
+    contextHash: string;
+    checkpoint: ReasoningCheckpoint;
+};
+export type ModelDiscoursePlanResult = {
+    runtime: string;
+    model: string;
+    plan: ReasoningDiscoursePlan;
+    usage: {
+        inputTokens: number | null;
+        outputTokens: number | null;
+    };
+    diagnostics?: ReasoningRuntimeDiagnostic[];
+};
+export type ModelRenderRequest = {
+    schemaVersion: typeof REASONING_POC_VERSION;
+    contract: QueryContract;
+    context: ReasoningPositionContext;
+    contextHash: string;
+    checkpoint: ReasoningCheckpoint;
+    discoursePlan?: ReasoningDiscoursePlan;
+    maxOutputChars: number;
+    previousValidationIssues?: ReasoningValidationIssue[];
+};
+export type ModelRenderResult = {
+    runtime: string;
+    model: string;
+    draft: ReasoningDraft;
+    usage: {
+        inputTokens: number | null;
+        outputTokens: number | null;
+    };
+    diagnostics?: ReasoningRuntimeDiagnostic[];
+    metrics: ReasoningRenderMetrics;
+};
+export type ModelDraftRepairRequest = {
+    schemaVersion: typeof REASONING_POC_VERSION;
+    contract: QueryContract;
+    context: ReasoningPositionContext;
+    contextHash: string;
+    originalDraft: ReasoningDraft;
+    issues: ReasoningValidationIssue[];
+    frozen: {
+        observationCoverage: ReasoningObservationCoverage[];
+        hypothesisLedgerRevision: string;
+        hypothesisIds: string[];
+        relationIds: string[];
+        graphEvidenceIds: string[];
+        evidenceIds: string[];
+        referenceAllowlists: {
+            pieceIds: string[];
+            squares: string[];
+            moves: Array<{
+                uci: string;
+                pieceId: string;
+                san: string;
+            }>;
+        };
+        referenceBindings: ReasoningCheckpointReferenceBindings;
+        claimScope: ReasoningClaimScope;
+        defenseCoverage: ReasoningDefenseCoverage;
+    };
+    maxOutputChars: number;
+};
+export type ModelDraftRepairResult = {
+    runtime: string;
+    model: string;
+    draft: ReasoningDraft;
+    usage: {
+        inputTokens: number | null;
+        outputTokens: number | null;
+    };
+    diagnostics?: ReasoningRuntimeDiagnostic[];
+};
+export type ValidatedReasoningAnswer = {
+    schemaVersion: typeof REASONING_POC_VERSION;
+    requestId: string;
+    contextHash: string;
+    status: "supported" | "partial" | "fact-only";
+    completionStage: ReasoningCompletionStage;
+    reasoningOutcome: ReasoningStructuralOutcome;
+    narrativeOutcome: ReasoningNarrativeOutcome;
+    interactionCoverage: ReasoningInteractionCoverage;
+    reasoningCheckpoint: ReasoningCheckpoint | null;
+    discoursePlan: ReasoningDiscoursePlan | null;
+    renderMetrics: ReasoningRenderMetrics;
+    claimScope: ReasoningClaimScope;
+    defenseCoverage: ReasoningDefenseCoverage;
+    answer: string;
+    claims: ValidatedReasoningClaim[];
+    rejectedClaims: Array<{
+        claim: ReasoningClaim;
+        reasons: string[];
+    }>;
+    rejectedDemonstrations: Array<{
+        demonstration: ReasoningDraftDemonstration;
+        issues: ReasoningValidationIssue[];
+    }>;
+    validationIssues: ReasoningValidationIssue[];
+    repair: {
+        attempted: boolean;
+        succeeded: boolean;
+    };
+    demonstrations: ReasoningDemonstration[];
+    annotations: BoardAnnotation[];
+    observationCoverage: ReasoningObservationCoverage[];
+    hypotheses: ReasoningHypothesisRecord[];
+    unverifiedCandidateHypothesisIds: string[];
+    evidence: ReasoningEvidenceRecord[];
+    limitations: string[];
+    trace: ReasoningToolTrace[];
+    runtime: string;
+    model: string;
+    usage: ModelRunResult["usage"];
+    runtimeDiagnostics: ReasoningRuntimeDiagnostic[];
+};
+export declare function validateReasoningPositionContext(value: ReasoningPositionContext): ReasoningPositionContext;
+export declare function reasoningContextHash(context: ReasoningPositionContext): string;
+export declare function createQueryContract(input: {
+    requestId: string;
+    question: string;
+    audience?: ReasoningAudience;
+    concise?: boolean;
+    responseCoverageRequirement?: QueryContract["responseCoverageRequirement"];
+    continuationCoverageRequirement?: QueryContract["continuationCoverageRequirement"];
+    minimumContinuationLines?: number;
+    graphRequirements?: Partial<ReasoningGraphRequirements>;
+    context: ReasoningPositionContext;
+}): QueryContract;
+export declare function createContextEvidence(context: ReasoningPositionContext, contextHash?: string): ReasoningEvidenceRecord;
+export {};