@ultimat3/scraping 30.9.0 → 31.1.0

package/src/clock.ts

@@ -1,118 +1,11 @@
-// The ONE file in this package allowed to make time pass. Every wait a scraper does — the
-// actionability poll, the wedge watchdog, the rate limiter, the graceful-quit ceiling — goes
-// through `ScrapeClock`, so a suite that exercises a 30-second timeout finishes in microseconds.
-//
-// `clock-discipline.test.ts` fails the build if a second file reaches for a timer directly.
+// Elapsed-time budgets for every wait a scraper does — the actionability poll, the wedge watchdog,
+// the rate limiter, the graceful-quit ceiling. The waiting itself is `@ultimat3/core`'s `SleepClock`
+// (`ambientClock()` unless a definition pins one), so a suite that exercises a 30-second timeout
+// finishes in microseconds. `clock-discipline.test.ts` fails the build if a file here arms a timer.
 
 import type { Clock } from '@ultimat3/core';
 import { finiteCount } from '@ultimat3/core';
 
-export interface ScrapeClock extends Clock {
-  /**
-   * Resolve after `ms` of this clock's time, or reject with the signal's reason the moment it
-   * aborts. Every poll loop here composes a wait with a cancellation, so a clock whose sleep
-   * ignored the signal would leave a killed run still counting.
-   */
-  sleep(ms: number, signal?: AbortSignal): Promise<void>;
-}
-
-export const systemScrapeClock: ScrapeClock = Object.freeze({
-  now(): Date {
-    return new Date();
-  },
-  monotonic(): number {
-    return performance.now();
-  },
-  async sleep(ms: number, signal?: AbortSignal): Promise<void> {
-    if (signal === undefined) {
-      await Bun.sleep(ms);
-      return;
-    }
-    signal.throwIfAborted();
-    // A timer raced against the signal, never `Bun.sleep(ms).then(check)`: the watchdog aborts a
-    // wedged run precisely so nothing waits out the rest of a five-minute budget, and a sleep
-    // that only notices the abort when it expires would wait out every one of them.
-    await new Promise<void>((resolve, reject) => {
-      // The reason is rejected VERBATIM, never wrapped: whoever aborted put a `ScrapeError` with
-      // a code and a fix there, and re-wrapping it would replace an instruction with `Error`.
-      const onAbort = (): void => {
-        clearTimeout(timer);
-        reject(signal.reason);
-      };
-      const timer = setTimeout(() => {
-        signal.removeEventListener('abort', onAbort);
-        resolve();
-      }, ms);
-      signal.addEventListener('abort', onAbort, { once: true });
-    });
-  },
-});
-
-/**
- * The system clock with the waiting taken out: `now()` and `monotonic()` are real, and every
- * `sleep` is ONE turn of the event loop whatever was asked for. For a test whose run waits on
- * something that really happens in the same process — an answer the test publishes, a job another
- * worker holds — where `testScrapeClock()`'s "sleeping is advancing" would run a five-minute budget out
- * in microtasks before the test's next line. A deadline is still a real one.
- */
-export const noWaitClock: ScrapeClock = Object.freeze({
-  now: () => systemScrapeClock.now(),
-  monotonic: () => systemScrapeClock.monotonic(),
-  sleep: (_ms: number, signal?: AbortSignal) => systemScrapeClock.sleep(0, signal),
-});
-
-let ambient: ScrapeClock | undefined;
-
-/**
- * The clock every run in this process waits on, unless its definition pins one — the counterpart
- * of `setScrapeDriver()`, and the seam a TEST takes: `setScrapeClock(noWaitClock)` in a
- * `beforeEach`, and a declaration under test needs no `clock:` field written for the test's sake.
- */
-export function setScrapeClock(clock: ScrapeClock): void {
-  ambient = clock;
-}
-
-/** The process's scrape clock: the installed one, or the system's. */
-export function scrapeClock(): ScrapeClock {
-  return ambient ?? systemScrapeClock;
-}
-
-/** Test seam: back to the system clock, so the next file runs on real time again. */
-export function resetScrapeClock(): void {
-  ambient = undefined;
-}
-
-/**
- * A clock in which sleeping IS advancing: `await clock.sleep(30_000)` returns on the next
- * microtask with thirty seconds elapsed. This is what makes a poll-until-deadline test instant
- * without the test knowing how many polls the loop makes — a count a test that asserted it would
- * pin to the implementation rather than to the behaviour.
- */
-export interface TestScrapeClock extends ScrapeClock {
-  advance(ms: number): void;
-}
-
-export function testScrapeClock(at: Date | number = 0): TestScrapeClock {
-  let epochMs = at instanceof Date ? at.getTime() : at;
-  let mono = 0;
-  const advance = (ms: number): void => {
-    epochMs += ms;
-    mono += ms;
-  };
-  return {
-    now: () => new Date(epochMs),
-    monotonic: () => mono,
-    advance,
-    sleep: async (ms: number, signal?: AbortSignal) => {
-      advance(ms);
-      // Yield the microtask queue anyway: a loop that never awaits anything real starves whatever
-      // the test armed to cancel it, and the wedge tests arm exactly that.
-      await Promise.resolve();
-      signal?.throwIfAborted();
-    },
-  };
-}
-
 /** Elapsed-time budget, read from one clock. Built once per waiting call, never shared. */
 export interface Deadline {
   readonly totalMs: number;

package/src/driver-cdp.ts

@@ -111,6 +111,9 @@ async function opened(
       browser,
       rules: init.rules,
       clock: init.clock,
+      // Through an exit the EXIT resolves names, so the browser leg's DNS screen stands down — the
+      // HTTP leg's rule, for the same reason (`browser-dial.ts`).
+      proxied: wiring.proxy !== undefined,
       ended,
     });
     if (init.restore !== undefined) await target.restore(init.restore);

