pi-hashline-edit-pro 2.8.0 → 2.8.2

package/src/grep.ts

@@ -1,20 +1,20 @@
 import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
 import { formatSize, DEFAULT_MAX_BYTES, DEFAULT_MAX_LINES, type TruncationResult } from "@earendil-works/pi-coding-agent";
 import { Type } from "typebox";
-import { readdir, stat } from "fs/promises";
+import { stat } from "fs/promises";
 import { dirname, join, relative } from "path";
+import { spawn, spawnSync } from "child_process";
+import { createInterface } from "readline";
 import { tryReadNormFile } from "./file-reader";
 import { MAX_HASH_LINES, fmtRow, HASH_LEN, HASH_SEP } from "./hashline";
 import { MAX_GREP_LINE_BYTES } from "./constants";
 import { toCwd } from "./paths";
 import { loadP, loadGuide } from "./prompts";
 import { normReq } from "./payload-contract";
-import { recordServedSafe } from "./served";
+import { recordServedSafe, buildServedMap } from "./served";
 import { abortIf, errCode, isRec, makePrepareArguments, rejectUnknownFields, truncateToBytes, visLines } from "./utils";
 
 const GREP_KS = new Set(["pattern", "path", "glob", "context", "ignoreCase", "literal", "limit"]);
-const SKIP_DIRS = new Set(["node_modules", ".git", ".tmp", "coverage"]);
-const MAX_SCAN_FILES = 4000;
 
 function cmp(a: string, b: string): number {
   return a < b ? -1 : a > b ? 1 : 0;
@@ -47,6 +47,7 @@ export function assertGrepReq(request: unknown): asserts request is GrepReq {
 }
 
 function buildRegex(pattern: string, literal: boolean, ignoreCase: boolean): RegExp {
+  if (!literal) assertSafeRegex(pattern);
   const source = literal ? pattern.replace(/[.*+?^${}()|[\]\\]/g, "\\$&") : pattern;
   try {
     return new RegExp(source, ignoreCase ? "ui" : "u");
@@ -55,6 +56,96 @@ function buildRegex(pattern: string, literal: boolean, ignoreCase: boolean): Reg
   }
 }
 
+interface RegexGroupRisk {
+  hasQuantifier: boolean;
+  hasAlternation: boolean;
+}
+
+function unsafeRegex(pattern: string): never {
+  throw new Error(
+    `[E_UNSAFE_REGEX] Refusing potentially exponential regex: ${pattern}. Use literal: true or simplify the expression.`,
+  );
+}
+
+function assertSafeRegex(pattern: string): void {
+  if (pattern.length > 4096) unsafeRegex(pattern);
+  const groups: RegexGroupRisk[] = [];
+  let inClass = false;
+  let escaped = false;
+  let variableQuantifiers = 0;
+  let lastAtom: { groupRisky: boolean; quantified: boolean } | undefined;
+  for (let i = 0; i < pattern.length; i++) {
+    const ch = pattern[i]!;
+    if (escaped) {
+      if (!inClass && (/[1-9]/.test(ch) || (ch === "k" && pattern[i + 1] === "<"))) {
+        unsafeRegex(pattern);
+      }
+      escaped = false;
+      lastAtom = { groupRisky: false, quantified: false };
+      continue;
+    }
+    if (ch === "\\") {
+      escaped = true;
+      continue;
+    }
+    if (inClass) {
+      if (ch === "]") {
+        inClass = false;
+        lastAtom = { groupRisky: false, quantified: false };
+      }
+      continue;
+    }
+    if (ch === "[") {
+      inClass = true;
+      continue;
+    }
+    if (ch === "(") {
+      groups.push({ hasQuantifier: false, hasAlternation: false });
+      lastAtom = undefined;
+      continue;
+    }
+    if (ch === ")") {
+      const group = groups.pop();
+      if (group) {
+        lastAtom = {
+          groupRisky: group.hasQuantifier || group.hasAlternation,
+          quantified: false,
+        };
+      }
+      continue;
+    }
+    if (ch === "|") {
+      const group = groups.at(-1);
+      if (group) group.hasAlternation = true;
+      lastAtom = undefined;
+      continue;
+    }
+    let quantifierLength = 0;
+    if (ch === "*" || ch === "+" || ch === "?") {
+      quantifierLength = 1;
+    } else if (ch === "{") {
+      quantifierLength = /^\{\d+(?:,\d*)?\}/.exec(pattern.slice(i))?.[0].length ?? 0;
+    }
+    if (ch === "{" && quantifierLength > 0) {
+      const quant = pattern.slice(i, i + quantifierLength);
+      const m = /^\{(\d+)/.exec(quant);
+      if (m && Number(m[1]) > 1000) unsafeRegex(pattern);
+    }
+    if (quantifierLength > 0 && lastAtom) {
+      if (ch === "?" && lastAtom.quantified) continue;
+      const variable = ch !== "{" || pattern.slice(i, i + quantifierLength).includes(",");
+      if (variable && ++variableQuantifiers > 1) unsafeRegex(pattern);
+      if (lastAtom.groupRisky) unsafeRegex(pattern);
+      const group = groups.at(-1);
+      if (group) group.hasQuantifier = true;
+      lastAtom.quantified = true;
+      i += quantifierLength - 1;
+      continue;
+    }
+    lastAtom = { groupRisky: false, quantified: false };
+  }
+}
+
 function globToRegex(glob: string): RegExp {
   if (glob.startsWith("/")) glob = glob.slice(1);
   let source = "";
@@ -87,8 +178,10 @@ interface FileHit {
   path: string;
   displayPath: string;
   fileHashes: string[];
+  fileLines: string[];
   rows: string[];
   hashes: string[];
+  lineNumbers: number[];
   matchCount: number;
   totalMatchCount: number;
   fragmented: boolean[];
@@ -129,89 +222,41 @@ function grepHeadFragment(line: string): string {
   return head.length < line.length ? `${head}...` : head;
 }
 
-interface ScanState {
-  scanned: number;
-  stopped: boolean;
-}
-
-async function walkFiles(
-  root: string,
-  state: ScanState,
-  onFile: (absPath: string) => Promise<void>,
-): Promise<void> {
-  const queue: string[] = [root];
-  let head = 0;
-  while (head < queue.length && !state.stopped) {
-    const dir = queue[head++]!;
-    let entries;
-    try {
-      entries = await readdir(dir, { withFileTypes: true });
-    } catch {
-      continue;
-    }
-    entries.sort((a, b) => cmp(a.name, b.name));
-    for (const entry of entries) {
-      if (state.stopped) break;
-      const full = join(dir, entry.name);
-      if (entry.isDirectory()) {
-        if (SKIP_DIRS.has(entry.name)) continue;
-        queue.push(full);
-      } else if (entry.isFile()) {
-        state.scanned += 1;
-        if (state.scanned > MAX_SCAN_FILES) {
-          state.stopped = true;
-          break;
-        }
-        await onFile(full);
-      }
-    }
-  }
-}
-
-async function searchFile(
-  absPath: string,
-  globRoot: string,
-  cwd: string,
-  regex: RegExp,
-  globRegex: RegExp | undefined,
+function makeHitFromIndices(
+  norm: { normalized: string; fileHashes: string[]; absolutePath: string },
+  displayPath: string,
+  matchIndices: number[],
   context: number,
-  maxMatches: number,
-): Promise<FileHit | undefined> {
-  const displayPath = relative(cwd, absPath).replace(/\\/g, "/");
-  if (globRegex) {
-    const globPath = relative(globRoot, absPath).replace(/\\/g, "/");
-    if (!globRegex.test(globPath) && !globRegex.test(displayPath)) return undefined;
-  }
-  const norm = await tryReadNormFile(absPath, cwd, { maxLines: MAX_HASH_LINES, noPersist: true });
-  if (!norm) return undefined;
+  regex: RegExp | undefined,
+  totalMatchCount: number,
+  keptMatchCount: number,
+): FileHit {
   const lines = visLines(norm.normalized);
-  const matchLines: number[] = [];
-  for (let i = 0; i < lines.length; i++) {
-    if (regex.test(lines[i]!)) matchLines.push(i);
-  }
-  if (matchLines.length === 0) return undefined;
-  const keptMatches = matchLines.length > maxMatches ? matchLines.slice(0, maxMatches) : matchLines;
   const shown = new Set<number>();
-  for (const i of keptMatches) {
+  const kept = matchIndices.slice(0, keptMatchCount);
+  for (const i of kept) {
     for (let j = Math.max(0, i - context); j <= Math.min(lines.length - 1, i + context); j++) shown.add(j);
   }
   const sorted = [...shown].sort((a, b) => a - b);
-  const matchSet = new Set(matchLines);
+  const matchSet = new Set(matchIndices);
   const rows: string[] = [];
   const hashes: string[] = [];
+  const lineNumbers: number[] = [];
   const fragmented: boolean[] = [];
   for (const idx of sorted) {
     const hash = norm.fileHashes[idx]!;
     const line = lines[idx]!;
     const row = fmtRow(hash, line);
     if (Buffer.byteLength(row, "utf-8") > MAX_GREP_LINE_BYTES) {
-      const content = matchSet.has(idx) ? grepMatchFragment(line, regex) : grepHeadFragment(line);
+      const content = matchSet.has(idx) && regex ? grepMatchFragment(line, regex) : grepHeadFragment(line);
       rows.push(fmtRow(hash, content));
       hashes.push(hash);
+      lineNumbers.push(idx + 1);
       fragmented.push(true);
     } else {
       rows.push(row);
       hashes.push(hash);
+      lineNumbers.push(idx + 1);
       fragmented.push(false);
     }
   }
@@ -219,14 +264,142 @@ async function searchFile(
     path: norm.absolutePath,
     displayPath,
     fileHashes: norm.fileHashes,
+    fileLines: lines,
     rows,
     hashes,
-    matchCount: keptMatches.length,
-    totalMatchCount: matchLines.length,
+    lineNumbers,
+    matchCount: kept.length,
+    totalMatchCount,
     fragmented,
   };
 }
 
+async function resolveRgPath(): Promise<string> {
+  try {
+    const r = spawnSync("rg", ["--version"], { stdio: "pipe" });
+    if (!r.error && r.status === 0) return "rg";
+  } catch {}
+  try {
+    const { homedir } = await import("os");
+    const { existsSync } = await import("fs");
+    const home = process.env.HOME ?? homedir();
+    const base = process.env.PI_CODING_AGENT_DIR ?? join(home, ".pi", "agent");
+    const bin = join(base, "bin", process.platform === "win32" ? "rg.exe" : "rg");
+    if (existsSync(bin)) {
+      const r = spawnSync(bin, ["--version"], { stdio: "pipe" });
+      if (!r.error && r.status === 0) return bin;
+    }
+  } catch {}
+  try {
+    const { createRequire } = await import("module");
+    const require = createRequire(import.meta.url);
+    const pkgPath = require.resolve("@earendil-works/pi-coding-agent/package.json");
+    const { dirname } = await import("path");
+    const piDir = dirname(pkgPath);
+    const toolsManagerPath = join(piDir, "dist/utils/tools-manager.js");
+    const mod = await import("file://" + toolsManagerPath);
+    if (mod.ensureTool) {
+      const p = await mod.ensureTool("rg", true);
+      if (p) return p;
+    }
+  } catch {}
+  throw new Error("[E_ACCESS] ripgrep (rg) is required for grep but was not found. Install ripgrep or ensure pi can download it to ~/.pi/agent/bin.");
+}
+
+async function collectRgMatches(
+  rgPath: string,
+  pattern: string,
+  searchPath: string,
+  req: GrepReq,
+  signal?: AbortSignal,
+): Promise<Map<string, number[]>> {
+  const args = ["--json", "--line-number", "--color=never", "--hidden"];
+  if (req.ignoreCase) args.push("--ignore-case");
+  if (req.literal) args.push("--fixed-strings");
+  args.push("--", pattern, searchPath);
+  const result = new Map<string, number[]>();
+  return await new Promise<Map<string, number[]>>((resolve, reject) => {
+    const child = spawn(rgPath, args, { stdio: ["ignore", "pipe", "pipe"] });
+    const rl = createInterface({ input: child.stdout });
+    let stderr = "";
+    let timedOut = false;
+    const rgTimeout = setTimeout(() => {
+      timedOut = true;
+      if (!child.killed) child.kill("SIGKILL");
+      reject(new Error("rg timeout"));
+    }, 10000);
+    child.stderr?.on("data", (chunk) => {
+      stderr += chunk.toString();
+    });
+    const onAbort = () => {
+      if (!child.killed) child.kill("SIGKILL");
+    };
+    signal?.addEventListener("abort", onAbort, { once: true });
+    const cleanup = () => {
+      clearTimeout(rgTimeout);
+      rl.close();
+      signal?.removeEventListener("abort", onAbort);
+    };
+    rl.on("line", (line) => {
+      if (!line.trim()) return;
+      let event: { type?: string; data?: { path?: { text?: string }; line_number?: number } };
+      try {
+        event = JSON.parse(line);
+      } catch {
+        return;
+      }
+      if (event.type === "match") {
+        const filePath = event.data?.path?.text;
+        const lineNumber = event.data?.line_number;
+        if (typeof filePath === "string" && typeof lineNumber === "number") {
+          let abs: string;
+          try {
+            abs = filePath.startsWith("/") || /^[A-Za-z]:\\/.test(filePath) ? filePath : join(searchPath, filePath);
+          } catch {
+            abs = filePath;
+          }
+          const list = result.get(abs) ?? [];
+          list.push(lineNumber);
+          result.set(abs, list);
+        }
+      }
+    });
+    child.on("error", (error) => {
+      cleanup();
+      reject(error);
+    });
+    child.on("close", (code) => {
+      cleanup();
+      if (timedOut) return;
+      if (signal?.aborted) {
+        reject(new Error("Operation aborted"));
+        return;
+      }
+      if (code !== 0 && code !== 1) {
+        const msg = stderr.trim() || `ripgrep exited with code ${code}`;
+        reject(new Error(msg));
+        return;
+      }
+      resolve(result);
+    });
+  });
+}
+
+function gutterWidthFor(numbers: number[]): number {
+  let max = 0;
+  for (const n of numbers) if (n > max) max = n;
+  return String(max || 1).length;
+}
+
+function displayRowsForHit(hit: FileHit): string[] {
+  const width = gutterWidthFor(hit.lineNumbers);
+  return hit.rows.map((row, i) => {
+    const n = hit.lineNumbers[i]!;
+    const padded = String(n).padStart(width, " ");
+    return `${padded} │ ${row}`;
+  });
+}
+
 const grepToolSchema = Type.Object(
   {
     pattern: Type.String({
@@ -283,10 +456,8 @@ export function regGrep(pi: ExtensionAPI): void {
       const canonical = normReq(params);
       assertGrepReq(canonical);
       const req = canonical;
-      const regex = buildRegex(req.pattern, req.literal === true, req.ignoreCase === true);
       const context = req.context ?? 0;
       const limit = req.limit ?? 100;
-      const globRegex = req.glob === undefined ? undefined : globToRegex(req.glob);
       const base = req.path ? toCwd(req.path, ctx.cwd) : ctx.cwd;
       abortIf(signal);
       let baseStat;
@@ -299,16 +470,9 @@ export function regGrep(pi: ExtensionAPI): void {
         throw new Error(`[E_ACCESS] Cannot access path: ${req.path ?? ctx.cwd}`);
       }
       const globRoot = baseStat.isFile() ? dirname(base) : base;
-      const state: ScanState = { scanned: 0, stopped: false };
-      const files: string[] = [];
-      if (baseStat.isFile()) {
-        files.push(base);
-      } else {
-        await walkFiles(base, state, async (absPath) => {
-          files.push(absPath);
-        });
-        files.sort(cmp);
-      }
+      const globRegex = req.glob === undefined ? undefined : globToRegex(req.glob);
+      const validatedRegex = buildRegex(req.pattern, req.literal === true, req.ignoreCase === true);
+      const rgPath = await resolveRgPath();
       const hits: FileHit[] = [];
       let matches = 0;
       let limitTruncated = false;
@@ -320,17 +484,26 @@ export function regGrep(pi: ExtensionAPI): void {
       let truncatedBy: "lines" | "bytes" | null = null;
       let linesReplaced = 0;
       let countOnly = false;
-      for (let f = 0; f < files.length; f++) {
+      const rgMatches = await collectRgMatches(rgPath, req.pattern, base, req, signal);
+      const sortedFiles = [...rgMatches.keys()].sort(cmp);
+      for (let f = 0; f < sortedFiles.length; f++) {
         abortIf(signal);
-        const absPath = files[f]!;
+        const absPath = sortedFiles[f]!;
+        const allNums = rgMatches.get(absPath) ?? [];
+        const totalForFile = allNums.length;
+        const sortedNums = [...allNums].sort((a, b) => a - b);
+        const indices = sortedNums.map((n) => n - 1).filter((n) => n >= 0);
         if (countOnly) {
-          const hit = await searchFile(absPath, globRoot, ctx.cwd, regex, globRegex, context, Number.MAX_SAFE_INTEGER);
-          if (!hit) continue;
-          totalRows += hit.rows.length;
-          for (const row of hit.rows) totalBytes += Buffer.byteLength(row, "utf-8") + 1;
+          const norm = await tryReadNormFile(absPath, ctx.cwd, { maxLines: MAX_HASH_LINES, noPersist: true, signal });
+          if (!norm) continue;
+          const hit = makeHitFromIndices(norm, relative(ctx.cwd, absPath).replace(/\\/g, "/"), indices, context, validatedRegex, totalForFile, indices.length);
+          const display = displayRowsForHit(hit);
+          totalRows += display.length;
+          for (const r of display) totalBytes += Buffer.byteLength(r, "utf-8") + 1;
           const remaining = limit - matches;
           if (remaining > 0) {
-            matches += Math.min(hit.matchCount, remaining);
+            const add = Math.min(hit.matchCount, remaining);
+            matches += add;
             if (hit.matchCount > remaining) limitTruncated = true;
           } else {
             limitTruncated = true;
@@ -342,24 +515,36 @@ export function regGrep(pi: ExtensionAPI): void {
           limitTruncated = true;
           break;
         }
-        const hit = await searchFile(absPath, globRoot, ctx.cwd, regex, globRegex, context, remaining);
+        const norm = await tryReadNormFile(absPath, ctx.cwd, { maxLines: MAX_HASH_LINES, noPersist: true, signal });
+        if (!norm) continue;
+        if (globRegex) {
+          const displayPath = relative(ctx.cwd, absPath).replace(/\\/g, "/");
+          const globPath = relative(globRoot, absPath).replace(/\\/g, "/");
+          if (!globRegex.test(globPath) && !globRegex.test(displayPath)) continue;
+        }
+        const hit = makeHitFromIndices(norm, relative(ctx.cwd, absPath).replace(/\\/g, "/"), indices, context, validatedRegex, totalForFile, Math.min(totalForFile, remaining));
         if (!hit) continue;
+        const display = displayRowsForHit(hit);
         const keptRows: string[] = [];
         const keptHashes: string[] = [];
-        for (let i = 0; i < hit.rows.length; i++) {
-          const row = hit.rows[i]!;
+        const keptLineNumbers: number[] = [];
+        const keptFragmented: boolean[] = [];
+        for (let i = 0; i < display.length; i++) {
+          const row = display[i]!;
           const rowBytes = Buffer.byteLength(row, "utf-8") + 1;
           if (rowCount >= DEFAULT_MAX_LINES || byteCount + rowBytes > DEFAULT_MAX_BYTES) {
             rowTruncated = true;
             if (truncatedBy === null) truncatedBy = byteCount + rowBytes > DEFAULT_MAX_BYTES ? "bytes" : "lines";
-            for (let j = i; j < hit.rows.length; j++) {
+            for (let j = i; j < display.length; j++) {
               totalRows += 1;
-              totalBytes += Buffer.byteLength(hit.rows[j]!, "utf-8") + 1;
+              totalBytes += Buffer.byteLength(display[j]!, "utf-8") + 1;
             }
             break;
           }
           keptRows.push(row);
-          keptHashes.push(hit.hashes[i]);
+          keptHashes.push(hit.hashes[i]!);
+          keptLineNumbers.push(hit.lineNumbers[i]!);
+          keptFragmented.push(hit.fragmented[i]!);
           if (hit.fragmented[i]) linesReplaced += 1;
           rowCount += 1;
           byteCount += rowBytes;
@@ -368,12 +553,14 @@ export function regGrep(pi: ExtensionAPI): void {
         }
         if (hit.totalMatchCount > hit.matchCount) limitTruncated = true;
         matches += hit.matchCount;
-        hits.push({ ...hit, rows: keptRows, hashes: keptHashes });
+        const displayHit: FileHit = { ...hit, rows: keptRows, hashes: keptHashes, lineNumbers: keptLineNumbers, fragmented: keptFragmented };
+        hits.push(displayHit);
         if (rowTruncated) countOnly = true;
       }
       hits.sort((a, b) => cmp(a.displayPath, b.displayPath));
       for (const hit of hits) {
-        await recordServedSafe(hit.path, hit.hashes, "grep", new Set(hit.fileHashes));
+        const servedMap = buildServedMap(hit.fileHashes, hit.fileLines, hit.hashes);
+        await recordServedSafe(hit.path, servedMap, "grep", new Set(hit.fileHashes));
       }
       const blocks = hits
         .map((hit) => `=== ${hit.displayPath} ===\n${hit.rows.join("\n")}`)
@@ -381,7 +568,6 @@ export function regGrep(pi: ExtensionAPI): void {
       const notes: string[] = [];
       if (rowTruncated) notes.push(`[grep: output truncated at ${DEFAULT_MAX_LINES} rows or ${formatSize(DEFAULT_MAX_BYTES)}; refine the pattern to see more.]`);
       if (limitTruncated) notes.push(`[grep: showing first ${limit} matches; increase limit to see more.]`);
-      if (state.stopped) notes.push(`[grep: scan cap of ${MAX_SCAN_FILES} files reached; results may be incomplete.]`);
       if (linesReplaced > 0) notes.push(`[grep: ${linesReplaced} line(s) exceed ${formatSize(MAX_GREP_LINE_BYTES)} and are shown as truncated fragments; use read to see the full lines.]`);
       const truncated = limitTruncated || rowTruncated;
       const truncation: TruncationResult | undefined = rowTruncated
@@ -408,7 +594,7 @@ export function regGrep(pi: ExtensionAPI): void {
           metrics: {
             matches,
             files: hits.length,
-            truncated: truncated || state.stopped,
+            truncated,
           },
         },
       };

package/src/hash-store/cache.ts

@@ -0,0 +1,18 @@
+export interface SnapshotCacheEntry {
+  checksum: string;
+  lineCount: number;
+  hashes: string[];
+}
+
+export const SNAPSHOT_CACHE_LIMIT = 256;
+
+export const snapshotCache = new Map<string, SnapshotCacheEntry>();
+
+export function cacheSnapshot(path: string, checksum: string, lineCount: number, hashes: string[]): void {
+  snapshotCache.delete(path);
+  snapshotCache.set(path, { checksum, lineCount, hashes: hashes.slice() });
+  if (snapshotCache.size > SNAPSHOT_CACHE_LIMIT) {
+    const oldest = snapshotCache.keys().next().value;
+    if (oldest !== undefined) snapshotCache.delete(oldest);
+  }
+}

package/src/hash-store/retry.ts

@@ -0,0 +1,48 @@
+import { isBusyError } from "./validation";
+
+const sleepSab = new Int32Array(new SharedArrayBuffer(4));
+
+function sleepSync(ms: number): void {
+  Atomics.wait(sleepSab, 0, 0, ms);
+}
+
+const BUSY_RETRIES = 3;
+const BUSY_RETRY_DELAY_MS = 50;
+
+export function withBusyRetry<T>(fn: () => T): T {
+  let lastError: unknown;
+  for (let attempt = 0; attempt <= BUSY_RETRIES; attempt++) {
+    try {
+      return fn();
+    } catch (error) {
+      lastError = error;
+      if (!isBusyError(error) || attempt === BUSY_RETRIES) throw error;
+      sleepSync(BUSY_RETRY_DELAY_MS * (1 << attempt));
+    }
+  }
+  throw lastError;
+}
+
+export async function withBusyRetryAsync<T>(fn: () => T): Promise<T> {
+  let lastError: unknown;
+  for (let attempt = 0; attempt <= BUSY_RETRIES; attempt++) {
+    try {
+      return fn();
+    } catch (error) {
+      lastError = error;
+      if (!isBusyError(error) || attempt === BUSY_RETRIES) throw error;
+      await new Promise<void>((r) => setTimeout(r, BUSY_RETRY_DELAY_MS * (1 << attempt)));
+    }
+  }
+  throw lastError;
+}
+
+export function retriedWrite(stmt: { run(...params: (string | number)[]): unknown }): (...params: (string | number)[]) => void {
+  return (...params) => {
+    withBusyRetry(() => { stmt.run(...params); });
+  };
+}
+
+export async function openDbWithBusyRetryAsync<T>(fn: () => T): Promise<T> {
+  return withBusyRetryAsync(fn);
+}

package/src/hash-store/validation.ts

@@ -0,0 +1,93 @@
+import { HASH_RE } from "../hashline/alphabet";
+
+export function isValidHashList(value: unknown): value is string[] {
+  if (!Array.isArray(value)) return false;
+  for (const hash of value) {
+    if (typeof hash !== "string" || !HASH_RE.test(hash)) return false;
+  }
+  if (new Set(value).size !== value.length) return false;
+  return true;
+}
+
+export function isValidServedMap(value: unknown): value is Record<string, string> {
+  if (typeof value !== "object" || value === null || Array.isArray(value)) return false;
+  for (const [k, v] of Object.entries(value as Record<string, unknown>)) {
+    if (typeof k !== "string" || !HASH_RE.test(k)) return false;
+    if (typeof v !== "string") return false;
+  }
+  return true;
+}
+
+export function parseHashList(raw: string, onInvalid: () => void, context?: string): string[] | undefined {
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(raw);
+  } catch (error) {
+    console.error(`[parseHashList]${context ? ` ${context}:` : ""} failed to parse stored hashes JSON:`, error);
+    onInvalid();
+    return undefined;
+  }
+  if (!isValidHashList(parsed)) {
+    console.error(`[parseHashList]${context ? ` ${context}:` : ""} stored hashes did not pass validation:`, Array.isArray(parsed) ? `length=${parsed.length} sample=${JSON.stringify(parsed.slice(0, 3))}` : (() => { try { return JSON.stringify(parsed)?.slice(0, 500) ?? String(parsed).slice(0, 500); } catch { return String(parsed).slice(0, 500); } })());
+    onInvalid();
+    return undefined;
+  }
+  return parsed;
+}
+
+export function parseServedMap(raw: string, onInvalid: () => void, context?: string): Map<string, string> | undefined {
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(raw);
+  } catch (error) {
+    console.error(`[parseServedMap]${context ? ` ${context}:` : ""} failed to parse stored served JSON:`, error);
+    onInvalid();
+    return undefined;
+  }
+  if (!isValidServedMap(parsed)) {
+    console.error(`[parseServedMap]${context ? ` ${context}:` : ""} stored served did not pass validation:`, (() => { try { return JSON.stringify(parsed)?.slice(0, 500) ?? String(parsed).slice(0, 500); } catch { return String(parsed).slice(0, 500); } })());
+    onInvalid();
+    return undefined;
+  }
+  return new Map(Object.entries(parsed as Record<string, string>));
+}
+
+export function parseStoredHashes(row: Record<string, unknown> | undefined, onInvalid: () => void): string[] | undefined {
+  if (!row) return undefined;
+  return parseHashList(row.hashes as string, onInvalid);
+}
+
+export function parseStoredServed(row: Record<string, unknown> | undefined, onInvalid: () => void): Map<string, string> | undefined {
+  if (!row) return undefined;
+  return parseServedMap(row.hashes as string, onInvalid);
+}
+
+export function isValidSnapshot(value: unknown): value is { content: string; hashes: string[] } {
+  if (typeof value !== "object" || value === null) return false;
+  const v = value as Record<string, unknown>;
+  if (typeof v.content !== "string") return false;
+  return isValidHashList(v.hashes);
+}
+
+export function isCorruptionError(error: unknown): boolean {
+  if (error && typeof error === "object") {
+    const errcode = (error as { errcode?: unknown }).errcode;
+    if (typeof errcode === "number") {
+      return errcode === 11 || errcode === 24 || errcode === 26;
+    }
+    const code = (error as { code?: unknown }).code;
+    if (typeof code === "string" && /NOTADB|CORRUPT/.test(code)) return true;
+  }
+  return (
+    error instanceof Error &&
+    /corrupt|not a database|malformed|database disk image/i.test(error.message)
+  );
+}
+
+export function isBusyError(error: unknown): boolean {
+  if (error && typeof error === "object") {
+    const errcode = (error as { errcode?: unknown }).errcode;
+    if (typeof errcode === "number") return errcode === 5 || errcode === 6;
+  }
+  return error instanceof Error && /busy|locked/i.test(error.message);
+}