@nitpicker/crawler 0.11.0 → 0.13.0

package/lib/archive/database.d.ts

@@ -1,5 +1,5 @@
 import type { JsonLdRow, TagRow } from './meta/types.js';
-import type { Config, DatabaseOption, DB_Anchor, DB_Page, DB_Redirect, DB_Referrer, DB_Resource, DatabaseEvent, PageFilter, PageSource } from './types.js';
+import type { Config, DatabaseOption, DB_Redirect, DB_Resource, DatabaseEvent, InventoryRunMeta, PageFilter, PageSource } from './types.js';
 import type { PageData, Resource } from '../utils/types/types.js';
 import type { ExURL, ParseURLOptions } from '@d-zero/shared/parse-url';
 import type { Knex } from 'knex';
@@ -7,11 +7,21 @@ import { TypedAwaitEventEmitter as EventEmitter } from '@d-zero/shared/typed-awa
 /**
  * Low-level database abstraction layer for the archive's SQLite database.
  *
- * Public methods that perform database queries use the `@retryable`
- * decorator for automatic retry on transient failures, and `@ErrorEmitter`
- * to propagate errors as events. The set of tables this layer manages is
- * defined by `init-schema.ts` (the source of truth — query that file for
- * the canonical list).
+ * 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.
@@ -20,45 +30,42 @@ export declare class Database extends EventEmitter<DatabaseEvent> {
     #private;
     private constructor();
     /**
-     * Adds the `order` column to the `pages` table for URL sort ordering.
-     * If the column already exists, this method does nothing.
-     * @deprecated Since v0.1.x. The column is now created during table initialization.
-     * @returns The result of the schema alteration, or void if the column already exists.
-     */
-    addOrderField(): Promise<void>;
-    /**
-     * Forces a WAL checkpoint, writing all pending WAL data back to the main database file.
-     * Uses TRUNCATE mode to reset the WAL file to zero bytes after checkpointing.
-     * This ensures the database is fully self-contained in `db.sqlite` before archiving.
+     * Forces a WAL checkpoint, writing all pending WAL data back to the main
+     * database file. Delegates to {@link checkpointOp}.
      */
     checkpoint(): Promise<void>;
     /**
      * Destroys the database connection, releasing all pooled resources.
+     * Delegates to {@link destroyOp}.
      */
     destroy(): Promise<void>;
     /**
      * Retrieves all anchors (outgoing links) on a specific page.
-     * Joins the `anchors` table with the `pages` table to resolve link destinations.
+     * 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 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<any>;
+    getBaseUrl(): Promise<string>;
     /**
      * Retrieves the full crawl configuration from the `info` table.
-     * Deserializes JSON-encoded fields (`roots`, `excludes`, `excludeKeywords`, `excludeUrls`).
+     * 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.
-     * @returns An object with `scraped` (completed URLs) and `pending` (remaining URLs) arrays.
+     * Delegates to {@link getCrawlingStateOp} — see the op for the strict
+     * pending-set rationale.
+     * @returns An object with `scraped` (completed URLs) and `pending` (the
+     *   strict set of in-scope, anchor-referenced, unfinished URLs).
      */
     getCrawlingState(): Promise<{
         scraped: string[];
@@ -66,47 +73,28 @@ export declare class Database extends EventEmitter<DatabaseEvent> {
     }>;
     /**
      * Return the subset of `urls` that already exist in the `pages` table.
-     * Chunked into batches so SQLite's `IN (?, ?, …)` parameter limit
-     * (`SQLITE_MAX_VARIABLE_NUMBER`, default 999) cannot be hit even when the
-     * inventory list contains tens of thousands of URLs.
-     *
-     * Read-only — no transaction, no lock contention with the crawler write
-     * pipeline (callers run this BEFORE the `<archive>.bak` is taken and the
-     * crawl is started).
+     * 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.
-     * See {@link Database.getExistingPageUrls} — same chunking strategy.
+     * Delegates to {@link getExistingResourceUrlsOp}.
      * @param urls - URL strings to probe.
      * @returns URLs found in `resources`.
      */
     getExistingResourceUrls(urls: readonly string[]): Promise<string[]>;
     /**
      * Reads the HTML snapshot stored as a zstd-compressed BLOB for the given page.
-     *
-     * Joins `page_html_ref` → `page_html_blobs` and decompresses inline. Returns
-     * `null` when the page has no stored body (a non-HTML resource, a redirect
-     * source, a degraded render). Read works identically on read-only / stub
-     * connections — the special-cased "do we have a loose dir vs zip?" branching
-     * the previous file-backed layout required is gone.
-     *
-     * Tables `page_html_ref` and `page_html_blobs` are created by `initSchema`.
-     * Older `.nitpicker` archives that predate this migration must be passed
-     * through `scripts/migrate-to-0.10.mjs` before they can be read.
+     * Delegates to {@link getHtmlOfPageByIdOp}.
      * @param pageId - The database ID of the page.
      * @returns The decompressed HTML string, or `null` if no snapshot is stored.
      */
     getHtmlOfPageById(pageId: number): Promise<string | null>;
     /**
      * Retrieves all `page_jsonld` rows for the given page id, parsed back into
-     * {@link JsonLdRow} shape (with `parsed` deserialised from its JSON column).
-     *
-     * Read-side counterpart to `#insertJsonLd`. Returns rows in insertion order
-     * by `id` so the order observed by `get-page-jsonld` matches the order the
-     * scraper saw them.
+     * {@link JsonLdRow} shape. Delegates to {@link getJsonLdOfPageOp}.
      * @param pageId
      */
     getJsonLdOfPage(pageId: number): Promise<JsonLdRow[]>;
@@ -119,71 +107,74 @@ export declare class Database extends EventEmitter<DatabaseEvent> {
     getKnex(): Knex;
     /**
      * 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<any>;
+    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.
+     * 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 {@link DB_Page} rows.
+     * @returns An array of raw `DB_Page` rows.
      */
-    getPages(filter?: PageFilter, offset?: number, limit?: number): Promise<DB_Page[]>;
+    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.
+     * 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: DB_Page[];
+        pages: import("./types.js").DB_Page[];
         redirects: DB_Redirect[];
-        anchors: DB_Anchor[];
-        referrers: DB_Referrer[];
+        anchors: import("./types.js").DB_Anchor[];
+        referrers: import("./types.js").DB_Referrer[];
     }>;
     /**
      * 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).
-     *
-     * Incoming links are resolved **through redirects**: an anchor pointing at a
-     * redirect source (e.g. `http://x` that 301s to `https://x`) counts as a
-     * referrer of the redirect's final destination, not of the source. This keeps
-     * backlinks merged on the canonical page instead of splitting them across the
-     * `http`/`https` (or any redirect source/dest) pair. The resolution mirrors
-     * `redirectTable()` — `redirectDestId` is pre-flattened to the final
-     * destination, so `COALESCE(target.redirectDestId, target.id)` is a single hop.
+     * 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}.
      *
-     * Accepts multiple URL candidates because the stored key is the resource's
-     * `href` while callers may only know the hash-stripped form; the first match
-     * wins.
-     *
-     * Deliberately NOT decorated with `@ErrorEmitter`: the only caller (the
+     * 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
@@ -194,63 +185,53 @@ export declare class Database extends EventEmitter<DatabaseEvent> {
     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}.
      * @returns An array of resource URL strings.
      */
-    getResourceUrlList(): Promise<any[]>;
+    getResourceUrlList(): Promise<string[]>;
     /**
      * Counts pages that were scraped as crawl targets (full HTML render).
-     *
-     * Used by the crawler to seed its `pagesScraped` counter on resume so the
-     * progress display reflects all browser-rendered HTML pages across sessions,
-     * not just the current one.
-     *
-     * "HTML page" is guaranteed by `contentType = 'text/html'`, NOT by `isTarget`
-     * alone: `isTarget` means "in-scope crawl target" and is set for in-scope
-     * non-HTML resources too (e.g. a PDF reached via the HEAD pre-flight is
-     * `isTarget = 1`). Counting those would over-report the HTML page total, so
-     * page-ness is asserted at the read layer here rather than by trusting
-     * `isTarget`.
+     * Delegates to {@link getScrapedHtmlPageCountOp}.
      * @returns The number of `text/html` rows with `isTarget = 1` and `scraped = 1`.
      */
     getScrapedHtmlPageCount(): Promise<number>;
     /**
      * Retrieves all `page_tags` rows for the given page id, parsed back into
-     * {@link TagRow} shape (with `categories` and `sources` JSON columns
-     * deserialised).
-     *
-     * Read-side counterpart to `#insertTags`.
+     * {@link TagRow} shape. Delegates to {@link getTagsOfPageOp}.
      * @param pageId
      */
     getTagsOfPage(pageId: number): Promise<TagRow[]>;
     /**
      * Records a crawler-level (`error` channel) failure into `crawl_errors`.
-     *
-     * Unlike {@link insertPageError} this is not tied to a scraped page: `url`
-     * may be an external link that never became a page row, or `null` for a
-     * process-level error. The cause is intentionally not stored — it is derived
-     * on read so that older archives (which only have `error.log`) and freshly
-     * captured rows classify identically.
+     * 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>;
+    /**
+     * 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 a partial scrape failure against the page identified by `url`.
-     *
-     * The page row is resolved (or inserted as a stub) via
-     * {@link Database.#getIdByUrl} so the error can be recorded even before
-     * `setPage` has run — useful when the failure fires during scraping
-     * (e.g. mid-`scrapeStart`) and the orchestrator enqueues this write
-     * before the success write for the same URL.
-     *
-     * A single page can have multiple `page_errors` rows (e.g. both
-     * `desktop-compact` and `mobile-small` viewports failing).
+     * 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.
@@ -259,102 +240,83 @@ export declare class Database extends EventEmitter<DatabaseEvent> {
     insertPageError(url: string, phase: string, message: string, isExternal?: boolean): Promise<void>;
     /**
      * Inserts a sub-resource into the `resources` table.
-     * Ignores duplicate URLs (uses `ON CONFLICT IGNORE`).
-     *
-     * The `source` provenance label is written ONLY on insert; an
-     * `ON CONFLICT IGNORE` collision leaves an existing row's source untouched
-     * (this is what makes a second `crawl --inventory` non-destructive — see
-     * the inventory plan).
+     * 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. Silently skips if the resource is not found.
+     * `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>;
+    /**
+     * 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[]>;
+    /**
+     * Appends one row to the `inventory_runs` audit log.
+     * Delegates to {@link recordInventoryRunOp}.
+     * @param meta - The run metadata to record. Only `ran_at` is required.
+     * @returns The autoincremented `id` of the newly-inserted row.
+     */
+    recordInventoryRun(meta: InventoryRunMeta): Promise<number>;
     /**
      * Records a redirect edge (source → destination) **without** re-storing the
-     * destination's content.
-     *
-     * The crawler renders a many-to-one redirect destination exactly once. For
-     * every subsequent source URL that redirects to that already-rendered
-     * destination, it calls this instead of {@link updatePage} (#73). Routing a
-     * content-less HEAD result through `updatePage` would funnel it into
-     * `#insertPage` and overwrite the destination's good title / meta with empty
-     * values, so the dedicated edge-only path is required.
-     *
-     * The destination row is resolved (created on demand if a concurrent in-flight
-     * render has not committed it yet) so the edge always points at a valid id;
-     * the single render fills in the destination's content under that same id.
-     * The destination's existing anchors / images are never touched here.
+     * 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).
-     */
-    recordRedirect(page: PageData): Promise<void>;
-    /**
-     * Promote previously-external pages whose URL falls under any of the new scope
-     * entries back to a "needs scraping" state so that the next crawl picks them up
-     * as full internal pages.
-     *
-     * For each matching page:
-     * - clears the scrape metadata (status, headers, snapshot path, etc.),
-     * - flips `isExternal` to `0` and `scraped` to `0`,
-     * - removes stale `anchors`, `images`, and `resources-referrers` rows so that
-     *   the re-scrape can re-insert fresh ones without duplicates.
-     *
-     * The page row itself is kept (id is preserved) so existing referrers via
-     * `anchors.hrefId` remain valid. SELECT and UPDATE/DELETE statements are
-     * chunked to stay below SQLite's `SQLITE_LIMIT_VARIABLE_NUMBER`.
+     * @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 the stored analysis violations with a freshly generated set.
+     * Delegates to {@link replaceAnalysisViolationsOp}.
+     * @param violations - Flat violation list from the analyze phase.
+     */
+    replaceAnalysisViolations(violations: readonly {
+        validator: string;
+        severity: string;
+        rule: string;
+        code?: string | null;
+        message: string;
+        url: string;
+        line?: number | null;
+        col?: number | null;
+    }[]): 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 {@link findScopeEntry}.
+     * @param options - URL parsing options forwarded to the scope matcher.
      * @returns The URLs of the pages that were promoted.
      */
     repromoteExternalPages(scopes: ReadonlyMap<string, readonly ExURL[]>, options?: ParseURLOptions): Promise<string[]>;
     /**
      * Reset previously-attempted pages that ended in a recoverable failure so a
-     * follow-up crawl can re-fetch them from scratch.
-     *
-     * A page qualifies as a recoverable failure when it was already scraped
-     * (`scraped = 1`), is not a redirect source (`redirectDestId IS NULL`), was
-     * not intentionally skipped (`isSkipped` is not `1`), and one of the
-     * following holds:
-     *
-     * - `status = -1` — the sentinel a hard scrape failure (network error,
-     *   timeout, browser crash) is recorded with (see `handle-scrape-error.ts`);
-     * - `status IS NULL` — no status was ever stored for the row;
-     * - `contentType IS NULL` — the content type could not be determined;
-     * - `status` is in the `5xx` range — a (frequently transient) server error.
-     *
-     * Definitive `4xx` responses are intentionally excluded: re-fetching a 404
-     * almost always yields the same answer. Matching rows — internal and
-     * external alike — are demoted back to pending (`scraped = 0`) and have their
-     * stale scrape metadata cleared. The page row itself is kept (id preserved)
-     * so existing `anchors.hrefId` referrers stay valid, and `isExternal` is left
-     * untouched so the next pass re-classifies each page from the crawl scope.
-     * Related `anchors`, `images`, `resources-referrers`, and `page_errors` rows
-     * are deleted so the re-scrape can re-insert fresh data without duplicates.
-     *
-     * SELECT and UPDATE/DELETE statements are chunked to stay below SQLite's
-     * `SQLITE_LIMIT_VARIABLE_NUMBER`.
+     * follow-up crawl can re-fetch them from scratch. Delegates to
+     * {@link resetFailedPagesOp} — see the op for the permanent-failure
+     * exclusion rationale.
      * @returns The URLs of the pages that were reset to pending.
      */
     resetFailedPages(): Promise<string[]>;
     /**
      * Stores the crawl configuration in the `info` table.
-     * Only fields in {@link INFO_COLUMN_ALLOWLIST} are forwarded — any extra
-     * runtime-only field on the input is silently dropped so callers can splat
-     * a wider config object without producing SQL errors. JSON-array fields
-     * are serialized via `JSON.stringify`.
+     * 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.
-     * Creates the page row if it does not already exist.
+     * 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`.
@@ -362,31 +324,19 @@ export declare class Database extends EventEmitter<DatabaseEvent> {
     setSkippedPage(url: string, reason: string, isExternal?: boolean): Promise<void>;
     /**
      * Assigns natural URL sort order values to all internal pages.
-     * Pages are sorted using {@link pathComparator} and assigned sequential order numbers.
+     * Delegates to {@link setUrlOrderOp}.
      */
     setUrlOrder(): Promise<void>;
     /**
      * Update the single row in the `info` table with a partial config patch.
-     *
-     * Used by the append flow to extend `roots` (and any other tweakable
-     * field) without replacing the entire row. JSON-array fields are serialized on
-     * the fly; primitive fields are written verbatim. Unspecified fields stay as-is.
-     *
-     * Unknown keys (anything outside the allow-list of `info`-table columns) are
-     * silently dropped instead of being passed to SQL, so callers that splat a
-     * wider runtime config (e.g. `CrawlConfig` with `cwd` / `executablePath`)
-     * cannot accidentally trigger a "no such column" SQL error.
+     * 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.
-     *
-     * Self-redirects (where the source URL equals the destination URL after normalization)
-     * are skipped to avoid marking a page as redirected to itself — a situation caused by
-     * authentication challenges (e.g. Basic Auth 302) that would otherwise exclude the page
-     * from reports via the `whereNull('redirectDestId')` filter.
+     * 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
@@ -394,9 +344,7 @@ export declare class Database extends EventEmitter<DatabaseEvent> {
      *   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` (this is why a
-     *   second `crawl --inventory` does not "demote" an `'inventory-seed'` row
-     *   that was discovered earlier).
+     *   inserted. Existing rows keep their original `source`.
      * @returns The database `pageId` of the inserted/updated row.
      */
     updatePage(page: PageData, writeHtml: boolean, isTarget: boolean, source?: PageSource): Promise<number>;