package/src/driver-fake.ts

@@ -5,9 +5,8 @@
 // It covers BOTH legs. `fakeBrowser({ pages, http })` replays the browser walk and the JSON
 // endpoints behind it from one declaration, so a hybrid scrape is tested the way it runs.
 
-import { finiteCount } from '@ultimat3/core';
-import type { ScrapeClock } from './clock';
-import { systemScrapeClock } from './clock';
+import type { SleepClock } from '@ultimat3/core';
+import { ambientClock, finiteCount } from '@ultimat3/core';
 import type { ScrapeDriver, ScrapeSession, SessionInit } from './driver';
 import { htmlTarget } from './html-target';
 import { httpRecordingsOf } from './http-recorded';
@@ -78,7 +77,7 @@ export function fakeBrowser(pages: FakePages, options: FakeBrowserOptions = {}):
 
 export interface FakePageOptions {
   readonly url?: string | undefined;
-  readonly clock?: ScrapeClock | undefined;
+  readonly clock?: SleepClock | undefined;
   readonly allowHosts?: readonly string[] | undefined;
   readonly timeoutMs?: number | undefined;
   readonly context?: Partial<PageContext> | undefined;
@@ -97,7 +96,7 @@ export const FAKE_PAGE_URL = 'https://fake.test/';
 export function fakePage(dom: string, options: FakePageOptions = {}): ScrapePage {
   const url = options.url ?? FAKE_PAGE_URL;
   const start: PageRecording = { url, html: dom };
-  const clock = options.clock ?? systemScrapeClock;
+  const clock = options.clock ?? ambientClock();
   const allowHosts = options.allowHosts ?? ['*'];
   const byUrl = new Map(
     [start, ...recordingsOf(options.pages ?? [])].map((page) => [normalise(page.url), page]),

package/src/driver.ts

@@ -1,13 +1,13 @@
 // The browser contract. Every driver implements exactly this, so a scrape's body never names one
 // — the same shape `packages/jobs/src/driver.ts` gives the queue, for the same reason: swapping
-// the browser is `setScrapeDriver(other)` and ZERO run-body change.
+// the browser is `scrapeDriver: other` in `apps/<app>/runtime.ts` and ZERO run-body change.
 //
 // Two methods. `open` hands back a session; `close` ends it. Everything else a scraper does goes
 // through `ScrapePage`, which is driver-blind by construction.
 
-import type { Logger } from '@ultimat3/core';
+import type { Logger, SleepClock } from '@ultimat3/core';
+import { adapterSlot } from '@ultimat3/core/adapter';
 import type { MoneyValue } from '@ultimat3/schema';
-import type { ScrapeClock } from './clock';
 import type { ScrapeHttp } from './http';
 import type { InterceptRules } from './intercept';
 import type { ScrapePage } from './page';
@@ -20,7 +20,7 @@ export interface SessionInit {
   /** The scrape's name — every error cause raised inside the session carries it. */
   readonly name: string;
   readonly rules: InterceptRules;
-  readonly clock: ScrapeClock;
+  readonly clock: SleepClock;
   /**
    * The run's logger — `scrapeLogger()`'s child, so every line carries the scrape and the run.
    * Required, because `close()` never throws: a teardown that failed (a rented browser its
@@ -100,22 +100,27 @@ export interface ScrapeDriver {
   open(init: SessionInit): Promise<ScrapeSession>;
 }
 
-let ambient: ScrapeDriver | undefined;
+const ambient = /* @__PURE__ */ adapterSlot<ScrapeDriver | undefined>(() => undefined);
 
-/** Set once by the app at boot — no config key names it. A scrape's own `driver:` overrides it. */
-export function setScrapeDriver(driver: ScrapeDriver): void {
-  ambient = driver;
+/**
+ * The boot's install, from `scrapeDriver` in `apps/<app>/runtime.ts` — exported from
+ * `@ultimat3/scraping/adapter` only, never the `.` barrel, so that file is the one place an app
+ * chooses a browser. A scrape's own `driver:` overrides it. Answers the release that removes THIS
+ * install and no other (core's `adapterSlot`), in any order, once.
+ */
+export function installScrapeDriver(driver: ScrapeDriver): () => void {
+  return ambient.install(driver);
 }
 
 export function scrapeDriver(): ScrapeDriver | undefined {
-  return ambient;
+  return ambient.current();
 }
 
 /**
- * Test/CLI seam: forget the ambient driver. The counterpart to `resetJobDriver()` — a test that
+ * Test/CLI seam: forget the ambient driver. The counterpart to `resetJobDriver()` (`@ultimat3/jobs/adapter`) — a test that
  * installs a browser has to be able to put the process back, or every later file in the same bun
  * process runs against a driver it never asked for.
  */
 export function resetScrapeDriver(): void {
-  ambient = undefined;
+  ambient.reset();
 }

package/src/error-throws-pdf.ts

@@ -1,6 +1,7 @@
 // The failure mode of a PDF layout request. Split from `error-throws.ts`, which stands at its size
 // ceiling; the code itself stays declared in `errors.ts` — one registry, one place.
 
+import { isRetryableStatus, renderCauseValue, renderFixShellArg } from '@ultimat3/core';
 import { ScrapeError } from './errors';
 
 /**
@@ -14,3 +15,47 @@ export const pdfOptionsInvalid = (reason: string, meta: { readonly field: string
     fix: "page.pdf({ format: 'a4', marginMm: { top: 12, bottom: 12 } }) — exactly one size: a format, or widthMm with heightMm, or preferCssPageSize alone",
     meta: { field: meta.field },
   });
+
+/** No server to load the route from: `APP_URL` unset and no `origin` on the declaration. */
+export const pdfOriginMissing = (): ScrapeError =>
+  new ScrapeError({
+    code: 'X_SCRAPE_PDF_ORIGIN_MISSING',
+    cause:
+      'pdf() has no origin to load its route from: APP_URL is unset in this process and the declaration names no origin',
+    fix: "export APP_URL=https://your.app   # or pdf({ origin: () => 'http://127.0.0.1:3000' }) in the declaring file",
+  });
+
+/** `route()` answered something the printing browser would load from another origin. */
+export const pdfRouteInvalid = (route: string): ScrapeError =>
+  new ScrapeError({
+    code: 'X_SCRAPE_PDF_ROUTE_INVALID',
+    cause: `pdf() route() answered ${renderCauseValue(route)}, which is not a path on this app's origin — the printing browser loads nothing else`,
+    fix: "pdf({ route: ({ input }) => '/invoices/' + input.id + '/print' })   # route() answers a path on this app, never a URL",
+  });
+
+/**
+ * The page answered an error status. A 4xx that no retry can change (a missing record, a route the
+ * printing browser may not read) is terminal on the instance; a 5xx or 429 stays retryable.
+ */
+export const pdfRouteFailed = (url: string, status: number): ScrapeError => {
+  const path = new URL(url).pathname;
+  return new ScrapeError({
+    code: 'X_SCRAPE_PDF_ROUTE_FAILED',
+    cause: `the route pdf() printed, ${renderCauseValue(path)}, answered HTTP ${String(status)}: printing it would store an error page as the document`,
+    fix: `curl -i "$APP_URL"${renderFixShellArg(path, '/<the path the cause names>')}   # a private route needs pdf({ headers }); a missing one, a route() naming a record that exists`,
+    meta: { status },
+    retry: status >= 400 && status < 500 && !isRetryableStatus(status) ? 'terminal' : 'retryable',
+  });
+};
+
+/** Every render slot stayed busy for the whole queue deadline: a burst, not a broken page. */
+export const pdfBusy = (input: {
+  readonly maxConcurrent: number;
+  readonly queueTimeoutMs: number;
+}): ScrapeError =>
+  new ScrapeError({
+    code: 'X_SCRAPE_PDF_BUSY',
+    cause: `all ${String(input.maxConcurrent)} pdf() render slot(s) stayed busy for ${String(input.queueTimeoutMs)}ms — each holds a live Chrome, so the renderer bounds them rather than let a burst exhaust this process's memory`,
+    fix: `pdf({ renderer: chromePdfRenderer({ maxConcurrent: ${String(input.maxConcurrent * 2)} }) })   # only on a host with the memory for it; otherwise the caller retries later`,
+    meta: { maxConcurrent: input.maxConcurrent, queueTimeoutMs: input.queueTimeoutMs },
+  });

package/src/error-throws-session.ts

@@ -51,7 +51,7 @@ export const promptTimedOut = (input: {
   new ScrapeError({
     code: 'X_SCRAPE_PROMPT_UNANSWERED',
     cause: `scrape "${input.scrape}" asked for "${input.label}" and no answer was published to ${input.event} within ${String(input.waitedMs)}ms`,
-    fix: 'call answerPrompt({ runId, index, answer }) with the run id and index the event name in the cause ends with, from a process on the same STORED event bus — setEventBus(postgresEventBus({ executor })) — or raise eventPrompt({ timeout })',
+    fix: 'call answerPrompt({ runId, index, answer }) with the run id and index the event name in the cause ends with, from a process on the same STORED event bus — eventBus: postgresEventBus({ executor }) in apps/<app>/runtime.ts — or raise eventPrompt({ timeout })',
     meta: {
       scrape: input.scrape,
       label: input.label,

package/src/error-throws.ts

@@ -30,8 +30,8 @@ export const driverUnknown = (
     cause:
       scrape === undefined
         ? `no scrape driver named "${name ?? 'none'}" is installed; installed: ${installed.join(', ') || 'none'}`
-        : `scrape "${scrape}" has no browser driver: nothing called setScrapeDriver() and the definition declares no driver; installed: ${installed.join(', ') || 'none'}`,
-    fix: 'call setScrapeDriver(localBrowser()) at boot, or pass driver: fakeBrowser() on the scrape() definition',
+        : `scrape "${scrape}" has no browser driver: apps/<app>/runtime.ts names no scrapeDriver and the definition declares no driver; installed: ${installed.join(', ') || 'none'}`,
+    fix: 'export const runtime = { scrapeDriver: localBrowser() }   # apps/<app>/runtime.ts — or pass driver: fakeBrowser() on the scrape() definition',
     meta: { driver: name ?? 'none', ...(scrape === undefined ? {} : { scrape }) },
   });
 
@@ -217,7 +217,7 @@ export const wedged = (what: string, idleMs: number): ScrapeError =>
  * opposite fixes are two codes, and the classifications differ with them: a wedge is retryable,
  * this is terminal (`errors.ts`).
  *
- * Reachable through the `ScrapeClock` seam and the driver's `kill()`, both of which a third party
+ * Reachable through the `SleepClock` seam and the driver's `kill()`, both of which a third party
  * writes. Leaving the loop dead and quiet is the alternative, and that is incident #1 with no
  * guard armed at all.
  */
@@ -225,7 +225,7 @@ export const watchdogStopped = (what: string, thrown: unknown): ScrapeError =>
   new ScrapeError({
     code: 'X_SCRAPE_WATCHDOG_STOPPED',
     cause: `the wedge watchdog for ${what} stopped measuring browser activity: ${renderThrowable(thrown)}`,
-    fix: 'drop the custom clock: from the scrape() definition — systemScrapeClock is the only ScrapeClock whose sleep() cannot reject — then re-run',
+    fix: "drop the custom clock: from the scrape() definition and any clock: line in apps/<app>/runtime.ts — @ultimat3/core's systemClock is the only SleepClock whose sleep() cannot reject — then re-run",
     meta: { what },
   });
 

package/src/errors.ts

@@ -43,6 +43,10 @@ export const SCRAPE_OWNED_ERROR_CODES = [
   'X_SCRAPE_EGRESS_IN_PAYLOAD',
   'X_SCRAPE_LAUNCH_ARGS_INVALID',
   'X_SCRAPE_PDF_OPTIONS_INVALID',
+  'X_SCRAPE_PDF_ORIGIN_MISSING',
+  'X_SCRAPE_PDF_ROUTE_INVALID',
+  'X_SCRAPE_PDF_ROUTE_FAILED',
+  'X_SCRAPE_PDF_BUSY',
 ] as const;
 
 /**
@@ -101,6 +105,10 @@ export const SCRAPE_ERROR_TITLES: Readonly<Record<ScrapeOwnedErrorCode, string>>
     'the launch options carry arguments this driver cannot hand the browser',
   X_SCRAPE_PDF_OPTIONS_INVALID:
     'the PDF request names no single page size a print engine can lay out',
+  X_SCRAPE_PDF_ORIGIN_MISSING: 'pdf() has no origin to render the route on',
+  X_SCRAPE_PDF_ROUTE_INVALID: 'a pdf() route is not a path on this app',
+  X_SCRAPE_PDF_ROUTE_FAILED: 'the route pdf() printed answered an error status',
+  X_SCRAPE_PDF_BUSY: 'every pdf() render slot stayed busy past the queue deadline',
 };
 
 // One unconditional call, so a second package claiming one of these codes throws
@@ -181,7 +189,7 @@ export const SCRAPE_ERROR_RETRY = {
   // TERMINAL where its sibling `X_SCRAPE_WEDGED` is retryable, and the difference IS the reason
   // the two codes are separate. A wedge is the site or the browser being slow — the definition of
   // "run it again and it may go differently". This is the guard's own loop dying on code the
-  // DEFINITION supplied: a `ScrapeClock` an app wrote, reached identically on attempt 2. Retrying
+  // DEFINITION supplied: a `SleepClock` an app wrote, reached identically on attempt 2. Retrying
   // launches a real browser five times to die at the first poll, and on an authenticated target
   // that is five arrivals at a login for no chance of a different answer — the rule this whole
   // table is written to, stated at the top of it. The fix is an edit, so a human decides.
@@ -214,6 +222,14 @@ export const SCRAPE_ERROR_RETRY = {
   // The request is the caller's literal, refused before any driver sees it: attempt 2 asks for the
   // same two sizes and is refused identically.
   X_SCRAPE_PDF_OPTIONS_INVALID: 'terminal',
+  // The deploy's environment and the declaration's own `route()`: attempt 2 reads the same ones.
+  X_SCRAPE_PDF_ORIGIN_MISSING: 'terminal',
+  X_SCRAPE_PDF_ROUTE_INVALID: 'terminal',
+  // The page answered an error: a 503 mid-deploy is the moment, so a `.job()` run tries again.
+  // The throw site narrows a 4xx to terminal — a missing record is missing on attempt 2 too.
+  X_SCRAPE_PDF_ROUTE_FAILED: 'retryable',
+  // Every slot busy is the moment, never the request: the same render fits once one ends.
+  X_SCRAPE_PDF_BUSY: 'retryable',
 } as const satisfies Readonly<Record<ScrapeOwnedErrorCode, 'retryable' | 'terminal'>>;
 
 registerErrorRetry(SCRAPE_ERROR_RETRY);

package/src/event-prompt.ts

@@ -54,7 +54,7 @@ export interface EventPromptOptions {
  * Only an answer published AFTER the prompt was asked is consumed. The run id is the same on
  * every attempt, so a code left over from attempt 1 would otherwise be typed into the site by
  * attempt 2 — and a stale code is a refused login. "After" is decided on ONE clock, the bus's
- * (`bus.now()`); the timeout and the poll stay on the run's own.
+ * (`bus.mark()`, or `bus.now()`); the timeout and the poll stay on the run's own.
  */
 export function eventPrompt(options: EventPromptOptions): PromptHandler {
   // Floors of 1, both: a zero timeout is a prompt that can never be answered and a zero interval
@@ -73,18 +73,24 @@ export function eventPrompt(options: EventPromptOptions): PromptHandler {
         driver: 'event bus',
         cause:
           'eventPrompt() was asked on the in-memory event bus — the answer is published by another process and can never reach this one',
-        fix: 'call setEventBus(postgresEventBus({ executor })) at boot — x dev and the served roles do — or pass bus: postgresEventBus({ executor }) to eventPrompt()',
+        fix: 'export const runtime = { eventBus: postgresEventBus({ executor }) }   # apps/<app>/runtime.ts — or delete that line: x dev and the served roles install it — or pass bus: postgresEventBus({ executor }) to eventPrompt()',
       });
     }
     const event = promptEventName(request.runId, request.index);
     // The BUS's clock, read once: an answer's `publishedAt` is stamped by it — the database, for
     // the stored bus — and `request.clock` is this worker's. Comparing the two let a few seconds
     // of skew between pods decide that an answer given after the ask had come before it.
-    const askedAt = await bus.now();
+    // Read with the bus's MARK where it has one, in the same statement: an answer stamped at
+    // INSERT and committed after this instant carries a stamp before it, and only a search under
+    // the mark's horizon still sees it (`EventLookup.mark`).
+    const mark: { readonly at: number; readonly horizon?: string } = (await bus.mark?.()) ?? {
+      at: await bus.now(),
+    };
+    const askedAt = mark.at;
     const budget = deadline(request.clock, timeoutMs, 'eventPrompt');
     for (;;) {
       request.signal?.throwIfAborted();
-      const found = await bus.find(event, undefined, askedAt);
+      const found = await bus.find(event, undefined, askedAt, undefined, mark.horizon, mark);
       if (found !== undefined) {
         if (!isSealed(found.payload)) {
           throw promptAnswerInvalid({ scrape: request.scrape, label: request.label, event });

package/src/events.ts

@@ -11,8 +11,7 @@
 // of a log line: `ScrapeEventFields` has no key to put one in, and core's logger redacts the
 // remaining spellings by key and every `Secret` by value.
 
-import type { Logger } from '@ultimat3/core';
-import type { ScrapeClock } from './clock';
+import type { Logger, SleepClock } from '@ultimat3/core';
 import { errorCode } from './failures';
 
 export interface ScrapeEventFields {
@@ -48,7 +47,7 @@ export const scrapeLogger = (logger: Logger, fields: ScrapeEventFields): Logger
 export interface StepEvent {
   readonly name: string;
   readonly logger: Logger;
-  readonly clock: ScrapeClock;
+  readonly clock: SleepClock;
   readonly attempt?: number | undefined;
 }
 

package/src/html-target.ts

@@ -5,9 +5,9 @@
 // through to the network would make a green offline suite that is secretly hitting production —
 // the exact failure an offline driver exists to prevent.
 
+import type { SleepClock } from '@ultimat3/core';
 import { NotImplementedError } from '@ultimat3/core';
 import type { CaptureClip } from './capture-clip';
-import type { ScrapeClock } from './clock';
 import type { ColorScheme } from './color-scheme';
 import { browserUnreachable, downloadTimeout, fixtureMissing, fixtureStale } from './error-throws';
 import { queryHtml } from './html-query';
@@ -84,7 +84,7 @@ export interface HtmlTargetInit {
   readonly driver: string;
   readonly lookup: RecordingLookup;
   readonly rules: InterceptRules;
-  readonly clock: ScrapeClock;
+  readonly clock: SleepClock;
   /** Where recordings come from, for the cause line: a directory, or `fakeBrowser()`. */
   readonly source: string;
   readonly start?: PageRecording | undefined;

package/src/http-recorded.ts

@@ -5,7 +5,7 @@
 // real network would make the hybrid path — which is where the interesting code lives — the one
 // path a test never really covers.
 
-import type { ScrapeClock } from './clock';
+import type { SleepClock } from '@ultimat3/core';
 import { fixtureMissing, fixtureStale, hostBlocked } from './error-throws';
 import type { HttpRequestInit, ScrapeHttp, ScrapeResponse } from './http';
 import { responseOver } from './http';
@@ -26,7 +26,7 @@ export interface RecordedHttpInit {
   readonly lookup: HttpRecordingLookup;
   readonly rules: InterceptRules;
   readonly network: NetworkRing;
-  readonly clock: ScrapeClock;
+  readonly clock: SleepClock;
   readonly source: string;
   /**
    * The SAME gate the page leg holds. Without it a hybrid scrape whose JSON endpoint is

package/src/http.ts

@@ -10,11 +10,11 @@
 // guarantee the page vocabulary makes — and a different exit IP mid-session is exactly what
 // anti-bot systems look for.
 
+import type { SleepClock } from '@ultimat3/core';
 import { finiteCount, readWithinLimit } from '@ultimat3/core';
 import { type DeadlineTimer, deadlineSignal, resolveDialHost } from '@ultimat3/core/outbound';
 import type { StandardSchemaV1 } from '@ultimat3/schema';
 import { parse } from '@ultimat3/schema';
-import type { ScrapeClock } from './clock';
 import { cookieHeaderFor } from './cookie-scope';
 import { bodyTooLarge, hostBlocked, httpFailed, redirectLoop, scrapeTimeout } from './error-throws';
 import type { RedirectHop } from './http-redirect';
@@ -96,7 +96,7 @@ export interface ScrapeHttp {
 
 export interface HttpTransportInit {
   readonly rules: InterceptRules;
-  readonly clock: ScrapeClock;
+  readonly clock: SleepClock;
   readonly timeoutMs: number;
   readonly network: NetworkRing;
   /**