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

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.21` candidate with Move Classifier `0.1.0-dev.15`.
+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.21.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-XQDZJOYD.js → chunk-6OXAG5H3.js}

@@ -1284,7 +1284,7 @@ function rejectionReason(context, hash, witness) {
   if (witness.authority !== "bounded-engine" || !Array.isArray(witness.licenses) || witness.licenses.length !== 1 || witness.licenses[0] !== "engine.bounded-continuation") return "missing-authority-license";
   if (witness.contextHash !== hash) return "context-mismatch";
   if (!["before", "after"].includes(witness.phase) || witness.fen !== (witness.phase === "before" ? context.fenBefore : context.fenAfter)) return "root-mismatch";
-  if (typeof witness.engineBuild !== "string" || !witness.engineBuild || typeof witness.command !== "string" || !witness.command || !positiveInteger(witness.requestedDepth) || !positiveInteger(witness.multiPv) || witness.multiPv > 32 || !Array.isArray(witness.lines) || witness.lines.length !== witness.multiPv || !Array.isArray(witness.rootMoves) || witness.rootMoves.length > 32 || witness.rootMoves.some((root) => typeof root !== "string" || !UCI.test(root)) || new Set(witness.rootMoves).size !== witness.rootMoves.length) return "invalid-search-scope";
+  if (typeof witness.engineBuild !== "string" || !witness.engineBuild || typeof witness.command !== "string" || !witness.command || !positiveInteger(witness.requestedDepth) || !positiveInteger(witness.multiPv) || witness.multiPv > 32 || !Array.isArray(witness.lines) || witness.lines.length < 1 || witness.lines.length > witness.multiPv || !Array.isArray(witness.rootMoves) || witness.rootMoves.length > 32 || witness.rootMoves.some((root) => typeof root !== "string" || !UCI.test(root)) || new Set(witness.rootMoves).size !== witness.rootMoves.length) return "invalid-search-scope";
   if (witness.lines.some((line) => !line || typeof line.rootMove !== "string")) return "invalid-pv";
   const roots = witness.lines.map((line) => line.rootMove);
   if (new Set(roots).size !== roots.length || witness.rootMoves.some((root) => !roots.includes(root)) || witness.rootMoves.length > 0 && roots.some((root) => !witness.rootMoves.includes(root))) return "root-set-mismatch";

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/{chunk-PLKNJRPF.js → chunk-V6NM6RB2.js}

@@ -50,7 +50,7 @@ import {
   validateEvidenceLicenseClaims,
   validateReasoningPositionContext,
   withEvidenceLicenses
-} from "./chunk-XQDZJOYD.js";
+} from "./chunk-6OXAG5H3.js";
 
 // src/chess-reasoning/branch-expansion-policy.ts
 var BRANCH_EXPANSION_OPTIONS = { maxNodes: 8, maxPlies: 4, maxLines: 2, depthFloor: 14, depthMode: "decreasing", maxElapsedMs: 2e4 };

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-PLKNJRPF.js";
+} from "./chunk-V6NM6RB2.js";
 import {
   DEFAULT_REASONING_RUN_CONTROLS,
   EVIDENCE_SHARING_VERSION,
@@ -71,7 +71,10 @@ import {
   toPositionAnalysisProvider,
   validateReasoningPositionContext,
   validateSimpleAgentConfig
-} from "./chunk-XQDZJOYD.js";
+} 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/owner-tests/pipeline-host-preparation.test.mjs

@@ -5879,7 +5879,7 @@ function rejectionReason(context2, hash, witness) {
   if (witness.authority !== "bounded-engine" || !Array.isArray(witness.licenses) || witness.licenses.length !== 1 || witness.licenses[0] !== "engine.bounded-continuation") return "missing-authority-license";
   if (witness.contextHash !== hash) return "context-mismatch";
   if (!["before", "after"].includes(witness.phase) || witness.fen !== (witness.phase === "before" ? context2.fenBefore : context2.fenAfter)) return "root-mismatch";
-  if (typeof witness.engineBuild !== "string" || !witness.engineBuild || typeof witness.command !== "string" || !witness.command || !positiveInteger(witness.requestedDepth) || !positiveInteger(witness.multiPv) || witness.multiPv > 32 || !Array.isArray(witness.lines) || witness.lines.length !== witness.multiPv || !Array.isArray(witness.rootMoves) || witness.rootMoves.length > 32 || witness.rootMoves.some((root) => typeof root !== "string" || !UCI.test(root)) || new Set(witness.rootMoves).size !== witness.rootMoves.length) return "invalid-search-scope";
+  if (typeof witness.engineBuild !== "string" || !witness.engineBuild || typeof witness.command !== "string" || !witness.command || !positiveInteger(witness.requestedDepth) || !positiveInteger(witness.multiPv) || witness.multiPv > 32 || !Array.isArray(witness.lines) || witness.lines.length < 1 || witness.lines.length > witness.multiPv || !Array.isArray(witness.rootMoves) || witness.rootMoves.length > 32 || witness.rootMoves.some((root) => typeof root !== "string" || !UCI.test(root)) || new Set(witness.rootMoves).size !== witness.rootMoves.length) return "invalid-search-scope";
   if (witness.lines.some((line) => !line || typeof line.rootMove !== "string")) return "invalid-pv";
   const roots = witness.lines.map((line) => line.rootMove);
   if (new Set(roots).size !== roots.length || witness.rootMoves.some((root) => !roots.includes(root)) || witness.rootMoves.length > 0 && roots.some((root) => !witness.rootMoves.includes(root))) return "root-set-mismatch";

package/dist/owner-tests/prose-reference-admission.test.mjs

@@ -1037,7 +1037,7 @@ function rejectionReason(context, hash, witness) {
   if (witness.authority !== "bounded-engine" || !Array.isArray(witness.licenses) || witness.licenses.length !== 1 || witness.licenses[0] !== "engine.bounded-continuation") return "missing-authority-license";
   if (witness.contextHash !== hash) return "context-mismatch";
   if (!["before", "after"].includes(witness.phase) || witness.fen !== (witness.phase === "before" ? context.fenBefore : context.fenAfter)) return "root-mismatch";
-  if (typeof witness.engineBuild !== "string" || !witness.engineBuild || typeof witness.command !== "string" || !witness.command || !positiveInteger(witness.requestedDepth) || !positiveInteger(witness.multiPv) || witness.multiPv > 32 || !Array.isArray(witness.lines) || witness.lines.length !== witness.multiPv || !Array.isArray(witness.rootMoves) || witness.rootMoves.length > 32 || witness.rootMoves.some((root) => typeof root !== "string" || !UCI.test(root)) || new Set(witness.rootMoves).size !== witness.rootMoves.length) return "invalid-search-scope";
+  if (typeof witness.engineBuild !== "string" || !witness.engineBuild || typeof witness.command !== "string" || !witness.command || !positiveInteger(witness.requestedDepth) || !positiveInteger(witness.multiPv) || witness.multiPv > 32 || !Array.isArray(witness.lines) || witness.lines.length < 1 || witness.lines.length > witness.multiPv || !Array.isArray(witness.rootMoves) || witness.rootMoves.length > 32 || witness.rootMoves.some((root) => typeof root !== "string" || !UCI.test(root)) || new Set(witness.rootMoves).size !== witness.rootMoves.length) return "invalid-search-scope";
   if (witness.lines.some((line) => !line || typeof line.rootMove !== "string")) return "invalid-pv";
   const roots = witness.lines.map((line) => line.rootMove);
   if (new Set(roots).size !== roots.length || witness.rootMoves.some((root) => !roots.includes(root)) || witness.rootMoves.length > 0 && roots.some((root) => !witness.rootMoves.includes(root))) return "root-set-mismatch";
@@ -1768,3 +1768,54 @@ test("fresh answer witnesses preserve shipped v22 reference geometry and reject
   assert.equal(rejected.referenceGapCounts.unresolvedReferences, 1);
   assert.equal(rejected.blocks[0].tokens[0].reference, void 0);
 });
+test("completed unrestricted MultiPV witnesses accept fewer lines without changing requested scope", () => {
+  const fen = "7r/p1p1p1kp/2p2rpQ/3q4/3P4/2P5/P1P2PP1/R3K2R b KQ - 5 18";
+  const context = { kind: "position", nodeId: "two-legal", historyStartFen: fen, historyUci: [], moveUci: "", moveSan: "", fenBefore: fen, fenAfter: fen };
+  const roots = ["g7g8", "g7f7"];
+  assert.deepEqual(new Set(new Chess34(fen).moves({ verbose: true }).map((m) => m.from + m.to)), new Set(roots));
+  const witness = {
+    version: "fresh-engine-pv-witness/1",
+    acquisition: "same-answer-engine",
+    acquisitionId: 1,
+    evidenceId: "server-engine-acquisition:two-legal",
+    contextHash: reasoningContextHash(context),
+    phase: "before",
+    fen,
+    engineBuild: "test-engine",
+    command: "go depth 18",
+    requestedDepth: 18,
+    multiPv: 3,
+    rootMoves: [],
+    authority: "bounded-engine",
+    licenses: ["engine.bounded-continuation"],
+    lines: roots.map((rootMove, index) => ({
+      rootMove,
+      pv: [rootMove],
+      depth: 18,
+      scoreCp: -200 - index,
+      mateInMoves: null,
+      scoreProvenance: { kind: "root-search", fen, engineBuild: "test-engine", command: "go depth 18", originatingDepth: 18, reportedDepth: 18 }
+    }))
+  };
+  const admitted = admitFreshEnginePvWitnesses(context, [witness]);
+  assert.equal(admitted.audit.acceptedLines, 2);
+  assert.equal(witness.multiPv, 3, "requested MultiPV remains provenance, not returned-line count");
+  assert.equal(admitFreshEnginePvWitnesses(context, [{ ...witness, lines: [witness.lines[0]] }]).audit.acceptedLines, 1);
+  for (const patch of [{ lines: [] }, { multiPv: 1 }, { rootMoves: roots, lines: [witness.lines[0]] }]) {
+    assert.equal(admitFreshEnginePvWitnesses(context, [{ ...witness, ...patch }]).audit.acceptedLines, 0);
+  }
+  for (const change of [(line) => {
+    line.depth = 17;
+  }, (line) => {
+    line.scoreCp = null;
+  }, (line) => {
+    line.pv = ["g7g6"];
+  }]) {
+    const invalid = structuredClone(witness);
+    change(invalid.lines[1]);
+    assert.equal(admitFreshEnginePvWitnesses(context, [invalid]).audit.acceptedLines, 0);
+  }
+  const rendered = simpleProseReferences("[Kg8](move:before:g7g8)", context, [], void 0, void 0, void 0, { freshEnginePvWitnesses: [witness] });
+  assert.equal(rendered.referenceGapCounts.unresolvedReferences, 0);
+  assert.equal(rendered.freshEnginePvAdmission.acceptedLines, 2);
+});

package/dist/research.js

@@ -211,7 +211,7 @@ import {
   wikibooksTargetsForTool,
   withBranchPreparation,
   withRecordedPositionTools
-} from "./chunk-PLKNJRPF.js";
+} from "./chunk-V6NM6RB2.js";
 import {
   CHESS_REASONING_POLICY_VERSION,
   CHESS_REASONING_SCHEMA_VERSION,
@@ -316,7 +316,10 @@ import {
   validateReasoningPositionContext,
   validateSimpleAgentConfig,
   withEvidenceLicenses
-} from "./chunk-XQDZJOYD.js";
+} 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": 969108
+  "runtimeBytes": 971929
 }

package/dist/shared.js

@@ -62,7 +62,7 @@ import {
   toPositionAnalysisProvider,
   validateReasoningPositionContext,
   validateSimpleAgentConfig
-} from "./chunk-XQDZJOYD.js";
+} from "./chunk-6OXAG5H3.js";
 
 // src/player-perspective.ts
 function normalizedPlayerName(value) {

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

@@ -80,3 +80,36 @@ remain in the canonical tool wrappers and host.
 
 
 See the [pipeline source](../src/chess-reasoning/answer-pipeline.ts) and [connector contract](../src/chess-reasoning/answer-model-connector.ts).
+
+
+### Completed MultiPV results
+
+Fresh engine presentation witnesses interpret `multiPv` as the requested maximum.
+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.13"
+    "@knights-eye-chess/move-classifier": "0.1.0-dev.15"
   }
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@knights-eye-chess/ai-analysis",
-  "version": "0.1.0-dev.17",
+  "version": "0.1.0-dev.21",
   "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.13",
+    "@knights-eye-chess/move-classifier": "0.1.0-dev.15",
     "@types/json-schema": "7.0.15",
     "@types/node": "22.19.19",
     "ai": "7.0.85",

package/scripts/check-release-tooling.mjs

@@ -7,7 +7,7 @@ import path from 'node:path';
 export function assertReleaseTooling(root = fileURLToPath(new URL('../', import.meta.url))) {
   const manifest = JSON.parse(readFileSync(path.join(root, 'scripts/release-tooling.json'), 'utf8'));
   if (manifest.schema !== 1 || manifest.canonical !== 'knightseye-net/tools/release-tooling') throw Error('Invalid release tooling stamp');
-  const required = ['scripts/pack.mjs', 'scripts/publish-reviewed.mjs', '.github/workflows/npm-publish.yml', 'scripts/verify-release.mjs', 'scripts/update-dependency.mjs', 'scripts/check-release-tooling.mjs', '.github/workflows/quality.yml'];
+  const required = ['scripts/check-review-marker.mjs', 'scripts/pack.mjs', 'scripts/publish-reviewed.mjs', '.github/workflows/npm-publish.yml', 'scripts/verify-release.mjs', 'scripts/update-dependency.mjs', 'scripts/check-release-tooling.mjs', '.github/workflows/quality.yml'];
   if (!manifest.sha256 || required.some(relative => !/^[a-f0-9]{64}$/.test(manifest.sha256[relative] || ''))) throw Error('Incomplete release tooling stamp');
   for (const [relative, expected] of Object.entries(manifest.sha256)) {
     if (path.isAbsolute(relative) || relative.split('/').includes('..')) throw Error(`Invalid tooling path: ${relative}`);

package/scripts/check-review-marker.mjs

@@ -0,0 +1,79 @@
+// Canonical source: knightseye-net/tools/release-tooling/templates/check-review-marker.mjs.
+import { execFileSync } from 'node:child_process';
+import { fileURLToPath } from 'node:url';
+import path from 'node:path';
+
+const shaPattern = /^[a-f0-9]{40}$/;
+export async function requireReview({ repository, sha, branch, reviewer, token, checkoutSha,
+  fetchImpl = fetch }) {
+  if (!/^[\w.-]+\/[\w.-]+$/.test(repository || '') || !shaPattern.test(sha || '') ||
+      checkoutSha !== sha || !['dev', 'production'].includes(branch) || reviewer !== 'Shedal' || !token) {
+    throw Error('Review gate requires repository, exact checkout SHA, release branch, Shedal and GitHub token');
+  }
+  const prefix = `/repos/${repository}`;
+  async function get(route) {
+    let response;
+    try {
+      response = await fetchImpl(`https://api.github.com${prefix}${route}`, {
+        headers: { Authorization: `Bearer ${token}`, Accept: 'application/vnd.github+json',
+          'X-GitHub-Api-Version': '2022-11-28' }, signal: AbortSignal.timeout(30000), redirect: 'error',
+      });
+    } catch { throw Error('Review evidence API unavailable'); }
+    if (!response.ok) throw Error(`Review evidence API failed: HTTP ${response.status}`);
+    try { return await response.json(); } catch { throw Error('Invalid review evidence JSON'); }
+  }
+  async function list(route) {
+    const all = [];
+    for (let page = 1; page <= 100; page++) {
+      const items = await get(`${route}?per_page=100&page=${page}`);
+      if (!Array.isArray(items)) throw Error('Invalid review evidence list');
+      all.push(...items);
+      if (items.length < 100) return all;
+    }
+    throw Error('Review evidence pagination limit reached');
+  }
+  const associated = await list(`/commits/${sha}/pulls`);
+  const matches = [];
+  const seen = new Set();
+  for (const candidate of associated) {
+    if (!Number.isSafeInteger(candidate.number) || candidate.number <= 0) throw Error('Invalid associated PR');
+    if (seen.has(candidate.number)) continue;
+    seen.add(candidate.number);
+    // Resolve current PR metadata, not the commit-association response's snapshot.
+    const pr = await get(`/pulls/${candidate.number}`);
+    if (pr.number === candidate.number && pr.merged === true && pr.merged_at &&
+        pr.merge_commit_sha === sha && pr.base?.ref === branch &&
+        pr.base?.repo?.full_name === repository) matches.push(pr);
+  }
+  if (matches.length !== 1) throw Error('Expected one merged release PR for the exact checkout SHA');
+  const pr = matches[0];
+  const comments = await list(`/issues/${pr.number}/comments`);
+  const decisions = [];
+  for (const comment of comments) {
+    if (comment.user?.login !== reviewer || typeof comment.body !== 'string') continue;
+    // Standalone line permits Claude's normal generated footer after the decision.
+    const markers = comment.body.split(/\r?\n/).filter(line =>
+      new RegExp(`^claude-review: (approved|rejected) ${sha}$`).test(line));
+    if (!markers.length) continue;
+    const created = Date.parse(comment.created_at), updated = Date.parse(comment.updated_at);
+    if (!Number.isSafeInteger(comment.id) || !Number.isFinite(created) || !Number.isFinite(updated) || updated < created) {
+      throw Error('Invalid review decision metadata');
+    }
+    const edited = updated !== created;
+    decisions.push({ id: comment.id, time: updated, approved: !edited && markers.length === 1 &&
+      markers[0] === `claude-review: approved ${sha}` });
+  }
+  decisions.sort((a, b) => a.time - b.time || a.id - b.id);
+  const latest = decisions.at(-1);
+  if (!latest?.approved) throw Error('Exact commit has no current unedited approval; post a fresh review decision');
+  return { repository, sha, reviewer, pullRequest: pr.number,
+    reviewUrl: `https://github.com/${repository}/pull/${pr.number}#issuecomment-${latest.id}` };
+}
+
+if (process.argv[1] && path.resolve(process.argv[1]) === fileURLToPath(import.meta.url)) {
+  const checkoutSha = execFileSync('git', ['rev-parse', 'HEAD'], { encoding: 'utf8' }).trim();
+  const receipt = await requireReview({ repository: process.env.GITHUB_REPOSITORY,
+    sha: process.env.GITHUB_SHA, branch: process.env.REVIEW_RELEASE_BRANCH,
+    reviewer: process.env.REVIEWER_LOGIN, token: process.env.GH_TOKEN, checkoutSha });
+  console.log(JSON.stringify(receipt));
+}

