@takara-ai/miru-code 1.8.2 → 1.10.0

package/src/cli.ts

@@ -2,6 +2,7 @@
 import { type AgentId, writeAgentFile } from "./agents.ts";
 import { clearBenchmarkHistory, resolveBenchmarkHistoryPath } from "./benchmark/history.ts";
 import { clearCache } from "./cache.ts";
+import { shouldRunMcp } from "./cli-mode.ts";
 import {
   fail,
   formatRelatedHeader,
@@ -26,7 +27,6 @@ import {
   printSageMakerHelp,
 } from "./help.ts";
 import { getBenchmarkModeStatus, setBenchmarkMode } from "./installer/benchmark-mode.ts";
-import { runSearchGuardFromStdin } from "./installer/hooks/search-guard.ts";
 import { runInstaller } from "./installer/installer.ts";
 import { promptConfirm } from "./installer/prompt.ts";
 import {
@@ -56,6 +56,7 @@ import {
   resolveChunk,
   resolveContent,
   resolveSearchPath,
+  SEARCH_RESULT_COUNT,
 } from "./utils.ts";
 import { maybeNotifyUpdate, miruVersion } from "./version.ts";
 
@@ -71,27 +72,6 @@ try {
   // Leave recovery to ensureCredentials / setup.
 }
 
-const CLI_COMMANDS = new Set([
-  "search",
-  "locate",
-  "expand",
-  "find-related",
-  "init",
-  "install",
-  "uninstall",
-  "setup",
-  "clear",
-  "benchmark",
-  "env",
-  "environment",
-  "hook-guard",
-  "help",
-  "-h",
-  "--help",
-  "-v",
-  "--version",
-]);
-
 const AGENTS = new Set<AgentId>(AGENT_IDS);
 
 function parseFlagArgv(argv: string[], flag: string): { present: boolean; rest: string[] } {
@@ -132,25 +112,6 @@ function parseContentArgv(argv: string[]): { content: ContentType[]; rest: strin
   return { content: resolveContent(content), rest };
 }
 
-function parseTopK(argv: string[]): { topK: number; rest: string[] } {
-  const rest: string[] = [];
-  let topK = 5;
-  for (let i = 0; i < argv.length; i++) {
-    const arg = argv[i];
-    if (arg === "-k" || arg === "--top-k") {
-      const raw = argv[++i];
-      if (raw) {
-        topK = Number(raw);
-      }
-      continue;
-    }
-    if (arg !== undefined) {
-      rest.push(arg);
-    }
-  }
-  return { topK: Number.isFinite(topK) && topK >= 1 ? Math.floor(topK) : 5, rest };
-}
-
 function emitSearchOutput(
   query: string,
   results: SearchResult[],
@@ -177,7 +138,6 @@ function emitSearchOutput(
 async function runSearch(
   path: string,
   query: string,
-  topK: number,
   content: ContentType[],
   jsonFlag: boolean,
 ): Promise<void> {
@@ -186,7 +146,7 @@ async function runSearch(
   const index = await withSpinner("Indexing and searching", async () => {
     const built = await MiruIndex.fromSource(path, content);
     await built.saveToCache(path);
-    const results = await built.search({ query, topK });
+    const results = await built.search({ query, topK: SEARCH_RESULT_COUNT });
     return { index: built, results };
   });
 
@@ -245,7 +205,6 @@ async function runFindRelated(
   path: string,
   filePath: string,
   line: number,
-  topK: number,
   content: ContentType[],
   jsonFlag: boolean,
 ): Promise<void> {
@@ -257,7 +216,7 @@ async function runFindRelated(
     if (!chunk) {
       throw new RelatedChunkNotFoundError(filePath, line);
     }
-    const hits = await built.findRelated(chunk, topK);
+    const hits = await built.findRelated(chunk, SEARCH_RESULT_COUNT);
     await built.saveToCache(path);
     return {
       results: hits,
@@ -412,21 +371,11 @@ async function runBenchmarkCommand(rest: string[]): Promise<void> {
 async function runCli(argv: string[]): Promise<void> {
   const [command, ...rest] = argv;
 
-  if (command === undefined) {
+  if (command === undefined || command === "-h" || command === "--help") {
     printMainHelp();
     return;
   }
 
-  if (command === "-h" || command === "--help") {
-    printMainHelp();
-    return;
-  }
-
-  if (command === "-v" || command === "--version") {
-    console.log(miruVersion());
-    return;
-  }
-
   if (command === "help") {
     const topic = rest[0];
     if (!topic || topic === "-h" || topic === "--help") {
@@ -456,10 +405,6 @@ async function runCli(argv: string[]): Promise<void> {
     return;
   }
 
-  if (command === "hook-guard") {
-    process.exit(await runSearchGuardFromStdin());
-  }
-
   if (command === "install" || command === "uninstall") {
     await runInstaller(command);
     return;
@@ -552,21 +497,28 @@ async function runCli(argv: string[]): Promise<void> {
 
   const { present: jsonFlag, rest: jsonRest } = parseFlagArgv(rest, "--json");
   const { content, rest: contentRest } = parseContentArgv(jsonRest);
-  const { topK, rest: sizedRest } = parseTopK(contentRest);
+
+  if (
+    (command === "search" || command === "find-related") &&
+    contentRest.some((arg) => arg === "-k" || arg === "--top-k")
+  ) {
+    fail("The -k/--top-k option has been removed; Miru returns a fixed number of results.");
+    process.exit(1);
+  }
 
   if (command === "search") {
-    const query = sizedRest[0];
+    const query = contentRest[0];
     if (!query) {
       printCommandHelp("search");
       process.exit(1);
     }
-    const path = resolveSearchPath(sizedRest[1] ?? process.cwd());
-    await runSearch(path, query, topK, content, jsonFlag);
+    const path = resolveSearchPath(contentRest[1] ?? process.cwd());
+    await runSearch(path, query, content, jsonFlag);
     return;
   }
 
   if (command === "locate") {
-    const literal = sizedRest[0];
+    const literal = contentRest[0];
     if (!literal) {
       printCommandHelp("locate");
       process.exit(1);
@@ -585,10 +537,10 @@ async function runCli(argv: string[]): Promise<void> {
       }
       return Math.floor(n);
     };
-    for (let i = 1; i < sizedRest.length; i++) {
-      const arg = sizedRest[i];
-      if (arg === "--mode" && sizedRest[i + 1]) {
-        const value = sizedRest[++i];
+    for (let i = 1; i < contentRest.length; i++) {
+      const arg = contentRest[i];
+      if (arg === "--mode" && contentRest[i + 1]) {
+        const value = contentRest[++i];
         if (value !== "count" && value !== "locations" && value !== "lines") {
           fail(`Unknown locate mode "${value}". Use count, locations, or lines.`);
           process.exit(1);
@@ -596,8 +548,8 @@ async function runCli(argv: string[]): Promise<void> {
         options.mode = value as LiteralMode;
         continue;
       }
-      if (arg === "--limit" && sizedRest[i + 1]) {
-        options.limit = positiveInt("--limit", sizedRest[++i], 1);
+      if (arg === "--limit" && contentRest[i + 1]) {
+        options.limit = positiveInt("--limit", contentRest[++i], 1);
         continue;
       }
       if (arg === "--ignore-case") {
@@ -608,16 +560,16 @@ async function runCli(argv: string[]): Promise<void> {
         options.match_variants = true;
         continue;
       }
-      if (arg === "--include" && sizedRest[i + 1]) {
-        include.push(sizedRest[++i] as string);
+      if (arg === "--include" && contentRest[i + 1]) {
+        include.push(contentRest[++i] as string);
         continue;
       }
-      if (arg === "--exclude" && sizedRest[i + 1]) {
-        exclude.push(sizedRest[++i] as string);
+      if (arg === "--exclude" && contentRest[i + 1]) {
+        exclude.push(contentRest[++i] as string);
         continue;
       }
-      if (arg === "--context" && sizedRest[i + 1]) {
-        options.context_lines = positiveInt("--context", sizedRest[++i], 0);
+      if (arg === "--context" && contentRest[i + 1]) {
+        options.context_lines = positiveInt("--context", contentRest[++i], 0);
         continue;
       }
       if (arg !== undefined) {
@@ -636,22 +588,22 @@ async function runCli(argv: string[]): Promise<void> {
   }
 
   if (command === "expand") {
-    const filePath = sizedRest[0];
-    const lineRaw = sizedRest[1];
+    const filePath = contentRest[0];
+    const lineRaw = contentRest[1];
     if (!filePath || !lineRaw) {
       printCommandHelp("expand");
       process.exit(1);
     }
     const line = Number(lineRaw);
-    const path = resolveSearchPath(sizedRest[2] ?? process.cwd());
+    const path = resolveSearchPath(contentRest[2] ?? process.cwd());
     let before = DEFAULT_EXPAND_BEFORE;
     let after = DEFAULT_EXPAND_AFTER;
-    for (let i = 3; i < sizedRest.length; i++) {
-      const arg = sizedRest[i];
-      if (arg === "--before" && sizedRest[i + 1]) {
-        before = Number(sizedRest[++i]);
-      } else if (arg === "--after" && sizedRest[i + 1]) {
-        after = Number(sizedRest[++i]);
+    for (let i = 3; i < contentRest.length; i++) {
+      const arg = contentRest[i];
+      if (arg === "--before" && contentRest[i + 1]) {
+        before = Number(contentRest[++i]);
+      } else if (arg === "--after" && contentRest[i + 1]) {
+        after = Number(contentRest[++i]);
       }
     }
     await runExpand(path, filePath, line, before, after, content, jsonFlag);
@@ -659,15 +611,15 @@ async function runCli(argv: string[]): Promise<void> {
   }
 
   if (command === "find-related") {
-    const filePath = sizedRest[0];
-    const lineRaw = sizedRest[1];
+    const filePath = contentRest[0];
+    const lineRaw = contentRest[1];
     if (!filePath || !lineRaw) {
       printCommandHelp("find-related");
       process.exit(1);
     }
     const line = Number(lineRaw);
-    const path = resolveSearchPath(sizedRest[2] ?? process.cwd());
-    await runFindRelated(path, filePath, line, topK, content, jsonFlag);
+    const path = resolveSearchPath(contentRest[2] ?? process.cwd());
+    await runFindRelated(path, filePath, line, content, jsonFlag);
     return;
   }
 
@@ -687,6 +639,10 @@ async function runMcp(argv: string[]): Promise<void> {
       benchmark = true;
       continue;
     }
+    if (arg === "--benchmark=true" || arg === "--benchmark=false") {
+      benchmark = arg === "--benchmark=true";
+      continue;
+    }
     if (arg === "--ref" && argv[i + 1]) {
       ref = argv[++i] ?? null;
       continue;
@@ -734,24 +690,24 @@ async function main(): Promise<void> {
   const argv = process.argv.slice(2);
   const first = argv[0];
 
+  // Old hook configs may survive until the next install/uninstall; let their
+  // search commands proceed normally while the installer removes the hooks.
+  if (first === "hook-guard") return;
+
   if (first === "-v" || first === "--version") {
     console.log(miruVersion());
     return;
   }
 
-  if (first === "hook-guard") {
-    process.exit(await runSearchGuardFromStdin());
-  }
-
   const updateNotice = maybeNotifyUpdate();
 
-  if (first && CLI_COMMANDS.has(first)) {
-    await Promise.all([runCli(argv), updateNotice]);
+  if (shouldRunMcp(argv, Boolean(process.stdin.isTTY), Boolean(process.stdout.isTTY))) {
+    await updateNotice;
+    await runMcpWithCredentials(first === "mcp" ? argv.slice(1) : argv);
     return;
   }
 
-  await updateNotice;
-  await runMcpWithCredentials(argv);
+  await Promise.all([runCli(argv), updateNotice]);
 }
 
 main().catch((err) => {

package/src/credentials.ts

@@ -20,17 +20,22 @@ export function setStoredCredentialsEnvToken(token: string): void {
   process.env.TAKARA_API_KEY = token;
 }
 
-export function resolveCredentialsDir(): string {
+/** True for an unresolved `${...}` placeholder — a plugin host that didn't substitute it. */
+function isUnsubstitutedPlaceholder(value: string): boolean {
+  return value.startsWith("${") && value.endsWith("}");
+}
+
+export function resolveCredentialsDir(platform: NodeJS.Platform = process.platform): string {
   const override = process.env.MIRU_CREDENTIALS_DIR;
-  if (override) {
+  if (override && !isUnsubstitutedPlaceholder(override)) {
     return override;
   }
   const home = process.env.HOME ?? process.env.USERPROFILE ?? "";
-  if (process.platform === "win32") {
+  if (platform === "win32") {
     const base = process.env.APPDATA ?? join(home, "AppData", "Roaming");
     return join(base, "miru");
   }
-  if (process.platform === "darwin") {
+  if (platform === "darwin") {
     return join(home, "Library", "Application Support", "miru");
   }
   const xdg = process.env.XDG_CONFIG_HOME ?? join(home, ".config");
@@ -41,12 +46,12 @@ export function resolveCredentialsDir(): string {
  * Global Miru state directory (credentials, benchmark history, etc.).
  * Same location as `resolveCredentialsDir()`; prefer this name for non-secret files.
  */
-export function resolveMiruStateDir(): string {
-  return resolveCredentialsDir();
+export function resolveMiruStateDir(platform: NodeJS.Platform = process.platform): string {
+  return resolveCredentialsDir(platform);
 }
 
-export function resolveCredentialsPath(): string {
-  return join(resolveCredentialsDir(), CREDENTIALS_FILENAME);
+export function resolveCredentialsPath(platform: NodeJS.Platform = process.platform): string {
+  return join(resolveCredentialsDir(platform), CREDENTIALS_FILENAME);
 }
 
 export async function readStoredCredentials(): Promise<StoredCredentials | null> {
@@ -262,12 +267,7 @@ export async function clearStoredCredentials(): Promise<{ cleared: boolean; path
   }
 
   // Read for env cleanup, but never let parse errors block deletion.
-  let stored: StoredCredentials | null = null;
-  try {
-    stored = await readStoredCredentials();
-  } catch {
-    // Ignore parse/read errors — removal still proceeds.
-  }
+  const stored = await readStoredCredentials();
   await rm(path, { force: true });
 
   if (stored) {

package/src/embeddings/openai.ts

@@ -353,7 +353,9 @@ export class EmbeddingApiError extends Error {
   }
 }
 
-function createClient(): EmbeddingClient {
+type EmbeddingFetch = (input: string | URL | Request, init?: RequestInit) => Promise<Response>;
+
+function createClient(fetchImpl: EmbeddingFetch = fetch): EmbeddingClient {
   const baseUrl = resolveEmbeddingBaseUrl();
   const endpoint = `${baseUrl}/embeddings`;
 
@@ -369,7 +371,7 @@ function createClient(): EmbeddingClient {
       if (dimensions != null) {
         body.dimensions = dimensions;
       }
-      const response = await fetch(endpoint, {
+      const response = await fetchImpl(endpoint, {
         method: "POST",
         headers: {
           Authorization: `Bearer ${apiKey}`,
@@ -407,9 +409,10 @@ export class OpenAIEmbeddingBackend implements EmbeddingBackend {
     maxEmbedChars?: number;
     dimensions?: number;
     client?: EmbeddingClient;
+    fetchImpl?: EmbeddingFetch;
   }) {
     this.model = options?.model ?? resolveEmbeddingModel();
-    this.client = options?.client ?? createClient();
+    this.client = options?.client ?? createClient(options?.fetchImpl);
     this.batchSize = options?.batchSize ?? resolveEmbeddingBatchSize();
     this.maxEmbedChars = options?.maxEmbedChars ?? resolveMaxEmbedChars();
     this.requestedDimensions = options?.dimensions ?? resolveEmbeddingDimensions(this.model);

package/src/embeddings/sagemaker.ts

@@ -26,6 +26,11 @@ function loadAwsCredentialProvider(): Promise<AwsCredentialProviderModule> {
   return awsCredentialProviderPromise;
 }
 
+/** Warm the lazily loaded AWS SDK modules before the first SageMaker request. */
+export async function preloadSageMakerSdk(): Promise<void> {
+  await Promise.all([loadSageMakerRuntime(), loadAwsCredentialProvider()]);
+}
+
 /** arn:aws:sagemaker:<region>:<account-id>:endpoint/<endpoint-name> (also covers aws-cn/aws-us-gov). */
 const ENDPOINT_ARN_PATTERN = /^arn:aws[a-z0-9-]*:sagemaker:([a-z0-9-]+):(\d{12}):endpoint\/(.+)$/;
 
@@ -344,7 +349,13 @@ function buildRequestBody(
   return body;
 }
 
-export function createSageMakerClient(config: SageMakerEmbeddingConfig): EmbeddingClient {
+export function createSageMakerClient(
+  config: SageMakerEmbeddingConfig,
+  loaders: {
+    loadRuntime?: () => Promise<SageMakerRuntimeModule>;
+    loadCredentials?: () => Promise<AwsCredentialProviderModule>;
+  } = {},
+): EmbeddingClient {
   let client: InstanceType<SageMakerRuntimeModule["SageMakerRuntimeClient"]> | null = null;
 
   return {
@@ -354,7 +365,10 @@ export function createSageMakerClient(config: SageMakerEmbeddingConfig): Embeddi
       dimensions?: number,
     ): Promise<EmbeddingResponse> {
       const [{ InvokeEndpointCommand, SageMakerRuntimeClient }, { defaultProvider }] =
-        await Promise.all([loadSageMakerRuntime(), loadAwsCredentialProvider()]);
+        await Promise.all([
+          (loaders.loadRuntime ?? loadSageMakerRuntime)(),
+          (loaders.loadCredentials ?? loadAwsCredentialProvider)(),
+        ]);
       if (!client) {
         const profile = config.profile?.trim() || process.env.AWS_PROFILE?.trim();
         const sdkCredentials = defaultProvider({ profile });
@@ -414,9 +428,10 @@ export interface ValidateSageMakerResult {
 /** Real InvokeEndpoint round trip, used by `miru setup --sagemaker` to confirm auth + shape. */
 export async function validateSageMakerConnection(
   config: SageMakerEmbeddingConfig,
+  createClient: typeof createSageMakerClient = createSageMakerClient,
 ): Promise<ValidateSageMakerResult> {
   try {
-    const client = createSageMakerClient(config);
+    const client = createClient(config);
     const response = await client.createEmbeddings("miru setup validation", "sagemaker-setup");
     const embedding = response.data[0]?.embedding;
     if (!embedding) {

package/src/embeddings/validate.ts

@@ -12,12 +12,15 @@ export interface ValidateApiKeyResult {
   message: string;
 }
 
-export async function validateEmbeddingApiKey(options: {
-  apiKey: string;
-  baseUrl?: string;
-  model?: string;
-  dimensions?: number;
-}): Promise<ValidateApiKeyResult> {
+export async function validateEmbeddingApiKey(
+  options: {
+    apiKey: string;
+    baseUrl?: string;
+    model?: string;
+    dimensions?: number;
+  },
+  fetchImpl: (input: string | URL | Request, init?: RequestInit) => Promise<Response> = fetch,
+): Promise<ValidateApiKeyResult> {
   const baseUrl = (options.baseUrl ?? resolveEmbeddingBaseUrl()).replace(/\/$/, "");
   const model = options.model ?? resolveTakaraEmbeddingModel();
   const dimensions = options.dimensions ?? resolveEmbeddingDimensions(model);
@@ -33,7 +36,7 @@ export async function validateEmbeddingApiKey(options: {
 
   let response: Response;
   try {
-    response = await fetch(endpoint, {
+    response = await fetchImpl(endpoint, {
       method: "POST",
       headers: {
         Authorization: `Bearer ${options.apiKey}`,

package/src/git.ts

@@ -5,7 +5,11 @@ import { envOptionalInt } from "./env.ts";
 
 const DEFAULT_CLONE_TIMEOUT_SEC = 60;
 
-export async function cloneGitRepository(url: string, ref?: string | null): Promise<string> {
+export async function cloneGitRepository(
+  url: string,
+  ref?: string | null,
+  spawn: typeof Bun.spawn = Bun.spawn,
+): Promise<string> {
   const timeoutSec = envOptionalInt(["MIRU_CLONE_TIMEOUT"], 1) ?? DEFAULT_CLONE_TIMEOUT_SEC;
   const dir = await mkdtemp(join(tmpdir(), "miru-git-"));
   const args = ["clone", "--depth", "1"];
@@ -16,7 +20,7 @@ export async function cloneGitRepository(url: string, ref?: string | null): Prom
 
   let proc: ReturnType<typeof Bun.spawn>;
   try {
-    proc = Bun.spawn(["git", ...args], {
+    proc = spawn(["git", ...args], {
       stdout: "pipe",
       stderr: "pipe",
       stdin: "ignore",

package/src/help.ts

@@ -28,7 +28,7 @@ export function printMainHelp(): void {
   header();
 
   section("Usage");
-  writeStdout("  miru                         Start MCP server (stdio)");
+  writeStdout("  miru                         Show help in a terminal");
   writeStdout("  miru <command> [options]");
   divider();
 
@@ -37,6 +37,7 @@ export function printMainHelp(): void {
   commandRow("locate", "Exact substring location in the index");
   commandRow("expand", "Adjacent chunks in the same file as a hit");
   commandRow("find-related", "Find chunks related to a file:line");
+  commandRow("mcp", "Start MCP server (stdio)");
   commandRow("setup", "Authenticate with Takara");
   commandRow("install", "Configure miru across coding agents");
   commandRow("uninstall", "Remove miru agent configuration");
@@ -108,11 +109,10 @@ export function printCommandHelp(command: string): void {
       section("Usage");
       writeStdout("  miru search <query> [path] [options]");
       section("Options");
-      writeStdout("  -k, --top-k N       Number of results (default: 5)");
       writeStdout("  --content TYPE      code | docs | config | all (default: code config)");
       writeStdout("  --json              JSON output (default when piped)");
       section("Example");
-      writeStdout('  miru search "where is auth" ./src -k 10 --content code docs');
+      writeStdout('  miru search "where is auth" ./src --content code docs');
       writeStdout("");
       return;
     case "locate":
@@ -149,7 +149,7 @@ export function printCommandHelp(command: string): void {
       section("Usage");
       writeStdout("  miru find-related <file> <line> [path] [options]");
       section("Example");
-      writeStdout("  miru find-related src/auth.ts 42 . -k 8");
+      writeStdout("  miru find-related src/auth.ts 42 .");
       writeStdout("");
       return;
     case "setup":
@@ -178,7 +178,7 @@ export function printCommandHelp(command: string): void {
     case "install":
       commandHeader("install", "Interactive global agent setup.");
       writeStdout("Configures MCP server, instructions, sub-agent files, and optional");
-      writeStdout("experimental integrations (search hooks, Caveman, STE writing) under");
+      writeStdout("experimental integrations (Caveman, STE writing) under");
       writeStdout("your user config (~/.claude, ~/.cursor, etc.).");
       writeStdout("");
       writeStdout(
@@ -244,9 +244,9 @@ export function printCommandHelp(command: string): void {
       writeStdout("");
       return;
     case "mcp":
-      commandHeader("mcp", "Stdio MCP server (default with no subcommand).");
+      commandHeader("mcp", "Stdio MCP server.");
       section("Usage");
-      writeStdout("  miru [--ref BRANCH] [--content TYPE ...] [--benchmark]");
+      writeStdout("  miru mcp [--ref BRANCH] [--content TYPE ...] [--benchmark]");
       writeStdout("  Default content: code config");
       writeStdout("");
       writeStdout("Indexes on the first search/expand/find_related tool call (repo argument).");

package/src/index/bm25.ts

@@ -42,12 +42,21 @@ function runScoreWorker(job: Bm25ScoreJob): Promise<Bm25ScoreResult> {
 }
 
 export class BM25Index {
-  private docFreq = new Map<string, number>();
-  private docLengths: number[] = [];
-  private postings = new Map<string, PostingsList>();
-  private avgDocLength = 0;
-  private numDocs = 0;
-  private totalLen = 0;
+  private docFreq: Map<string, number>;
+  private docLengths: number[];
+  private postings: Map<string, PostingsList>;
+  private avgDocLength: number;
+  private numDocs: number;
+  private totalLen: number;
+
+  constructor() {
+    this.docFreq = new Map();
+    this.docLengths = [];
+    this.postings = new Map();
+    this.avgDocLength = 0;
+    this.numDocs = 0;
+    this.totalLen = 0;
+  }
 
   /** Append one tokenized document. Safe to call incrementally while indexing. */
   addDocument(doc: string[]): number {
@@ -73,6 +82,57 @@ export class BM25Index {
     return docIndex;
   }
 
+  get size(): number {
+    return this.numDocs;
+  }
+
+  /**
+   * A new index with the given documents removed and later doc indices shifted down,
+   * equal to re-indexing the surviving docs in order. `this` is left untouched, so
+   * searches already holding it never see a half-updated index.
+   */
+  withoutDocuments(removed: ReadonlySet<number>): BM25Index {
+    const next = new BM25Index();
+    const remap = new Int32Array(this.numDocs);
+    let kept = 0;
+    let firstRemoved = this.numDocs;
+    for (let doc = 0; doc < this.numDocs; doc++) {
+      if (removed.has(doc)) {
+        remap[doc] = -1;
+        if (firstRemoved === this.numDocs) {
+          firstRemoved = doc;
+        }
+      } else {
+        remap[doc] = kept++;
+        const length = this.docLengths[doc] ?? 0;
+        next.docLengths.push(length);
+        next.totalLen += length;
+      }
+    }
+    next.numDocs = kept;
+    next.avgDocLength = kept === 0 ? 0 : next.totalLen / kept;
+
+    for (const [term, list] of this.postings) {
+      // Lists ascend by doc index, so one ending before the first removal is untouched.
+      // Copy the array (addDocument appends to it) but share the immutable tuples.
+      const untouched = (list.at(-1)?.[0] ?? 0) < firstRemoved;
+      const nextList: PostingsList = untouched ? list.slice() : [];
+      if (!untouched) {
+        for (const entry of list) {
+          const mapped = remap[entry[0]] ?? -1;
+          if (mapped !== -1) {
+            nextList.push(mapped === entry[0] ? entry : [mapped, entry[1]]);
+          }
+        }
+      }
+      if (nextList.length > 0) {
+        next.postings.set(term, nextList);
+        next.docFreq.set(term, nextList.length);
+      }
+    }
+    return next;
+  }
+
   index(tokenizedDocs: string[][]): void {
     this.numDocs = 0;
     this.docFreq.clear();