@ultimat3/scraping 22.15.0 → 24.0.0

package/src/event-prompt.ts

@@ -0,0 +1,133 @@
+// A prompt answered from ANOTHER process while the browser stays open: `eventPrompt()` is a
+// `PromptHandler` that polls the stored job event bus, and `answerPrompt()` is the one way an
+// answer is published to it.
+//
+// It polls IN PROCESS and never uses `step.waitForEvent`: that suspends the run, the attempt ends,
+// `runScrape`'s `finally` closes the session — and the site is waiting for the code inside that
+// session. So the run keeps its claim (the worker's heartbeat is a timer, untouched by a poll),
+// keeps the browser alive between polls, and gives up on the run's own cancellation.
+//
+// The event name is DERIVED — `scrape-prompt:<runId>:<n>` — and it is not an authorization: the
+// app's answering action is policy-checked like any action and calls `answerPrompt()`.
+
+import type { SealKeySource } from '@ultimat3/core';
+import { finiteCount, isLocal, isSealed, openText, seal } from '@ultimat3/core';
+import type { EventBus, JobEvent } from '@ultimat3/jobs';
+import { DriverUnavailableError, eventBus } from '@ultimat3/jobs';
+import type { PromptHandler, PromptRequest } from './auth';
+import { deadline, throwIfAborted } from './clock';
+import { promptAnswerInvalid, promptTimedOut } from './error-throws-session';
+
+/** How often the bus is asked. One indexed read and one browser round trip per interval. */
+export const DEFAULT_PROMPT_POLL_MS = 1_000;
+
+/**
+ * How long a published answer stays matchable. Short on purpose: an answer is a one-time code,
+ * and the stored bus's own default keeps an event for a week.
+ */
+export const DEFAULT_PROMPT_ANSWER_TTL_MS = 600_000;
+
+/** The one spelling. `index` is `PromptRequest.index`: 1 for the first prompt of an attempt. */
+export const promptEventName = (runId: string, index: number): string =>
+  `scrape-prompt:${runId}:${String(index)}`;
+
+export interface EventPromptOptions {
+  /** Milliseconds one prompt waits for its answer before `X_SCRAPE_PROMPT_UNANSWERED`. */
+  readonly timeout: number;
+  /** Milliseconds between two looks at the bus. Defaults to `DEFAULT_PROMPT_POLL_MS`. */
+  readonly pollMs?: number | undefined;
+  /**
+   * The bus to read. Defaults to the ambient one, read when the prompt is ASKED — boot installs
+   * the stored bus after this module is evaluated. It has to be the stored one in any deployment
+   * with more than one process: the answer is published by a web process, never by this worker.
+   */
+  readonly bus?: EventBus | undefined;
+  /** Where the master key is read from, for opening the answer. `seal()`'s own two fields. */
+  readonly keySource?: SealKeySource | undefined;
+  /** Where the environment is read from. Defaults to the process's own. */
+  readonly env?: Readonly<Record<string, string | undefined>> | undefined;
+}
+
+/**
+ * `prompt: eventPrompt({ timeout: 300_000 })` on a `scrape()` definition.
+ *
+ * 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.
+ */
+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
+  // is the poll loop spinning on the worker's only thread.
+  const timeoutMs = finiteCount('eventPrompt', 'timeout', options.timeout, 1);
+  const pollMs = finiteCount('eventPrompt', 'pollMs', options.pollMs ?? DEFAULT_PROMPT_POLL_MS, 1);
+  return async (request: PromptRequest): Promise<string> => {
+    const bus = options.bus ?? eventBus();
+    // Refused when the prompt is ASKED, before the wait: the answer is published by a web process
+    // and read by this worker, so an in-memory bus can only ever time out — minutes later, as
+    // `X_SCRAPE_PROMPT_UNANSWERED`, blaming the human who did answer. Development and test run
+    // every role in one process, where the in-memory bus is the right one. `=== false`, never
+    // `!bus.stored`: only a bus that SAYS it is not stored is refused.
+    if (bus.stored === false && !isLocal({ env: options.env, fallback: 'production' })) {
+      throw new DriverUnavailableError({
+        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(createPgEventBus({ executor })) at boot — x dev and the served roles do — or pass bus: createPgEventBus({ 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();
+    const budget = deadline(request.clock, timeoutMs, 'eventPrompt');
+    for (;;) {
+      if (request.signal !== undefined) throwIfAborted(request.signal);
+      const found = await bus.find(event, undefined, askedAt);
+      if (found !== undefined) {
+        if (!isSealed(found.payload)) {
+          throw promptAnswerInvalid({ scrape: request.scrape, label: request.label, event });
+        }
+        // The purpose IS the event name, so an answer sealed for another run or another prompt of
+        // this one fails its tag instead of being typed.
+        return await openText(found.payload, { purpose: event, ...options.keySource });
+      }
+      if (budget.expired()) {
+        throw promptTimedOut({
+          scrape: request.scrape,
+          label: request.label,
+          event,
+          waitedMs: timeoutMs,
+        });
+      }
+      await request.keepAlive();
+      await request.clock.sleep(Math.min(pollMs, budget.remainingMs()), request.signal);
+    }
+  };
+}
+
+export interface AnswerPromptInput {
+  readonly runId: string;
+  /** Which prompt of the run: `PromptRequest.index`. */
+  readonly index: number;
+  readonly answer: string;
+  /** Milliseconds the answer stays matchable. Defaults to `DEFAULT_PROMPT_ANSWER_TTL_MS`. */
+  readonly ttl?: number | undefined;
+  readonly bus?: EventBus | undefined;
+  readonly keySource?: SealKeySource | undefined;
+}
+
+/**
+ * Publish one prompt's answer. Called from the app's own action, after its policy passed.
+ *
+ * The answer is SEALED before it is published: the stored bus is a table, and an OTP or a
+ * security answer written there in the clear is a credential in a queue row.
+ */
+export async function answerPrompt(input: AnswerPromptInput): Promise<JobEvent> {
+  const event = promptEventName(input.runId, input.index);
+  const sealed = await seal(input.answer, { purpose: event, ...input.keySource });
+  return (input.bus ?? eventBus()).publish(event, sealed, {
+    ttl: finiteCount('answerPrompt', 'ttl', input.ttl ?? DEFAULT_PROMPT_ANSWER_TTL_MS, 1),
+  });
+}

package/src/events.ts

@@ -33,6 +33,12 @@ export interface ScrapeEventFields {
   readonly refused?: number | undefined;
   readonly reused?: boolean | undefined;
   readonly burned?: boolean | undefined;
+  /** `ScrapeUsage`'s counts — numbers only, so a failed run still says what it spent. */
+  readonly browserMs?: number | undefined;
+  readonly navigations?: number | undefined;
+  readonly httpRequests?: number | undefined;
+  readonly bytesIn?: number | undefined;
+  readonly promptsAnswered?: number | undefined;
 }
 
 /** One child logger per run, so every line downstream carries the run's identity unasked. */

package/src/expect.ts

@@ -3,7 +3,7 @@
 // where the data went. `expect` turns that into a red run: a yield under `minRows`, or under
 // `maxDrop` of what this scrape normally returns, throws.
 
-import { finiteCount, finiteOption } from '@ultimat3/core';
+import { assert, finiteCount, finiteOption } from '@ultimat3/core';
 import { yieldCollapsed } from './error-throws';
 import type { ScrapeError } from './errors';
 
@@ -57,6 +57,23 @@ export interface YieldCheck {
   readonly history: readonly number[];
 }
 
+/**
+ * `maxDrop`, screened: finite, then a FRACTION in `[0, 1)`. `1` and anything above it — `50`, the
+ * percent habit — make `baseline * (1 - maxDrop)` zero or negative, so no yield is ever under it
+ * and the alarm is silent forever; a negative one fires on a run that matched its baseline. Asked
+ * by the rule and by `scrape()`, where the number is written.
+ */
+export function maxDropFraction(scrape: string, value: number): number {
+  const fraction = finiteOption('the scrape expect', 'maxDrop', value);
+  assert(
+    fraction >= 0 && fraction < 1,
+    `scrape "${scrape}" declares expect.maxDrop: ${String(fraction)}, and maxDrop is a fraction of the trailing median from 0 up to but not including 1 — at 1 or above no yield is ever under the line and the alarm can never fire; write it as a fraction, expect: { maxDrop: 0.5 } allows half`,
+    // Lists every declaration outside [0, 1) — static, so no declared value reaches a shell.
+    "grep -rnE --include='*.ts' 'maxDrop: *(-|[1-9]|1\\.)' .",
+  );
+  return fraction;
+}
+
 /**
  * The whole rule, pure: the error this yield earns, or `undefined`. Pure so a test can hand it
  * fifty histories without a queue, a browser or a clock.
@@ -69,8 +86,8 @@ export function yieldProblem(check: YieldCheck): ScrapeError | undefined {
   // instead, and an alarm that always fires is an alarm somebody turns off.
   //
   // `minRows: 0` is legal and stays legal: this file asks an author whose answer is legitimately
-  // sometimes zero to declare exactly that. `maxDrop` is a FRACTION of a median, so `finiteOption`
-  // and not `finiteCount` — `0.5` is the documented value.
+  // sometimes zero to declare exactly that. `maxDrop` is a FRACTION of a median, so not
+  // `finiteCount` — `0.5` is the documented value (`maxDropFraction`).
   const minRows =
     check.expect.minRows === undefined
       ? undefined
@@ -78,7 +95,7 @@ export function yieldProblem(check: YieldCheck): ScrapeError | undefined {
   const maxDrop =
     check.expect.maxDrop === undefined
       ? undefined
-      : finiteOption('the scrape expect', 'maxDrop', check.expect.maxDrop);
+      : maxDropFraction(check.scrape, check.expect.maxDrop);
   if (minRows !== undefined && check.rows < minRows) {
     return yieldCollapsed({ scrape: check.scrape, rows: check.rows, reason: 'min-rows', minRows });
   }

package/src/html-target.ts

@@ -5,16 +5,11 @@
 // 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 { 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,
-  scrapeNotImplemented,
-} from './error-throws';
+import { browserUnreachable, downloadTimeout, fixtureMissing, fixtureStale } from './error-throws';
 import { queryHtml } from './html-query';
 import { markupRequests } from './html-requests';
 import type { InterceptRules } from './intercept';
@@ -358,10 +353,10 @@ export function htmlTarget(init: HtmlTargetInit): ScrapeTarget {
      * attribute would pass every test against the element a screen reader cannot reach.
      */
     async accessibility(_selector: string, _max: number): Promise<readonly AxNode[]> {
-      throw scrapeNotImplemented(
-        `accessibility() on the ${init.driver} driver`,
-        'run this assertion on localBrowser()/remoteBrowser(), whose accessibility() reads the tree the browser computed — an offline driver parses markup and computes no role',
-      );
+      throw new NotImplementedError({
+        cause: `accessibility() on the ${init.driver} driver is not implemented by this driver`,
+        fix: 'run this assertion on localBrowser()/remoteBrowser(), whose accessibility() reads the tree the browser computed — an offline driver parses markup and computes no role',
+      });
     },
     evaluate(expression: string): Promise<unknown> {
       live();
@@ -381,10 +376,10 @@ export function htmlTarget(init: HtmlTargetInit): ScrapeTarget {
     // `async`, so the refusal REJECTS: the method is typed `Promise<void>` and a synchronous
     // `throw` from one jumps straight over `page.offline(true).catch(…)` at every caller.
     async setOfflineMode(_enabled: boolean): Promise<void> {
-      throw scrapeNotImplemented(
-        `setOfflineMode() on the ${init.driver} driver`,
-        'run this assertion on localBrowser()/remoteBrowser(), whose setOfflineMode() reaches a real browser — an offline driver has no network to cut, so it cannot prove an offline behaviour',
-      );
+      throw new NotImplementedError({
+        cause: `setOfflineMode() on the ${init.driver} driver is not implemented by this driver`,
+        fix: 'run this assertion on localBrowser()/remoteBrowser(), whose setOfflineMode() reaches a real browser — an offline driver has no network to cut, so it cannot prove an offline behaviour',
+      });
     },
     /**
      * ACCEPTED and recorded, where `setOfflineMode` refuses — and the line between them is which

package/src/http-recorded.ts

@@ -15,6 +15,7 @@ import type { HttpRecording } from './recording';
 import type { NetworkRing } from './rings';
 import type { RobotsGate } from './robots';
 import type { ScrapeSecrets } from './secrets';
+import type { UsageMeter } from './usage';
 
 export type HttpRecordingLookup = (
   method: string,
@@ -36,6 +37,8 @@ export interface RecordedHttpInit {
   readonly maxAgeMs?: number | undefined;
   /** The SAME bag the live leg holds, so a recorded 4xx body redacts the way a real one does. */
   readonly secrets?: ScrapeSecrets | undefined;
+  /** The SAME meter the live leg counts into, so a fixture run reports the usage a real one would. */
+  readonly usage?: UsageMeter | undefined;
 }
 
 /** `GET https://api.example.com/v1/orders?page=2` -> `http-get-api-example-com-v1-orders-page-2`. */
@@ -61,7 +64,9 @@ export function recordedHttp(init: RecordedHttpInit): ScrapeHttp {
       if (found === undefined) throw fixtureMissing(`${method} ${url}`, init.source);
       if (init.maxAgeMs !== undefined && found.recordedAt !== undefined) {
         const age = init.clock.now().getTime() - new Date(found.recordedAt).getTime();
-        if (age > init.maxAgeMs) throw fixtureStale(`${method} ${url}`, age, init.maxAgeMs);
+        // `!(age <= limit)`, never `age > limit`: an unparseable `recordedAt` makes `age` NaN, and
+        // `NaN > limit` is false — a recording of unknown age replayed as fresh. `auth.ts` the same.
+        if (!(age <= init.maxAgeMs)) throw fixtureStale(`${method} ${url}`, age, init.maxAgeMs);
       }
       init.network.push({
         method,
@@ -70,6 +75,7 @@ export function recordedHttp(init: RecordedHttpInit): ScrapeHttp {
         resourceType: 'fetch',
         at: init.clock.now().getTime(),
       });
+      init.usage?.httpRequest(new TextEncoder().encode(found.body).length);
       return responseOver(
         url,
         found.status,

package/src/http.ts

@@ -20,11 +20,14 @@ import type { RedirectHop } from './http-redirect';
 import { MAX_REDIRECT_HOPS, redirectHop } from './http-redirect';
 import type { InterceptRules } from './intercept';
 import { interceptVerdict } from './intercept';
+import type { DialTarget, HostResolve } from './pinned-host';
+import { dialTarget, resolveHost } from './pinned-host';
 import type { NetworkRing } from './rings';
 import type { RobotsGate } from './robots';
 import type { ScrapeSecrets } from './secrets';
 import { redactSecrets } from './secrets';
 import type { SessionSnapshot } from './session-state';
+import type { UsageMeter } from './usage';
 
 /**
  * Just the call. `typeof fetch` also carries `preconnect`, which no test double and no app wrapper
@@ -42,6 +45,11 @@ export type ScrapeFetch = (input: string, init: ScrapeFetchInit) => Promise<Resp
 export interface ScrapeFetchInit extends RequestInit {
   /** The session's exit. A different exit IP mid-session is a different client to an anti-bot. */
   readonly proxy?: string | undefined;
+  /**
+   * The NAME a pinned connection proves (`pinned-host.ts`): the url names the approved address,
+   * and Bun's `fetch` verifies the certificate against this instead.
+   */
+  readonly tls?: { readonly serverName?: string | undefined } | undefined;
 }
 
 export interface HttpRequestInit {
@@ -110,7 +118,11 @@ export interface HttpTransportInit {
    * until 2026-08-24, so nothing on this leg COULD redact.
    */
   readonly secrets?: ScrapeSecrets | undefined;
+  /** The run's meter: one `httpRequest` per hop on the wire, with the body bytes read for it. */
+  readonly usage?: UsageMeter | undefined;
   readonly fetch?: ScrapeFetch | undefined;
+  /** The resolver a wildcard-admitted name is checked and pinned with. Defaults to `Bun.dns`. */
+  readonly resolve?: HostResolve | undefined;
 }
 
 /**
@@ -193,6 +205,22 @@ const withoutCredentials = (headers: Readonly<Record<string, string>>): Record<s
     Object.entries(headers).filter(([name]) => !CROSS_ORIGIN_STRIPPED.has(name.toLowerCase())),
   );
 
+/**
+ * The request's headers from every source, LATER sources winning, keyed by the lower-cased name.
+ * HTTP names are case-insensitive and `Headers` APPENDS two spellings of one name: a caller's
+ * `User-Agent: Mine` beside the session's `user-agent` went out as `BrowserUA, Mine`, and a
+ * declared `Cookie` was joined to the jar's instead of replacing it.
+ */
+const composeHeaders = (
+  ...sources: readonly Readonly<Record<string, string>>[]
+): Record<string, string> => {
+  const out = new Map<string, string>();
+  for (const source of sources) {
+    for (const [name, value] of Object.entries(source)) out.set(name.toLowerCase(), value);
+  }
+  return Object.fromEntries(out);
+};
+
 /** Unparseable is not same-origin: a URL this package cannot read is one it cannot vouch for. */
 const sameOrigin = (left: string, right: string): boolean => {
   try {
@@ -213,8 +241,11 @@ const readResponse = async (
   response: Response,
   maxBytes: number,
   secrets: ScrapeSecrets | undefined,
+  usage: UsageMeter | undefined,
 ): Promise<ScrapeResponse> => {
   const capped = await readWithinLimit(response.body, maxBytes);
+  // Counted on BOTH branches: the bytes a refused body cost were read before the refusal.
+  usage?.httpRequest('over' in capped ? capped.over : capped.bytes.length);
   if ('over' in capped) throw bodyTooLarge(url, capped.over, maxBytes);
   const body = new TextDecoder().decode(capped.bytes);
   return responseOver(
@@ -245,12 +276,21 @@ export function httpOverFetch(init: HttpTransportInit): ScrapeHttp {
    * The three gates, in one place, so the initial URL and hop seven are screened by the same code
    * in the same order. A second copy for redirects is how the two drift.
    */
-  const screen = async (target: string): Promise<void> => {
+  const resolve = init.resolve ?? resolveHost;
+  const screen = async (target: string): Promise<DialTarget> => {
     if (interceptVerdict(target, 'fetch', init.rules) !== 'allow') {
       throw hostBlocked(target, init.rules.allowHosts);
     }
+    // Through a proxy the PROXY resolves the name, from its own network, so an answer from this
+    // box's resolver says nothing about where the request lands — and pinning would hand the
+    // proxy an address where it expects the name.
+    const dial =
+      init.proxy === undefined
+        ? await dialTarget(target, init.rules.allowHosts, resolve)
+        : { url: target };
     await init.robots?.assertAllowed(target);
     await init.pace?.(init.signal);
+    return dial;
   };
   return {
     async request(url: string, request: HttpRequestInit = {}): Promise<ScrapeResponse> {
@@ -278,7 +318,7 @@ export function httpOverFetch(init: HttpTransportInit): ScrapeHttp {
         1,
       );
       init.onActivity?.();
-      await screen(url);
+      let dial = await screen(url);
       const session = await init.session();
       // `AbortSignal.timeout` and NOT `clock.sleep`: this is a deadline handed to the platform's
       // own fetch, not a wait this package performs — and under a test clock a slept deadline
@@ -313,14 +353,17 @@ export function httpOverFetch(init: HttpTransportInit): ScrapeHttp {
           const declared = credentialsInScope
             ? request.headers
             : withoutCredentials(request.headers ?? {});
-          const response = await call(hop.url, {
+          const response = await call(dial.url, {
             method: hop.method,
-            headers: {
-              ...carried,
-              ...(session.userAgent === '' ? {} : { 'user-agent': session.userAgent }),
-              ...(cookies === undefined ? {} : { cookie: cookies }),
-              ...declared,
-            },
+            headers: composeHeaders(
+              carried,
+              session.userAgent === '' ? {} : { 'user-agent': session.userAgent },
+              cookies === undefined ? {} : { cookie: cookies },
+              declared ?? {},
+              // Last: a pinned request is reached AS the name that was screened, whatever was declared.
+              dial.host === undefined ? {} : { host: dial.host },
+            ),
+            ...(dial.serverName === undefined ? {} : { tls: { serverName: dial.serverName } }),
             ...(hop.body === undefined ? {} : { body: hop.body }),
             signal: AbortSignal.any(signals),
             // The whole point: the platform's own `follow` is what made the four lines above
@@ -345,14 +388,16 @@ export function httpOverFetch(init: HttpTransportInit): ScrapeHttp {
             hop.body,
           );
           if (next === undefined)
-            return await readResponse(hop.url, response, maxBytes, init.secrets);
+            return await readResponse(hop.url, response, maxBytes, init.secrets, init.usage);
+          // A followed hop was a request on the wire too; its body is discarded unread.
+          init.usage?.httpRequest(0);
           // Discarded BEFORE the refusal, not after it: a throw over an unread stream holds that
           // hop's socket until the collector reaches it, and the refusal path is exactly the one a
           // hostile chain drives ten times per request.
           await discardHopBody(response);
           if (followed >= MAX_REDIRECT_HOPS) throw redirectLoop(url, next.url, followed + 1);
           init.onActivity?.();
-          await screen(next.url);
+          dial = await screen(next.url);
           if (!sameOrigin(hop.url, next.url)) credentialsInScope = false;
           hop = next;
         }

package/src/index.ts

@@ -12,6 +12,7 @@ export {
 export type {
   AuthContext,
   PromptHandler,
+  PromptInit,
   PromptRequest,
   ScrapeAuth,
 } from './auth';
@@ -21,6 +22,8 @@ export type { CaptureClip, CaptureFraming } from './capture-clip';
 export { assertCaptureFraming } from './capture-clip';
 export type {
   CdpBrowserLike,
+  CdpBrowserSessionLike,
+  CdpBrowserTargetLike,
   CdpFrameLike,
   CdpKeyboardLike,
   CdpLauncherLike,
@@ -29,11 +32,21 @@ export type {
   CdpScreenshotOptions,
   CdpSessionLike,
 } from './cdp-port';
+export type { CdpResolution, CdpResolver, CdpResolverRequest } from './cdp-resolver';
 export { snapshotExpression } from './cdp-snapshot';
 export type { CdpTargetInit } from './cdp-target';
 export { CDP_DRIVER, cdpTarget } from './cdp-target';
 export type { Deadline, ScrapeClock, TestScrapeClock } from './clock';
-export { deadline, systemScrapeClock, testClock, throwIfAborted } from './clock';
+export {
+  deadline,
+  noWaitClock,
+  resetScrapeClock,
+  scrapeClock,
+  setScrapeClock,
+  systemScrapeClock,
+  testClock,
+  throwIfAborted,
+} from './clock';
 export type { ColorScheme } from './color-scheme';
 export { COLOR_SCHEMES, isColorScheme } from './color-scheme';
 export { cookieHeaderFor } from './cookie-scope';
@@ -43,14 +56,15 @@ export type { BrowserOptions, LocalBrowserOptions, RemoteBrowserOptions } from '
 export { localBrowser, remoteBrowser } from './driver-cdp';
 export type { FakeBrowserOptions, FakePageOptions, FakePages } from './driver-fake';
 export { FAKE_DRIVER, FAKE_PAGE_URL, fakeBrowser, fakePage, recordingsOf } from './driver-fake';
-export type { FixtureBrowserOptions } from './driver-fixture';
-export { FIXTURE_DRIVER, fixtureBrowser } from './driver-fixture';
+export type { FixtureBrowserOptions } from './driver-recorded';
+export { FIXTURE_DRIVER, fixtureBrowser } from './driver-recorded';
 export {
   authFailed,
   blocked,
   bodyTooLarge,
   browserUnreachable,
   cdpAttachFailed,
+  cdpResolveFailed,
   downloadTimeout,
   driverUnknown,
   fixtureMissing,
@@ -67,7 +81,6 @@ export {
   redirectLoop,
   remoteRequired,
   robotsDisallowed,
-  scrapeNotImplemented,
   scrapeTimeout,
   secretExposed,
   selectorMissing,
@@ -75,6 +88,12 @@ export {
   wedged,
   yieldCollapsed,
 } from './error-throws';
+export {
+  egressInPayload,
+  egressUnsupported,
+  promptAnswerInvalid,
+  promptTimedOut,
+} from './error-throws-session';
 export type { ScrapeErrorCode, ScrapeErrorInit, ScrapeOwnedErrorCode } from './errors';
 export {
   isRetryableScrapeError,
@@ -86,6 +105,14 @@ export {
   SCRAPE_OWNED_ERROR_CODES,
   ScrapeError,
 } from './errors';
+export type { AnswerPromptInput, EventPromptOptions } from './event-prompt';
+export {
+  answerPrompt,
+  DEFAULT_PROMPT_ANSWER_TTL_MS,
+  DEFAULT_PROMPT_POLL_MS,
+  eventPrompt,
+  promptEventName,
+} from './event-prompt';
 export type { ScrapeEventFields, StepEvent } from './events';
 export type { YieldCheck, YieldExpectation, YieldGuardInput, YieldHistory } from './expect';
 export {
@@ -164,6 +191,7 @@ export type {
   ScrapeDefinition,
   ScrapeReport,
   ScrapeRunArgs,
+  ScrapeSettled,
 } from './scrape';
 export { scrape } from './scrape';
 export { DEFAULT_PAGE_TIMEOUT_MS, runScrape } from './scrape-run';
@@ -177,10 +205,17 @@ export {
   safeNetwork,
   safePageErrors,
 } from './secrets';
-export type { ScrapeSessionStore, SessionSnapshot, SessionState } from './session-state';
+export type {
+  ScrapeSessionStore,
+  SessionSnapshot,
+  SessionState,
+  StorageSessionStoreOptions,
+} from './session-state';
 export {
   memorySessionStore,
   parseSessionState,
+  recordVersion,
+  SESSION_SEAL_PURPOSE,
   sessionDigest,
   sessionKeyFor,
   storageSessionStore,
@@ -196,5 +231,8 @@ export type {
   ScrapeDownloadFile,
   ScrapeTarget,
 } from './target';
+export { endpointLabel, urlSecretValues } from './url-secrets';
+export type { RunUsageMeter, ScrapeUsage, UsageMeter } from './usage';
+export { createUsageMeter } from './usage';
 export type { WedgeGuard, WedgeGuardInit } from './watchdog';
 export { DEFAULT_GRACE_MS } from './watchdog';

package/src/launch-args.ts

@@ -0,0 +1,51 @@
+// The argument list a launched browser gets: the caller's own, then the exit. The exit is the
+// session's — the driver's `proxy` or the run's `egress` — so it is appended LAST and a caller
+// switch that would decide the route instead is refused rather than ranked.
+
+import { launchArgsInvalid } from './error-throws-session';
+
+/**
+ * Every switch Chrome reads a proxy decision from. Matched on the switch NAME, case-folded and
+ * with either prefix POSIX Chrome accepts (`--` and `-`), so a value that merely mentions a proxy
+ * (`--user-agent=proxy-server-test`) is not refused.
+ */
+const ROUTE_SWITCHES = new Set([
+  'proxy-server',
+  'proxy-bypass-list',
+  'proxy-pac-url',
+  'proxy-auto-detect',
+  'no-proxy-server',
+]);
+
+const switchName = (arg: string): string | undefined => {
+  const match = /^--?([^=]+)/.exec(arg);
+  return match?.[1]?.toLowerCase();
+};
+
+/**
+ * `undefined` when the launch carries no args at all — the launcher's own defaults stay untouched
+ * then. Refused with `X_SCRAPE_LAUNCH_ARGS_INVALID` before anything starts: a browser launched on a
+ * second route is a session that reports one exit and leaves the worker by another.
+ */
+export function launchArgs(
+  callerArgs: unknown,
+  proxyArg: string | undefined,
+): string[] | undefined {
+  if (callerArgs !== undefined) {
+    if (!Array.isArray(callerArgs) || !callerArgs.every((arg) => typeof arg === 'string')) {
+      throw launchArgsInvalid('is not an array of strings', false);
+    }
+    for (const arg of callerArgs as readonly string[]) {
+      const name = switchName(arg);
+      if (name !== undefined && ROUTE_SWITCHES.has(name)) {
+        throw launchArgsInvalid(
+          `sets --${name}, which decides the route this session leaves by`,
+          true,
+        );
+      }
+    }
+  }
+  const args = [...((callerArgs as readonly string[] | undefined) ?? [])];
+  if (proxyArg !== undefined) args.push(`--proxy-server=${proxyArg}`);
+  return args.length === 0 ? undefined : args;
+}

package/src/offline-session.ts

@@ -42,6 +42,10 @@ export async function openOfflineSession(init: OfflineSessionInit): Promise<Scra
   if (init.session.restore !== undefined) await target.restore(init.session.restore);
   return {
     driver: init.driver,
+    // An offline session dials nothing — except the run's own `/robots.txt` read, which is a real
+    // request. Reporting the run's exit is what makes that one request leave through it, exactly
+    // as it would on the driver this recording stands in for.
+    ...(init.session.proxy === undefined ? {} : { proxy: init.session.proxy }),
     page: pageOverTarget(target, {
       clock: init.session.clock,
       allowHosts: init.session.rules.allowHosts,
@@ -51,6 +55,7 @@ export async function openOfflineSession(init: OfflineSessionInit): Promise<Scra
       signal: init.session.signal,
       onActivity: init.session.onActivity,
       pace: init.session.pace,
+      usage: init.session.usage,
     }),
     http: recordedHttp({
       lookup: init.http,
@@ -63,6 +68,7 @@ export async function openOfflineSession(init: OfflineSessionInit): Promise<Scra
       // The same bag, for the same reason: a redaction only the live leg performs is one no
       // fixture can prove.
       secrets: init.session.secrets,
+      usage: init.session.usage,
       maxAgeMs: init.maxAgeMs,
     }),
     close: () => target.close(),

package/src/page-over-target.ts

@@ -35,6 +35,7 @@ import type {
   ScrapeTarget,
 } from './target';
 import { ROOT_SELECTOR } from './target';
+import type { UsageMeter } from './usage';
 
 export interface PageContext {
   readonly clock: ScrapeClock;
@@ -51,6 +52,8 @@ export interface PageContext {
   readonly secrets?: ScrapeSecrets | undefined;
   readonly robots?: RobotsGate | undefined;
   readonly signal?: AbortSignal | undefined;
+  /** The run's meter. Counts a navigation where the wedge watchdog is told about one. */
+  readonly usage?: UsageMeter | undefined;
 }
 
 /** Mutable, shared by the page and every frame under it: a taint is a property of the SESSION. */
@@ -251,6 +254,7 @@ export function pageOverTarget(target: ScrapeTarget, ctx: PageContext): ScrapePa
       await guardNavigation(url, ctx);
       await ctx.pace?.(ctx.signal);
       ctx.onActivity?.();
+      ctx.usage?.navigation();
       await target.goto(url, {
         timeoutMs: options?.timeout ?? ctx.defaultTimeoutMs,
         signal: ctx.signal,