package/scripts/publish-reviewed.mjs

@@ -1,8 +1,9 @@
 // Generated from knightseye-net/tools/release-tooling; edit the canonical template and sync.
+import { requireReview } from './check-review-marker.mjs';
 import { assertReleaseTooling } from './check-release-tooling.mjs';
 import { readFileSync } from 'node:fs';
 import { createHash } from 'node:crypto';
-import { spawnSync } from 'node:child_process';
+import { spawnSync, execFileSync } from 'node:child_process';
 import { fileURLToPath } from 'node:url';
 import path from 'node:path';
 
@@ -81,5 +82,8 @@ export function publishReviewed({root, version, sha256, env = process.env, run =
 }
 if (process.argv[1] && path.resolve(process.argv[1]) === fileURLToPath(import.meta.url)) {
   assertReleaseTooling();
+  await requireReview({ repository: process.env.GITHUB_REPOSITORY, sha: process.env.GITHUB_SHA,
+    checkoutSha: execFileSync('git', ['rev-parse', 'HEAD'], { cwd: fileURLToPath(new URL('../', import.meta.url)), encoding: 'utf8' }).trim(),
+    branch: 'dev', reviewer: 'Shedal', token: process.env.GH_TOKEN });
   console.log(JSON.stringify(publishReviewed({root: fileURLToPath(new URL('../', import.meta.url)), version: process.argv[2], sha256: process.argv[3]})));
 }

package/scripts/release-tooling.json

@@ -3,11 +3,12 @@
   "canonical": "knightseye-net/tools/release-tooling",
   "sha256": {
     "scripts/pack.mjs": "334aa4041e59b14fd2b072969f50beea64449136f7f9146d63d7277fc2e4808a",
-    "scripts/publish-reviewed.mjs": "b91c7aa578bc34c490b42006038de4ee8b9c596a592aa079bacd836d02feb647",
-    ".github/workflows/npm-publish.yml": "b25cec136db205d69a407284dae2bb66f3d56be13ed2a1367f0db167a232050d",
+    "scripts/check-review-marker.mjs": "1d06c9139a835e47f78eef1bff221d5ccdc57c10f0731796ca6f5f0e3ca49e7f",
+    "scripts/publish-reviewed.mjs": "e046dda0c47cb4f7b2d044e22d7c719d5f1fda02762bef4d013125da6258fbd3",
+    ".github/workflows/npm-publish.yml": "0bb481c699566136e271babf8bdb7860b545c0e789034c0e06f5c0556d84b250",
     "scripts/verify-release.mjs": "d0f9baead779e553385bb7c26f1238ad4e60a189a818d4db4f721a1e5f88dedc",
     "scripts/update-dependency.mjs": "9919f172be33973f124eabf56c1dc70e41e941e601783ef01aba1c47dd70db9d",
-    "scripts/check-release-tooling.mjs": "29563619bdc3e86ef10dec1e983274e36138193f04d33f2455501b59a4016e0d",
+    "scripts/check-release-tooling.mjs": "667e9c096ef28cddaefb90be92601828e7268c39f8a285f6644d3784db6f5064",
     ".github/workflows/quality.yml": "a014920a9f89dc494a020bee5f69aec779cf58825f491690f9ed1ec089ed6fa0"
   }
 }

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/src/chess-reasoning/fresh-engine-pv-witnesses.ts

