@ultimat3/scraping 23.0.0 → 25.0.0

package/src/cdp-target.ts

@@ -1,13 +1,13 @@
 // `ScrapeTarget` over a real browser, through the structural CDP port. Everything driver-specific
 // in this package lives here and in `driver-cdp.ts`; the vocabulary above it does not change.
 
-import { isUltimateError } from '@ultimat3/core';
+import { isUltimateError, NotImplementedError } from '@ultimat3/core';
 import type { StandardSchemaV1 } from '@ultimat3/schema';
 import { parse, t } from '@ultimat3/schema';
 import { browserRecord } from './browser-record';
 import { axNodesFor } from './cdp-a11y';
 import type { CdpArmInit } from './cdp-arm';
-import { arm } from './cdp-arm';
+import { arm, armBrowser } from './cdp-arm';
 import type { CdpBrowserLike, CdpFrameLike } from './cdp-port';
 import {
   clearExpression,
@@ -16,10 +16,10 @@ import {
   snapshotExpression,
 } from './cdp-snapshot';
 import { type ColorScheme, colorSchemeFeatures } from './color-scheme';
-import { browserUnreachable, pageCrashed, scrapeNotImplemented } from './error-throws';
+import { browserUnreachable, pageCrashed } from './error-throws';
 import { parseKeyChord } from './key-chord';
 import type { ConsoleLine, NetworkEntry, PageError } from './rings';
-import { createRing } from './rings';
+import { boundedRing } from './rings';
 import type { SessionSnapshot } from './session-state';
 import type {
   AxNode,
@@ -54,7 +54,7 @@ const cookieSchema = t.array(
  *
  * | Code | Why a retry cannot change it |
  * |---|---|
- * | `X_NOT_IMPLEMENTED` | a fact about the launcher's own shape. A browser cannot produce it; only this file's `scrapeNotImplemented()` can, and the method is still missing on attempt five |
+ * | `X_NOT_IMPLEMENTED` | a fact about the launcher's own shape. A browser cannot produce it; only this file's own `NotImplementedError` refusals can, and the method is still missing on attempt five |
  * | `X_VALIDATION_FAILED` | the browser ANSWERED, and the answer did not match the shape this driver reads it with. The page is what it is; attempt five reads the same DOM |
  *
  * Both were re-labelled `X_SCRAPE_BROWSER_UNREACHABLE`, which `errors.ts` registers `retryable`,
@@ -94,11 +94,12 @@ export interface CdpTargetInit extends CdpArmInit {
 }
 
 export async function cdpTarget(init: CdpTargetInit): Promise<ScrapeTarget> {
-  const console_ = createRing<ConsoleLine>();
-  const network = createRing<NetworkEntry>();
-  const pageErrors = createRing<PageError>();
+  const console_ = boundedRing<ConsoleLine>();
+  const network = boundedRing<NetworkEntry>();
+  const pageErrors = boundedRing<PageError>();
   const crashed: { value: string | undefined } = { value: undefined };
   await arm(init, { network, console: console_, pageErrors, crashed });
+  await armBrowser(init, network);
   let pendingStorage: SessionSnapshot | undefined;
 
   const originOf = (url: string): string => {
@@ -124,8 +125,10 @@ export async function cdpTarget(init: CdpTargetInit): Promise<ScrapeTarget> {
     if (pending === undefined) return;
     if (originOf(init.page.url()) !== pending.origin || pending.origin === '') return;
     pendingStorage = undefined;
+    // PAIRS, never an object literal: `{"__proto__": "…"}` in the page sets the literal's
+    // prototype and files no key, so a token stored under that legal name was never restored.
     await init.page.evaluate(
-      `(() => { const entries = ${JSON.stringify(pending.storage)}; for (const key of Object.keys(entries)) localStorage.setItem(key, entries[key]); })()`,
+      `(() => { for (const [key, value] of ${JSON.stringify(Object.entries(pending.storage))}) localStorage.setItem(key, value); })()`,
     );
   };
 
@@ -148,9 +151,9 @@ export async function cdpTarget(init: CdpTargetInit): Promise<ScrapeTarget> {
     ...parent,
     url: () => frame.url(),
     content: () => guard('content', () => frame.content()),
-    query: (selector) =>
+    query: (selector, options) =>
       guard('query', async () =>
-        parseSnapshots(await frame.evaluate(snapshotExpression(selector))),
+        parseSnapshots(await frame.evaluate(snapshotExpression(selector, options))),
       ),
     click: (selector) => guard('click', () => frame.click(selector)),
     type: (selector, text) => guard('type', () => frame.type(selector, text)),
@@ -183,10 +186,11 @@ export async function cdpTarget(init: CdpTargetInit): Promise<ScrapeTarget> {
     // rather than answered from the PARENT document, which is what the spread alone would do.
     accessibility: (_selector, _max): Promise<readonly AxNode[]> =>
       Promise.reject(
-        scrapeNotImplemented(
-          'accessibility() on a frame of the puppeteer driver',
-          'read the accessibility tree through the page — page.accessibility(selector) — which covers the top-level document only',
-        ),
+        new NotImplementedError({
+          cause:
+            'accessibility() on a frame of the puppeteer driver is not implemented by this driver',
+          fix: 'read the accessibility tree through the page — page.accessibility(selector) — which covers the top-level document only',
+        }),
       ),
   });
 
@@ -204,9 +208,9 @@ export async function cdpTarget(init: CdpTargetInit): Promise<ScrapeTarget> {
         await applyPendingStorage();
       }),
     content: () => guard('content', () => init.page.content()),
-    query: (selector) =>
+    query: (selector, options) =>
       guard('query', async () =>
-        parseSnapshots(await init.page.evaluate(snapshotExpression(selector))),
+        parseSnapshots(await init.page.evaluate(snapshotExpression(selector, options))),
       ),
     click: (selector) => guard('click', () => init.page.click(selector)),
     type: (selector, text) => guard('type', () => init.page.type(selector, text)),
@@ -228,10 +232,10 @@ export async function cdpTarget(init: CdpTargetInit): Promise<ScrapeTarget> {
       await guard('press', async () => {
         const keyboard = init.page.keyboard;
         if (keyboard === undefined) {
-          throw scrapeNotImplemented(
-            'press() on a CDP page with no keyboard',
-            'upgrade the launcher to a puppeteer-core that exposes page.keyboard, or dispatch the key from the app under test instead of the browser',
-          );
+          throw new NotImplementedError({
+            cause: 'press() on a CDP page with no keyboard is not implemented by this driver',
+            fix: 'upgrade the launcher to a puppeteer-core that exposes page.keyboard, or dispatch the key from the app under test instead of the browser',
+          });
         }
         // Down in the order written, the key, then up in REVERSE — the order a hand releases
         // them, and the order the browser's own `press` with modifiers performs. `.call`-free:
@@ -248,10 +252,10 @@ export async function cdpTarget(init: CdpTargetInit): Promise<ScrapeTarget> {
       guard('focus', async () => {
         const focus = init.page.focus;
         if (typeof focus !== 'function') {
-          throw scrapeNotImplemented(
-            'focus() on a CDP page with no focus() method',
-            'upgrade the launcher to a puppeteer-core that exposes page.focus(), or click the element instead',
-          );
+          throw new NotImplementedError({
+            cause: 'focus() on a CDP page with no focus() method is not implemented by this driver',
+            fix: 'upgrade the launcher to a puppeteer-core that exposes page.focus(), or click the element instead',
+          });
         }
         // `.call`, for `setColorScheme`'s reason: the member is read off the object.
         await focus.call(init.page, selector);
@@ -260,10 +264,11 @@ export async function cdpTarget(init: CdpTargetInit): Promise<ScrapeTarget> {
       guard('accessibility', async () => {
         const createSession = init.page.createCDPSession;
         if (typeof createSession !== 'function') {
-          throw scrapeNotImplemented(
-            'accessibility() on a CDP page with no createCDPSession() method',
-            'upgrade the launcher to a puppeteer-core that exposes page.createCDPSession(), or assert on the markup with page.query() — which reads attributes, not what the browser computed',
-          );
+          throw new NotImplementedError({
+            cause:
+              'accessibility() on a CDP page with no createCDPSession() method is not implemented by this driver',
+            fix: 'upgrade the launcher to a puppeteer-core that exposes page.createCDPSession(), or assert on the markup with page.query() — which reads attributes, not what the browser computed',
+          });
         }
         const session = await createSession.call(init.page);
         try {
@@ -276,10 +281,11 @@ export async function cdpTarget(init: CdpTargetInit): Promise<ScrapeTarget> {
       guard('setOfflineMode', async () => {
         const source = init.page as { setOfflineMode?: (value: boolean) => Promise<void> };
         if (typeof source.setOfflineMode !== 'function') {
-          throw scrapeNotImplemented(
-            'setOfflineMode() on a CDP page with no setOfflineMode() method',
-            'upgrade the launcher to a puppeteer-core that exposes page.setOfflineMode(), or drive the condition from the app under test instead of the browser',
-          );
+          throw new NotImplementedError({
+            cause:
+              'setOfflineMode() on a CDP page with no setOfflineMode() method is not implemented by this driver',
+            fix: 'upgrade the launcher to a puppeteer-core that exposes page.setOfflineMode(), or drive the condition from the app under test instead of the browser',
+          });
         }
         await source.setOfflineMode(enabled);
       }),
@@ -291,10 +297,11 @@ export async function cdpTarget(init: CdpTargetInit): Promise<ScrapeTarget> {
         // older spelling.
         const emulate = init.page.emulateMediaFeatures;
         if (typeof emulate !== 'function') {
-          throw scrapeNotImplemented(
-            'setColorScheme() on a CDP page with no emulateMediaFeatures() method',
-            'upgrade the launcher to a puppeteer-core that exposes page.emulateMediaFeatures(), or have the page under test set its own theme',
-          );
+          throw new NotImplementedError({
+            cause:
+              'setColorScheme() on a CDP page with no emulateMediaFeatures() method is not implemented by this driver',
+            fix: 'upgrade the launcher to a puppeteer-core that exposes page.emulateMediaFeatures(), or have the page under test set its own theme',
+          });
         }
         // `.call`, because the member is read off the object: an unbound method loses `this` and
         // puppeteer's own `Page` needs it.
@@ -305,10 +312,11 @@ export async function cdpTarget(init: CdpTargetInit): Promise<ScrapeTarget> {
         // Read off the object and called through it, for `setColorScheme`'s reason.
         const evaluateOnNewDocument = init.page.evaluateOnNewDocument;
         if (typeof evaluateOnNewDocument !== 'function') {
-          throw scrapeNotImplemented(
-            'prepare() on a CDP page with no evaluateOnNewDocument() method',
-            'upgrade the launcher to a puppeteer-core that exposes page.evaluateOnNewDocument(), or seed the state from the app under test instead of the browser',
-          );
+          throw new NotImplementedError({
+            cause:
+              'prepare() on a CDP page with no evaluateOnNewDocument() method is not implemented by this driver',
+            fix: 'upgrade the launcher to a puppeteer-core that exposes page.evaluateOnNewDocument(), or seed the state from the app under test instead of the browser',
+          });
         }
         await evaluateOnNewDocument.call(init.page, expression);
       }),
@@ -333,14 +341,15 @@ export async function cdpTarget(init: CdpTargetInit): Promise<ScrapeTarget> {
       guard('cookies', async () => {
         const source = init.browser as { cookies?: () => Promise<unknown> };
         if (typeof source.cookies !== 'function') {
-          throw scrapeNotImplemented(
-            'cookies() on a CDP browser with no cookies() method',
-            'upgrade the launcher to a puppeteer-core that exposes browser.cookies(), or read them with page.evaluate("document.cookie")',
-          );
+          throw new NotImplementedError({
+            cause:
+              'cookies() on a CDP browser with no cookies() method is not implemented by this driver',
+            fix: 'upgrade the launcher to a puppeteer-core that exposes browser.cookies(), or read them with page.evaluate("document.cookie")',
+          });
         }
         return parse(cookieSchema, await source.cookies());
       }),
-    // Honest stub, in the shape `packages/jobs/src/driver-redis.ts` uses. A real one needs
+    // Honest stub: correct types and one labelled `X_NOT_IMPLEMENTED`. A real one needs
     // `Browser.setDownloadBehavior` over a raw CDP session plus a directory watch, and a
     // half-written version that silently returned empty bytes is worse than this line.
     //
@@ -349,10 +358,10 @@ export async function cdpTarget(init: CdpTargetInit): Promise<ScrapeTarget> {
     // `try` — a synchronous `throw` jumps over the first of those entirely.
     download: (_options): Promise<ScrapeDownloadFile> =>
       Promise.reject(
-        scrapeNotImplemented(
-          'download() on the puppeteer driver',
-          'fetch the file inside the page — page.evaluate("fetch(url).then(r => r.text())") — or run this scrape on fixtureBrowser(), whose download() is complete',
-        ),
+        new NotImplementedError({
+          cause: 'download() on the puppeteer driver is not implemented by this driver',
+          fix: 'fetch the file inside the page — page.evaluate("fetch(url).then(r => r.text())") — or run this scrape on fixtureBrowser(), whose download() is complete',
+        }),
       ),
     frames: () =>
       guard('frames', () =>
@@ -378,10 +387,19 @@ export async function cdpTarget(init: CdpTargetInit): Promise<ScrapeTarget> {
         } catch {
           origin = '';
         }
-        const source = init.browser as { cookies?: () => Promise<unknown> };
+        // Refused, never `[]`: the HTTP leg reads its cookies from here on every request and
+        // `persistSession` stores what this answers, so an empty jar went out logged-out and was
+        // saved as the session — both silently, while every other missing port method refuses.
+        if (typeof init.browser.cookies !== 'function') {
+          throw new NotImplementedError({
+            cause:
+              'session() on a CDP browser with no cookies() method is not implemented by this driver',
+            fix: 'upgrade the launcher to a puppeteer-core that exposes browser.cookies() — the HTTP leg and a persisted session both read the jar through it',
+          });
+        }
+        const jar = parse(cookieSchema, await init.browser.cookies());
         return {
-          cookies:
-            typeof source.cookies === 'function' ? parse(cookieSchema, await source.cookies()) : [],
+          cookies: jar,
           headers: {},
           // `browserRecord` and not `t.record()`: a page may legitimately hold a key called
           // `constructor`, and the schema refuses that name outright — see `browser-record.ts`.
@@ -394,11 +412,17 @@ export async function cdpTarget(init: CdpTargetInit): Promise<ScrapeTarget> {
       guard('restore', async () => {
         // Two halves, because they belong to two different moments: cookies are the browser's and
         // can be put back now, storage is an ORIGIN's and cannot exist until one is loaded.
-        const source = init.browser as {
-          setCookie?: (...cookies: readonly unknown[]) => Promise<void>;
-        };
-        if (typeof source.setCookie === 'function' && session.cookies.length > 0) {
-          await source.setCookie(...session.cookies);
+        if (session.cookies.length > 0) {
+          // Refused rather than skipped: a restore that dropped the cookies opened the session
+          // logged-out while the run believed it restored one.
+          if (typeof init.browser.setCookie !== 'function') {
+            throw new NotImplementedError({
+              cause:
+                'restore() of cookies on a CDP browser with no setCookie() method is not implemented by this driver',
+              fix: 'upgrade the launcher to a puppeteer-core that exposes browser.setCookie(), or set auth: { reuse: false } on the scrape() definition so no session is restored',
+            });
+          }
+          await init.browser.setCookie(...session.cookies);
         }
         pendingStorage = Object.keys(session.storage).length > 0 ? session : undefined;
         await applyPendingStorage();

package/src/clock.ts

@@ -28,7 +28,7 @@ export const systemScrapeClock: ScrapeClock = Object.freeze({
       await Bun.sleep(ms);
       return;
     }
-    throwIfAborted(signal);
+    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.
@@ -52,7 +52,7 @@ export const systemScrapeClock: ScrapeClock = Object.freeze({
  * 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 `testClock()`'s "sleeping is advancing" would run a five-minute budget out
+ * 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({
@@ -82,11 +82,6 @@ export function resetScrapeClock(): void {
   ambient = undefined;
 }
 
-/** The abort reason, unwrapped — a caller's `AbortSignal.reason` is whatever they put there. */
-export function throwIfAborted(signal: AbortSignal): void {
-  if (signal.aborted) throw signal.reason;
-}
-
 /**
  * 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
@@ -97,7 +92,7 @@ export interface TestScrapeClock extends ScrapeClock {
   advance(ms: number): void;
 }
 
-export function testClock(at: Date | number = 0): TestScrapeClock {
+export function testScrapeClock(at: Date | number = 0): TestScrapeClock {
   let epochMs = at instanceof Date ? at.getTime() : at;
   let mono = 0;
   const advance = (ms: number): void => {
@@ -113,7 +108,7 @@ export function testClock(at: Date | number = 0): TestScrapeClock {
       // 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();
-      if (signal !== undefined) throwIfAborted(signal);
+      signal?.throwIfAborted();
     },
   };
 }

package/src/driver-cdp.ts

@@ -23,6 +23,7 @@ import { isScrapeError } from './errors';
 import type { ScrapeEventFields } from './events';
 import { errorCode } from './failures';
 import { httpOverFetch } from './http';
+import { launchArgs } from './launch-args';
 import { pageOverTarget } from './page-over-target';
 import type { ScrapeTarget } from './target';
 import { endpointLabel, hasCredentials, splitCredentials, urlSecretValues } from './url-secrets';
@@ -38,7 +39,10 @@ export interface BrowserOptions {
    * `egress(input)` — `SessionInit.proxy` — wins over it, per session.
    */
   readonly proxy?: string | undefined;
-  /** Extra launch/connect arguments, passed through untouched. */
+  /**
+   * Extra launch/connect options, passed through — except `args`, which `localBrowser()` puts
+   * BEFORE the exit's `--proxy-server` and screens for a second route (`launch-args.ts`).
+   */
   readonly options?: Record<string, unknown> | undefined;
   /** How long a graceful `close()` may take before the process is killed. */
   readonly graceMs?: number | undefined;
@@ -267,6 +271,11 @@ export function localBrowser(options: LocalBrowserOptions): ScrapeDriver {
       // The userinfo never reaches the argument list: Chrome ignores it there, and an argument is
       // readable by every process on the box. `opened()` answers the challenge instead.
       const proxyArg = proxy !== undefined && authenticate ? splitCredentials(proxy).bare : proxy;
+      // The caller's args FIRST and the exit appended after them, never a spread that lets one
+      // replace the other: `{ args: ['--no-sandbox'] }` — every container deploy's — used to
+      // overwrite the proxy flag, and the browser dialled direct while the session reported the exit.
+      const { args: callerArgs, ...passthrough } = options.options ?? {};
+      const args = launchArgs(callerArgs, proxyArg);
       let browser: CdpBrowserLike;
       try {
         browser = await launch.call(options.launcher, {
@@ -275,8 +284,8 @@ export function localBrowser(options: LocalBrowserOptions): ScrapeDriver {
             ? {}
             : { executablePath: options.executablePath }),
           ...(options.profileDir === undefined ? {} : { userDataDir: options.profileDir }),
-          ...(proxyArg === undefined ? {} : { args: [`--proxy-server=${proxyArg}`] }),
-          ...options.options,
+          ...passthrough,
+          ...(args === undefined ? {} : { args }),
         });
       } catch (thrown) {
         throw browserUnreachable(CDP_DRIVER, thrown);

package/src/driver.ts

@@ -102,7 +102,7 @@ export interface ScrapeDriver {
 
 let ambient: ScrapeDriver | undefined;
 
-/** Set once at boot from `app.config.ts`. A scrape's own `driver:` overrides it per definition. */
+/** 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;
 }

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(createPgEventBus({ 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 — setEventBus(postgresEventBus({ executor })) — or raise eventPrompt({ timeout })',
     meta: {
       scrape: input.scrape,
       label: input.label,
@@ -72,3 +72,40 @@ export const promptAnswerInvalid = (input: {
     fix: 'publish the answer with answerPrompt({ runId, index, answer }) and never publishEvent() by hand — the answer is sealed for this one prompt, so a plain payload is refused rather than typed into the site',
     meta: { scrape: input.scrape, label: input.label, event: input.event },
   });
+
+/** Lists every `localBrowser(` call site and every proxy switch in the app — where the edit goes. */
+export const LAUNCH_ARGS_FIX =
+  "grep -rnE --include='*.ts' -e 'localBrowser\\(' -e '--(no-)?proxy-' .";
+
+/**
+ * The caller's launch args set the exit themselves, or are not a list a launcher can take. The
+ * switch NAME only, never its value: `--proxy-server=http://user:pass@…` is a credential a caller
+ * may well have written, and this cause is written to the dead-letter row.
+ */
+
+export const launchArgsInvalid = (reason: string, route: boolean): ScrapeError =>
+  new ScrapeError({
+    code: 'X_SCRAPE_LAUNCH_ARGS_INVALID',
+    cause: `localBrowser({ options: { args } }) ${reason} — ${
+      route
+        ? 'delete the switch from args and pass the exit as localBrowser({ proxy }) or scrape({ egress })'
+        : "pass args as a list of strings, e.g. options: { args: ['--no-sandbox'] }"
+    }`,
+    // One command, the same for both shapes: it lists every call site and every proxy switch.
+    fix: LAUNCH_ARGS_FIX,
+    meta: { reason },
+  });
+
+/**
+ * A name a WILDCARD admitted, resolved to an address inside the network. The address CLASS and
+ * never the address: the cause reaches the dead-letter row, and the hostname is enough to act on.
+ */
+export const hostResolvesInward = (url: string, hostname: string, kind: string): ScrapeError =>
+  new ScrapeError({
+    code: 'X_SCRAPE_HOST_BLOCKED',
+    cause: `${url} is admitted by a wildcard in allowHosts, and ${hostname} resolves to ${
+      kind === 'unresolvable' ? 'no address' : `a ${kind} address`
+    } — a wildcard admits public addresses only`,
+    fix: `name the host exactly on the scrape() definition — allowHosts: [${JSON.stringify(hostname)}] — if it is meant to be reached inside your network`,
+    meta: { url, host: hostname, addressClass: kind },
+  });

package/src/error-throws.ts

@@ -8,7 +8,6 @@ import {
   isRetryableStatus,
   renderFixShellArg,
   renderThrowable,
-  UltimateError,
 } from '@ultimat3/core';
 import type { CaptureClip } from './capture-clip';
 import { ScrapeError } from './errors';
@@ -303,7 +302,11 @@ export const fixtureMissing = (url: string, dir: string): ScrapeError =>
 export const fixtureStale = (url: string, ageMs: number, maxAgeMs: number): ScrapeError =>
   new ScrapeError({
     code: 'X_SCRAPE_FIXTURE_STALE',
-    cause: `the recording of ${url} is ${String(Math.round(ageMs / 86_400_000))} days old and fixtureBrowser declares maxAge ${String(Math.round(maxAgeMs / 86_400_000))} days`,
+    cause: `the recording of ${url} ${
+      Number.isFinite(ageMs)
+        ? `is ${String(Math.round(ageMs / 86_400_000))} days old`
+        : 'has a recordedAt that is not a date'
+    } and fixtureBrowser declares maxAge ${String(Math.round(maxAgeMs / 86_400_000))} days`,
     fix: 're-record the fixture directory, or raise maxAge on fixtureBrowser({ maxAge }) with the reason an old recording still proves something',
     meta: { url, ageMs, maxAgeMs },
   });
@@ -398,7 +401,7 @@ export const authFailed = (scrape: string, detail: string): ScrapeError =>
     meta: { scrape },
   });
 
-export const sessionExpired = (scrape: string, key: string): ScrapeError =>
+export const scrapeSessionExpired = (scrape: string, key: string): ScrapeError =>
   new ScrapeError({
     code: 'X_SCRAPE_SESSION_EXPIRED',
     cause: `the stored session ${key} for scrape "${scrape}" failed its validate() probe and the definition declares no auth.login`,
@@ -426,19 +429,6 @@ export const blocked = (scrape: string, url: string, detail: string): ScrapeErro
     meta: { scrape, url },
   });
 
-/**
- * The honest stub, in the shape `packages/jobs/src/driver-redis.ts` uses: correct types so an app
- * can be written against the seam, and one labelled throw so nobody discovers the gap from a
- * silently-skipped recovery.
- */
-export const scrapeNotImplemented = (feature: string, fix: string): UltimateError =>
-  new UltimateError({
-    code: 'X_NOT_IMPLEMENTED',
-    cause: `${feature} is declared and not implemented in @ultimat3/scraping`,
-    fix,
-    meta: { feature },
-  });
-
 /**
  * The crop rectangle's three refusals, one code. Each is a caller's DECLARATION being impossible
  * rather than a site behaving badly, so each names the edit that fixes it — and the alternative in

package/src/errors.ts

@@ -41,11 +41,12 @@ export const SCRAPE_OWNED_ERROR_CODES = [
   'X_SCRAPE_KEY_INVALID',
   'X_SCRAPE_EGRESS_UNSUPPORTED',
   'X_SCRAPE_EGRESS_IN_PAYLOAD',
+  'X_SCRAPE_LAUNCH_ARGS_INVALID',
 ] as const;
 
 /**
- * `X_NOT_IMPLEMENTED` is `@ultimat3/core`'s and `recover.ts` throws it for the agent seam, the
- * way `packages/jobs/src/driver-redis.ts` does for its stub. `X_ENV_MISSING` is core's too: a
+ * `X_NOT_IMPLEMENTED` is `@ultimat3/core`'s: `recover.ts`, `cdp-target.ts` and `html-target.ts`
+ * throw it as core's own `NotImplementedError`, never a constructor of this package's. `X_ENV_MISSING` is core's too: a
  * declared secret with no value in the environment is a missing environment variable, not a
  * scraping concept needing its own code. No title is kept here for either — one code, one owner,
  * or the two copies drift.
@@ -95,6 +96,8 @@ export const SCRAPE_ERROR_TITLES: Readonly<Record<ScrapeOwnedErrorCode, string>>
   X_SCRAPE_KEY_INVALID: 'the key chord names no key a browser can press',
   X_SCRAPE_EGRESS_UNSUPPORTED: 'this driver cannot give the session the exit the run asked for',
   X_SCRAPE_EGRESS_IN_PAYLOAD: 'the run exit carries a credential that is also in the job payload',
+  X_SCRAPE_LAUNCH_ARGS_INVALID:
+    'the launch options carry arguments this driver cannot hand the browser',
 };
 
 // One unconditional call, so a second package claiming one of these codes throws
@@ -202,6 +205,9 @@ export const SCRAPE_ERROR_RETRY = {
   X_SCRAPE_EGRESS_UNSUPPORTED: 'terminal',
   // The payload is the row: every remaining attempt reads the same credential out of it.
   X_SCRAPE_EGRESS_IN_PAYLOAD: 'terminal',
+  // The args are the deploy's own literal: attempt 2 launches with the same list and is refused
+  // the same way. Launching anyway is the retry that "works" from the worker's own address.
+  X_SCRAPE_LAUNCH_ARGS_INVALID: 'terminal',
 } as const satisfies Readonly<Record<ScrapeOwnedErrorCode, 'retryable' | 'terminal'>>;
 
 registerErrorRetry(SCRAPE_ERROR_RETRY);

package/src/event-prompt.ts

@@ -15,7 +15,7 @@ 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 { deadline } 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. */
@@ -73,7 +73,7 @@ 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(createPgEventBus({ executor })) at boot — x dev and the served roles do — or pass bus: createPgEventBus({ executor }) to eventPrompt()',
+        fix: 'call setEventBus(postgresEventBus({ executor })) at boot — x dev and the served roles do — or pass bus: postgresEventBus({ executor }) to eventPrompt()',
       });
     }
     const event = promptEventName(request.runId, request.index);
@@ -83,7 +83,7 @@ export function eventPrompt(options: EventPromptOptions): PromptHandler {
     const askedAt = await bus.now();
     const budget = deadline(request.clock, timeoutMs, 'eventPrompt');
     for (;;) {
-      if (request.signal !== undefined) throwIfAborted(request.signal);
+      request.signal?.throwIfAborted();
       const found = await bus.find(event, undefined, askedAt);
       if (found !== undefined) {
         if (!isSealed(found.payload)) {

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 });
   }