@nitpicker/crawler 0.12.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, InventoryRunMeta, 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,12 +7,14 @@ 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 `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).
+ * 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'`).
@@ -28,103 +30,40 @@ 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.
-     *
-     * `scraped` is straightforward: every page row whose `scraped` flag is `1`
-     * — that is, every URL the crawl reached a terminal state on, including
-     * setSkippedPage / setExternalPage / outright setPage success or failure.
-     *
-     * `pending` is intentionally STRICT — not "every `scraped = 0` row".
-     * Three filters apply:
-     *
-     * 1. `scraped = 0` — work still incomplete.
-     * 2. `isExternal = 0` — only in-scope work. External URLs go through a
-     *    HEAD-only path that always lands on `scraped = 1` (either setPage or
-     *    setExternalPage). A row with `isExternal = 1 AND scraped = 0` is
-     *    therefore a data anomaly, and resume / inventory / append have no
-     *    business retrying it on the next session.
-     * 3. `EXISTS (anchor with hrefId = pages.id) OR source != 'crawled'` —
-     *    the row was either discovered as an anchor destination during a
-     *    previous scrape OR was explicitly tagged with a non-default
-     *    source label (`'inventory-seed'`, `'inventory-discovered'`, …).
-     *    Both halves of the OR represent "deliberately enqueued, expected
-     *    to be processed", which is exactly what `resume` should pick up.
-     *
-     *    The orphan filter targets the **predicted-discard leak** in
-     *    `crawler.ts` where `shouldDiscardPredicted` returns true but no
-     *    `emit('skip')` follows. Such placeholders are inserted with the
-     *    DB DEFAULT `source = 'crawled'` (no caller explicitly labels
-     *    them) AND have no anchor referrer (predicted URLs are
-     *    synthesised from pagination patterns, never anchored from a
-     *    rendered page) — both halves of the OR are therefore false and
-     *    the leak is excluded.
-     *
-     *    The `source != 'crawled'` clause specifically saves the
-     *    `--inventory` × `--retry-failed` interaction: an inventory-seed
-     *    URL came from the operator's URL list (no anchor referrer) and
-     *    `resetFailedPages` puts it back at `scraped = 0`. Without this
-     *    clause those legitimate retries would be dropped on resume.
-     *
-     * The defensive shape is on purpose: the data source can drift into
-     * anomalous states under interruption, but the reader must never throw
-     * or feed garbage back into the dealer. A real in-scope URL that was
-     * truly interrupted mid-crawl will always have at least one anchor
-     * referrer (otherwise the dealer would not have queued it), so the
-     * strict filter loses no legitimate pending work.
-     *
-     * Seeds passed directly to `Crawler.start()` are NOT in the strict
-     * pending set when they were never picked by the dealer — they have no
-     * DB row at all in that case (`linkList.add` is purely in-memory until
-     * `setPage` runs). A Ctrl-C between dealer pick and `setPage` likewise
-     * leaves no row to recover. Recovery of un-picked seeds is the
-     * responsibility of the caller (e.g. re-running `--inventory ./list.txt`
-     * with the same URL list).
-     *
-     * The query uses an explicit `p` alias on the `pages` table so the
-     * correlated `EXISTS` subquery can join via `whereRaw('anchors.hrefId =
-     * p.id')`. A future refactor that renames the alias must update both
-     * sites — the raw string in the subquery cannot be grep-resolved
-     * automatically. Read-only / stub viewer connections never call this
-     * method (they do not need to know about pending state), so the EXISTS
-     * shape is safe to use without the `migrate*` guards that other writer
-     * methods carry.
+     * 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).
      */
