@nitpicker/crawler 0.18.0 → 0.19.0

package/lib/append-retry-failed-common-setup-phases.d.ts

@@ -0,0 +1,15 @@
+/**
+ * The setup-phase labels `append()` and `retryFailed()` announce identically
+ * — everything except the one step in between that names what each mode is
+ * actually doing (`'Repromoting external pages'` vs `'Resetting failed
+ * pages'`) — split into a `prefix` (before that step) and `suffix` (after
+ * it). Single source of truth for `APPEND_SETUP_PHASES` /
+ * `RETRY_FAILED_SETUP_PHASES` (issue #294): the two were previously
+ * hand-written as independent nine-entry literal arrays sharing eight of
+ * nine entries verbatim, with nothing to catch one drifting from the other
+ * if a shared phase were added, renamed, or reordered in only one place.
+ */
+export declare const APPEND_RETRY_FAILED_COMMON_SETUP_PHASES: {
+    readonly prefix: readonly ["Extracting archive", "Loading archive config", "Backing up archive"];
+    readonly suffix: readonly ["Loading dedupe-cap shape keys", "Loading crawl state", "Loading resource list", "Loading scraped page count", "Restoring crawl state"];
+};

package/lib/append-retry-failed-common-setup-phases.js

@@ -0,0 +1,21 @@
+/**
+ * The setup-phase labels `append()` and `retryFailed()` announce identically
+ * — everything except the one step in between that names what each mode is
+ * actually doing (`'Repromoting external pages'` vs `'Resetting failed
+ * pages'`) — split into a `prefix` (before that step) and `suffix` (after
+ * it). Single source of truth for `APPEND_SETUP_PHASES` /
+ * `RETRY_FAILED_SETUP_PHASES` (issue #294): the two were previously
+ * hand-written as independent nine-entry literal arrays sharing eight of
+ * nine entries verbatim, with nothing to catch one drifting from the other
+ * if a shared phase were added, renamed, or reordered in only one place.
+ */
+export const APPEND_RETRY_FAILED_COMMON_SETUP_PHASES = {
+    prefix: ['Extracting archive', 'Loading archive config', 'Backing up archive'],
+    suffix: [
+        'Loading dedupe-cap shape keys',
+        'Loading crawl state',
+        'Loading resource list',
+        'Loading scraped page count',
+        'Restoring crawl state',
+    ],
+};

package/lib/append-setup-phases.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Ordered `SetupProgressCallbacks.onPhase` labels `CrawlerOrchestrator.append`
+ * announces, in call order, before its `initializedCallback` fires. Single
+ * source of truth for both the `onPhase` call sites in
+ * `crawler-orchestrator.ts` and the CLI's setup task list (`create-setup-task-list.ts`),
+ * which pre-builds one task-list row per entry — duplicating this sequence by
+ * hand at the CLI layer would silently drift the moment a phase is added,
+ * renamed, or reordered here. Shares its prefix/suffix with
+ * `RETRY_FAILED_SETUP_PHASES` via `APPEND_RETRY_FAILED_COMMON_SETUP_PHASES` —
+ * `'Repromoting external pages'` is the one step unique to `append()`.
+ *
+ * Linear on the success path (no branching before `initializedCallback`). On
+ * failure — anywhere from `archive.updateConfig` through the crawl itself —
+ * a `SETUP_RECOVERY_PHASE_LABELS` entry (`'Restoring archive from backup'`)
+ * is announced instead of continuing this sequence.
+ */
+export declare const APPEND_SETUP_PHASES: readonly ["Extracting archive", "Loading archive config", "Backing up archive", "Repromoting external pages", "Loading dedupe-cap shape keys", "Loading crawl state", "Loading resource list", "Loading scraped page count", "Restoring crawl state"];

package/lib/append-setup-phases.js

