@nitpicker/crawler 0.11.0 → 0.13.0

package/lib/archive/database.js

@@ -1,1791 +1,538 @@
-var __runInitializers = (this && this.__runInitializers) || function (thisArg, initializers, value) {
-    var useValue = arguments.length > 2;
-    for (var i = 0; i < initializers.length; i++) {
-        value = useValue ? initializers[i].call(thisArg, value) : initializers[i].call(thisArg);
-    }
-    return useValue ? value : void 0;
-};
-var __esDecorate = (this && this.__esDecorate) || function (ctor, descriptorIn, decorators, contextIn, initializers, extraInitializers) {
-    function accept(f) { if (f !== void 0 && typeof f !== "function") throw new TypeError("Function expected"); return f; }
-    var kind = contextIn.kind, key = kind === "getter" ? "get" : kind === "setter" ? "set" : "value";
-    var target = !descriptorIn && ctor ? contextIn["static"] ? ctor : ctor.prototype : null;
-    var descriptor = descriptorIn || (target ? Object.getOwnPropertyDescriptor(target, contextIn.name) : {});
-    var _, done = false;
-    for (var i = decorators.length - 1; i >= 0; i--) {
-        var context = {};
-        for (var p in contextIn) context[p] = p === "access" ? {} : contextIn[p];
-        for (var p in contextIn.access) context.access[p] = contextIn.access[p];
-        context.addInitializer = function (f) { if (done) throw new TypeError("Cannot add initializers after decoration has completed"); extraInitializers.push(accept(f || null)); };
-        var result = (0, decorators[i])(kind === "accessor" ? { get: descriptor.get, set: descriptor.set } : descriptor[key], context);
-        if (kind === "accessor") {
-            if (result === void 0) continue;
-            if (result === null || typeof result !== "object") throw new TypeError("Object expected");
-            if (_ = accept(result.get)) descriptor.get = _;
-            if (_ = accept(result.set)) descriptor.set = _;
-            if (_ = accept(result.init)) initializers.unshift(_);
-        }
-        else if (_ = accept(result)) {
-            if (kind === "field") initializers.unshift(_);
-            else descriptor[key] = _;
-        }
-    }
-    if (target) Object.defineProperty(target, contextIn.name, descriptor);
-    done = true;
-};
-import { createHash } from 'node:crypto';
 import { existsSync } from 'node:fs';
 import path from 'node:path';
-import { zstdCompressSync, zstdDecompressSync } from 'node:zlib';
-import { tryParseUrl as parseUrl } from '@d-zero/shared/parse-url';
-import { retry } from '@d-zero/shared/retry';
-import { pathComparator } from '@d-zero/shared/sort/path';
+import { retryCall } from '@d-zero/shared/retry';
 import { TypedAwaitEventEmitter as EventEmitter } from '@d-zero/shared/typed-await-event-emitter';
 import knex from 'knex';
-import { findScopeEntry } from '../crawler/find-scope-entry.js';
-import { isHtmlContentType } from '../crawler/is-html-content-type.js';
-import { normalizeContentType } from '../crawler/normalize-content-type.js';
-import { eachSplitted } from '../utils/array/each-splitted.js';
-import { ErrorEmitter } from '../utils/error/error-emitter.js';
-import { dbLog } from './debug.js';
+import { emitErrorAndRetry } from '../utils/error/emit-error-with-retry.js';
+import { emitError } from '../utils/error/emit-error.js';
+import { createWriteRefCaches } from './db-ops/_shared/create-write-ref-caches.js';
+import { retrySetting } from './db-ops/_shared/retry-setting.js';
+import { replaceAnalysisViolations as replaceAnalysisViolationsOp } from './db-ops/analysis/replace-analysis-violations.js';
+import { getAnchorsOnPage as getAnchorsOnPageOp } from './db-ops/anchors/get-anchors-on-page.js';
+import { getBaseUrl as getBaseUrlOp } from './db-ops/config/get-base-url.js';
+import { getConfig as getConfigOp } from './db-ops/config/get-config.js';
+import { getName as getNameOp } from './db-ops/config/get-name.js';
+import { setConfig as setConfigOp } from './db-ops/config/set-config.js';
+import { updateConfig as updateConfigOp } from './db-ops/config/update-config.js';
+import { insertCrawlError as insertCrawlErrorOp } from './db-ops/errors/insert-crawl-error.js';
+import { insertPageError as insertPageErrorOp } from './db-ops/errors/insert-page-error.js';
+import { listDnsBurnedHostCandidates as listDnsBurnedHostCandidatesOp } from './db-ops/errors/list-dns-burned-host-candidates.js';
+import { getHtmlOfPageById as getHtmlOfPageByIdOp } from './db-ops/html/get-html-of-page-by-id.js';
+import { recordInventoryRun as recordInventoryRunOp } from './db-ops/inventory/record-inventory-run.js';
+import { checkpoint as checkpointOp } from './db-ops/lifecycle/checkpoint.js';
+import { destroy as destroyOp } from './db-ops/lifecycle/destroy.js';
+import { init as initOp } from './db-ops/lifecycle/init.js';
+import { getJsonLdOfPage as getJsonLdOfPageOp } from './db-ops/meta/get-jsonld-of-page.js';
+import { getTagsOfPage as getTagsOfPageOp } from './db-ops/meta/get-tags-of-page.js';
+import { setUrlOrder as setUrlOrderOp } from './db-ops/pages/order/set-url-order.js';
+import { getCrawlingState as getCrawlingStateOp } from './db-ops/pages/read/get-crawling-state.js';
+import { getExistingPageUrls as getExistingPageUrlsOp } from './db-ops/pages/read/get-existing-page-urls.js';
+import { getPageCount as getPageCountOp } from './db-ops/pages/read/get-page-count.js';
+import { getPageSourceByUrl as getPageSourceByUrlOp } from './db-ops/pages/read/get-page-source-by-url.js';
+import { getPagesWithRels as getPagesWithRelsOp } from './db-ops/pages/read/get-pages-with-rels.js';
+import { getPages as getPagesOp } from './db-ops/pages/read/get-pages.js';
+import { getScrapedHtmlPageCount as getScrapedHtmlPageCountOp } from './db-ops/pages/read/get-scraped-html-page-count.js';
+import { repromoteExternalPages as repromoteExternalPagesOp } from './db-ops/pages/reset/repromote-external-pages.js';
+import { resetFailedPages as resetFailedPagesOp } from './db-ops/pages/reset/reset-failed-pages.js';
+import { insertInventorySeeds as insertInventorySeedsOp } from './db-ops/pages/write/insert-inventory-seeds.js';
+import { recordRedirect as recordRedirectOp } from './db-ops/pages/write/record-redirect.js';
+import { setSkippedPage as setSkippedPageOp } from './db-ops/pages/write/set-skipped-page.js';
+import { updatePage as updatePageOp } from './db-ops/pages/write/update-page.js';
+import { getRedirectsForPages as getRedirectsForPagesOp } from './db-ops/referrers/get-redirects-for-pages.js';
+import { getReferrersOfPage as getReferrersOfPageOp } from './db-ops/referrers/get-referrers-of-page.js';
+import { getReferrersOfResource as getReferrersOfResourceOp } from './db-ops/referrers/get-referrers-of-resource.js';
+import { getExistingResourceUrls as getExistingResourceUrlsOp } from './db-ops/resources/get-existing-resource-urls.js';
+import { getResourceByUrl as getResourceByUrlOp } from './db-ops/resources/get-resource-by-url.js';
+import { getResourceUrlList as getResourceUrlListOp } from './db-ops/resources/get-resource-url-list.js';
+import { getResources as getResourcesOp } from './db-ops/resources/get-resources.js';
+import { insertInventoryResources as insertInventoryResourcesOp } from './db-ops/resources/insert-inventory-resources.js';
+import { insertResourceReferrers as insertResourceReferrersOp } from './db-ops/resources/insert-resource-referrers.js';
+import { insertResource as insertResourceOp } from './db-ops/resources/insert-resource.js';
 import { mkdir } from './filesystem/mkdir.js';
-import { getJSON } from './get-json.js';
-import { applyConnectionPragmas, initSchema } from './init-schema.js';
 import { LibsqlDialect } from './libsql-dialect.js';
-import { limitedPageIds } from './limited-page-ids.js';
-import { assertCompatibleVersion } from './meta/assert-compatible-version.js';
-import { classifyJsonLdType } from './meta/classify-jsonld-type.js';
-import { computePageDenormalized } from './meta/compute-page-denormalized.js';
-import { deriveFlatFromMeta } from './meta/derive-flat-from-meta.js';
-import { deriveMetaExtras } from './meta/derive-meta-extras.js';
-import { extractTagsForArchive } from './meta/extract-tags-for-archive.js';
-import { migrateCrawlErrors } from './migrate-crawl-errors.js';
-import { migrateHtmlBlobTables } from './migrate-html-blob-tables.js';
-import { migrateInfoRoots } from './migrate-info-roots.js';
-import { migratePageErrors } from './migrate-page-errors.js';
-import { migratePagesResourcesSource } from './migrate-pages-resources-source.js';
-import { redirectTable } from './redirect-table.js';
-import { resolveRedirectChain } from './resolve-redirect-chain.js';
-const retrySetting = {
-    interval: 300,
-    retries: 3,
-};
-/**
- * Decodes a stored HTML body BLOB according to its codec marker. The codec
- * column on `page_html_blobs` exists so individual rows can be migrated to
- * a future encoder without rewriting the whole table; readers must dispatch
- * on it. The body is typed `Uint8Array` (not `Buffer`) because libsql
- * returns BLOB columns as bare `Uint8Array`; `Buffer.from` wraps it
- * zero-copy.
- * @param body - Raw bytes as stored in `page_html_blobs.body`.
- * @param codec - The `codec` column value (e.g. `'zstd'`, `'none'`).
- * @returns UTF-8 decoded HTML string.
- * @throws {Error} If the codec is not recognised.
- */
 /**
- * Parses a JSON column value, returning `null` on parse failure rather than
- * throwing. JSON columns in `page_jsonld` (`parsed`) and `page_tags`
- * (`categories`, `sources`) are written by `JSON.stringify` and round-trip
- * cleanly under normal conditions; a hand-edited archive that has
- * malformed JSON in those columns should degrade gracefully rather than
- * propagate a parse error up to the consumer.
- * @param value - JSON-encoded text.
+ * 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.
  */