@@ -134,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[]>;
@@ -187,90 +107,72 @@ 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. Used by
-     * the orchestrator's `PageSourceLookup` injection so the Crawler can
-     * resolve a parent page's lineage on `--resume` / `--retry-failed`
-     * sessions, where the in-memory `inventoryMode` is no longer
-     * available but the DB still remembers what label was last persisted.
-     *
-     * Returns `undefined` when the URL has no `pages` row (e.g. a brand-new
-     * URL that has not been seen yet) so the caller can fall through to
-     * its default behaviour without distinguishing "row absent" from "row
-     * present with NULL source" — the schema's `NOT NULL DEFAULT 'crawled'`
-     * makes a NULL value impossible in practice.
-     *
-     * Read-only — no transaction, single PK-equivalent lookup on
-     * `pages.url` (a UNIQUE column), so the cost is constant per call. The
-     * Crawler calls this at most once per page render, NOT per
-     * sub-resource, so the N+1 risk does not apply.
+     * 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.
-     *
-     * 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.
+     * 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),
@@ -283,115 +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
-     * with `source = 'inventory-seed'` and all metadata columns NULL — the
-     * non-HTML counterpart of {@link Database.insertInventorySeeds}. Used by
-     * `CrawlerOrchestrator.inventory` so the ingestion phase commits all of
-     * its non-HTML URLs in one chunked round-trip per 500 instead of N
-     * sequential `insertResource` awaits. On a 50k-URL inventory list the
-     * old per-URL loop spent minutes inside the `.bak`-protected window;
-     * the bulk path finishes in seconds.
-     *
-     * Idempotent: `onConflict('url').ignore()` leaves existing rows untouched
-     * (the orchestrator's `getExistingResourceUrls` filter is what keeps a
-     * crawled-lineage `resources` row from being downgraded to the
-     * inventory label here).
-     *
-     * Chunked at 500 to stay well under SQLite's `SQLITE_MAX_VARIABLE_NUMBER`
-     * (default 999) — every row binds the URL plus the `responseHeaders`
-     * JSON null, so the per-chunk bound budget is well within limits.
+     * 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 so the URL's existence in the
-     * archive is **durable before the scrape phase starts**.
-     *
-     * Why this is the linchpin of `--inventory` Ctrl+C tolerance: HTML seeds
-     * used to live only in the Crawler's in-memory `LinkList` until the
-     * dealer eventually called `setPage`. A Ctrl+C / crash before that point
-     * lost the seed without trace, and `--resume` could not recover it
-     * because `getCrawlingState`'s strict pending set requires a `pages` row.
-     * Pre-inserting fills exactly that gap: the strict pending set picks
-     * these rows up via its `OR p.source != 'crawled'` clause, so
-     * `--resume` after an interrupted inventory pass picks every seed back
-     * up. See {@link Database.getCrawlingState} for the strict-set rationale.
-     *
-     * Idempotent: `onConflict('url').ignore()` keeps existing rows intact.
-     * The {@link Database.#getIdByUrl} crawled-wins downgrade still fires
-     * later when a crawled-lineage anchor reaches one of these seeds —
-     * that's the right behaviour (a seed that turned out to be reachable
-     * is not an orphan and should not retain the inventory label).
-     *
-     * Chunked into 500-URL batches so SQLite's bound-parameter limit
-     * (`SQLITE_MAX_VARIABLE_NUMBER`, default 999) cannot be hit even on a
-     * tens-of-thousands inventory list.
-     *
-     * Called by {@link CrawlerOrchestrator.inventory} during the
-     * `.bak`-protected ingestion phase, so any failure here aborts the run
-     * and restores from backup — the operator reruns from scratch.
+     * `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.
@@ -400,162 +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 — i.e. hosts
-     * the previous crawl already proved unreachable. Returned in lower-cased
-     * form. Used by `CrawlerOrchestrator.#preloadDnsBurnedHostCache` so the
-     * next session short-circuits HEAD pre-flight on these hosts.
-     *
-     * Implementation: a coarse `LIKE` filter over `crawl_errors.message`
-     * narrows the row set, then `classifyErrorKind` confirms `'dns'` in JS
-     * (the regex is the single truth source — DB-side filters never narrow
-     * it). Exclusion bags are built from a single `pages` and a single
-     * `resources` scan: any host with a 2xx-3xx page, a 2xx-3xx resource, or
-     * a `pages.lastCrawledAt` newer than its latest DNS error is dropped
-     * (the host probably recovered between the failure and the last crawl).
-     *
-     * Returns `[]` on legacy archives that pre-date the `crawl_errors`
-     * table — the `hasTable` guard keeps the call non-destructive.
+     * 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.
-     *
-     * Called by {@link CrawlerOrchestrator.inventory} on every successful
-     * `--inventory <list>` invocation so the archive carries a durable
-     * record of which deploy list was applied when and at what scale —
-     * the operational question "did we apply last month's list" the
-     * archive itself can answer without consulting external bookkeeping.
-     *
-     * Append-only at Phase 1. There is intentionally no UPDATE path and
-     * no UNIQUE constraint on `source_file_sha256`; two applies of the
-     * same list each get their own row, and `Phase 3 --refresh` is where
-     * dedupe / pre-flight against the hash will land. Field-level NULL
-     * semantics live on {@link InventoryRunMeta}.
+     * 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).
-     * @param source - Inventory provenance forwarded by the orchestrator
-     *   (`Archive.setRedirect` → here) for the redirect-edge fast path. Used
-     *   as the fallback when the originating URL's row does NOT yet exist in
-     *   the archive (`#73` convergence on first sight, js-redirect rescue
-     *   before any prior write). When the originating row already exists
-     *   (e.g. anchor-lineage INSERT from a prior pass), its stored `source`
-     *   takes precedence so transitive lineage is preserved across resume /
-     *   retry-failed sessions. `undefined` keeps the DB DEFAULT `'crawled'`
-     *   on a brand-new destination row.
+     * @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>;
     /**
-     * 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`.
+     * 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.
-     *
-     * A second exclusion runs in JS after the SQL candidate scan: any page whose
-     * latest recorded `page_errors` / `crawl_errors` message classifies into a
-     * permanent {@link PERMANENT_ERROR_KINDS} kind (dns / tls / client-blocked /
-     * parse-error / connection-refused) is left as-is rather than reset to
-     * pending. Without this filter, `--retry-failed` never converges: NXDOMAIN
-     * hosts, expired-cert hosts, and `ERR_BLOCKED_BY_CLIENT` ad pixels would be
-     * reset every iteration, re-attempted, fail identically, and rejoin the
-     * candidate pool for the next iteration. The exclusion keeps the retry
-     * target shrinking across `--retry-failed` passes by leaving deterministic
-     * dead-ends alone.
-     *
-     * 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`.
@@ -563,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
@@ -595,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>;