@nitpicker/crawler 0.20.0 → 0.22.0

package/lib/archive/types.d.ts

@@ -80,6 +80,28 @@ export interface Config extends Required<Pick<ParseURLOptions, 'disableQueries'>
      * detection, or `null`/omitted to use the automatic heuristic.
      */
     mainContentSelector?: string | null;
+    /**
+     * The `process.cwd()` recorded when this session's stub (tmpDir) was
+     * created by `CrawlerOrchestrator.crawling` / `.append` / `.inventory` /
+     * `.recrawl` / `.retryFailed` — NOT written by `.resume` itself, which
+     * only reads it. `Archive.resume` uses this (falling back to its own
+     * `process.cwd()` for a stub that predates this column) to reconstruct
+     * the completed archive's output path independent of the directory
+     * `crawl --resume` happens to be invoked from.
+     *
+     * `.nitpicker` files are routinely shared between users, and this local
+     * absolute path (which can embed a username / project layout) has no
+     * business surviving into a shared archive — `Archive.write` scrubs the
+     * column back to `null` immediately before packaging, so it only ever
+     * exists in an unpackaged stub.
+     *
+     * WHY (for future stub-limited fields): if you add another column meant
+     * to live only in the unpackaged stub, pair it with a matching scrub in
+     * `Archive.write` (`archive.ts`) — nothing enforces this automatically,
+     * and a forgotten scrub silently leaks the field into every shared
+     * `.nitpicker` from then on.
+     */
+    createdCwd?: string | null;
 }
 /**
  * Provenance of a page or resource row — which crawler channel originally
@@ -107,13 +129,13 @@ export interface Config extends Required<Pick<ParseURLOptions, 'disableQueries'>
  */
 export type PageSource = 'crawled' | 'inventory-seed' | 'inventory-discovered';
 /**
- * One row written to the `inventory_runs` audit table on each successful
- * `--inventory <list>` invocation.
+ * One row written to the `list_reconcile_runs` audit table on each
+ * successful `--inventory <list>` or `--recrawl <list>` invocation.
  *
- * Schema-mirror interface: every column on `inventory_runs` is represented
- * here. Only `ran_at` is required — every other field is nullable so a
- * raw-SQL backfill (a one-off `sqlite3 INSERT` recording an inventory
- * pass that predates this table) can omit summary
+ * Schema-mirror interface: every column on `list_reconcile_runs` is
+ * represented here. Only `ran_at` is required — every other field is
+ * nullable so a raw-SQL backfill (a one-off `sqlite3 INSERT` recording a
+ * reconcile pass that predates this table) can omit summary
  * stats it cannot reconstruct.
  *
  * The audit log is append-only: there is intentionally no UPDATE path,
@@ -122,7 +144,7 @@ export type PageSource = 'crawled' | 'inventory-seed' | 'inventory-discovered';
  * detection is a read-side concern; `source_file_sha256` is recorded as
  * the content-identity key it would use.
  * @example
- * await archive.recordInventoryRun({
+ * await archive.recordListReconcileRun({
  *   ran_at: new Date().toISOString(),
  *   list_label: 'prod-2026-06',
  *   total_lines: 113_268,
@@ -132,7 +154,7 @@ export type PageSource = 'crawled' | 'inventory-seed' | 'inventory-discovered';
  *   exclude_skipped: 3,
  * });
  */