@@ -52,7 +52,7 @@ function rejectionReason(context: ReasoningPositionContext, hash: string, witnes
     || witness.fen !== (witness.phase === 'before' ? context.fenBefore : context.fenAfter)) return 'root-mismatch';
   if (typeof witness.engineBuild !== 'string' || !witness.engineBuild || typeof witness.command !== 'string' || !witness.command
     || !positiveInteger(witness.requestedDepth) || !positiveInteger(witness.multiPv) || witness.multiPv > 32
-    || !Array.isArray(witness.lines) || witness.lines.length !== witness.multiPv
+    || !Array.isArray(witness.lines) || witness.lines.length < 1 || witness.lines.length > witness.multiPv
     || !Array.isArray(witness.rootMoves) || witness.rootMoves.length > 32
     || witness.rootMoves.some(root => typeof root !== 'string' || !UCI.test(root))
     || new Set(witness.rootMoves).size !== witness.rootMoves.length) return 'invalid-search-scope';

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/owner/prose-reference-admission.test.mjs

@@ -24,3 +24,31 @@ test('fresh answer witnesses preserve shipped v22 reference geometry and reject
   assert.equal(rejected.referenceGapCounts.unresolvedReferences,1);
   assert.equal(rejected.blocks[0].tokens[0].reference,undefined);
 });