@@ -0,0 +1,22 @@
+import { APPEND_RETRY_FAILED_COMMON_SETUP_PHASES } from './append-retry-failed-common-setup-phases.js';
+/**
+ * Ordered `SetupProgressCallbacks.onPhase` labels `CrawlerOrchestrator.append`
+ * announces, in call order, before its `initializedCallback` fires. Single
+ * source of truth for both the `onPhase` call sites in
+ * `crawler-orchestrator.ts` and the CLI's setup task list (`create-setup-task-list.ts`),
+ * which pre-builds one task-list row per entry — duplicating this sequence by
+ * hand at the CLI layer would silently drift the moment a phase is added,
+ * renamed, or reordered here. Shares its prefix/suffix with
+ * `RETRY_FAILED_SETUP_PHASES` via `APPEND_RETRY_FAILED_COMMON_SETUP_PHASES` —
+ * `'Repromoting external pages'` is the one step unique to `append()`.
+ *
+ * Linear on the success path (no branching before `initializedCallback`). On
+ * failure — anywhere from `archive.updateConfig` through the crawl itself —
+ * a `SETUP_RECOVERY_PHASE_LABELS` entry (`'Restoring archive from backup'`)
+ * is announced instead of continuing this sequence.
+ */
+export const APPEND_SETUP_PHASES = [
+    ...APPEND_RETRY_FAILED_COMMON_SETUP_PHASES.prefix,
+    'Repromoting external pages',
+    ...APPEND_RETRY_FAILED_COMMON_SETUP_PHASES.suffix,
+];

package/lib/archive/archive-accessor.d.ts