-export interface InventoryRunMeta {
+export interface ListReconcileRunMeta {
     /** ISO 8601 timestamp at which the run completed (e.g. `'2026-06-21T11:30:00+09:00'`). */
     ran_at: string;
     /** Human-readable identifier (e.g. `'prod-2026-06-21'`). `null` when the caller did not supply one. */
@@ -147,13 +169,36 @@ export interface InventoryRunMeta {
     new_resources?: number | null;
     /** Number of input URLs dropped because they fell outside the archived scope. */
     scope_skipped?: number | null;
-    /** Number of novel in-scope input URLs recorded as terminal skipped pages (`is_skipped=1`, `skip_reason='excluded'`) instead of being imported, because they matched the effective `excludes` / `excludeUrls` config. Pure audit output like every other count on this row — written once per run, read back only by `listInventoryRuns` display surfaces, never consumed by any runtime decision. `null` on rows written before the column existed (those runs predate ingestion-side exclusion — their excluded URLs were imported as real pages/resources, not counted). */
+    /** Number of novel in-scope input URLs recorded as terminal skipped pages (`is_skipped=1`, `skip_reason='excluded'`) instead of being imported, because they matched the effective `excludes` / `excludeUrls` config. Pure audit output like every other count on this row — written once per run, read back only by `listReconcileRuns` display surfaces, never consumed by any runtime decision. `null` on rows written before the column existed (those runs predate ingestion-side exclusion — their excluded URLs were imported as real pages/resources, not counted). */
     exclude_skipped?: number | null;
     /** Number of source-file lines dropped by the CLI for failing URL validation, before this row's `total_lines` was counted. `null` for programmatic callers that built the URL list in-memory (no source file to have invalid lines). */
     invalid_skipped?: number | null;
     /** Free-form text for backfill annotations or operator notes. */
     notes?: string | null;
 }
+/**
+ * Result of {@link Database.resetPagesByUrls}: the URLs actually reset back
+ * to pending, plus the URLs excluded from reset grouped by why — a caller
+ * (`CrawlerOrchestrator.recrawl`) reports each exclusion category to the
+ * operator separately rather than lumping them into one opaque count.
+ *
+ * A URL can appear in at most one of these four arrays: `resetUrls` when it
+ * matched the reset candidate criteria, or exactly one exclusion array when
+ * it matched an existing page row but failed one of the conservative guards.
+ * A URL with no matching row in the archive at all (not yet known) appears in
+ * none of them — that case is the caller's "novel URL" handling, not this
+ * function's concern.
+ */
+export interface ResetPagesByUrlsResult {
+    /** URLs whose row was reset to `scraped = 0` and had its derived data cleared. */
+    resetUrls: string[];
+    /** URLs excluded because the matching row is a redirect source (`redirect_dest_id` is set) — resetting it would discard a real 3xx observation. */
+    excludedRedirects: string[];
+    /** URLs excluded because the matching row was intentionally skipped (`is_skipped = 1`, e.g. `excludes`/`excludeUrls`) — the exclusion still applies. */
+    excludedSkipped: string[];
+    /** URLs excluded because the matching row is external (`is_external = 1`) — bringing a scope-external URL back into scope is `--append`'s job, not a URL-list re-fetch. */
+    excludedExternal: string[];
+}
 /**
  * A row in `network_outages` — one detected operator-network outage.
  *
@@ -183,7 +228,7 @@ export interface NetworkOutageRow {
 /**
  * Fields required to record a newly-detected outage via
  * `Database.insertNetworkOutage`. camelCase (unlike {@link NetworkOutageRow}
- * / {@link InventoryRunMeta}) because callers build this directly from
+ * / {@link ListReconcileRunMeta}) because callers build this directly from
  * `NetworkOutageDetector`'s camelCase `OutageSuspect` plus a probe host —
  * the db-op does the camelCase → snake_case column mapping on write.
  */
@@ -210,6 +255,44 @@ export interface InsertDedupeCapEventParams {
     observedCount: number;
     detectedAt: number;
 }
+/**
+ * One previously-scraped internal page's raw fields, read back from
+ * `content_items` / `page_meta` / `url_refs` / `text_refs`, in the exact
+ * shape `buildDedupeCapObservation` needs to reconstruct the
+ * `DedupeCapObservation` that page would have produced during a live crawl.
+ * Produced by `listDedupeCapObservations` — see that function for the row
+ * selection criteria (which pages qualify, and why).
+ *
+ * Nullable fields mirror the LEFT JOINed `text_refs` / `url_refs` columns
+ * they come from (a page with no `<title>`, no meta description, or no
+ * `og:title`/`og:url` leaves the corresponding ref column NULL).
+ */
+export interface DedupeCapObservationRow {
+    /**
+     * `url_refs.url`, in `withoutHashAndAuth` form — matches how
+     * `computeShapeKey`'s live callers key their gate lookups. No hash
+     * fragment survives here even if the original page URL had one (the
+     * archive never stores it) — see `buildDedupeCapObservation`'s JSDoc
+     * for why this makes its `ogUrlMismatch` reconstruction an
+     * approximation for hash-carrying URLs.
+     */
+    url: string;
+    /** `page_meta.title_text_id` → `text_refs.text`. Never NULL in practice (beholder always returns at least `''`), but read as nullable since the join can't guarantee it. */
+    title: string | null;
+    /** `page_meta.description_text_id` → `text_refs.text`. */
+    description: string | null;
+    /** `page_meta.og_title_text_id` → `text_refs.text`. */
+    ogTitle: string | null;
+    /**
+     * `page_meta.og_url_id` → `url_refs.url` — already absolutised at write
+     * time (`derive-flat-from-meta.ts`), not the raw `og:url` attribute
+     * value. See `buildDedupeCapObservation`'s JSDoc for why this makes its
+     * `metaSig` component an approximation for relative-`og:url` templates.
+     */
+    ogUrl: string | null;
+    /** `page_meta.body_hash`. Rows with a NULL body hash are excluded by `listDedupeCapObservations` itself, so this is always present by the time a row reaches this type — kept non-nullable here for that reason. */
+    bodyHash: Buffer;
+}
 /**
  * Filter type for querying pages from the database.
  *
@@ -402,6 +485,10 @@ export interface DB_Page {
     scroll_height_desktop: number | null;
     /** `document.body.scrollHeight` at the mobile-small preset, or null. */
     scroll_height_mobile: number | null;
+    /** `@d-zero/beholder`'s `IMAGE_SCAN_CODE` outcome for the desktop-compact `<img>` scan, or null when not attempted. */
+    image_scan_desktop: number | null;
+    /** `@d-zero/beholder`'s `IMAGE_SCAN_CODE` outcome for the mobile-small `<img>` scan, or null when not attempted. */
+    image_scan_mobile: number | null;
     /** JSON-serialised nested Meta sub-objects not flattened above. */
     meta_extras: string | null;
     /** JSON-serialized network logs captured during scraping, or null if not collected. */

package/lib/compute-auto-retry-backoff-delay.d.ts

@@ -0,0 +1,30 @@
+/**
+ * Computes the exponential backoff delay before an auto-retry attempt
+ * (issue #350): 30s, 60s, 120s, … doubling each attempt, capped at 5
+ * minutes so a long run of retries against a persistently slow site does
+ * not stall for arbitrarily long between attempts.
+ *
+ * WHY NOT `@d-zero/shared/retry`'s `retryCall`: that helper retries a
+ * single async call until it stops throwing, driven entirely by
+ * exceptions — this loop instead re-runs a whole crawl pass and decides
+ * whether to continue by reading `getCrawlingState().pending` afterward
+ * (no exception involved on the "still pending" path) and can abandon
+ * early on a no-progress attempt, neither of which `retryCall`'s
+ * catch-and-retry model expresses. `@d-zero/shared/retry` also does not
+ * export its interval math as a standalone function (only the
+ * `retryCall`/`retry` entry points, which own the whole wait+retry loop
+ * internally), so there is nothing smaller to reuse for just the delay
+ * calculation either.
+ * @param attempt - The 1-indexed attempt number about to run.
+ * @returns The delay in milliseconds to wait before that attempt.
+ * @example
+ * ```ts
+ * computeAutoRetryBackoffDelayMs(1);
+ * // => 30_000 (30s)
+ * computeAutoRetryBackoffDelayMs(2);
+ * // => 60_000 (60s)
+ * computeAutoRetryBackoffDelayMs(10);
+ * // => 300_000 (5min) — capped
+ * ```
+ */
+export declare function computeAutoRetryBackoffDelayMs(attempt: number): number;

package/lib/compute-auto-retry-backoff-delay.js

@@ -0,0 +1,36 @@
+/** Initial wait before the first auto-retry attempt, in milliseconds. */
+const INITIAL_DELAY_MS = 30_000;
+/** Upper bound on the wait between auto-retry attempts, in milliseconds. */
+const MAX_DELAY_MS = 300_000;
+/**
+ * Computes the exponential backoff delay before an auto-retry attempt
+ * (issue #350): 30s, 60s, 120s, … doubling each attempt, capped at 5
+ * minutes so a long run of retries against a persistently slow site does
+ * not stall for arbitrarily long between attempts.
+ *
+ * WHY NOT `@d-zero/shared/retry`'s `retryCall`: that helper retries a
+ * single async call until it stops throwing, driven entirely by
+ * exceptions — this loop instead re-runs a whole crawl pass and decides
+ * whether to continue by reading `getCrawlingState().pending` afterward
+ * (no exception involved on the "still pending" path) and can abandon
+ * early on a no-progress attempt, neither of which `retryCall`'s
+ * catch-and-retry model expresses. `@d-zero/shared/retry` also does not
+ * export its interval math as a standalone function (only the
+ * `retryCall`/`retry` entry points, which own the whole wait+retry loop
+ * internally), so there is nothing smaller to reuse for just the delay
+ * calculation either.
+ * @param attempt - The 1-indexed attempt number about to run.
+ * @returns The delay in milliseconds to wait before that attempt.
+ * @example
+ * ```ts
+ * computeAutoRetryBackoffDelayMs(1);
+ * // => 30_000 (30s)
+ * computeAutoRetryBackoffDelayMs(2);
+ * // => 60_000 (60s)
+ * computeAutoRetryBackoffDelayMs(10);
+ * // => 300_000 (5min) — capped
+ * ```
+ */
+export function computeAutoRetryBackoffDelayMs(attempt) {
+    return Math.min(INITIAL_DELAY_MS * 2 ** (attempt - 1), MAX_DELAY_MS);
+}

package/lib/crawler/apply-crawl-runtime-options-patch.d.ts

@@ -0,0 +1,32 @@
+import type { CrawlerOptions, CrawlRuntimeOptions, CrawlRuntimeOptionsPatch } from './types.js';
+/**
+ * Applies a runtime patch to a live {@link CrawlerOptions} object in place
+ * and returns a snapshot of the affected fields.
+ *
+ * `parallels`/`interval` overwrite the current value. The three exclude
+ * arrays are additive only — new entries are appended (duplicates against
+ * the existing array dropped); there is no way to remove an already-set
+ * exclude pattern through this function. `Crawler#updateRuntimeOptions`
+ * (the only caller) reads `options.excludes`/`.excludeUrls`/
+ * `.excludeKeywords`/`.parallels`/`.interval` fresh on every use — see
+ * `shouldSkipUrl`'s call site in `crawler.ts` and the per-URL interval
+ * check — so replacing these fields with new arrays/values here takes
+ * effect starting with the next URL a worker picks up, without any cache
+ * to invalidate.
+ * @param options - The live options object to mutate.
+ * @param patch - The runtime change to apply.
+ * @returns A snapshot of `parallels`/`interval`/the three exclude arrays after
+ *   applying `patch`, plus which of `patch`'s exclude entries (if any) were
+ *   genuinely new (see {@link CrawlRuntimeOptions.addedExcludes}).
+ * @throws {RangeError} If `parallels` is present and not an integer `>= 1`, or `interval` is present and not an integer `>= 0`.
+ * @throws {TypeError} If any exclude entry is present and not a non-empty string.
+ * @example
+ * ```ts
+ * const snapshot = applyCrawlRuntimeOptionsPatch(options, {
+ *   parallels: 4,
+ *   excludes: ['/admin/**'],
+ * });
+ * console.log(snapshot.parallels); // 4
+ * ```
+ */
+export declare function applyCrawlRuntimeOptionsPatch(options: CrawlerOptions, patch: CrawlRuntimeOptionsPatch): CrawlRuntimeOptions;

package/lib/crawler/apply-crawl-runtime-options-patch.js

@@ -0,0 +1,129 @@
+/**
+ * Merges `additions` into `existing`, appending only entries not already
+ * present (order-preserving, first occurrence wins) — the same
+ * `[...new Set([...a, ...b])]` idiom `crawler-orchestrator.ts` already uses
+ * for root/URL merges (`mergedRoots`, `shapeKeysToFinalize`).
+ * @param existing - The current array.
+ * @param additions - Entries to add, or `undefined` to leave `existing` unchanged.
+ * @returns A new array — `existing` itself when `additions` is `undefined` or empty.
+ */
+function mergeUnique(existing, additions) {
+    if (!additions || additions.length === 0) {
+        return existing;
+    }
+    return [...new Set([...existing, ...additions])];
+}
+/**
+ * The subset of `additions` not already present in `existing` — order
+ * preserved, and a duplicate within `additions` itself counted only once.
+ * Distinct from {@link mergeUnique}'s result (which is `existing` plus these
+ * entries): a caller reporting "what was newly added" needs just this part,
+ * not the merged array — see {@link CrawlRuntimeOptions.addedExcludes}'s
+ * JSDoc for why echoing `additions` itself back as "added" is wrong when
+ * every entry in it was already present.
+ * @param existing - The current array.
+ * @param additions - Entries the patch requested adding, or `undefined`.
+ * @returns The entries from `additions` that are genuinely new.
+ */
+function pickNewEntries(existing, additions) {
+    if (!additions || additions.length === 0) {
+        return [];
+    }
+    const existingSet = new Set(existing);
+    const added = [];
+    for (const entry of additions) {
+        if (!existingSet.has(entry) && !added.includes(entry)) {
+            added.push(entry);
+        }
+    }
+    return added;
+}
+/**
+ * Validates every field of `patch` before any mutation, so a single invalid
+ * field (e.g. `parallels: 0`) cannot leave `options` half-updated.
+ * @param patch - The patch to validate.
+ * @throws {RangeError} If `parallels` is present and not an integer `>= 1`, or `interval` is present and not an integer `>= 0`.
+ * @throws {TypeError} If any exclude entry is present and not a non-empty string.
+ */
+function assertValidPatch(patch) {
+    if (patch.parallels !== undefined &&
+        (!Number.isSafeInteger(patch.parallels) || patch.parallels < 1)) {
+        throw new RangeError(`parallels must be an integer >= 1, got ${patch.parallels}`);
+    }
+    if (patch.interval !== undefined &&
+        (!Number.isSafeInteger(patch.interval) || patch.interval < 0)) {
+        throw new RangeError(`interval must be an integer >= 0, got ${patch.interval}`);
+    }
+    for (const [field, entries] of [
+        ['excludes', patch.excludes],
+        ['excludeUrls', patch.excludeUrls],
+        ['excludeKeywords', patch.excludeKeywords],
+    ]) {
+        if (!entries)
+            continue;
+        for (const entry of entries) {
+            if (typeof entry !== 'string' || entry.length === 0) {
+                throw new TypeError(`${field} entries must be non-empty strings, got ${JSON.stringify(entry)}`);
+            }
+        }
+    }
+}
+/**
+ * Applies a runtime patch to a live {@link CrawlerOptions} object in place
+ * and returns a snapshot of the affected fields.
+ *
+ * `parallels`/`interval` overwrite the current value. The three exclude
+ * arrays are additive only — new entries are appended (duplicates against
+ * the existing array dropped); there is no way to remove an already-set
+ * exclude pattern through this function. `Crawler#updateRuntimeOptions`
+ * (the only caller) reads `options.excludes`/`.excludeUrls`/
+ * `.excludeKeywords`/`.parallels`/`.interval` fresh on every use — see
+ * `shouldSkipUrl`'s call site in `crawler.ts` and the per-URL interval
+ * check — so replacing these fields with new arrays/values here takes
+ * effect starting with the next URL a worker picks up, without any cache
+ * to invalidate.
+ * @param options - The live options object to mutate.
+ * @param patch - The runtime change to apply.
+ * @returns A snapshot of `parallels`/`interval`/the three exclude arrays after
+ *   applying `patch`, plus which of `patch`'s exclude entries (if any) were
+ *   genuinely new (see {@link CrawlRuntimeOptions.addedExcludes}).
+ * @throws {RangeError} If `parallels` is present and not an integer `>= 1`, or `interval` is present and not an integer `>= 0`.
+ * @throws {TypeError} If any exclude entry is present and not a non-empty string.
+ * @example
+ * ```ts
+ * const snapshot = applyCrawlRuntimeOptionsPatch(options, {
+ *   parallels: 4,
+ *   excludes: ['/admin/**'],
+ * });
+ * console.log(snapshot.parallels); // 4
+ * ```
+ */
+export function applyCrawlRuntimeOptionsPatch(options, patch) {
+    assertValidPatch(patch);
+    // Computed before `options` is mutated below — `pickNewEntries` needs the
+    // pre-patch arrays to tell "new" from "already present".
+    const addedExcludes = pickNewEntries(options.excludes, patch.excludes);
+    const addedExcludeUrls = pickNewEntries(options.excludeUrls, patch.excludeUrls);
+    const addedExcludeKeywords = pickNewEntries(options.excludeKeywords, patch.excludeKeywords);
+    if (patch.parallels !== undefined) {
+        options.parallels = patch.parallels;
+    }
+    if (patch.interval !== undefined) {
+        options.interval = patch.interval;
+    }
+    options.excludes = [...mergeUnique(options.excludes, patch.excludes)];
+    options.excludeUrls = [...mergeUnique(options.excludeUrls, patch.excludeUrls)];
+    options.excludeKeywords = [
+        ...mergeUnique(options.excludeKeywords, patch.excludeKeywords),
+    ];
+    return {
+        parallels: options.parallels,
+        interval: options.interval,
+        excludes: options.excludes,
+        excludeUrls: options.excludeUrls,
+        excludeKeywords: options.excludeKeywords,
+        addedExcludes,
+        addedExcludeUrls,
+        addedExcludeKeywords,
+    };
+}

package/lib/crawler/crawler.d.ts

@@ -1,4 +1,4 @@
-import type { CrawlerEventTypes, CrawlerOptions } from './types.js';
+import type { CrawlerEventTypes, CrawlerOptions, CrawlRuntimeOptions, CrawlRuntimeOptionsPatch } from './types.js';
 import type { ExURL } from '@d-zero/shared/parse-url';
 import { TypedAwaitEventEmitter as EventEmitter } from '@d-zero/shared/typed-await-event-emitter';
 export type { CrawlerOptions } from './types.js';
@@ -68,8 +68,11 @@ export default class Crawler extends EventEmitter<CrawlerEventTypes> {
      * @param pagesScrapedOffset - Number of HTML pages already rendered in previous
      *   sessions, used to seed the session-spanning progress counter. Defaults to 0
      *   for callers that don't need cross-session accuracy in the progress display.
+     * @param metadataOnlyUrls - The subset of `pending` fated for a
+     *   metadata-only scrape — see `LinkList#resume`'s `metadataOnlyUrls`
+     *   doc (#369).
      */
-    resume(pending: string[], scraped: string[], resources: string[], pagesScrapedOffset?: number): void;
+    resume(pending: string[], scraped: string[], resources: string[], pagesScrapedOffset?: number, metadataOnlyUrls?: readonly string[]): void;
     /**
      * Start crawling from one or more root URLs.
      *
@@ -85,14 +88,43 @@ export default class Crawler extends EventEmitter<CrawlerEventTypes> {
      * previously-external page — does not race on two parallel slots.
      * @param urls - The list of root URLs to begin crawling from. May be empty
      *   when resumed pending URLs already exist (for example `--retry-failed`).
-     * @param opts - Optional overrides; currently only `recursive` is honoured.
+     * @param opts - Optional overrides.
      * @param opts.recursive - When `false`, disables recursive discovery and forces list-mode.
      *   Defaults to the constructor option's `recursive` value.
+     * @param opts.isRetryContinuation - Forwarded to `#runDeal` (issue #350):
+     *   when `true`, this is `CrawlerOrchestrator`'s auto-retry loop
+     *   re-invoking `start()` on the same `Crawler` instance after a prior
+     *   pass ended with pages still pending, not an unrelated fresh
+     *   session — see `#runDeal`'s JSDoc for what that changes.
      * @throws {Error} If the URL list is empty.
      */
     start(urls: ExURL[], opts?: {
         recursive?: boolean;
+        isRetryContinuation?: boolean;
     }): void;
+    /**
+     * Applies a runtime change to this crawl's tunable options
+     * (`parallels`/`interval`/the three exclude arrays) while it is in
+     * progress. See {@link applyCrawlRuntimeOptionsPatch} for merge
+     * semantics and validation.
+     *
+     * A `parallels` change takes effect immediately (via the live
+     * `Dealer`'s `setLimit()`) when this is called while a `deal()` round
+     * is actually in flight ({@link #dealController} non-`null`). Between
+     * auto-retry rounds ({@link #dealController} `null`), only
+     * `#options.parallels` is updated — the next round's `#runDeal` reads it
+     * when computing that round's `concurrency`.
+     * @param patch - The runtime change to apply.
+     * @returns A snapshot of the tunable options after applying `patch`.
+     * @throws {RangeError} If `parallels` is present and not an integer `>= 1`, or `interval` is present and not an integer `>= 0`.
+     * @throws {TypeError} If any exclude entry is present and not a non-empty string.
+     * @example
+     * ```ts
+     * const snapshot = crawler.updateRuntimeOptions({ parallels: 4 });
+     * console.log(snapshot.parallels); // 4
+     * ```
+     */
+    updateRuntimeOptions(patch: CrawlRuntimeOptionsPatch): CrawlRuntimeOptions;
     /**
      * Launches a fresh Puppeteer browser, runs the beholder scraper, and cleans up.
      *