mixdog 0.9.156 → 0.9.157

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mixdog",
-  "version": "0.9.156",
+  "version": "0.9.157",
   "private": false,
   "type": "module",
   "description": "Standalone mixdog coding-agent CLI/TUI workspace.",
@@ -54,7 +54,7 @@
     "smoke:all": "npm run smoke && npm run smoke:boot && npm run smoke:patch && npm run smoke:compact",
     "smoke:boot": "node scripts/boot-smoke.mjs",
     "smoke:compact": "node scripts/compact-smoke.mjs",
-    "test:compact": "node --test scripts/suite-compact-test.mjs",
+    "test:compact": "node --test scripts/suite-compact-test.mjs src/runtime/agent/orchestrator/session/token-estimate.test.mjs",
     "test:markdown": "node --test scripts/markdown-surface-test.mjs",
     "smoke:loop": "node scripts/smoke-loop.mjs",
     "smoke:loop:final": "node scripts/smoke-loop-report.mjs --require-complete --min-elapsed 5h --min-iterations 400 --max-gap 60s --max-smoke-ms 10000 --max-avg-smoke-ms 8500 --max-step-ms smoke.mjs=4000 --max-step-ms boot-smoke.mjs=8000 --max-rss-mb 140 --max-rss-growth-mb 50",
@@ -72,7 +72,7 @@
     "test:session-transport": "node --test scripts/session-transport-test.mjs scripts/daemon-bootstrap-test.mjs src/runtime/shared/child-spawn-remote.test.mjs src/standalone/session-runtime-agent-control-client.test.mjs src/standalone/session-runtime-dispatch-cancel.test.mjs src/standalone/session-runtime-host-factory.test.mjs src/standalone/session-runtime-inline-host.test.mjs src/standalone/session-runtime-provider-cooldown.test.mjs src/standalone/session-runtime-shard-host.test.mjs src/standalone/session-runtime-shard-router.test.mjs",
     "test:session": "node --test scripts/runtime-turn-contract-test.mjs scripts/session-save-fault-store-test.mjs scripts/turn-review-revert-test.mjs src/runtime/shared/tool-surface.test.mjs src/runtime/bridge-clients.test.mjs",
     "test:quick": "npm run test:session && npm run test:session-transport && npm run test:desktop-main --prefix apps/desktop",
-    "test:office": "node --test src/runtime/office/office-runtime.test.mjs src/runtime/office/office-assurance.test.mjs src/runtime/office/portable-authoring.test.mjs && npm run test:office-approval --prefix apps/desktop",
+    "test:office": "node --test scripts/run-office-live-tests.test.mjs src/runtime/office/office-runtime.test.mjs src/runtime/office/office-assurance.test.mjs src/runtime/office/portable-authoring.test.mjs && npm run test:office-approval --prefix apps/desktop",
     "test:office:live": "node scripts/run-office-live-tests.mjs",
     "test:media": "node --test src/runtime/media/store.test.mjs src/runtime/media/renditions.test.mjs src/runtime/media/adapters/codex-image.test.mjs",
     "failures": "node scripts/tool-failures.mjs",
