@tikoci/rosetta 0.8.9 → 0.8.10

package/src/query.ts

@@ -5,9 +5,22 @@
  * no author/date/engagement signals — just text search with BM25 ranking.
  */
 
+import { type CanonicalCommand, canonicalize } from "./canonicalize.ts";
+import { makeDbVerbResolver } from "./canonicalize-resolver.ts";
 import { classifyQuery, type QueryClassification } from "./classify.ts";
 import { db } from "./db.ts";
 
+/**
+ * Lazy DB-backed verb resolver for the classifier. Built on first use so
+ * tests that import query.ts but never call searchAll don't pay the cost,
+ * and it inherits the same `db` singleton everything else uses.
+ */
+let _verbResolver: ReturnType<typeof makeDbVerbResolver> | null = null;
+function getVerbResolver() {
+  if (!_verbResolver) _verbResolver = makeDbVerbResolver(db);
+  return _verbResolver;
+}
+
 export type SearchResult = {
   id: number;
   title: string;
@@ -43,6 +56,18 @@ const STOP_WORDS = new Set([
   "what", "when", "where", "which", "why", "with", "without",
 ]);
 
+const CHANGELOG_GENERIC_TERMS = new Set([
+  "change",
+  "changed",
+  "changes",
+  "changelog",
+  "changelogs",
+  "new",
+  "release",
+  "released",
+  "version",
+]);
+
 const COMPOUND_TERMS: [string, string][] = [
   ["firewall", "filter"],
   ["firewall", "mangle"],
@@ -94,6 +119,13 @@ const COMPOUND_TERMS: [string, string][] = [
 // from here for backward compatibility. See classify.ts for the canonical definition.
 export { KNOWN_TOPICS } from "./classify.ts";
 
+function applyContextualTermFilters(terms: string[]): string[] {
+  if (terms.includes("bridge") && terms.includes("vlan") && terms.includes("filtering")) {
+    return terms.filter((term) => term !== "switch");
+  }
+  return terms;
+}
+
 function getSpecialSearchHint(question: string): string | undefined {
   const normalized = question.toLowerCase();
   if (/(?:^|\b)(?:the\s+)?dude(?:\b|$)/.test(normalized)) {
@@ -118,12 +150,13 @@ function rowsToCsv<T extends Record<string, CsvScalar>>(
 }
 
 export function extractTerms(question: string): string[] {
-  return question
+  const terms = question
     .toLowerCase()
     .replace(/[^\w\s-]/g, " ")
     .split(/\s+/)
     .filter((t) => t.length >= MIN_TERM_LENGTH && !STOP_WORDS.has(t))
     .slice(0, MAX_TERMS);
+  return applyContextualTermFilters(terms);
 }
 
 export function buildFtsQuery(terms: string[], mode: "AND" | "OR"): string {
@@ -203,6 +236,7 @@ type RelatedProperty = {
   page_title: string;
   page_url: string;
   page_id: number;
+  confidence: PropertyLookupConfidence;
 };
 
 type RelatedDevice = {
@@ -273,7 +307,7 @@ function relatedCaps(limit: number): { cap: number; videoCap: number } {
 }
 
 export function searchAll(query: string, limit = DEFAULT_LIMIT): SearchAllResponse {
-  const classified = classifyQuery(query);
+  const classified = classifyQuery(query, { isVerb: getVerbResolver() });
   const pagesResp = searchPages(query, limit);
   const { cap: RELATED_CAP, videoCap: RELATED_VIDEO_CAP } = relatedCaps(limit);
 
@@ -330,6 +364,7 @@ export function searchAll(query: string, limit = DEFAULT_LIMIT): SearchAllRespon
         page_title: p.page_title,
         page_url: p.page_url,
         page_id: p.page_id,
+        confidence: p.confidence,
       }));
     }
   }
@@ -500,6 +535,177 @@ function buildSearchAllNote(
   return notes.length > 0 ? notes.join(" ") : undefined;
 }
 
+type ExplainCommandConfidence = CanonicalCommand["confidence"] | "none";
+
+type ExplainCommandCanonical = {
+  path: string;
+  verb: string;
+  args: string[];
+  confidence: CanonicalCommand["confidence"];
+};
+
+type ExplainCommandArg = {
+  raw: string;
+  name: string;
+  value: string;
+  property?: {
+    name: string;
+    type: string | null;
+    default_val: string | null;
+    description: string;
+    page_title: string;
+    page_url: string;
+    page_id: number;
+    confidence: PropertyLookupConfidence;
+  };
+};
+
+type ExplainCommandWarning = {
+  kind: "no-command" | "low-confidence" | "unknown-arg" | "command-not-in-version" | "model-context-unused";
+  message: string;
+  arg?: string;
+  suggestion?: string;
+};
+
+export type ExplainCommandResult = {
+  command: string;
+  canonical: ExplainCommandCanonical | null;
+  confidence: ExplainCommandConfidence;
+  args: ExplainCommandArg[];
+  warnings: ExplainCommandWarning[];
+  pages: SearchResult[];
+  changelog_hits: ChangelogResult[];
+  version_check?: ReturnType<typeof checkCommandVersions>;
+};
+
+function parseKeyValueArg(raw: string): { name: string; value: string } | null {
+  const eq = raw.indexOf("=");
+  if (eq <= 0) return null;
+  return {
+    name: raw.slice(0, eq),
+    value: raw.slice(eq + 1),
+  };
+}
+
+function explainCommandSearchText(command: string, canonical: ExplainCommandCanonical | null, args: ExplainCommandArg[]): string {
+  if (!canonical) return command;
+  const argNames = args.map((arg) => arg.name).join(" ");
+  return `${canonical.path} ${canonical.verb} ${argNames}`.trim();
+}
+
+/**
+ * Explain a candidate RouterOS CLI command using only the local rosetta DB.
+ *
+ * This is read-only: it canonicalizes the command, annotates key=value args
+ * with documentation-property matches, checks version presence, and surfaces
+ * compact docs/changelog context. It never connects to or modifies a router.
+ */
+export function explainCommand(command: string, rosVersion?: string, model?: string): ExplainCommandResult {
+  const parsed = canonicalize(command, "/", { isVerb: getVerbResolver() });
+  const primary = parsed.commands.find((cmd) => !cmd.subshell) ?? parsed.commands[0] ?? null;
+  const warnings: ExplainCommandWarning[] = [];
+
+  if (!primary?.verb) {
+    warnings.push({
+      kind: "no-command",
+      message: "No primary RouterOS command verb could be extracted from the input.",
+      suggestion: "Pass a full CLI command such as '/ip/firewall/filter add chain=forward action=drop'.",
+    });
+  }
+
+  const canonical = primary
+    ? {
+      path: primary.path,
+      verb: primary.verb,
+      args: primary.args,
+      confidence: primary.confidence,
+    }
+    : null;
+  const confidence: ExplainCommandConfidence = canonical?.confidence ?? "none";
+
+  if (confidence === "low") {
+    warnings.push({
+      kind: "low-confidence",
+      message: "The command path/verb was inferred from a loose or prose-shaped input.",
+      suggestion: "Use a full absolute RouterOS CLI form such as '/ip/firewall/filter add ...'.",
+    });
+  }
+
+  if (model) {
+    warnings.push({
+      kind: "model-context-unused",
+      message: `Model context "${model}" was accepted but device-specific command validation is not implemented yet.`,
+      suggestion: "Use routeros_device_lookup separately for hardware specs; this tool stays read-only and documentation-backed.",
+    });
+  }
+
+  const args: ExplainCommandArg[] = [];
+  if (canonical) {
+    for (const raw of canonical.args) {
+      const parsedArg = parseKeyValueArg(raw);
+      if (!parsedArg) continue;
+      const match = lookupProperty(parsedArg.name, canonical.path)[0];
+      const explainedArg: ExplainCommandArg = {
+        raw,
+        name: parsedArg.name,
+        value: parsedArg.value,
+      };
+      if (match) {
+        explainedArg.property = {
+          name: match.name,
+          type: match.type,
+          default_val: match.default_val,
+          description: match.description,
+          page_title: match.page_title,
+          page_url: match.page_url,
+          page_id: match.page_id,
+          confidence: match.confidence,
+        };
+      } else {
+        warnings.push({
+          kind: "unknown-arg",
+          arg: parsedArg.name,
+          message: `No documented property named "${parsedArg.name}" was found for ${canonical.path}.`,
+          suggestion: `Use routeros_command_tree path="${canonical.path}" or routeros_get_page for the linked documentation to confirm available arguments.`,
+        });
+      }
+      args.push(explainedArg);
+    }
+  }
+
+  let version_check: ReturnType<typeof checkCommandVersions> | undefined;
+  if (canonical) {
+    version_check = checkCommandVersions(canonical.path);
+    if (rosVersion && !version_check.versions.includes(rosVersion)) {
+      warnings.push({
+        kind: "command-not-in-version",
+        message: `${canonical.path} is not present in tracked command data for RouterOS ${rosVersion}.`,
+        suggestion: version_check.versions.length > 0
+          ? `Tracked range for this path: ${version_check.first_seen}–${version_check.last_seen}. Use routeros_command_diff for upgrade changes.`
+          : "Use routeros_command_tree/routeros_search to confirm the path, or check routeros_stats for tracked version coverage.",
+      });
+    }
+  }
+
+  const contextQuery = explainCommandSearchText(command, canonical, args);
+  const pages = searchPages(contextQuery || command, 3).results;
+  const changelog_hits = searchChangelogs(contextQuery || command, {
+    ...(rosVersion ? { version: rosVersion } : {}),
+    limit: 3,
+  });
+
+  return {
+    command,
+    canonical,
+    confidence,
+    args,
+    warnings,
+    pages,
+    changelog_hits,
+    ...(version_check ? { version_check } : {}),
+  };
+}
+
 function runFtsQuery(ftsQuery: string, limit: number): SearchResult[] {
   if (!ftsQuery) return [];
   try {
@@ -804,11 +1010,9 @@ function getPageToc(pageId: number, pageUrl: string): SectionTocEntry[] {
   }));
 }
 
-/** Lookup property by name, optionally filtered by command path. */
-export function lookupProperty(
-  name: string,
-  commandPath?: string,
-): Array<{
+export type PropertyLookupConfidence = "high" | "medium" | "low";
+
+export type PropertyLookupRow = {
   name: string;
   type: string | null;
   default_val: string | null;
@@ -817,7 +1021,13 @@ export function lookupProperty(
   page_title: string;
   page_url: string;
   page_id: number;
-}> {
+  confidence: PropertyLookupConfidence;
+};
+
+type PropertyLookupRowWithoutConfidence = Omit<PropertyLookupRow, "confidence">;
+
+/** Lookup property by name, optionally filtered by command path. */
+export function lookupProperty(name: string, commandPath?: string): PropertyLookupRow[] {
   if (commandPath) {
     // Find the page linked to this command path, then search properties there
     const linked = db
@@ -828,7 +1038,7 @@ export function lookupProperty(
       .get(commandPath) as { page_id: number } | null;
 
     if (linked) {
-      return db
+      const scopedRows = db
         .prepare(
           `SELECT p.name, p.type, p.default_val, p.description, p.section,
                   pg.title as page_title, pg.url as page_url, pg.id as page_id
@@ -837,12 +1047,15 @@ export function lookupProperty(
            WHERE p.page_id = ? AND p.name = ? COLLATE NOCASE
            ORDER BY p.sort_order`,
         )
-        .all(linked.page_id, name) as typeof lookupProperty extends (...a: unknown[]) => infer R ? R : never;
+        .all(linked.page_id, name) as PropertyLookupRowWithoutConfidence[];
+      if (scopedRows.length > 0) {
+        return scopedRows.map((row) => ({ ...row, confidence: "high" }));
+      }
     }
   }
 
   // Fallback: search by property name across all pages
-  return db
+  const globalRows = db
     .prepare(
       `SELECT p.name, p.type, p.default_val, p.description, p.section,
               pg.title as page_title, pg.url as page_url, pg.id as page_id
@@ -851,7 +1064,9 @@ export function lookupProperty(
        WHERE p.name = ? COLLATE NOCASE
        ORDER BY pg.title, p.sort_order`,
     )
-    .all(name) as typeof lookupProperty extends (...a: unknown[]) => infer R ? R : never;
+    .all(name) as PropertyLookupRowWithoutConfidence[];
+  const confidence: PropertyLookupConfidence = commandPath ? "low" : "medium";
+  return globalRows.map((row) => ({ ...row, confidence }));
 }
 
 /** Parse _attrs JSON and extract completion, stripping _attrs from output. */
@@ -1931,6 +2146,29 @@ function filterVersionRange(
   });
 }
 
+function isMajorMinorVersion(version: string): boolean {
+  return /^\d+\.\d+$/.test(version);
+}
+
+function resolveChangelogVersionList(version: string): string[] {
+  const all = getChangelogVersions();
+  if (all.includes(version)) return [version];
+  if (isMajorMinorVersion(version)) {
+    const patchPrefix = `${version}.`;
+    const patchVersions = all.filter((v) => v.startsWith(patchPrefix));
+    if (patchVersions.length > 0) return patchVersions;
+  }
+  return [version];
+}
+
+function extractChangelogTerms(query: string, version?: string): string[] {
+  const terms = extractTerms(query);
+  if (!version) return terms;
+
+  const versionParts = new Set(version.match(/\d+/g) ?? []);
+  return terms.filter((term) => !CHANGELOG_GENERIC_TERMS.has(term) && !versionParts.has(term));
+}
+
 /** Search changelogs with FTS, version range, category, and breaking-only filters. */
 export function searchChangelogs(
   query: string,
@@ -1946,12 +2184,12 @@ export function searchChangelogs(
   } = {},
 ): ChangelogResult[] {
   const limit = options.limit ?? 20;
-  const terms = extractTerms(query);
+  const terms = extractChangelogTerms(query, options.version);
 
   // Build version filter
   let versionList: string[] | null = null;
   if (options.version) {
-    versionList = [options.version];
+    versionList = resolveChangelogVersionList(options.version);
   } else if (options.fromVersion || options.toVersion) {
     const all = getChangelogVersions();
     versionList = filterVersionRange(all, options.fromVersion, options.toVersion, options.inclusiveFrom);

package/src/release.test.ts

@@ -15,6 +15,12 @@ function readText(relPath: string): string {
   return readFileSync(path.join(ROOT, relPath), "utf-8");
 }
 
+function mustIndex(haystack: string, needle: string): number {
+  const idx = haystack.indexOf(needle);
+  expect(idx).toBeGreaterThanOrEqual(0);
+  return idx;
+}
+
 // ---------------------------------------------------------------------------
 // package.json health
 // ---------------------------------------------------------------------------
@@ -196,11 +202,24 @@ describe("setup.ts", () => {
     expect(mcp).toContain("refreshDb");
   });
 
+  test("serializes package DB preparation with a sidecar lock", () => {
+    const src = readText("src/setup.ts");
+    expect(src).toContain(".lock");
+    expect(src).toContain("tryAcquireDownloadLock");
+    expect(src).toContain("waitForUsableDb");
+  });
+
   test("mcp.ts fails hard on persistent schema mismatch (no silent fall-through)", () => {
     const src = readText("src/mcp.ts");
     // Must call process.exit on the unrecoverable schema-mismatch path
     expect(src).toContain("Still incompatible after re-download");
-    expect(src).toMatch(/Still incompatible[\s\S]{0,400}process\.exit\(1\)/);
+    expect(src).toMatch(/Still incompatible[\s\S]{0,500}(throw new Error|process\.exit\(1\))/);
+  });
+
+  test("mcp.ts aborts startup instead of continuing with an empty DB", () => {
+    const src = readText("src/mcp.ts");
+    expect(src).toContain("Unable to start rosetta without a usable database");
+    expect(src).toContain("Database remained empty after recovery");
   });
 
   test("no DB open uses { readonly: true } (WAL-shm init trap on macOS)", () => {
@@ -299,6 +318,18 @@ describe("Makefile", () => {
     expect(phonyBlock).toContain("extract-skills");
   });
 
+  test("has gc-versions target with EXTRA_FLAGS passthrough", () => {
+    expect(makefile).toContain("gc-versions:");
+    expect(makefile).toContain("src/gc-versions.ts $(EXTRA_FLAGS)");
+  });
+
+  test("gc-versions is in PHONY", () => {
+    const phonyStart = makefile.indexOf(".PHONY:");
+    const phonyEnd = makefile.indexOf("\n\n", phonyStart);
+    const phonyBlock = makefile.slice(phonyStart, phonyEnd);
+    expect(phonyBlock).toContain("gc-versions");
+  });
+
   test("extract-dude is in PHONY", () => {
     const phonyStart = makefile.indexOf(".PHONY:");
     const phonyEnd = makefile.indexOf("\n\n", phonyStart);
@@ -356,6 +387,8 @@ describe("release.yml", () => {
     const src = readText(".github/workflows/release.yml");
     expect(src).toContain("html_url:");
     expect(src).toContain("version:");
+    expect(src).toContain("republish_assets:");
+    expect(src).not.toContain("inputs.force");
   });
 
   test("tolerates Confluence zip with absolute path root entry", () => {
@@ -394,6 +427,44 @@ describe("release.yml", () => {
     expect(src).toContain("bun run lint");
   });
 
+  test("runs early quality gate before downloading HTML export", () => {
+    const src = readText(".github/workflows/release.yml");
+    const installIdx = mustIndex(src, "bun install");
+    const typecheckIdx = mustIndex(src, "Type check (fast-fail)");
+    const lintIdx = mustIndex(src, "Lint (fast-fail)");
+    const earlyTestIdx = mustIndex(src, "Run tests (fast-fail)");
+    const downloadIdx = mustIndex(src, "Download HTML export");
+
+    expect(installIdx).toBeLessThan(typecheckIdx);
+    expect(typecheckIdx).toBeLessThan(lintIdx);
+    expect(lintIdx).toBeLessThan(earlyTestIdx);
+    expect(earlyTestIdx).toBeLessThan(downloadIdx);
+  });
+
+  test("keeps post-extraction DB-wipe guard after extraction", () => {
+    const src = readText(".github/workflows/release.yml");
+    const linkIdx = mustIndex(src, "Link commands to pages");
+    const guardIdx = mustIndex(src, "Run tests (DB-wipe guard)");
+    const buildIdx = mustIndex(src, "Build release artifacts");
+
+    expect(guardIdx).toBeGreaterThan(linkIdx);
+    expect(guardIdx).toBeLessThan(buildIdx);
+    expect(src.slice(guardIdx, buildIdx)).toContain("bun test");
+  });
+
+  test("runs schema_node_presence GC after link and before stats/build", () => {
+    const src = readText(".github/workflows/release.yml");
+    const linkIdx = mustIndex(src, "Link commands to pages");
+    const gcIdx = mustIndex(src, "GC schema node presence versions");
+    const statsIdx = mustIndex(src, "Collect DB stats");
+    const buildIdx = mustIndex(src, "Build release artifacts");
+
+    expect(gcIdx).toBeGreaterThan(linkIdx);
+    expect(gcIdx).toBeLessThan(statsIdx);
+    expect(gcIdx).toBeLessThan(buildIdx);
+    expect(src.slice(gcIdx, statsIdx)).toContain("make gc-versions EXTRA_FLAGS=--verbose");
+  });
+
   test("runs MCP contract tests against the real built DB before eval/release", () => {
     const src = readText(".github/workflows/release.yml");
     const contractIdx = src.indexOf("bun test src/mcp-contract.test.ts");
@@ -409,6 +480,50 @@ describe("release.yml", () => {
     expect(src).toContain("gh release create");
   });
 
+  test("republish_assets controls immutable npm skips and release clobbering", () => {
+    const src = readText(".github/workflows/release.yml");
+    expect(src).toContain("republish_assets:");
+    expect(src).toContain("Does NOT re-publish npm");
+    expect(src).not.toContain("inputs.force");
+    expect(src).not.toContain("force=true");
+
+    const republishBranchIdx = src.search(
+      /if \[ "\$\{\{ inputs\.republish_assets \}\}" = "true" \]; then/,
+    );
+    expect(republishBranchIdx).toBeGreaterThanOrEqual(0);
+    const clobberIdx = mustIndex(src, "gh release upload");
+    expect(src.slice(clobberIdx, clobberIdx + 120)).toContain("--clobber");
+    expect(republishBranchIdx).toBeLessThan(clobberIdx);
+
+    expect(src).toContain("if: inputs.republish_assets != true");
+    expect(src).toContain("if: inputs.republish_assets == true");
+    expect(src).toMatch(
+      /Publish to npm[\s\S]{0,120}if: inputs\.republish_assets != true/,
+    );
+    expect(src).toMatch(
+      /bunx-smoke:[\s\S]{0,120}if: inputs\.republish_assets != true/,
+    );
+    expect(src).toMatch(
+      /bump-version:[\s\S]{0,120}if: inputs\.republish_assets != true/,
+    );
+  });
+
+  test("bump-version fetches and rebases before retrying push", () => {
+    const src = readText(".github/workflows/release.yml");
+    const bumpIdx = mustIndex(src, "bump-version:");
+    const bumpBlock = src.slice(bumpIdx);
+    const loopIdx = mustIndex(bumpBlock, "for attempt in 1 2 3; do");
+    const fetchIdx = mustIndex(bumpBlock, "git fetch origin main");
+    const rebaseIdx = mustIndex(bumpBlock, "git rebase origin/main");
+    const pushIdx = mustIndex(bumpBlock, "git push origin HEAD:main");
+    const retryIdx = mustIndex(bumpBlock, "Push rejected on attempt");
+
+    expect(loopIdx).toBeLessThan(fetchIdx);
+    expect(fetchIdx).toBeLessThan(rebaseIdx);
+    expect(rebaseIdx).toBeLessThan(pushIdx);
+    expect(pushIdx).toBeLessThan(retryIdx);
+  });
+
   test("publishes to npm", () => {
     const src = readText(".github/workflows/release.yml");
     expect(src).toContain("npm publish");
@@ -463,6 +578,11 @@ describe("CLI flags", () => {
     expect(src).toContain('if (args[0] === "browse")');
     expect(src).toContain("await ensureDbReady");
   });
+
+  test("top-level CLI bootstrap has a catch that exits non-zero on startup errors", () => {
+    expect(src).toContain("})().catch((err) => {");
+    expect(src).toContain("process.exit(1)");
+  });
 });
 
 // ---------------------------------------------------------------------------

package/src/setup.test.ts

@@ -20,9 +20,26 @@ afterAll(() => {
   } catch {}
 });
 
-const { probeDb, dbDownloadUrls } = await import("./setup.ts");
+const { dbDownloadUrls, probeDb, releaseDownloadLock, tryAcquireDownloadLock, waitForUsableDb } = await import("./setup.ts");
 const { SCHEMA_VERSION } = await import("./paths.ts");
 
+function writeUsableDb(dbFile: string, releaseTag = "v0.0.0-test"): void {
+  const db = new sqlite(dbFile);
+  db.run(`PRAGMA user_version = ${SCHEMA_VERSION};`);
+  db.run("CREATE TABLE pages (id INTEGER PRIMARY KEY, title TEXT);");
+  db.run("CREATE TABLE commands (id INTEGER PRIMARY KEY, path TEXT);");
+  db.run("CREATE TABLE db_meta (key TEXT PRIMARY KEY, value TEXT NOT NULL);");
+
+  const insertPage = db.prepare("INSERT INTO pages (title) VALUES (?)");
+  for (let i = 0; i < 100; i++) insertPage.run(`page-${i}`);
+
+  const insertCmd = db.prepare("INSERT INTO commands (path) VALUES (?)");
+  for (let i = 0; i < 1000; i++) insertCmd.run(`/cmd/${i}`);
+
+  db.run("INSERT INTO db_meta (key, value) VALUES ('release_tag', ?);", [releaseTag]);
+  db.close();
+}
+
 // ---------------------------------------------------------------------------
 // dbDownloadUrls — version pinning + latest fallback
 // ---------------------------------------------------------------------------
@@ -53,6 +70,53 @@ describe("dbDownloadUrls", () => {
   });
 });
 
+// ---------------------------------------------------------------------------
+// download lock helpers — serialize package-mode DB preparation
+// ---------------------------------------------------------------------------
+
+describe("download lock helpers", () => {
+  test("lock is exclusive until released", () => {
+    const dbFile = path.join(tmp, "locked.db");
+    const first = tryAcquireDownloadLock(dbFile);
+    expect(first).not.toBeNull();
+    const second = tryAcquireDownloadLock(dbFile);
+    expect(second).toBeNull();
+
+    releaseDownloadLock(first);
+
+    const third = tryAcquireDownloadLock(dbFile);
+    expect(third).not.toBeNull();
+    releaseDownloadLock(third);
+  });
+
+  test("waitForUsableDb returns false when lock goes away without a healthy DB", async () => {
+    const dbFile = path.join(tmp, "wait-false.db");
+    const lock = tryAcquireDownloadLock(dbFile);
+    expect(lock).not.toBeNull();
+
+    const waiter = waitForUsableDb(dbFile, () => {}, 2_000);
+    setTimeout(() => releaseDownloadLock(lock), 100);
+
+    expect(await waiter).toBe(false);
+  });
+
+  test("waitForUsableDb returns true when another process finishes the DB", async () => {
+    const dbFile = path.join(tmp, "wait-true.db");
+    const lock = tryAcquireDownloadLock(dbFile);
+    expect(lock).not.toBeNull();
+
+    writeUsableDb(dbFile, "v0.0.0-wait");
+    const waiter = waitForUsableDb(dbFile, () => {}, 2_000);
+    setTimeout(() => releaseDownloadLock(lock), 100);
+
+    expect(await waiter).toBe(true);
+    const probe = probeDb(dbFile);
+    expect(probe?.releaseTag).toBe("v0.0.0-wait");
+    expect(probe?.pages).toBe(100);
+    expect(probe?.commands).toBe(1000);
+  });
+});
+
 // ---------------------------------------------------------------------------
 // probeDb — schema / pages / commands / release_tag
 // ---------------------------------------------------------------------------