@knights-eye-chess/ai-analysis 0.1.0-dev.18 → 0.1.0-dev.24

package/NPM-PUBLISHING.md

@@ -2,9 +2,9 @@
 
 The owner authorized public npm prereleases on 10 October 2026. Use **`next`** and preserve any existing `latest` tag. Licensing is documented in [LICENSING.md](LICENSING.md).
 
-The first registry prerelease is `0.1.0-dev.14`. The source checkout now prepares
-`0.1.0-dev.17` with Move Classifier `0.1.0-dev.13`.
-This next candidate has not been published; `@next` remains the verified registry release.
+The first registry prerelease was `0.1.0-dev.14`. This checkout prepares the
+local `0.1.0-dev.24` candidate with Move Classifier `0.1.0-dev.16-board-offers.3`.
+This candidate has not been published; check the registry before relying on `@next`.
 
 ## Prepare the exact candidate
 
@@ -15,9 +15,9 @@ npm ci
 npm run publish:prepare
 ```
 
-Review `artifacts/knights-eye-chess-ai-analysis-0.1.0-dev.17.tgz`, including its files, exports, declarations, licenses and exact registry dependencies. Reusable source and offline owner tests are intentional; application traces, credentials, vendor archives and source lockfiles are excluded. The checkout stays `private: true`; publish only the staged archive. Archive contents are immutable: use a new version for changed bytes.
+Review `artifacts/knights-eye-chess-ai-analysis-0.1.0-dev.24.tgz`, including its files, exports, declarations, licenses and exact registry dependencies. Reusable source and offline owner tests are intentional; application traces, credentials, vendor archives and source lockfiles are excluded. The checkout stays `private: true`; publish only the staged archive. Archive contents are immutable: use a new version for changed bytes.
 
-Before every coordinated release, run `node tools/release-tooling/sync.mjs --check` in the reviewed app checkout alongside all six component revisions. Record those commits and the result.
+Before every coordinated release, run `node tools/release-tooling/sync.mjs --check` in the reviewed app checkout against its current component registry. Record the app and component commits and the result.
 
 ## Publish through GitHub Actions
 

package/build.mjs

@@ -4,7 +4,11 @@ import {readFileSync,writeFileSync,readdirSync,copyFileSync,rmSync} from 'node:f
 import {createRequire} from 'node:module';
 const require=createRequire(import.meta.url);
 rmSync('dist',{recursive:true,force:true});
-const result=await build({entryPoints:{index:'src/chess-reasoning/answer-pipeline-exports.ts',research:'src/chess-reasoning/research-exports.ts',shared:'src/shared-exports.ts'},bundle:true,format:'esm',platform:'neutral',target:'es2022',packages:'external',splitting:true,outdir:'dist',metafile:true});
+const result=await build({entryPoints:{index:'src/chess-reasoning/answer-pipeline-exports.ts',research:'src/chess-reasoning/research-exports.ts',shared:'src/shared-exports.ts',engine:'src/chess-reasoning/engine-analysis-provider.ts'},bundle:true,format:'esm',platform:'neutral',target:'es2022',packages:'external',splitting:true,outdir:'dist',metafile:true});
+const engine=await build({entryPoints:['src/chess-reasoning/engine-analysis-provider.ts'],bundle:true,format:'esm',platform:'neutral',target:'es2022',packages:'external',write:false,metafile:true});
+const engineImports=Object.values(engine.metafile.outputs).flatMap(output=>output.imports);
+if(engineImports.length)throw Error('Engine provider must have no runtime dependencies: '+engineImports.map(item=>item.path).join(', '));
+writeFileSync('dist/engine-runtime-closure.json',JSON.stringify({runtimeInputs:Object.keys(engine.metafile.inputs).sort(),externalImports:[]},null,2)+'\n');
 const shared=await build({entryPoints:['src/shared-exports.ts'],bundle:true,format:'esm',platform:'neutral',target:'es2022',packages:'external',write:false,metafile:true});
 const sharedImports=[...new Set(Object.values(shared.metafile.outputs).flatMap(output=>output.imports.filter(item=>item.external).map(item=>item.path)))];
 if(sharedImports.some(name=>name === 'ai' || name.startsWith('@ai-sdk/') || name.startsWith('@knights-eye-chess/move-classifier')))throw Error('Model or classifier runtime leaked into shared helpers: '+sharedImports.join(', '));

package/dist/chunk-AJJP7FYT.js

@@ -0,0 +1,59 @@
+// src/chess-reasoning/engine-analysis-provider.ts
+function createEngineAnalysisProvider(client) {
+  return { async analyze(request) {
+    request.signal?.throwIfAborted();
+    const result = await client.search({
+      fen: request.fen,
+      limit: { depth: request.depth },
+      multiPv: request.multiPv,
+      rootMoves: request.rootMoves,
+      ...request.rootMoves.length ? { requireRootCoverage: true } : {},
+      signal: request.signal
+    });
+    request.signal?.throwIfAborted();
+    const command = "go depth " + request.depth + (request.rootMoves.length ? " searchmoves " + request.rootMoves.join(" ") : "");
+    if (result.noMove === true) {
+      if (result.bestmove !== null || result.candidates.length !== 0 || !result.engineBuild) {
+        throw new Error("Invalid UCI no-move result.");
+      }
+      return {
+        engine: result.engineBuild,
+        engineBuild: result.engineBuild,
+        command,
+        bestMove: null,
+        cacheProvenance: "engine",
+        lines: [],
+        ...result.diagnostics ? { diagnostics: result.diagnostics } : {}
+      };
+    }
+    const build = result.candidates[0]?.scoreProvenance?.engineBuild;
+    if (typeof build !== "string" || !build) throw new Error("Engine returned no attributed build identity.");
+    if (!result.bestmove || result.bestmove !== result.candidates[0]?.pv[0] || result.engineBuild && result.engineBuild !== build || result.weightsId && result.weightsId !== result.candidates[0]?.scoreProvenance?.weightsId) {
+      throw new Error("Engine returned an incomplete or inconsistent best move.");
+    }
+    if (result.candidates.some((line) => line.scoreProvenance?.engineBuild !== build || line.scoreProvenance?.weightsId !== result.candidates[0]?.scoreProvenance?.weightsId)) {
+      throw new Error("Engine returned inconsistent build identity.");
+    }
+    return {
+      engine: build,
+      engineBuild: build,
+      command,
+      bestMove: result.bestmove,
+      cacheProvenance: "engine",
+      ...result.diagnostics ? { diagnostics: result.diagnostics } : {},
+      lines: result.candidates.map((candidate) => ({
+        rootMove: candidate.pv[0],
+        pv: candidate.pv,
+        depth: candidate.depth,
+        nodes: candidate.nodes ?? null,
+        scoreCp: candidate.scoreCp,
+        mateInMoves: candidate.mate,
+        scoreProvenance: candidate.scoreProvenance ? { ...candidate.scoreProvenance } : void 0
+      }))
+    };
+  } };
+}
+
+export {
+  createEngineAnalysisProvider
+};

package/dist/engine-runtime-closure.json

@@ -0,0 +1,6 @@
+{
+  "runtimeInputs": [
+    "src/chess-reasoning/engine-analysis-provider.ts"
+  ],
+  "externalImports": []
+}

package/dist/engine.js

@@ -0,0 +1,6 @@
+import {
+  createEngineAnalysisProvider
+} from "./chunk-AJJP7FYT.js";
+export {
+  createEngineAnalysisProvider
+};

package/dist/index.js

@@ -17,7 +17,7 @@ import {
   simpleSystemPolicy,
   simpleToolDescription,
   validateSimpleToolInput
-} from "./chunk-TYQ5WIL2.js";
+} from "./chunk-V6NM6RB2.js";
 import {
   DEFAULT_REASONING_RUN_CONTROLS,
   EVIDENCE_SHARING_VERSION,
@@ -72,6 +72,9 @@ import {
   validateReasoningPositionContext,
   validateSimpleAgentConfig
 } from "./chunk-6OXAG5H3.js";
+import {
+  createEngineAnalysisProvider
+} from "./chunk-AJJP7FYT.js";
 export {
   DEFAULT_REASONING_RUN_CONTROLS,
   EVIDENCE_SHARING_VERSION,
@@ -97,6 +100,7 @@ export {
   classifyReviewSubject,
   createContextEvidence,
   createDefaultSaliencePolicy,
+  createEngineAnalysisProvider,
   createNativeAnswerConnector,
   createPocToolHost,
   createProductionObservationProvider,

package/dist/owner-tests/engine-analysis-provider.test.mjs

@@ -0,0 +1,169 @@
+// test/owner/engine-analysis-provider.test.mjs
+import assert from "node:assert/strict";
+import { test } from "node:test";
+
+// src/chess-reasoning/engine-analysis-provider.ts
+function createEngineAnalysisProvider(client) {
+  return { async analyze(request2) {
+    request2.signal?.throwIfAborted();
+    const result = await client.search({
+      fen: request2.fen,
+      limit: { depth: request2.depth },
+      multiPv: request2.multiPv,
+      rootMoves: request2.rootMoves,
+      ...request2.rootMoves.length ? { requireRootCoverage: true } : {},
+      signal: request2.signal
+    });
+    request2.signal?.throwIfAborted();
+    const command = "go depth " + request2.depth + (request2.rootMoves.length ? " searchmoves " + request2.rootMoves.join(" ") : "");
+    if (result.noMove === true) {
+      if (result.bestmove !== null || result.candidates.length !== 0 || !result.engineBuild) {
+        throw new Error("Invalid UCI no-move result.");
+      }
+      return {
+        engine: result.engineBuild,
+        engineBuild: result.engineBuild,
+        command,
+        bestMove: null,
+        cacheProvenance: "engine",
+        lines: [],
+        ...result.diagnostics ? { diagnostics: result.diagnostics } : {}
+      };
+    }
+    const build = result.candidates[0]?.scoreProvenance?.engineBuild;
+    if (typeof build !== "string" || !build) throw new Error("Engine returned no attributed build identity.");
+    if (!result.bestmove || result.bestmove !== result.candidates[0]?.pv[0] || result.engineBuild && result.engineBuild !== build || result.weightsId && result.weightsId !== result.candidates[0]?.scoreProvenance?.weightsId) {
+      throw new Error("Engine returned an incomplete or inconsistent best move.");
+    }
+    if (result.candidates.some((line2) => line2.scoreProvenance?.engineBuild !== build || line2.scoreProvenance?.weightsId !== result.candidates[0]?.scoreProvenance?.weightsId)) {
+      throw new Error("Engine returned inconsistent build identity.");
+    }
+    return {
+      engine: build,
+      engineBuild: build,
+      command,
+      bestMove: result.bestmove,
+      cacheProvenance: "engine",
+      ...result.diagnostics ? { diagnostics: result.diagnostics } : {},
+      lines: result.candidates.map((candidate) => ({
+        rootMove: candidate.pv[0],
+        pv: candidate.pv,
+        depth: candidate.depth,
+        nodes: candidate.nodes ?? null,
+        scoreCp: candidate.scoreCp,
+        mateInMoves: candidate.mate,
+        scoreProvenance: candidate.scoreProvenance ? { ...candidate.scoreProvenance } : void 0
+      }))
+    };
+  } };
+}
+
+// test/owner/engine-analysis-provider.test.mjs
+var request = { fen: "root", depth: 18, multiPv: 3, rootMoves: [], minimumPvPlies: 10 };
+var line = (move, mate = null) => ({
+  pv: [move],
+  depth: 18,
+  nodes: 42,
+  scoreCp: mate === null ? 21 : null,
+  mate,
+  scoreProvenance: { kind: "root-search", engineBuild: "Stockfish test", fen: "root", originatingDepth: 18, reportedDepth: 18 }
+});
+test("maps one completed search without padding fewer lines or short PVs", async () => {
+  let calls = 0, received;
+  const candidates = [line("g7g8", -3), line("g7f7")];
+  const diagnostics = { processReused: true };
+  const provider = createEngineAnalysisProvider({ async search(input) {
+    calls++;
+    received = input;
+    return { bestmove: "g7g8", candidates, diagnostics };
+  } });
+  const result = await provider.analyze(request);
+  assert.equal(calls, 1);
+  assert.deepEqual(received, { fen: "root", limit: { depth: 18 }, multiPv: 3, rootMoves: [], signal: void 0 });
+  assert.equal(result.lines.length, 2);
+  assert.deepEqual(result.lines[0].pv, ["g7g8"]);
+  assert.equal(result.lines[0].mateInMoves, -3);
+  assert.equal(result.lines[0].scoreCp, null);
+  assert.equal(result.lines[0].nodes, 42);
+  assert.deepEqual(result.lines[0].scoreProvenance, candidates[0].scoreProvenance);
+  assert.equal(result.engineBuild, "Stockfish test");
+  assert.equal(result.cacheProvenance, "engine");
+  assert.equal(result.diagnostics, diagnostics);
+});
+test("preserves restricted roots and cancellation instead of changing search scope", async () => {
+  const controller = new AbortController();
+  let received;
+  const provider = createEngineAnalysisProvider({ async search(input) {
+    received = input;
+    return { bestmove: "g7g8", candidates: [line("g7g8")] };
+  } });
+  const result = await provider.analyze({ ...request, multiPv: 1, rootMoves: ["g7g8"], signal: controller.signal });
+  assert.equal(received.signal, controller.signal);
+  assert.deepEqual(received.rootMoves, ["g7g8"]);
+  assert.equal(received.requireRootCoverage, true);
+  assert.equal(result.command, "go depth 18 searchmoves g7g8");
+  controller.abort();
+  await assert.rejects(provider.analyze({ ...request, signal: controller.signal }), { name: "AbortError" });
+});
+test("explicit comparison requires every requested root from the engine client", async () => {
+  const required = ["g7g8", "g7f7"];
+  let seen;
+  const client = { async search(input) {
+    seen = input;
+    const candidates = [line("g7g8")];
+    if (input.requireRootCoverage && input.rootMoves.some((root) => !candidates.some((candidate) => candidate.pv[0] === root)))
+      throw new Error("UCI engine did not complete requested score and root coverage.");
+    return { bestmove: "g7g8", candidates };
+  } };
+  const provider = createEngineAnalysisProvider(client);
+  await assert.rejects(provider.analyze({ ...request, multiPv: 2, rootMoves: required }), /root coverage/);
+  assert.deepEqual(seen.rootMoves, required);
+  assert.equal(seen.requireRootCoverage, true);
+  const unrestricted = await provider.analyze({ ...request, multiPv: 2, rootMoves: [] });
+  assert.equal(seen.requireRootCoverage, void 0);
+  assert.equal(unrestricted.lines.length, 1);
+});
+test("does not turn a cancelled or failed engine search into evidence", async () => {
+  const controller = new AbortController();
+  const provider = createEngineAnalysisProvider({ async search() {
+    controller.abort();
+    return { candidates: [line("g7g8")] };
+  } });
+  await assert.rejects(provider.analyze({ ...request, signal: controller.signal }), { name: "AbortError" });
+  const failure = new Error("engine failed");
+  await assert.rejects(createEngineAnalysisProvider({ async search() {
+    throw failure;
+  } }).analyze(request), (error) => error === failure);
+});
+test("requires an attributed single engine result", async () => {
+  for (const candidates of [[line("g7g8"), { ...line("g7f7"), scoreProvenance: { ...line("g7f7").scoreProvenance, weightsId: "different" } }], [{ ...line("g7g8"), scoreProvenance: void 0 }], [line("g7g8"), { ...line("g7f7"), scoreProvenance: { engineBuild: "other" } }]]) {
+    await assert.rejects(createEngineAnalysisProvider({ async search() {
+      return { bestmove: "g7g8", candidates };
+    } }).analyze(request), /identity/);
+  }
+});
+test("explicit no-move result carries engine identity without inventing a score", async () => {
+  const provider = createEngineAnalysisProvider({ async search() {
+    return { noMove: true, bestmove: null, candidates: [], engineBuild: "Stockfish test" };
+  } });
+  const result = await provider.analyze(request);
+  assert.equal(result.bestMove, null);
+  assert.deepEqual(result.lines, []);
+  assert.equal(result.engineBuild, "Stockfish test");
+  for (const malformed of [
+    { noMove: true, bestmove: null, candidates: [], engineBuild: "" },
+    { noMove: true, bestmove: "e2e4", candidates: [], engineBuild: "Stockfish test" },
+    { noMove: true, bestmove: null, candidates: [line("e2e4")], engineBuild: "Stockfish test" }
+  ]) {
+    await assert.rejects(createEngineAnalysisProvider({ async search() {
+      return malformed;
+    } }).analyze(request), /no-move/);
+  }
+});
+test("scored search requires an explicit completed best move", async () => {
+  for (const bestmove of [void 0, "d2d4"]) {
+    await assert.rejects(createEngineAnalysisProvider({ async search() {
+      return { bestmove, candidates: [line("e2e4")] };
+    } }).analyze(request), /best move/);
+  }
+});

package/dist/research.js

@@ -211,7 +211,7 @@ import {
   wikibooksTargetsForTool,
   withBranchPreparation,
   withRecordedPositionTools
-} from "./chunk-TYQ5WIL2.js";
+} from "./chunk-V6NM6RB2.js";
 import {
   CHESS_REASONING_POLICY_VERSION,
   CHESS_REASONING_SCHEMA_VERSION,
@@ -317,6 +317,9 @@ import {
   validateSimpleAgentConfig,
   withEvidenceLicenses
 } from "./chunk-6OXAG5H3.js";
+import {
+  createEngineAnalysisProvider
+} from "./chunk-AJJP7FYT.js";
 
 // src/chess-reasoning/ablation-direct-synthesis.ts
 import { SQUARES } from "chess.js";
@@ -2119,6 +2122,7 @@ export {
   createContextEvidence,
   createDefaultObservationProvider,
   createDefaultSaliencePolicy,
+  createEngineAnalysisProvider,
   createIdeaGraph,
   createIdentityState,
   createMechanicalFactRequest,

package/dist/runtime-closure.json

@@ -26,6 +26,7 @@
     "src/chess-reasoning/compact-search-preparation.ts",
     "src/chess-reasoning/concept-registry.ts",
     "src/chess-reasoning/conversation-context.ts",
+    "src/chess-reasoning/engine-analysis-provider.ts",
     "src/chess-reasoning/engine-search-failure.ts",
     "src/chess-reasoning/evidence-citation-normalization.ts",
     "src/chess-reasoning/evidence-licenses.ts",
@@ -99,5 +100,5 @@
     "@ai-sdk/provider",
     "@ai-sdk/provider-utils"
   ],
-  "runtimeBytes": 969134
+  "runtimeBytes": 971929
 }

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

@@ -9,6 +9,8 @@ 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 { createEngineAnalysisProvider } from './engine-analysis-provider.js';
+export type { AnalysisEngineClient } from './engine-analysis-provider.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';

package/dist/types/chess-reasoning/engine-analysis-provider.d.ts

@@ -0,0 +1,42 @@
+import type { PositionAnalysisProvider } from './position-analysis-contracts.js';
+/** Consumer-owned structural contract. No dependency on an engine implementation. */
+export type AnalysisEngineClient = {
+    search(request: {
+        fen: string;
+        limit: {
+            depth: number;
+        };
+        multiPv: number;
+        rootMoves: string[];
+        requireRootCoverage?: boolean;
+        signal?: AbortSignal;
+    }): Promise<({
+        noMove?: false;
+        bestmove: string;
+        engineBuild?: string;
+        weightsId?: string;
+        candidates: Array<{
+            pv: string[];
+            depth: number;
+            nodes?: number | null;
+            scoreCp: number | null;
+            mate: number | null;
+            scoreProvenance?: {
+                engineBuild: string;
+                weightsId?: string;
+            };
+        }>;
+    } | {
+        noMove: true;
+        bestmove: null;
+        candidates: [];
+        engineBuild: string;
+        weightsId?: string;
+    }) & {
+        diagnostics?: unknown;
+    }>;
+};
+/** Adapt a host-owned depth-search client without acquiring or closing it.
+ * Short PVs remain short; evidence admission stays with the existing consumers.
+ */
+export declare function createEngineAnalysisProvider(client: AnalysisEngineClient): PositionAnalysisProvider;

package/docs/API.md

@@ -89,3 +89,27 @@ An unrestricted completed search can return one through that many valid lines;
 the original requested count remains in the witness even when fewer lines arrive.
 Explicit `rootMoves` searches must still cover their entire requested root set.
 Depth, score, provenance, distinct-root and legal-PV checks remain unchanged.
+
+## Host-owned engine clients
+
+`createEngineAnalysisProvider(client)` is exported from the package root and the
+small `@knights-eye-chess/ai-analysis/engine` entry point. The latter imports no
+model SDK or engine implementation. AI Analysis declares its own structural
+`AnalysisEngineClient` contract; the host wires a compatible implementation.
+
+The adapter translates a depth request to `limit: { depth }` and maps completed
+engine candidates to AI lines without changing scores, mate units, achieved depth,
+PV length or provenance. A valid result can contain fewer lines than requested.
+Engine/weights identity remains attributed; different engines are not blended.
+This is not evidence admission or a calibration of another engine's scores for
+the Knight's Eye classifier. Nodes/time-limited human-likelihood evidence needs
+its own consumer contract rather than masquerading as depth-search evidence.
+
+The host owns lifecycle and closes the client. `minimumPvPlies` does not make this
+adapter perform extra searches or pad PVs. Existing downstream admission and
+continuation handling remain responsible for evidence use.
+Scored results require an explicit completed `bestmove` matching the first scored
+root. An explicit `noMove: true` result with empty candidates, `bestmove: null`,
+and top-level `engineBuild` maps to no scored lines and a null best move. This is
+only a UCI no-move report: the host checks legal moves at the FEN before claiming
+checkmate, stalemate, or another chess terminal condition.

package/npm-release.json

@@ -1,5 +1,5 @@
 {
   "registryDependencies": {
-    "@knights-eye-chess/move-classifier": "0.1.0-dev.14"
+    "@knights-eye-chess/move-classifier": "0.1.0-dev.16-board-offers.3"
   }
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@knights-eye-chess/ai-analysis",
-  "version": "0.1.0-dev.18",
+  "version": "0.1.0-dev.24",
   "type": "module",
   "files": [
     "dist",
@@ -33,6 +33,10 @@
     "./shared": {
       "types": "./dist/types/shared-exports.d.ts",
       "import": "./dist/shared.js"
+    },
+    "./engine": {
+      "types": "./dist/types/chess-reasoning/engine-analysis-provider.d.ts",
+      "import": "./dist/engine.js"
     }
   },
   "scripts": {
@@ -51,7 +55,7 @@
   "dependencies": {
     "@ai-sdk/provider": "4.0.9",
     "@ai-sdk/provider-utils": "5.0.34",
-    "@knights-eye-chess/move-classifier": "0.1.0-dev.14",
+    "@knights-eye-chess/move-classifier": "0.1.0-dev.16-board-offers.3",
     "@types/json-schema": "7.0.15",
     "@types/node": "22.19.19",
     "ai": "7.0.85",

package/src/chess-reasoning/answer-pipeline-exports.ts

@@ -9,6 +9,8 @@ export {createPocToolHost} from './answer-tool-host';
 export type {AnswerToolHostOptions} from './answer-tool-host';
 export type {PositionAnalysisProvider,PositionAnalysisRequest,PositionAnalysisResult,PositionAnalysisLine,PositionAnalysisSegment,CompatiblePositionAnalysisProvider,LegacyPositionAnalysisProvider,LegacyPositionAnalysisResult,LegacyPositionAnalysisLine} from './position-analysis-contracts';
 export {toPositionAnalysis,toLegacyPositionAnalysis,toPositionAnalysisProvider,toLegacyPositionAnalysisProvider} from './position-analysis-contracts';
+export {createEngineAnalysisProvider} from './engine-analysis-provider';
+export type {AnalysisEngineClient} from './engine-analysis-provider';
 export {createProductionObservationProvider} from './production-observation-provider';
 export {validateReasoningPositionContext,reasoningContextHash,createContextEvidence,createQueryContract,DEFAULT_REASONING_RUN_CONTROLS,REASONING_POC_VERSION} from './poc-contracts';
 export type {ReasoningPositionContext,ReasoningToolSet,ObservationProvider,ReasoningEvidenceRecord} from './poc-contracts';

package/src/chess-reasoning/engine-analysis-provider.ts

@@ -0,0 +1,62 @@
+import type { PositionAnalysisProvider, PositionAnalysisResult } from './position-analysis-contracts';
+
+/** Consumer-owned structural contract. No dependency on an engine implementation. */
+export type AnalysisEngineClient = {
+  search(request: {
+    fen: string; limit: { depth: number }; multiPv: number; rootMoves: string[];
+    requireRootCoverage?: boolean; signal?: AbortSignal;
+  }): Promise<({
+    noMove?: false; bestmove: string; engineBuild?: string; weightsId?: string;
+    candidates: Array<{
+      pv: string[]; depth: number; nodes?: number | null; scoreCp: number | null; mate: number | null;
+      scoreProvenance?: { engineBuild: string; weightsId?: string };
+    }>;
+  } | {
+    noMove: true; bestmove: null; candidates: []; engineBuild: string; weightsId?: string;
+  }) & { diagnostics?: unknown }>;
+};
+
+/** Adapt a host-owned depth-search client without acquiring or closing it.
+ * Short PVs remain short; evidence admission stays with the existing consumers.
+ */
+export function createEngineAnalysisProvider(client: AnalysisEngineClient): PositionAnalysisProvider {
+  return { async analyze(request): Promise<PositionAnalysisResult> {
+    request.signal?.throwIfAborted();
+    const result = await client.search({ fen: request.fen, limit: { depth: request.depth },
+      multiPv: request.multiPv, rootMoves: request.rootMoves,
+      ...(request.rootMoves.length ? { requireRootCoverage: true } : {}), signal: request.signal });
+    request.signal?.throwIfAborted();
+    const command = 'go depth ' + request.depth + (request.rootMoves.length ? ' searchmoves ' + request.rootMoves.join(' ') : '');
+    if (result.noMove === true) {
+      if (result.bestmove !== null || result.candidates.length !== 0 || !result.engineBuild) {
+        throw new Error('Invalid UCI no-move result.');
+      }
+      // A UCI no-move report is unscored; the host must check the legal board
+      // before interpreting it as checkmate, stalemate, or another terminal.
+      return { engine: result.engineBuild, engineBuild: result.engineBuild, command,
+        bestMove: null, cacheProvenance: 'engine', lines: [],
+        ...(result.diagnostics ? { diagnostics: result.diagnostics } : {}) };
+    }
+    const build = result.candidates[0]?.scoreProvenance?.engineBuild;
+    if (typeof build !== 'string' || !build) throw new Error('Engine returned no attributed build identity.');
+    if (!result.bestmove || result.bestmove !== result.candidates[0]?.pv[0] ||
+      (result.engineBuild && result.engineBuild !== build) ||
+      (result.weightsId && result.weightsId !== result.candidates[0]?.scoreProvenance?.weightsId)) {
+      throw new Error('Engine returned an incomplete or inconsistent best move.');
+    }
+    // A provider result represents one engine search, not a blend of engines.
+    if (result.candidates.some(line => line.scoreProvenance?.engineBuild !== build ||
+      line.scoreProvenance?.weightsId !== result.candidates[0]?.scoreProvenance?.weightsId)) {
+      throw new Error('Engine returned inconsistent build identity.');
+    }
+    return {
+      engine: build, engineBuild: build,
+      command, bestMove: result.bestmove,
+      cacheProvenance: 'engine',
+      ...(result.diagnostics ? { diagnostics: result.diagnostics } : {}),
+      lines: result.candidates.map(candidate => ({ rootMove: candidate.pv[0], pv: candidate.pv,
+        depth: candidate.depth, nodes: candidate.nodes ?? null, scoreCp: candidate.scoreCp,
+        mateInMoves: candidate.mate, scoreProvenance: candidate.scoreProvenance ? { ...candidate.scoreProvenance } : undefined })),
+    };
+  } };
+}

package/test/owner/engine-analysis-provider.test.mjs

@@ -0,0 +1,70 @@
+import assert from 'node:assert/strict';
+import {test} from 'node:test';
+import {createEngineAnalysisProvider} from '../../src/chess-reasoning/engine-analysis-provider.ts';
+const request={fen:'root',depth:18,multiPv:3,rootMoves:[],minimumPvPlies:10};
+const line=(move,mate=null)=>({pv:[move],depth:18,nodes:42,scoreCp:mate===null?21:null,mate,
+ scoreProvenance:{kind:'root-search',engineBuild:'Stockfish test',fen:'root',originatingDepth:18,reportedDepth:18}});
+test('maps one completed search without padding fewer lines or short PVs',async()=>{
+ let calls=0,received;
+ const candidates=[line('g7g8',-3),line('g7f7')];
+ const diagnostics={processReused:true};
+ const provider=createEngineAnalysisProvider({async search(input){calls++;received=input;return{bestmove:'g7g8',candidates,diagnostics};}});
+ const result=await provider.analyze(request);
+ assert.equal(calls,1);assert.deepEqual(received,{fen:'root',limit:{depth:18},multiPv:3,rootMoves:[],signal:undefined});
+ assert.equal(result.lines.length,2);assert.deepEqual(result.lines[0].pv,['g7g8']);
+ assert.equal(result.lines[0].mateInMoves,-3);assert.equal(result.lines[0].scoreCp,null);
+ assert.equal(result.lines[0].nodes,42);assert.deepEqual(result.lines[0].scoreProvenance,candidates[0].scoreProvenance);
+ assert.equal(result.engineBuild,'Stockfish test');assert.equal(result.cacheProvenance,'engine');assert.equal(result.diagnostics,diagnostics);
+});
+test('preserves restricted roots and cancellation instead of changing search scope',async()=>{
+ const controller=new AbortController();let received;
+ const provider=createEngineAnalysisProvider({async search(input){received=input;return{bestmove:'g7g8',candidates:[line('g7g8')]};}});
+ const result=await provider.analyze({...request,multiPv:1,rootMoves:['g7g8'],signal:controller.signal});
+ assert.equal(received.signal,controller.signal);assert.deepEqual(received.rootMoves,['g7g8']);
+ assert.equal(received.requireRootCoverage,true);
+ assert.equal(result.command,'go depth 18 searchmoves g7g8');
+ controller.abort();await assert.rejects(provider.analyze({...request,signal:controller.signal}),{name:'AbortError'});
+});
+test('explicit comparison requires every requested root from the engine client',async()=>{
+ const required=['g7g8','g7f7'];let seen;
+ const client={async search(input){
+  seen=input;
+  const candidates=[line('g7g8')];
+  if(input.requireRootCoverage && input.rootMoves.some(root=>!candidates.some(candidate=>candidate.pv[0]===root)))
+   throw new Error('UCI engine did not complete requested score and root coverage.');
+  return {bestmove:'g7g8',candidates};
+ }};
+ const provider=createEngineAnalysisProvider(client);
+ await assert.rejects(provider.analyze({...request,multiPv:2,rootMoves:required}),/root coverage/);
+ assert.deepEqual(seen.rootMoves,required);assert.equal(seen.requireRootCoverage,true);
+ const unrestricted=await provider.analyze({...request,multiPv:2,rootMoves:[]});
+ assert.equal(seen.requireRootCoverage,undefined);assert.equal(unrestricted.lines.length,1);
+});
+test('does not turn a cancelled or failed engine search into evidence',async()=>{
+ const controller=new AbortController();
+ const provider=createEngineAnalysisProvider({async search(){controller.abort();return{candidates:[line('g7g8')]};}});
+ await assert.rejects(provider.analyze({...request,signal:controller.signal}),{name:'AbortError'});
+ const failure=new Error('engine failed');
+ await assert.rejects(createEngineAnalysisProvider({async search(){throw failure;}}).analyze(request),error=>error===failure);
+});
+test('requires an attributed single engine result',async()=>{
+ for(const candidates of [[line('g7g8'),{...line('g7f7'),scoreProvenance:{...line('g7f7').scoreProvenance,weightsId:'different'}}],[{...line('g7g8'),scoreProvenance:undefined}],[line('g7g8'),{...line('g7f7'),scoreProvenance:{engineBuild:'other'}}]]){
+  await assert.rejects(createEngineAnalysisProvider({async search(){return{bestmove:'g7g8',candidates};}}).analyze(request),/identity/);
+ }
+});
+test('explicit no-move result carries engine identity without inventing a score',async()=>{
+ const provider=createEngineAnalysisProvider({async search(){return{noMove:true,bestmove:null,candidates:[],engineBuild:'Stockfish test'};}});
+ const result=await provider.analyze(request);
+ assert.equal(result.bestMove,null);assert.deepEqual(result.lines,[]);
+ assert.equal(result.engineBuild,'Stockfish test');
+ for(const malformed of [{noMove:true,bestmove:null,candidates:[],engineBuild:''},
+  {noMove:true,bestmove:'e2e4',candidates:[],engineBuild:'Stockfish test'},
+  {noMove:true,bestmove:null,candidates:[line('e2e4')],engineBuild:'Stockfish test'}]) {
+  await assert.rejects(createEngineAnalysisProvider({async search(){return malformed;}}).analyze(request),/no-move/);
+ }
+});
+test('scored search requires an explicit completed best move',async()=>{
+ for(const bestmove of [undefined,'d2d4']) {
+  await assert.rejects(createEngineAnalysisProvider({async search(){return{bestmove,candidates:[line('e2e4')]};}}).analyze(request),/best move/);
+ }
+});

package/test-types.mts

@@ -21,3 +21,8 @@ const oldAsCurrent:PositionAnalysisResult=old;
 const badMate:PositionAnalysisResult={...modern,lines:[{...modern.lines[0],mateInMoves:'3'}]};
 void runAnswerPipeline({connector,requestId:'parallel',question:'x',selected:selection,bridge:history,analyzer,preparationAnalyzer:analyzer,parallelPreparation:true,observationProvider:createProductionObservationProvider({context:selection.context}),prepareRouting:async()=>({question:'x',selectionKey:'x',deliveryId:'x',elapsedMs:0,omitSelectedContext:false,decision:{version:QUESTION_ROUTING_VERSION,status:'fallback',omitSelectedContext:false,includeGameRecord:false,reviewGame:false,reason:'explicit'}})});
 void analyzer;void oldAsCurrent;void badMate;
+
+import {createEngineAnalysisProvider,type AnalysisEngineClient} from '@knights-eye-chess/ai-analysis/engine';
+const engineClient:AnalysisEngineClient={async search(request){return{bestmove:'e2e4',candidates:[{pv:['e2e4'],depth:request.limit.depth,scoreCp:20,mate:null,scoreProvenance:{engineBuild:'test'}}]};}};
+const engineProvider:PositionAnalysisProvider=createEngineAnalysisProvider(engineClient);
+void engineProvider;