@@ -125,7 +125,7 @@
   "dependencies": {
     "@anthropic-ai/sdk": "^0.105.0",
     "@google/generative-ai": "^0.24.1",
-    "@huggingface/transformers": "^3.8.1",
+    "@huggingface/transformers": "^4.2.0",
     "@modelcontextprotocol/sdk": "^1.29.0",
     "@mozilla/readability": "^0.6.0",
     "@napi-rs/canvas": "^1.0.8",
@@ -136,10 +136,9 @@
     "ink": "^7.1.0",
     "jsdom": "^27.0.0",
     "jszip": "^3.10.1",
-    "kiwi-nlp": "^0.21.0",
     "marked": "^14.1.4",
     "node-cron": "^4.5.0",
-    "onnxruntime-node": "1.23.2",
+    "onnxruntime-node": "1.29.0",
     "openai": "^6.44.0",
     "pdf-lib": "^1.17.1",
     "pdfjs-dist": "^6.2.108",
@@ -150,7 +149,6 @@
     "string-width": "^8.2.1",
     "strip-ansi": "^7.2.0",
     "tesseract.js": "^7.0.0",
-    "tiktoken": "^1.0.22",
     "undici": "^8.5.0",
     "unpdf": "^1.8.0",
     "wrap-ansi": "^10.0.0",
@@ -160,7 +158,7 @@
   },
   "overrides": {
     "onnxruntime-node": {
-      ".": "1.23.2",
+      ".": "1.29.0",
       "global-agent": "^4.1.3"
     },
     "sharp": "^0.35.3"

package/scripts/build-ffmpeg-runtime.sh

@@ -0,0 +1,141 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+FFMPEG_VERSION="${FFMPEG_VERSION:-6.1.1}"
+TARGET_OS="${TARGET_OS:?TARGET_OS is required}"
+TARGET_ARCH="${TARGET_ARCH:?TARGET_ARCH is required}"
+ROOT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
+BUILD_DIR="$ROOT_DIR/build/ffmpeg-runtime-${TARGET_OS}-${TARGET_ARCH}"
+SOURCE_DIR="$BUILD_DIR/ffmpeg-${FFMPEG_VERSION}"
+DIST_DIR="$ROOT_DIR/dist"
+
+rm -rf "$BUILD_DIR"
+mkdir -p "$BUILD_DIR" "$DIST_DIR"
+
+echo "==> Downloading FFmpeg n${FFMPEG_VERSION}"
+curl -fsSL --retry 3 \
+  "https://ffmpeg.org/releases/ffmpeg-${FFMPEG_VERSION}.tar.xz" \
+  -o "$BUILD_DIR/ffmpeg.tar.xz"
+tar -xJf "$BUILD_DIR/ffmpeg.tar.xz" -C "$BUILD_DIR"
+
+CONFIGURE_FLAGS=(
+  --disable-everything
+  --disable-autodetect
+  --disable-debug
+  --disable-doc
+  --disable-network
+  --disable-shared
+  --enable-static
+  --enable-small
+  --enable-ffmpeg
+  --enable-avcodec
+  --enable-avfilter
+  --enable-avformat
+  --enable-swresample
+  --enable-protocol=file,pipe
+  --enable-demuxer=aac,ac3,aiff,amr,ape,asf,au,avi,caf,flac,flv,matroska,mov,mp3,mpegts,ogg,wav,wv
+  --enable-decoder=aac,aac_fixed,ac3,alac,amrnb,amrwb,ape,eac3,flac,mp1,mp1float,mp2,mp2float,mp3,mp3float,opus,pcm_alaw,pcm_f32be,pcm_f32le,pcm_f64be,pcm_f64le,pcm_mulaw,pcm_s16be,pcm_s16le,pcm_s24be,pcm_s24le,pcm_s32be,pcm_s32le,pcm_s8,pcm_u16be,pcm_u16le,pcm_u24be,pcm_u24le,pcm_u32be,pcm_u32le,pcm_u8,vorbis,wavpack,wmav1,wmav2,wmapro
+  --enable-encoder=pcm_s16le
+  --enable-parser=aac,aac_latm,ac3,flac,mpegaudio,opus,vorbis
+  --enable-filter=aformat,anull,aresample
+  --enable-muxer=wav
+)
+
+EXE_NAME=ffmpeg
+STRIP_COMMAND=strip
+if [[ "$TARGET_OS" == "win32" ]]; then
+  CONFIGURE_FLAGS+=(
+    --target-os=mingw32
+    --arch=x86_64
+    --cc=gcc
+    --ar=ar
+    --ranlib=ranlib
+    --nm=nm
+    --strip=strip
+    --extra-ldflags=-static
+  )
+  EXE_NAME=ffmpeg.exe
+elif [[ "$TARGET_OS" == "darwin" ]]; then
+  STRIP_COMMAND="strip -x"
+fi
+
+echo "==> Configuring minimal audio-transcode runtime"
+pushd "$SOURCE_DIR" >/dev/null
+./configure "${CONFIGURE_FLAGS[@]}"
+make -j"$(getconf _NPROCESSORS_ONLN 2>/dev/null || sysctl -n hw.logicalcpu)"
+popd >/dev/null
+
+RUNTIME_EXE="$SOURCE_DIR/ffmpeg"
+if [[ "$TARGET_OS" == "win32" ]]; then
+  RUNTIME_EXE="$SOURCE_DIR/ffmpeg.exe"
+fi
+if [[ ! -f "$RUNTIME_EXE" ]]; then
+  echo "FFmpeg build did not produce $RUNTIME_EXE" >&2
+  exit 1
+fi
+
+read -r -a STRIP_PARTS <<< "$STRIP_COMMAND"
+"${STRIP_PARTS[@]}" "$RUNTIME_EXE"
+
+echo "==> Smoke testing WAV normalization"
+PYTHON_COMMAND=
+for candidate in python3 python; do
+  if command -v "$candidate" >/dev/null 2>&1; then
+    PYTHON_COMMAND="$candidate"
+    break
+  fi
+done
+if [[ -z "$PYTHON_COMMAND" ]]; then
+  echo "Python 3 is required for the FFmpeg runtime smoke test" >&2
+  exit 1
+fi
+
+"$PYTHON_COMMAND" - "$BUILD_DIR/input.wav" <<'PY'
+import math
+import struct
+import sys
+import wave
+
+with wave.open(sys.argv[1], "wb") as wav:
+    wav.setnchannels(2)
+    wav.setsampwidth(2)
+    wav.setframerate(48000)
+    frames = bytearray()
+    for index in range(4800):
+        sample = int(math.sin(index * 2 * math.pi * 440 / 48000) * 12000)
+        frames.extend(struct.pack("<hh", sample, sample))
+    wav.writeframes(frames)
+PY
+"$RUNTIME_EXE" -hide_banner -loglevel error \
+  -i "$BUILD_DIR/input.wav" -ar 16000 -ac 1 -threads 1 -y "$BUILD_DIR/output.wav"
+"$PYTHON_COMMAND" - "$BUILD_DIR/output.wav" <<'PY'
+import sys
+import wave
+
+with wave.open(sys.argv[1], "rb") as wav:
+    assert wav.getframerate() == 16000
+    assert wav.getnchannels() == 1
+    assert wav.getnframes() > 0
+PY
+
+RUNTIME_BYTES="$(wc -c < "$RUNTIME_EXE" | tr -d ' ')"
+if (( RUNTIME_BYTES > 26214400 )); then
+  echo "Minimal FFmpeg exceeds 25 MiB: $RUNTIME_BYTES bytes" >&2
+  exit 1
+fi
+
+ASSET_NAME="ffmpeg-${TARGET_OS}-${TARGET_ARCH}.gz"
+gzip -9 -n -c "$RUNTIME_EXE" > "$DIST_DIR/$ASSET_NAME"
+ASSET_BYTES="$(wc -c < "$DIST_DIR/$ASSET_NAME" | tr -d ' ')"
+if (( ASSET_BYTES > 15728640 )); then
+  echo "Compressed FFmpeg exceeds 15 MiB: $ASSET_BYTES bytes" >&2
+  exit 1
+fi
+
+if command -v sha256sum >/dev/null 2>&1; then
+  (cd "$DIST_DIR" && sha256sum "$ASSET_NAME" > "$ASSET_NAME.sha256")
+else
+  (cd "$DIST_DIR" && shasum -a 256 "$ASSET_NAME" > "$ASSET_NAME.sha256")
+fi
+
+echo "Built $DIST_DIR/$ASSET_NAME ($RUNTIME_BYTES bytes raw, $ASSET_BYTES bytes compressed)"

package/scripts/generate-voice-runtime-manifest.mjs

@@ -10,6 +10,7 @@ const RELEASE_HASH_INPUTS = [
   new URL('../.github/workflows/build-voice-runtime.yml', import.meta.url),
   new URL('./build-voice-runtime-unix.sh', import.meta.url),
   new URL('./build-voice-runtime-windows.ps1', import.meta.url),
+  new URL('./build-ffmpeg-runtime.sh', import.meta.url),
   new URL('./generate-voice-runtime-manifest.mjs', import.meta.url),
 ]
 
@@ -21,6 +22,9 @@ function loadVoiceRuntimeConfig() {
   if (!/^[a-f0-9]{40}$/.test(config.whisperCommit || '')) {
     throw new Error('voice runtime config has an invalid whisperCommit')
   }
+  if (!/^\d+\.\d+\.\d+-mixdog\.\d+$/.test(config.ffmpegVersion || '')) {
+    throw new Error('voice runtime config has an invalid ffmpegVersion')
+  }
   if (!Array.isArray(config.platforms) || config.platforms.length === 0) {
     throw new Error('voice runtime config has no platforms')
   }
@@ -133,6 +137,38 @@ export function buildVoiceRuntimePlatforms(
   return platforms
 }
 
+function ffmpegAssetName(spec) {
+  return `ffmpeg-${spec.os}-${spec.arch}.gz`
+}
+
+export function buildVoiceFfmpegPlatforms(
+  releaseAssets,
+  { repository = 'tribgames/mixdog', tag = VOICE_RUNTIME_TAG } = {},
+) {
+  const byName = new Map((releaseAssets || []).map((asset) => [asset.name, asset]))
+  const platforms = {}
+  for (const spec of VOICE_RUNTIME_CONFIG.platforms) {
+    const assetName = ffmpegAssetName(spec)
+    const asset = byName.get(assetName)
+    if (!asset) throw new Error(`release is missing required asset ${assetName}`)
+    if (!Number.isSafeInteger(asset.size) || asset.size <= 0) {
+      throw new Error(`release asset ${assetName} has invalid size`)
+    }
+    platforms[spec.key] = {
+      url: `https://github.com/${repository}/releases/download/${tag}/${assetName}`,
+      sha256: releaseAssetSha256(asset),
+      size: asset.size,
+      format: 'gz',
+      executable: spec.os === 'win32' ? 'ffmpeg.exe' : 'ffmpeg',
+    }
+  }
+  return {
+    version: VOICE_RUNTIME_CONFIG.ffmpegVersion,
+    source: 'FFmpeg n6.1.1 minimal audio-transcode build',
+    platforms,
+  }
+}
+
 function githubHeaders(token, accept = 'application/vnd.github+json') {
   return {
     Accept: accept,
@@ -207,6 +243,7 @@ export function voiceRuntimeIdentity(manifest) {
     source: manifest?.source,
     release_tag: manifest?.release_tag,
     build_hash: manifest?.build_hash,
+    ffmpeg: manifest?.ffmpeg,
     platforms: manifest?.platforms,
   }
 }
@@ -258,6 +295,36 @@ export async function assertVoiceRuntimeManifestIdentity(
       throw new Error(`voice runtime manifest ${spec.key} does not match the release config`)
     }
   }
+  const expectedFfmpeg = buildVoiceFfmpegPlatforms(
+    VOICE_RUNTIME_CONFIG.platforms.map((spec, index) => ({
+      name: ffmpegAssetName(spec),
+      size: index + 1,
+      digest: `sha256:${String(index + 1).padStart(64, '0')}`,
+    })),
+    { repository, tag: VOICE_RUNTIME_TAG },
+  )
+  if (
+    manifest?.ffmpeg?.version !== expectedFfmpeg.version
+    || manifest?.ffmpeg?.source !== expectedFfmpeg.source
+    || JSON.stringify(Object.keys(manifest?.ffmpeg?.platforms || {}))
+      !== JSON.stringify(Object.keys(expectedFfmpeg.platforms))
+  ) {
+    throw new Error('voice runtime FFmpeg manifest does not match the release config')
+  }
+  for (const spec of VOICE_RUNTIME_CONFIG.platforms) {
+    const actual = manifest.ffmpeg.platforms[spec.key]
+    const expected = expectedFfmpeg.platforms[spec.key]
+    if (
+      actual?.url !== expected.url
+      || actual?.format !== expected.format
+      || actual?.executable !== expected.executable
+      || !/^[a-f0-9]{64}$/.test(actual?.sha256 || '')
+      || !Number.isSafeInteger(actual?.size)
+      || actual.size <= 0
+    ) {
+      throw new Error(`voice runtime FFmpeg ${spec.key} does not match the release config`)
+    }
+  }
 }
 
 async function main() {
@@ -269,11 +336,13 @@ async function main() {
   const manifestPath = resolve(process.argv[2] || 'src/runtime/channels/data/voice-runtime-manifest.json')
   const manifest = JSON.parse(await readFile(manifestPath, 'utf8'))
   let platforms
+  let ffmpeg
   let lastError
   for (let attempt = 1; attempt <= 5; attempt++) {
     try {
       const release = await fetchGithubRelease(repository, tag, process.env.GITHUB_TOKEN)
       platforms = buildVoiceRuntimePlatforms(release.assets, { repository, tag })
+      ffmpeg = buildVoiceFfmpegPlatforms(release.assets, { repository, tag })
       lastError = null
       break
     } catch (error) {
@@ -286,6 +355,7 @@ async function main() {
   manifest.source = `ggml-org/whisper.cpp@${VOICE_RUNTIME_COMMIT}`
   manifest.release_tag = tag
   manifest.build_hash = await voiceRuntimeBuildHash()
+  manifest.ffmpeg = ffmpeg
   manifest.platforms = platforms
   await writeFile(manifestPath, `${JSON.stringify(manifest, null, 2)}\n`)
   console.log(`updated ${manifestPath} from ${tag}`)

package/scripts/lib/embedding-model-bench-core.mjs

@@ -0,0 +1,353 @@
+import { createHash } from 'node:crypto'
+import { parsePeriod } from '../../src/runtime/memory/lib/recall-format.mjs'
+
+export const CASE_FILES = Object.freeze([
+  'recall-bench-cases.json',
+  'recall-quality-cases.json',
+  'recall-repo-cases.json',
+  'recall-usecase-cases.json',
+  'recall-event-cases.json',
+  'recall-history-cases.json',
+])
+
+const RETRIEVAL_INSTRUCTION = 'Given a web search query, retrieve relevant passages that answer the query'
+
+export const MODEL_SPECS = Object.freeze({
+  harrier: Object.freeze({
+    label: 'Harrier 270M q4',
+    modelId: 'onnx-community/harrier-oss-v1-270m-ONNX',
+    dtype: 'q4',
+    pooling: 'last_token',
+    outputName: 'sentence_embedding',
+    queryPrefix: `Instruct: ${RETRIEVAL_INSTRUCTION}\nQuery: `,
+    documentPrefix: '',
+    batchSize: 16,
+  }),
+  granite97: Object.freeze({
+    label: 'Granite 97M quint8',
+    modelId: 'ibm-granite/granite-embedding-97m-multilingual-r2',
+    dtype: 'fp32',
+    modelFileName: 'model_quint8_avx2',
+    pooling: 'cls',
+    outputName: '',
+    queryPrefix: '',
+    documentPrefix: '',
+    batchSize: 16,
+  }),
+  e5small: Object.freeze({
+    label: 'multilingual-e5-small q8',
+    modelId: 'Xenova/multilingual-e5-small',
+    dtype: 'q8',
+    pooling: 'mean',
+    outputName: '',
+    queryPrefix: 'query: ',
+    documentPrefix: 'passage: ',
+    batchSize: 16,
+  }),
+  embeddinggemma: Object.freeze({
+    label: 'EmbeddingGemma 300M q4',
+    modelId: 'onnx-community/embeddinggemma-300m-ONNX',
+    dtype: 'q4',
+    pooling: 'mean',
+    outputName: 'sentence_embedding',
+    queryPrefix: 'task: search result | query: ',
+    documentPrefix: 'title: none | text: ',
+    batchSize: 16,
+  }),
+  bgem3: Object.freeze({
+    label: 'BGE-M3 q4',
+    modelId: 'Xenova/bge-m3',
+    dtype: 'q4',
+    pooling: 'cls',
+    outputName: '',
+    queryPrefix: '',
+    documentPrefix: '',
+    batchSize: 16,
+  }),
+  qwen3: Object.freeze({
+    label: 'Qwen3-Embedding 0.6B q8',
+    modelId: 'onnx-community/Qwen3-Embedding-0.6B-ONNX',
+    dtype: 'q8',
+    pooling: 'last_token',
+    outputName: '',
+    queryPrefix: `Instruct: ${RETRIEVAL_INSTRUCTION}\nQuery:`,
+    documentPrefix: '',
+    batchSize: 16,
+  }),
+})
+
+export function documentText(row) {
+  return [row?.element, row?.summary].filter(Boolean).join(' — ').trim()
+}
+
+export function classifyQueryLanguage(query) {
+  const text = String(query || '')
+  const hasHangul = /[\uac00-\ud7a3]/u.test(text)
+  const hasLatin = /[A-Za-z]/u.test(text)
+  if (hasHangul && hasLatin) return 'mixed'
+  if (hasHangul) return 'ko'
+  if (hasLatin) return 'en'
+  return 'other'
+}
+
+export function buildEvaluation(caseFile, kase) {
+  const query = kase?.args?.query
+  const targets = Array.isArray(kase?.expect?.topNContains)
+    ? kase.expect.topNContains.map((value) => String(value || '')).filter(Boolean)
+    : []
+  if (typeof query !== 'string' || !query.trim() || targets.length === 0) return null
+  const temporal = parsePeriod(String(kase?.args?.period || ''), true)
+  return {
+    id: String(kase.id),
+    caseFile,
+    label: String(kase.label || kase.id),
+    query: query.trim(),
+    language: classifyQueryLanguage(query),
+    targets,
+    contractTopN: Number.isInteger(kase?.expect?.topN) ? kase.expect.topN : 5,
+    filter: {
+      projectScope: String(kase?.args?.projectScope || 'mixdog'),
+      categories: (Array.isArray(kase?.args?.category) ? kase.args.category : [kase?.args?.category])
+        .map((value) => String(value || '').trim().toLowerCase())
+        .filter(Boolean),
+      startMs: Number.isFinite(Number(temporal?.startMs)) ? Number(temporal.startMs) : null,
+      endMs: Number.isFinite(Number(temporal?.endMs)) ? Number(temporal.endMs) : null,
+    },
+  }
+}
+
+export function documentMatchesFilter(document, filter = {}) {
+  const scope = String(filter.projectScope || 'mixdog')
+  if (scope === 'common' && document.projectId != null) return false
+  if (scope !== 'all' && scope !== 'common' && document.projectId != null && document.projectId !== scope) return false
+  if (Array.isArray(filter.categories) && filter.categories.length > 0) {
+    if (!filter.categories.includes(String(document.category || '').toLowerCase())) return false
+  }
+  const ts = Number(document.ts)
+  if (filter.startMs != null && (!Number.isFinite(ts) || ts < filter.startMs)) return false
+  if (filter.endMs != null && (!Number.isFinite(ts) || ts > filter.endMs)) return false
+  return true
+}
+
+export function attachPositiveIds(evaluation, documents, targetMatches = new Map()) {
+  const eligible = documents.filter((document) => documentMatchesFilter(document, evaluation.filter))
+  const eligibleIds = new Set(eligible.map((document) => document.id))
+  const documentIds = new Set(documents.map((document) => document.id))
+  const positiveIdsByTarget = evaluation.targets.map((target) => {
+    const needle = target.toLowerCase()
+    const positiveIds = new Set(
+      eligible
+        .filter((document) => document.textLower.includes(needle))
+        .map((document) => document.id),
+    )
+    for (const match of targetMatches.get(needle) || []) {
+      if (!documentIds.has(match.rootId)) continue
+      if (!documentMatchesFilter(match, evaluation.filter)) continue
+      positiveIds.add(match.rootId)
+    }
+    return [...positiveIds]
+  })
+  const extraCandidateIds = [...new Set(positiveIdsByTarget.flat())]
+    .filter((id) => !eligibleIds.has(id))
+  return {
+    ...evaluation,
+    candidateCount: eligible.length + extraCandidateIds.length,
+    extraCandidateIds,
+    positiveIdsByTarget,
+  }
+}
+
+function deterministicIds(ids) {
+  return [...new Set(ids)]
+    .map((id) => ({
+      id,
+      digest: createHash('sha256').update(String(id)).digest('hex'),
+    }))
+    .sort((left, right) => left.digest.localeCompare(right.digest) || left.id - right.id)
+    .map((row) => row.id)
+}
+
+export function selectDeterministicCorpus(documents, evaluations, limit, positiveCap = 0) {
+  const requested = Number(limit)
+  const cap = Math.max(0, Math.floor(Number(positiveCap) || 0))
+  const targetPositiveIds = evaluations.flatMap((evaluation) => evaluation.positiveIdsByTarget)
+  const selectedPositiveIds = cap > 0
+    ? targetPositiveIds.flatMap((ids) => deterministicIds(ids).slice(0, cap))
+    : targetPositiveIds.flat()
+  if (!Number.isInteger(requested) || requested <= 0 || requested >= documents.length) {
+    return {
+      documents,
+      sourceDocuments: documents.length,
+      selectedDocuments: documents.length,
+      positiveDocuments: new Set(selectedPositiveIds).size,
+      method: 'full-corpus',
+    }
+  }
+  const positiveIds = new Set(selectedPositiveIds)
+  const remaining = documents
+    .filter((document) => !positiveIds.has(document.id))
+    .map((document) => ({
+      id: document.id,
+      digest: createHash('sha256').update(String(document.id)).digest('hex'),
+    }))
+    .sort((left, right) => left.digest.localeCompare(right.digest) || left.id - right.id)
+  const selectedIds = new Set(positiveIds)
+  const targetSize = Math.max(requested, selectedIds.size)
+  for (const row of remaining) {
+    if (selectedIds.size >= targetSize) break
+    selectedIds.add(row.id)
+  }
+  return {
+    documents: documents.filter((document) => selectedIds.has(document.id)),
+    sourceDocuments: documents.length,
+    selectedDocuments: selectedIds.size,
+    positiveDocuments: positiveIds.size,
+    method: `${cap > 0 ? `up-to-${cap}-positive-roots-per-target` : 'all-positive-roots'} + sha256(document-id) negatives`,
+  }
+}
+
+export function tokenizeBm25(text) {
+  return String(text || '').toLowerCase().match(/[\p{L}\p{N}_-]+/gu) || []
+}
+
+export function prepareBm25Documents(documents) {
+  return documents.map((document) => {
+    const tokens = tokenizeBm25(document.text)
+    const termFrequency = new Map()
+    for (const token of tokens) termFrequency.set(token, (termFrequency.get(token) || 0) + 1)
+    return { length: tokens.length, termFrequency }
+  })
+}
+
+export function rankBm25(query, candidateIndices, preparedDocuments, k1 = 1.2, b = 0.75) {
+  const terms = [...new Set(tokenizeBm25(query))]
+  if (terms.length === 0 || candidateIndices.length === 0) return []
+  const averageLength = candidateIndices.reduce(
+    (sum, index) => sum + preparedDocuments[index].length,
+    0,
+  ) / candidateIndices.length
+  const documentFrequency = new Map(terms.map((term) => [term, 0]))
+  for (const index of candidateIndices) {
+    const tf = preparedDocuments[index].termFrequency
+    for (const term of terms) if (tf.has(term)) documentFrequency.set(term, documentFrequency.get(term) + 1)
+  }
+  const scored = []
+  for (const index of candidateIndices) {
+    const document = preparedDocuments[index]
+    let score = 0
+    for (const term of terms) {
+      const frequency = document.termFrequency.get(term) || 0
+      if (frequency === 0) continue
+      const df = documentFrequency.get(term) || 0
+      const idf = Math.log(1 + ((candidateIndices.length - df + 0.5) / (df + 0.5)))
+      const denominator = frequency + k1 * (1 - b + b * (document.length / Math.max(1, averageLength)))
+      score += idf * ((frequency * (k1 + 1)) / denominator)
+    }
+    if (score > 0) scored.push({ index, score })
+  }
+  scored.sort((left, right) => right.score - left.score || left.index - right.index)
+  return scored
+}
+
+export function rankDense(queryVector, documentVectors, dims, candidateIndices) {
+  const scored = new Array(candidateIndices.length)
+  for (let position = 0; position < candidateIndices.length; position += 1) {
+    const index = candidateIndices[position]
+    const offset = index * dims
+    let score = 0
+    for (let dimension = 0; dimension < dims; dimension += 1) {
+      score += queryVector[dimension] * documentVectors[offset + dimension]
+    }
+    scored[position] = { index, score }
+  }
+  scored.sort((left, right) => right.score - left.score || left.index - right.index)
+  return scored
+}
+
+export function rankEqualRrf(denseRanked, lexicalRanked, k = 60) {
+  const scores = new Map()
+  for (let index = 0; index < denseRanked.length; index += 1) {
+    scores.set(denseRanked[index].index, 1 / (k + index + 1))
+  }
+  for (let index = 0; index < lexicalRanked.length; index += 1) {
+    const documentIndex = lexicalRanked[index].index
+    scores.set(documentIndex, (scores.get(documentIndex) || 0) + 1 / (k + index + 1))
+  }
+  return [...scores.entries()]
+    .map(([index, score]) => ({ index, score }))
+    .sort((left, right) => right.score - left.score || left.index - right.index)
+}
+
+function discountedGain(rank) {
+  return 1 / Math.log2(rank + 1)
+}
+
+export function scoreRanking(evaluation, ranked, documents, cutoff = 10) {
+  const rankById = new Map()
+  for (let index = 0; index < ranked.length; index += 1) {
+    rankById.set(documents[ranked[index].index].id, index + 1)
+  }
+  const targetRows = evaluation.targets.map((target, index) => {
+    const positiveIds = evaluation.positiveIdsByTarget[index] || []
+    let rank = null
+    for (const id of positiveIds) {
+      const value = rankById.get(id)
+      if (value != null && (rank == null || value < rank)) rank = value
+    }
+    return {
+      target,
+      positiveCount: positiveIds.length,
+      rank,
+      rrAt10: rank != null && rank <= cutoff ? 1 / rank : 0,
+      recallAt5: rank != null && rank <= 5 ? 1 : 0,
+      recallAt10: rank != null && rank <= cutoff ? 1 : 0,
+    }
+  })
+  const relevantIds = new Set(evaluation.positiveIdsByTarget.flat())
+  let dcg = 0
+  for (let index = 0; index < Math.min(cutoff, ranked.length); index += 1) {
+    if (relevantIds.has(documents[ranked[index].index].id)) dcg += discountedGain(index + 1)
+  }
+  let idealDcg = 0
+  for (let rank = 1; rank <= Math.min(cutoff, relevantIds.size); rank += 1) idealDcg += discountedGain(rank)
+  const divisor = targetRows.length || 1
+  return {
+    mrrAt10: targetRows.reduce((sum, row) => sum + row.rrAt10, 0) / divisor,
+    recallAt5: targetRows.reduce((sum, row) => sum + row.recallAt5, 0) / divisor,
+    recallAt10: targetRows.reduce((sum, row) => sum + row.recallAt10, 0) / divisor,
+    ndcgAt10: idealDcg > 0 ? dcg / idealDcg : 0,
+    targets: targetRows,
+    top3: ranked.slice(0, 3).map((row) => ({
+      id: documents[row.index].id,
+      score: row.score,
+      text: documents[row.index].text.slice(0, 240),
+    })),
+  }
+}
+
+function mean(rows, key) {
+  if (rows.length === 0) return 0
+  return rows.reduce((sum, row) => sum + Number(row[key] || 0), 0) / rows.length
+}
+
+export function aggregateScoredRows(rows) {
+  const aggregate = (subset) => ({
+    cases: subset.length,
+    mrrAt10: mean(subset, 'mrrAt10'),
+    recallAt5: mean(subset, 'recallAt5'),
+    recallAt10: mean(subset, 'recallAt10'),
+    ndcgAt10: mean(subset, 'ndcgAt10'),
+  })
+  const byLanguage = {}
+  for (const language of ['ko', 'en', 'mixed', 'other']) {
+    byLanguage[language] = aggregate(rows.filter((row) => row.language === language))
+  }
+  return { overall: aggregate(rows), byLanguage }
+}
+
+export function percentile(values, ratio) {
+  if (!Array.isArray(values) || values.length === 0) return 0
+  const sorted = [...values].sort((left, right) => left - right)
+  const index = Math.min(sorted.length - 1, Math.max(0, Math.ceil(sorted.length * ratio) - 1))
+  return sorted[index]
+}