dsh-locator 0.8.2 → 0.10.0

package/lib/content.js

@@ -15,7 +15,7 @@
  * alone unless `includeArchived` is set.
  * @module dsh-locator/content
  */
-import { chmodSync, closeSync, existsSync, mkdirSync, openSync, readFileSync, rmSync, statSync, writeFileSync } from 'node:fs';
+import { chmodSync, closeSync, existsSync, mkdirSync, openSync, readFileSync, renameSync, rmSync, statSync, writeFileSync } from 'node:fs';
 import { readdir, readFile, stat } from 'node:fs/promises';
 import { homedir } from 'node:os';
 import { basename, dirname, extname, join } from 'node:path';
@@ -52,7 +52,7 @@ export class ContentIndex {
     rt;
     options;
     db = null;
-    state = { building: false, files: 0, sessions: 0, messages: 0, truncated: false, error: '', updatedAt: 0 };
+    state = { building: false, files: 0, sessions: 0, messages: 0, truncated: false, error: '', warnings: [], updatedAt: 0 };
     generation = 0;
     totalBytes = 0;
     sliceDeadline = 0;
@@ -62,6 +62,8 @@ export class ContentIndex {
     workerSeq = 0;
     pendingStart = false;
     dbIdentity = null;
+    /** Session id → indexed session log path, for session-scoped content search. */
+    sessionPaths = new Map();
     pending = new Map();
     constructor(rt, options) {
         this.rt = rt;
@@ -70,7 +72,7 @@ export class ContentIndex {
     status() {
         if (this.db !== null && !this.state.building && !this.databaseIsCurrent())
             this.recoverExternal();
-        return { ...this.state, building: this.state.building || this.pendingStart };
+        return { ...this.state, warnings: [...this.state.warnings], building: this.state.building || this.pendingStart };
     }
     /**
      * Report a lazy build as in progress before the asynchronous start reaches
@@ -110,6 +112,7 @@ export class ContentIndex {
         this.releaseLock();
         this.pendingStart = false;
         this.dbIdentity = null;
+        this.sessionPaths.clear();
     }
     /** Build everything from scratch. */
     start() { this.begin('full'); }
@@ -200,6 +203,7 @@ export class ContentIndex {
         this.state.building = true;
         this.state.error = '';
         this.state.truncated = false;
+        this.state.warnings = [];
         const run = mode === 'full' ? this.full(generation) : this.incremental(generation);
         void run.catch(error => {
             if (generation !== this.generation)
@@ -261,8 +265,21 @@ export class ContentIndex {
         }
         const dbPath = join(this.options.stateDir, 'content.db');
         const existed = existsSync(dbPath);
-        if (existed && !this.ownedDatabase(dbPath)) {
-            throw new Error(`content.db is not a dsh-locator database, refusing to touch it: ${dbPath}`);
+        if (existed) {
+            const verdict = this.classifyDatabase(dbPath);
+            if (verdict === 'foreign') {
+                throw new Error(`content.db is not a dsh-locator database, refusing to touch it: ${dbPath}`);
+            }
+            if (verdict !== 'ok') {
+                // A corrupt, empty or older-schema database must not disable content
+                // search for the rest of the session. Keep the bad file for diagnosis
+                // (rename, never delete bytes we did not create) and rebuild fresh.
+                // During an incremental open this throws so the caller falls back to a
+                // full rebuild; a full open simply continues with a clean file.
+                this.quarantineDatabase(dbPath, verdict);
+                if (!fresh)
+                    throw new Error('content database is incompatible; rebuilding');
+            }
         }
         let oldFileRemained = false;
         if (fresh) {
@@ -315,57 +332,164 @@ export class ContentIndex {
         }
         if (fresh)
             this.db.exec(`PRAGMA user_version = ${SCHEMA_VERSION}`);
+        this.refreshSessionPaths();
         this.reopenWorker();
     }
+    /**
+     * Decide what an existing `content.db` is before touching it:
+     * - `foreign`: no dsh-locator table at all — refuse to modify it.
+     * - `corrupt`: zero bytes, unreadable, or not a SQLite database.
+     * - `incompatible`: has our tables but a different schema version/shape.
+     * - `ok`: safe to reuse.
+     */
+    classifyDatabase(path) {
+        let size = 0;
+        try {
+            size = statSync(path).size;
+        }
+        catch {
+            return 'corrupt';
+        }
+        if (size === 0)
+            return 'corrupt';
+        let probe;
+        try {
+            probe = new DatabaseSync(path, { readOnly: true });
+            const names = new Set(probe.prepare("SELECT name FROM sqlite_master WHERE type = 'table'").all()
+                .map(row => row.name)
+                .filter((name) => typeof name === 'string'));
+            const owned = ['docs', 'docs_meta', 'sources', 'content_meta'];
+            if (!owned.some(name => names.has(name)))
+                return 'foreign';
+            if (!names.has('docs') || !names.has('docs_meta') || !names.has('sources') || !names.has('content_meta'))
+                return 'incompatible';
+            const version = probe.prepare('PRAGMA user_version').get()?.user_version ?? 0;
+            if (Number(version) !== SCHEMA_VERSION)
+                return 'incompatible';
+            return 'ok';
+        }
+        catch {
+            return 'corrupt';
+        }
+        finally {
+            try {
+                probe?.close();
+            }
+            catch { /* ignore */ }
+        }
+    }
+    /**
+     * Move a broken/outdated database aside instead of destroying it. The
+     * timestamped name keeps the bytes around for inspection; if the rename
+     * fails (another process still holds it on Windows) a fresh file is still
+     * created so content search recovers.
+     */
+    quarantineDatabase(dbPath, verdict) {
+        this.stopWorker();
+        try {
+            this.db?.close();
+        }
+        catch { /* ignore */ }
+        this.db = null;
+        const target = `${dbPath}.corrupt-${Date.now()}`;
+        try {
+            renameSync(dbPath, target);
+            this.addWarning(verdict === 'corrupt' ? 'content-db-corrupt' : 'content-db-incompatible');
+        }
+        catch {
+            try {
+                rmSync(dbPath, { force: true });
+            }
+            catch { /* ignore */ }
+            this.addWarning(verdict === 'corrupt' ? 'content-db-corrupt' : 'content-db-incompatible');
+        }
+        for (const suffix of ['-wal', '-shm']) {
+            try {
+                rmSync(dbPath + suffix, { force: true });
+            }
+            catch { /* ignore */ }
+        }
+    }
+    /** Record one non-fatal build warning (deduplicated, bounded). */
+    addWarning(warning) {
+        if (this.state.warnings.includes(warning))
+            return;
+        if (this.state.warnings.length >= 20)
+            return;
+        this.state.warnings.push(warning);
+    }
     reopenWorker() {
         if (this.worker === null)
             return;
-        this.worker.postMessage({ id: ++this.workerSeq, open: join(this.options.stateDir, 'content.db') });
+        try {
+            this.worker.postMessage({ id: ++this.workerSeq, open: join(this.options.stateDir, 'content.db') });
+        }
+        catch { /* a dying worker is replaced on the next query */ }
     }
     stopWorker() {
         const worker = this.worker;
         this.worker = null;
-        for (const entry of this.pending.values())
-            entry.resolve([]);
+        for (const resolve of this.pending.values())
+            resolve(workerFailureResult('content-search-worker-failed'));
         this.pending.clear();
         if (worker !== null)
             void worker.terminate();
     }
+    /**
+     * Whether a usable search worker exists, creating one when needed.
+     * @returns false when the worker cannot be created at all; that is the only
+     *          case in which an in-process (sync) query is allowed.
+     */
     ensureWorker() {
-        if (this.options.searchWorker !== true || this.worker !== null)
-            return;
+        if (this.options.searchWorker !== true)
+            return false;
+        if (this.worker !== null)
+            return true;
         // In a TypeScript test run the compiled worker does not exist next to the
-        // source; skip spawning and answer queries in-process instead.
+        // source; answer queries in-process instead (budgeted, see searchSync).
         const workerPath = fileURLToPath(new URL('./content-search-worker.js', import.meta.url));
-        if (!existsSync(workerPath))
-            return;
+        const factory = this.options.searchWorkerFactory;
+        if (factory === undefined && !existsSync(workerPath))
+            return false;
         try {
-            const worker = new Worker(workerPath, {
-                workerData: { dbPath: join(this.options.stateDir, 'content.db') },
-            });
-            worker.on('message', (message) => {
-                const entry = this.pending.get(message.id);
-                if (entry === undefined)
-                    return;
-                this.pending.delete(message.id);
-                entry.resolve(message.hits ?? []);
-            });
+            const worker = factory !== undefined
+                ? factory(workerPath)
+                : new Worker(workerPath, { workerData: { dbPath: join(this.options.stateDir, 'content.db') } });
+            worker.on('message', (message) => { this.onWorkerMessage(message); });
             const fail = () => {
                 if (this.worker !== worker)
                     return;
                 this.worker = null;
-                for (const entry of this.pending.values())
-                    entry.reject(new Error('content search worker failed'));
+                for (const resolve of this.pending.values())
+                    resolve(workerFailureResult('content-search-worker-failed'));
                 this.pending.clear();
             };
             worker.on('error', fail);
             worker.on('exit', fail);
             this.worker = worker;
+            return true;
         }
         catch {
             this.worker = null;
+            return false;
         }
     }
+    /**
+     * Resolve one worker reply. A malformed reply is reported as a protocol
+     * error; the query is never retried on the host thread.
+     */
+    onWorkerMessage(message) {
+        if (typeof message !== 'object' || message === null)
+            return;
+        const record = message;
+        if (typeof record.id !== 'number')
+            return;
+        const resolve = this.pending.get(record.id);
+        if (resolve === undefined)
+            return;
+        this.pending.delete(record.id);
+        resolve(isContentSearchResult(record.result) ? record.result : workerFailureResult('content-search-worker-protocol-error'));
+    }
     identityOf(path) {
         try {
             const info = statSync(path);
@@ -401,6 +525,7 @@ export class ContentIndex {
         this.dbIdentity = null;
         this.stopWorker();
         this.totalBytes = 0;
+        this.sessionPaths.clear();
         this.state.updatedAt = 0;
         this.state.error = '';
         this.state.truncated = false;
@@ -414,24 +539,6 @@ export class ContentIndex {
         const scanning = this.rt.status?.scanning;
         return scanning !== undefined && scanning !== null;
     }
-    /** Whether `path` is a SQLite database this plugin created (has docs_meta). */
-    ownedDatabase(path) {
-        let probe;
-        try {
-            probe = new DatabaseSync(path, { readOnly: true });
-            const row = probe.prepare("SELECT name FROM sqlite_master WHERE type = 'table' AND name = 'docs_meta'").get();
-            return row !== undefined;
-        }
-        catch {
-            return false;
-        }
-        finally {
-            try {
-                probe?.close();
-            }
-            catch { /* ignore */ }
-        }
-    }
     readFlag(key) {
         const row = this.db.prepare('SELECT value FROM content_meta WHERE key = ?').get(key);
         return row?.value === undefined ? undefined : Number(row.value);
@@ -477,11 +584,41 @@ export class ContentIndex {
         this.state.updatedAt = Date.now();
         this.writeTotalBytes();
         this.writeFlag('complete', 1);
+        this.refreshSessionPaths();
         this.reopenWorker();
     }
+    /**
+     * Rebuild the session id → session log path map from the persisted sources.
+     * Runs after `open()` and after every build/refresh, so session-scoped
+     * searches work against an existing database before the first refresh ends.
+     */
+    refreshSessionPaths() {
+        this.sessionPaths.clear();
+        if (this.db === null)
+            return;
+        try {
+            const rows = this.db.prepare('SELECT path FROM sources').all();
+            for (const row of rows) {
+                const path = row.path;
+                if (typeof path !== 'string' || path === '')
+                    continue;
+                const sessionId = basename(dirname(path));
+                if (sessionId !== '')
+                    this.sessionPaths.set(sessionId, path);
+            }
+        }
+        catch {
+            // A database from an older schema cannot answer session-scoped queries
+            // until its next rebuild; leave the map empty instead of failing boot.
+        }
+    }
     addDoc(row) {
         const cap = this.options.maxTotalBytes ?? 0;
-        if (cap > 0 && this.totalBytes + row.body.length > cap) {
+        // Replacing an existing document frees its old body first: an unchanged
+        // file rewritten at refresh time must not be rejected because its stale
+        // copy still occupies the budget.
+        const previous = this.storedBytes(row.key);
+        if (cap > 0 && this.totalBytes - previous + row.body.length > cap) {
             this.state.truncated = true;
             return false;
         }
@@ -492,6 +629,12 @@ export class ContentIndex {
         this.totalBytes += row.body.length;
         return true;
     }
+    /** Body bytes stored for one document key (0 when it is not indexed). */
+    storedBytes(key) {
+        const row = this.db.prepare(`SELECT COALESCE(length(d.body), 0) AS n
+      FROM docs_meta m JOIN docs d ON d.rowid = m.rowid WHERE m.doc_key = ?`).get(key);
+        return Number(row?.n ?? 0);
+    }
     deleteDoc(key) {
         const row = this.db.prepare('SELECT rowid FROM docs_meta WHERE doc_key = ?').get(key);
         if (row === undefined)
@@ -517,6 +660,7 @@ export class ContentIndex {
         let after = 0;
         let seen = 0;
         let scanned = 0;
+        let capped = false;
         for (;;) {
             if (generation !== this.generation)
                 return;
@@ -532,8 +676,10 @@ export class ContentIndex {
                     continue;
                 if (!TEXT_EXTENSIONS.has(extname(entry.name).toLowerCase()) || contentSkipPath(entry.path, this.options.excludes ?? []))
                     continue;
-                if (this.options.maxFiles > 0 && seen >= this.options.maxFiles)
+                if (this.options.maxFiles > 0 && seen >= this.options.maxFiles) {
+                    capped = true;
                     break;
+                }
                 const row = await this.readFileDoc(entry.path, entry.name, entry.mtime);
                 if (row === null)
                     continue;
@@ -542,6 +688,8 @@ export class ContentIndex {
                     return;
                 await this.breathe();
             }
+            if (capped)
+                break;
             after = page.next;
             if (page.done || page.entries.length === 0)
                 break;
@@ -554,8 +702,13 @@ export class ContentIndex {
         const seen = new Set();
         const deferred = [];
         let after = 0;
+        // `maxFiles` counts documents that are actually stored. A file whose read
+        // failed is not stored, so it must not consume a slot: counting it here used
+        // to stop the loop early (and the deletion pass then removed every trailing
+        // document that was never reached). `indexed` only moves on success.
         let indexed = 0;
         let scanned = 0;
+        let capped = false;
         for (;;) {
             if (generation !== this.generation)
                 return;
@@ -571,24 +724,35 @@ export class ContentIndex {
                     continue;
                 if (!TEXT_EXTENSIONS.has(extname(entry.name).toLowerCase()) || contentSkipPath(entry.path, this.options.excludes ?? []))
                     continue;
-                if (this.options.maxFiles > 0 && indexed >= this.options.maxFiles)
+                if (this.options.maxFiles > 0 && indexed >= this.options.maxFiles) {
+                    capped = true;
                     break;
+                }
                 const key = `file:${entry.path}`;
                 seen.add(key);
-                indexed++;
-                if (meta.get(key) === entry.mtime)
+                if (meta.get(key) === entry.mtime) {
+                    // Unchanged and already stored: it still occupies one of the slots.
+                    indexed++;
                     continue;
-                if (this.wouldExceed(entry.size)) {
+                }
+                if (this.wouldExceed(entry.size, key)) {
                     deferred.push({ path: entry.path, name: entry.name, mtime: entry.mtime, size: entry.size });
                     continue;
                 }
-                this.deleteDoc(key);
+                // Read first, replace only on success. A transient read failure must
+                // keep the document indexed by the previous refresh, not delete it.
                 const row = await this.readFileDoc(entry.path, entry.name, entry.mtime);
-                if (row !== null && !this.addDoc(row)) {
+                if (row === null)
+                    continue;
+                if (!this.addDoc(row)) {
                     deferred.push({ path: entry.path, name: entry.name, mtime: entry.mtime, size: entry.size });
+                    continue;
                 }
+                indexed++;
                 await this.breathe();
             }
+            if (capped)
+                break;
             after = page.next;
             if (page.done || page.entries.length === 0)
                 break;
@@ -601,13 +765,14 @@ export class ContentIndex {
         for (const entry of deferred) {
             if (generation !== this.generation)
                 return;
-            if (this.wouldExceed(entry.size)) {
+            if (this.wouldExceed(entry.size, `file:${entry.path}`)) {
                 this.state.truncated = true;
                 continue;
             }
-            this.deleteDoc(`file:${entry.path}`);
             const row = await this.readFileDoc(entry.path, entry.name, entry.mtime);
-            if (row === null || !this.addDoc(row)) {
+            if (row === null)
+                continue;
+            if (!this.addDoc(row)) {
                 this.state.truncated = true;
                 continue;
             }
@@ -615,11 +780,12 @@ export class ContentIndex {
         }
     }
     /** Would storing a file of this size overflow the configured body budget? */
-    wouldExceed(size) {
+    wouldExceed(size, docKey) {
         const cap = this.options.maxTotalBytes ?? 0;
         if (cap <= 0)
             return false;
-        return this.totalBytes + Math.min(size, this.options.maxFileBytes) > cap;
+        const previous = docKey === undefined ? 0 : this.storedBytes(docKey);
+        return this.totalBytes - previous + Math.min(size, this.options.maxFileBytes) > cap;
     }
     async readFileDoc(path, name, mtime) {
         let buffer;
@@ -639,8 +805,15 @@ export class ContentIndex {
         for (const file of files) {
             if (generation !== this.generation)
                 return;
+            const read = await this.readSessionText(file);
+            if (!read.ok) {
+                // A log that cannot be read or decompressed does not contribute rows;
+                // the build continues with the remaining sessions.
+                this.addWarning('content-session-log-unreadable');
+                continue;
+            }
             this.deletePath(file.path);
-            if (!(await this.indexSessionFile(file, generation)))
+            if (!(await this.indexSessionText(file, read.text, generation)))
                 return;
             this.db.prepare('INSERT OR REPLACE INTO sources (path, mtime) VALUES (?, ?)').run(file.path, file.mtime);
             await this.breathe();
@@ -662,8 +835,16 @@ export class ContentIndex {
                 continue;
             if (known.get(file.path) === file.mtime)
                 continue;
+            // Decode the whole log before touching the old rows. On failure keep the
+            // previous messages and the previous sources.mtime, so the next refresh
+            // retries the same file instead of treating it as empty.
+            const read = await this.readSessionText(file);
+            if (!read.ok) {
+                this.addWarning('content-session-log-unreadable');
+                continue;
+            }
             this.deletePath(file.path);
-            if (!(await this.indexSessionFile(file, generation)))
+            if (!(await this.indexSessionText(file, read.text, generation)))
                 return;
             this.db.prepare('INSERT OR REPLACE INTO sources (path, mtime) VALUES (?, ?)').run(file.path, file.mtime);
             await this.breathe();
@@ -675,17 +856,23 @@ export class ContentIndex {
             this.db.prepare('DELETE FROM sources WHERE path = ?').run(path);
         }
     }
-    async indexSessionFile(file, generation) {
+    /** Read and decompress one session log completely; no side effects on rows. */
+    async readSessionText(file) {
         let text;
         try {
             text = (await zstdDecompressAsync(await readFile(file.path))).toString('utf8');
         }
-        catch {
-            return true;
+        catch (error) {
+            return { ok: false, error: messageOf(error) };
         }
+        return { ok: true, text };
+    }
+    /** Index one already-decoded session log; the caller owns row replacement. */
+    async indexSessionText(file, text, generation) {
         if (generation !== this.generation)
             return false;
         const sessionId = basename(dirname(file.path));
+        this.sessionPaths.set(sessionId, file.path);
         let title = '';
         let parsed = 0;
         for (const line of text.split('\n')) {
@@ -735,57 +922,134 @@ export class ContentIndex {
             return this.options.sessionDirs;
         return [join(dshHome(), 'sessions')];
     }
-    /**
-     * Search file bodies and session messages. With `searchWorker` enabled the
-     * query itself runs off the host thread; a failed or wedged worker falls back
-     * to the in-process query so a result is still produced.
-     * @param query - words or a phrase to find.
-     * @param limit - maximum hits.
-     * @returns matching documents ordered by relevance.
-     */
-    async search(query, limit) {
+    async search(query, limit, options) {
+        const result = await this.searchDetailed(query, limit, options ?? {});
+        return options === undefined ? result.hits : result;
+    }
+    async searchDetailed(query, limit, options) {
+        const resolved = this.resolveSession(options);
+        if (resolved === null)
+            return emptySearchResult(['unknown-session']);
         if (this.db === null)
-            return [];
+            return emptySearchResult();
         if (!this.databaseIsCurrent()) {
             this.recoverExternal();
-            return [];
+            return emptySearchResult();
         }
+        // Direct embedders run in-process by design (searchWorker is off).
         if (this.options.searchWorker !== true)
-            return this.searchSync(query, limit);
-        this.ensureWorker();
-        if (this.worker === null)
-            return this.searchSync(query, limit);
-        const id = ++this.workerSeq;
+            return this.searchSync(query, limit, resolved, false);
+        if (!this.ensureWorker()) {
+            // The worker could not be created at all: the one allowed sync path.
+            return this.searchSync(query, limit, resolved, true);
+        }
+        return await this.searchInWorker(query, limit, resolved);
+    }
+    /** Run one query on the worker; timeout/protocol errors are final results. */
+    async searchInWorker(query, limit, options) {
         const worker = this.worker;
-        const response = new Promise((resolve, reject) => { this.pending.set(id, { resolve, reject }); });
-        worker.postMessage({ id, query, limit });
+        if (worker === null)
+            return workerFailureResult('content-search-worker-failed');
+        const id = ++this.workerSeq;
+        const response = new Promise(resolve => { this.pending.set(id, resolve); });
+        const timeoutMs = Math.max(1, this.options.searchWorkerTimeoutMs ?? WORKER_TIMEOUT_MS);
         let timer;
-        const timeout = new Promise((_resolve, reject) => {
-            timer = setTimeout(() => { this.pending.delete(id); reject(new Error('content search worker timed out')); }, 5_000);
+        const timeout = new Promise(resolve => {
+            timer = setTimeout(() => {
+                if (!this.pending.delete(id))
+                    return;
+                // A wedged worker is thrown away; the next query gets a fresh one. The
+                // current query is reported as timed out, never re-run here.
+                if (this.worker === worker) {
+                    this.worker = null;
+                    void worker.terminate();
+                }
+                resolve(workerFailureResult('content-search-timeout'));
+            }, timeoutMs);
         });
         try {
-            return await Promise.race([response, timeout]);
+            worker.postMessage({ id, query, limit, options });
         }
         catch {
-            return this.searchSync(query, limit);
+            if (this.pending.delete(id)) {
+                if (timer !== undefined)
+                    clearTimeout(timer);
+                return workerFailureResult('content-search-worker-failed');
+            }
+        }
+        try {
+            return await Promise.race([response, timeout]);
         }
         finally {
             if (timer !== undefined)
                 clearTimeout(timer);
         }
     }
-    searchSync(query, limit) {
+    /** Map a request's sessionId onto the indexed session log path. */
+    resolveSession(options) {
+        if (options.sessionPath !== undefined && options.sessionPath !== null)
+            return options;
+        if (options.sessionId === undefined || options.sessionId === '')
+            return { ...options, sessionPath: null };
+        const path = this.sessionPaths.get(options.sessionId);
+        if (path === undefined)
+            return null;
+        return { ...options, sessionPath: path };
+    }
+    /**
+     * In-process query path. When `degraded` is set (worker creation failed) the
+     * options are tightened so this rare path cannot spend an unbounded amount of
+     * host-thread time counting matches.
+     */
+    searchSync(query, limit, options, degraded) {
         if (this.db === null)
-            return [];
+            return emptySearchResult();
+        const effective = degraded ? budgetedSearchOptions(options) : options;
         try {
-            return searchContent(this.db, query, limit);
+            const result = searchContent(this.db, query, limit, effective);
+            if (!degraded)
+                return result;
+            return { ...result, warnings: [...new Set(['content-search-in-process', ...result.warnings])] };
         }
         catch (error) {
             this.state.error = messageOf(error);
-            return [];
+            return emptySearchResult();
         }
     }
 }
+/** Default deadline for one worker query. */
+const WORKER_TIMEOUT_MS = 5_000;
+/** Counting cap used by the rare in-process fallback. */
+const IN_PROCESS_COUNT_LIMIT = 200;
+/** Tighten a query for the in-process fallback: bounded counting only. */
+function budgetedSearchOptions(options) {
+    return {
+        ...options,
+        count: options.count === 'none' ? 'none' : 'bounded',
+        countLimit: Math.min(options.countLimit ?? IN_PROCESS_COUNT_LIMIT, IN_PROCESS_COUNT_LIMIT),
+    };
+}
+/** Whether a value looks like a complete worker search result. */
+function isContentSearchResult(value) {
+    if (typeof value !== 'object' || value === null)
+        return false;
+    const record = value;
+    if (!Array.isArray(record.hits) || !Array.isArray(record.warnings))
+        return false;
+    const count = record.count;
+    if (typeof count !== 'object' || count === null)
+        return false;
+    const kind = count.kind;
+    return kind === 'exact' || kind === 'bounded' || kind === 'unknown';
+}
+/** Result for a failed worker query; carries an explicit error code. */
+function workerFailureResult(error) {
+    return { hits: [], count: { value: 0, kind: 'unknown' }, warnings: [error], error };
+}
+/** Result used when a content query could not run at all. */
+function emptySearchResult(warnings = []) {
+    return { hits: [], count: { value: 0, kind: 'unknown' }, warnings };
+}
 function dshHome() {
     return process.env.DSH_HOME || join(homedir(), '.dsh');
 }