@@ -29,6 +29,16 @@ export declare class ArchiveAccessor extends EventEmitter<DatabaseEvent> {
     constructor(tmpDir: string, db: Database, namespace?: string | null, options?: {
         readOnly?: boolean;
     });
+    /**
+     * Enables `await using accessor = ...`. Delegates to {@link close} with
+     * the default timeout — callers that need a non-default `timeoutMs`
+     * must call `close` explicitly instead of relying on disposal.
+     *
+     * Dispatches through the instance's own `close`, so an `Archive`
+     * (which overrides `close`) gets its full teardown here too — this
+     * method does not need to be re-implemented on subclasses.
+     */
+    [Symbol.asyncDispose](): Promise<void>;
     /**
      * Closes the underlying database connection.
      *
@@ -94,6 +104,13 @@ export declare class ArchiveAccessor extends EventEmitter<DatabaseEvent> {
      * @returns The parsed {@link Config} object.
      */
     getConfig(): Promise<Config>;
+    /**
+     * Retrieves the Web Components (custom elements) within the given page's
+     * detected main content region, from `page_main_content_custom_elements`.
+     * @param pageId - The database id of the page.
+     * @returns Ordered custom-element rows.
+     */
+    getCustomElementsOfPage(pageId: number): Promise<import("./meta/types.js").MainContentCustomElementRow[]>;
     /**
      * Reads custom data stored in the archive by name.
      * @param name - The base name of the data file (without extension).
@@ -199,6 +216,13 @@ export declare class ArchiveAccessor extends EventEmitter<DatabaseEvent> {
     getPagesWithRefs(limit: number, callback: (pages: Page[], currentOffset: number, max: number) => void | Promise<void>, options?: ParseURLOptions & {
         withRefs?: boolean;
     }): Promise<void>;
+    /**
+     * Retrieves the confidence-combined technology roll-up for the given
+     * page, from the `page_technologies` table.
+     * @param pageId - The database id of the page.
+     * @returns Technology rows with category, version, confidence, signalCount.
+     */
+    getPageTechnologiesOfPage(pageId: number): Promise<import("./meta/types.js").PageTechnologyRow[]>;
     /**
      * Retrieves pages that link to the specified page (incoming links).
      * @param pageId - The database ID of the target page.
@@ -218,16 +242,18 @@ export declare class ArchiveAccessor extends EventEmitter<DatabaseEvent> {
     getResources(): Promise<Resource[]>;
     /**
      * Retrieves a flat list of all resource URLs stored in the archive.
+     * @param onProgress - Forwarded to {@link Database.getResourceUrlList} —
+     *   see that method's docs.
      * @returns An array of resource URL strings.
      */
-    getResourceUrlList(): Promise<string[]>;
+    getResourceUrlList(onProgress?: (scannedUpToId: number, maxId: number) => void): Promise<string[]>;
     /**
-     * Retrieves the Wappalyzer tag entries for the given page, parsed back
-     * from the `page_tags` table.
+     * Retrieves the raw technology-detection signals for the given page,
+     * from the `technology_signals` table.
      * @param pageId - The database id of the page.
-     * @returns Ordered entries with provider, category, externalId, etc.
+     * @returns Ordered signal rows with technology, signalType, evidence, weight.
      */
-    getTagsOfPage(pageId: number): Promise<import("./meta/types.js").TagRow[]>;
+    getTechnologySignalsOfPage(pageId: number): Promise<import("./meta/types.js").TechnologySignalRow[]>;
     /**
      * Retrieves the videos within the given page's detected main content
      * region, from `page_main_content_videos`.

package/lib/archive/archive-accessor.js

@@ -1,4 +1,5 @@
 import path from 'node:path';
+import { raceWithTimeout } from '@d-zero/shared/race-with-timeout';
 import { TypedAwaitEventEmitter as EventEmitter } from '@d-zero/shared/typed-await-event-emitter';
 import { log } from './debug.js';
 import { outputJSON } from './filesystem/output-json.js';
@@ -81,6 +82,18 @@ export class ArchiveAccessor extends EventEmitter {
             void this.emit('error', e);
         });
     }
+    /**
+     * Enables `await using accessor = ...`. Delegates to {@link close} with
+     * the default timeout — callers that need a non-default `timeoutMs`
+     * must call `close` explicitly instead of relying on disposal.
+     *
+     * Dispatches through the instance's own `close`, so an `Archive`
+     * (which overrides `close`) gets its full teardown here too — this
+     * method does not need to be re-implemented on subclasses.
+     */
+    async [Symbol.asyncDispose]() {
+        await this.close();
+    }
     /**
      * Closes the underlying database connection.
      *
@@ -162,6 +175,15 @@ export class ArchiveAccessor extends EventEmitter {
     async getConfig() {
         return this.#db.getConfig();
     }
+    /**
+     * Retrieves the Web Components (custom elements) within the given page's
+     * detected main content region, from `page_main_content_custom_elements`.
+     * @param pageId - The database id of the page.
+     * @returns Ordered custom-element rows.
+     */
+    async getCustomElementsOfPage(pageId) {
+        return this.#db.getCustomElementsOfPage(pageId);
+    }
     async getData(name, format = 'json') {
         const namespace = this.#namespace || '';
         const filePath = safePath(this.#tmpDir, namespace, `${name}.${format}`);
@@ -310,6 +332,15 @@ export class ArchiveAccessor extends EventEmitter {
             times++;
         }
     }
+    /**
+     * Retrieves the confidence-combined technology roll-up for the given
+     * page, from the `page_technologies` table.
+     * @param pageId - The database id of the page.
+     * @returns Technology rows with category, version, confidence, signalCount.
+     */
+    async getPageTechnologiesOfPage(pageId) {
+        return this.#db.getPageTechnologiesOfPage(pageId);
+    }
     /**
      * Retrieves pages that link to the specified page (incoming links).
      * @param pageId - The database ID of the target page.
@@ -338,19 +369,21 @@ export class ArchiveAccessor extends EventEmitter {
     }
     /**
      * Retrieves a flat list of all resource URLs stored in the archive.
+     * @param onProgress - Forwarded to {@link Database.getResourceUrlList} —
+     *   see that method's docs.
      * @returns An array of resource URL strings.
      */
-    async getResourceUrlList() {
-        return this.#db.getResourceUrlList();
+    async getResourceUrlList(onProgress) {
+        return this.#db.getResourceUrlList(onProgress);
     }
     /**
-     * Retrieves the Wappalyzer tag entries for the given page, parsed back
-     * from the `page_tags` table.
+     * Retrieves the raw technology-detection signals for the given page,
+     * from the `technology_signals` table.
      * @param pageId - The database id of the page.
-     * @returns Ordered entries with provider, category, externalId, etc.
+     * @returns Ordered signal rows with technology, signalType, evidence, weight.
      */
-    async getTagsOfPage(pageId) {
-        return this.#db.getTagsOfPage(pageId);
+    async getTechnologySignalsOfPage(pageId) {
+        return this.#db.getTechnologySignalsOfPage(pageId);
     }
     /**
      * Retrieves the videos within the given page's detected main content
@@ -457,27 +490,16 @@ export class ArchiveAccessor extends EventEmitter {
             await this.#db.destroy();
             return;
         }
-        let timer = null;
-        const timeout = new Promise((resolve) => {
-            timer = setTimeout(() => resolve('timeout'), timeoutMs);
-        });
         // Track destroy() so we can attach an error-suppressing handler if we
         // give up waiting — otherwise a late rejection becomes an unhandled
         // promise rejection on the process.
         const destroy = this.#db.destroy().then(() => 'done');
-        try {
-            const result = await Promise.race([destroy, timeout]);
-            if (result === 'timeout') {
-                log('ArchiveAccessor.close: db.destroy() did not settle within %dms — giving up', timeoutMs);
-                destroy.catch((error) => {
-                    log('ArchiveAccessor.close: late db.destroy() rejection (post-timeout): %O', error);
-                });
-            }
-        }
-        finally {
-            if (timer) {
-                clearTimeout(timer);
-            }
+        const { timeout } = await raceWithTimeout(() => destroy, timeoutMs);
+        if (timeout) {
+            log('ArchiveAccessor.close: db.destroy() did not settle within %dms — giving up', timeoutMs);
+            destroy.catch((error) => {
+                log('ArchiveAccessor.close: late db.destroy() rejection (post-timeout): %O', error);
+            });
         }
     }
 }

package/lib/archive/archive.d.ts

@@ -19,16 +19,15 @@ import { ArchiveAccessor } from './archive-accessor.js';
  *
  * Use the static factory methods ({@link Archive.create}, {@link Archive.open},
  * {@link Archive.resume}, {@link Archive.connect}) to obtain instances.
- * The constructor is private.
+ * The constructor is private. Implements `Symbol.asyncDispose` (inherited
+ * from {@link ArchiveAccessor}) so callers can use `await using` instead of
+ * a manual `try`/`finally` around {@link close}.
  * @example
- * const archive = await Archive.create({ filePath: '/path/to/site.nitpicker' });
- * try {
- *   await archive.setConfig(config);
- *   const pageId = await archive.setPage(pageData);
- * } finally {
- *   // Writes the `.nitpicker` tar (if absent), removes tmpDir, releases the lock.
- *   await archive.close();
- * }
+ * await using archive = await Archive.create({ filePath: '/path/to/site.nitpicker' });
+ * await archive.setConfig(config);
+ * const pageId = await archive.setPage(pageData);
+ * // Writes the `.nitpicker` tar (if absent), removes tmpDir, releases the
+ * // lock — all on scope exit, whether by fallthrough or thrown error.
  */
 export default class Archive extends ArchiveAccessor {
     #private;
@@ -308,17 +307,21 @@ export default class Archive extends ArchiveAccessor {
      * internal pages on the next pass.
      * @param scopes - Hostname-indexed scope map representing the new scope.
      * @param options - URL parsing options forwarded to the scope-entry lookup.
+     * @param onProgress - Forwarded to {@link Database.repromoteExternalPages}
+     *   — see that method's docs.
      * @returns The URLs that were repromoted.
      */
-    repromoteExternalPages(scopes: ReadonlyMap<string, readonly ExURL[]>, options?: ParseURLOptions): Promise<string[]>;
+    repromoteExternalPages(scopes: ReadonlyMap<string, readonly ExURL[]>, options?: ParseURLOptions, onProgress?: (processed: number, total: number) => void): Promise<string[]>;
     /**
      * Reset previously-failed pages back to pending so a follow-up crawl re-fetches them.
      *
      * Delegates to {@link Database.resetFailedPages}. See that method for the
      * exact failure criteria (missing status / content type, or a 5xx status).
+     * @param onProgress - Forwarded to {@link Database.resetFailedPages} —
+     *   see that method's docs.
      * @returns The URLs of the pages that were reset to pending.
      */
-    resetFailedPages(): Promise<string[]>;
+    resetFailedPages(onProgress?: (processed: number, total: number) => void): Promise<string[]>;
     /**
      * Persists the raw bytes of an `--inventory` source URL list into the
      * archive's tar payload, at `inventory/<sha256>.txt`.
@@ -374,9 +377,12 @@ export default class Archive extends ArchiveAccessor {
      * pages share a single `page_html_blobs` row.
      * @param pageInfo - The page data to store.
      * @param source - Provenance label for new rows. `undefined` leaves the DB DEFAULT (`'crawled'`).
+     * @param bodyHash - Precomputed body hash for the page's HTML (see
+     *   `CrawlerEventTypes.page.bodyHash`). `undefined`/`null` falls back to
+     *   computing it from the HTML instead.
      * @returns The database ID of the stored page.
      */
-    setPage(pageInfo: PageData, source?: PageSource): Promise<number>;
+    setPage(pageInfo: PageData, source?: PageSource, bodyHash?: Buffer | null): Promise<number>;
     /**
      * Records a redirect edge without re-storing the destination's content.
      *
@@ -418,8 +424,10 @@ export default class Archive extends ArchiveAccessor {
     /**
      * Assigns natural URL sort order values to all pages in the database
      * that do not yet have an `order` field set.
+     * @param onProgress - Forwarded to {@link Database.setUrlOrder} — see that
+     *   method's docs.
      */
-    setUrlOrder(): Promise<void>;
+    setUrlOrder(onProgress?: (processed: number, total: number) => void): Promise<void>;
     /**
      * Updates a subset of fields on the archive's `info` row. Used by the append
      * flow to extend `roots` / `scope` without rewriting the entire config.
@@ -442,8 +450,26 @@ export default class Archive extends ArchiveAccessor {
      * `db.sqlite`, so a re-crawl (`append` / `inventory` / `retryFailed`)
      * opened without it would tar back a tmpDir missing those extra files,
      * silently dropping them from the rewritten archive.
-     */
-    write(): Promise<void>;
+     * @param options - Optional write settings.
+     * @param options.onTarProgress - Called as archive bytes are written
+     *   during the tar step, with the bytes written so far and the estimated
+     *   total (issue #294: tarring a large archive takes minutes, and
+     *   without this the CLI shows nothing until `write` returns). Omit for
+     *   a silent write (the default).
+     * @param options.onStep - Called once at the start of each of this
+     *   method's four steps (issue #294): `checkpoint` (WAL fold-back —
+     *   single synchronous PRAGMA, no countable progress) and `remove`
+     *   (deleting the tarred-away tmpDir) have no progress signal of their
+     *   own, so without this a large archive's write looks frozen between
+     *   the `tar` step's byte updates and completion. `rename` is nearly
+     *   instant (same-filesystem directory move) but included for
+     *   completeness — a caller displaying phase labels shouldn't have a
+     *   gap where the operation is silently between named steps.
+     */
+    write(options?: {
+        onTarProgress?: (writtenBytes: number, totalBytes: number) => void;
+        onStep?: (step: 'checkpoint' | 'rename' | 'tar' | 'remove') => void;
+    }): Promise<void>;
     /** The file extension for Nitpicker archive files (without the leading dot). */
     static FILE_EXTENSION: string;
     /** The filename of the SQLite database within the archive. */
@@ -464,27 +490,38 @@ export default class Archive extends ArchiveAccessor {
      * on the user's tmpDir.
      *
      * `options.readOnly: false` is a narrow escape hatch for opening a
-     * second, writable connection to a `tmpDir` that {@link Archive.openCached}
-     * already extracted (and migrated) into an OS-temp cache directory —
-     * never the caller's live/interrupted crawl tmpDir, which must stay
-     * read-only. A read-only open (`Archive.openCached`/`ArchiveManager.open`)
-     * must never take this path itself — blocking or writing during what
-     * must be a read-only open is forbidden (issue #177). This escape
-     * hatch has no current production caller; any future
-     * one is responsible for its own cross-process coordination (see
-     * `acquireArchiveLock`) — this method does not acquire any lock itself.
+     * second, writable connection to a `tmpDir` the caller's own process
+     * already owns and extracted itself. The one production caller is the
+     * viewer-read-model worker thread (`@nitpicker/query`'s
+     * `viewer-read-model-worker-entry.ts`, issue #294): the parent thread
+     * holds the archive via `Archive.open` (lock included — worker threads
+     * share the parent's PID, so the PID-based `acquireArchiveLock` guard
+     * stays valid), sits idle awaiting the worker, and re-tars the tmpDir
+     * afterward. What this hatch must NEVER target is a live/interrupted
+     * crawl tmpDir owned by a *different* process (the stub-mode
+     * `ArchiveManager.open` path attaches to exactly such directories, and
+     * must stay read-only): writable connects run the self-healing
+     * migrations, and mutating a directory out from under its owner is how
+     * archives corrupt. A read-only open (`Archive.openCached`/
+     * `ArchiveManager.open`) must never take this path itself — blocking or
+     * writing during what must be a read-only open is forbidden (issue
+     * #177). Any new caller is responsible for its own coordination with
+     * the tmpDir's owner (see `acquireArchiveLock` for the cross-process
+     * case) — this method does not acquire any lock itself.
      * @param tmpDir - The path to the temporary directory containing the database.
      * @param namespace - An optional namespace for scoping data access within the archive.
      * @param options - Connection options.
      * @param options.readOnly - Defaults to `true`. Pass `false` to obtain a
-     *   writable accessor against an already-extracted cache directory.
+     *   writable accessor against a tmpDir the calling process itself owns.
      * @returns An ArchiveAccessor instance for querying the archive data.
      * @example
      * // Default (read-only) — safe for stub mode and cache reads:
      * const accessor = await Archive.connect(tmpDir);
      * @example
-     * // Writable escape hatch — only against a tar-cache extraction:
-     * const writable = await Archive.connect(cacheDir, null, { readOnly: false });
+     * // Writable escape hatch — only against a tmpDir this process owns
+     * // (e.g. the viewer-read-model worker thread reconnecting to the
+     * // parent's Archive.open extraction):
+     * const writable = await Archive.connect(ownTmpDir, null, { readOnly: false });
      */
     static connect(tmpDir: string, namespace?: string | null, options?: {
         readOnly?: boolean;
@@ -522,18 +559,17 @@ export default class Archive extends ArchiveAccessor {
      * {@link Archive.open}.
      * @param filePath - Absolute path to the `.nitpicker` file.
      * @param namespace - Optional namespace forwarded to {@link ArchiveAccessor}.
+     * @param onExtractProgress - Forwarded to {@link extractArchiveToCache} —
+     *   see that function's docs for the cache-hit/miss contract.
      * @returns A read-only {@link ArchiveAccessor} backed by the cache directory.
      * @example
      * ```ts
-     * const accessor = await Archive.openCached('/path/to/site.nitpicker');
-     * try {
-     *   const summary = await getSummary(accessor);
-     * } finally {
-     *   await accessor.close(); // tears down DB handle, cacheDir persists.
-     * }
+     * await using accessor = await Archive.openCached('/path/to/site.nitpicker');
+     * const summary = await getSummary(accessor);
+     * // tears down DB handle on scope exit; cacheDir persists.
      * ```
      */
-    static openCached(filePath: string, namespace?: string | null): Promise<ArchiveAccessor>;
+    static openCached(filePath: string, namespace?: string | null, onExtractProgress?: (readBytes: number, totalBytes: number) => void): Promise<ArchiveAccessor>;
     /**
      * Creates a new archive at the specified file path.
      * Initializes a temporary working directory and a fresh SQLite database.
@@ -558,10 +594,13 @@ export default class Archive extends ArchiveAccessor {
      * Resumes an archive from an existing temporary directory
      * (e.g., after an interrupted crawl session).
      * @param targetPath - The path to the temporary directory to resume from.
+     * @param onLog - Forwarded to {@link Database.connect} — see
+     *   {@link ArchiveOpenOptions.onLog}'s docs (this writable reconnect
+     *   runs the same self-healing migrations `Archive.open` does).
      * @returns An Archive instance reconnected to the existing data.
      * @throws {Error} If the specified path is not a directory.
      */
-    static resume(targetPath: string): Promise<Archive>;
+    static resume(targetPath: string, onLog?: (message: string) => void): Promise<Archive>;
     /**
      * Generates a timestamp string in the format `YYYYMMDDHHmmssSSS`
      * suitable for use in file names.
@@ -588,8 +627,28 @@ export default class Archive extends ArchiveAccessor {
      * {@link ArchiveAccessor} (not an `Archive`), so `close()` resolves to
      * the safe base implementation — no `write()`, no `remove()`, no lock
      * release — leaving the tmpDir intact for the live crawler.
-     */
-    close(): Promise<void>;
+     * @param options - Optional close settings. `timeoutMs` is accepted for
+     *   compatibility with {@link ArchiveAccessor.close}'s signature (forwarded
+     *   to the base `super.close()` call below); the rest are progress
+     *   callbacks (issue #294) forwarded to {@link write} when this call ends
+     *   up taking the recovery-write branch (the archive file doesn't exist
+     *   yet).
+     * @param options.timeoutMs - See {@link ArchiveAccessor.close}.
+     * @param options.onRecoveryStart - Called once, only when this `close()`
+     *   is about to write the archive because the file doesn't exist on
+     *   disk yet — e.g. a caller's own explicit `write()` threw before
+     *   finishing, or was never called at all. Without this, a listener
+     *   that already tore down its display after that earlier failure has
+     *   no way to know a second, recovery write is happening.
+     * @param options.onTarProgress - See {@link write}.
+     * @param options.onStep - See {@link write}.
+     */
+    close(options?: {
+        timeoutMs?: number;
+        onRecoveryStart?: () => void;
+        onTarProgress?: (writtenBytes: number, totalBytes: number) => void;
+        onStep?: (step: 'checkpoint' | 'rename' | 'tar' | 'remove') => void;
+    }): Promise<void>;
     /**
      * Retrieves the crawl configuration stored in the archive database.
      * @returns The configuration object.
@@ -623,5 +682,24 @@ type ArchiveOpenOptions = {
      * dropping them from the rewritten archive.
      */
     openPluginData?: boolean;
+    /**
+     * Called as archive bytes are consumed during the initial tar
+     * extraction, with the bytes read so far and the archive's total size
+     * (issue #294: a large archive takes minutes to extract, and without
+     * this the CLI shows nothing at all until `open` returns). Byte
+     * granularity is the read-stream chunk size — throttle in the callback
+     * for coarser display updates. Omit for a silent extraction (the
+     * default).
+     */
+    onExtractProgress?: (readBytes: number, totalBytes: number) => void;
+    /**
+     * Called instead of `console.error` for self-healing schema migration
+     * notices that fire while opening a legacy archive (issue #294) —
+     * forwarded to {@link Database.connect}'s `onLog`. Without this, a
+     * migration notice can print mid-redraw of a caller's `Lanes`/`TaskList`
+     * display, corrupting its cursor tracking. Omit to fall back to
+     * `console.error` (the pre-#294 behavior).
+     */
+    onLog?: (message: string) => void;
 };
 export {};