pikelet-wasm 0.7.0 → 0.8.1

package/complete/index.mjs

@@ -1,4 +1,4 @@
-// The one-file reader: open a .pancake (spec/COMPLETE_PROFILE.md) and query
+// The one-file reader: open a .pikelet (spec/COMPLETE_PROFILE.md) and query
 // it. Environment-neutral — the same module runs in Node (file path or
 // range source) and the browser (HTTP range source, via a bundler for the
 // CJS sketch-reader dependency). The query path needs no core HNSW engine:
@@ -8,15 +8,15 @@
 // engine's SIMD scan kernel (options.sketchScanner — auto-staged in Node,
 // injected in browsers), which only ever changes speed, never results.
 //
-//   const search = await openPancakeFile('pancake-docs.pancake');   // Node
-//   const search = await openPancakeFile(httpRangeSource(url));     // browser
+//   const search = await openPikeletFile('docs.pikelet');           // Node
+//   const search = await openPikeletFile(httpRangeSource(url));     // browser
 //   const out = await search.query('how do workers restore snapshots');
 //
 // Every byte of the artifact is untrusted input (contract section 7): each
 // offset, length, and count is validated — safe integer, within the header's
 // fileBytes and the source's size, under the per-open read budget — before a
 // read is issued or a buffer allocated, and every read must return exactly
-// the bytes asked for. Format 2 files (profile pancake-complete-v2) carry
+// the bytes asked for. Format 2 files (profile pikelet-complete-v2) carry
 // per-record corpus digests, so each hydrated record is verified on its own
 // range read; format 1 files verify eager segments whole and hydrate records
 // under the segment digest only (reported via info().corpusIntegrity).
@@ -25,7 +25,7 @@ import { loadStudentModel, embedTextWithStudent } from './student-embedder.mjs';
 import { computeMatchQuality, computePreSearchAbstention } from './student-abstention.mjs';
 import { createAbstentionScorer } from './retrieval-abstention.mjs';
 import { openLexicalIndex, openLexicalIndexLazy } from './lexical.mjs';
