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

package/src/chess-reasoning/concept-registry.ts

@@ -0,0 +1,275 @@
+import type {
+  ConceptKey,
+  RegistryKey,
+  SemanticCandidate,
+  SemanticEntity,
+  SemanticParticipant,
+  SemanticValue,
+} from "./types";
+
+export const ENTITY_TYPES = {
+  IDEA: "idea",
+  PLAN: "plan",
+  ROLE: "role-assignment",
+  CONDITION: "condition",
+  TRANSFORMATION: "transformation",
+  OUTCOME: "outcome",
+} as const;
+
+export const REFERENCE_DOMAINS = {
+  PIECE: "piece",
+  SQUARE: "square",
+  MOVE: "move",
+  POSITION: "position",
+  OUTCOME: "outcome",
+  ENTITY: "entity",
+} as const;
+
+export const PARTICIPANT_ROLES = {
+  ACTOR: "actor",
+  SUBJECT: "subject",
+  TARGET: "target",
+  GOAL: "goal",
+  RESOURCE: "resource",
+  DEFENDER: "defender",
+  DESTINATION: "destination",
+} as const;
+
+export const ATTRIBUTE_KEYS = {
+  ACCEPTING_MOVES: "acceptingMoves",
+  PROPOSAL_REASONS: "proposalReasons",
+  DESCRIPTION: "description",
+  CONFIDENCE_NOTE: "confidenceNote",
+} as const;
+
+export const RELATION_TYPES = {
+  SUPPORTS: "supports",
+  COMPETES: "competes",
+  DERIVES: "derives",
+  SPLITS: "splits",
+  CONVERGES: "converges",
+  ENABLES: "enables",
+  REQUIRES: "requires",
+  REFUTES: "refutes",
+  EXPLAINS: "explains",
+  TRANSFORMS: "transforms",
+} as const;
+
+/**
+ * These are registry values, not members of the entity schema. New concepts
+ * may be registered without changing `SemanticCandidate` or `SemanticEntity`.
+ */
+export const CONCEPT_KEYS = {
+  OFFER: "material.offer",
+  MATERIAL_CLAIM: "material.claim",
+  FORK: "tactic.fork",
+  TRAPPED_TARGET: "tactic.trapped-target",
+  PROMOTION: "tactic.promotion",
+  MATING_ATTACK: "attack.mating",
+  PERPETUAL_CHECK: "attack.perpetual-check",
+  POSITIONAL_CLAIM: "position.claim",
+  KING_ATTACK_PLAN: "plan.king-attack",
+  PIECE_ROLE: "role.piece-function",
+  CHANGED_CONSTRAINT: "condition.changed-constraint",
+  POSITIONAL_TRANSFORMATION: "position.transformation",
+} as const;
+
+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>>>;
+
+const COMMON_TERMINAL_STATES = ["converted", "refuted", "abandoned", "expired"];
+
+function claimLifecycle(capturedBy: CaptureActor): ConceptLifecycle {
+  return {
+    initialState: "created",
+    retainedState: "retained",
+    terminalStates: [...COMMON_TERMINAL_STATES],
+    trackedParticipantRole: PARTICIPANT_ROLES.TARGET,
+    expireWhenTrackedUnavailable: true,
+    onTrackedCapture: {
+      capturedBy,
+      matchingState: "converted",
+      matchingAnnotation: "converted",
+      otherState: "refuted",
+      otherAnnotation: "refuted",
+    },
+  };
+}
+
+export function createConceptRegistry(definitions: ConceptDefinition[]): ConceptRegistry {
+  const registry: Record<string, Readonly<ConceptDefinition>> = {};
+  for (const definition of definitions) {
+    if (!definition.key.trim()) throw new Error("Concept keys must not be empty");
+    if (registry[definition.key]) throw new Error(`Duplicate concept key: ${definition.key}`);
+    registry[definition.key] = Object.freeze({
+      ...definition,
+      lifecycle: definition.lifecycle
+        ? Object.freeze({
+          ...definition.lifecycle,
+          terminalStates: Object.freeze([...definition.lifecycle.terminalStates]) as unknown as RegistryKey[],
+          onTrackedCapture: definition.lifecycle.onTrackedCapture
+            ? Object.freeze({ ...definition.lifecycle.onTrackedCapture })
+            : undefined,
+        })
+        : undefined,
+    });
+  }
+  return Object.freeze(registry);
+}
+
+export function extendConceptRegistry(registry: ConceptRegistry, definitions: ConceptDefinition[]): ConceptRegistry {
+  return createConceptRegistry([...Object.values(registry), ...definitions]);
+}
+
+export function conceptDefinition(registry: ConceptRegistry, key: ConceptKey): Readonly<ConceptDefinition> | null {
+  return registry[key] || null;
+}
+
+export function conceptsOf(value: Pick<SemanticCandidate | SemanticEntity, "concepts">): ConceptKey[] {
+  return [...value.concepts];
+}
+
+export function hasConcept(value: Pick<SemanticCandidate | SemanticEntity, "concepts">, concept: ConceptKey): boolean {
+  return value.concepts.includes(concept);
+}
+
+export function primaryConcept(value: Pick<SemanticCandidate | SemanticEntity, "concepts">): ConceptKey | null {
+  return value.concepts[0] || null;
+}
+
+export function participantIds(
+  value: Pick<SemanticCandidate | SemanticEntity, "participants">,
+  role: RegistryKey,
+  domain?: RegistryKey,
+): string[] {
+  return value.participants
+    .filter((participant) => participant.role === role && (!domain || participant.ref.domain === domain))
+    .map((participant) => participant.ref.id);
+}
+
+export function participant(role: RegistryKey, domain: RegistryKey, id: string): SemanticParticipant {
+  return { role, ref: { domain, id } };
+}
+
+export function stringListAttribute(value: { attributes: Record<string, SemanticValue> }, key: string): string[] {
+  const attribute = value.attributes[key];
+  return Array.isArray(attribute) ? attribute.filter((item): item is string => typeof item === "string") : [];
+}
+
+export const DEFAULT_CONCEPT_REGISTRY = createConceptRegistry([
+  {
+    key: CONCEPT_KEYS.OFFER,
+    label: "Material offer",
+    category: "tactical",
+    description: "A material liability the opponent may choose to accept.",
+    defaultEntityType: ENTITY_TYPES.IDEA,
+    acceptancePolicy: "material-offer-liability/1",
+    lifecycle: claimLifecycle("opponent"),
+  },
+  {
+    key: CONCEPT_KEYS.MATERIAL_CLAIM,
+    label: "Material claim",
+    category: "tactical",
+    description: "An evidence-backed entitlement to win material.",
+    defaultEntityType: ENTITY_TYPES.IDEA,
+    lifecycle: claimLifecycle("owner"),
+  },
+  {
+    key: CONCEPT_KEYS.FORK,
+    label: "Fork",
+    category: "tactical",
+    description: "One resource attacks multiple targets.",
+    defaultEntityType: ENTITY_TYPES.IDEA,
+    lifecycle: claimLifecycle("owner"),
+  },
+  {
+    key: CONCEPT_KEYS.TRAPPED_TARGET,
+    label: "Trapped target",
+    category: "tactical",
+    description: "A target lacks an adequate escape or defensive resource.",
+    defaultEntityType: ENTITY_TYPES.IDEA,
+    lifecycle: claimLifecycle("owner"),
+  },
+  {
+    key: CONCEPT_KEYS.PROMOTION,
+    label: "Promotion",
+    category: "tactical",
+    description: "A promotion event or promotion claim.",
+    defaultEntityType: ENTITY_TYPES.IDEA,
+  },
+  {
+    key: CONCEPT_KEYS.MATING_ATTACK,
+    label: "Mating attack",
+    category: "tactical",
+    description: "A coordinated plan whose concrete target is mate.",
+    defaultEntityType: ENTITY_TYPES.PLAN,
+  },
+  {
+    key: CONCEPT_KEYS.PERPETUAL_CHECK,
+    label: "Perpetual check",
+    category: "tactical",
+    description: "A claim to a repeatable checking sequence.",
+    defaultEntityType: ENTITY_TYPES.IDEA,
+  },
+  {
+    key: CONCEPT_KEYS.POSITIONAL_CLAIM,
+    label: "Positional claim",
+    category: "positional",
+    description: "A measured, evidence-bounded positional interpretation.",
+    defaultEntityType: ENTITY_TYPES.IDEA,
+  },
+  {
+    key: CONCEPT_KEYS.KING_ATTACK_PLAN,
+    label: "King attack plan",
+    category: "plan",
+    description: "A goal-directed sequence intended to attack the king.",
+    defaultEntityType: ENTITY_TYPES.PLAN,
+  },
+  {
+    key: CONCEPT_KEYS.PIECE_ROLE,
+    label: "Piece role",
+    category: "role",
+    description: "A context-dependent function performed by a piece.",
+    defaultEntityType: ENTITY_TYPES.ROLE,
+  },
+  {
+    key: CONCEPT_KEYS.CHANGED_CONSTRAINT,
+    label: "Changed constraint",
+    category: "condition",
+    description: "A condition whose importance changed after a move or sequence.",
+    defaultEntityType: ENTITY_TYPES.CONDITION,
+  },
+  {
+    key: CONCEPT_KEYS.POSITIONAL_TRANSFORMATION,
+    label: "Positional transformation",
+    category: "transformation",
+    description: "A causal change in the meaning of a positional feature.",
+    defaultEntityType: ENTITY_TYPES.TRANSFORMATION,
+  },
+]);

