@ultimat3/scraping 23.0.0 → 25.0.0

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';
@@ -23,7 +18,7 @@ import { parseKeyChord } from './key-chord';
 import type { PageRecording } from './recording';
 import { splitDownload } from './recording';
 import type { ConsoleLine, NetworkEntry, PageError } from './rings';
-import { createRing } from './rings';
+import { boundedRing } from './rings';
 import type { SessionSnapshot } from './session-state';
 import { EMPTY_SESSION } from './session-state';
 import type {
@@ -124,14 +119,14 @@ interface OfflineDocument {
 }
 
 export function htmlTarget(init: HtmlTargetInit): ScrapeTarget {
-  const consoleRing = createRing<ConsoleLine>();
-  const networkRing = createRing<NetworkEntry>();
+  const consoleRing = boundedRing<ConsoleLine>();
+  const networkRing = boundedRing<NetworkEntry>();
   // Built and never pushed to, deliberately: this target parses markup and executes none of it, so
   // there is no uncaught exception for it to have. It ANSWERS rather than omitting the ring —
   // `page.pageErrors()` returning `[]` here is the honest "nothing threw, and nothing could",
   // where a missing ring would be a page method that throws on two of the three drivers.
   // `driver-parity.test.ts` pins the divergence, beside the box/hit-target one it already carries.
-  const pageErrorRing = createRing<PageError>();
+  const pageErrorRing = boundedRing<PageError>();
   const overlay = new Map<string, string>();
   /**
    * One overlay per FRAME, held here rather than in the frame target, because `frames()` builds a
@@ -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

@@ -64,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,

package/src/http.ts

@@ -20,6 +20,8 @@ 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';
@@ -43,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 {
@@ -114,6 +121,8 @@ export interface HttpTransportInit {
   /** 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;
 }
 
 /**
@@ -196,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 {
@@ -251,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> {
@@ -284,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
@@ -319,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
@@ -360,7 +397,7 @@ export function httpOverFetch(init: HttpTransportInit): ScrapeHttp {
           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

@@ -5,10 +5,7 @@
 export type { ActionabilityState, ActionabilityWait } from './actionability';
 export { awaitActionable } from './actionability';
 export type { ArtifactRef, ArtifactWriter, ArtifactWriterInit } from './artifacts';
-export {
-  createArtifactWriter,
-  DEFAULT_CONTENT_TYPE,
-} from './artifacts';
+export { artifactWriter } from './artifacts';
 export type {
   AuthContext,
   PromptHandler,
@@ -16,12 +13,14 @@ export type {
   PromptRequest,
   ScrapeAuth,
 } from './auth';
-export { burnSession, createPrompt, ensureAuthenticated, restorableSession } from './auth';
+export { burnSession, ensureAuthenticated, restorableSession, scrapePrompt } from './auth';
 export { browserRecord } from './browser-record';
 export type { CaptureClip, CaptureFraming } from './capture-clip';
 export { assertCaptureFraming } from './capture-clip';
 export type {
   CdpBrowserLike,
+  CdpBrowserSessionLike,
+  CdpBrowserTargetLike,
   CdpFrameLike,
   CdpKeyboardLike,
   CdpLauncherLike,
@@ -42,8 +41,7 @@ export {
   scrapeClock,
   setScrapeClock,
   systemScrapeClock,
-  testClock,
-  throwIfAborted,
+  testScrapeClock,
 } from './clock';
 export type { ColorScheme } from './color-scheme';
 export { COLOR_SCHEMES, isColorScheme } from './color-scheme';
@@ -79,11 +77,10 @@ export {
   redirectLoop,
   remoteRequired,
   robotsDisallowed,
-  scrapeNotImplemented,
+  scrapeSessionExpired,
   scrapeTimeout,
   secretExposed,
   selectorMissing,
-  sessionExpired,
   wedged,
   yieldCollapsed,
 } from './error-throws';
@@ -121,8 +118,6 @@ export {
   memoryYieldHistory,
 } from './expect';
 export { BURNS_SESSION, errorCode, NEVER_RETRIED } from './failures';
-export type { HostDecision, HostRule } from './hosts';
-export { ANY_HOST, hostDecision, hostMatches } from './hosts';
 export { queryHtml } from './html-query';
 export type { MarkupRequest } from './html-requests';
 export type { HtmlTargetInit, RecordingLookup } from './html-target';
@@ -151,7 +146,7 @@ export type {
 export type { PageContext } from './page-over-target';
 export { pageOverTarget } from './page-over-target';
 export type { Pacer } from './rate';
-export { createPacer } from './rate';
+export { scrapePacer } from './rate';
 export type { HttpRecording, PageRecording } from './recording';
 export {
   httpRecordingSchema,
@@ -172,13 +167,21 @@ export type {
   Ring,
 } from './rings';
 export {
-  createRing,
+  boundedRing,
   MAX_PAGE_ERROR_CHARS,
   pageErrorEntry,
   RESOURCE_TYPES,
 } from './rings';
-export type { RobotsFetch, RobotsGate, RobotsGateInit, RobotsPolicy, RobotsRules } from './robots';
-export { createRobotsGate, parseRobots, robotsAllows } from './robots';
+export type {
+  RobotsAnswer,
+  RobotsFetch,
+  RobotsGate,
+  RobotsGateInit,
+  RobotsPolicy,
+  RobotsRules,
+  RobotsUnreachable,
+} from './robots';
+export { parseRobots, robotsAllows, robotsGate } from './robots';
 export type { RobotsFetchInit } from './robots-fetch';
 export {
   DEFAULT_ROBOTS_MAX_BYTES,
@@ -196,13 +199,13 @@ export { scrape } from './scrape';
 export { DEFAULT_PAGE_TIMEOUT_MS, runScrape } from './scrape-run';
 export type { ScrapeSecrets, SecretResolver } from './secrets';
 export {
-  createSecretBag,
   MIN_REDACTABLE_LENGTH,
   redactSecrets,
   safeConsole,
   safeHtml,
   safeNetwork,
   safePageErrors,
+  secretBag,
 } from './secrets';
 export type {
   ScrapeSessionStore,
@@ -213,6 +216,7 @@ export type {
 export {
   memorySessionStore,
   parseSessionState,
+  recordVersion,
   SESSION_SEAL_PURPOSE,
   sessionDigest,
   sessionKeyFor,
@@ -225,12 +229,13 @@ export type {
   ElementSnapshot,
   FrameRef,
   GotoOptions,
+  QueryOptions,
   ScrapeCookie,
   ScrapeDownloadFile,
   ScrapeTarget,
 } from './target';
 export { endpointLabel, urlSecretValues } from './url-secrets';
 export type { RunUsageMeter, ScrapeUsage, UsageMeter } from './usage';
-export { createUsageMeter } from './usage';
+export { usageMeter } from './usage';
 export type { WedgeGuard, WedgeGuardInit } from './watchdog';
 export { DEFAULT_GRACE_MS } from './watchdog';

package/src/intercept.ts

@@ -5,8 +5,8 @@
 // differently — `driver-parity.test.ts` asserts the same refusal on all three, and a rule
 // re-implemented per driver is a rule that holds only on the driver nobody ships.
 
-import type { HostRule } from './hosts';
-import { hostDecision } from './hosts';
+import type { HostRule } from '@ultimat3/core';
+import { hostDecision } from '@ultimat3/core';
 import type { NetworkEntry, ResourceType } from './rings';
 
 export interface InterceptRules {

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/page-over-target.ts

@@ -4,7 +4,7 @@
 // driver a test uses and the driver production uses.
 
 import type { Secret } from '@ultimat3/core';
-import { finiteCount, isSecret, revealSecret } from '@ultimat3/core';
+import { finiteCount, hostDecision, isSecret, revealSecret } from '@ultimat3/core';
 import type { ActionabilityState } from './actionability';
 import { awaitActionable } from './actionability';
 import { assertCaptureFraming } from './capture-clip';
@@ -12,7 +12,6 @@ import type { ScrapeClock } from './clock';
 import { deadline } from './clock';
 import type { ColorScheme } from './color-scheme';
 import { hostBlocked, secretExposed, selectorMissing } from './error-throws';
-import { hostDecision } from './hosts';
 import type {
   AccessibilityOptions,
   CaptureRequest,
@@ -30,6 +29,7 @@ import type {
   AxNode,
   CaptureOptions,
   ElementSnapshot,
+  QueryOptions,
   ScrapeCookie,
   ScrapeDownloadFile,
   ScrapeTarget,
@@ -80,9 +80,13 @@ const toValue = (snapshot: ElementSnapshot): ElementValue => ({
   attrs: snapshot.attrs,
 });
 
-async function first(resolve: Resolve, selector: string): Promise<ElementSnapshot | undefined> {
+async function first(
+  resolve: Resolve,
+  selector: string,
+  options?: QueryOptions,
+): Promise<ElementSnapshot | undefined> {
   const target = await resolve();
-  return (await target.query(selector))[0];
+  return (await target.query(selector, options))[0];
 }
 
 function frameOver(
@@ -103,14 +107,18 @@ function frameOver(
   ): Promise<ElementSnapshot> => {
     const target = await resolve();
     lastUrl = target.url();
+    const state = options?.state ?? fallback;
+    // Only `actionable` reads `hitTarget`, so only it pays for moving the page — on every poll,
+    // because a layout shift between two can carry the element back out of view.
+    const query: QueryOptions = { reveal: state === 'actionable' };
     return awaitActionable({
       selector,
       url: lastUrl,
-      state: options?.state ?? fallback,
+      state,
       timeoutMs: timeoutFor(options),
       clock: ctx.clock,
       signal: ctx.signal,
-      snapshot: () => first(resolve, selector),
+      snapshot: () => first(resolve, selector, query),
     });
   };
 

package/src/pinned-host.ts

@@ -0,0 +1,65 @@
+// The DNS half of `allowHosts`, for the two legs this package dials itself — the HTTP leg and the
+// robots read. Core's `hostDecision` is synchronous and judges NAMES: a wildcard never admits an
+// address literal inside the network, but `allowHosts: ['*']` still admits a hostname that
+// resolves inward. So a name admitted by a wildcard alone is resolved here, every address
+// classified by core's one classifier, and the connection PINNED to the approved address — the
+// shape `@ultimat3/jobs`' `webhook-target.ts` takes for a webhook.
+
+import type { HostRule } from '@ultimat3/core';
+import { classifyAddress, hostMatches } from '@ultimat3/core';
+import { hostResolvesInward } from './error-throws-session';
+
+/** Every address a hostname answers. Injected in tests: the network is sealed in this repo. */
+export type HostResolve = (hostname: string) => Promise<readonly string[]>;
+
+/** `Bun.dns.lookup` — the runtime's own resolver, every family, every address. */
+export const resolveHost: HostResolve = async (hostname) =>
+  (await Bun.dns.lookup(hostname)).map((entry) => entry.address);
+
+/** What the transport connects to: the URL to dial, and the name it proves when pinned. */
+export interface DialTarget {
+  readonly url: string;
+  /** The original `host[:port]`, sent as the `Host` header of a pinned request. */
+  readonly host?: string | undefined;
+  /** For `https:` — the certificate is verified against the NAME, not the address. */
+  readonly serverName?: string | undefined;
+}
+
+const isWildcard = (rule: HostRule): boolean => {
+  const cleaned = rule.trim();
+  return cleaned === '*' || cleaned.startsWith('*.');
+};
+
+/**
+ * The connection for `url`, which `interceptVerdict` has ALREADY allowed. Unchanged when an exact
+ * rule names the host — the app said that host, internal or not, in a line a reviewer can see —
+ * or when the host is an address literal, which core's floor already judged. Otherwise resolved:
+ * one address that is not public refuses the request (`X_SCRAPE_HOST_BLOCKED`), and the dial is
+ * pinned to the first approved address, so a name that answers public here and private to the
+ * socket (DNS rebinding) is never reached. A resolver failure propagates: nothing unscreened is
+ * dialled, and the same name would not have resolved for `fetch` either.
+ */
+export async function dialTarget(
+  url: string,
+  allowHosts: readonly HostRule[],
+  resolve: HostResolve,
+): Promise<DialTarget> {
+  const parsed = new URL(url);
+  if (parsed.protocol !== 'http:' && parsed.protocol !== 'https:') return { url };
+  const hostname = parsed.hostname.replace(/^\[|\]$/g, '');
+  if (classifyAddress(hostname) !== undefined) return { url };
+  if (allowHosts.some((rule) => !isWildcard(rule) && hostMatches(hostname, rule))) return { url };
+  const addresses = await resolve(hostname);
+  const inward = addresses.map((address) => classifyAddress(address) ?? 'unclassifiable');
+  const refused =
+    addresses.length === 0 ? 'unresolvable' : inward.find((kind) => kind !== 'public');
+  if (refused !== undefined) throw hostResolvesInward(url, hostname, refused);
+  const pinned = addresses[0] ?? hostname;
+  const target = new URL(parsed.href);
+  target.hostname = pinned.includes(':') ? `[${pinned}]` : pinned;
+  return {
+    url: target.href,
+    host: parsed.host,
+    ...(parsed.protocol === 'https:' ? { serverName: hostname } : {}),
+  };
+}

package/src/rate.ts

@@ -9,7 +9,7 @@ export const DEFAULT_NAVIGATION_RATE = 1;
 
 export type Pacer = (signal?: AbortSignal) => Promise<void>;
 
-export function createPacer(rate: number, clock: ScrapeClock): Pacer {
+export function scrapePacer(rate: number, clock: ScrapeClock): Pacer {
   const intervalMs = 1_000 / rate;
   let nextAt = 0;
   return async (signal?: AbortSignal): Promise<void> => {

package/src/recover.ts

@@ -3,10 +3,11 @@
 // Two shapes. A FUNCTION is complete and shipped — an app writes its own fallback, gets the page
 // and the failure, and answers whether the attempt should be retried. `'agent'` is the seam for
 // letting a model re-derive the selector from the page, and it is an honest
-// `X_NOT_IMPLEMENTED` today, in the shape `packages/jobs/src/driver-redis.ts` uses: correct types
+// `X_NOT_IMPLEMENTED` today: correct types
 // so an app can be written against it, one labelled throw, no silent no-op.
 
-import { recoverRefused, scrapeNotImplemented } from './error-throws';
+import { NotImplementedError } from '@ultimat3/core';
+import { recoverRefused } from './error-throws';
 import type { ScrapePage } from './page';
 
 export interface RecoveryAttempt {
@@ -41,7 +42,7 @@ export async function runRecovery(recovery: Recovery, attempt: RecoveryAttempt):
     // The agent path lands with `@ultimat3/ai`'s `llm()` behind it: page HTML in, a selector out,
     // re-run once. Until it does, this throws rather than answering `false` — a recovery that
     // silently declines is indistinguishable from one that was never configured.
-    throw scrapeNotImplemented("recover: 'agent'", AGENT_FIX);
+    throw new NotImplementedError({ cause: "recover: 'agent' is not implemented", fix: AGENT_FIX });
   }
   const verdict: unknown = await recovery(attempt);
   if (typeof verdict !== 'boolean') {

package/src/rings.ts

@@ -107,18 +107,18 @@ export type PageErrorRing = Ring<PageError>;
  *
  * Both wrong values fail in opposite directions and neither is survivable. A NEGATIVE capacity
  * makes `while (items.length > capacity) items.shift()` spin forever on an already-empty array
- * (`0 > -1`): `createRing(-1).push(1)` never returns, and it is a synchronous loop on the worker's
+ * (`0 > -1`): `boundedRing(-1).push(1)` never returns, and it is a synchronous loop on the worker's
  * only thread, inside a `page.on('request')` handler — past `ctx.signal`, past the wedge watchdog
  * and past the job timeout, which is incident #1 in this file's header. `NaN` fails the other way:
  * the comparison is false forever, the ring is UNBOUNDED, and the OOM the bound exists to prevent
  * arrives two hours in. Zero is a ring that discards everything silently, and a fraction is a
  * bound that is not the number anybody asked for.
  */
-export function createRing<T>(capacity: number = DEFAULT_RING_CAPACITY): Ring<T> {
+export function boundedRing<T>(capacity: number = DEFAULT_RING_CAPACITY): Ring<T> {
   assert(
     Number.isSafeInteger(capacity) && capacity > 0,
     `a ring capacity must be a positive integer, got ${String(capacity)}: a negative one spins forever on push() and NaN makes the ring unbounded`,
-    `pass a positive capacity — createRing(${String(DEFAULT_RING_CAPACITY)}) — or omit it and take DEFAULT_RING_CAPACITY`,
+    `pass a positive capacity — boundedRing(${String(DEFAULT_RING_CAPACITY)}) — or omit it and take DEFAULT_RING_CAPACITY`,
   );
   const items: T[] = [];
   let dropped = 0;