-import { PancakeSketchArtifact } from '../pancake-artifact.js';
+import { PikeletSketchArtifact } from '../src/artifact/pikelet-artifact.js';
 import { MAGIC, HEADER_BYTES, TABLE_ENTRY_BYTES, KINDS, KIND_NAMES } from './format.mjs';
 
 import {
@@ -36,9 +36,13 @@ import {
 } from './inline-transformer.mjs';
 
 export { httpRangeSource } from './sources.mjs';
-// The project renamed to Pikelet (2026-09); the wire format and this
-// reader's original export keep their pancake-era names for
-// compatibility, and openPikeletFile is the documented alias.
+// Re-exported for the builder side: calibration fits coverage against the
+// same fused (vector+BM25) ranking the reader serves, which needs an
+// in-memory lexical searcher over the segment bytes already assembled by
+// buildLexicalSegment, before the artifact is written to disk.
+export { openLexicalIndex } from './lexical.mjs';
+export { fuseCandidates, FUSION_DEFAULTS } from './fusion.mjs';
+import { fuseCandidates } from './fusion.mjs';
 export {
     KERNEL_LAYOUT, expectedBlobBytes, parseInlineTransformerEncoder,
     createInlineTransformerEmbedder, INLINE_TEST_VECTOR_TEXTS,
@@ -47,7 +51,13 @@ export {
 };
 
 // Supported container formats: header formatVersion -> manifest profile.
-export const SUPPORTED_PROFILES = Object.freeze({ 1: 'pancake-complete-v1', 2: 'pancake-complete-v2' });
+export const SUPPORTED_PROFILES = Object.freeze({ 1: 'pikelet-complete-v1', 2: 'pikelet-complete-v2' });
+// Pre-rename profile strings (2026-09): every .pikelet published before this
+// date — including live GitHub release assets — carries "pancake-complete-
+// vN" in its manifest. Readers accept both spellings indefinitely so an
+// already-published pack does not go dark on a reader upgrade; only
+// SUPPORTED_PROFILES (above) is what a fresh build ever writes.
+const LEGACY_PROFILES = Object.freeze({ 1: 'pancake-complete-v1', 2: 'pancake-complete-v2' });
 export const CORPUS_LAYOUT_V2 = 'records-v2';
 
 // Read budgets. Open-path reads (manifest, segment table, query-interp,
@@ -63,13 +73,32 @@ const MAX_RECORDS = 2 ** 31 - 1;
 const MAX_PAGE_RECORDS = 65536;
 const DIGEST_PAGE_CACHE = 64;
 const RECORD_CACHE = 256;
-// The embedded index is a .pancake-sketch artifact (SKETCH_PROFILE.md);
+// The embedded index is a .pikelet-sketch artifact (SKETCH_PROFILE.md);
 // its fixed-size header is what format 2 commits to in the manifest.
 const SKETCH_HEADER_BYTES = 256;
 // Hybrid retrieval: BM25 candidates fetched from the lexical segment per
-// query, and the reciprocal-rank-fusion constant (the standard untuned 60).
+// query; the fusion rule and its constants live in fusion.mjs, shared with
+// the calibrator so fit-time rankings match what is served.
 const LEXICAL_CANDIDATES = 24;
-const RRF_K = 60;
+// scoreQuality's coverage term hydrates the fused top passagesNeeded
+// records (asset.coverage.topK, 5 by default — see calibrate.mjs's
+// COVERAGE_TOP_PASSAGES) once retrieval returns. The scorer that knows
+// the real number is created inside retrievalScorer()'s own closure, not
+// reachable from here, so this is a fixed approximation used to decide
+// how many of fusedFull's records to include in the batched hydration
+// below, alongside phrase-pinning's own candidates — hydrating a couple
+// more than coverage strictly needs just costs a little extra bandwidth
+// on a cache entry that goes unread; hydrating fewer only narrows how
+// much of coverage's later hydration hits warm cache. Either way is
+// harmless: it's a batch-sizing choice, not a correctness one.
+const COVERAGE_BATCH_COUNT = 5;
+// Only BM25 hits within this fraction of the top lexical score join fusion.
+// Common query terms give every matching document a near-tied score (idf
+// collapses them flat); a wide cutoff let that tied mass ride into fusion on
+// a technicality. Kept identical to pikelet/src/calibrate.mjs's
+// LEXICAL_CUTOFF so calibration is fit against the same fusion the reader
+// actually serves.
+const LEXICAL_CUTOFF = 1.5;
 // Query-interpretation segments above this size open lazily (kind 3's
 // inline encoder is ~25 MiB); smaller ones keep the one-read eager path.
 const LAZY_QI_BYTES = 4 * 1024 * 1024;
@@ -110,20 +139,30 @@ function toHex(bytes) {
 const isSha256Hex = (value) => typeof value === 'string' && /^[0-9a-f]{64}$/.test(value);
 
 // SHA-256 via WebCrypto (browser, workerd, Node 18+); node:crypto fallback
-// for older Node. Fails closed: verification is not optional in this reader.
+// for older Node, gated on an actual Node runtime check rather than just
+// "WebCrypto is missing" — a browser can lack crypto.subtle too (privacy
+// settings, a hardened build), and a bare dynamic import('node:crypto')
+// there isn't a Node module resolution failure, it's a cross-origin module
+// fetch a browser refuses outright, surfacing as an opaque module-loading
+// error instead of the clear message below. Fails closed either way:
+// verification is not optional in this reader.
 async function sha256hex(bytes) {
     if (globalThis.crypto?.subtle) {
         return toHex(new Uint8Array(await globalThis.crypto.subtle.digest('SHA-256', bytes)));
     }
-    const { createHash } = await import(/* webpackIgnore: true */ /* @vite-ignore */ 'node:crypto');
-    return createHash('sha256').update(bytes).digest('hex');
+    if (typeof process !== 'undefined' && process.versions?.node) {
+        const { createHash } = await import(/* webpackIgnore: true */ /* @vite-ignore */ 'node:crypto');
+        return createHash('sha256').update(bytes).digest('hex');
+    }
+    throw new Error('No crypto backend available (crypto.subtle is missing) — '
+        + 'cannot verify artifact integrity in this environment');
 }
 
 function asUint8Array(bytes) {
     if (bytes instanceof Uint8Array) return bytes;
     if (bytes instanceof ArrayBuffer) return new Uint8Array(bytes);
     if (ArrayBuffer.isView(bytes)) return new Uint8Array(bytes.buffer, bytes.byteOffset, bytes.byteLength);
-    throw new Error('.pancake range source returned a non-binary value');
+    throw new Error('.pikelet range source returned a non-binary value');
 }
 
 function resolveBudget(value, label, fallback) {
@@ -138,7 +177,7 @@ function resolveBudget(value, label, fallback) {
 // u64 fields become JS numbers only when they are exactly representable.
 function u64(view, offset, label) {
     const big = view.getBigUint64(offset, true);
-    if (big > MAX_SAFE_BIG) throw new Error(`.pancake ${label} exceeds the safe integer range`);
+    if (big > MAX_SAFE_BIG) throw new Error(`.pikelet ${label} exceeds the safe integer range`);
     return Number(big);
 }
 
@@ -148,16 +187,16 @@ function u64(view, offset, label) {
 function checkRange(source, offset, length, label, limit, fileBytes) {
     if (!Number.isSafeInteger(offset) || !Number.isSafeInteger(length)
         || offset < 0 || length < 0 || !Number.isSafeInteger(offset + length)) {
-        throw new Error(`.pancake ${label} range is out of bounds`);
+        throw new Error(`.pikelet ${label} range is out of bounds`);
     }
     if (length > limit) {
-        throw new Error(`.pancake ${label} read of ${length} bytes exceeds the ${limit}-byte read budget`);
+        throw new Error(`.pikelet ${label} read of ${length} bytes exceeds the ${limit}-byte read budget`);
     }
     if (fileBytes !== undefined && offset + length > fileBytes) {
-        throw new Error(`.pancake ${label} range extends past the file (${offset}+${length} > ${fileBytes})`);
+        throw new Error(`.pikelet ${label} range extends past the file (${offset}+${length} > ${fileBytes})`);
     }
     if (Number.isSafeInteger(source.size) && offset + length > source.size) {
-        throw new Error(`.pancake ${label} range extends past the source (${offset}+${length} > ${source.size})`);
+        throw new Error(`.pikelet ${label} range extends past the source (${offset}+${length} > ${source.size})`);
     }
 }
 
@@ -165,7 +204,7 @@ async function readChecked(source, offset, length, label, limit, fileBytes) {
     checkRange(source, offset, length, label, limit, fileBytes);
     const bytes = asUint8Array(await source.read(offset, length));
     if (bytes.length !== length) {
-        throw new Error(`.pancake ${label} read returned ${bytes.length} of ${length} bytes (truncated or misbehaving source)`);
+        throw new Error(`.pikelet ${label} read returned ${bytes.length} of ${length} bytes (truncated or misbehaving source)`);
     }
     return bytes;
 }
@@ -185,7 +224,7 @@ async function fileSource(filePath) {
         preferredParallelism: Infinity,
         preferredGapBytes: 2048,
         async read(offset, length) {
-            if (fd === null) throw new Error('.pancake file source is closed');
+            if (fd === null) throw new Error('.pikelet file source is closed');
             const buffer = new Uint8Array(length);
             let bytesRead = 0;
             while (bytesRead < length) {
@@ -217,7 +256,7 @@ function windowSource(source, offset, length) {
         preferredGapBytes: source.preferredGapBytes,
         async read(off, len) {
             if (!Number.isSafeInteger(off) || !Number.isSafeInteger(len) || off < 0 || len < 0 || off + len > length) {
-                throw new Error('.pancake index segment read is outside the segment window');
+                throw new Error('.pikelet index segment read is outside the segment window');
             }
             return source.read(offset + off, len);
         },
@@ -257,19 +296,19 @@ function base64Bytes(text) {
 export async function verifyHostEncoder(declaration, encodeQuery, dim) {
     const vectors = declaration.testVectors;
     if (!Array.isArray(vectors) || vectors.length === 0) {
-        throw new Error('.pancake kind-2 declaration carries no verification vectors');
+        throw new Error('.pikelet kind-2 declaration carries no verification vectors');
     }
     if (declaration.dim !== undefined && declaration.dim !== dim) {
-        throw new Error(`.pancake kind-2 declaration dim ${declaration.dim} disagrees with manifest dim ${dim}`);
+        throw new Error(`.pikelet kind-2 declaration dim ${declaration.dim} disagrees with manifest dim ${dim}`);
     }
     for (const tv of vectors) {
         if (!tv || typeof tv.text !== 'string') {
-            throw new Error('.pancake kind-2 verification vector is malformed');
+            throw new Error('.pikelet kind-2 verification vector is malformed');
         }
         // The expected embedding must be dim finite numbers: a malformed
         // entry would turn every comparison into NaN, and NaN > maxDiff is
         // false — the vector would "pass" without comparing anything.
-        const label = `.pancake kind-2 verification vector "${tv.text.slice(0, 40)}…"`;
+        const label = `.pikelet kind-2 verification vector "${tv.text.slice(0, 40)}…"`;
         validateExpectedEmbedding(tv.embedding, dim, label);
         const tolerance = validateTestVectorTolerance(tv.tolerance, label);
         const vector = toFloat32(await encodeQuery(tv.text), dim, 'options.encodeQuery');
@@ -288,15 +327,15 @@ export async function verifyHostEncoder(declaration, encodeQuery, dim) {
 }
 
 /**
- * Open a .pancake complete artifact from a file path (Node) or a
+ * Open a .pikelet complete artifact from a file path (Node) or a
  * { read(offset, length), size? } range source (any runtime).
  * Returns { query(text, {k}), info(), evaluation(), close() }.
  */
-export async function openPancakeFile(input, options = {}) {
+export async function openPikeletFile(input, options = {}) {
     const source = typeof input === 'string' ? await fileSource(input) : input;
     const owned = typeof input === 'string';
     if (!source || typeof source.read !== 'function') {
-        throw new Error('openPancakeFile() requires a file path or a range source with read(offset, length)');
+        throw new Error('openPikeletFile() requires a file path or a range source with read(offset, length)');
     }
     const maxReadBytes = resolveBudget(options.maxReadBytes, 'maxReadBytes', DEFAULT_OPEN_READ_BYTES);
     const maxRecordBytes = resolveBudget(options.maxRecordBytes, 'maxRecordBytes', DEFAULT_RECORD_BYTES);
@@ -333,23 +372,23 @@ export async function openPancakeFile(input, options = {}) {
         const header = await readChecked(source, 0, HEADER_BYTES, 'header', maxReadBytes);
         const headerView = viewOf(header);
         if (headerView.getUint32(0, true) !== MAGIC) {
-            throw new Error('not a .pancake file (bad magic)');
+            throw new Error('not a .pikelet file (bad magic)');
         }
         const formatVersion = headerView.getUint32(4, true);
         const profile = SUPPORTED_PROFILES[formatVersion];
-        if (!profile) throw new Error(`unsupported .pancake format version ${formatVersion}`);
+        if (!profile) throw new Error(`unsupported .pikelet format version ${formatVersion}`);
         const manifestBytes = headerView.getUint32(8, true);
         const segmentCount = headerView.getUint32(12, true);
         const fileBytes = u64(headerView, 16, 'header fileBytes');
         if (manifestBytes < 2 || manifestBytes > MAX_MANIFEST_BYTES || segmentCount < 1 || segmentCount > MAX_SEGMENTS) {
-            throw new Error('.pancake header is implausible');
+            throw new Error('.pikelet header is implausible');
         }
         if (Number.isSafeInteger(source.size) && source.size !== fileBytes) {
-            throw new Error(`.pancake is truncated or padded: header says ${fileBytes} bytes, source has ${source.size}`);
+            throw new Error(`.pikelet is truncated or padded: header says ${fileBytes} bytes, source has ${source.size}`);
         }
         const tableBytes = segmentCount * TABLE_ENTRY_BYTES;
         if (HEADER_BYTES + manifestBytes + tableBytes > fileBytes) {
-            throw new Error('.pancake header places the manifest or segment table past the file');
+            throw new Error('.pikelet header places the manifest or segment table past the file');
         }
         const identity = toHex(header.subarray(24, 56));
         // A caller pinning an expected identity (a shelf entry, a lockfile,
@@ -362,30 +401,31 @@ export async function openPancakeFile(input, options = {}) {
                 throw new Error('options.expectedIdentity must be a sha256 hex string');
             }
             if (identity !== options.expectedIdentity.toLowerCase()) {
-                throw new Error(`.pancake identity mismatch: expected ${options.expectedIdentity.toLowerCase()}, found ${identity}`);
+                throw new Error(`.pikelet identity mismatch: expected ${options.expectedIdentity.toLowerCase()}, found ${identity}`);
             }
         }
 
         const manifestBuf = await readChecked(source, HEADER_BYTES, manifestBytes, 'manifest', maxReadBytes, fileBytes);
         if (await sha256hex(manifestBuf) !== identity) {
-            throw new Error('.pancake manifest failed identity verification');
+            throw new Error('.pikelet manifest failed identity verification');
         }
         let manifest;
         try { manifest = JSON.parse(decoder.decode(manifestBuf)); } catch (err) {
-            throw new Error('.pancake manifest is not valid JSON', { cause: err });
+            throw new Error('.pikelet manifest is not valid JSON', { cause: err });
         }
-        if (!manifest || typeof manifest !== 'object' || manifest.profile !== profile) {
+        if (!manifest || typeof manifest !== 'object'
+            || (manifest.profile !== profile && manifest.profile !== LEGACY_PROFILES[formatVersion])) {
             throw new Error(`unsupported profile ${manifest?.profile} for format version ${formatVersion}`);
         }
         if (!Array.isArray(manifest.segments) || manifest.segments.length !== segmentCount) {
-            throw new Error('.pancake manifest segment list disagrees with the header segment count');
+            throw new Error('.pikelet manifest segment list disagrees with the header segment count');
         }
         const dim = manifest.dim;
         if (!Number.isSafeInteger(dim) || dim < 1 || dim > 65536) {
-            throw new Error('.pancake manifest dim is implausible');
+            throw new Error('.pikelet manifest dim is implausible');
         }
         if (!manifest.corpus || typeof manifest.corpus !== 'object') {
-            throw new Error('.pancake manifest has no corpus block');
+            throw new Error('.pikelet manifest has no corpus block');
         }
 
         const table = await readChecked(source, HEADER_BYTES + manifestBytes, tableBytes, 'segment table', maxReadBytes, fileBytes);
@@ -401,26 +441,26 @@ export async function openPancakeFile(input, options = {}) {
             const declared = manifest.segments[i];
             if (!declared || typeof declared !== 'object' || declared.bytes !== length || !isSha256Hex(declared.sha256)
                 || offset !== expectedOffset || !Number.isSafeInteger(offset + length) || offset + length > fileBytes) {
-                throw new Error(`.pancake segment table disagrees with manifest at entry ${i}`);
+                throw new Error(`.pikelet segment table disagrees with manifest at entry ${i}`);
             }
             if (kind === undefined) {
                 // Unknown kinds are skipped, not failed (spec 3.3); they are
                 // still committed through the manifest, so the declared name
                 // must at least not claim to be a kind this reader knows.
                 if (typeof declared.kind !== 'string' || declared.kind in KINDS) {
-                    throw new Error(`.pancake segment table entry ${i} has unknown kind ${kindNumber} but the manifest names it ${declared.kind}`);
+                    throw new Error(`.pikelet segment table entry ${i} has unknown kind ${kindNumber} but the manifest names it ${declared.kind}`);
                 }
             } else {
                 if (declared.kind !== kind) {
-                    throw new Error(`.pancake segment table disagrees with manifest at entry ${i}`);
+                    throw new Error(`.pikelet segment table disagrees with manifest at entry ${i}`);
                 }
-                if (segments.has(kind)) throw new Error(`.pancake carries more than one ${kind} segment`);
+                if (segments.has(kind)) throw new Error(`.pikelet carries more than one ${kind} segment`);
                 segments.set(kind, { offset, length, sha256: declared.sha256 });
             }
             expectedOffset = align16(offset + length);
         }
         for (const required of ['index', 'corpus', 'query-interp']) {
-            if (!segments.has(required)) throw new Error(`.pancake is missing the ${required} segment`);
+            if (!segments.has(required)) throw new Error(`.pikelet is missing the ${required} segment`);
         }
 
         // Corpus tables: count + offsets (+ page table for layout v2),
@@ -432,15 +472,15 @@ export async function openPancakeFile(input, options = {}) {
         const corpus = segments.get('corpus');
         const declaredRecords = manifest.corpus.records;
         if (!Number.isSafeInteger(declaredRecords) || declaredRecords < 0 || declaredRecords > MAX_RECORDS) {
-            throw new Error('.pancake manifest corpus.records is implausible');
+            throw new Error('.pikelet manifest corpus.records is implausible');
         }
         const layout = manifest.corpus.layout;
         const perRecord = formatVersion >= 2;
         if (perRecord && layout !== CORPUS_LAYOUT_V2) {
-            throw new Error(`.pancake format ${formatVersion} requires corpus layout ${CORPUS_LAYOUT_V2}, manifest says ${layout}`);
+            throw new Error(`.pikelet format ${formatVersion} requires corpus layout ${CORPUS_LAYOUT_V2}, manifest says ${layout}`);
         }
         if (!perRecord && layout !== undefined) {
-            throw new Error(`.pancake format 1 carries corpus layout v1, manifest says ${layout}`);
+            throw new Error(`.pikelet format 1 carries corpus layout v1, manifest says ${layout}`);
         }
         let pageRecords = 0;
         let pages = 0;
@@ -451,12 +491,12 @@ export async function openPancakeFile(input, options = {}) {
         if (perRecord) {
             pageRecords = manifest.corpus.pageRecords;
             if (!Number.isSafeInteger(pageRecords) || pageRecords < 1 || pageRecords > MAX_PAGE_RECORDS) {
-                throw new Error('.pancake manifest corpus.pageRecords is implausible');
+                throw new Error('.pikelet manifest corpus.pageRecords is implausible');
             }
             pages = Math.ceil(declaredRecords / pageRecords);
             if (manifest.corpus.pages !== pages || !isSha256Hex(manifest.corpus.pageTableSha256)
                 || manifest.corpus.recordDigest !== 'sha256') {
-                throw new Error('.pancake manifest corpus integrity block is inconsistent');
+                throw new Error('.pikelet manifest corpus integrity block is inconsistent');
             }
             offsetsAt = 8;
             tablesBytes = offsetsAt + 8 * (declaredRecords + 1) + 32 * pages;
@@ -468,7 +508,7 @@ export async function openPancakeFile(input, options = {}) {
             recordsAt = tablesBytes;
         }
         if (!Number.isSafeInteger(recordsAt) || recordsAt > corpus.length) {
-            throw new Error('.pancake manifest corpus.records is implausible for the corpus segment');
+            throw new Error('.pikelet manifest corpus.records is implausible for the corpus segment');
         }
         // Format 2 commits to the embedded sketch's 256-byte header
         // (metric/dim/count and the sketch's residentSha256/vectorsSha256),
@@ -476,7 +516,7 @@ export async function openPancakeFile(input, options = {}) {
         // sketch's self-checks alone verify against fields an attacker who
         // rewrites the segment also controls.
         if (perRecord && (!isSha256Hex(manifest.index?.headerSha256) || idx.length < SKETCH_HEADER_BYTES)) {
-            throw new Error('.pancake manifest carries no index header commitment (index.headerSha256)');
+            throw new Error('.pikelet manifest carries no index header commitment (index.headerSha256)');
         }
 
         // After the segment table, every remaining open-path extent is known,
@@ -502,11 +542,11 @@ export async function openPancakeFile(input, options = {}) {
                 }
                 const bytes = await readChecked(source, qi.offset, qi.length, 'query-interp segment', maxReadBytes, fileBytes);
                 if (await sha256hex(bytes) !== qi.sha256) {
-                    throw new Error('.pancake query-interp segment failed hash verification');
+                    throw new Error('.pikelet query-interp segment failed hash verification');
                 }
                 return bytes;
             })(),
-            PancakeSketchArtifact.open(windowSource(source, idx.offset, idx.length), { maxReadBytes }),
+            PikeletSketchArtifact.open(windowSource(source, idx.offset, idx.length), { maxReadBytes }),
             readChecked(source, corpus.offset, tablesBytes, 'corpus tables', maxReadBytes, fileBytes),
             // Lexical index (kind 5, OPTIONAL). Small segments: eager
             // whole-segment read, digest-verified like the query-interp
@@ -522,14 +562,14 @@ export async function openPancakeFile(input, options = {}) {
                 }
                 const bytes = await readChecked(source, seg.offset, seg.length, 'lexical segment', maxReadBytes, fileBytes);
                 if (await sha256hex(bytes) !== seg.sha256) {
-                    throw new Error('.pancake lexical segment failed hash verification');
+                    throw new Error('.pikelet lexical segment failed hash verification');
                 }
                 return { bytes };
             })() : null,
             perRecord ? (async () => {
                 const headerBytes = await readChecked(source, idx.offset, SKETCH_HEADER_BYTES, 'index header', maxReadBytes, fileBytes);
                 if (await sha256hex(headerBytes) !== manifest.index.headerSha256) {
-                    throw new Error('.pancake index header failed hash verification against the manifest');
+                    throw new Error('.pikelet index header failed hash verification against the manifest');
                 }
             })() : null,
         ]);
@@ -538,12 +578,12 @@ export async function openPancakeFile(input, options = {}) {
             ? (lexicalBytes.lazyIndex || openLexicalIndex(lexicalBytes.bytes))
             : null;
         if (lexicalIndex && lexicalIndex.docCount !== declaredRecords) {
-            throw new Error(`.pancake lexical segment covers ${lexicalIndex.docCount} records, corpus declares ${declaredRecords}`);
+            throw new Error(`.pikelet lexical segment covers ${lexicalIndex.docCount} records, corpus declares ${declaredRecords}`);
         }
 
         // Query interpretation: version word, kind, two length-prefixed
         // regions that must tile the segment exactly.
-        if (qi.length < 16) throw new Error('.pancake query-interp segment is too short');
+        if (qi.length < 16) throw new Error('.pikelet query-interp segment is too short');
         const qiView = viewOf(qiFirst);
         const qiVersion = qiView.getUint32(0, true);
         if (qiVersion !== 1) throw new Error(`unsupported query-interpretation version ${qiVersion}`);
@@ -551,7 +591,7 @@ export async function openPancakeFile(input, options = {}) {
         const encoderLen = qiView.getUint32(8, true);
         const calibrationLen = qiView.getUint32(12, true);
         if (16 + encoderLen + calibrationLen !== qi.length) {
-            throw new Error('.pancake query-interp segment layout is inconsistent');
+            throw new Error('.pikelet query-interp segment layout is inconsistent');
         }
         // Laziness only pays for kind 3 (the deferrable bulk IS the
         // encoder); a large segment of any other kind falls back to the
@@ -561,7 +601,7 @@ export async function openPancakeFile(input, options = {}) {
         if (qiDeferrable && qiKind !== 3) {
             qiBytes = await readChecked(source, qi.offset, qi.length, 'query-interp segment', maxReadBytes, fileBytes);
             if (await sha256hex(qiBytes) !== qi.sha256) {
-                throw new Error('.pancake query-interp segment failed hash verification');
+                throw new Error('.pikelet query-interp segment failed hash verification');
             }
             qiDeferred = false;
         }
@@ -574,10 +614,10 @@ export async function openPancakeFile(input, options = {}) {
         const encoderBytes = qiDeferred ? null : qiBytes.subarray(16, 16 + encoderLen);
         let calibrationJson;
         try { calibrationJson = JSON.parse(decoder.decode(calibrationRegion)); } catch (err) {
-            throw new Error('.pancake calibration is not valid JSON', { cause: err });
+            throw new Error('.pikelet calibration is not valid JSON', { cause: err });
         }
         if (!calibrationJson || typeof calibrationJson !== 'object') {
-            throw new Error('.pancake calibration must be a JSON object');
+            throw new Error('.pikelet calibration must be a JSON object');
         }
 
         // kind 1 (student-inline-v1): pure-JS inline encoder + feature-stream
@@ -595,20 +635,42 @@ export async function openPancakeFile(input, options = {}) {
         const retrievalScorer = () => {
             const scorer = createAbstentionScorer(calibrationJson.asset, base64Bytes(calibrationJson.vocabBloomBase64));
             const VERDICTS = { answer: 'strong', weak: 'weak', abstain: 'none' };
-            return async (hits, context) => {
+            return async (hits, context, fusedHits) => {
                 if (!scorer) return { match_quality: 'unscored' };
                 // The coverage term grounds the verdict in the top passages'
-                // text, so those records hydrate before scoring. When the
-                // query is answered the pages are already hot for result
-                // hydration; an abstained query costs these extra reads.
-                // Hydration failures propagate — on format 2 a record that
-                // fails its digest must fail the query, not skew its verdict.
-                const topTexts = scorer.usesPassage && hits.length
-                    ? (await Promise.all(hits.slice(0, scorer.passagesNeeded || 1)
-                        .map((hit) => hydrate(hit.id)))).map((record) => record?.text)
+                // text, so those records hydrate before scoring. Hydrated
+                // from the fused (RRF) order when hybrid retrieval produced
+                // one — calibrate.mjs fits coverage against the same fused
+                // ranking, and a chunk BM25 ranks first but the embedding
+                // ranks far down is exactly the case coverage exists to
+                // catch; scoring it against vector-only order would miss it
+                // again. Falls back to vector order (hits) when there is no
+                // lexical segment or fusion did not change anything. When
+                // the query is answered the pages are already hot for
+                // result hydration; an abstained query costs these extra
+                // reads. Hydration failures propagate — on format 2 a
+                // record that fails its digest must fail the query, not
+                // skew its verdict.
+                const passageSource = fusedHits?.length ? fusedHits : hits;
+                // A record's text starts with its own heading echoed as the
+                // first line (ingest.mjs's section-to-chunk join). A
+                // heading match still grounds the query but at reduced
+                // credit — see retrieval-abstention.mjs's coverageFrac and
+                // calibrate.mjs's HEADING_COVERAGE_WEIGHT, which this split
+                // must match exactly (build-time and serve-time coverage
+                // must agree, or the fitted thresholds are scoring a
+                // different signal than the one they were calibrated
+                // against).
+                const splitHeadingBody = (text) => {
+                    const nl = String(text || '').indexOf('\n');
+                    return nl === -1 ? { heading: text, body: '' } : { heading: text.slice(0, nl), body: text.slice(nl + 1) };
+                };
+                const topTexts = scorer.usesPassage && passageSource.length
+                    ? (await Promise.all(passageSource.slice(0, scorer.passagesNeeded || 1)
+                        .map((hit) => hydrate(hit.id)))).map((record) => splitHeadingBody(record?.text))
                     : [];
-                const scored = scorer.score(context.text, hits, topTexts);
-                return { match_quality: VERDICTS[scored.verdict] || scored.verdict, confidence: scored.p };
+                const scored = await scorer.score(context.text, hits, topTexts);
+                return { match_quality: VERDICTS[scored.verdict] || scored.verdict, confidence: scored.p, grounding: scored.grounding || null };
             };
         };
         if (qiKind === 1) {
@@ -625,9 +687,9 @@ export async function openPancakeFile(input, options = {}) {
         } else if (qiKind === 2) {
             let declaration;
             try { declaration = JSON.parse(decoder.decode(encoderBytes)); } catch (err) {
-                throw new Error('.pancake kind-2 encoder declaration is not valid JSON', { cause: err });
+                throw new Error('.pikelet kind-2 encoder declaration is not valid JSON', { cause: err });
             }
-            if (!declaration || typeof declaration !== 'object') throw new Error('.pancake kind-2 encoder declaration must be a JSON object');
+            if (!declaration || typeof declaration !== 'object') throw new Error('.pikelet kind-2 encoder declaration must be a JSON object');
             encoderInfo = declaration;
             const encodeQuery = options.encodeQuery;
             if (encodeQuery !== undefined && typeof encodeQuery !== 'function') {
@@ -641,7 +703,7 @@ export async function openPancakeFile(input, options = {}) {
                 } else if (options.allowUnverifiedEncoder === true) {
                     encoderVerified = false;
                 } else {
-                    throw new Error(`.pancake declares an external encoder (${declaration.model}) without verification vectors, `
+                    throw new Error(`.pikelet declares an external encoder (${declaration.model}) without verification vectors, `
                         + 'so the host encoder cannot be checked against it (contract section 4.4); '
                         + 'pass options.allowUnverifiedEncoder: true to serve it anyway, marked unverified');
                 }
@@ -650,8 +712,8 @@ export async function openPancakeFile(input, options = {}) {
             }
             embed = async (text) => {
                 if (!encodeQuery) {
-                    throw new Error(`.pancake declares an external encoder (${declaration.model}); `
-                        + 'pass options.encodeQuery to openPancakeFile');
+                    throw new Error(`.pikelet declares an external encoder (${declaration.model}); `
+                        + 'pass options.encodeQuery to openPikeletFile');
                 }
                 return { vector: toFloat32(await encodeQuery(text), dim, 'options.encodeQuery'), text };
             };
@@ -670,7 +732,7 @@ export async function openPancakeFile(input, options = {}) {
                 } catch (err) {
                     throw new Error('kind-3 artifact requires the inline-transformer kernels at '
                         + 'complete/encoder-kernels/ (pikelet-wasm/complete); run '
-                        + 'examples/05-one-file-search/encoder-spike/build-encoder.sh to rebuild them',
+                        + 'examples/one-file-search/encoder-spike/build-encoder.sh to rebuild them',
                     { cause: err });
                 }
             }
@@ -680,7 +742,7 @@ export async function openPancakeFile(input, options = {}) {
                 if (qiDeferred) {
                     const full = await readChecked(source, qi.offset, qi.length, 'query-interp segment', maxReadBytes, fileBytes);
                     if (await sha256hex(full) !== qi.sha256) {
-                        throw new Error('.pancake query-interp segment failed hash verification');
+                        throw new Error('.pikelet query-interp segment failed hash verification');
                     }
                     // The header and calibration slices used at open were
                     // unverified; the digest-verified segment must contain
@@ -688,13 +750,13 @@ export async function openPancakeFile(input, options = {}) {
                     // every query must fail.
                     if (!bytesEqual(full.subarray(0, 16), openHeader)
                         || !bytesEqual(full.subarray(16 + encoderLen), calibrationRegion)) {
-                        throw new Error('.pancake query-interp segment bytes changed between open and encoder fetch');
+                        throw new Error('.pikelet query-interp segment bytes changed between open and encoder fetch');
                     }
                     encBytes = full.subarray(16, 16 + encoderLen);
                 }
                 const { declaration, vocabText, blob } = parseInlineTransformerEncoder(encBytes);
                 if (declaration.dim !== undefined && declaration.dim !== dim) {
-                    throw new Error(`.pancake kind-3 declaration dim ${declaration.dim} disagrees with manifest dim ${dim}`);
+                    throw new Error(`.pikelet kind-3 declaration dim ${declaration.dim} disagrees with manifest dim ${dim}`);
                 }
                 const embedder = await createInlineTransformerEmbedder({ declaration, vocabText, blob, createEncoder, verify: verifyEncoder });
                 encoderInfo = declaration;
@@ -732,10 +794,10 @@ export async function openPancakeFile(input, options = {}) {
         // Index: the embedded sketch artifact, opened in the wave above
         // against a segment-windowed source (resident hash verified there).
         if (sketch.count !== declaredRecords) {
-            throw new Error(`.pancake index count ${sketch.count} != corpus records ${declaredRecords}`);
+            throw new Error(`.pikelet index count ${sketch.count} != corpus records ${declaredRecords}`);
         }
         if (sketch.dim !== undefined && sketch.dim !== dim) {
-            throw new Error(`.pancake index dim ${sketch.dim} != manifest dim ${dim}`);
+            throw new Error(`.pikelet index dim ${sketch.dim} != manifest dim ${dim}`);
         }
         // The metric decides the search semantics; the sketch header's copy
         // must agree with the identity-verified manifest (on format 2 the
@@ -743,7 +805,7 @@ export async function openPancakeFile(input, options = {}) {
         // is the only binding).
         if (METRIC_NAMES[sketch.metric] !== undefined && typeof manifest.metric === 'string'
             && METRIC_NAMES[sketch.metric] !== manifest.metric) {
-            throw new Error(`.pancake index metric ${METRIC_NAMES[sketch.metric]} != manifest metric ${manifest.metric}`);
+            throw new Error(`.pikelet index metric ${METRIC_NAMES[sketch.metric]} != manifest metric ${manifest.metric}`);
         }
         if (verifyIndexVectors) {
             await sketch.verifyVectors();
@@ -788,9 +850,9 @@ export async function openPancakeFile(input, options = {}) {
                 // Hidden from bundlers like the node encoder kernels: the
                 // web entrypoint's ?url wasm imports would break a browser
                 // build that statically pulled this in.
-                const { default: Pancake } = await import(/* webpackIgnore: true */ /* @vite-ignore */ '../pancake.node.mjs');
+                const { default: Pikelet } = await import(/* webpackIgnore: true */ /* @vite-ignore */ '../src/pikelet.node.mjs');
                 await sketch.fullyResident;
-                const created = await Pancake.createSketchScanner(sketch, {
+                const created = await Pikelet.createSketchScanner(sketch, {
                     maxRerank: Math.min(sketch.count, SCANNER_MAX_RERANK),
                 });
                 disposeScanner = () => created.dispose();
@@ -805,16 +867,16 @@ export async function openPancakeFile(input, options = {}) {
         const tablesView = viewOf(tables);
         const recordCount = tablesView.getUint32(0, true);
         if (recordCount !== declaredRecords) {
-            throw new Error('.pancake corpus count disagrees with manifest');
+            throw new Error('.pikelet corpus count disagrees with manifest');
         }
         if (perRecord && tablesView.getUint32(4, true) !== pageRecords) {
-            throw new Error('.pancake corpus page size disagrees with manifest');
+            throw new Error('.pikelet corpus page size disagrees with manifest');
         }
         const recordOffsets = new Float64Array(recordCount + 1);
         for (let i = 0; i <= recordCount; i++) {
             const value = u64(tablesView, offsetsAt + 8 * i, `corpus offset ${i}`);
             if (value > corpus.length || (i > 0 && value < recordOffsets[i - 1]) || (i === 0 && value !== recordsAt)) {
-                throw new Error('.pancake corpus offsets are inconsistent');
+                throw new Error('.pikelet corpus offsets are inconsistent');
             }
             recordOffsets[i] = value;
         }
@@ -822,7 +884,7 @@ export async function openPancakeFile(input, options = {}) {
         if (perRecord) {
             pageTable = tables.slice(offsetsAt + 8 * (recordCount + 1), tablesBytes);
             if (await sha256hex(pageTable) !== manifest.corpus.pageTableSha256) {
-                throw new Error('.pancake corpus page table failed hash verification');
+                throw new Error('.pikelet corpus page table failed hash verification');
             }
         }
         const corpusIntegrity = perRecord ? (verifyRecords ? 'per-record-sha256' : 'per-record-sha256 (unverified by option)') : 'segment-sha256';
@@ -846,7 +908,7 @@ export async function openPancakeFile(input, options = {}) {
                     `corpus digest page ${page}`, maxReadBytes, fileBytes);
                 if (await sha256hex(bytes) !== toHex(pageTable.subarray(32 * page, 32 * page + 32))) {
                     digestPages.delete(page);
-                    throw new Error(`.pancake corpus digest page ${page} failed hash verification`);
+                    throw new Error(`.pikelet corpus digest page ${page} failed hash verification`);
                 }
                 return bytes;
             })();
@@ -869,7 +931,7 @@ export async function openPancakeFile(input, options = {}) {
 
         const hydrate = async (id) => {
             if (!Number.isSafeInteger(id) || id < 0 || id >= recordCount) {
-                throw new Error(`.pancake result id ${id} is outside the corpus`);
+                throw new Error(`.pikelet result id ${id} is outside the corpus`);
             }
             if (recordCache.has(id)) {
                 const cached = recordCache.get(id);
@@ -885,15 +947,15 @@ export async function openPancakeFile(input, options = {}) {
                 const digests = await pageDigests(page);
                 const at = 32 * (id - page * pageRecords);
                 if (await sha256hex(bytes) !== toHex(digests.subarray(at, at + 32))) {
-                    throw new Error(`.pancake corpus record ${id} failed integrity verification`);
+                    throw new Error(`.pikelet corpus record ${id} failed integrity verification`);
                 }
             }
             let record;
             try { record = JSON.parse(decoder.decode(bytes)); } catch (err) {
-                throw new Error(`.pancake corpus record ${id} is not valid JSON`, { cause: err });
+                throw new Error(`.pikelet corpus record ${id} is not valid JSON`, { cause: err });
             }
             if (!record || typeof record !== 'object' || Array.isArray(record)) {
-                throw new Error(`.pancake corpus record ${id} is not a JSON object`);
+                throw new Error(`.pikelet corpus record ${id} is not a JSON object`);
             }
             return cacheRecord(id, record);
         };
@@ -903,7 +965,7 @@ export async function openPancakeFile(input, options = {}) {
         // use after close instead of reading through a freed encoder.
         let closed = false;
         const assertOpen = () => {
-            if (closed) throw new Error('.pancake reader is closed');
+            if (closed) throw new Error('.pikelet reader is closed');
         };
 
         return {
@@ -976,6 +1038,8 @@ export async function openPancakeFile(input, options = {}) {
                 const pre = preScore(context);
                 let hits = [];
                 let fused = null;
+                let searched = null;
+                let fusedFull = null;
                 if (!pre) {
                     // Hybrid retrieval when the artifact carries a lexical
                     // segment: the BM25 top matches join the sketch's exact
@@ -1012,8 +1076,8 @@ export async function openPancakeFile(input, options = {}) {
                     }
                     const lexicalRaw = lexicalIndex && retrieval !== 'vector'
                         ? await lexicalIndex.search(trimmed, LEXICAL_CANDIDATES) : [];
-                    const lexicalHits = lexicalRaw.filter((h) => h.score >= lexicalRaw[0].score / 3);
-                    const searched = (await sketch.search(context.vector, k, {
+                    const lexicalHits = lexicalRaw.filter((h) => h.score >= lexicalRaw[0].score / LEXICAL_CUTOFF);
+                    searched = (await sketch.search(context.vector, k, {
                         rerank: queryOptions.rerank,
                         parallelism: queryOptions.parallelism ?? queryOptions.rerankParallelism ?? options.rerankParallelism,
                         // The identity-verified manifest may carry a fetch
@@ -1029,39 +1093,107 @@ export async function openPancakeFile(input, options = {}) {
                         // sketch reader ignores it for any query whose C
                         // exceeds the scanner's buffers.
                         ...(scanner ? { scanner } : {}),
-                        ...(lexicalHits.length ? {
-                            extraCandidates: lexicalHits.map((h) => h.id),
-                            fullRerankOutput: true,
-                        } : {}),
+                        ...(lexicalHits.length ? { extraCandidates: lexicalHits.map((h) => h.id) } : {}),
+                        // Always return the full reranked candidate list
+                        // (already fetched and exactly scored) rather than
+                        // truncating to k: abstention is fit at a fixed
+                        // top-10 window (calibrate.mjs) independent of the
+                        // caller's k, and needs that full window to score
+                        // consistently — see retrieval-abstention.mjs.
+                        fullRerankOutput: true,
                     })).results;
                     hits = searched.slice(0, k);
-                    if (retrieval === 'augmented') {
-                        fused = null; // distance order, candidates already augmented
-                    } else if (retrieval === 'lexical') {
+                    // Full-window fused order (not k-truncated) for scoring:
+                    // coverage grounds its verdict in the passage fusion
+                    // actually ranks first, and calibrate.mjs fits it the
+                    // same way — a k-truncated fused list would silently
+                    // drop the fused top hit for callers requesting a small k.
+                    if (retrieval === 'lexical') {
                         const byId = new Map(searched.map((hit) => [hit.id, hit]));
-                        fused = lexicalHits.map((h) => byId.get(h.id)).filter(Boolean).slice(0, k);
-                    } else if (lexicalHits.length) {
+                        fusedFull = lexicalHits.map((h) => byId.get(h.id)).filter(Boolean);
+                    } else if (retrieval !== 'augmented' && lexicalHits.length) {
                         const lexRank = new Map(lexicalHits.map((h, i) => [h.id, i]));
-                        fused = searched
-                            .map((hit, vRank) => ({
-                                hit,
-                                score: 1 / (RRF_K + vRank) + (lexRank.has(hit.id) ? 1 / (RRF_K + lexRank.get(hit.id)) : 0),
-                            }))
-                            .sort((a, b) => (b.score - a.score) || (a.hit.distance - b.hit.distance))
-                            .slice(0, k)
-                            .map((entry) => entry.hit);
+                        fusedFull = fuseCandidates(searched, lexicalHits.map((h) => h.id));
+                        // One batched hydration for everything this block and
+                        // scoreQuality's coverage term (below) will need, in
+                        // place of two separate staged fetches (phrase-pin's
+                        // own, then a later cold start for coverage): over a
+                        // remote range-read source each hydrate() a caller
+                        // hasn't already paid for is its own network round
+                        // trip, and sequential/staged awaits pay that cost
+                        // once per stage instead of once per query. The
+                        // union of phrase-pin's candidates (top lexical
+                        // hits) and coverage's (fusedFull's top few — phrase
+                        // pinning only ever reorders that window, never
+                        // changes its membership) is known right here, so
+                        // both stages can share one round trip. A record
+                        // that fails to hydrate here does not fail the
+                        // query: the id is just missing from the map, and
+                        // each site below falls through exactly as it would
+                        // on a cold cache miss (recs[i] undefined; coverage
+                        // sees fewer usable passages) — hydrate() raising
+                        // for a bad id is still a real failure, but only
+                        // once a site actually needs that specific record,
+                        // not speculatively for every candidate touched here.
+                        const phraseCandidates = lexicalHits.slice(0, 3);
+                        const coverageCandidates = fusedFull.slice(0, COVERAGE_BATCH_COUNT);
+                        const batchIds = [...new Set([...phraseCandidates, ...coverageCandidates].map((h) => h.id))];
+                        const batch = new Map();
+                        await Promise.all(batchIds.map(async (id) => {
+                            try { batch.set(id, await hydrate(id)); } catch { /* see comment above */ }
+                        }));
+                        // Phrase pinning: a verbatim occurrence of the query (>= 3
+                        // content words) in one of the top lexical hits is the
+                        // strongest evidence of support there is; rank it first.
+                        const norm = (t) => String(t || '').toLowerCase().replace(/[^a-z0-9' ]+/g, ' ').replace(/\s+/g, ' ').trim();
+                        const phrase = norm(trimmed);
+                        if (phrase.split(' ').length >= 3) {
+                            for (const h of phraseCandidates) {
+                                if (norm(batch.get(h.id)?.text).includes(phrase)) {
+                                    fusedFull = [searched.find((x) => x.id === h.id), ...fusedFull.filter((x) => x.id !== h.id)].filter(Boolean);
+                                    break;
+                                }
+                            }
+                        }
+                        // Rank transparency: a consumer can see a verbatim hit sitting
+                        // at fused rank 3 behind two semantic near-misses.
+                        for (const [i, hit] of fusedFull.entries()) { hit.fusedRank = i + 1; hit.lexicalRank = lexRank.has(hit.id) ? lexRank.get(hit.id) + 1 : null; hit.vectorRank = searched.findIndex((x) => x.id === hit.id) + 1; }
                     }
+                    fused = retrieval === 'augmented' ? null : fusedFull?.slice(0, k) ?? null;
                 }
-                const quality = pre || await scoreQuality(hits, context);
-                const returned = quality.match_quality === 'none' ? [] : (fused || hits);
+                // Abstention scores the full reranked candidate window
+                // (searched), not the k-truncated hits: calibrate.mjs fits
+                // its signals at a fixed top-10 (top-5 for coverage)
+                // regardless of how many results a caller ultimately
+                // requests, so scoring must use the same window to match.
+                // preScore (kind 1) runs before search and has no window to
+                // fix, so it is unaffected. fusedFull (RRF over the same
+                // full window, not k-truncated) is threaded through
+                // separately so coverage grades the passage fusion actually
+                // ranks first, while d0/margin/mean10 still read vector
+                // order (searched) exactly as calibrated.
+                const quality = pre || await scoreQuality(searched ?? hits, context, fusedFull);
+                // A 'none' verdict withholds results by default — the
+                // calibrated abstention signal is doing its job, and most
+                // callers want that. showAbstained is an explicit opt-out
+                // for a caller that wants the raw retrieval anyway (e.g. to
+                // inspect why the classifier abstained); it never changes
+                // matchQuality or confidence, only whether results ships.
+                const returned = quality.match_quality === 'none' && !queryOptions.showAbstained
+                    ? [] : (fused || hits);
                 // The search's id and distance are authoritative: they are
                 // written last so a corpus record carrying its own `id` or
                 // `distance` field cannot overwrite them (reserved names).
                 const results = await Promise.all(returned.map(async (hit) => {
                     const record = await hydrate(hit.id);
-                    return { ...record, id: hit.id, distance: hit.distance };
+                    return { ...record, id: hit.id, distance: hit.distance, ...(hit.fusedRank ? { fusedRank: hit.fusedRank, lexicalRank: hit.lexicalRank, vectorRank: hit.vectorRank } : {}) };
                 }));
-                return { matchQuality: quality.match_quality, confidence: quality.confidence, results };
+                // Grounding transparency: which record's text grounded the verdict
+                // and which query words it covered, so a consumer can tell a
+                // topical match ("much money darcy make year") from an answer.
+                const passageOrder = fusedFull?.length ? fusedFull : (searched ?? hits);
+                const grounding = quality.grounding ? { ...quality.grounding, recordId: passageOrder[quality.grounding.passageIndex]?.id ?? null } : null;
+                return { matchQuality: quality.match_quality, confidence: quality.confidence, results, ...(grounding ? { grounding } : {}) };
             },
 
             /** Hydrate one corpus record by id (verified per record on format 2). */
@@ -1087,14 +1219,14 @@ export async function openPancakeFile(input, options = {}) {
                 if (!ev) return null;
                 const bytes = await readChecked(source, ev.offset, ev.length, 'evaluation segment', maxReadBytes, fileBytes);
                 if (await sha256hex(bytes) !== ev.sha256) {
-                    throw new Error('.pancake evaluation segment failed hash verification');
+                    throw new Error('.pikelet evaluation segment failed hash verification');
                 }
                 let parsed;
                 try { parsed = JSON.parse(decoder.decode(bytes)); } catch (err) {
-                    throw new Error('.pancake evaluation segment is not valid JSON', { cause: err });
+                    throw new Error('.pikelet evaluation segment is not valid JSON', { cause: err });
                 }
                 if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed)) {
-                    throw new Error('.pancake evaluation segment must be a JSON object');
+                    throw new Error('.pikelet evaluation segment must be a JSON object');
                 }
                 return parsed;
             },
@@ -1119,6 +1251,3 @@ export async function openPancakeFile(input, options = {}) {
         throw err;
     }
 }
-
-// Documented alias (see the rename note at the top of this file).
-export { openPancakeFile as openPikeletFile };