package/src/chess-reasoning/conversation-context.ts

@@ -0,0 +1,29 @@
+import type { ModelMessage } from 'ai';
+export type PriorConversationMessage = { role: 'user' | 'assistant'; content: string; position?: { fenBefore: string; fenAfter: string; moveUci: string } };
+export 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 function priorConversationMessages(history: readonly PriorConversationMessage[] = []): ModelMessage[] {
+  const retained: ModelMessage[] = [];
+  let bytes = 0;
+  for (let i = history.length - 1; i >= 0; i--) {
+    const item = history[i];
+    if (!item || (item.role !== 'user' && item.role !== 'assistant') || typeof item.content !== 'string' || !item.content.trim()) continue;
+    // Explicit allowlist: saved diagnostics, native tool turns, provider metadata
+    // and nested presentation/evidence never enter subsequent investigations.
+    const p = item.position;
+    const position = p && typeof p.fenBefore === 'string' && typeof p.fenAfter === 'string' && typeof p.moveUci === 'string'
+      ? { fenBefore: p.fenBefore, fenAfter: p.fenAfter, moveUci: p.moveUci } : undefined;
+    // Prior answers supply prose context, not reusable interaction pointers.
+    // Labels retain the actual displayed moves/pieces/squares; frozen UI is separate.
+    const text = item.content.replace(/\[([^\]\n]+)\]\((?:move|piece|square|line):[^)\n]+\)/g, '$1')
+      .replace(/\[(?:\s*evidence:[\w:-]+\s*[,;]?\s*)+\]/g, '');
+    const content = JSON.stringify({ scope: 'previous-conversation', position, text });
+    const size = new TextEncoder().encode(content).length;
+    if (bytes + size > 36_000 || retained.length >= 24) break;
+    bytes += size; retained.unshift({ role: item.role, content });
+  }
+  // Avoid an orphan answer if truncation cut off its question.
+  if (retained[0]?.role === 'assistant') retained.shift();
+  return retained.length < history.length
+    ? [{ role: 'user', content: '[Conversation history truncated: only the most recent complete exchanges that fit are included.]' }, ...retained]
+    : retained;
+}