-function safeParseJson(value) {
-    try {
-        return JSON.parse(value);
+export class Database extends EventEmitter {
+    /** The Knex query builder instance connected to the SQLite database. */
+    #instance;
+    /** Connection-scoped write-side id caches for entity/ref upserts. */
+    #writeRefCaches = createWriteRefCaches();
+    // eslint-disable-next-line no-restricted-syntax
+    constructor(options) {
+        super();
+        // **Known caveat (libsql 0.5.x)**: passing `readonly: true` via
+        // `connection.options` is accepted by the libsql driver but is
+        // NOT enforced at the SQL layer — `CREATE TABLE` / `INSERT`
+        // against the resulting connection still succeed. The flag
+        // remains a no-op until libsql adds real read-only enforcement
+        // upstream. Read-only safety in cache mode therefore relies on:
+        //
+        // 1. `Database.#init` skipping schema init + migrations when
+        //    `readOnly` is set (so no `initSchema` / `migrate*` ever
+        //    writes to the shared cache directory).
+        // 2. `ArchiveAccessor.setData` rejecting writes when the
+        //    `readOnly` flag is set on the accessor.
+        // 3. Code review on any future internal use of
+        //    `accessor.getKnex()` — there is no driver-level guard.
+        this.#instance = knex({
+            client: LibsqlDialect,
+            connection: {
+                filename: options.filename,
+            },
+            useNullAsDefault: true,
+            pool: {
+                acquireTimeoutMillis: 600_000,
+            },
+        });
     }
-    catch {
-        return null;
+    /**
+     * Forces a WAL checkpoint, writing all pending WAL data back to the main
+     * database file. Delegates to {@link checkpointOp}.
+     */
+    async checkpoint() {
+        await checkpointOp(this.#instance);
     }
-}
-/**
- *
- * @param body
- * @param codec
- */
-function decodeStoredBlob(body, codec) {
-    // `Buffer.from(buffer)` accepts Uint8Array, Buffer, and array-like
-    // shapes uniformly; libsql may hand back any of these for a BLOB
-    // column depending on the row encoding.
-    const buffer = Buffer.from(body);
-    if (codec === 'zstd') {
-        return zstdDecompressSync(buffer).toString('utf8');
+    /**
+     * Destroys the database connection, releasing all pooled resources.
+     * Delegates to {@link destroyOp}.
+     */
+    async destroy() {
+        await destroyOp(this.#instance);
     }
-    if (codec === 'none') {
-        return buffer.toString('utf8');
+    /**
+     * 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.
+     */
+    async getAnchorsOnPage(pageId) {
+        return emitErrorAndRetry(this, 'Database.getAnchorsOnPage', async () => await getAnchorsOnPageOp(this.#instance, pageId), retrySetting);
     }
-    throw new Error(`Unknown page_html_blobs.codec: ${codec}`);
-}
-/**
- * Columns of the `info` table that `setConfig` / `updateConfig` are allowed to
- * write. Any key outside this set is silently dropped so callers can splat a
- * wider runtime config (with extras like `cwd`) without hitting "no such
- * column" at the SQL layer.
- */
-const INFO_COLUMN_ALLOWLIST = new Set([
-    'version',
-    'name',
-    'baseUrl',
-    'roots',
-    'recursive',
-    'interval',
-    'image',
-    'fetchExternal',
-    'parallels',
-    'excludes',
-    'excludeKeywords',
-    'excludeUrls',
-    'maxExcludedDepth',
-    'retry',
-    'fromList',
-    'disableQueries',
-    'userAgent',
-    'ignoreRobots',
-]);
-/**
- * Subset of {@link INFO_COLUMN_ALLOWLIST} that is stored as a JSON-encoded
- * string and therefore needs `JSON.stringify` on write.
- */
-const INFO_JSON_COLUMNS = new Set([
-    'roots',
-    'excludes',
-    'excludeKeywords',
-    'excludeUrls',
-]);
-/**
- * Columns of the `pages` table that should be reset to `null` whenever a
- * previously-scraped row is demoted back to "pending" (i.e. by
- * `resetFailedPages` and `repromoteExternalPages`).
- *
- * Includes all flat meta columns, the denormalised aggregates, and the
- * `meta_extras` JSON catch-all. **Excludes** `firstCrawledAt` / `lastCrawledAt`
- * by design — failure reset must not erase the last-success timestamp, which
- * is the within-archive observation axis for #11 / #17 / #19 use cases.
- *
- * Centralised in one constant so schema growth and reset logic stay in lock-
- * step: adding a flat meta column without updating this list would leave
- * stale data after a reset.
- */
-const META_NULLABLE_COLUMNS = [
-    // Document basics
-    'lang',
-    'dir',
-    'charset',
-    'baseHref',
-    'viewport_raw',
-    'themeColor',
-    'applicationName',
-    'author',
-    'generator',
-    'publisher',
-    // Title / description / keywords
-    'title',
-    'description',
-    'keywords',
-    // Robots
-    'robots_raw',
-    'robots_noindex',
-    'robots_nofollow',
-    'robots_noarchive',
-    'robots_noimageindex',
-    'googlebot',
-    // Link (1:1)
-    'canonical',
-    'amphtml',
-    'manifest',
-    'icon_href',
-    'appleTouchIcon_href',
-    // Open Graph
-    'og_type',
-    'og_title',
-    'og_url',
-    'og_site_name',
-    'og_description',
-    'og_image',
-    'og_image_alt',
-    'og_image_width',
-    'og_image_height',
-    'og_locale',
-    'og_article_published_time',
-    'og_article_modified_time',
-    // Twitter
-    'twitter_card',
-    'twitter_site',
-    'twitter_creator',
-    'twitter_title',
-    'twitter_description',
-    'twitter_image',
-    // One-offs
-    'fb_app_id',
-    'verification_google',
-    'formatDetection_telephone',
-    // Denormalised aggregates
-    'tag_count',
-    'jsonld_count',
-    'tags_providers_csv',
-    // Catch-all
-    'meta_extras',
-];
-/**
- * Builds the reset payload for {@link META_NULLABLE_COLUMNS} as a plain object
- * suitable for `knex.update(...)`. All listed columns are mapped to `null`.
- */
-function makeMetaResetPayload() {
-    const payload = {};
-    for (const col of META_NULLABLE_COLUMNS) {
-        payload[col] = null;
+    /**
+     * 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.
+     */
+    async getBaseUrl() {
+        return emitErrorAndRetry(this, 'Database.getBaseUrl', async () => await getBaseUrlOp(this.#instance), retrySetting);
+    }
+    /**
+     * 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.
+     */
+    async getConfig() {
+        return emitErrorAndRetry(this, 'Database.getConfig', async () => await getConfigOp(this.#instance), retrySetting);
+    }
+    /**
+     * 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) and `pending` (the
+     *   strict set of in-scope, anchor-referenced, unfinished URLs).
+     */
+    async getCrawlingState() {
+        return emitErrorAndRetry(this, 'Database.getCrawlingState', async () => await getCrawlingStateOp(this.#instance), retrySetting);
+    }
+    /**
+     * 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.
+     */
+    async getExistingPageUrls(urls) {
+        return emitError(this, 'Database.getExistingPageUrls', async () => await getExistingPageUrlsOp(this.#instance, urls));
+    }
+    /**
+     * 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`.
+     */
+    async getExistingResourceUrls(urls) {
+        return emitError(this, 'Database.getExistingResourceUrls', async () => await getExistingResourceUrlsOp(this.#instance, urls));
+    }
+    /**
+     * Reads the HTML snapshot stored as a zstd-compressed BLOB for the given page.
+     * Delegates to {@link getHtmlOfPageByIdOp}.
+     * @param pageId - The database ID of the page.
+     * @returns The decompressed HTML string, or `null` if no snapshot is stored.
+     */
+    async getHtmlOfPageById(pageId) {
+        return emitErrorAndRetry(this, 'Database.getHtmlOfPageById', async () => await getHtmlOfPageByIdOp(this.#instance, pageId), retrySetting);
+    }
+    /**
+     * Retrieves all `page_jsonld` rows for the given page id, parsed back into
+     * {@link JsonLdRow} shape. Delegates to {@link getJsonLdOfPageOp}.
+     * @param pageId
+     */
+    async getJsonLdOfPage(pageId) {
+        return emitErrorAndRetry(this, 'Database.getJsonLdOfPage', async () => await getJsonLdOfPageOp(this.#instance, pageId), retrySetting);
+    }
+    /**
+     * 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() {
+        return this.#instance;
+    }
+    /**
+     * 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.
+     */
+    async getName() {
+        return emitErrorAndRetry(this, 'Database.getName', async () => await getNameOp(this.#instance), retrySetting);
+    }
+    /**
+     * 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.
+     */
+    async getPageCount() {
+        return emitErrorAndRetry(this, 'Database.getPageCount', async () => await getPageCountOp(this.#instance), retrySetting);
+    }
+    /**
+     * 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.
+     */
+    async getPages(filter, offset = 0, limit = 100_000) {
+        return emitErrorAndRetry(this, 'Database.getPages', async () => await getPagesOp(this.#instance, filter, offset, limit), retrySetting);
+    }
+    /**
+     * 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.
+     */
+    async getPageSourceByUrl(url) {
+        return emitError(this, 'Database.getPageSourceByUrl', async () => await getPageSourceByUrlOp(this.#instance, url));
+    }
+    /**
+     * 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.
+     */
+    async getPagesWithRels(offset, limit) {
+        return emitErrorAndRetry(this, 'Database.getPagesWithRels', async () => await getPagesWithRelsOp(this.#instance, offset, limit), retrySetting);
+    }
+    /**
+     * 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.
+     */
+    async getRedirectsForPages(pageIds) {
+        return emitErrorAndRetry(this, 'Database.getRedirectsForPages', async () => await getRedirectsForPagesOp(this.#instance, pageIds), retrySetting);
+    }
+    /**
+     * 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.
+     */
+    async getReferrersOfPage(pageId) {
+        return emitErrorAndRetry(this, 'Database.getReferrersOfPage', async () => await getReferrersOfPageOp(this.#instance, pageId), retrySetting);
+    }
+    /**
+     * 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.
+     */
+    async getReferrersOfResource(id) {
+        return emitErrorAndRetry(this, 'Database.getReferrersOfResource', async () => await getReferrersOfResourceOp(this.#instance, id), retrySetting);
+    }
+    /**
+     * 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.
+     */
+    async getResourceByUrl(urls) {
+        return retryCall(async () => await getResourceByUrlOp(this.#instance, urls), {
+            ...retrySetting,
+            label: 'Database.getResourceByUrl',
+        });
+    }
+    /**
+     * Retrieves all sub-resources from the `resources` table.
+     * Delegates to {@link getResourcesOp}.
+     * @returns An array of raw {@link DB_Resource} rows.
+     */
+    async getResources() {
+        return emitErrorAndRetry(this, 'Database.getResources', async () => await getResourcesOp(this.#instance), retrySetting);
+    }
+    /**
+     * Retrieves a flat list of all resource URLs from the `resources` table.
+     * Delegates to {@link getResourceUrlListOp}.
+     * @returns An array of resource URL strings.
+     */
+    async getResourceUrlList() {
+        return emitErrorAndRetry(this, 'Database.getResourceUrlList', async () => await getResourceUrlListOp(this.#instance), retrySetting);
+    }
+    /**
+     * 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`.
+     */
+    async getScrapedHtmlPageCount() {
+        return emitErrorAndRetry(this, 'Database.getScrapedHtmlPageCount', async () => await getScrapedHtmlPageCountOp(this.#instance), retrySetting);
+    }
+    /**
+     * Retrieves all `page_tags` rows for the given page id, parsed back into
+     * {@link TagRow} shape. Delegates to {@link getTagsOfPageOp}.
+     * @param pageId
+     */
+    async getTagsOfPage(pageId) {
+        return emitErrorAndRetry(this, 'Database.getTagsOfPage', async () => await getTagsOfPageOp(this.#instance, pageId), retrySetting);
+    }
+    /**
+     * 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.
+     */
+    async insertCrawlError(url, message, isExternal = false) {
+        return emitErrorAndRetry(this, 'Database.insertCrawlError', async () => await insertCrawlErrorOp(this.#instance, url, message, isExternal), retrySetting);
+    }
+    /**
+     * Pre-insert inventory non-HTML URLs into `resources` as placeholder rows.
+     * Delegates to {@link insertInventoryResourcesOp}.
+     * @param urls - URL strings (already in `withoutHashAndAuth` form).
+     */
+    async insertInventoryResources(urls) {
+        return emitErrorAndRetry(this, 'Database.insertInventoryResources', async () => await insertInventoryResourcesOp(this.#instance, this.#writeRefCaches, urls), retrySetting);
+    }
+    /**
+     * 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.
+     */
+    async insertInventorySeeds(urls) {
+        return emitErrorAndRetry(this, 'Database.insertInventorySeeds', async () => await insertInventorySeedsOp(this.#instance, this.#writeRefCaches, urls), retrySetting);
+    }
+    /**
+     * 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`.
+     */
+    async insertPageError(url, phase, message, isExternal = false) {
+        return emitErrorAndRetry(this, 'Database.insertPageError', async () => await insertPageErrorOp(this.#instance, this.#writeRefCaches, url, phase, message, isExternal), retrySetting);
+    }
+    /**
+     * 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'`).
+     */
+    async insertResource(resource, source) {
+        return emitErrorAndRetry(this, 'Database.insertResource', async () => await insertResourceOp(this.#instance, this.#writeRefCaches, resource, source), retrySetting);
+    }
+    /**
+     * 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.
+     */
+    async insertResourceReferrers(src, pageUrl) {
+        return emitErrorAndRetry(this, 'Database.insertResourceReferrers', async () => await insertResourceReferrersOp(this.#instance, this.#writeRefCaches, src, pageUrl), retrySetting);
+    }
+    /**
+     * 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.
+     */
+    async listDnsBurnedHostCandidates() {
+        return emitErrorAndRetry(this, 'Database.listDnsBurnedHostCandidates', async () => await listDnsBurnedHostCandidatesOp(this.#instance), retrySetting);
+    }
+    /**
+     * 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.
+     */
+    async recordInventoryRun(meta) {
+        return emitErrorAndRetry(this, 'Database.recordInventoryRun', async () => await recordInventoryRunOp(this.#instance, meta), retrySetting);
+    }
+    /**
+     * 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.
+     */
+    async recordRedirect(page, source) {
+        return emitErrorAndRetry(this, 'Database.recordRedirect', async () => await recordRedirectOp(this.#instance, this.#writeRefCaches, page, source), retrySetting);
+    }
+    /**
+     * Replaces the stored analysis violations with a freshly generated set.
+     * Delegates to {@link replaceAnalysisViolationsOp}.
+     * @param violations - Flat violation list from the analyze phase.
+     */
+    async replaceAnalysisViolations(violations) {
+        return emitErrorAndRetry(this, 'Database.replaceAnalysisViolations', async () => await replaceAnalysisViolationsOp(this.#instance, violations), retrySetting);
+    }
+    /**
+     * 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.
+     * @returns The URLs of the pages that were promoted.
+     */
+    async repromoteExternalPages(scopes, options) {
+        return emitErrorAndRetry(this, 'Database.repromoteExternalPages', async () => await repromoteExternalPagesOp(this.#instance, scopes, options), retrySetting);
+    }
+    /**
+     * 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.
+     * @returns The URLs of the pages that were reset to pending.
+     */
+    async resetFailedPages() {
+        return emitErrorAndRetry(this, 'Database.resetFailedPages', async () => await resetFailedPagesOp(this.#instance), retrySetting);
+    }
+    /**
+     * Stores the crawl configuration in the `info` table.
+     * Delegates to {@link setConfigOp}.
+     * @param config - The {@link Config} object to store.
+     */
+    async setConfig(config) {
+        return emitErrorAndRetry(this, 'Database.setConfig', async () => await setConfigOp(this.#instance, config), retrySetting);
+    }
+    /**
+     * 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`.
+     */
+    async setSkippedPage(url, reason, isExternal = false) {
+        return emitErrorAndRetry(this, 'Database.setSkippedPage', async () => await setSkippedPageOp(this.#instance, this.#writeRefCaches, url, reason, isExternal), retrySetting);
+    }
+    /**
+     * Assigns natural URL sort order values to all internal pages.
+     * Delegates to {@link setUrlOrderOp}.
+     */
+    async setUrlOrder() {
+        await setUrlOrderOp(this.#instance);
+    }
+    /**
+     * 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.
+     */
+    async updateConfig(patch) {
+        return emitErrorAndRetry(this, 'Database.updateConfig', async () => await updateConfigOp(this.#instance, patch), retrySetting);
+    }
+    /**
+     * 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`.
+     * @returns The database `pageId` of the inserted/updated row.
+     */
+    async updatePage(page, writeHtml, isTarget, source) {
+        return emitErrorAndRetry(this, 'Database.updatePage', async () => await updatePageOp(this.#instance, this.#writeRefCaches, page, writeHtml, isTarget, source), retrySetting);
+    }
+    /**
+     * Initializes the database schema if tables do not exist, then runs
+     * lightweight migrations; in read-only mode both are skipped.
+     * Delegates to {@link initOp}.
+     * @param readOnly - When true, skip schema init + migrations.
+     */
+    async #init(readOnly) {
+        await initOp(this.#instance, readOnly);
+    }
+    /**
+     * 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 async connect(options) {
+        if (options.readOnly) {
+            if (!existsSync(path.dirname(options.filename))) {
+                throw new Error(`Cannot open archive read-only: parent directory disappeared (${path.dirname(options.filename)}). The source may have been removed by another process.`);
+            }
+            if (!existsSync(options.filename)) {
+                throw new Error(`Cannot open archive read-only: database file missing (${options.filename}). The source may have been removed by another process.`);
+            }
+        }
+        else {
+            mkdir(options.filename);
+        }
+        const db = new Database(options);
+        await db.#init(options.readOnly ?? false);
+        return db;
     }
-    return payload;
 }
-/**
- * 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).
- *
- * Use the static {@link Database.connect} factory method to create instances.
- * The constructor is private.
- */
-let Database = (() => {
-    let _classSuper = EventEmitter;
-    let _instanceExtraInitializers = [];
-    let _getAnchorsOnPage_decorators;
-    let _getBaseUrl_decorators;
-    let _getConfig_decorators;
-    let _getCrawlingState_decorators;
-    let _getExistingPageUrls_decorators;
-    let _getExistingResourceUrls_decorators;
-    let _getHtmlOfPageById_decorators;
-    let _getJsonLdOfPage_decorators;
-    let _getName_decorators;
-    let _getPageCount_decorators;
-    let _getPages_decorators;
-    let _getPagesWithRels_decorators;
-    let _getRedirectsForPages_decorators;
-    let _getReferrersOfPage_decorators;
-    let _getReferrersOfResource_decorators;
-    let _getResourceByUrl_decorators;
-    let _getResources_decorators;
-    let _getResourceUrlList_decorators;
-    let _getScrapedHtmlPageCount_decorators;
-    let _getTagsOfPage_decorators;
-    let _insertCrawlError_decorators;
-    let _insertPageError_decorators;
-    let _insertResource_decorators;
-    let _insertResourceReferrers_decorators;
-    let _recordRedirect_decorators;
-    let _repromoteExternalPages_decorators;
-    let _resetFailedPages_decorators;
-    let _setConfig_decorators;
-    let _setSkippedPage_decorators;
-    let _updateConfig_decorators;
-    let _updatePage_decorators;
-    return class Database extends _classSuper {
-        static {
-            const _metadata = typeof Symbol === "function" && Symbol.metadata ? Object.create(_classSuper[Symbol.metadata] ?? null) : void 0;
-            _getAnchorsOnPage_decorators = [ErrorEmitter(), retry(retrySetting)];
-            _getBaseUrl_decorators = [ErrorEmitter(), retry(retrySetting)];
-            _getConfig_decorators = [ErrorEmitter(), retry(retrySetting)];
-            _getCrawlingState_decorators = [ErrorEmitter(), retry(retrySetting)];
-            _getExistingPageUrls_decorators = [ErrorEmitter()];
-            _getExistingResourceUrls_decorators = [ErrorEmitter()];
-            _getHtmlOfPageById_decorators = [ErrorEmitter(), retry(retrySetting)];
-            _getJsonLdOfPage_decorators = [ErrorEmitter(), retry(retrySetting)];
-            _getName_decorators = [ErrorEmitter(), retry(retrySetting)];
-            _getPageCount_decorators = [ErrorEmitter(), retry(retrySetting)];
-            _getPages_decorators = [ErrorEmitter(), retry(retrySetting)];
-            _getPagesWithRels_decorators = [ErrorEmitter(), retry(retrySetting)];
-            _getRedirectsForPages_decorators = [ErrorEmitter(), retry(retrySetting)];
-            _getReferrersOfPage_decorators = [ErrorEmitter(), retry(retrySetting)];
-            _getReferrersOfResource_decorators = [ErrorEmitter(), retry(retrySetting)];
-            _getResourceByUrl_decorators = [retry(retrySetting)];
-            _getResources_decorators = [ErrorEmitter(), retry(retrySetting)];
-            _getResourceUrlList_decorators = [ErrorEmitter(), retry(retrySetting)];
-            _getScrapedHtmlPageCount_decorators = [ErrorEmitter(), retry(retrySetting)];
-            _getTagsOfPage_decorators = [ErrorEmitter(), retry(retrySetting)];
-            _insertCrawlError_decorators = [ErrorEmitter(), retry(retrySetting)];
-            _insertPageError_decorators = [ErrorEmitter(), retry(retrySetting)];
-            _insertResource_decorators = [ErrorEmitter(), retry(retrySetting)];
-            _insertResourceReferrers_decorators = [ErrorEmitter(), retry(retrySetting)];
-            _recordRedirect_decorators = [ErrorEmitter(), retry(retrySetting)];
-            _repromoteExternalPages_decorators = [ErrorEmitter(), retry(retrySetting)];
-            _resetFailedPages_decorators = [ErrorEmitter(), retry(retrySetting)];
-            _setConfig_decorators = [ErrorEmitter(), retry(retrySetting)];
-            _setSkippedPage_decorators = [ErrorEmitter(), retry(retrySetting)];
-            _updateConfig_decorators = [ErrorEmitter(), retry(retrySetting)];
-            _updatePage_decorators = [ErrorEmitter(), retry(retrySetting)];
-            __esDecorate(this, null, _getAnchorsOnPage_decorators, { kind: "method", name: "getAnchorsOnPage", static: false, private: false, access: { has: obj => "getAnchorsOnPage" in obj, get: obj => obj.getAnchorsOnPage }, metadata: _metadata }, null, _instanceExtraInitializers);
-            __esDecorate(this, null, _getBaseUrl_decorators, { kind: "method", name: "getBaseUrl", static: false, private: false, access: { has: obj => "getBaseUrl" in obj, get: obj => obj.getBaseUrl }, metadata: _metadata }, null, _instanceExtraInitializers);
-            __esDecorate(this, null, _getConfig_decorators, { kind: "method", name: "getConfig", static: false, private: false, access: { has: obj => "getConfig" in obj, get: obj => obj.getConfig }, metadata: _metadata }, null, _instanceExtraInitializers);
-            __esDecorate(this, null, _getCrawlingState_decorators, { kind: "method", name: "getCrawlingState", static: false, private: false, access: { has: obj => "getCrawlingState" in obj, get: obj => obj.getCrawlingState }, metadata: _metadata }, null, _instanceExtraInitializers);
-            __esDecorate(this, null, _getExistingPageUrls_decorators, { kind: "method", name: "getExistingPageUrls", static: false, private: false, access: { has: obj => "getExistingPageUrls" in obj, get: obj => obj.getExistingPageUrls }, metadata: _metadata }, null, _instanceExtraInitializers);
-            __esDecorate(this, null, _getExistingResourceUrls_decorators, { kind: "method", name: "getExistingResourceUrls", static: false, private: false, access: { has: obj => "getExistingResourceUrls" in obj, get: obj => obj.getExistingResourceUrls }, metadata: _metadata }, null, _instanceExtraInitializers);
-            __esDecorate(this, null, _getHtmlOfPageById_decorators, { kind: "method", name: "getHtmlOfPageById", static: false, private: false, access: { has: obj => "getHtmlOfPageById" in obj, get: obj => obj.getHtmlOfPageById }, metadata: _metadata }, null, _instanceExtraInitializers);
-            __esDecorate(this, null, _getJsonLdOfPage_decorators, { kind: "method", name: "getJsonLdOfPage", static: false, private: false, access: { has: obj => "getJsonLdOfPage" in obj, get: obj => obj.getJsonLdOfPage }, metadata: _metadata }, null, _instanceExtraInitializers);
-            __esDecorate(this, null, _getName_decorators, { kind: "method", name: "getName", static: false, private: false, access: { has: obj => "getName" in obj, get: obj => obj.getName }, metadata: _metadata }, null, _instanceExtraInitializers);
-            __esDecorate(this, null, _getPageCount_decorators, { kind: "method", name: "getPageCount", static: false, private: false, access: { has: obj => "getPageCount" in obj, get: obj => obj.getPageCount }, metadata: _metadata }, null, _instanceExtraInitializers);
-            __esDecorate(this, null, _getPages_decorators, { kind: "method", name: "getPages", static: false, private: false, access: { has: obj => "getPages" in obj, get: obj => obj.getPages }, metadata: _metadata }, null, _instanceExtraInitializers);
-            __esDecorate(this, null, _getPagesWithRels_decorators, { kind: "method", name: "getPagesWithRels", static: false, private: false, access: { has: obj => "getPagesWithRels" in obj, get: obj => obj.getPagesWithRels }, metadata: _metadata }, null, _instanceExtraInitializers);
-            __esDecorate(this, null, _getRedirectsForPages_decorators, { kind: "method", name: "getRedirectsForPages", static: false, private: false, access: { has: obj => "getRedirectsForPages" in obj, get: obj => obj.getRedirectsForPages }, metadata: _metadata }, null, _instanceExtraInitializers);
-            __esDecorate(this, null, _getReferrersOfPage_decorators, { kind: "method", name: "getReferrersOfPage", static: false, private: false, access: { has: obj => "getReferrersOfPage" in obj, get: obj => obj.getReferrersOfPage }, metadata: _metadata }, null, _instanceExtraInitializers);
-            __esDecorate(this, null, _getReferrersOfResource_decorators, { kind: "method", name: "getReferrersOfResource", static: false, private: false, access: { has: obj => "getReferrersOfResource" in obj, get: obj => obj.getReferrersOfResource }, metadata: _metadata }, null, _instanceExtraInitializers);
-            __esDecorate(this, null, _getResourceByUrl_decorators, { kind: "method", name: "getResourceByUrl", static: false, private: false, access: { has: obj => "getResourceByUrl" in obj, get: obj => obj.getResourceByUrl }, metadata: _metadata }, null, _instanceExtraInitializers);
-            __esDecorate(this, null, _getResources_decorators, { kind: "method", name: "getResources", static: false, private: false, access: { has: obj => "getResources" in obj, get: obj => obj.getResources }, metadata: _metadata }, null, _instanceExtraInitializers);
-            __esDecorate(this, null, _getResourceUrlList_decorators, { kind: "method", name: "getResourceUrlList", static: false, private: false, access: { has: obj => "getResourceUrlList" in obj, get: obj => obj.getResourceUrlList }, metadata: _metadata }, null, _instanceExtraInitializers);
-            __esDecorate(this, null, _getScrapedHtmlPageCount_decorators, { kind: "method", name: "getScrapedHtmlPageCount", static: false, private: false, access: { has: obj => "getScrapedHtmlPageCount" in obj, get: obj => obj.getScrapedHtmlPageCount }, metadata: _metadata }, null, _instanceExtraInitializers);
-            __esDecorate(this, null, _getTagsOfPage_decorators, { kind: "method", name: "getTagsOfPage", static: false, private: false, access: { has: obj => "getTagsOfPage" in obj, get: obj => obj.getTagsOfPage }, metadata: _metadata }, null, _instanceExtraInitializers);
-            __esDecorate(this, null, _insertCrawlError_decorators, { kind: "method", name: "insertCrawlError", static: false, private: false, access: { has: obj => "insertCrawlError" in obj, get: obj => obj.insertCrawlError }, metadata: _metadata }, null, _instanceExtraInitializers);
-            __esDecorate(this, null, _insertPageError_decorators, { kind: "method", name: "insertPageError", static: false, private: false, access: { has: obj => "insertPageError" in obj, get: obj => obj.insertPageError }, metadata: _metadata }, null, _instanceExtraInitializers);
-            __esDecorate(this, null, _insertResource_decorators, { kind: "method", name: "insertResource", static: false, private: false, access: { has: obj => "insertResource" in obj, get: obj => obj.insertResource }, metadata: _metadata }, null, _instanceExtraInitializers);
-            __esDecorate(this, null, _insertResourceReferrers_decorators, { kind: "method", name: "insertResourceReferrers", static: false, private: false, access: { has: obj => "insertResourceReferrers" in obj, get: obj => obj.insertResourceReferrers }, metadata: _metadata }, null, _instanceExtraInitializers);
-            __esDecorate(this, null, _recordRedirect_decorators, { kind: "method", name: "recordRedirect", static: false, private: false, access: { has: obj => "recordRedirect" in obj, get: obj => obj.recordRedirect }, metadata: _metadata }, null, _instanceExtraInitializers);
-            __esDecorate(this, null, _repromoteExternalPages_decorators, { kind: "method", name: "repromoteExternalPages", static: false, private: false, access: { has: obj => "repromoteExternalPages" in obj, get: obj => obj.repromoteExternalPages }, metadata: _metadata }, null, _instanceExtraInitializers);
-            __esDecorate(this, null, _resetFailedPages_decorators, { kind: "method", name: "resetFailedPages", static: false, private: false, access: { has: obj => "resetFailedPages" in obj, get: obj => obj.resetFailedPages }, metadata: _metadata }, null, _instanceExtraInitializers);
-            __esDecorate(this, null, _setConfig_decorators, { kind: "method", name: "setConfig", static: false, private: false, access: { has: obj => "setConfig" in obj, get: obj => obj.setConfig }, metadata: _metadata }, null, _instanceExtraInitializers);
-            __esDecorate(this, null, _setSkippedPage_decorators, { kind: "method", name: "setSkippedPage", static: false, private: false, access: { has: obj => "setSkippedPage" in obj, get: obj => obj.setSkippedPage }, metadata: _metadata }, null, _instanceExtraInitializers);
-            __esDecorate(this, null, _updateConfig_decorators, { kind: "method", name: "updateConfig", static: false, private: false, access: { has: obj => "updateConfig" in obj, get: obj => obj.updateConfig }, metadata: _metadata }, null, _instanceExtraInitializers);
-            __esDecorate(this, null, _updatePage_decorators, { kind: "method", name: "updatePage", static: false, private: false, access: { has: obj => "updatePage" in obj, get: obj => obj.updatePage }, metadata: _metadata }, null, _instanceExtraInitializers);
-            if (_metadata) Object.defineProperty(this, Symbol.metadata, { enumerable: true, configurable: true, writable: true, value: _metadata });
-        }
-        /** The Knex query builder instance connected to the SQLite database. */
-        #instance = __runInitializers(this, _instanceExtraInitializers);
-        // eslint-disable-next-line no-restricted-syntax
-        constructor(options) {
-            super();
-            this.#instance = knex({
-                client: LibsqlDialect,
-                connection: {
-                    filename: options.filename,
-                },
-                useNullAsDefault: true,
-                pool: {
-                    acquireTimeoutMillis: 600_000,
-                },
-            });
-        }
-        /**
-         * 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.
-         */
-        async addOrderField() {
-            const hasColumn = await this.#instance.schema.hasColumn('pages', 'order');
-            if (hasColumn) {
-                return;
-            }
-            return await this.#instance.schema.table('pages', (t) => {
-                t.integer('order').unsigned().nullable().defaultTo(null);
-            });
-        }
-        /**
-         * 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.
-         */
-        async checkpoint() {
-            await this.#instance.raw('PRAGMA wal_checkpoint(TRUNCATE)');
-        }
-        /**
-         * Destroys the database connection, releasing all pooled resources.
-         */
-        async destroy() {
-            await this.#instance.destroy();
-        }
-        /**
-         * Retrieves all anchors (outgoing links) on a specific page.
-         * Joins the `anchors` table with the `pages` table to resolve link destinations.
-         * @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.
-         */
-        async getAnchorsOnPage(pageId) {
-            const res = await this.#instance
-                .select('pages.url', 'pages.title', 'pages.status', 'pages.statusText', 'pages.contentType', 'anchors.hash', 'anchors.textContent')
-                .from('anchors')
-                .join('pages', 'anchors.hrefId', '=', 'pages.id')
-                .where('anchors.pageId', pageId);
-            return res;
-        }
-        /**
-         * Retrieves the base URL of the crawl session from the `info` table.
-         * @returns The base URL string.
-         * @throws {Error} If no base URL is found in the database.
-         */
-        async getBaseUrl() {
-            const selected = await this.#instance.select('baseUrl').from('info');
-            if (!selected[0]) {
-                throw new Error('No baseUrl');
-            }
-            const [{ baseUrl }] = selected;
-            return baseUrl || '';
-        }
-        /**
-         * Retrieves the full crawl configuration from the `info` table.
-         * Deserializes JSON-encoded fields (`roots`, `excludes`, `excludeKeywords`, `excludeUrls`).
-         * @returns The parsed {@link Config} object.
-         * @throws {Error} If no configuration is found in the database.
-         */
-        async getConfig() {
-            const [config] = await this.#instance.select('*').from('info');
-            if (!config) {
-                throw new Error('No config');
-            }
-            const opt = {
-                ...config,
-                excludes: getJSON(config.excludes, []),
-                excludeKeywords: getJSON(config.excludeKeywords, []),
-                excludeUrls: getJSON(config.excludeUrls, []),
-                roots: getJSON(config.roots, []),
-                retry: config.retry ?? 3,
-            };
-            // @ts-expect-error — `id` is the primary key, not part of the public Config shape
-            delete opt.id;
-            dbLog('Table `info`: %O => %O', config, opt);
-            return opt;
-        }
-        /**
-         * Retrieves the current crawling state by listing scraped and pending URLs.
-         * @returns An object with `scraped` (completed URLs) and `pending` (remaining URLs) arrays.
-         */
-        async getCrawlingState() {
-            const ex = (r) => r.url;
-            const $scraped = await this.#instance
-                .select('url')
-                .from('pages')
-                .where('scraped', 1);
-            const scraped = $scraped.map(ex);
-            const $pending = await this.#instance
-                .select('url')
-                .from('pages')
-                .where('scraped', 0);
-            const pending = $pending.map(ex);
-            return {
-                scraped,
-                pending,
-            };
-        }
-        /**
-         * 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).
-         * @param urls - URL strings to probe (already in `withoutHashAndAuth` form).
-         * @returns URLs found in `pages`. Order is not preserved.
-         */
-        async getExistingPageUrls(urls) {
-            if (urls.length === 0) {
-                return [];
-            }
-            const found = [];
-            await eachSplitted([...urls], 500, async (chunk) => {
-                const rows = await this.#instance
-                    .select('url')
-                    .from('pages')
-                    .whereIn('url', chunk);
-                for (const row of rows) {
-                    found.push(row.url);
-                }
-            });
-            return found;
-        }
-        /**
-         * Return the subset of `urls` that already exist in the `resources` table.
-         * See {@link Database.getExistingPageUrls} — same chunking strategy.
-         * @param urls - URL strings to probe.
-         * @returns URLs found in `resources`.
-         */
-        async getExistingResourceUrls(urls) {
-            if (urls.length === 0) {
-                return [];
-            }
-            const found = [];
-            await eachSplitted([...urls], 500, async (chunk) => {
-                const rows = await this.#instance
-                    .select('url')
-                    .from('resources')
-                    .whereIn('url', chunk);
-                for (const row of rows) {
-                    found.push(row.url);
-                }
-            });
-            return found;
-        }
-        /**
-         * 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.
-         * @param pageId - The database ID of the page.
-         * @returns The decompressed HTML string, or `null` if no snapshot is stored.
-         */
-        async getHtmlOfPageById(pageId) {
-            const row = await this.#instance
-                .from('page_html_ref')
-                .join('page_html_blobs', 'page_html_ref.hash', '=', 'page_html_blobs.hash')
-                .select('page_html_blobs.body as body', 'page_html_blobs.codec as codec')
-                .where('page_html_ref.page_id', pageId)
-                .first();
-            if (!row) {
-                return null;
-            }
-            return decodeStoredBlob(row.body, row.codec);
-        }
-        /**
-         * 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.
-         * @param pageId
-         */
-        async getJsonLdOfPage(pageId) {
-            const rows = await this.#instance
-                .select('id', 'pageId', 'kind', 'type', 'raw', 'parsed', 'parseError')
-                .from('page_jsonld')
-                .where('pageId', pageId)
-                .orderBy('id', 'asc');
-            return rows.map((r) => ({
-                id: r.id,
-                pageId: r.pageId,
-                kind: r.kind === 'speculationrules' ? 'speculationrules' : 'ld+json',
-                type: r.type,
-                raw: r.raw,
-                parsed: r.parsed === null ? null : safeParseJson(r.parsed),
-                parseError: r.parseError,
-            }));
-        }
-        /**
-         * 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() {
-            return this.#instance;
-        }
-        /**
-         * Retrieves the crawl session name from the `info` table.
-         * @returns The name string.
-         * @throws {Error} If no name is found in the database.
-         */
-        async getName() {
-            const selected = await this.#instance.select('name').from('info');
-            if (!selected[0]) {
-                throw new Error('No name');
-            }
-            const [{ name }] = selected;
-            return name;
-        }
-        /**
-         * Counts the total number of pages in the database.
-         * @returns The total page count.
-         * @throws {Error} If the count query fails.
-         */
-        async getPageCount() {
-            const selected = await this.#instance.count('id').from('pages');
-            if (!selected[0]) {
-                throw new Error('No count');
-            }
-            // @ts-expect-error
-            const count = selected[0]['count(`id`)'];
-            dbLog('Number of pages: %d', count);
-            return count;
-        }
-        /**
-         * Retrieves pages from the database with optional filtering, pagination via offset and limit.
-         * @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.
-         */
-        async getPages(filter, offset = 0, limit = 100_000) {
-            const q = this.#instance.select('*').from('pages');
-            switch (filter) {
-                case 'page': {
-                    return q
-                        .where({
-                        contentType: 'text/html',
-                        isTarget: 1,
-                    })
-                        .limit(limit)
-                        .offset(offset);
-                }
-                case 'page-included-no-target': {
-                    return q
-                        .where({
-                        contentType: 'text/html',
-                    })
-                        .limit(limit)
-                        .offset(offset);
-                }
-                case 'external-page': {
-                    return q
-                        .where({
-                        contentType: 'text/html',
-                        isExternal: 1,
-                    })
-                        .limit(limit)
-                        .offset(offset);
-                }
-                case 'internal-page': {
-                    return q
-                        .where({
-                        contentType: 'text/html',
-                        isExternal: 0,
-                    })
-                        .limit(limit)
-                        .offset(offset);
-                }
-                case 'no-page': {
-                    return q
-                        .whereNull('contentType')
-                        .orWhereNot({
-                        contentType: 'text/html',
-                    })
-                        .limit(limit)
-                        .offset(offset);
-                }
-                case 'external-no-page': {
-                    return q
-                        .where((qb) => {
-                        qb.whereNull('contentType').orWhereNot({
-                            contentType: 'text/html',
-                        });
-                    })
-                        .andWhere({
-                        isExternal: 1,
-                    })
-                        .limit(limit)
-                        .offset(offset);
-                }
-                case 'internal-no-page': {
-                    return q
-                        .where((qb) => {
-                        qb.whereNull('contentType').orWhereNot({
-                            contentType: 'text/html',
-                        });
-                    })
-                        .andWhere({
-                        isExternal: 0,
-                    })
-                        .limit(limit)
-                        .offset(offset);
-                }
-            }
-            return q.limit(limit).offset(offset);
-        }
-        /**
-         * 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.
-         * @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.
-         */
-        async getPagesWithRels(offset, limit) {
-            await this.addOrderField();
-            await this.setUrlOrder();
-            dbLog('Get Pages');
-            const pages = await this.#instance
-                .select('*')
-                .from('pages')
-                .orderByRaw('`order` ASC NULLS LAST')
-                .whereNull('redirectDestId')
-                .limit(limit)
-                .offset(offset);
-            // When empty
-            if (pages.length === 0) {
-                return {
-                    pages: [],
-                    redirects: [],
-                    referrers: [],
-                    anchors: [],
-                };
-            }
-            dbLog('Get Pages: Redirects');
-            const redirects = await this.#instance
-                .with('limitedPages', limitedPageIds(limit, offset))
-                .with('redirect', redirectTable(false))
-                .select('id as pageId', 'from', 'fromId')
-                .from('redirect')
-                // Filter
-                .join('limitedPages', 'redirect.toId', '=', 'limitedPages.id')
-                // Sort
-                .orderBy('id', 'asc');
-            dbLog('Get Pages: Anchors');
-            const anchors = await this.#instance
-                .with('limitedPages', limitedPageIds(limit, offset))
-                .with('redirect', redirectTable())
-                .select('limitedPages.id as pageId', 'href.url', 'redirect.from as href', 'href.isExternal', 'href.title', 'href.status', 'href.statusText', 'href.contentType', 'anchors.hash', 'anchors.textContent')
-                .from('anchors')
-                // Filters
-                .join('limitedPages', 'anchors.pageId', '=', 'limitedPages.id')
-                // Resolves redirect
-                .join('redirect', 'anchors.hrefId', '=', 'redirect.fromId')
-                // Target
-                .join('pages as href', 'redirect.toId', '=', 'href.id')
-                // Sort
-                .orderBy('anchors.id', 'asc');
-            dbLog('Get Pages: Referrers');
-            const referrers = await this.#instance
-                .with('limitedPages', limitedPageIds(limit, offset))
-                .with('redirect', redirectTable())
-                .select('redirect.toId as pageId', 'referrer.url', 'redirect.from as through', 'redirect.fromId as throughId', 'anchors.hash', 'anchors.textContent')
-                .from('anchors')
-                // Resolves redirect
-                .join('redirect', 'anchors.hrefId', '=', 'redirect.fromId')
-                // Referrer
-                .join('pages as referrer', 'anchors.pageId', '=', 'referrer.id')
-                // Filters
-                .join('limitedPages', 'redirect.toId', '=', 'limitedPages.id')
-                // Sort
-                .orderBy('anchors.id', 'asc');
-            dbLog('Get Pages: Done');
-            return {
-                pages,
-                redirects,
-                anchors,
-                referrers,
-            };
-        }
-        /**
-         * Retrieves redirect sources for the given page IDs in bulk.
-         * @param pageIds - The database IDs of the destination pages.
-         * @returns An array of {@link DB_Redirect} records mapping destination pages to their redirect sources.
-         */
-        async getRedirectsForPages(pageIds) {
-            if (pageIds.length === 0)
-                return [];
-            return this.#instance
-                .select('redirectDestId as pageId', 'url as from', 'id as fromId')
-                .from('pages')
-                .whereIn('redirectDestId', pageIds);
-        }
-        /**
-         * 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.
-         * @param pageId - The database ID of the target page.
-         * @returns An array of referrer records with URL, hash, and text content.
-         */
-        async getReferrersOfPage(pageId) {
-            const res = await this.#instance
-                .select('referrer.url', 
-            // `through` / `throughId` = the URL the anchor actually pointed at (the
-            // redirect source, e.g. `http://x`), mirroring `getPagesWithRels`'
-            // `redirect.from` / `redirect.fromId`. Lets report code print the
-            // "[REDIRECTED FROM]" note even on this (non-preloaded) referrer path.
-            'target.url as through', 'target.id as throughId', 'anchors.hash', 'anchors.textContent')
-                .from('anchors')
-                .join('pages as referrer', 'anchors.pageId', '=', 'referrer.id')
-                .join('pages as target', 'anchors.hrefId', '=', 'target.id')
-                .whereRaw('coalesce("target"."redirectDestId", "target"."id") = ?', [pageId]);
-            return res;
-        }
-        /**
-         * Retrieves the page URLs that reference a specific resource.
-         * @param id - The database ID of the resource.
-         * @returns An array of page URL strings that reference the resource.
-         */
-        async getReferrersOfResource(id) {
-            const res = await this.#instance
-                .select('pages.url')
-                .from('resources-referrers')
-                .join('resources', 'resources.id', '=', 'resources-referrers.resourceId')
-                .join('pages', 'pages.id', '=', 'resources-referrers.pageId')
-                .where('resources.id', id);
-            return res.map((r) => r.url);
-        }
-        /**
-         * 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.
-         *
-         * Deliberately NOT decorated with `@ErrorEmitter`: 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.
-         */
-        async getResourceByUrl(urls) {
-            const res = await this.#instance
-                .select('*')
-                .from('resources')
-                .whereIn('url', [...urls])
-                .first();
-            return res ?? null;
-        }
-        /**
-         * Retrieves all sub-resources from the `resources` table.
-         * @returns An array of raw {@link DB_Resource} rows.
-         */
-        async getResources() {
-            return this.#instance.select('*').from('resources');
-        }
-        /**
-         * Retrieves a flat list of all resource URLs from the `resources` table.
-         * @returns An array of resource URL strings.
-         */
-        async getResourceUrlList() {
-            const res = await this.#instance.select('url').from('resources');
-            return res.map((r) => r.url);
-        }
-        /**
-         * 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`.
-         * @returns The number of `text/html` rows with `isTarget = 1` and `scraped = 1`.
-         */
-        async getScrapedHtmlPageCount() {
-            const [row] = await this.#instance
-                .from('pages')
-                .where('isTarget', 1)
-                .andWhere('scraped', 1)
-                .andWhere('contentType', 'text/html')
-                .count('* as count');
-            return row ? Number(row.count) : 0;
-        }
-        /**
-         * 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`.
-         * @param pageId
-         */
-        async getTagsOfPage(pageId) {
-            const rows = await this.#instance
-                .select('id', 'pageId', 'provider', 'category', 'externalId', 'version', 'confidence', 'categories', 'sources')
-                .from('page_tags')
-                .where('pageId', pageId)
-                .orderBy('id', 'asc');
-            return rows.map((r) => ({
-                id: r.id,
-                pageId: r.pageId,
-                provider: r.provider,
-                category: r.category,
-                externalId: r.externalId,
-                version: r.version,
-                confidence: r.confidence,
-                categories: r.categories === null ? [] : (safeParseJson(r.categories) ?? []),
-                sources: r.sources === null ? [] : (safeParseJson(r.sources) ?? []),
-            }));
-        }
-        /**
-         * 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.
-         * @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.
-         */
-        async insertCrawlError(url, message, isExternal = false) {
-            await this.#instance('crawl_errors').insert({
-                url,
-                isExternal: isExternal ? 1 : 0,
-                message,
-                createdAt: Date.now(),
-            });
-        }
-        /**
-         * 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).
-         * @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`.
-         */
-        async insertPageError(url, phase, message, isExternal = false) {
-            const pageId = await this.#getIdByUrl(url, isExternal ? 1 : 0);
-            await this.#instance('page_errors').insert({
-                pageId,
-                phase,
-                message,
-                createdAt: Date.now(),
-            });
-        }
-        /**
-         * 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).
-         * @param resource - The resource data to insert.
-         * @param source - Provenance label for new rows. `undefined` leaves the DB DEFAULT (`'crawled'`).
-         */
-        async insertResource(resource, source) {
-            await this.#instance
-                .from('resources')
-                .insert({
-                url: resource.url.href,
-                isExternal: resource.isExternal ? 1 : 0,
-                status: resource.status,
-                statusText: resource.statusText,
-                // Canonicalize like `pages.contentType` (see #insertPage) so resource
-                // content-type filters / dedupe keys are case- and whitespace-stable.
-                contentType: normalizeContentType(resource.contentType),
-                contentLength: resource.contentLength,
-                compress: resource.compress || 0,
-                cdn: resource.cdn || 0,
-                responseHeaders: JSON.stringify(resource.headers),
-                ...(source === undefined ? {} : { source }),
-            })
-                .onConflict('url')
-                .ignore();
-        }
-        /**
-         * Inserts a referrer relationship between a resource and a page into the
-         * `resources-referrers` table. Silently skips if the resource is not found.
-         * @param src - The URL of the resource.
-         * @param pageUrl - The URL of the page that references the resource.
-         */
-        async insertResourceReferrers(src, pageUrl) {
-            const selected = await this.#instance
-                .select('id')
-                .from('resources')
-                .where('url', src);
-            if (!selected[0]) {
-                // Ignore when the resource is not found
-                return;
-            }
-            const [{ id: resourceId }] = selected;
-            const pageId = await this.#getIdByUrl(pageUrl);
-            await this.#instance('resources-referrers')
-                .insert({
-                resourceId,
-                pageId,
-            })
-                .onConflict(['resourceId', 'pageId'])
-                .ignore();
-        }
-        /**
-         * 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.
-         * @param page - HEAD-resolved page data carrying the redirect chain. Its
-         *   `anchorList` / `imageList` are ignored (a redirect source owns no content).
-         */
-        async recordRedirect(page) {
-            const { destUrl, sources } = resolveRedirectChain(page.url.withoutHashAndAuth, page.redirectPaths);
-            // No redirect chain (the URL is itself the already-rendered destination,
-            // reached both directly and via a redirect) → there is no edge to write.
-            // Returning here avoids opening a transaction and, crucially, avoids
-            // `#getIdByUrl` inserting a content-less placeholder row for a destination
-            // that may not have been written yet.
-            if (sources.length === 0) {
-                return;
-            }
-            const destUrlObject = parseUrl(destUrl);
-            if (!destUrlObject) {
-                // A malformed redirect target should not abort the whole crawl (this
-                // runs inside the WriteQueue, whose rejection aborts the run). Recording
-                // a single redirect edge is best-effort, so skip it and move on. Unlike
-                // `updatePage`, there is no page content at stake here.
-                dbLog('recordRedirect: skip malformed destination URL: %s', destUrl);
-                return;
-            }
-            await this.#instance.transaction(async (trx) => {
-                const destId = await this.#getIdByUrl(destUrlObject.withoutHashAndAuth, undefined, trx);
-                await this.#linkRedirectSources(trx, sources, destId, destUrlObject.withoutHashAndAuth, page.isExternal);
-            });
-        }
-        /**
-         * 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 scopes - The hostname-indexed scope map after the new roots are merged.
-         * @param options - URL parsing options forwarded to {@link findScopeEntry}.
-         * @returns The URLs of the pages that were promoted.
-         */
-        async repromoteExternalPages(scopes, options) {
-            if (scopes.size === 0) {
-                return [];
-            }
-            const candidates = await this.#instance
-                .select('id', 'url')
-                .from('pages')
-                .where('isExternal', 1);
-            const promotedIds = [];
-            const promotedUrls = [];
-            for (const row of candidates) {
-                const parsed = parseUrl(row.url, options);
-                if (!parsed) {
-                    continue;
-                }
-                if (findScopeEntry(parsed, scopes, options) === null) {
-                    continue;
-                }
-                promotedIds.push(row.id);
-                promotedUrls.push(row.url);
-            }
-            if (promotedIds.length === 0) {
-                return [];
-            }
-            const chunkSize = 500;
-            const metaReset = makeMetaResetPayload();
-            for (let i = 0; i < promotedIds.length; i += chunkSize) {
-                const chunk = promotedIds.slice(i, i + chunkSize);
-                await this.#instance('pages')
-                    .whereIn('id', chunk)
-                    .update({
-                    scraped: 0,
-                    isExternal: 0,
-                    isSkipped: 0,
-                    skipReason: null,
-                    status: null,
-                    statusText: null,
-                    contentType: null,
-                    contentLength: null,
-                    responseHeaders: '{}',
-                    redirectDestId: null,
-                    // Null every flat meta column + denormalised aggregates +
-                    // meta_extras. `firstCrawledAt` / `lastCrawledAt` are
-                    // deliberately omitted from META_NULLABLE_COLUMNS — the
-                    // last-success timestamp survives the demotion.
-                    ...metaReset,
-                });
-                // Clear the prior crawl's data for the repromoted pages. `updatePage`
-                // also replaces anchors/images/tags/jsonld when it re-scrapes them, but
-                // only when the new scrape is non-empty — so this pre-clear is still
-                // load-bearing for pages that get repromoted but then re-scrape to
-                // nothing (or are never reached again), and it is the only place
-                // `resources-referrers` is cleared. The HTML body ref is also cleared
-                // so a repromoted page whose re-scrape ends up degraded does not keep
-                // its old external-render snapshot. `page_tags` / `page_jsonld` are
-                // cleared explicitly even though both tables also carry ON DELETE
-                // CASCADE — we keep the existing pattern of explicit chunked DELETEs
-                // rather than relying on CASCADE indirectly (and would not cascade
-                // anyway: the parent `pages` row is updated, not deleted). Orphan
-                // blobs in `page_html_blobs` are left behind; #23 will add GC.
-                await this.#instance('anchors').whereIn('pageId', chunk).delete();
-                await this.#instance('images').whereIn('pageId', chunk).delete();
-                await this.#instance('resources-referrers').whereIn('pageId', chunk).delete();
-                await this.#instance('page_html_ref').whereIn('page_id', chunk).delete();
-                await this.#instance('page_tags').whereIn('pageId', chunk).delete();
-                await this.#instance('page_jsonld').whereIn('pageId', chunk).delete();
-            }
-            dbLog('Repromoted %d external pages back to pending', promotedUrls.length);
-            return promotedUrls;
-        }
-        /**
-         * 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`.
-         * @returns The URLs of the pages that were reset to pending.
-         */
-        async resetFailedPages() {
-            const candidates = await this.#instance
-                .select('id', 'url')
-                .from('pages')
-                .where('scraped', 1)
-                .whereNull('redirectDestId')
-                .where((qb) => {
-                qb.where('isSkipped', 0).orWhereNull('isSkipped');
-            })
-                .where((qb) => {
-                qb.whereNull('status')
-                    .orWhere('status', -1)
-                    .orWhereNull('contentType')
-                    .orWhereBetween('status', [500, 599]);
-            });
-            if (candidates.length === 0) {
-                return [];
-            }
-            const ids = candidates.map((row) => row.id);
-            const urls = candidates.map((row) => row.url);
-            const chunkSize = 500;
-            const metaReset = makeMetaResetPayload();
-            for (let i = 0; i < ids.length; i += chunkSize) {
-                const chunk = ids.slice(i, i + chunkSize);
-                await this.#instance('pages')
-                    .whereIn('id', chunk)
-                    .update({
-                    scraped: 0,
-                    status: null,
-                    statusText: null,
-                    contentType: null,
-                    contentLength: null,
-                    responseHeaders: '{}',
-                    // Null every flat meta column + denormalised aggregates +
-                    // meta_extras. `firstCrawledAt` / `lastCrawledAt` are
-                    // deliberately omitted from META_NULLABLE_COLUMNS so the
-                    // last-success timestamp records survive the demotion (the
-                    // within-archive observation axis for #11/#17/#19).
-                    ...metaReset,
-                });
-                // Clear the prior crawl's per-page data so the re-scrape starts clean.
-                // `updatePage` only replaces anchors/images/tags/jsonld when the new
-                // scrape is non-empty, so this pre-clear is load-bearing for pages that
-                // reset but then fail again (or are never reached), and it is the only
-                // place `resources-referrers` and `page_errors` are cleared. The HTML
-                // body ref is also cleared so a previously-rendered page that now fails
-                // to re-scrape does not keep its old snapshot.
-                await this.#instance('anchors').whereIn('pageId', chunk).delete();
-                await this.#instance('images').whereIn('pageId', chunk).delete();
-                await this.#instance('resources-referrers').whereIn('pageId', chunk).delete();
-                await this.#instance('page_errors').whereIn('pageId', chunk).delete();
-                await this.#instance('page_html_ref').whereIn('page_id', chunk).delete();
-                await this.#instance('page_tags').whereIn('pageId', chunk).delete();
-                await this.#instance('page_jsonld').whereIn('pageId', chunk).delete();
-            }
-            dbLog('Reset %d failed pages back to pending', urls.length);
-            return urls;
-        }
-        /**
-         * 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`.
-         * @param config - The {@link Config} object to store.
-         */
-        async setConfig(config) {
-            const payload = {};
-            for (const [key, value] of Object.entries(config)) {
-                if (!INFO_COLUMN_ALLOWLIST.has(key)) {
-                    continue;
-                }
-                payload[key] = INFO_JSON_COLUMNS.has(key) ? JSON.stringify(value) : value;
-            }
-            return this.#instance.from('info').insert(payload);
-        }
-        /**
-         * Marks a page as skipped in the database with the given reason.
-         * Creates the page row if it does not already exist.
-         * @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`.
-         */
-        async setSkippedPage(url, reason, isExternal = false) {
-            const pageId = await this.#getIdByUrl(url, isExternal ? 1 : 0);
-            await this.#instance('pages')
-                .where('id', pageId)
-                .update({
-                scraped: 1,
-                isExternal: isExternal ? 1 : 0,
-                isSkipped: 1,
-                skipReason: reason,
-            });
-        }
-        /**
-         * Assigns natural URL sort order values to all internal pages.
-         * Pages are sorted using {@link pathComparator} and assigned sequential order numbers.
-         */
-        async setUrlOrder() {
-            dbLog('Set URL Order');
-            const res = await this.#instance
-                .select('id', 'url')
-                .from('pages')
-                .where('isExternal', '=', 0);
-            const sorted = res.toSorted((a, b) => pathComparator(a.url, b.url));
-            // Batch update using chunked CASE statements to avoid N+1 queries
-            const BATCH_SIZE = 500;
-            for (let i = 0; i < sorted.length; i += BATCH_SIZE) {
-                const batch = sorted.slice(i, i + BATCH_SIZE);
-                const ids = batch.map((row) => row.id);
-                const bindings = [];
-                const cases = batch
-                    .map((row, j) => {
-                    bindings.push(row.id, i + j + 1);
-                    return 'WHEN ? THEN ?';
-                })
-                    .join(' ');
-                const placeholders = ids.map(() => '?').join(',');
-                await this.#instance.raw(`UPDATE pages SET \`order\` = CASE id ${cases} END WHERE id IN (${placeholders})`, [...bindings, ...ids]);
-            }
-        }
-        /**
-         * 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.
-         * @param patch - Partial {@link Config} fields to overwrite. `undefined` values are skipped.
-         */
-        async updateConfig(patch) {
-            const payload = {};
-            for (const [key, value] of Object.entries(patch)) {
-                if (value === undefined) {
-                    continue;
-                }
-                if (!INFO_COLUMN_ALLOWLIST.has(key)) {
-                    continue;
-                }
-                if (INFO_JSON_COLUMNS.has(key)) {
-                    payload[key] = JSON.stringify(value);
-                    continue;
-                }
-                payload[key] = value;
-            }
-            if (Object.keys(payload).length === 0) {
-                return;
-            }
-            await this.#instance.from('info').update(payload);
-        }
-        /**
-         * 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.
-         * @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` (this is why a
-         *   second `crawl --inventory` does not "demote" an `'inventory-seed'` row
-         *   that was discovered earlier).
-         * @returns The database `pageId` of the inserted/updated row.
-         */
-        async updatePage(page, writeHtml, isTarget, source) {
-            const { destUrl, sources } = resolveRedirectChain(page.url.withoutHashAndAuth, page.redirectPaths);
-            const destUrlObject = parseUrl(destUrl);
-            if (!destUrlObject) {
-                throw new Error(`Failed to parse URL: ${destUrl}`);
-            }
-            return await this.#instance.transaction(async (trx) => {
-                const pageId = await this.#insertPage({
-                    ...page,
-                    url: destUrlObject,
-                }, isTarget, trx, source);
-                // Wappalyzer tag detection is HTML-body independent (relies on
-                // `<script src>` / `<iframe src>` / window globals / response
-                // headers) so it runs for every page including external /
-                // metadata-only. JSON-LD on the other hand lives inside the
-                // rendered HTML body, so we only write it when there is HTML to
-                // scrape — see the same `writeHtml` gate as `#writePageHtmlBlob`
-                // below.
-                await this.#insertTags(pageId, page.meta, trx);
-                if (writeHtml) {
-                    await this.#insertJsonLd(pageId, page.meta, trx);
-                }
-                await this.#linkRedirectSources(trx, sources, pageId, destUrlObject.withoutHashAndAuth, page.isExternal);
-                // Only insert a snapshot blob when there is actual HTML to write.
-                // `page.html.length > 0` is the precise signal: the scraper returns
-                // `html: ''` for everything that is not a rendered `text/html` document
-                // (non-HTML responses, metadata-only, external, degraded renders), so a
-                // non-empty `html` is exactly "a rendered HTML body exists". Gating on
-                // `isTarget` alone would store an empty body for every internal non-HTML
-                // resource — PDF / zip / images are isTarget=1 (#72).
-                //
-                // `isTarget` is intentionally NOT part of this condition: it is implied by
-                // `html.length > 0` (only in-scope target pages are browser-rendered into a
-                // non-empty body; metadata-only and external pages carry `html: ''`), so the
-                // content check alone expresses the intent without a redundant term.
-                if (writeHtml && page.html.length > 0) {
-                    await this.#writePageHtmlBlob(pageId, page.html, trx);
-                }
-                else if (writeHtml &&
-                    page.contentType !== null &&
-                    !isHtmlContentType(page.contentType)) {
-                    // The page is now a *known* non-HTML type. If a previous scrape stored
-                    // an HTML body for this URL (e.g. it served HTML then was replaced by
-                    // a PDF across `crawl --resume` / `--append`), drop the stale ref so
-                    // `page_html_ref` never contradicts `contentType`. A degraded HTML
-                    // re-scrape (text/html or unknown content type with empty html) is NOT
-                    // cleared — the last good snapshot is preserved, mirroring the
-                    // anchors / images empty-guard below. Gated on `writeHtml` because a
-                    // stale ref can only have been written by a snapshot-capable call
-                    // (`setPage`); `setExternalPage` passes `writeHtml = false` and never
-                    // sets `html`, so it has nothing to clear.
-                    await trx('page_html_ref').where('page_id', pageId).delete();
-                }
-                // Re-scrape semantics: the same URL can be scraped more than once
-                // (e.g. `crawl --resume`, re-visits, `--append` re-promotion). The
-                // `anchors` / `images` tables have no uniqueness constraint, so
-                // re-inserting without clearing would accumulate a full duplicate set
-                // on every re-scrape (the bug fixed in #70). So we delete-then-insert
-                // to *replace* the previous rows.
-                //
-                // The delete is paired with — and guarded by — a non-empty new list:
-                // a degraded re-scrape (navigation timeout / partial render) can return
-                // an empty `anchorList` for a page that previously had links, and
-                // wiping the prior good data in that case would be destructive. We
-                // cannot tell a transient empty result apart from a page that has
-                // legitimately lost all its links, so we err on the side of keeping
-                // what we already had. The accepted trade-off is that a page which
-                // genuinely dropped to zero links keeps its stale rows until the next
-                // non-empty re-scrape replaces them.
-                //
-                // (A DB-level unique constraint + `onConflict` would also prevent
-                // duplication, but multiple distinct anchors can share the same
-                // hrefId/hash/textContent legitimately, so there is no natural unique
-                // key to enforce — replace-on-write is the correct mechanism here.)
-                const anchors = await Promise.all(page.anchorList.map(async (anchor) => {
-                    const hrefId = await this.#getIdByUrl(anchor.href.withoutHashAndAuth, anchor.isExternal ? 1 : 0, trx);
-                    return {
-                        pageId,
-                        hrefId,
-                        hash: anchor.href.hash,
-                        textContent: anchor.textContent,
-                    };
-                }));
-                dbLog('Insert anchors.length: %d', anchors.length);
-                if (anchors.length > 0) {
-                    await trx('anchors').where('pageId', pageId).delete();
-                    await eachSplitted(anchors, 100, async (_anchors) => {
-                        await trx('anchors').insert(_anchors);
-                    });
-                }
-                const images = page.imageList.map((image) => ({
-                    pageId,
-                    ...image,
-                }));
-                dbLog('Insert images.length: %d', images.length);
-                if (images.length > 0) {
-                    await trx('images').where('pageId', pageId).delete();
-                    await eachSplitted(images, 100, async (_images) => {
-                        await trx('images').insert(_images);
-                    });
-                }
-                return pageId;
-            });
-        }
-        /**
-         * Returns the database ID for a URL, creating a new page row if needed.
-         * Uses `ON CONFLICT IGNORE` to handle race conditions in concurrent inserts.
-         *
-         * `source` is written ONLY on the INSERT path — when the row already
-         * exists, we never reach the INSERT and the existing row's `source`
-         * stays untouched. This is what keeps a second `crawl --inventory` from
-         * "demoting" a page that was first labelled `'inventory-seed'` back to
-         * `'inventory-discovered'` on later passes.
-         * @param url
-         * @param isExternal
-         * @param trx
-         * @param source - Provenance label to put on the newly-inserted row. `undefined` lets the DB DEFAULT (`'crawled'`) apply.
-         */
-        async #getIdByUrl(url, isExternal, trx, source) {
-            const qb = trx ?? this.#instance;
-            const [record] = await qb.select('id').from('pages').where('url', url);
-            // Must use `?` because it may be `undefined`
-            const pageId = record?.id ?? Number.NaN;
-            if (Number.isFinite(pageId)) {
-                return pageId;
-            }
-            const insertedRows = await qb('pages')
-                .insert({
-                url,
-                scraped: 0,
-                isTarget: 0,
-                ...(isExternal != null && { isExternal }),
-                ...(source === undefined ? {} : { source }),
-            })
-                .onConflict('url')
-                .ignore();
-            const [insertedId] = insertedRows;
-            if (!insertedId) {
-                // onConflict.ignore() returns 0 on race condition — re-select
-                const [existing] = await qb.select('id').from('pages').where('url', url);
-                if (existing?.id) {
-                    return existing.id;
-                }
-                throw new Error(`Failed to insert a new page: ${url}`);
-            }
-            return insertedId;
-        }
-        /**
-         * Initializes the database schema if tables do not exist, then runs lightweight
-         * migrations that bring older archives up to the current schema.
-         *
-         * Migrations are idempotent and run on every writer-side {@link Database.connect};
-         * in read-only mode they are SKIPPED so the same DB can be opened safely
-         * by a viewer attached to a live (or interrupted) crawl without rewriting
-         * the user's tmpDir.
-         * @param readOnly - When true, skip schema init + migrations.
-         */
-        async #init(readOnly) {
-            // Connection-level PRAGMAs (foreign_keys, mmap_size, …) must be
-            // reapplied on every connect — they are not persisted across opens.
-            // They are safe in read-only mode because they don't write to the
-            // user's tmpDir, just configure the libsql connection.
-            await applyConnectionPragmas(this.#instance);
-            // Reject pre-0.10 archives before any further work. Runs for both
-            // writer and read-only (stub viewer) connections so old
-            // `._nitpicker-*` stubs surface a clear error instead of
-            // dereferencing missing columns at query time. New archives (no
-            // `info` table yet) pass through; the schema is filled in by
-            // `initSchema` below.
-            await assertCompatibleVersion(this.#instance);
-            if (readOnly) {
-                return;
-            }
-            await initSchema(this.#instance);
-            await migrateInfoRoots(this.#instance);
-            await migratePageErrors(this.#instance);
-            await migrateCrawlErrors(this.#instance);
-            await migrateHtmlBlobTables(this.#instance);
-            await migratePagesResourcesSource(this.#instance);
-        }
-        /**
-         * Replaces the page's JSON-LD / SpeculationRules rows with the freshly
-         * captured set. Called inside `updatePage`'s transaction.
-         *
-         * `writeHtml = false` branches (`setExternalPage`, metadata-only) skip
-         * this entirely — JSON-LD lives inside the HTML body, so external pages
-         * that are not rendered have no entries to write. An empty array on a
-         * normally-rendered page is treated as a degraded re-scrape: prior rows
-         * are kept (same `delete-only-when-replacing` invariant as `anchors` /
-         * `images`).
-         * @param pageId
-         * @param meta
-         * @param trx
-         */
-        async #insertJsonLd(pageId, meta, trx) {
-            // `??` guards tolerate the legacy "minimal meta" shape from older test
-            // fixtures. Real beholder 3.0.0 always populates these required fields.
-            const jsonLd = meta.jsonLd ?? [];
-            const speculationRules = meta.speculationRules ?? [];
-            const rows = [];
-            for (const entry of jsonLd) {
-                rows.push({
-                    pageId,
-                    kind: 'ld+json',
-                    type: classifyJsonLdType(entry),
-                    raw: entry.raw,
-                    parsed: entry.parsed === undefined ? null : JSON.stringify(entry.parsed),
-                    parseError: entry.parseError ?? null,
-                });
-            }
-            for (const entry of speculationRules) {
-                rows.push({
-                    pageId,
-                    kind: 'speculationrules',
-                    type: classifyJsonLdType(entry),
-                    raw: entry.raw,
-                    parsed: entry.parsed === undefined ? null : JSON.stringify(entry.parsed),
-                    parseError: entry.parseError ?? null,
-                });
-            }
-            if (rows.length === 0)
-                return;
-            await trx('page_jsonld').where('pageId', pageId).delete();
-            await eachSplitted(rows, 100, async (chunk) => {
-                await trx('page_jsonld').insert(chunk);
-            });
-        }
-        /**
-         * Upserts page data into the `pages` table (inserts if new, updates if existing).
-         *
-         * `source` is intentionally NOT in the UPDATE clause — provenance is set
-         * once at INSERT time inside `#getIdByUrl`, and existing rows keep
-         * whatever label they were first inserted with.
-         * @param page
-         * @param isTarget
-         * @param trx
-         * @param source - Inventory provenance for the INSERT path. Ignored on UPDATE.
-         */
-        async #insertPage(page, isTarget, trx, source) {
-            const qb = trx ?? this.#instance;
-            const pageId = await this.#getIdByUrl(page.url.withoutHashAndAuth, undefined, trx, source);
-            const flat = deriveFlatFromMeta(page.meta, page.url.href);
-            const denorm = computePageDenormalized(page.meta);
-            const extras = deriveMetaExtras(page.meta);
-            const now = Date.now();
-            // Source promotion on UPDATE: when an inventory-mode scrape lands on
-            // a row that was created earlier as a placeholder (e.g. an anchor
-            // from a seed page pointed at this URL and `#getIdByUrl` inserted a
-            // row with the DB DEFAULT `'crawled'`), bump the label to the
-            // inventory variant. But never demote an already-inventoried row —
-            // `CASE WHEN source = 'crawled' THEN ? ELSE source END` keeps a
-            // previously labelled `'inventory-seed'` or `'inventory-discovered'`
-            // row intact on a second pass.
-            const sourceUpdate = source === undefined
-                ? {}
-                : {
-                    source: qb.raw("CASE WHEN source = 'crawled' THEN ? ELSE source END", [
-                        source,
-                    ]),
-                };
-            await qb('pages')
-                .where('id', pageId)
-                .update({
-                scraped: true,
-                isTarget,
-                isExternal: page.isExternal,
-                status: page.status,
-                statusText: page.statusText,
-                // Canonicalize so the stored value matches the exact-string page-ness
-                // predicate (`WHERE contentType = 'text/html'`) used by the read layer
-                // and the case-insensitive `isHtmlContentType` used in code. Responses
-                // are recorded verbatim upstream, so `Text/HTML` / `text/html ` can
-                // otherwise be stored and silently misclassified.
-                contentType: normalizeContentType(page.contentType),
-                contentLength: page.contentLength,
-                responseHeaders: JSON.stringify(page.responseHeaders),
-                // Flat meta columns derived from beholder 3.0.0 nested Meta.
-                // URL-shaped columns (canonical / og_url / og_image / amphtml / manifest /
-                // icon_href / appleTouchIcon_href / twitter_image) are already absolutised
-                // by `deriveFlatFromMeta` against the page URL — `find-mismatches` compares
-                // `canonical != url` directly, so storing the raw `getAttribute('href')`
-                // would generate false positives for sites using relative canonicals.
-                ...flat,
-                // Denormalised aggregates: written once at scrape time so list reads
-                // (Sheets, page-detail summary) can answer "how many JSON-LD entries?"
-                // and "which Wappalyzer providers?" by selecting a single pages column
-                // rather than running a GROUP BY join on every read.
-                tag_count: denorm.tag_count,
-                jsonld_count: denorm.jsonld_count,
-                tags_providers_csv: denorm.tags_providers_csv,
-                // JSON catch-all for nested Meta sub-objects not flattened above.
-                meta_extras: JSON.stringify(extras),
-                // Timestamps: `firstCrawledAt` is set only on first INSERT — `COALESCE`
-                // preserves the existing value so a re-scrape (`--append`, `--retry-failed`)
-                // does not erase the discovery time. `lastCrawledAt` is updated every
-                // successful scrape.
-                firstCrawledAt: qb.raw('COALESCE(firstCrawledAt, ?)', [now]),
-                lastCrawledAt: now,
-                isSkipped: page.isSkipped,
-                ...sourceUpdate,
-            });
-            return pageId;
-        }
-        /**
-         * Replaces the page's Wappalyzer tag rows with the freshly captured set.
-         * Called inside `updatePage`'s transaction unconditionally — tag
-         * detection draws on `<script src>` / `<iframe src>` / window globals /
-         * response headers, not the HTML body, so external pages that skip
-         * rendering still contribute tags.
-         *
-         * Same empty-guard as `#insertJsonLd`: an empty array does not wipe
-         * prior rows on a degraded re-scrape.
-         * @param pageId
-         * @param meta
-         * @param trx
-         */
-        async #insertTags(pageId, meta, trx) {
-            const partial = extractTagsForArchive(meta.tags);
-            if (partial.length === 0)
-                return;
-            const rows = partial.map((p) => ({
-                pageId,
-                provider: p.provider,
-                category: p.category,
-                externalId: p.externalId,
-                version: p.version,
-                confidence: p.confidence,
-                categories: JSON.stringify(p.categories),
-                sources: JSON.stringify(p.sources),
-            }));
-            await trx('page_tags').where('pageId', pageId).delete();
-            await eachSplitted(rows, 100, async (chunk) => {
-                await trx('page_tags').insert(chunk);
-            });
-        }
-        /**
-         * Points each redirect-source URL at the destination page, marking it scraped
-         * and clearing any content it owned in a former life.
-         *
-         * Shared by {@link updatePage} (which also renders and stores the destination)
-         * and {@link recordRedirect} (which only records the edge for a destination
-         * rendered elsewhere). Self-redirects (source equal to the destination) are
-         * skipped so a page is never marked as redirecting to itself — that would
-         * exclude it from reports via the `whereNull('redirectDestId')` filter.
-         * @param trx - The active transaction.
-         * @param sources - Redirect-source URLs (normalised): the original URL plus
-         *   any intermediate hops. Empty when the page was not redirected.
-         * @param destId - Database id of the redirect destination page.
-         * @param destUrlNormalized - Normalised destination URL, used to detect and
-         *   skip self-redirects.
-         * @param isExternal - Whether the sources are external to the crawl scope.
-         */
-        async #linkRedirectSources(trx, sources, destId, destUrlNormalized, isExternal) {
-            for (const redirect of sources) {
-                if (redirect === destUrlNormalized) {
-                    dbLog('Skip self-redirect: %s', redirect);
-                    continue;
-                }
-                dbLog('Set redirected url: %s -> id:%d', redirect, destId);
-                const redirectId = await this.#getIdByUrl(redirect, undefined, trx);
-                await trx('pages')
-                    .where('id', redirectId)
-                    .update({
-                    scraped: 1,
-                    redirectDestId: destId,
-                    isExternal: isExternal ? 1 : 0,
-                });
-                // A page that used to be scraped as content can later turn into a
-                // redirect source. It owns no content anymore, so drop any anchors /
-                // images it captured in its former life — otherwise they linger and
-                // leak into referrer / incoming-link reads (which do not filter out
-                // redirect sources).
-                await trx('anchors').where('pageId', redirectId).delete();
-                await trx('images').where('pageId', redirectId).delete();
-            }
-        }
-        /**
-         * Encodes, dedups, and persists a page's HTML snapshot.
-         *
-         * Computes SHA-256 over the raw UTF-8 bytes, compresses them with zstd,
-         * inserts into `page_html_blobs` only if the hash is new (so identical
-         * bodies — 404 templates, error pages, redirect destinations — share a
-         * single row), and then upserts `page_html_ref(page_id → hash)` so the
-         * latest scrape always points at the right body.
-         *
-         * Runs entirely inside the caller's transaction; a failure here rolls
-         * back the rest of `updatePage`, which is the desired semantics (an
-         * archive that lost its HTML for a page would otherwise serve stale
-         * meta against a missing body).
-         * @param pageId - The database id of the page.
-         * @param html - The raw HTML string (UTF-8).
-         * @param trx - The active transaction.
-         */
-        async #writePageHtmlBlob(pageId, html, trx) {
-            const rawBytes = Buffer.from(html, 'utf8');
-            const hash = createHash('sha256').update(rawBytes).digest();
-            const compressed = zstdCompressSync(rawBytes);
-            await trx('page_html_blobs')
-                .insert({
-                hash,
-                body: compressed,
-                codec: 'zstd',
-                size_raw: rawBytes.byteLength,
-                size_stored: compressed.byteLength,
-            })
-                .onConflict('hash')
-                .ignore();
-            // Upsert so a re-scrape's body cleanly supersedes the prior pointer.
-            // The old blob row is intentionally left in place — a future #23 GC
-            // pass will sweep unreachable hashes.
-            await trx('page_html_ref')
-                .insert({ page_id: pageId, hash })
-                .onConflict('page_id')
-                .merge(['hash']);
-        }
-        /**
-         * 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 async connect(options) {
-            if (options.readOnly) {
-                if (!existsSync(path.dirname(options.filename))) {
-                    throw new Error(`Cannot open archive read-only: parent directory disappeared (${path.dirname(options.filename)}). The source may have been removed by another process.`);
-                }
-                if (!existsSync(options.filename)) {
-                    throw new Error(`Cannot open archive read-only: database file missing (${options.filename}). The source may have been removed by another process.`);
-                }
-            }
-            else {
-                mkdir(options.filename);
-            }
-            const db = new Database(options);
-            await db.#init(options.readOnly ?? false);
-            return db;
-        }
-    };
-})();
-export { Database };