@ultimat3/scraping 25.2.0 → 26.1.0

package/README.md

@@ -499,4 +499,4 @@ a job boundary the class is gone and the `code` is what survives — match on th
 
 ## Boundary
 
-Tier 5. May import tiers 0-4 only — enforced by `bun run scripts/boundaries.ts`.
+Tier 4. May import tiers 0-3 only — enforced by `bun run scripts/boundaries.ts`.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ultimat3/scraping",
-  "version": "25.2.0",
+  "version": "26.1.0",
   "description": "Browser automation as a job: scrape() returns a JobHandle",
   "license": "MIT",
   "type": "module",
@@ -31,9 +31,9 @@
     "test": "bun test"
   },
   "dependencies": {
-    "@ultimat3/core": "25.2.0",
-    "@ultimat3/jobs": "25.2.0",
-    "@ultimat3/schema": "25.2.0",
-    "@ultimat3/storage": "25.2.0"
+    "@ultimat3/core": "26.1.0",
+    "@ultimat3/jobs": "26.1.0",
+    "@ultimat3/schema": "26.1.0",
+    "@ultimat3/storage": "26.1.0"
   }
 }

package/src/index.ts

@@ -154,7 +154,7 @@ export {
   parseHttpRecording,
   parseRecording,
 } from './recording';
-export type { AgentRecovery, Recovery, RecoveryAttempt, RecoveryHook } from './recover';
+export type { RecoveryAttempt, RecoveryHook } from './recover';
 export { runRecovery } from './recover';
 export type {
   ConsoleLine,

package/src/recover.ts

@@ -1,12 +1,9 @@
 // The recovery seam: what happens when a selector has moved and the run failed on it.
 //
-// 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: correct types
-// so an app can be written against it, one labelled throw, no silent no-op.
+// One shape: a FUNCTION. An app writes its own fallback, gets the page and the failure, and
+// answers whether the attempt should be retried. A model that re-derives the selector is the app's
+// own hook wrapping `llm()` (axiom 8), never a string the framework interprets.
 
-import { NotImplementedError } from '@ultimat3/core';
 import { recoverRefused } from './error-throws';
 import type { ScrapePage } from './page';
 
@@ -25,25 +22,10 @@ export interface RecoveryAttempt {
  */
 export type RecoveryHook = (attempt: RecoveryAttempt) => Promise<boolean> | boolean;
 
-export type Recovery = RecoveryHook | 'agent';
-
-/** What the agent recovery will need when it lands. Declared now so the seam is typed, not free. */
-export interface AgentRecovery {
-  readonly kind: 'agent';
-  /** The model call. Deliberately not typed against `@ultimat3/ai` yet — see the throw below. */
-  readonly instruction?: string | undefined;
-}
-
-const AGENT_FIX =
-  "replace recover: 'agent' with a function — recover: ({ page }) => page.waitFor('<the moved selector>').then(() => true) — which is complete today";
-
-export async function runRecovery(recovery: Recovery, attempt: RecoveryAttempt): Promise<boolean> {
-  if (recovery === 'agent') {
-    // 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 new NotImplementedError({ cause: "recover: 'agent' is not implemented", fix: AGENT_FIX });
-  }
+export async function runRecovery(
+  recovery: RecoveryHook,
+  attempt: RecoveryAttempt,
+): Promise<boolean> {
   const verdict: unknown = await recovery(attempt);
   if (typeof verdict !== 'boolean') {
     throw recoverRefused(attempt.scrape, 'the hook answered something other than true or false');

package/src/scrape.ts

@@ -33,7 +33,7 @@ import type { YieldExpectation, YieldHistory } from './expect';
 import { maxDropFraction } from './expect';
 import type { ScrapeHttp } from './http';
 import type { ScrapePage } from './page';
-import type { Recovery } from './recover';
+import type { RecoveryHook } from './recover';
 import type { ResourceType } from './rings';
 import type { RobotsPolicy } from './robots';
 import { runScrape } from './scrape-run';
@@ -103,7 +103,7 @@ export interface ScrapeDefinition<I, Row> {
   readonly artifacts?: ScrapeArtifacts | undefined;
   /** NAMES, never values. */
   readonly secrets?: readonly string[] | undefined;
-  readonly recover?: Recovery | undefined;
+  readonly recover?: RecoveryHook | undefined;
   /**
    * Session lifecycle: acquire, persist, reuse, validate, burn. Authenticated scraping is the
    * primary case, so this is declared rather than hand-rolled per app. See `auth.ts`.
@@ -195,6 +195,13 @@ export function scrape<I, Row>(definition: ScrapeDefinition<I, Row>): JobHandle<
     `scrape "${definition.name}" declares rate: ${String(definition.rate)} — a rate is navigations per second, greater than zero`,
     `set rate: 1 on scrape("${definition.name}"), or leave it out — to go faster raise the number, there is no unpaced mode`,
   );
+  // The type says function; this catches plain JS and the removed `recover: 'agent'` (26.0.0),
+  // which would otherwise surface as a TypeError on the first moved selector, mid-session.
+  assert(
+    definition.recover === undefined || typeof definition.recover === 'function',
+    `scrape "${definition.name}" declares recover: ${JSON.stringify(definition.recover)} — a recover hook is a function`,
+    `on scrape("${definition.name}") write recover: ({ page }) => page.waitFor('<the moved selector>').then(() => true) — to ask a model, call your own llm() action inside that function`,
+  );
   // Two halves that must be set together. `maxDrop` is a fraction of a trailing median and only
   // `history:` can supply one, so declaring it alone is an alarm that cannot fire — refused here,
   // where it is written, rather than discovered as a scrape that never once went red.