package/src/chess-reasoning/engine-search-failure.ts

@@ -0,0 +1,11 @@
+/** Bounded observable cause only: no stack, response headers or provider payload. */
+export function engineSearchFailure(error: unknown) {
+  const detail = error as { message?: unknown; code?: unknown; status?: unknown; cause?: unknown } | null;
+  const message = typeof detail?.message === 'string' ? detail.message.slice(0, 300)
+    : typeof error === 'string' ? error.slice(0, 300) : 'engine-search-unavailable';
+  const cause = detail?.cause as { message?: unknown; code?: unknown } | null;
+  return { error: message,
+    ...(typeof detail?.code === 'string' ? { code: detail.code.slice(0, 80) } : {}),
+    ...(typeof detail?.status === 'number' && Number.isInteger(detail.status) && detail.status >= 100 && detail.status <= 599 ? { status: detail.status } : {}),
+    ...(typeof cause?.message === 'string' ? { cause: cause.message.slice(0, 300) } : {}) };
+}

package/src/chess-reasoning/evidence-citation-normalization.ts

@@ -0,0 +1,15 @@
+import type { ReasoningEvidenceRecord } from './poc-contracts';
+
+/** Repair syntax only when the exact supplied identifier makes it unambiguous. */
+export function normalizedEvidenceCitations(answer: string, records: readonly Pick<ReasoningEvidenceRecord, 'id'>[]) {
+  const ids = new Set(records.map(record => record.id));
+  const repairs: Array<{originalId:string;canonicalId:string}> = [];
+  const normalized = answer.replace(/\b(?:evidence:){2,}[\w:-]+/g, originalId => {
+    if (ids.has(originalId)) return originalId;
+    const canonicalId = originalId.replace(/^(?:evidence:)+/, 'evidence:');
+    if (!ids.has(canonicalId)) return originalId;
+    repairs.push({originalId,canonicalId});
+    return canonicalId;
+  });
+  return {answer:normalized,repairs};
+}