+
+
+test('completed unrestricted MultiPV witnesses accept fewer lines without changing requested scope', () => {
+  const fen='7r/p1p1p1kp/2p2rpQ/3q4/3P4/2P5/P1P2PP1/R3K2R b KQ - 5 18';
+  const context={kind:'position',nodeId:'two-legal',historyStartFen:fen,historyUci:[],moveUci:'',moveSan:'',fenBefore:fen,fenAfter:fen};
+  const roots=['g7g8','g7f7'];
+  assert.deepEqual(new Set(new Chess(fen).moves({verbose:true}).map(m=>m.from+m.to)),new Set(roots));
+  const witness={version:'fresh-engine-pv-witness/1',acquisition:'same-answer-engine',acquisitionId:1,
+    evidenceId:'server-engine-acquisition:two-legal',contextHash:reasoningContextHash(context),phase:'before',fen,
+    engineBuild:'test-engine',command:'go depth 18',requestedDepth:18,multiPv:3,rootMoves:[],
+    authority:'bounded-engine',licenses:['engine.bounded-continuation'],
+    lines:roots.map((rootMove,index)=>({rootMove,pv:[rootMove],depth:18,scoreCp:-200-index,mateInMoves:null,
+      scoreProvenance:{kind:'root-search',fen,engineBuild:'test-engine',command:'go depth 18',originatingDepth:18,reportedDepth:18}}))};
+  const admitted=admitFreshEnginePvWitnesses(context,[witness]);
+  assert.equal(admitted.audit.acceptedLines,2);
+  assert.equal(witness.multiPv,3,'requested MultiPV remains provenance, not returned-line count');
+  assert.equal(admitFreshEnginePvWitnesses(context,[{...witness,lines:[witness.lines[0]]}]).audit.acceptedLines,1);
+  for (const patch of [{lines:[]},{multiPv:1},{rootMoves:roots,lines:[witness.lines[0]]}]) {
+    assert.equal(admitFreshEnginePvWitnesses(context,[{...witness,...patch}]).audit.acceptedLines,0);
+  }
+  for (const change of [line=>{line.depth=17;},line=>{line.scoreCp=null;},line=>{line.pv=['g7g6'];}]) {
+    const invalid=structuredClone(witness);change(invalid.lines[1]);
+    assert.equal(admitFreshEnginePvWitnesses(context,[invalid]).audit.acceptedLines,0);
+  }
+  const rendered=simpleProseReferences('[Kg8](move:before:g7g8)',context,[],undefined,undefined,undefined,{freshEnginePvWitnesses:[witness]});
+  assert.equal(rendered.referenceGapCounts.unresolvedReferences,0);
+  assert.equal(rendered.freshEnginePvAdmission.acceptedLines,2);
+});

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;