@nitpicker/archive 0.0.0 → 0.25.1

package/lib/database.d.ts

@@ -0,0 +1,549 @@
+import type { TemplateClusterReason } from './db-ops/templates/types.js';
+import type { OutageWindow } from './is-within-outage-window.js';
+import type { JsonLdRow, MainContentAudioRow, MainContentButtonRow, MainContentCanvasRow, MainContentCustomElementRow, MainContentHeadingRow, MainContentIframeRow, MainContentImageRow, MainContentTableRow, MainContentVideoRow, PageTechnologyRow, TechnologySignalRow } from './meta/types.js';
+import type { Config, DatabaseOption, DB_Redirect, DB_Resource, DatabaseEvent, DedupeCapObservationRow, InsertDedupeCapEventParams, InsertNetworkOutageParams, ListReconcileRunMeta, PageFilter, PageSource, ResetPagesByUrlsResult } from './types.js';
+import type { PageData, Resource, ConsoleLogEntry } from './utils/types/types.js';
+import type { ExURL, ParseURLOptions } from '@d-zero/shared/parse-url';
+import type { Knex } from 'knex';
+import { TypedAwaitEventEmitter as EventEmitter } from '@d-zero/shared/typed-await-event-emitter';
+/**
+ * Low-level database abstraction layer for the archive's SQLite database.
+ *
+ * Every method is a thin dispatcher: the SQL itself lives in a dedicated
+ * single-export op module under `./db-ops/` (one file per operation), and
+ * the class contributes only the connection (`this.#instance`) plus the
+ * error/retry wrapper. Public methods that perform database queries use the
+ * `emitErrorAndRetry` HOF for automatic retry on transient failures combined
+ * with error-event propagation, or `emitError` when retry is not appropriate.
+ * The set of tables this layer manages is defined by `init-schema.ts` (the
+ * source of truth — query that file for the canonical list).
+ *
+ * **Label sync caveat**: each `emitError` / `emitErrorAndRetry` call passes
+ * the method name as a string literal (e.g. `'Database.getAnchorsOnPage'`).
+ * TypeScript cannot check that the string matches the enclosing method's
+ * real name — the two-way sync is manual. Renaming a method here **must**
+ * update the literal string too, otherwise debug logs and `RetryTimeoutError`
+ * messages will silently report the old name.
+ *
+ * Use the static {@link Database.connect} factory method to create instances.
+ * The constructor is private.
+ */
+export declare class Database extends EventEmitter<DatabaseEvent> {
+    #private;
+    private constructor();
+    /**
+     * Adds onto the `rejected_count` of a shape's `dedupe_cap_events` row,
+     * looked up by `shape_key` rather than `id`. Delegates to
+     * {@link accumulateDedupeCapRejectedCountOp}.
+     * @param shapeKey - The capped shape whose rejection count to accumulate.
+     * @param rejectedCount - Additional anchors rejected for this shape in the current session.
+     */
+    accumulateDedupeCapRejectedCount(shapeKey: string, rejectedCount: number): Promise<void>;
+    /**
+     * Forces a WAL checkpoint, writing all pending WAL data back to the main
+     * database file. Delegates to {@link checkpointOp}.
+     */
+    checkpoint(): Promise<void>;
+    /**
+     * Closes an outage row by stamping `ended_at` — a no-op if the row is
+     * already closed. Delegates to {@link closeNetworkOutageOp}.
+     * @param id - The `network_outages.id` to close.
+     * @param endedAt - Epoch ms the outage is considered to have ended.
+     */
+    closeNetworkOutage(id: number, endedAt: number): Promise<void>;
+    /**
+     * Destroys the database connection, releasing all pooled resources.
+     * Delegates to {@link destroyOp}.
+     */
+    destroy(): Promise<void>;
+    /**
+     * Finalizes a `dedupe_cap_events` row by stamping `rejected_count` — a
+     * no-op if the row is already finalized. Delegates to
+     * {@link finalizeDedupeCapEventOp}.
+     * @param id - The `dedupe_cap_events.id` to finalize.
+     * @param rejectedCount - Number of anchors rejected for this shape after it capped.
+     */
+    finalizeDedupeCapEvent(id: number, rejectedCount: number): Promise<void>;
+    /**
+     * Retrieves all anchors (outgoing links) on a specific page.
+     * Delegates to {@link getAnchorsOnPageOp}.
+     * @param pageId - The database ID of the page whose anchors to retrieve.
+     * @returns An array of anchor records with resolved URL, title, status, and content type.
+     */
+    getAnchorsOnPage(pageId: number): Promise<any[]>;
+    /**
+     * Retrieves all `page_main_content_audios` rows for the given page id.
+     * Delegates to {@link getAudiosOfPageOp}.
+     * @param pageId
+     */
+    getAudiosOfPage(pageId: number): Promise<MainContentAudioRow[]>;
+    /**
+     * Retrieves the base URL of the crawl session from the `info` table.
+     * Delegates to {@link getBaseUrlOp}.
+     * @returns The base URL string.
+     * @throws {Error} If no base URL is found in the database.
+     */
+    getBaseUrl(): Promise<string>;
+    /**
+     * Retrieves all `page_main_content_buttons` rows for the given page id.
+     * Delegates to {@link getButtonsOfPageOp}.
+     * @param pageId
+     */
+    getButtonsOfPage(pageId: number): Promise<MainContentButtonRow[]>;
+    /**
+     * Retrieves all `page_main_content_canvases` rows for the given page id.
+     * Delegates to {@link getCanvasesOfPageOp}.
+     * @param pageId
+     */
+    getCanvasesOfPage(pageId: number): Promise<MainContentCanvasRow[]>;
+    /**
+     * Retrieves the full crawl configuration from the `info` table.
+     * Delegates to {@link getConfigOp}.
+     * @returns The parsed {@link Config} object.
+     * @throws {Error} If no configuration is found in the database.
+     */
+    getConfig(): Promise<Config>;
+    /**
+     * Retrieves the current crawling state by listing scraped and pending URLs.
+     * Delegates to {@link getCrawlingStateOp} — see the op for the strict
+     * pending-set rationale.
+     * @returns An object with `scraped` (completed URLs), `pending` (the
+     *   strict set of in-scope, anchor-referenced, unfinished URLs), and
+     *   `pendingMetadataOnly` (the subset of `pending` fated for a
+     *   metadata-only scrape — see the op's doc).
+     */
+    getCrawlingState(): Promise<{
+        scraped: string[];
+        pending: string[];
+        pendingMetadataOnly: string[];
+    }>;
+    /**
+     * Retrieves the `info.createdCwd` value stamped at stub-creation time.
+     * Delegates to {@link getCreatedCwdOp}.
+     * @returns The recorded cwd, or `null` if never stamped.
+     */
+    getCreatedCwd(): Promise<string | null>;
+    /**
+     * Retrieves all `page_main_content_custom_elements` rows for the given
+     * page id. Delegates to {@link getCustomElementsOfPageOp}.
+     * @param pageId
+     */
+    getCustomElementsOfPage(pageId: number): Promise<MainContentCustomElementRow[]>;
+    /**
+     * Return the subset of `urls` that already exist in the `pages` table.
+     * Delegates to {@link getExistingPageUrlsOp}.
+     * @param urls - URL strings to probe (already in `withoutHashAndAuth` form).
+     * @returns URLs found in `pages`. Order is not preserved.
+     */
+    getExistingPageUrls(urls: readonly string[]): Promise<string[]>;
+    /**
+     * Return the subset of `urls` that already exist in the `resources` table.
+     * Delegates to {@link getExistingResourceUrlsOp}.
+     * @param urls - URL strings to probe.
+     * @returns URLs found in `resources`.
+     */
+    getExistingResourceUrls(urls: readonly string[]): Promise<string[]>;
+    /**
+     * Retrieves all `page_main_content_headings` rows for the given page id.
+     * Delegates to {@link getHeadingsOfPageOp}.
+     * @param pageId
+     */
+    getHeadingsOfPage(pageId: number): Promise<MainContentHeadingRow[]>;
+    /**
+     * Reads the HTML snapshot stored as a zstd-compressed BLOB for the given page.
+     * Reads the row through {@link readPageHtmlBlobOp} with retries, then
+     * decodes it once: a decode failure is in the stored bytes and would only
+     * repeat, so it is not retried.
+     * @param pageId - The database ID of the page.
+     * @returns The decompressed HTML string, or `null` if no snapshot is stored.
+     * @throws {Error} `HTML snapshot of page <id> (page_html_blobs hash <hex>) could not be decoded: …`
+     *   when the snapshot is corrupt or decompresses past `MAX_DECODED_SNAPSHOT_BYTES`
+     *   (also emitted as an `'error'` event).
+     */
+    getHtmlOfPageById(pageId: number): Promise<string | null>;
+    /**
+     * Retrieves all `page_main_content_iframes` rows for the given page id.
+     * Delegates to {@link getIframesOfPageOp}.
+     * @param pageId
+     */
+    getIframesOfPage(pageId: number): Promise<MainContentIframeRow[]>;
+    /**
+     * Retrieves all `page_jsonld` rows for the given page id, parsed back into
+     * {@link JsonLdRow} shape. Delegates to {@link getJsonLdOfPageOp}.
+     * @param pageId
+     */
+    getJsonLdOfPage(pageId: number): Promise<JsonLdRow[]>;
+    /**
+     * Returns the underlying Knex query builder instance for direct SQL access.
+     * This enables advanced queries (GROUP BY, HAVING, JOINs) at the database
+     * layer for performance with large datasets.
+     * @returns The Knex instance connected to the SQLite database.
+     */
+    getKnex(): Knex;
+    /**
+     * Retrieves all `page_main_content_images` rows for the given page id.
+     * Delegates to {@link getMainContentImagesOfPageOp}.
+     * @param pageId
+     */
+    getMainContentImagesOfPage(pageId: number): Promise<MainContentImageRow[]>;
+    /**
+     * Retrieves all `page_main_content_tables` rows for the given page id.
+     * Delegates to {@link getMainContentTablesOfPageOp}.
+     * @param pageId
+     */
+    getMainContentTablesOfPage(pageId: number): Promise<MainContentTableRow[]>;
+    /**
+     * Retrieves the crawl session name from the `info` table.
+     * Delegates to {@link getNameOp}.
+     * @returns The name string.
+     * @throws {Error} If no name is found in the database.
+     */
+    getName(): Promise<string>;
+    /**
+     * Counts the total number of pages in the database.
+     * Delegates to {@link getPageCountOp}.
+     * @returns The total page count.
+     * @throws {Error} If the count query fails.
+     */
+    getPageCount(): Promise<number>;
+    /**
+     * Retrieves pages from the database with optional filtering, pagination via
+     * offset and limit. Delegates to {@link getPagesOp}.
+     * @param filter - An optional {@link PageFilter} to narrow results by content type and origin.
+     * @param offset - The number of rows to skip. Defaults to `0`.
+     * @param limit - The maximum number of rows to return. Defaults to `100000`.
+     * @returns An array of raw `DB_Page` rows.
+     */
+    getPages(filter?: PageFilter, offset?: number, limit?: number): Promise<import("./types.js").DB_Page[]>;
+    /**
+     * Look up the `source` column of a single page by its URL key.
+     * Delegates to {@link getPageSourceByUrlOp}.
+     * @param url - URL key in `url.withoutHashAndAuth` form.
+     * @returns The recorded `source`, or `undefined` when no row exists.
+     */
+    getPageSourceByUrl(url: string): Promise<PageSource | undefined>;
+    /**
+     * Retrieves pages along with their related redirect, anchor, and referrer data.
+     * Results are ordered by the natural URL sort order. Only non-redirected pages
+     * are returned. Delegates to {@link getPagesWithRelsOp}.
+     * @param offset - The number of rows to skip.
+     * @param limit - The maximum number of pages to return.
+     * @returns An object containing `pages`, `redirects`, `anchors`, and `referrers` arrays.
+     */
+    getPagesWithRels(offset: number, limit: number): Promise<{
+        pages: import("./types.js").DB_Page[];
+        redirects: DB_Redirect[];
+        anchors: import("./types.js").DB_Anchor[];
+        referrers: import("./types.js").DB_Referrer[];
+    }>;
+    /**
+     * Retrieves all `page_technologies` rows for the given page id.
+     * Delegates to {@link getPageTechnologiesOfPageOp}.
+     * @param pageId
+     */
+    getPageTechnologiesOfPage(pageId: number): Promise<PageTechnologyRow[]>;
+    /**
+     * Retrieves redirect sources for the given page IDs in bulk.
+     * Delegates to {@link getRedirectsForPagesOp}.
+     * @param pageIds - The database IDs of the destination pages.
+     * @returns An array of {@link DB_Redirect} records mapping destination pages to their redirect sources.
+     */
+    getRedirectsForPages(pageIds: number[]): Promise<DB_Redirect[]>;
+    /**
+     * Retrieves pages that link to a specific page (incoming links / referrers),
+     * resolved through redirects. Delegates to {@link getReferrersOfPageOp}.
+     * @param pageId - The database ID of the target page.
+     * @returns An array of referrer records with URL, hash, and text content.
+     */
+    getReferrersOfPage(pageId: number): Promise<any[]>;
+    /**
+     * Retrieves the page URLs that reference a specific resource.
+     * Delegates to {@link getReferrersOfResourceOp}.
+     * @param id - The database ID of the resource.
+     * @returns An array of page URL strings that reference the resource.
+     */
+    getReferrersOfResource(id: number): Promise<string[]>;
+    /**
+     * Retrieves a single sub-resource from the `resources` table by its URL.
+     * Delegates to {@link getResourceByUrlOp}.
+     *
+     * Deliberately NOT wrapped with `emitError`/`emitErrorAndRetry`: the only caller (the
+     * crawler's resource-reuse hook) has a full fallback (the HEAD pre-flight),
+     * so a read failure here must not surface as a database `error` event —
+     * the orchestrator aborts the whole crawl on that event, which is the
+     * correct reaction to write failures but not to a recoverable read.
+     * @param urls - URL candidates to match against the `url` column.
+     * @returns The raw {@link DB_Resource} row, or `null` if none match.
+     */
+    getResourceByUrl(urls: readonly string[]): Promise<DB_Resource | null>;
+    /**
+     * Retrieves all sub-resources from the `resources` table.
+     * Delegates to {@link getResourcesOp}.
+     * @returns An array of raw {@link DB_Resource} rows.
+     */
+    getResources(): Promise<DB_Resource[]>;
+    /**
+     * Retrieves a flat list of all resource URLs from the `resources` table.
+     * Delegates to {@link getResourceUrlListOp}.
+     *
+     * `onProgress` is clamped to a high-water mark across retries: a
+     * transient failure partway through the keyset scan restarts
+     * {@link getResourceUrlListOp} from `id = 0` (its own `lastId` is a local
+     * closure variable, reset on every `fn` invocation `retryCall` retries),
+     * which would otherwise visibly rewind the reported progress backwards
+     * before catching back up.
+     * @param onProgress - Forwarded to {@link getResourceUrlListOp} — see
+     *   that function's docs.
+     * @returns An array of resource URL strings.
+     */
+    getResourceUrlList(onProgress?: (scannedUpToId: number, maxId: number) => void): Promise<string[]>;
+    /**
+     * Counts pages that were scraped as crawl targets (full HTML render).
+     * Delegates to {@link getScrapedHtmlPageCountOp}.
+     * @returns The number of `text/html` rows with `isTarget = 1` and `scraped = 1`.
+     */
+    getScrapedHtmlPageCount(): Promise<number>;
+    /**
+     * Retrieves all `technology_signals` rows for the given page id.
+     * Delegates to {@link getTechnologySignalsOfPageOp}.
+     * @param pageId
+     */
+    getTechnologySignalsOfPage(pageId: number): Promise<TechnologySignalRow[]>;
+    /**
+     * Retrieves all `page_main_content_videos` rows for the given page id.
+     * Delegates to {@link getVideosOfPageOp}.
+     * @param pageId
+     */
+    getVideosOfPage(pageId: number): Promise<MainContentVideoRow[]>;
+    /**
+     * Records a crawler-level (`error` channel) failure into `crawl_errors`.
+     * Delegates to {@link insertCrawlErrorOp}.
+     * @param url - The URL the error is about, or `null` for a process-level error.
+     * @param message - The error message (one line is enough for classification).
+     * @param isExternal - Whether the URL is external to the crawl scope.
+     */
+    insertCrawlError(url: string | null, message: string, isExternal?: boolean): Promise<void>;
+    /**
+     * Appends one row (`rejected_count = NULL`) to the `dedupe_cap_events`
+     * journal. Delegates to {@link insertDedupeCapEventOp}.
+     * @param params - The newly-capped shape's fields to record.
+     * @returns The autoincremented `id` of the newly-inserted row.
+     */
+    insertDedupeCapEvent(params: InsertDedupeCapEventParams): Promise<number>;
+    /**
+     * Pre-insert inventory non-HTML URLs into `resources` as placeholder rows.
+     * Delegates to {@link insertInventoryResourcesOp}.
+     * @param urls - URL strings (already in `withoutHashAndAuth` form).
+     */
+    insertInventoryResources(urls: readonly string[]): Promise<void>;
+    /**
+     * Pre-insert inventory HTML seeds into `pages` as `scraped = 0`,
+     * `source = 'inventory-seed'` placeholders. Delegates to
+     * {@link insertInventorySeedsOp} — see the op for the Ctrl+C tolerance
+     * rationale.
+     * @param urls - URL strings already in `withoutHashAndAuth` form.
+     */
+    insertInventorySeeds(urls: readonly string[]): Promise<void>;
+    /**
+     * Records exclude-matched inventory URLs as terminal skipped pages
+     * (`scraped=1`, `is_skipped=1`, `skip_reason='excluded'`,
+     * `source='inventory-seed'`). Delegates to
+     * {@link insertInventorySkippedPagesOp} — see that op's JSDoc for the
+     * normal-crawl parity rationale.
+     * @param urls - URL strings already in `withoutHashAndAuth` form.
+     */
+    insertInventorySkippedPages(urls: readonly string[]): Promise<void>;
+    /**
+     * Appends one open (`ended_at = NULL`) row to the `network_outages`
+     * journal. Delegates to {@link insertNetworkOutageOp}.
+     * @param params - The confirmed-outage fields to record.
+     * @returns The autoincremented `id` of the newly-inserted row.
+     */
+    insertNetworkOutage(params: InsertNetworkOutageParams): Promise<number>;
+    /**
+     * Records a partial scrape failure against the page identified by `url`.
+     * Delegates to {@link insertPageErrorOp}.
+     * @param url - URL of the page being scraped.
+     * @param phase - Scrape phase name (typically `'retryExhausted'`).
+     * @param message - Human-readable failure message.
+     * @param isExternal - Whether the URL is external. Defaults to `false`.
+     */
+    insertPageError(url: string, phase: string, message: string, isExternal?: boolean): Promise<void>;
+    /**
+     * Inserts a sub-resource into the `resources` table.
+     * Delegates to {@link insertResourceOp}.
+     * @param resource - The resource data to insert.
+     * @param source - Provenance label for new rows. `undefined` leaves the DB DEFAULT (`'crawled'`).
+     */
+    insertResource(resource: Resource, source?: PageSource): Promise<void>;
+    /**
+     * Inserts a referrer relationship between a resource and a page into the
+     * `resources-referrers` table. Delegates to {@link insertResourceReferrersOp}.
+     * @param src - The URL of the resource.
+     * @param pageUrl - The URL of the page that references the resource.
+     */
+    insertResourceReferrers(src: string, pageUrl: string): Promise<void>;
+    /**
+     * Every previously-scraped internal page's raw fields, in the shape
+     * `buildDedupeCapObservation` needs to replay this archive's prior
+     * `DedupeCapTracker` observations into a fresh tracker instance.
+     * Delegates to {@link listDedupeCapObservationsOp} — see that function
+     * for the row selection criteria.
+     * @param onProgress - Forwarded to {@link listDedupeCapObservationsOp} —
+     *   see that function's docs.
+     * @returns Every qualifying page's raw fields, in `content_items.id` order.
+     */
+    listDedupeCapObservations(onProgress?: (scannedUpToId: number, maxId: number) => void): Promise<DedupeCapObservationRow[]>;
+    /**
+     * Every distinct `dedupe_cap_events.shape_key` recorded in this archive.
+     * Delegates to {@link listDedupeCapShapeKeysOp}.
+     * @returns Distinct shape keys already confirmed capped, or `[]` on an
+     *   archive that predates `dedupe_cap_events` or has recorded none.
+     */
+    listDedupeCapShapeKeys(): Promise<string[]>;
+    /**
+     * Hostnames whose `crawl_errors` history is consistently DNS failures and
+     * for which no recent 2xx-3xx page or resource is recorded.
+     * Delegates to {@link listDnsBurnedHostCandidatesOp}.
+     * @returns Lower-cased hostnames safe to short-circuit.
+     */
+    listDnsBurnedHostCandidates(): Promise<string[]>;
+    /**
+     * Lists every recorded outage as a resolved {@link OutageWindow}.
+     * Delegates to {@link listNetworkOutagesOp}.
+     * @returns Resolved outage windows, or `[]` on an archive that predates
+     *   `network_outages` or has recorded no outages.
+     */
+    listNetworkOutages(): Promise<OutageWindow[]>;
+    /**
+     * Appends one row to the `list_reconcile_runs` audit log.
+     * Delegates to {@link recordListReconcileRunOp}.
+     * @param meta - The run metadata to record. Only `ran_at` is required.
+     * @returns The autoincremented `id` of the newly-inserted row.
+     */
+    recordListReconcileRun(meta: ListReconcileRunMeta): Promise<number>;
+    /**
+     * Records a redirect edge (source → destination) **without** re-storing the
+     * destination's content. Delegates to {@link recordRedirectOp}.
+     * @param page - HEAD-resolved page data carrying the redirect chain. Its
+     *   `anchorList` / `imageList` are ignored (a redirect source owns no content).
+     * @param source - Inventory provenance forwarded by the orchestrator for
+     *   the redirect-edge fast path. `undefined` keeps the DB DEFAULT
+     *   `'crawled'` on a brand-new destination row.
+     */
+    recordRedirect(page: PageData, source?: PageSource): Promise<void>;
+    /**
+     * Replaces one page's `page_console_logs` rows with a freshly captured
+     * set of console messages / page errors. Delegates to
+     * {@link replaceConsoleLogsOp}.
+     * @param pageUrl - The originally-requested URL, normalised (`withoutHashAndAuth` form).
+     * @param redirectPaths - The redirect chain hops captured during fetch, in order.
+     * @param entries - The console log entries to persist.
+     */
+    replaceConsoleLogs(pageUrl: string, redirectPaths: readonly string[], entries: readonly ConsoleLogEntry[]): Promise<void>;
+    /**
+     * Replaces the stored DOM-structure template classification with a
+     * freshly generated set. Delegates to {@link replacePageTemplatesOp}.
+     * @param templateKeysByUrl - Page URL → template key.
+     * @param clusterReasonsByTemplateKey - Template key → cluster-selection
+     *   evidence, if the caller captured it.
+     */
+    replacePageTemplates(templateKeysByUrl: ReadonlyMap<string, string>, clusterReasonsByTemplateKey?: ReadonlyMap<string, TemplateClusterReason>): Promise<void>;
+    /**
+     * Promote previously-external pages whose URL falls under any of the new
+     * scope entries back to a "needs scraping" state.
+     * Delegates to {@link repromoteExternalPagesOp}.
+     * @param scopes - The hostname-indexed scope map after the new roots are merged.
+     * @param options - URL parsing options forwarded to the scope matcher.
+     * @param onProgress - Forwarded to {@link repromoteExternalPagesOp} — see
+     *   that function's docs.
+     * @returns The URLs of the pages that were promoted.
+     */
+    repromoteExternalPages(scopes: ReadonlyMap<string, readonly ExURL[]>, options?: ParseURLOptions, onProgress?: (processed: number, total: number) => void): Promise<string[]>;
+    /**
+     * Reset previously-attempted pages that ended in a recoverable failure so a
+     * follow-up crawl can re-fetch them from scratch. Delegates to
+     * {@link resetFailedPagesOp} — see the op for the permanent-failure
+     * exclusion rationale.
+     * @param onProgress - Forwarded to {@link resetFailedPagesOp} — see that
+     *   function's docs.
+     * @returns The URLs of the pages that were reset to pending.
+     */
+    resetFailedPages(onProgress?: (processed: number, total: number) => void): Promise<string[]>;
+    /**
+     * Reset pages matching an operator-supplied URL list back to pending so a
+     * follow-up crawl re-fetches them from scratch. Delegates to
+     * {@link resetPagesByUrlsOp} — see the op for the conservative exclusion
+     * rationale (redirect sources / intentionally-skipped / external pages).
+     * @param urls - URL strings to match, already in `withoutHashAndAuth` form.
+     * @param onProgress - Forwarded to {@link resetPagesByUrlsOp} — see that
+     *   function's docs.
+     * @returns The reset URLs plus the excluded URLs grouped by reason.
+     */
+    resetPagesByUrls(urls: readonly string[], onProgress?: (processed: number, total: number) => void): Promise<ResetPagesByUrlsResult>;
+    /**
+     * Stores the crawl configuration in the `info` table.
+     * Delegates to {@link setConfigOp}.
+     * @param config - The {@link Config} object to store.
+     */
+    setConfig(config: Config): Promise<number[]>;
+    /**
+     * Marks a page as skipped in the database with the given reason.
+     * Delegates to {@link setSkippedPageOp}.
+     * @param url - The URL of the skipped page.
+     * @param reason - The reason the page was skipped.
+     * @param isExternal - Whether the page is on an external domain. Defaults to `false`.
+     */
+    setSkippedPage(url: string, reason: string, isExternal?: boolean): Promise<void>;
+    /**
+     * Assigns natural URL sort order values to all internal pages.
+     * Delegates to {@link setUrlOrderOp}.
+     * @param onProgress - Forwarded to {@link setUrlOrderOp} — see that
+     *   function's docs.
+     */
+    setUrlOrder(onProgress?: (processed: number, total: number) => void): Promise<void>;
+    /**
+     * Update the single row in the `info` table with a partial config patch.
+     * Delegates to {@link updateConfigOp}.
+     * @param patch - Partial {@link Config} fields to overwrite. `undefined` values are skipped.
+     */
+    updateConfig(patch: Partial<Config>): Promise<void>;
+    /**
+     * Inserts or updates a crawled page in the database, including its redirect
+     * chain, anchors, images, and (when `writeHtml`) its compressed HTML
+     * snapshot BLOB. Delegates to {@link updatePageOp}.
+     * @param page - The page data to store.
+     * @param writeHtml - When `true`, this call is allowed to insert (or clear)
+     *   the page's HTML blob. `setExternalPage` passes `false` because external
+     *   metadata-only scrapes never carry HTML and must not perturb an already
+     *   stored body.
+     * @param isTarget - Whether this page is a crawl target.
+     * @param source - Provenance label written ONLY when the row is freshly
+     *   inserted. Existing rows keep their original `source`.
+     * @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.
+     * @param recursive - See {@link updatePageOp}'s `recursive` doc.
+     * @returns The database `pageId` of the inserted/updated row.
+     */
+    updatePage(page: PageData, writeHtml: boolean, isTarget: boolean, source?: PageSource, bodyHash?: Buffer | null, recursive?: boolean): Promise<number>;
+    /**
+     * Creates and initializes a new Database instance.
+     *
+     * **Writer mode (default)**: creates the parent directory for the
+     * database file if needed, establishes the connection, and initializes
+     * the schema + migrations.
+     *
+     * **Read-only mode** (`options.readOnly`): refuses to resurrect a
+     * missing parent directory or db file — throws if either is absent at
+     * the time of the call. Skips schema init and migrations entirely so
+     * the user's tmpDir is never modified. Required by viewer / MCP
+     * stub-mode opens, where a TOCTOU window between classification and
+     * `connect()` could otherwise leave behind a phantom empty tmpDir.
+     * @param options - Database connection options.
+     * @returns A fully initialized Database instance.
+     * @throws {Error} In read-only mode, if the parent directory or db
+     *   file does not exist when `connect()` runs.
+     */
+    static connect(options: DatabaseOption): Promise<Database>;
+}