package/src/chess-reasoning/evidence-licenses.ts

@@ -0,0 +1,166 @@
+import type { ProofStrength, SemanticValue } from "./types";
+
+export const EVIDENCE_LICENSE = Object.freeze({
+  CHESS_LEGALITY: "chess.legality",
+  CHESS_IDENTITY: "chess.identity",
+  CHESS_POSITION_FACT: "chess.position-fact",
+  ENGINE_BOUNDED_CONTINUATION: "engine.bounded-continuation",
+  ENGINE_BOUNDED_COMPARISON: "engine.bounded-comparison",
+  ENGINE_BOUNDED_SCORE: "engine.bounded-score",
+  ENGINE_BOUNDED_RESPONSE_COVERAGE: "engine.bounded-response-coverage",
+  COVERAGE_EXHAUSTIVE: "coverage.exhaustive",
+  ATTENTION_AFFORDANCE: "attention.affordance",
+  SEMANTIC_REVIEWED_STATE: "semantic.reviewed-state",
+  WORKFLOW_AUDIT: "workflow.audit",
+} as const);
+
+export type EvidenceLicense = typeof EVIDENCE_LICENSE[keyof typeof EVIDENCE_LICENSE];
+
+const LICENSES = new Set<EvidenceLicense>(Object.values(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 function evidenceLicenseInput(record: LicensableEvidenceRecord): EvidenceLicenseInput {
+  const data = record.data || {};
+  const authority = typeof data.authority === "string"
+    ? data.authority
+    : record.kind === "fact"
+      ? "deterministic-derived"
+      : record.kind === "probe"
+        ? "bounded-engine"
+        : null;
+  return {
+    kind: record.kind,
+    source: record.source,
+    authority,
+    proofStrength: record.proofStrength,
+    data,
+    coverage: record.coverage || null,
+    replay: record.replay || null,
+  };
+}
+
+function exactSequenceOnly(input: EvidenceLicenseInput): boolean {
+  return input.data.scope === "sequence-legality-and-identity";
+}
+
+function isWorkflowKind(kind: string): boolean {
+  return kind === "observation-review"
+    || kind === "reasoning-challenge"
+    || kind === "hypothesis-review"
+    || kind === "critic-resolution-audit";
+}
+
+/**
+ * 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 function maximumEvidenceLicenses(input: EvidenceLicenseInput): EvidenceLicense[] {
+  // Authority is the source ceiling. A heuristic producer cannot self-upgrade
+  // by attaching a narrower-looking scope.
+  if (input.authority === "heuristic-affordance") return [EVIDENCE_LICENSE.ATTENTION_AFFORDANCE];
+  if (isWorkflowKind(input.kind)) return [EVIDENCE_LICENSE.WORKFLOW_AUDIT];
+  if (input.kind === "graph") return [EVIDENCE_LICENSE.SEMANTIC_REVIEWED_STATE];
+  // A replay witness explicitly scoped to legality and stable identity stays
+  // in that narrow authority lane even when it was transported as a probe.
+  // Record kind is transport metadata; it must not broaden the scope's
+  // evidentiary meaning into a bounded-engine continuation or score.
+  if (exactSequenceOnly(input)) {
+    if (input.authority !== "legal-exact" && input.authority !== "bounded-engine") return [];
+    const scoped = new Set<EvidenceLicense>([
+      EVIDENCE_LICENSE.CHESS_LEGALITY,
+      EVIDENCE_LICENSE.CHESS_IDENTITY,
+    ]);
+    if (input.coverage?.complete && input.coverage.unresolved.length === 0) {
+      scoped.add(EVIDENCE_LICENSE.COVERAGE_EXHAUSTIVE);
+    }
+    return [...scoped].sort();
+  }
+
+  const result = new Set<EvidenceLicense>();
+  if (input.authority === "legal-exact" || input.authority === "deterministic-derived") {
+    result.add(EVIDENCE_LICENSE.CHESS_LEGALITY);
+    result.add(EVIDENCE_LICENSE.CHESS_IDENTITY);
+    result.add(EVIDENCE_LICENSE.CHESS_POSITION_FACT);
+  }
+
+  if (input.authority === "bounded-engine") {
+    result.add(EVIDENCE_LICENSE.ENGINE_BOUNDED_SCORE);
+    if (/compare[_-]moves|compare-moves/.test(input.source)) {
+      result.add(EVIDENCE_LICENSE.ENGINE_BOUNDED_COMPARISON);
+    } else {
+      result.add(EVIDENCE_LICENSE.ENGINE_BOUNDED_CONTINUATION);
+    }
+    if (/enumerate[_-]defenses|enumerate-defenses/.test(input.source)) {
+      result.add(EVIDENCE_LICENSE.ENGINE_BOUNDED_RESPONSE_COVERAGE);
+    }
+    if (input.replay) {
+      result.add(EVIDENCE_LICENSE.CHESS_LEGALITY);
+      result.add(EVIDENCE_LICENSE.CHESS_IDENTITY);
+    }
+  }
+
+  if (input.coverage?.complete && input.coverage.unresolved.length === 0) {
+    result.add(EVIDENCE_LICENSE.COVERAGE_EXHAUSTIVE);
+  }
+  return [...result].sort();
+}
+
+export function validateEvidenceLicenseClaims(input: EvidenceLicenseInput, claimed: readonly unknown[]): EvidenceLicense[] {
+  if (!Array.isArray(claimed)) throw new Error("Evidence licenses must be an array");
+  const normalized = [...new Set(claimed.map(String))];
+  const unknown = normalized.filter((license) => !LICENSES.has(license as EvidenceLicense));
+  if (unknown.length) throw new Error(`Unknown evidence license(s): ${unknown.join(", ")}`);
+  const maximum = new Set(maximumEvidenceLicenses(input));
+  const excessive = normalized.filter((license) => !maximum.has(license as EvidenceLicense));
+  if (excessive.length) throw new Error(`Evidence claims license(s) beyond its source ceiling: ${excessive.join(", ")}`);
+  return normalized.sort() as EvidenceLicense[];
+}
+
+export function effectiveEvidenceLicenses(input: EvidenceLicenseInput & { licenses?: readonly unknown[] }): EvidenceLicense[] {
+  // Legacy development fixtures without an explicit field are normalized at
+  // admission. Runtime and provider-owned records always serialize the result.
+  return input.licenses === undefined
+    ? maximumEvidenceLicenses(input)
+    : validateEvidenceLicenseClaims(input, input.licenses);
+}
+
+export function effectiveLicensesForRecord(record: LicensableEvidenceRecord): EvidenceLicense[] {
+  return effectiveEvidenceLicenses({ ...evidenceLicenseInput(record), licenses: record.licenses });
+}
+
+export function withEvidenceLicenses<T extends LicensableEvidenceRecord>(record: T): T & { licenses: EvidenceLicense[] } {
+  return { ...record, licenses: effectiveLicensesForRecord(record) };
+}
+
+export function licensesSemanticChessGrounding(licenses: readonly EvidenceLicense[]): boolean {
+  return licenses.some((license) => license === EVIDENCE_LICENSE.CHESS_POSITION_FACT
+    || license === EVIDENCE_LICENSE.ENGINE_BOUNDED_CONTINUATION
+    || license === EVIDENCE_LICENSE.ENGINE_BOUNDED_COMPARISON
+    || license === EVIDENCE_LICENSE.ENGINE_BOUNDED_RESPONSE_COVERAGE
+    || license === EVIDENCE_LICENSE.SEMANTIC_REVIEWED_STATE);
+}
+
+export function licensesBoundedRouteRelevance(licenses: readonly EvidenceLicense[]): boolean {
+  return licenses.includes(EVIDENCE_LICENSE.ENGINE_BOUNDED_CONTINUATION)
+    || licenses.includes(EVIDENCE_LICENSE.ENGINE_BOUNDED_COMPARISON)
+    || licenses.includes(EVIDENCE_LICENSE.ENGINE_BOUNDED_RESPONSE_COVERAGE);
+}

package/src/chess-reasoning/evidence-selector-contract.ts

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